XCalib Conventions¶
Open this when naming models or configuration, changing versions, handling evidence or generated output, or reviewing compatibility.
- Public boundary
- Models and configuration
- Versions and packaging
- Evidence and generated output
- Compatibility
Public boundary¶
All tracked source, tests, entry files, and documentation are public. Keep artifact publication, restricted datasets, partner identifiers, credentials, private paths, and internal operations outside this repository.
Models and configuration¶
- Model implementation modules use stable lowercase identifiers registered in
src/xcalib/models/registry.py. - Packaged configuration files use
<model>_<site>.yamland ship undersrc/xcalib/cfg/. - Site-specific exports use separate output directories so one site's weights cannot overwrite another's.
- Public configs and docs may name only data and artifacts that are actually available to their intended reader.
Versions and packaging¶
The canonical version is src/xcalib/__init__.py; pyproject.toml reads it
dynamically. Use major.minor.revision and update frozen release metadata or
documentation in the same change when required. Wheels are pure Python and
package src/xcalib; checkpoints and large datasets are retrieved separately.
Evidence and generated output¶
docs/evidence/contains frozen shareable JSON evidence and its index.reports/,runs/,onnx/,engines/,dist/, andsite/are generated or local outputs unless an owning workflow explicitly promotes an artifact.- Never replace frozen evidence with a hand-edited number.
- Inventory ignored checkpoints, caches, and reports before deletion.
Compatibility¶
- Python support and optional dependencies are declared in
pyproject.toml. - Keep public imports, protocol fields, config names, export formats, and CLI behavior backward compatible unless a documented migration justifies a breaking change.
- Tests requiring local checkpoints skip in public CI rather than weakening assertions or silently downloading restricted data.