Skip to content

Development

Set up a development checkout of Altar, then run the checks a change must pass: the local gate, the documentation build and the public-API snapshot.

Repository layout

altar/       the altar distribution: package, tests, documentation, public-api.json
identity/    altar-identity: variant IDs, the container variant file, SHA-256 file identity
bindings/    one independently installable package per model, dataset or service
runtimes/    model environments, each with its own lockfile, image definition and command
examples/    programs and notebooks that use Altar as an outside package would
scripts/     the local gate and the repository's policy checks

Read AGENTS.md before moving behavior between these areas. In short: model-specific knowledge goes in a binding, heavyweight frameworks go in a runtime, and altar itself imports neither.

Set up a checkout

Altar uses uv, pinned to 0.12.17. Run it through uvx so the version matches the lockfile, whatever uv is on your PATH:

git clone https://github.com/kundajelab/altar.git
cd altar
uvx uv@0.12.17 sync --all-packages --extra test --extra kubernetes

This creates .venv with altar, altar-identity and every binding installed in editable mode, from uv.lock. Add --extra docs to build the documentation in the same environment. Run the tests with:

.venv/bin/python -m pytest altar/tests bindings -q

identity/ supports Python 3.9. When you change it, test it there as well:

uvx uv@0.12.17 run --isolated --no-project --python 3.9 --with pytest --with-editable identity \
    python -m pytest identity/tests

The local gate

scripts/check_local.py runs every check CI runs, from one command. Run it with the Python of the workspace environment before you open a pull request. Maintainers merge a change only after it passes:

.venv/bin/python scripts/check_local.py

It runs these steps:

  • the core, bindings and identity tests;
  • strict mypy for core and every binding, and for altar-identity on Python 3.9;
  • the core-boundary, public-API, public-import, runtime-Dockerfile and validation-record checks;
  • the Ruff checks and ruff format --check, and marimo check on the tutorials;
  • Ruff with every configured rule on the Python lines changed since the merge base with main (scripts/check_ruff_changed.py). Older findings elsewhere in a changed file do not fail it;
  • uv lock --check for the workspace and every runtime;
  • the conservation tests with the build extra installed, so the bigWig builder test runs;
  • mkdocs build --strict in an environment that holds altar[docs];
  • the external-plugin fixtures: it builds the Altar wheel and the two fixture wheels, installs them together in a new environment, and runs the fixture's tests from outside the checkout;
  • the identity tests on Python 3.9, with altar-identity installed alone.

The last four steps each install a separate environment. Every step runs even after one fails. The summary lists each step with its time, and the exit status is non-zero if any step failed.

These options add slower steps:

Option What it adds
--runtime NAME The runtime's tests in its own locked environment, for example --runtime legnet. Repeat it for each runtime. The variants runtime has no tests, so it gets CI's import checks.
--changed-runtimes --runtime for every runtime the branch affects, compared with the merge base with main, uncommitted changes included. A runtime is affected by its own files and its binding's files. A change under identity/ affects every runtime, and a change under altar/altar/variants/ affects the variants runtime.
--also-python VERSION The core and binding tests again, in an environment of Python 3.12 or 3.13 synced from uv.lock. CI tests both. Pass the one your workspace environment does not use; .venv/bin/python --version shows which that is.
--release-build A wheel and an sdist of all 17 distributions, built and checked as a release is, at the workspace version. It runs scripts/release_local.py --candidate --skip-gate, which installs every wheel together on Python 3.12 and 3.13 and checks that Altar's plugin discovery finds every binding. It needs a clean working tree.
--emulator The BigQuery emulator in Docker, with the image and flags CI uses, on a free local port. It runs the tests marked bigquery_emulator against it and then removes the container. Without the option those tests skip, unless BIGQUERY_EMULATOR_HOST names a running emulator.

Runtimes install TensorFlow or PyTorch, and the other options each install or start something the workspace environment lacks, so the default gate leaves them out. Add --changed-runtimes to every run on a branch that touches a runtime, a model binding or identity/. Before a release, run everything, with --also-python naming the supported version the workspace environment does not use:

.venv/bin/python scripts/check_local.py --changed-runtimes --also-python 3.13 --release-build --emulator

The gate does not build runtime images or run model-scoring tests that need Docker or a GPU. Run those on a machine with the hardware.

