Contributing¶
The full guide lives in CONTRIBUTING.md in the repository. This page is the short version.
Setup¶
You need a Rust toolchain and Python 3.10+.
git clone https://github.com/Aamodx6/Kymora
cd Kymora
python -m venv .venv
. .venv/bin/activate # .venv\Scripts\activate on Windows
pip install maturin
pip install -e ".[test]"
maturin develop --release
Always build with --release. A debug build is roughly an order of magnitude
slower, which makes every timing observation meaningless.
Checks¶
Run all of these before opening a PR; CI runs the same set.
pytest tests/ # Python-visible behaviour
cargo test --no-default-features # pure-Rust unit tests
cargo fmt --all -- --check
cargo clippy --no-default-features --all-targets -- -D warnings
python tools/validation_report.py # exits non-zero if a feature drifts
--no-default-features disables pyo3/extension-module, which omits libpython
at link time; a test binary cannot link without it, so cargo test needs the
flag.
Architecture rules¶
- No numeric logic in Python.
python/kymora/__init__.pyis a pass-through with docstrings; all math lives insrc/features/. - No panic may cross the FFI boundary. Fallible steps return
Result<_, KymoraError>;src/error.rsis the single conversion point toPyErr. - Structural errors and NaN values stay separate.
KymoraErrordescribes shapes and layout, never values — see the NaN policy.
Adding a feature¶
The 33-feature set is closed on purpose. Open a New feature proposal issue
and get agreement before writing code. NAMES in src/features/mod.rs is the
single source of truth for column order — append at the end, never insert in the
middle.
Versioning policy¶
feature_names() order and length are public API. Reordering, renaming, or
removing a feature is a major bump; appending one at the end is a minor bump.
The full table is in the repository guide.