boileroom API Overview

boileroom provides a unified Python interface to run protein prediction models (structure prediction and embeddings) on serverless (Modal) or local (Apptainer) GPU infrastructure. You call the same methods regardless of backend — the models and their outputs are the primary interface.

These boileroom docs describe the v0.3 architecture and contributor workflow. If you are working against an older checkout or release, some files and development steps may differ.

boileroom powers BAGEL’s oracle inference. When you create an oracle like bg.oracles.ESMFold(use_modal=True) in BAGEL, boileroom handles model loading, GPU execution, and dependency isolation behind the scenes. See the BAGEL Oracles documentation for how oracles integrate with energy terms.

Architecture

User Code
    │
    ▼
Model (ESMFold / ESM2 / Chai1 / Boltz2)
    │
    ▼
Backend (Modal / Apptainer)
    │
    ▼
GPU Execution

Quick start

from boileroom import ESMFold

model = ESMFold(backend="modal")
result = model.fold("MKTVRQERLKSIVRI")

# Access the predicted structure
print(result.atom_array)  # list of Biotite AtomArray objects

Available models

Model	Type	Method	Description
`ESMFold`	Structure prediction	`.fold()`	Meta’s fast single-sequence structure prediction
`ESM2`	Embeddings	`.embed()`	Protein language model embeddings (6 model sizes)
`Chai1`	Structure prediction	`.fold()`	Diffusion-based structure prediction
`Boltz2`	Structure prediction	`.fold()`	Diffusion-based structure prediction with MSA support

Import patterns

from boileroom import ESMFold, ESM2, Chai1, Boltz2

Constructor

All models share the same constructor signature:

Model(backend="modal", device=None, config=None)

str

default:"modal"

Backend to use for execution. Supported values: "modal" (serverless GPU) or "apptainer" (local GPU via container). See Backends.

str | None

default:"None"

GPU device identifier (e.g., "cuda:0", "cpu"). If None, defaults to "cuda:0" when a GPU is available.

dict | None

default:"None"

Model-specific configuration overrides merged with defaults. Each model has its own config keys — see the model’s page or Configuration.

Context manager

All models can be used as context managers to ensure the backend is properly shut down:

with ESMFold(backend="modal") as model:
    result = model.fold("MKTVRQERLKSIVRI")
# Backend is automatically stopped

Without a context manager, the backend is cleaned up when the model instance is garbage collected or when the Python process exits.

Folding models

ESMFold

Fast single-sequence protein structure prediction.

Chai-1

Diffusion-based structure prediction.

Boltz-2

Diffusion-based structure prediction with MSA support.

Embedding models

ESM2

Protein language model for sequence embeddings.

Reference

Output Types

Shared output types and cross-model comparison.

Configuration

Static vs dynamic config, per-model config keys.

Backends

Modal (serverless) and Apptainer (local) backends.

Overview

Folding Models

Embedding Models

Reference

Development

boileroom API Overview

Architecture

Quick start

Available models

Import patterns

Constructor

Context manager

Folding models

ESMFold

Chai-1

Boltz-2

Embedding models

ESM2

Reference

Output Types

Configuration

Backends

​Architecture

​Quick start

​Available models

​Import patterns

​Constructor

​Context manager

​Folding models

ESMFold

Chai-1

Boltz-2

​Embedding models

ESM2

​Reference

Output Types

Configuration

Backends

Architecture

Quick start

Available models

Import patterns

Constructor

Context manager

Folding models

Embedding models

Reference