Skip to content

AGENTS.md

Latest commit

 

History

History
99 lines (71 loc) · 2.97 KB

AGENTS.md

File metadata and controls

99 lines (71 loc) · 2.97 KB
Raw

transcribe.cpp Agent Conventions

Read CONTRIBUTING.md for contribution policy, review gates, and coding style. This file is only the local command/automation convention sheet for coding agents.

Python

  • ALWAYS use uv run for every Python invocation. Never bare python, python3, or pip.
  • Use uv pip for packages, uv sync for envs, and uv run for scripts.
  • Per-family reference environments live under scripts/envs/<family>/ and are invoked as:
uv run --project scripts/envs/<family> scripts/<script>.py ...

Build

  • After C++ changes, run:
cmake --build build --target transcribe-cli

Formatting

  • Format our C/C++ before committing. The formatter is pinned and fetched via uvx, so do not rely on a system clang-format:
scripts/ci/clang-format.sh            # format our tree in place (default)
scripts/ci/clang-format.sh --check    # verify, no changes
  • Scope is our code only. Vendored trees (ggml/, src/third_party/) and verbatim upstream copies (src/transcribe-unicode-data.cpp) are never formatted. CI gates our C/C++ in .github/workflows/clang-format.yml.

C ABI Exception Discipline

No C++ exception may escape a public entry point.

  • A new public entry point must either route through an api_guard_* wrapper (src/transcribe.cpp) or be nothrow by construction. Device and registry queries are not pure reads; guard them.
  • Entry points with ownership out-params enforce "non-OK => *out == NULL, nothing leaked" in their forwarders on every error return.
  • Teardown never uses raw ggml_backend_free / ggml_backend_buffer_free / ggml_backend_sched_free in library code: use transcribe::safe_* from src/transcribe-backend.h. tests/lint_teardown.cmake fails CI on violations.
  • Host log callbacks are contained at the emission site (transcribe_log_invoke).
  • The TRANSCRIBE_TEST_* fault hooks (_DEV_INIT_THROW, _TEARDOWN_THROW) intentionally ship in release artifacts for wheel clean-install CI. Present-but-empty values are inert.

Verification

  • End-to-end numerical checks:
uv run scripts/validate.py all --family <f> [--variant <v>]

--variant is required when the family has multiple manifests.

  • Manual tensor debugging:
uv run scripts/compare_tensors.py ...
  • Cheap metadata/config gates before expensive numerical work:
uv run scripts/preflight.py --family <f> [--variant <v>]
  • Never suppress test failures without root cause analysis.

Porting a New Model

Use the porting-* skills in .claude/skills/. Stage skills are independent and run in order:

porting-1-intake -> porting-2-oracle -> porting-3-convert -> porting-4-cpp
-> porting-5-quants -> porting-6-bench -> porting-7-wer -> porting-8-ship

Git Hygiene

  • Do not commit, push, create pull requests, or comment on pull requests unless the user explicitly asks for that action.
  • Do not reformat unrelated code in the same change as a behavior fix.