Contributing to Jevstiller

Jevstiller is small on purpose. The fastest way to help is to run it on a real task and report what happened.

Set up

git clone https://github.com/tomerglick57/Jevstiller
cd Jevstiller
python -m pip install -e ".[dev]"      # or: uv sync --extra dev
pytest -q                               # CPU only, no network
ruff check .

The test suite never needs an API key or a real encoder; SyntheticTeacher drives the whole loop.

Rules that keep the guarantee honest

1. Rows that went to Jev because the student was unsure never enter the calibration split.
2. Thresholds are chosen against a confidence bound, never a point estimate.
3. Anything shown as “agreement” is agreement with the teacher. Never call it accuracy.
4. Training, calibration and audit statistics use one teacher lineage only.
5. The proxy answers locally only for an API key Jev has accepted, and never stores or logs a key.

A change that touches any of these needs a test.

Pull requests

• One change per PR.
• Add or update a test in tests/.
• If behaviour changes, update DESIGN.md, the relevant docs/ page and CHANGELOG.md in the same PR.
• Made with an AI tool? Say so in the PR (a trailer is enough). Jevstiller itself is written with Claude Code (how). If you claim a number, include the command that produced it.

This website

The site lives in website/ and is built with Starlight. Pages are Markdown files in website/src/content/docs/. The pages under Run the proxy, Configuration, Benchmarks, How it compares and Writing are generated at build time from docs/*.md, docs/posts/ and the README: edit those, not the generated copies.

cd website
npm install
npm run dev

Full guide: CONTRIBUTING.md. Security issues: SECURITY.md.

Citing

If Jevstiller is part of research, cite it with the metadata in CITATION.cff; GitHub’s “Cite this repository” button renders it as BibTeX or APA. The method is described in A bound, not a threshold and the prior art it builds on is listed under How it compares.