boileroom: protein prediction models across Modal and Apptainer

boileroom is a Python package that provides a unified interface to protein prediction models across Modal's serverless GPUs and Apptainer-based local or HPC execution.

🚨🚨🚨 v0.3.0 introduced major changes, including new models and inference backends. If you're upgrading from v0.2, please see the Migration Guide for details on breaking changes and how to update your code. 🚨🚨🚨

⚠️ Note: This package is currently in active development. The API and features may change between versions. We recommend pinning your version in production environments.

Features

• 🚀 Modal and Apptainer execution backends
• 🔄 Unified API across different models and runtimes
• 🎯 Production-ready with GPU acceleration
• 📦 Easy installation and deployment

Installation

1. Install the package using pip:

pip install boileroom

2. If you plan to use Modal, set up Modal credentials:

modal token new

For local containerized execution instead, install Apptainer and use backend="apptainer".

Quick Start

from boileroom import ESMC, ESMFold

# Use Modal by default; pass backend="apptainer" for local containerized execution
model = ESMFold()

# Predict structure for a protein sequence
sequence = "MLKNVHVLVLGAGDVGSVVVRLLEK"

result = model.fold(sequence, options={"include_fields": ["plddt"]})

# Access prediction results
atom_array = result.atom_array[0]
coordinates = atom_array.coord
confidence = result.plddt[0]  # Requested explicitly via include_fields above

# ESM-C / ESM3 are embedding-only. Colon-separated chains are supported.
embedder = ESMC(config={"model_name": "esmc_300m"})
embedding_result = embedder.embed("ACD:EF")
embedding_result.embeddings.shape  # (1, 5, features), residue-only
embedding_result.chain_index       # [[0, 0, 0, 1, 1]]

ESM-C and ESM3 use the MIT-licensed 2026 Chan Zuckerberg Biohub esm fork (weights biohub/esmc-*-2024-12 and biohub/esm3-sm-open-v1). They share the Biohub esmfold2 runtime image — the same esm package backs all three. Set MODEL_DIR to control the shared model-weight cache.

Confidence metrics returned by structure wrappers use a consistent public shape: plddt entries are unit-scale per-residue arrays on [0, 1], and scalar scores such as ptm and iptm are returned as shape-(1,) arrays. In 0.3.1, this replaces ESMFold's old padded pLDDT batch array and moves Boltz ptm/iptm from nested confidence dictionaries to top-level fields.

Available Models

Licensing: all bundled model weights are MIT-licensed except Chai-1, whose weights are released under the non-commercial Chai Discovery Community License. Review Chai Discovery's terms before using Chai-1 outside research.

Development

1. Clone the repository:

git clone https://github.com/jakublala/boileroom
cd boileroom

2. Install development dependencies using uv:

curl -LsSf https://astral.sh/uv/install.sh | sh
uv python install 3.12
uv sync

3. Run tests:

uv run pytest

For Modal integration tests, run the model families in parallel shards:

uv run pytest -v -n 4 --dist loadgroup -m integration

This starts four pytest workers and keeps each model family on its own worker, so Boltz, Chai, ESM2, and ESMFold use separate Modal apps without registering unrelated GPU functions in the same app.

To run the same integration tests in series, omit xdist:

uv run pytest -v -m integration

or only one test that's more verbose and shows print statements:

uv run python -m pytest tests/test_basic.py::test_esmfold_batch -v -s

To specify a GPU type for Modal backend tests (defaults to T4 if not specified):

uv run pytest --gpu A100-40GB

To run Modal integration tests against a specific Docker Hub namespace, image tag, and GPU type:

uv run pytest -v -n 4 --dist loadgroup -m integration \
  --docker-user <your-dockerhub-user> \
  --image-tag cuda12.6-my-test-tag \
  --gpu A10

The same --image-tag option works for the Apptainer backend. For Apptainer you can also pass the tag inline as --backend apptainer:<tag> (the inline suffix wins over --image-tag).

Available GPU options include T4, A100-40GB, A100-80GB, and other Modal-supported GPU types.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Citation

If you use boileroom in your research, please cite:

@software{boileroom2025,
  author = {Lála, Jakub},
  title = {boileroom: serverless protein prediction models},
  year = {2025},
  publisher = {GitHub},
  url = {https://github.com/softnanolab/boileroom}
}

Acknowledgments

• Modal Labs for the serverless infrastructure
• The teams behind ESMFold, AlphaFold, and other protein prediction models