boileroom 0.3.0

Protein prediction models with Modal

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 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

Available Models

Model	Status	Description	Reference
ESMFold	✅	Fast protein structure prediction	Facebook (now Meta)
ESM-2	✅	MSA-free embedding model	Facebook (now Meta)
Chai-1	✅	Protein design and structure prediction model	Chai Discovery
Boltz-2	✅	Diffusion-based protein structure prediction	Boltz / MIT

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:

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

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

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