Skip to content
vaak

Contributing

vaak is Apache-2.0. Issues and pull requests are welcome at github.com/mirukullacode/vaak.

Development setup

Section titled “Development setup”
Terminal window
git clone https://github.com/mirukullacode/vaak
cd vaak
python -m venv .venv && source .venv/bin/activate
pip install -e ".[all,dev]"
pre-commit install

dev adds pytest, ruff and mypy. Run the checks:

Terminal window
ruff check . && ruff format --check .
mypy vaak
pytest

Tests that need model weights are marked @pytest.mark.slow and skipped by default. pytest -m slow runs them; they download small models the first time.

Repository layout

Section titled “Repository layout”
vaak/                 Python package
  audio.py            load_audio()
  metrics.py          wer(), cer(), normalize_text()
  backends/           one file per backend, registry in __init__.py
  server/app.py       FastAPI app
  cli.py              vaak transcribe | serve | bench | models
bench/                datasets.py, run.py, report.py, results/
train/                finetune_whisper_lora.py, tiny_ctc_from_scratch.py
runpod/               run_all.sh, Dockerfile
huggingface/          Space, model card, publish.py
docker/               API server Dockerfile
website/              this site (Astro Starlight)

Adding a backend

Section titled “Adding a backend”
  1. Create vaak/backends/<name>.py with a class that subclasses Backend from base.py.
  2. Set name to the registry prefix. model_id is whatever follows the colon in the spec string.
  3. Import the runtime inside load(), not at module top level. vaak models must stay fast and must not fail when an optional extra is missing.
  4. transcribe() must accept a float32 numpy array, resample if sample_rate != 16000, and return a Transcript with rtf measured around the model call only.
  5. Set languages to the ISO 639-1 codes the model supports, or None for multilingual.
  6. Register it in vaak/backends/__init__.py and add the runtime to the right extra in pyproject.toml.
  7. Add a test in tests/backends/ that runs on the smallest available checkpoint.
  8. Document the spec in website/src/content/docs/reference/model-specs.md and add a row to the backends table on the landing page.

Adding a dataset

Section titled “Adding a dataset”

Add a generator to bench/datasets.py that yields {"id", "audio", "text", "lang"} with audio as a 16 kHz float32 array. Register the key in the DATASETS dict. Document it on the benchmarks page.

Benchmarks and numbers

Section titled “Benchmarks and numbers”
  • Never type a benchmark number into the website. Rows come from bench/results/*.json through bench/report.py.
  • Published numbers from papers go in the reference array of website/src/data/benchmarks.json with "reproduced": false and a source URL.
  • Do not commit results from hardware you cannot name.

Website

Section titled “Website”
Terminal window
cd website
npm install
npm run dev

Pages are Markdown or MDX in src/content/docs/. Run npm run build before opening a PR. Writing style: plain, short sentences, no marketing language, state limitations.

Pull requests

Section titled “Pull requests”
  • One change per PR.
  • Describe what you measured, if anything, and on what hardware.
  • Keep the public API in ARCHITECTURE.md in sync with the code. If a PR changes a route, a CLI flag or a dataclass field, update that file in the same PR.