Skip to content

Development guide

Setup

uv sync --frozen --extra dev

Optional extras:

uv sync --frozen --extra mlx
uv sync --extra docs

Tests

uv run pytest

Lint (also run in CI):

uv run ruff check .

Live model integration (optional):

ODDSGRAPH_LIVE_MODEL_TEST=1 uv run pytest -m integration

Live server integration (optional, requires running llama-server):

ODDSGRAPH_LIVE_SERVER_TEST=1 uv run pytest -m integration

Docs structure and strict build:

uv run mkdocs build --strict
uv run pytest tests/docs -q

Benchmarks

uv run python scripts/benchmark_build.py \
  --markets tests/fixtures/golden_semantic_markets.parquet
uv run python scripts/benchmark_infer.py --help

benchmark_build.py times proposition compilation, rule application, entity resolution, and the full build pipeline. Residual LLM decode timing lives in Inference backends.

Quality expectations

  • Prefer deterministic coverage over residual LLM work when adding topology.
  • Keep ontology changes paired with validation and docs updates.
  • Do not commit large parquet exports or model weights.

See also