Skip to content

Contributing to Squish

Thank you for your interest in contributing! Squish is an Apple Silicon–only local LLM inference library. Contributions that improve load-time performance, accuracy fidelity, or API compatibility are especially welcome.

Not sure where to start? Jump into Discord or browse GitHub Discussions. Questions are welcome.

Good First Issues

Look for issues tagged good first issue on GitHub. Common entry points:

Label Examples
good first issue Add a new CLI flag, improve an error message, add a test
docs Fix a typo, add an example, improve the quickstart
bench Run a new model through squish bench and submit results
model-card Compress a model and upload to squishai on HuggingFace

If none of the open issues fit, open a Discussion proposing your idea before you write code.

Setting Up the Development Environment

# 1. Clone and enter the repo
git clone https://github.com/konjoai/squish.git
cd squish

# 2. Create a virtual environment (Python 3.12 recommended)
python3 -m venv .venv
source .venv/bin/activate

# 3. Install in editable mode with dev extras
pip install -e ".[dev]"

# 4. (Optional) Build the Rust INT8 quantiser extension
cd squish_quant_rs
pip install maturin
maturin develop --release
cd ..

Running Tests

pytest tests/ -v          # or:  make test

The test suite does not require model weights: it uses mocked tensors and stub loaders. Tests that do require weights are skipped automatically when ~/models/ is absent.

Coverage

make coverage             # terminal report (term-missing) + coverage.xml
make coverage-html        # also writes htmlcov/index.html

Coverage is measured on Apple Silicon so the MLX inference paths execute: the bulk of squish/ cannot run on a Linux runner, so a Linux-only number understates real coverage. The make targets set CI=1 (which lifts the sandbox MLX-import guard) and exclude the handful of files that SIGABRT at collection under Metal. CI runs the same measurement in the Coverage (Apple Silicon + MLX) job and uploads to Codecov; the badge at the top of the README reflects main.

Linting

Squish uses ruff with a line length of 100:

ruff check squish/ tests/
ruff format squish/ tests/

CI will fail if ruff check reports any errors.

What Makes a Good PR

  • Focused: one logical change per PR
  • No hardcoded paths: use Path.home() or environment variables
  • Tests pass: pytest tests/ green before opening the PR
  • No model weights committed: models/ is gitignored for a reason
  • Performance-sensitive changes include a before/after squish bench run

Reporting Bugs

Use GitHub Issues with the Bug report template. Please include your chip generation (M1/M2/M3/M4), macOS version, and the model you were loading.

For quick questions, Discord #help is often faster.

Branch Strategy

Branch Purpose
main Stable, tagged releases
research Eval scripts, benchmark notebooks, paper tooling

Documentation

The docs site is built with MkDocs Material:

pip install mkdocs-material
mkdocs serve        # live preview at http://127.0.0.1:8000
mkdocs build        # generate static site in site/

Docs source lives in docs/. The nav is configured in mkdocs.yml.