Seven export tests skip on the emulator, because its version, 0.6.6, cannot analyze SELECT ... FROM UNNEST(@variant_ids), which is valid BigQuery. The DuckDB-backed export tests run that SQL.

Leaked resources fail the tests

Every pytest configuration in the repository turns ResourceWarning into an error. That warning reports a file, socket or database connection that was never closed. Python often finds the leak in a finalizer, after the test that caused it, and pytest then reports it as PytestUnraisableExceptionWarning, which is an error too. Close what a test opens with a with block or a fixture that closes it. To see where a leaked object was created, run the failing test with allocation tracing:

.venv/bin/python -X tracemalloc=20 -m pytest path/to/test_module.py -q

Silence a leak only with a filterwarnings mark on the one test whose leak comes from a third-party library, with a comment that names it.

Documentation

The site's source is altar/docs, and its navigation is in altar/mkdocs.yml. Preview it, and build it as the gate does, with:

uvx uv@0.12.17 sync --all-packages --extra test --extra kubernetes --extra docs
.venv/bin/mkdocs serve --config-file altar/mkdocs.yml
.venv/bin/mkdocs build --strict --config-file altar/mkdocs.yml

--strict fails the build on a broken link, a page missing from the navigation, or a ::: directive that names nothing. Write pages to the writing style and the docstring and doc conventions.

The API reference is rendered by mkdocstrings from the public modules' signatures and docstrings, including names re-exported from implementation modules. Edit the docstring to change an entry. When you add a public module, add its ::: directive to a reference page and add that page to altar/mkdocs.yml.

Some pages hold code blocks that tests run, such as the model-binding and annotation-source guides and the quickstart. Their tests name the page and the block markers. If you move such a page or change a block, update its test in the same change.

Pull requests build the site with --strict. The site is published from a released version, as Release Altar describes.

The public-API snapshot

altar/public-api.json records the public API: every name in each public module's __all__, with its shape. scripts/check_public_api.py compares the installed modules with it and fails on any difference. The gate runs it.

When you change the public API on purpose, regenerate the snapshot and review its diff as an API change:

.venv/bin/python scripts/check_public_api.py --update

Never edit the file by hand. When two branches both change it, regenerate it after the rebase rather than merging the conflict.

What the snapshot records

For each name in a public module's __all__:

Export Recorded
every name its kind and its defining module path (target)
function its signature
class its bases, the signatures of its constructor and of its public methods and properties, and its public class attributes: the annotation, and the value when it is a simple literal
Pydantic model every field: annotation, constraints such as min_length=1, whether it is required, its default or default factory, and any alias; plus the model_config keys it sets, such as extra and frozen
dataclass every field, including fields excluded from __init__: annotation, default or default factory, and init/kw_only flags; plus any dataclass parameter that differs from the default, such as frozen
enum every member name and value
constant its value when it is a simple literal (strings, numbers, booleans, None, enum members, and tuples, lists, sets, and dicts of them), otherwise only its type name
type alias its definition, such as Callable[[Transfer], Transfer]

The snapshot also lists each module's __provisional__ names under provisional, and rejects a provisional name missing from __all__. A provisional name's signature is still recorded, so every change to it is reviewed. Moving a name into or out of the provisional set is itself a snapshot change.

It records every canonical entry-point group under entry_point_groups: its name, the contract type its registry validates, the attribute that must match the entry-point name, whether a manifest is required, and whether the group is provisional. The private PROVISIONAL_PLUGIN_GROUPS constant names the provisional groups. A test requires each group's contract type to be provisional exactly when its group is, and requires Entry-point groups to label those groups as provisional.

The output is the same on every machine. Unordered collections are sorted, memory addresses are elided, paths are recorded only as the type name Path, and Pydantic annotations and constraints are rebuilt from their typing structure (Annotated[str, min_length=1] | None) rather than from a dependency's repr. A Pydantic upgrade does not by itself change the snapshot. Values that are neither literals nor types, such as the AnnotationContract held by VARIANT_GENE_LINK_ANNOTATION_CONTRACT, are recorded by type name only, so the snapshot does not detect a change to their contents.

Bindings

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

Runtimes

Each runtime owns its Python version, lockfile, tests, image definition and command. Test a change to the command contract between a binding and its runtime on both sides, and keep their dependency locks separate. 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 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.

runtimes/README.md shows how to build each image.