Read AGENTS.md and CONTRIBUTING.md first, house rules live there.
API contributions
Where things live
api/src/routers/openai_compatible.py- main API surface (/v1/audio/speech,/v1/audio/voices,/v1/models). Captioned speech is/dev/captioned_speechindevelopment.py. Changes here affect every OpenAI-client consumer, so keep request/response shapes backward compatible.api/src/routers/debug.py- introspection endpoints, opt-in (enable_debug_endpoints).development.pyis on by default except/dev/model,/dev/unload,/dev/reloadbehindallow_dev_unload, and/dev/dialoguebehindenable_voice_tags.api/src/routers/ssml.py-/dev/ssml, behindenable_ssml.tune.py-/dev/tune, opt-in (enable_inno_tuner).web_player.pyserves/web.api/src/services/tts_service.py- orchestration between text processing, inference, and audio encoding.api/src/services/streaming_audio_writer.py- per-format encode/finalize. Historically fragile at chunk boundaries and finalize time (WAV trailer click, OGG final-page loss), so test full stream + finalize output, not just single chunks.api/src/inference/-kokoro_v1.py(backend),model_manager.py,voice_manager.py. Voice tensors are loaded withweights_only=True(core/paths.py) and kept in a bounded LRU inkokoro_v1.py; keep both properties intact.api/src/core/config.py- pydantic-settings, all env-overridable.
Adding an endpoint
- Add the route in the right router (or a new one, registered in
api/src/main.py). - Two gating patterns, both 403 when off and both documented in
docs/configuration.md:- Surfaces host, process, or model internals (unload, introspection, etc):
False-default setting, opt-in, to avoid unintentional exposure on shared deployments. Followenable_debug_endpoints/allow_dev_unload. - Parses richer user text (tags, markup):
True-default kill switch so operators proxying untrusted input can turn it off. Followenable_voice_tags/enable_ssml.
- Surfaces host, process, or model internals (unload, introspection, etc):
- Add
api/tests/test_<feature>.pycovering enabled, disabled, and error paths.
Testing
uv run pytestrunsapi/tests/with coverage; integration tests are excluded (-m integrationto opt in, needs a running server).asyncio_mode = autoin pytest.ini, no@pytest.mark.asyncioneeded. Hypothesis profiles inapi/tests/conftest.py:dev300 random examples,ci500 derandomized, picked by theCIenv var.- Tests mock the model; no GPU needed. If a change is only verifiable on CUDA/ROCm hardware you don't have, say so in the PR.
uv run --only-group lint ruff format .anduv run --only-group lint ruff check . --fixbefore staging.