Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/arjunkshah/supercompress/llms.txt

Use this file to discover all available pages before exploring further.

Contributions to SuperCompress are welcome — bug fixes, new baseline policies, improved training data, documentation updates, or anything else that improves the library. The project uses pytest for testing and ruff for linting, both of which run automatically in CI on every push and pull request.

​
Dev environment setup

1

Clone the repository

git clone https://github.com/arjunkshah/supercompress.git
cd supercompress
2

Install all development dependencies

The dev extra adds pytest, ruff, and httpx. The serve extra adds FastAPI and Uvicorn, which are required for test_local_server.py.
pip install -e ".[dev,serve]"
3

Verify the test suite passes

All 52 tests should pass on a clean checkout:
pytest tests/ -q
Expected output ends with something like:
52 passed in 3.14s
4

Run the linter

ruff check .
Ruff is configured to check supercompress/, tests/, and scripts/. A clean pass produces no output.

​
Project layout

PathDescription
supercompress/Core library — ~5K-param eviction policy, baselines, features, simulator
supercompress/api/Hosted API layer — key management, Firebase auth, usage tracking
web/Static landing page, browser demo, and dashboard
scripts/benchmark_web.py, local_web_server.py, export_model_json.py, generate_charts.py
tests/test_supercompress, test_api_hard, test_api_keys, test_api_server, test_local_server
checkpoints/default.ptTrained weights (included in the repo)
docs/API reference, integrations, environment impact, dashboard guide

​
Test suites

FileCoverage
test_supercompress.pyCore compress_context, compare_policies, CompressResult fields, oracle recall, edge cases
test_api_hard.pyHard validation edge cases — invalid budget_ratio, oversized payloads, malformed JSON
test_api_keys.pyAPI key generation format (sc_live_…), hashing, and equality checks
test_api_server.pyFastAPI route behaviour — status codes, response schema, authentication
test_local_server.pyFull integration tests for the local dev server using httpx.AsyncClient
test_local_server.py requires the serve extra. If you install only .[dev], those tests are automatically skipped — this is expected behaviour, not a failure.

​
Linting and code style

SuperCompress uses Ruff with the following configuration from pyproject.toml: 
[tool.ruff]
line-length = 120
target-version = "py310"

[tool.ruff.lint]
select = ["E", "F", "I", "W"]
This enforces PEP 8 errors (E), Pyflakes (F), import ordering (I), and pycodestyle warnings (W). The scripts/ directory has E402 (module-level import not at top of file) suppressed because the scripts manually prepend the repo root to sys.path.
Run ruff check --fix . to auto-fix import ordering and other safe issues before committing.

​
CI/CD

GitHub Actions runs the full CI pipeline on every push to main and on every pull request targeting main. The workflow matrix tests Python 3.11 and 3.12. Each CI run executes the following steps in order:
  1. Install — pip install -e ".[dev,serve]" and pip install ruff
  2. Ruff — ruff check supercompress tests scripts
  3. Export browser model — python scripts/export_model_json.py
  4. Pytest — pytest tests/ -q
  5. Benchmark JSON — python scripts/benchmark_web.py
  6. Verify web assets — asserts that web/assets/data/model.json, web/assets/data/benchmarks.json, web/assets/js/compress-engine.js, web/assets/img/chart-kv-savings.svg, web/assets/img/chart-impact.svg, and web/assets/video/launch.mp4 all exist
CI does not run generate_charts.py because SVG generation depends on matplotlib and the chart files are committed to the repository. The verify step only checks that the committed files are present.

​
Submitting a pull request

Before opening a PR, confirm that:
  • pytest tests/ -q shows 52 passed (or more if you have added tests)
  • ruff check . exits with no errors
  • Any new public function is documented in docs/API.md
  • If you retrained the checkpoint, python scripts/export_model_json.py succeeds and you have committed the updated web/assets/data/model.json

​
License

SuperCompress is released under the MIT License. By contributing you agree that your changes will be distributed under the same terms.

Build docs developers (and LLMs) love

Get started for freeTalk to us