LayerCake welcomes fixes, documentation, security improvements, runtime work, new tests, and well-evidenced research. Start with the repository map and read AGENTS.md before changing governed or evidence-bound surfaces.
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
python -m layercake --help
python scripts/check_docs.py
pytest -qLinux and macOS use source .venv/bin/activate.
| Contribution | Start in | Minimum validation |
|---|---|---|
| Package lifecycle | layercake/cake/, tests/cake/ |
Focused tests plus package tamper/compatibility coverage |
| Routing or orchestration | layercake/routing/, tests/routing/ |
Focused routing tests plus fail-closed negative cases |
| Runtime or kernels | layercake/runtime/ |
Numerical identity, incremental-state, memory, and device tests appropriate to the change |
| Model or training research | layercake/models/, layercake/training/, a versioned config |
Frozen splits, seeds, commands, raw results, and honest promotion outcome |
| Documentation | Root canonical docs or docs/ |
python scripts/check_docs.py |
| New scientific claim | Governed protocol plus results/moonshot/ |
Exact raw rows, derivation, hashes, environment, verifier, and invalidation analysis |
- Explain the user-visible or scientific problem.
- Keep the change scoped to the smallest responsible subsystem.
- Add a regression test for behavior changes.
- Run focused tests and the complete suite when practical.
- Run
python scripts/check_docs.pywhen documentation or public commands change. - Do not modify generated certificates by hand.
- Do not overwrite or delete negative or superseded evidence.
- State whether the invalidation matrix affects any sealed claim.
- Python 3.10+
- type hints on public function signatures
ruff check layercake tests scripts/check_docs.py- deterministic serialization for manifests, packages, and evidence
- fail-closed validation for signatures, hashes, package schemas, permissions, and scientific inputs
The installable package depends on PyTorch, NumPy, safetensors, cryptography, psutil, and PyYAML. Add dependencies only when the public runtime or a clearly declared optional feature requires them.
A pull request that adds or changes a scientific or performance claim must include:
- the exact final artifact and source commit;
- exact commands, seeds, data and artifact hashes, environment, and hardware;
- immutable raw observations and a verifier that recomputes aggregates;
- the comparison contract, including what was held constant;
- negative controls, failures, and uncertainty required by the protocol; and
- an invalidation analysis for dependent certificates.
Do not infer semantic portability from byte identity, quality from a construct test, performance from another checkpoint, or independent reproduction from a same-machine rerun.
Do not add arbitrary generated output to results/ or checkpoints to
artifacts/. Evidence-bearing files require a locked protocol, content hashes,
and a retention/publication plan. Large immutable payloads should use an
approved hash-addressed distribution path rather than silently growing normal
Git history.
Never commit private signing keys, secrets, restricted training data, or unreviewed executable package payloads.
Open a GitHub issue with:
- operating system and hardware;
- Python and PyTorch versions;
- exact commit or tag;
- exact command;
- full error output or divergent value; and
- whether required model, data, or package assets were available.
Security issues should follow SECURITY.md.
Contributions are licensed under Apache-2.0; see LICENSE.