Skip to content

Development

Environment setup

uv sync
uv sync --extra adapters --extra export
uv sync --extra audio
uv sync --group dev
uv sync --group docs

Verification commands

uv run ruff format src tests examples scripts
uv run ruff check src tests examples scripts
uv run python scripts/check_python_standards.py
uv run ty check src tests scripts
uv run python -m compileall src tests scripts
uv run pytest -q
uv build
uv run python -m pip_audit
uv run --group docs mkdocs build --strict

For runtime-heavy changes, also run the reusable smoke harness on the lane you actually changed:

uv run python scripts/runtime_smoke.py \
  --model llama3-1B-chat \
  --output .omx/logs/runtime-smoke.json

The manual regression helpers in scripts/test.py, scripts/test_autoinference.py, and scripts/full_tests.py require explicit CLI arguments for model roots, cache directories, and prompt/sample inputs instead of relying on machine-local hard-coded paths.

If you recommend a specific command or runtime lane to a user, validate that exact lane before push, or explicitly say which stricter equivalent you used.

Engineering standards

The canonical standards baseline lives in Python Standards.

This repo is treated as greenfield:

  • no legacy preservation
  • no backwards-compatibility ballast
  • delete bad shapes instead of keeping them alive

The standards checker and audit surfaces are:

Documentation site

The project documentation is built with MkDocs Material.

Build locally:

uv run --group docs mkdocs build --strict

Preview locally:

uv run --group docs mkdocs serve

Contributor ADRs

Longer-horizon contributor-facing design decisions live under docs/development/.

Current ADR pages:

Examples and manual scripts

  • end-user smoke examples live in examples/
  • export and manual validation scripts live in scripts/
  • large text fixtures live in samples/
  • scripts/runtime_smoke.py is the reusable pre-push runtime validation path for prompt and chat-session semantics

Some older manual scripts still contain machine-specific paths and should be treated as ad hoc local experiments rather than the canonical validation path.