Index of every page on this site: llms.txt
All skills
remsky avatar

/api-contrib

@ffa0691
by Jeremyremsky/kokoro-fastapi5.7k stars
951
Run it yourself

Contributing to the Kokoro-FastAPI Python API: module layout, endpoint gating pattern, test expectations. Use when adding or changing endpoints, services, or inference code.

  • 1 file
  • 2.9 KB
  • Updated 3 weeks ago
  • GitHub
Use this Skill: https://skilld.dev/gh/remsky/kokoro-fastapi/api-contrib

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈47 tokens for metadata: the name and description. ≈688 when used: this file.

Description uses 2.3% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈187 characters, or 2.3%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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_speech in development.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.py is on by default except /dev/model, /dev/unload, /dev/reload behind allow_dev_unload, and /dev/dialogue behind enable_voice_tags.
  • api/src/routers/ssml.py - /dev/ssml, behind enable_ssml. tune.py - /dev/tune, opt-in (enable_inno_tuner). web_player.py serves /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 with weights_only=True (core/paths.py) and kept in a bounded LRU in kokoro_v1.py; keep both properties intact.
  • api/src/core/config.py - pydantic-settings, all env-overridable.

Adding an endpoint

  1. Add the route in the right router (or a new one, registered in api/src/main.py).
  2. 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. Follow enable_debug_endpoints / allow_dev_unload.
    • Parses richer user text (tags, markup): True-default kill switch so operators proxying untrusted input can turn it off. Follow enable_voice_tags / enable_ssml.
  3. Add api/tests/test_<feature>.py covering enabled, disabled, and error paths.

Testing

  • uv run pytest runs api/tests/ with coverage; integration tests are excluded (-m integration to opt in, needs a running server).
  • asyncio_mode = auto in pytest.ini, no @pytest.mark.asyncio needed. Hypothesis profiles in api/tests/conftest.py: dev 300 random examples, ci 500 derandomized, picked by the CI env 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 . and uv run --only-group lint ruff check . --fix before staging.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at ffa0691. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 3 weeks ago

README badge

README badge for remsky/kokoro-fastapi/api-contrib