Contributing

​

Prerequisites

• Python 3.12
• uv package manager
• Git
• Modal account (for running integration tests remotely) or Apptainer (for local testing)

​

Setup

git clone https://github.com/softnanolab/boileroom.git
cd boileroom
uv python install 3.12
uv python pin 3.12
uv sync

​

Running tests

uv run pytest

uv run pytest tests/esm/ -v

uv run pytest --gpu A100-40GB

​

Code quality

uv run pre-commit run --all-files

• ruff for linting and formatting (line length: 120 characters)
• mypy for type checking

​

PR process

1. Create a branch from main (or the current development branch if one exists).
2. Make focused changes. Prefer small, reviewable PRs over large ones.
3. Ensure all CI checks pass (lint, format, tests).
4. Bump the version in pyproject.toml. This is required by CI and your pipeline will fail without it.
5. Write a PR description that explains what you changed and why.

​

Release and versioning

• Docker image version tags follow project.version in pyproject.toml.
• Runtime defaults also follow the installed boileroom package version unless you explicitly override the image tag.
• Merging to main triggers the Docker image workflow, which builds a temporary sha-<commit> validation tag, verifies it, and then promotes it to the current package version on Docker Hub.
• PyPI publication is separate and only happens when a GitHub release is published.
• That means Docker Hub can be the earlier staged release channel, while PyPI remains the later Python package release step.
• If you bump project.version, you are also changing the public versioned Docker tags that will be produced from main.

​

Project structure

boileroom/
    __init__.py          # Public exports
    base.py              # Algorithm, ModelWrapper base classes
    utils.py             # Shared utilities
    backend/
        base.py          # Backend ABC
        modal.py         # Modal backend
        apptainer.py     # Apptainer backend
    models/
        esm/             # ESMFold + ESM2
        chai/            # Chai-1
        boltz/           # Boltz-2
    images/              # Modal image definitions
tests/
    conftest.py          # Shared fixtures
    esm/, chai/, boltz/  # Per-model test suites
    data/                # Reference outputs

​

Key conventions

• Core algorithms are backend-agnostic. They must not import Modal, Apptainer, or any other backend-specific library.
• Modal imports go at the top of wrapper files (they are needed at import time for decorators).
• Apptainer imports are lazy (inside elif branches) to avoid requiring Apptainer as a dependency.
• Output types are dataclasses defined in types.py.
• Test reference data goes in tests/data/{model}/.

​

Further reading

• Architecture — how the system is structured and why.
• Adding a Model — step-by-step guide for integrating a new model.
• Adding a Backend — how to implement a new execution backend.