{"owner":"remsky","repo":"Kokoro-FastAPI","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# AGENTS.md\n\nGuidance for coding agents working on Kokoro-FastAPI. \nAgent-assisted contributions are welcome, with caveats:\n    - All judgement and accountability falls to the named human contributor as the reviewer. \n    - If the user doesn't demonstrate understanding a change, it's not ready to merge. \n    - Code style here must still match house style. \n    - To the above, explicitly: \n        - wanton em-dash usage is not permitted.\n        - expositionary and excessive commenting is not permitted.\n        - when in doubt, do less. Comments are reserved for decision points, or unexpected gotchas, etc.  \n\n\nThe general instructions must also still be followed, same as any contributor, and live in [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Layout\n\n- `api/src/routers/` - HTTP endpoints. `openai_compatible.py` is the main API surface.\n- `api/src/services/` - TTS orchestration (`tts_service.py`), audio encoding and streaming (`audio.py`, `streaming_audio_writer.py`), `text_processing/` (normalization, phonemization).\n- `api/src/inference/` - model backends (`kokoro_v1.py`), model and voice managers.\n- `api/src/core/` - `config.py` (env-driven settings), `paths.py`, `openai_mappings.json` (OpenAI model/voice name mapping).\n- `web/` - vanilla JS web player, served by the API. No framework, no build step.\n- `docker/{cpu,gpu,rocm}/` - per-accelerator images and compose files. `docker-bake.hcl` defines the CI build targets.\n- `examples/` - standalone samples with their own uv venv. Run `uv run` from inside `examples/`, not the root env.\n\n## Commands\n\n- Python tests: `uv run pytest` (runs `api/tests/`; integration tests are excluded by default, opt in with `-m integration`).\n- Format and lint: `ruff format .` then `ruff check . --fix`.\n- Web unit tests: `npm run test:web`. E2e: `npm run test:e2e`. New unit test files must be imported from `web/tests/unit/index.test.mjs`; it is a manual registry.\n- Container smoke test: `npm run cpu:up` (or `gpu:up`, `rocm:up`).\n\n## Conventions\n\n- Commit and PR titles use conventional style with a scope: `fix(audio): ...`, `feat(api): ...`, `chore(docker): ...`.\n- Every behavior change ships with a test (`api/tests/test_*.py` or `web/tests/`).\n- Add a `CHANGELOG.md` entry for user-visible changes. Don't bump `VERSION`; that happens at release time.\n- Endpoints that surface host, process, or model internals go behind an opt-in setting in `api/src/core/config.py` (see `enable_debug_endpoints`, `allow_dev_unload`) to avoid unintentional exposure on shared deployments. Features that interpret user-supplied text get a default-on kill switch instead (see `enable_voice_tags`).\n- Keep changes small and modular; match the surrounding style.\n\n## Gotchas\n\n- Dockerfiles are tuned for multi-arch CI. Don't remove build tools or restructure stages without a tested build for every target. \n- Trust me on the above point. The dependencies are touchy for this stack. \n- Local (non-Docker) runs need espeak-ng installed and on PATH; the Docker images handle this separately.\n- Japanese support (`misaki[ja]`) requires the full UniDic dictionary (~526MB), not `unidic-lite`. CI caches it.\n- The release/publish workflow triggers itself on push to the `release` branch. It should never never be triggered manually. Tag @remsky to do so. \n"},"files":{"AGENTS.md":"# AGENTS.md\n\nGuidance for coding agents working on Kokoro-FastAPI. \nAgent-assisted contributions are welcome, with caveats:\n    - All judgement and accountability falls to the named human contributor as the reviewer. \n    - If the user doesn't demonstrate understanding a change, it's not ready to merge. \n    - Code style here must still match house style. \n    - To the above, explicitly: \n        - wanton em-dash usage is not permitted.\n        - expositionary and excessive commenting is not permitted.\n        - when in doubt, do less. Comments are reserved for decision points, or unexpected gotchas, etc.  \n\n\nThe general instructions must also still be followed, same as any contributor, and live in [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Layout\n\n- `api/src/routers/` - HTTP endpoints. `openai_compatible.py` is the main API surface.\n- `api/src/services/` - TTS orchestration (`tts_service.py`), audio encoding and streaming (`audio.py`, `streaming_audio_writer.py`), `text_processing/` (normalization, phonemization).\n- `api/src/inference/` - model backends (`kokoro_v1.py`), model and voice managers.\n- `api/src/core/` - `config.py` (env-driven settings), `paths.py`, `openai_mappings.json` (OpenAI model/voice name mapping).\n- `web/` - vanilla JS web player, served by the API. No framework, no build step.\n- `docker/{cpu,gpu,rocm}/` - per-accelerator images and compose files. `docker-bake.hcl` defines the CI build targets.\n- `examples/` - standalone samples with their own uv venv. Run `uv run` from inside `examples/`, not the root env.\n\n## Commands\n\n- Python tests: `uv run pytest` (runs `api/tests/`; integration tests are excluded by default, opt in with `-m integration`).\n- Format and lint: `ruff format .` then `ruff check . --fix`.\n- Web unit tests: `npm run test:web`. E2e: `npm run test:e2e`. New unit test files must be imported from `web/tests/unit/index.test.mjs`; it is a manual registry.\n- Container smoke test: `npm run cpu:up` (or `gpu:up`, `rocm:up`).\n\n## Conventions\n\n- Commit and PR titles use conventional style with a scope: `fix(audio): ...`, `feat(api): ...`, `chore(docker): ...`.\n- Every behavior change ships with a test (`api/tests/test_*.py` or `web/tests/`).\n- Add a `CHANGELOG.md` entry for user-visible changes. Don't bump `VERSION`; that happens at release time.\n- Endpoints that surface host, process, or model internals go behind an opt-in setting in `api/src/core/config.py` (see `enable_debug_endpoints`, `allow_dev_unload`) to avoid unintentional exposure on shared deployments. Features that interpret user-supplied text get a default-on kill switch instead (see `enable_voice_tags`).\n- Keep changes small and modular; match the surrounding style.\n\n## Gotchas\n\n- Dockerfiles are tuned for multi-arch CI. Don't remove build tools or restructure stages without a tested build for every target. \n- Trust me on the above point. The dependencies are touchy for this stack. \n- Local (non-Docker) runs need espeak-ng installed and on PATH; the Docker images handle this separately.\n- Japanese support (`misaki[ja]`) requires the full UniDic dictionary (~526MB), not `unidic-lite`. CI caches it.\n- The release/publish workflow triggers itself on push to the `release` branch. It should never never be triggered manually. Tag @remsky to do so. \n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# AGENTS.md\n\nGuidance for coding agents working on Kokoro-FastAPI. \nAgent-assisted contributions are welcome, with caveats:\n    - All judgement and accountability falls to the named human contributor as the reviewer. \n    - If the user doesn't demonstrate understanding a change, it's not ready to merge. \n    - Code style here must still match house style. \n    - To the above, explicitly: \n        - wanton em-dash usage is not permitted.\n        - expositionary and excessive commenting is not permitted.\n        - when in doubt, do less. Comments are reserved for decision points, or unexpected gotchas, etc.  \n\n\nThe general instructions must also still be followed, same as any contributor, and live in [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Layout\n\n- `api/src/routers/` - HTTP endpoints. `openai_compatible.py` is the main API surface.\n- `api/src/services/` - TTS orchestration (`tts_service.py`), audio encoding and streaming (`audio.py`, `streaming_audio_writer.py`), `text_processing/` (normalization, phonemization).\n- `api/src/inference/` - model backends (`kokoro_v1.py`), model and voice managers.\n- `api/src/core/` - `config.py` (env-driven settings), `paths.py`, `openai_mappings.json` (OpenAI model/voice name mapping).\n- `web/` - vanilla JS web player, served by the API. No framework, no build step.\n- `docker/{cpu,gpu,rocm}/` - per-accelerator images and compose files. `docker-bake.hcl` defines the CI build targets.\n- `examples/` - standalone samples with their own uv venv. Run `uv run` from inside `examples/`, not the root env.\n\n## Commands\n\n- Python tests: `uv run pytest` (runs `api/tests/`; integration tests are excluded by default, opt in with `-m integration`).\n- Format and lint: `ruff format .` then `ruff check . --fix`.\n- Web unit tests: `npm run test:web`. E2e: `npm run test:e2e`. New unit test files must be imported from `web/tests/unit/index.test.mjs`; it is a manual registry.\n- Container smoke test: `npm run cpu:up` (or `gpu:up`, `rocm:up`).\n\n## Conventions\n\n- Commit and PR titles use conventional style with a scope: `fix(audio): ...`, `feat(api): ...`, `chore(docker): ...`.\n- Every behavior change ships with a test (`api/tests/test_*.py` or `web/tests/`).\n- Add a `CHANGELOG.md` entry for user-visible changes. Don't bump `VERSION`; that happens at release time.\n- Endpoints that surface host, process, or model internals go behind an opt-in setting in `api/src/core/config.py` (see `enable_debug_endpoints`, `allow_dev_unload`) to avoid unintentional exposure on shared deployments. Features that interpret user-supplied text get a default-on kill switch instead (see `enable_voice_tags`).\n- Keep changes small and modular; match the surrounding style.\n\n## Gotchas\n\n- Dockerfiles are tuned for multi-arch CI. Don't remove build tools or restructure stages without a tested build for every target. \n- Trust me on the above point. The dependencies are touchy for this stack. \n- Local (non-Docker) runs need espeak-ng installed and on PATH; the Docker images handle this separately.\n- Japanese support (`misaki[ja]`) requires the full UniDic dictionary (~526MB), not `unidic-lite`. CI caches it.\n- The release/publish workflow triggers itself on push to the `release` branch. It should never never be triggered manually. Tag @remsky to do so. \n","category":"root","tokens":823}]}