Skip to content

Development

Setting up a checkout, running lint and tests, the test data, and how releases are cut. For contributors; users need only Installation.

git clone git@github.com:openvax/vaxrank.git
cd vaxrank
python -m venv venv
source venv/bin/activate
pip install -e "." 'setuptools>=77.0.3' pytest pytest-cov ruff mkdocs-material
# Reference releases exercised by the test suite
pyensembl install --release 75 93 --species human
pyensembl install --release 93 102 --species mouse

Install the PDF dependencies and samtools for the original-read integration tests. Run linting and tests:

./lint.sh && ./test.sh

The distribution test invokes the build backend offline in this environment, so it needs the declared setuptools version even when editable installation used an isolated build environment. To check the documentation and README links:

python scripts/prepare_docs.py
mkdocs build --strict

See CONTRIBUTING.md for pull-request expectations and RELEASING.md for the release procedure.

Test suite and test data

The test suite is intentionally repository-only and is not included in source distributions: its integration tests depend on helpers and genomic fixtures that are not package payloads. Run tests from a Git checkout rather than an unpacked PyPI archive.

The Sid test data contains only the reads the regression suite explicitly selects. They come from openvax-v1, the OpenVax libraries' shared Sid test data published by osteosarc; the reviewed recipe ships in the package and verifies every selected record. The first run downloads required reads and reference data. Cached runs can reuse them; the full suite also contains explicit download and integration checks.

The first run may take a while to build the reference proteome kmer index. Later runs use the cached index.

Reference membership caches

Caches are keyed by installed annotation/sequence content, or by actual protein content for custom reference providers, as well as species and release. This supports explicit offline PyEnsembl Genome references and keeps a subset from sharing a full-reference cache. Upgrading from species/release-only caches triggers a one-time rebuild; old cache files are not trusted and not automatically deleted.

Safety prediction coverage API

Library callers of assess_vaccine_antigen_window and safety_assessment_from_prediction_frame can pass prediction_requests, a tuple of public MHCRequest records (also used by context audits). Each record declares an exact prediction kind, predictor name/version, one allele, and one required peptide length. Resolve these from the intended model configuration before prediction; never construct the request from the output rows. Declare lengths per allele so class-I and class-II configurations remain separate.

For every requested combination, coverage requires a finite percentile at every position where that peptide length fits inside the scanned window. Missing positions and nonfinite percentiles appear in prediction_coverage_gaps, with offsets relative to the window. Output outside the declared model/allele/length scope raises SafetyAssessmentError. A length longer than the window requires no positions, but an entirely empty prediction inventory cannot be reported as complete.

Historical inventories without a request remain readable and explicitly lack coverage. The safety policy reports incomplete in audit mode and raises SafetyPolicyError in enforce mode for undeclared or incomplete coverage. Off mode remains visibly disabled. Native replay retains the request and recomputes gaps from the preserved evidence; JSON reports include both. These coverage checks do not enable default CLI safety enforcement or change its screening thresholds, which remain separate work.

Scripts

  • develop.sh: installs the package in editable mode.
  • lint.sh: runs Ruff on the package, tests and release helpers.
  • test.sh: runs pytest; CI additionally collects coverage.
  • deploy.sh: runs lint, tests, build and upload through one Python environment, verifies PyPI artifacts by SHA-256, and safely resumes an interrupted upload from its original artifacts.
  • check_release_version.py --base origin/main: compares the committed PR version with the fetched target branch and release tags, without importing either version file.

Deploying a release

Deploy is restricted to a synchronized main/master. Bump the version in a PR, then run ./deploy.sh after merging. An optional version argument (with or without a v prefix) must match vaxrank/version.py; it never edits or commits a version bump.

After the quality gates, release_deploy.py rechecks live main and claims refs/tags/release-locks/vVERSION on origin before building. Independent clones wait for that owner, then verify the completed release instead of rebuilding it. Annotated release tags record the source commit and the exact wheel/sdist SHA-256 hashes, which must match PyPI. --dry-run validates and builds an archive of committed sources in temporary directories without uploading, tagging, pushing, or replacing a running deploy's build files.

An interrupted upload is resumed with its original dist/ files and local annotated release tag; missing or changed artifacts are rejected. Normal failures release the remote claim, but a killed process or lost connection may leave one behind. Before removing a stale claim, confirm its owner has stopped and recover its original artifacts and tag. The error message prints a deletion command guarded by that claim's exact object ID, so it cannot delete a newer owner's claim. Published versions with older lightweight tags have no recorded hashes and need manual artifact/tag verification; they are never rebuilt automatically.

Release version check in CI

The Release version PR check fetches the current target branch and tags on every run, including when a PR is retargeted. A PR must increase the version and choose a version with no existing release tag. Fetch the target branch and tags before running check_release_version.py locally (git fetch --tags origin).

Closed PR events are skipped. If validation fails while an open PR's job is running, the workflow rechecks the live PR state before reporting a failure; open PRs and failed state lookups still fail validation. A green check only covers the base and tags available during that run. Require the check with GitHub's "Require branches to be up to date before merging" option to prevent an old green result surviving another PR's release; otherwise rerun it after the target branch advances. The workflow itself does not change branch protection.

CI installs

CI uses scripts/pip_install.sh for installs that resolve sibling releases. It makes at most three attempts, waiting 20 then 40 seconds, and bypasses pip's cache on retries. All requirements and constraints stay unchanged, and persistent failures retain pip's exit status. PYTHON, PIP_INSTALL_ATTEMPTS and PIP_INSTALL_RETRY_DELAY override the interpreter and retry settings.