Development

The repository contains one stable framework distribution plus independently installable bindings and runtimes.

Repository layout

altar/       Python distribution, tests, documentation, reference host
bindings/    lightweight scientific integration packages
runtimes/    independently locked model and command environments
scripts/     repository boundary and compatibility checks

Read AGENTS.md before moving behavior between these areas.

Framework checks

uv venv --python 3.12
uv pip install -e "altar[test,docs]"
.venv/bin/python -m pytest altar/tests -q
.venv/bin/python scripts/check_core_boundary.py
.venv/bin/python scripts/check_public_api.py
cd altar && ../.venv/bin/python -m mypy altar

Documentation

.venv/bin/mkdocs serve --config-file altar/mkdocs.yml
.venv/bin/mkdocs build --strict --config-file altar/mkdocs.yml

The API reference is rendered by mkdocstrings from the public modules' signatures and docstrings, including symbols re-exported from nested implementation modules. Update the source docstrings to update those entries. When adding a public module, add its ::: directive to a reference page and include that page in altar/mkdocs.yml.

The Docs site workflow runs a strict build for pull requests that change library source, documentation, MkDocs configuration, or the root or package pyproject.toml. Merging those changes to main also publishes the updated reference to GitHub Pages. Pull requests never deploy the site.

Every public concept should be introduced through the scientist's or integrator's goal before naming the Python object. Keep internal migration notes and host-application assumptions out of the public site.

Bindings

Install each binding with Altar in isolation, run its tests, type-check its package, and verify its entry point. Do not add its heavy model framework to the Altar environment.

Runtimes

Each runtime owns its Python version, lockfile, tests, image definition, and executable CLI. Changes to the binding/runtime command contract must be tested together while preserving their independent dependency locks. Each container binding's tests write the commands its plan produces into runtimes/<model>/tests/data/binding_commands.json and fail when the plan and that file differ. The paired runtime's tests parse every command in the file with the runtime's own CLI parser, without importing Altar or running a model. After an intended command change, rewrite the file with ALTAR_UPDATE_GOLDENS=1 pytest bindings/<model>/tests, review the diff, and run the runtime's tests.