Contributing

Make the benchmark more trustworthy.

Good contributions make a number easier to reproduce, a contract easier to use, or a limitation easier to see. Keep changes direct, tested, and explainable.

Development setup.

git clone https://github.com/sachncs/trivium.git
cd trivium
uv venv
uv pip install -e ".[dev]"

Run the quality gates.

ruff check .
ruff format --check .
mypy
pytest -q -m "not golden" --cov=trivium --cov-branch --cov-fail-under=90
npm --prefix site ci
npm --prefix site run build

Golden tests are explicit regression anchors and require the benchmark data cache. Run them separately when that cache is available.

Design rules.

Implement the smallest relevant public contract: embedder, retriever, fusion strategy, reranker, or pipeline.
Register concrete components rather than adding forwarding wrappers or compatibility aliases.
Validate persistence boundaries: shapes, cardinality, IDs, metadata, and atomic writes.
When a benchmark number changes, update the evidence and explain why.

Open an issue