Build with us
Contributing
Contributions should make the algorithm easier to trust: small changes, explicit invariants, and reproducible tests.
Before opening a change
- Read the relevant concept and architecture pages.
- Write down the invariant or public behavior the change preserves.
- Add a deterministic regression, property-based test, or benchmark evidence for the failure mode.
- Keep the canonical API small: do not add aliases, wrappers, compatibility shims, or silent fallback paths.
Choose the right change surface
| If you are changing… | Also update… | Evidence expected |
|---|---|---|
| Public API or errors | API reference and get-started example | Executable example plus regression tests |
| Matching or graph state | Concepts and architecture boundary | Validity, maximality, and rollback coverage |
| Multilevel behavior | Research status and modes guidance | Recursive derivation and deterministic transition tests |
| Claims or benchmarks | Changelog and limitation language | Reproducible command, environment, and measured output |
What belongs in a pull request?
Include the smallest coherent implementation, tests for the failure mode, and documentation when behavior or guarantees change. Explain the state transition and why the relevant invariant still holds. If a paper-level claim is not fully validated, label it as research work rather than upgrading the product claim.
Local quality gate
python -m pytest -q
ruff check axiom/ tests/ scripts/ benchmarks/ examples/
mypy axiom/
cd site && npm run check && npm run build
cd .. && python scripts/verify_site_examples.pyKeep the site examples executable: a new user should be able to copy the documented path and get the documented result. Release and security checks run in CI; do not bypass them to make a change appear green.
Where to work
The repository contains source, tests, engineering policies, and release automation. The website is the visitor-facing product surface. If a behavior is difficult to explain here, treat that as a design signal and clarify the implementation or its boundary before merging.