BoltzGen¶
All-atom generative diffusion model for de novo binder design across proteins, peptides, nanobodies, and small molecule targets using a 7-stage design-to-validation pipeline.
License: MIT · Molecules: protein, dna, rna, ligand, complex · Tasks: sequence_generation, structure_prediction
Actions: generate · Variants: 1
At a glance¶
Use it when
- You need an end-to-end protein binder design pipeline that handles backbone generation, sequence design, structure validation, and affinity prediction without switching between separate tools
- You are designing nanobody (VHH) binders against protein targets and need to redesign CDR loops while preserving the stable immunoglobulin framework
- You are designing cyclic peptides as therapeutic candidates targeting protein-protein interactions, with support for head-to-tail cyclization and disulfide bond constraints
- You need to design protein pockets around specific small-molecule ligands (drug substrates, cofactors) for enzyme or biosensor engineering
- You want diversity-aware candidate selection that maximizes structural coverage across your design library, improving experimental success probability
- You need to computationally rank designs by predicted binding affinity before committing to experimental synthesis and testing
Strengths
- End-to-end binder design pipeline: integrates diffusion-based backbone generation, inverse folding (BoltzIF), integrated structure validation, and integrated binding affinity prediction in a single unified workflow -- no separate tools needed
- Experimentally validated with 66% nanomolar binder success rate across 9 novel protein targets, including targets with low similarity to known bound structures -- competitive with the best published binder design results
- Supports diverse design modalities: de novo protein binders, nanobody CDR redesign, cyclic peptides (with head-to-tail cyclization and disulfide bonds), and small-molecule pocket design in a single model
- Geometry-based 14-atom amino acid representation generates physically plausible all-atom structures in continuous 3D coordinate space, avoiding discrete tokenization artifacts
- Integrated affinity ranking: each design is scored for predicted binding affinity, enabling computational filtering before expensive experimental validation
- Successfully designs binders against traditionally difficult targets: intrinsically disordered protein regions, antimicrobial peptides, and proteins with no known binders in the structural database
- Diversity-aware filtering selects structurally diverse top candidates, improving the probability that at least one candidate succeeds experimentally
- MIT license with no usage restrictions -- fully open-source design pipeline suitable for academic research and commercial drug discovery
Limitations
- Requires A100 40GB GPU with 64GB system RAM and up to 24 hours for large design campaigns (up to 500 candidate designs per request; default 100) -- expensive infrastructure for iterative optimization
- Affinity predictions from the integrated affinity module carry high stochastic variance (80%+ between runs), requiring ensemble averaging for reliable ranking -- not a deterministic affinity oracle
- Nanobody CDR redesign requires precise CDR residue index specification matching PDB numbering -- incorrect indices silently produce meaningless designs
- Not a structure prediction model: cannot predict the native fold of an existing protein sequence; use Chai-1, RF3, or AF2 NIM for prediction tasks
- Membrane protein targets are poorly supported due to training data bias toward soluble complexes and absence of lipid bilayer modeling
- Full IgG antibody design is not supported -- the model targets nanobody/VHH fragments and small-to-medium protein binders (80-200 residues)
- Designed sequences are novel and may have unforeseen aggregation, immunogenicity, or manufacturability issues that the model does not predict
- Very short peptide designs (< 8 residues) lack sufficient structural context for reliable backbone generation within the diffusion framework
Reach for something else when
- You need to predict the native structure of an existing protein or complex -- BoltzGen is for design, not prediction; use RF3, Chai-1, or AF2 NIM
- You need to design full-length IgG antibodies -- BoltzGen targets nanobodies and smaller protein binders; use antibody-specific design tools for full IgG engineering
- You need precise catalytic activity design for enzymes -- BoltzGen designs binding pockets but does not model catalytic mechanisms, transition states, or enzyme kinetics
- Your target is a membrane protein and the binding site is within the lipid bilayer -- BoltzGen is trained on soluble complexes
- You need deterministic affinity predictions -- BoltzGen's integrated affinity stage has high stochastic variance requiring multiple samples for reliable ranking
- You need symmetric protein assembly design (cages, rings, nanocages) -- BoltzGen has no explicit symmetric design mode for these repeated architectures
- You need fast single-pass structure generation for rapid prototyping -- BoltzGen's full pipeline (10,000 candidates + filtering) is computationally intensive
Alternatives
| Model | Better when | Worse when |
|---|---|---|
| mpnn | Gold-standard inverse folding: designs sequences for any supplied backbone in seconds on modest hardware, independent of how the backbone was produced. | Requires an existing backbone and outputs sequences only; cannot generate novel backbones, design against a target, or predict binding affinity. |
| esm_if1 | GVP-transformer inverse folding trained on ~12M predicted structures; single-pass sequence design over a supplied backbone, tolerant of partial/multi-chain input. | Inverse folding only — needs a supplied backbone, and cannot do de novo backbone generation, target-conditioned binder design, or affinity scoring. |
| antifold | Purpose-built antibody/nanobody inverse folding; a direct substitute for BoltzGen's nanobody-CDR-redesign use case, redesigning CDR sequences on an existing Fv/nanobody structure while preserving the framework. | Restricted to antibody/nanobody structures and sequence redesign only; cannot generate novel backbones or design against arbitrary protein/ligand targets. |
API & schema¶
Call an action with POST /api/v1/{slug}/{action} — the request envelope is {"items": [...], "params": {...}} and a success returns {"results": [...]}. See the HTTP API page for the base URL, error shape, and full contract.
generate¶
Call it
curl -X POST http://127.0.0.1:8000/api/v1/boltzgen/generate \
-H "Content-Type: application/json" \
-d '{
"items": [
{
"entities": [
{}
]
}
]
}'
Request — BoltzGenDesignRequest
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
items |
list[BoltzGenDesignRequestItem] | yes | items 1–1 | Batch of inputs to process in a single request. Up to 1 design system per request. |
params |
BoltzGenDesignParams | no | Optional parameters controlling this action (defaults are used when omitted). |
Nested types
BoltzGenBindingType
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
chain |
string | list[string] | yes | Chain ID or list of chain IDs this binding constraint applies to. | |
binding |
string | integer | list[string | integer] | null | no | Residue positions that should be at the binding interface. Accepts the same formats as res_index, or 'all'. | |
not_binding |
string | integer | list[string | integer] | null | no | Residue positions that should NOT be at the binding interface. Accepts the same formats as res_index, or 'all'. |
BoltzGenBondConstraint
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
atom1 |
list[string | integer] | yes | Atom identifier for the first atom, as [chain_id, res_index, atom_name] (e.g. ['A', 1, 'CA']). | |
atom2 |
list[string | integer] | yes | Atom identifier for the second atom, as [chain_id, res_index, atom_name]. |
BoltzGenChainSelector
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
id |
string | list[string] | yes | Chain ID or list of chain IDs to select (e.g. 'A' or ['A', 'B']). | |
res_index |
string | integer | list[string | integer] | null | no | Residue positions within the chain. Uses 1-based indexing. Accepts an integer (5), a range ('10..16'), open ranges ('..10', '20..'), or comma-separated combinations ('1..5,10,20..30'). If omitted, the entire chain is selected. |
BoltzGenConstraint
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
bond |
BoltzGenBondConstraint | null | no | Force a covalent bond between two atoms (e.g. for disulfide bonds or linker attachment). | |
contact |
BoltzGenContactConstraint | null | no | Require two residues to be within a maximum Cα–Cα distance. | |
pocket |
BoltzGenPocketConstraint | null | no | Constrain a binder chain to contact a set of pocket residues on a target chain. | |
total_len |
BoltzGenTotalLengthConstraint | null | no | Bound the total number of designable residues across all chains. |
BoltzGenContactConstraint
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
token1 |
list[string | integer] | yes | Token identifier for the first residue, as [chain_id, res_index] (e.g. ['A', 5]). | |
token2 |
list[string | integer] | yes | Token identifier for the second residue, as [chain_id, res_index]. | |
max_distance |
number | yes | Maximum allowed Cα–Cα distance in Ångströms between the two tokens. |
BoltzGenDesignInsertion
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
insertion |
object | yes | Insertion site specification with keys: 'id' (chain ID, e.g. 'B'), 'res_index' (position to insert after, e.g. 26), 'num_residues' (count or range, e.g. '1..5'). |
BoltzGenDesignParams
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
protocol |
BoltzGenProtocol | no | default protein-anything |
Design protocol that determines what is being designed and how. 'protein-anything' designs a protein binder against any target chain. 'peptide-anything' designs a short peptide binder. 'protein-small_molecule' designs a protein that binds a specified small-molecule ligand. 'nanobody-anything' designs a nanobody-format binder. |
steps |
list[BoltzGenPipelineStep] | null | no | Ordered list of pipeline steps to execute. If omitted, all steps run in the default order: design → inverse_folding → folding → design_folding → affinity → analysis → filtering. Provide an explicit list to run a subset (e.g. ['design'] for backbone-only runs). Steps are always executed in pipeline order regardless of the order listed here. | |
num_designs |
integer | no | ≥1; ≤500; default 100 |
Total number of backbone structures to generate in the 'design' step. This is the size of the candidate pool that all subsequent steps (inverse folding, folding, affinity, analysis) will process. A larger pool gives the filtering step more diversity to select from, but increases compute time proportionally. Default is 100. Maximum is 500. See also: 'budget', which controls how many designs are returned after filtering. |
budget |
integer | no | ≥1; ≤500; default 100 |
Number of final designs to return after the 'filtering' step applies diversity-optimised ranking. The filtering step scores all 'num_designs' candidates, then selects this many using a quality-vs-diversity trade-off (controlled by 'alpha'). Must be ≤ num_designs. Has no effect if the 'filtering' step is not included in 'steps'. See also: 'num_designs' (the full candidate pool size) and 'alpha' (diversity weight). |
diffusion_batch_size |
integer | null | no | Number of diffusion samples to generate in parallel. | |
step_scale |
number | null | no | Fixed step scale (noise schedule multiplier) for the diffusion sampler. Lower values produce more conservative, less diverse structures. Higher values produce more diverse but potentially lower-quality structures. If omitted, boltzgen uses its adaptive default. | |
noise_scale |
number | null | no | Noise injection scale applied during diffusion sampling (0.0–1.0). 0.0 = fully deterministic sampling, 1.0 = maximum stochasticity. If omitted, boltzgen uses its default noise schedule. | |
inverse_fold_num_sequences |
integer | no | ≥1; ≤10; default 1 |
Number of amino-acid sequences to generate per backbone in the 'inverse_folding' step. Each backbone from 'num_designs' gets this many sequence candidates, so the total sequences entering the folding step is num_designs × inverse_fold_num_sequences. Increasing this improves sequence diversity at the cost of proportionally more compute in the folding and affinity steps. |
inverse_fold_avoid |
string | null | no | Amino acids to exclude from inverse-folding predictions, as a string of one-letter codes (e.g. 'KEC' to disallow lysine, glutamate, and cysteine). Useful for removing cysteines (disulfide risk) or charged residues for specific formulations. | |
refolding_rmsd_threshold |
number | null | no | Maximum Cα RMSD (Å) between the designed backbone and its refolded structure, used as a self-consistency filter in the 'folding' step. Designs where the folded structure deviates beyond this threshold are discarded. Lower values enforce stricter self-consistency. If omitted, no RMSD filter is applied. | |
alpha |
number | null | no | Diversity weight for the final selection in the 'filtering' step (0.0–1.0). 0.0 = pure quality ranking (top-scoring designs regardless of similarity). 1.0 = pure diversity selection (maximise sequence/structure spread). Intermediate values blend quality and diversity. If omitted, boltzgen uses its default balance. | |
filter_biased |
boolean | null | no | Whether to remove designs with biased amino-acid compositions during filtering. When True, designs that are statistical outliers in their residue frequencies (e.g. unusually hydrophobic or charged) are discarded before the final selection. | |
additional_filters |
list[string] | null | no | Hard filters applied to the scored designs before final selection. Each entry is an expression of the form 'metric>threshold' or 'metric |
|
metrics_override |
object | null | no | Override the per-metric importance weights used during ranking. Keys are metric names (e.g. 'plddt', 'ptm', 'affinity') and values are floats representing inverse importance (higher = less important in ranking). Use this to up-weight or down-weight specific metrics relative to the protocol default. |
BoltzGenDesignRequestItem
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
entities |
list[BoltzGenEntity] | yes | items 1– | List of entities (protein, ligand, file, DNA, RNA) that make up the design system. At least one entity is required. Typically this includes one designable chain and one or more fixed target chains, but the exact composition depends on the protocol. |
constraints |
list[BoltzGenConstraint] | null | no | Structural constraints enforced during diffusion sampling. Use bond, contact, or pocket constraints to bias the design toward specific geometries. If omitted, no structural constraints are applied beyond those implied by the protocol. | |
reset_res_index |
list[BoltzGenChainSelector] | null | no | Reset residue numbering to start from 1 for the specified chains. This top-level field applies the reset globally across all entities. Can also be set per-entity inside a file entity. Commonly needed in scaffold redesign when input structures have non-sequential numbering. |
BoltzGenDesignSpec
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
chain |
string | list[string] | yes | Chain ID or list of chain IDs whose residues are designable. | |
res_index |
string | integer | list[string | integer] | null | no | Residue positions to make designable. Uses 1-based indexing. Accepts an integer, a range ('10..16'), or comma-separated combinations ('26..34,52..59'). If omitted, the entire chain is treated as designable. |
BoltzGenEntity
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
protein |
BoltzGenProteinEntity | null | no | A protein chain defined by sequence or length. Use for chains that will be designed or held fixed. | |
ligand |
BoltzGenLigandEntity | null | no | A small-molecule ligand defined by CCD code or SMILES. Use for protein-small_molecule protocols. | |
file |
BoltzGenFileEntity | null | no | A structure loaded from a CIF or PDB file. Use when the scaffold or reference structure is pre-determined. | |
dna |
object | null | no | A DNA chain entity. Follows the same structure as protein entities (id, sequence, etc.). | |
rna |
object | null | no | An RNA chain entity. Follows the same structure as protein entities (id, sequence, etc.). |
BoltzGenFileEntity
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
cif |
string | null | no | Structure content in mmCIF format. Exactly one of 'cif' or 'pdb' must be provided. | |
pdb |
string | null | no | Structure content in PDB format. Exactly one of 'cif' or 'pdb' must be provided. | |
include |
list[BoltzGenChainSelector] | null | no | Chains (and optionally residues) from the file to include in the design system. If omitted, all chains are included. | |
exclude |
list[BoltzGenChainSelector] | null | no | Chains (and optionally residues) from the file to exclude from the design system. Useful for removing non-essential chains like crystallographic partners. | |
include_proximity |
list[object] | null | no | Include residues that are spatially proximate to specified reference residues. Each entry is a dict matching the boltzgen YAML proximity format. | |
binding_types |
string | list[BoltzGenBindingType] | null | no | Binding-site constraints for chains in this file entity. Pass 'auto' to infer binding sites automatically, or provide explicit per-chain specs. | |
structure_groups |
list[BoltzGenStructureGroup] | null | no | Groups of chains with a shared visibility level during diffusion. Controls how much structural context each group provides to the model. | |
design |
list[BoltzGenDesignSpec] | null | no | Chains and residues that are designable (sequence will be optimised). If omitted alongside not_design, the protocol default applies. | |
not_design |
list[BoltzGenDesignSpec] | null | no | Residues to explicitly lock (exclude from design), even if they fall within a 'design' spec. Takes precedence over entries in 'design'. | |
secondary_structure |
list[BoltzGenSecondaryStructureSpec] | null | no | Secondary structure constraints (helix, sheet, loop) for residues in this entity. | |
design_insertions |
list[BoltzGenDesignInsertion] | null | no | Insertion sites where the model may insert additional residues during design. | |
fuse |
string | null | no | Chain ID to fuse this entity's chain into. When set, the two chains are treated as a single contiguous chain by the model. | |
use_assembly |
boolean | null | no | Whether to load the biological assembly from the structure file rather than the asymmetric unit. Defaults to False. Useful when the functional form is a homo-oligomer. | |
reset_res_index |
list[BoltzGenChainSelector] | null | no | Reset residue numbering to start from 1 for the specified chains. Commonly needed in scaffold redesign workflows where the input structure has non-standard numbering. | |
add_cyclization |
list[object] | null | no | Add covalent cyclization bonds (e.g. head-to-tail) to specified chains. Each entry is a dict matching the boltzgen YAML cyclization format. Use for cyclic peptide or cyclic protein design. | |
msa |
integer | string | null | no | Multiple sequence alignment (MSA) mode for this entity. 0 = auto-generate MSA (default behaviour), -1 = no MSA (single-sequence mode), or provide a path to a pre-computed MSA file. |
BoltzGenLigandEntity
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
id |
string | list[string] | yes | Chain ID or list of chain IDs for this ligand entity (e.g. 'L' or ['L1', 'L2']). | |
ccd |
string | null | no | Chemical Component Dictionary (CCD) code identifying the ligand (e.g. 'ATP', 'HEM'). Use this for standard ligands with a PDB CCD entry. Exactly one of 'ccd' or 'smiles' must be provided. | |
smiles |
string | null | no | SMILES string defining the ligand chemistry. Use this for non-standard or novel small molecules. Exactly one of 'ccd' or 'smiles' must be provided. | |
binding_types |
string | list[BoltzGenBindingType] | null | no | Binding-site constraints for this ligand. Pass 'auto' to infer binding sites automatically, or provide explicit per-chain specs. |
BoltzGenPipelineStep
Allowed values: design, inverse_folding, folding, design_folding, affinity, analysis, filtering
BoltzGenPocketConstraint
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
binder |
string | yes | Chain ID of the binder (the chain being designed to engage the pocket). | |
contacts |
list[list[string | integer]] | yes | List of pocket residue tokens on the target chain that the binder must contact. Each entry is [chain_id, res_index] (e.g. [['B', 42], ['B', 56]]). | |
max_distance |
number | null | no | Maximum Cα–Cα distance (Å) used to define 'contact'. If omitted, the boltzgen default threshold is used. |
BoltzGenProteinEntity
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
id |
string | list[string] | yes | Chain ID or list of chain IDs for this protein entity (e.g. 'A' or ['A', 'B']). | |
sequence |
string | integer | object | yes | Defines the protein chain length and any fixed residues. Pass an integer (e.g. 50) to design a chain of that exact length with all residues free. Pass a range string (e.g. '30..50') to allow variable length. Pass an amino-acid sequence string (e.g. 'MKVL...') to fix the entire sequence. Pass a dict of {residue_index: amino_acid} to fix only specific positions. | |
cyclic |
boolean | no | default False |
Whether this protein chain is cyclic (head-to-tail peptide bond). When True, boltzgen adds the appropriate cyclization bond during design. |
secondary_structure |
list[BoltzGenSecondaryStructureSpec] | null | no | Secondary structure constraints (helix, sheet, loop) for residues in this chain. | |
binding_types |
string | list[BoltzGenBindingType] | null | no | Binding-site constraints for this chain. Pass 'auto' to infer binding sites automatically, or provide explicit per-chain specs. | |
msa |
integer | string | null | no | Multiple sequence alignment (MSA) mode for this entity. 0 = auto-generate MSA (default behaviour), -1 = no MSA (single-sequence mode), or provide a path to a pre-computed MSA file. |
BoltzGenProtocol
Allowed values: protein-anything, peptide-anything, protein-small_molecule, nanobody-anything
BoltzGenSecondaryStructureSpec
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
chain |
string | list[string] | yes | Chain ID or list of chain IDs to apply secondary structure constraints to. | |
loop |
string | integer | list[string | integer] | null | no | Residue positions that should adopt loop (coil) secondary structure. | |
helix |
string | integer | list[string | integer] | null | no | Residue positions that should adopt alpha-helix secondary structure. | |
sheet |
string | integer | list[string | integer] | null | no | Residue positions that should adopt beta-sheet secondary structure. |
BoltzGenStructureGroup
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
group |
object | yes | Mapping of chain IDs to residue indices defining the group membership. Use 'all' as the id to target all residues. | |
visibility |
integer | no | ≥0; ≤2; default 1 |
Structural visibility level for this group. 0 = fully masked, 1 = partial visibility (default), 2 = fully visible (fixed). |
BoltzGenTotalLengthConstraint
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
min |
integer | null | no | Minimum total residue count across all designable chains. | |
max |
integer | null | no | Maximum total residue count across all designable chains. |
Raw JSON Schema
{
"$defs": {
"BoltzGenBindingType": {
"additionalProperties": false,
"description": "Specifies binding-site residues for a chain, used to bias diffusion toward interface contacts.",
"properties": {
"chain": {
"anyOf": [
{
"type": "string"
},
{
"items": {
"type": "string"
},
"type": "array"
}
],
"description": "Chain ID or list of chain IDs this binding constraint applies to.",
"title": "Chain"
},
"binding": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
},
{
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Residue positions that should be at the binding interface. Accepts the same formats as res_index, or 'all'.",
"title": "Binding"
},
"not_binding": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
},
{
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Residue positions that should NOT be at the binding interface. Accepts the same formats as res_index, or 'all'.",
"title": "Not Binding"
}
},
"required": [
"chain"
],
"title": "BoltzGenBindingType",
"type": "object"
},
"BoltzGenBondConstraint": {
"additionalProperties": false,
"description": "Forces a covalent bond between two specific atoms across any two chains.",
"properties": {
"atom1": {
"description": "Atom identifier for the first atom, as [chain_id, res_index, atom_name] (e.g. ['A', 1, 'CA']).",
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"title": "Atom1",
"type": "array"
},
"atom2": {
"description": "Atom identifier for the second atom, as [chain_id, res_index, atom_name].",
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"title": "Atom2",
"type": "array"
}
},
"required": [
"atom1",
"atom2"
],
"title": "BoltzGenBondConstraint",
"type": "object"
},
"BoltzGenChainSelector": {
"additionalProperties": false,
"description": "Selects a chain (or subset of residues) for include/exclude/reset operations.\n\nUsed by ``include``, ``exclude``, and ``reset_res_index`` fields on file entities\nand at the top level of a design request item.",
"properties": {
"id": {
"anyOf": [
{
"type": "string"
},
{
"items": {
"type": "string"
},
"type": "array"
}
],
"description": "Chain ID or list of chain IDs to select (e.g. 'A' or ['A', 'B']).",
"title": "Id"
},
"res_index": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
},
{
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Residue positions within the chain. Uses 1-based indexing. Accepts an integer (5), a range ('10..16'), open ranges ('..10', '20..'), or comma-separated combinations ('1..5,10,20..30'). If omitted, the entire chain is selected.",
"title": "Res Index"
}
},
"required": [
"id"
],
"title": "BoltzGenChainSelector",
"type": "object"
},
"BoltzGenConstraint": {
"additionalProperties": false,
"description": "A single structural constraint applied during diffusion. Exactly one constraint type must be set.",
"properties": {
"bond": {
"anyOf": [
{
"$ref": "#/$defs/BoltzGenBondConstraint"
},
{
"type": "null"
}
],
"default": null,
"description": "Force a covalent bond between two atoms (e.g. for disulfide bonds or linker attachment)."
},
"contact": {
"anyOf": [
{
"$ref": "#/$defs/BoltzGenContactConstraint"
},
{
"type": "null"
}
],
"default": null,
"description": "Require two residues to be within a maximum C\u03b1\u2013C\u03b1 distance."
},
"pocket": {
"anyOf": [
{
"$ref": "#/$defs/BoltzGenPocketConstraint"
},
{
"type": "null"
}
],
"default": null,
"description": "Constrain a binder chain to contact a set of pocket residues on a target chain."
},
"total_len": {
"anyOf": [
{
"$ref": "#/$defs/BoltzGenTotalLengthConstraint"
},
{
"type": "null"
}
],
"default": null,
"description": "Bound the total number of designable residues across all chains."
}
},
"title": "BoltzGenConstraint",
"type": "object"
},
"BoltzGenContactConstraint": {
"additionalProperties": false,
"description": "Requires two residue tokens to be within a maximum C\u03b1\u2013C\u03b1 distance of each other.",
"properties": {
"token1": {
"description": "Token identifier for the first residue, as [chain_id, res_index] (e.g. ['A', 5]).",
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"title": "Token1",
"type": "array"
},
"token2": {
"description": "Token identifier for the second residue, as [chain_id, res_index].",
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"title": "Token2",
"type": "array"
},
"max_distance": {
"description": "Maximum allowed C\u03b1\u2013C\u03b1 distance in \u00c5ngstr\u00f6ms between the two tokens.",
"title": "Max Distance",
"type": "number"
}
},
"required": [
"token1",
"token2",
"max_distance"
],
"title": "BoltzGenContactConstraint",
"type": "object"
},
"BoltzGenDesignInsertion": {
"additionalProperties": false,
"description": "Defines an insertion site where new residues may be inserted during design.",
"properties": {
"insertion": {
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"description": "Insertion site specification with keys: 'id' (chain ID, e.g. 'B'), 'res_index' (position to insert after, e.g. 26), 'num_residues' (count or range, e.g. '1..5').",
"title": "Insertion",
"type": "object"
}
},
"required": [
"insertion"
],
"title": "BoltzGenDesignInsertion",
"type": "object"
},
"BoltzGenDesignParams": {
"additionalProperties": false,
"description": "Pipeline-level parameters controlling how BoltzGen generates and ranks designs.",
"properties": {
"protocol": {
"$ref": "#/$defs/BoltzGenProtocol",
"default": "protein-anything",
"description": "Design protocol that determines what is being designed and how. 'protein-anything' designs a protein binder against any target chain. 'peptide-anything' designs a short peptide binder. 'protein-small_molecule' designs a protein that binds a specified small-molecule ligand. 'nanobody-anything' designs a nanobody-format binder."
},
"steps": {
"anyOf": [
{
"items": {
"$ref": "#/$defs/BoltzGenPipelineStep"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Ordered list of pipeline steps to execute. If omitted, all steps run in the default order: design \u2192 inverse_folding \u2192 folding \u2192 design_folding \u2192 affinity \u2192 analysis \u2192 filtering. Provide an explicit list to run a subset (e.g. ['design'] for backbone-only runs). Steps are always executed in pipeline order regardless of the order listed here.",
"title": "Steps"
},
"num_designs": {
"default": 100,
"description": "Total number of backbone structures to generate in the 'design' step. This is the size of the candidate pool that all subsequent steps (inverse folding, folding, affinity, analysis) will process. A larger pool gives the filtering step more diversity to select from, but increases compute time proportionally. Default is 100. Maximum is 500. See also: 'budget', which controls how many designs are returned after filtering.",
"maximum": 500,
"minimum": 1,
"title": "Num Designs",
"type": "integer"
},
"budget": {
"default": 100,
"description": "Number of final designs to return after the 'filtering' step applies diversity-optimised ranking. The filtering step scores all 'num_designs' candidates, then selects this many using a quality-vs-diversity trade-off (controlled by 'alpha'). Must be \u2264 num_designs. Has no effect if the 'filtering' step is not included in 'steps'. See also: 'num_designs' (the full candidate pool size) and 'alpha' (diversity weight).",
"maximum": 500,
"minimum": 1,
"title": "Budget",
"type": "integer"
},
"diffusion_batch_size": {
"anyOf": [
{
"maximum": 100,
"minimum": 1,
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Number of diffusion samples to generate in parallel.",
"title": "Diffusion Batch Size"
},
"step_scale": {
"anyOf": [
{
"maximum": 10.0,
"minimum": 0.1,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Fixed step scale (noise schedule multiplier) for the diffusion sampler. Lower values produce more conservative, less diverse structures. Higher values produce more diverse but potentially lower-quality structures. If omitted, boltzgen uses its adaptive default.",
"title": "Step Scale"
},
"noise_scale": {
"anyOf": [
{
"maximum": 1.0,
"minimum": 0.0,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Noise injection scale applied during diffusion sampling (0.0\u20131.0). 0.0 = fully deterministic sampling, 1.0 = maximum stochasticity. If omitted, boltzgen uses its default noise schedule.",
"title": "Noise Scale"
},
"inverse_fold_num_sequences": {
"default": 1,
"description": "Number of amino-acid sequences to generate per backbone in the 'inverse_folding' step. Each backbone from 'num_designs' gets this many sequence candidates, so the total sequences entering the folding step is num_designs \u00d7 inverse_fold_num_sequences. Increasing this improves sequence diversity at the cost of proportionally more compute in the folding and affinity steps.",
"maximum": 10,
"minimum": 1,
"title": "Inverse Fold Num Sequences",
"type": "integer"
},
"inverse_fold_avoid": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Amino acids to exclude from inverse-folding predictions, as a string of one-letter codes (e.g. 'KEC' to disallow lysine, glutamate, and cysteine). Useful for removing cysteines (disulfide risk) or charged residues for specific formulations.",
"title": "Inverse Fold Avoid"
},
"refolding_rmsd_threshold": {
"anyOf": [
{
"minimum": 0.0,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Maximum C\u03b1 RMSD (\u00c5) between the designed backbone and its refolded structure, used as a self-consistency filter in the 'folding' step. Designs where the folded structure deviates beyond this threshold are discarded. Lower values enforce stricter self-consistency. If omitted, no RMSD filter is applied.",
"title": "Refolding Rmsd Threshold"
},
"alpha": {
"anyOf": [
{
"maximum": 1.0,
"minimum": 0.0,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Diversity weight for the final selection in the 'filtering' step (0.0\u20131.0). 0.0 = pure quality ranking (top-scoring designs regardless of similarity). 1.0 = pure diversity selection (maximise sequence/structure spread). Intermediate values blend quality and diversity. If omitted, boltzgen uses its default balance.",
"title": "Alpha"
},
"filter_biased": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether to remove designs with biased amino-acid compositions during filtering. When True, designs that are statistical outliers in their residue frequencies (e.g. unusually hydrophobic or charged) are discarded before the final selection.",
"title": "Filter Biased"
},
"additional_filters": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Hard filters applied to the scored designs before final selection. Each entry is an expression of the form 'metric>threshold' or 'metric<threshold' (e.g. ['plddt>70', 'ptm>0.5']). Designs that fail any filter are excluded. Available metrics depend on which analysis steps have run.",
"title": "Additional Filters"
},
"metrics_override": {
"anyOf": [
{
"additionalProperties": {
"anyOf": [
{
"type": "number"
},
{
"type": "string"
}
]
},
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Override the per-metric importance weights used during ranking. Keys are metric names (e.g. 'plddt', 'ptm', 'affinity') and values are floats representing inverse importance (higher = less important in ranking). Use this to up-weight or down-weight specific metrics relative to the protocol default.",
"title": "Metrics Override"
}
},
"title": "BoltzGenDesignParams",
"type": "object"
},
"BoltzGenDesignRequestItem": {
"additionalProperties": false,
"description": "Defines a single design target: the set of chains and constraints that describe the system to design.",
"properties": {
"entities": {
"description": "List of entities (protein, ligand, file, DNA, RNA) that make up the design system. At least one entity is required. Typically this includes one designable chain and one or more fixed target chains, but the exact composition depends on the protocol.",
"items": {
"$ref": "#/$defs/BoltzGenEntity"
},
"minItems": 1,
"title": "Entities",
"type": "array"
},
"constraints": {
"anyOf": [
{
"items": {
"$ref": "#/$defs/BoltzGenConstraint"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Structural constraints enforced during diffusion sampling. Use bond, contact, or pocket constraints to bias the design toward specific geometries. If omitted, no structural constraints are applied beyond those implied by the protocol.",
"title": "Constraints"
},
"reset_res_index": {
"anyOf": [
{
"items": {
"$ref": "#/$defs/BoltzGenChainSelector"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Reset residue numbering to start from 1 for the specified chains. This top-level field applies the reset globally across all entities. Can also be set per-entity inside a file entity. Commonly needed in scaffold redesign when input structures have non-sequential numbering.",
"title": "Reset Res Index"
}
},
"required": [
"entities"
],
"title": "BoltzGenDesignRequestItem",
"type": "object"
},
"BoltzGenDesignSpec": {
"additionalProperties": false,
"description": "Marks residues in a chain as designable (sequence will be optimised by the model).\n\nStructurally identical to ``BoltzGenChainSelector`` but uses ``chain`` instead\nof ``id`` to match the boltzgen YAML format for ``design`` / ``not_design`` fields.",
"properties": {
"chain": {
"anyOf": [
{
"type": "string"
},
{
"items": {
"type": "string"
},
"type": "array"
}
],
"description": "Chain ID or list of chain IDs whose residues are designable.",
"title": "Chain"
},
"res_index": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
},
{
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Residue positions to make designable. Uses 1-based indexing. Accepts an integer, a range ('10..16'), or comma-separated combinations ('26..34,52..59'). If omitted, the entire chain is treated as designable.",
"title": "Res Index"
}
},
"required": [
"chain"
],
"title": "BoltzGenDesignSpec",
"type": "object"
},
"BoltzGenEntity": {
"additionalProperties": false,
"description": "Entity specification - can be protein, ligand, or file.\n\nThis uses a discriminated union pattern where exactly one of\nprotein, ligand, or file must be provided.",
"properties": {
"protein": {
"anyOf": [
{
"$ref": "#/$defs/BoltzGenProteinEntity"
},
{
"type": "null"
}
],
"default": null,
"description": "A protein chain defined by sequence or length. Use for chains that will be designed or held fixed."
},
"ligand": {
"anyOf": [
{
"$ref": "#/$defs/BoltzGenLigandEntity"
},
{
"type": "null"
}
],
"default": null,
"description": "A small-molecule ligand defined by CCD code or SMILES. Use for protein-small_molecule protocols."
},
"file": {
"anyOf": [
{
"$ref": "#/$defs/BoltzGenFileEntity"
},
{
"type": "null"
}
],
"default": null,
"description": "A structure loaded from a CIF or PDB file. Use when the scaffold or reference structure is pre-determined."
},
"dna": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "A DNA chain entity. Follows the same structure as protein entities (id, sequence, etc.).",
"title": "Dna"
},
"rna": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "An RNA chain entity. Follows the same structure as protein entities (id, sequence, etc.).",
"title": "Rna"
}
},
"title": "BoltzGenEntity",
"type": "object"
},
"BoltzGenFileEntity": {
"additionalProperties": false,
"description": "File entity for loading structures from CIF/PDB files.\n\nThe file content should be provided as either `cif` or `pdb` string.\nThe file will be written to a temporary location when processing.",
"properties": {
"cif": {
"anyOf": [
{
"maxLength": 2500000,
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Structure content in mmCIF format. Exactly one of 'cif' or 'pdb' must be provided.",
"title": "Cif"
},
"pdb": {
"anyOf": [
{
"maxLength": 2500000,
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Structure content in PDB format. Exactly one of 'cif' or 'pdb' must be provided.",
"title": "Pdb"
},
"include": {
"anyOf": [
{
"items": {
"$ref": "#/$defs/BoltzGenChainSelector"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Chains (and optionally residues) from the file to include in the design system. If omitted, all chains are included.",
"title": "Include"
},
"exclude": {
"anyOf": [
{
"items": {
"$ref": "#/$defs/BoltzGenChainSelector"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Chains (and optionally residues) from the file to exclude from the design system. Useful for removing non-essential chains like crystallographic partners.",
"title": "Exclude"
},
"include_proximity": {
"anyOf": [
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Include residues that are spatially proximate to specified reference residues. Each entry is a dict matching the boltzgen YAML proximity format.",
"title": "Include Proximity"
},
"binding_types": {
"anyOf": [
{
"type": "string"
},
{
"items": {
"$ref": "#/$defs/BoltzGenBindingType"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Binding-site constraints for chains in this file entity. Pass 'auto' to infer binding sites automatically, or provide explicit per-chain specs.",
"title": "Binding Types"
},
"structure_groups": {
"anyOf": [
{
"items": {
"$ref": "#/$defs/BoltzGenStructureGroup"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Groups of chains with a shared visibility level during diffusion. Controls how much structural context each group provides to the model.",
"title": "Structure Groups"
},
"design": {
"anyOf": [
{
"items": {
"$ref": "#/$defs/BoltzGenDesignSpec"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Chains and residues that are designable (sequence will be optimised). If omitted alongside not_design, the protocol default applies.",
"title": "Design"
},
"not_design": {
"anyOf": [
{
"items": {
"$ref": "#/$defs/BoltzGenDesignSpec"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Residues to explicitly lock (exclude from design), even if they fall within a 'design' spec. Takes precedence over entries in 'design'.",
"title": "Not Design"
},
"secondary_structure": {
"anyOf": [
{
"items": {
"$ref": "#/$defs/BoltzGenSecondaryStructureSpec"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Secondary structure constraints (helix, sheet, loop) for residues in this entity.",
"title": "Secondary Structure"
},
"design_insertions": {
"anyOf": [
{
"items": {
"$ref": "#/$defs/BoltzGenDesignInsertion"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Insertion sites where the model may insert additional residues during design.",
"title": "Design Insertions"
},
"fuse": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Chain ID to fuse this entity's chain into. When set, the two chains are treated as a single contiguous chain by the model.",
"title": "Fuse"
},
"use_assembly": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether to load the biological assembly from the structure file rather than the asymmetric unit. Defaults to False. Useful when the functional form is a homo-oligomer.",
"title": "Use Assembly"
},
"reset_res_index": {
"anyOf": [
{
"items": {
"$ref": "#/$defs/BoltzGenChainSelector"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Reset residue numbering to start from 1 for the specified chains. Commonly needed in scaffold redesign workflows where the input structure has non-standard numbering.",
"title": "Reset Res Index"
},
"add_cyclization": {
"anyOf": [
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Add covalent cyclization bonds (e.g. head-to-tail) to specified chains. Each entry is a dict matching the boltzgen YAML cyclization format. Use for cyclic peptide or cyclic protein design.",
"title": "Add Cyclization"
},
"msa": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Multiple sequence alignment (MSA) mode for this entity. 0 = auto-generate MSA (default behaviour), -1 = no MSA (single-sequence mode), or provide a path to a pre-computed MSA file.",
"title": "Msa"
}
},
"title": "BoltzGenFileEntity",
"type": "object"
},
"BoltzGenLigandEntity": {
"additionalProperties": false,
"description": "A small-molecule ligand entity defined by CCD code or SMILES string.",
"properties": {
"id": {
"anyOf": [
{
"type": "string"
},
{
"items": {
"type": "string"
},
"type": "array"
}
],
"description": "Chain ID or list of chain IDs for this ligand entity (e.g. 'L' or ['L1', 'L2']).",
"title": "Id"
},
"ccd": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Chemical Component Dictionary (CCD) code identifying the ligand (e.g. 'ATP', 'HEM'). Use this for standard ligands with a PDB CCD entry. Exactly one of 'ccd' or 'smiles' must be provided.",
"title": "Ccd"
},
"smiles": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "SMILES string defining the ligand chemistry. Use this for non-standard or novel small molecules. Exactly one of 'ccd' or 'smiles' must be provided.",
"title": "Smiles"
},
"binding_types": {
"anyOf": [
{
"type": "string"
},
{
"items": {
"$ref": "#/$defs/BoltzGenBindingType"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Binding-site constraints for this ligand. Pass 'auto' to infer binding sites automatically, or provide explicit per-chain specs.",
"title": "Binding Types"
}
},
"required": [
"id"
],
"title": "BoltzGenLigandEntity",
"type": "object"
},
"BoltzGenPipelineStep": {
"description": "Available pipeline steps.",
"enum": [
"design",
"inverse_folding",
"folding",
"design_folding",
"affinity",
"analysis",
"filtering"
],
"title": "BoltzGenPipelineStep",
"type": "string"
},
"BoltzGenPocketConstraint": {
"additionalProperties": false,
"description": "Constrains a binder chain to be in contact with specified pocket residues on a target chain.",
"properties": {
"binder": {
"description": "Chain ID of the binder (the chain being designed to engage the pocket).",
"title": "Binder",
"type": "string"
},
"contacts": {
"description": "List of pocket residue tokens on the target chain that the binder must contact. Each entry is [chain_id, res_index] (e.g. [['B', 42], ['B', 56]]).",
"items": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array"
},
"title": "Contacts",
"type": "array"
},
"max_distance": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Maximum C\u03b1\u2013C\u03b1 distance (\u00c5) used to define 'contact'. If omitted, the boltzgen default threshold is used.",
"title": "Max Distance"
}
},
"required": [
"binder",
"contacts"
],
"title": "BoltzGenPocketConstraint",
"type": "object"
},
"BoltzGenProteinEntity": {
"additionalProperties": false,
"description": "A protein chain defined by sequence or length, to be placed in the design system.",
"properties": {
"id": {
"anyOf": [
{
"type": "string"
},
{
"items": {
"type": "string"
},
"type": "array"
}
],
"description": "Chain ID or list of chain IDs for this protein entity (e.g. 'A' or ['A', 'B']).",
"title": "Id"
},
"sequence": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
},
{
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "object"
}
],
"description": "Defines the protein chain length and any fixed residues. Pass an integer (e.g. 50) to design a chain of that exact length with all residues free. Pass a range string (e.g. '30..50') to allow variable length. Pass an amino-acid sequence string (e.g. 'MKVL...') to fix the entire sequence. Pass a dict of {residue_index: amino_acid} to fix only specific positions.",
"title": "Sequence"
},
"cyclic": {
"default": false,
"description": "Whether this protein chain is cyclic (head-to-tail peptide bond). When True, boltzgen adds the appropriate cyclization bond during design.",
"title": "Cyclic",
"type": "boolean"
},
"secondary_structure": {
"anyOf": [
{
"items": {
"$ref": "#/$defs/BoltzGenSecondaryStructureSpec"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Secondary structure constraints (helix, sheet, loop) for residues in this chain.",
"title": "Secondary Structure"
},
"binding_types": {
"anyOf": [
{
"type": "string"
},
{
"items": {
"$ref": "#/$defs/BoltzGenBindingType"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Binding-site constraints for this chain. Pass 'auto' to infer binding sites automatically, or provide explicit per-chain specs.",
"title": "Binding Types"
},
"msa": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Multiple sequence alignment (MSA) mode for this entity. 0 = auto-generate MSA (default behaviour), -1 = no MSA (single-sequence mode), or provide a path to a pre-computed MSA file.",
"title": "Msa"
}
},
"required": [
"id",
"sequence"
],
"title": "BoltzGenProteinEntity",
"type": "object"
},
"BoltzGenProtocol": {
"enum": [
"protein-anything",
"peptide-anything",
"protein-small_molecule",
"nanobody-anything"
],
"title": "BoltzGenProtocol",
"type": "string"
},
"BoltzGenSecondaryStructureSpec": {
"additionalProperties": false,
"description": "Constrains secondary structure assignments for residues in a chain during design.",
"properties": {
"chain": {
"anyOf": [
{
"type": "string"
},
{
"items": {
"type": "string"
},
"type": "array"
}
],
"description": "Chain ID or list of chain IDs to apply secondary structure constraints to.",
"title": "Chain"
},
"loop": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
},
{
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Residue positions that should adopt loop (coil) secondary structure.",
"title": "Loop"
},
"helix": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
},
{
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Residue positions that should adopt alpha-helix secondary structure.",
"title": "Helix"
},
"sheet": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
},
{
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Residue positions that should adopt beta-sheet secondary structure.",
"title": "Sheet"
}
},
"required": [
"chain"
],
"title": "BoltzGenSecondaryStructureSpec",
"type": "object"
},
"BoltzGenStructureGroup": {
"additionalProperties": false,
"description": "Groups chains together to control their structural visibility during design.",
"properties": {
"group": {
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
},
{
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array"
}
]
},
"description": "Mapping of chain IDs to residue indices defining the group membership. Use 'all' as the id to target all residues.",
"title": "Group",
"type": "object"
},
"visibility": {
"default": 1,
"description": "Structural visibility level for this group. 0 = fully masked, 1 = partial visibility (default), 2 = fully visible (fixed).",
"maximum": 2,
"minimum": 0,
"title": "Visibility",
"type": "integer"
}
},
"required": [
"group"
],
"title": "BoltzGenStructureGroup",
"type": "object"
},
"BoltzGenTotalLengthConstraint": {
"additionalProperties": false,
"description": "Constrains the total number of designable residues across all chains.",
"properties": {
"min": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Minimum total residue count across all designable chains.",
"title": "Min"
},
"max": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Maximum total residue count across all designable chains.",
"title": "Max"
}
},
"title": "BoltzGenTotalLengthConstraint",
"type": "object"
}
},
"additionalProperties": false,
"description": "Design request for BoltzGen.",
"properties": {
"items": {
"description": "Batch of inputs to process in a single request. Up to 1 design system per request.",
"items": {
"$ref": "#/$defs/BoltzGenDesignRequestItem"
},
"maxItems": 1,
"minItems": 1,
"title": "Items",
"type": "array"
},
"params": {
"$ref": "#/$defs/BoltzGenDesignParams",
"description": "Optional parameters controlling this action (defaults are used when omitted)."
}
},
"required": [
"items"
],
"title": "BoltzGenDesignRequest",
"type": "object"
}
Response — BoltzGenDesignResponse
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
results |
list[BoltzGenDesignResult] | yes | List of individual design results. Each entry contains the CIF structure, quality metrics, and sequence for one design. |
Nested types
BoltzGenDesignResult
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
cif |
string | yes | mmCIF format structure of the designed molecule. Contains the full atomic model produced by boltzgen for this design. | |
metrics |
object | null | no | Per-design quality metrics computed by the analysis step. Common keys include 'plddt' (predicted local distance difference test, 0–100), 'ptm' (predicted TM-score, 0–1), and 'affinity' (predicted binding affinity). Present only when the 'analysis' step was included in the pipeline. | |
sequence |
string | null | no | Amino-acid sequence of the designed chain(s) in one-letter code. Present only when the 'inverse_folding' step was included in the pipeline. |
Raw JSON Schema
{
"$defs": {
"BoltzGenDesignResult": {
"description": "Result for a single design.",
"properties": {
"cif": {
"description": "mmCIF format structure of the designed molecule. Contains the full atomic model produced by boltzgen for this design.",
"title": "Cif",
"type": "string"
},
"metrics": {
"anyOf": [
{
"additionalProperties": {
"type": "number"
},
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Per-design quality metrics computed by the analysis step. Common keys include 'plddt' (predicted local distance difference test, 0\u2013100), 'ptm' (predicted TM-score, 0\u20131), and 'affinity' (predicted binding affinity). Present only when the 'analysis' step was included in the pipeline.",
"title": "Metrics"
},
"sequence": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Amino-acid sequence of the designed chain(s) in one-letter code. Present only when the 'inverse_folding' step was included in the pipeline.",
"title": "Sequence"
}
},
"required": [
"cif"
],
"title": "BoltzGenDesignResult",
"type": "object"
}
},
"description": "Response for design requests.",
"properties": {
"results": {
"description": "List of individual design results. Each entry contains the CIF structure, quality metrics, and sequence for one design.",
"items": {
"$ref": "#/$defs/BoltzGenDesignResult"
},
"title": "Results",
"type": "array"
}
},
"required": [
"results"
],
"title": "BoltzGenDesignResponse",
"type": "object"
}
Usage¶
One-line summary: All-atom generative diffusion model for de novo binder design across proteins, peptides, nanobodies, and small molecule targets using a 7-stage design-to-validation pipeline.
Overview¶
BoltzGen is an all-atom diffusion-based generative model developed at MIT by Hannes Stark, Jeremy Wohlwend, Gabriele Corso, Regina Barzilay, Tommi Jaakkola, and collaborators. It designs proteins and peptides of any modality to bind a wide range of biomolecular targets by unifying structure prediction and generative design into a single model.
Unlike prior methods that decouple backbone generation from sequence design, BoltzGen uses a novel 14-atom geometry-based amino acid representation that operates entirely in continuous coordinate space. This enables joint training on both structure prediction and design tasks, and the model achieves state-of-the-art folding performance while simultaneously generating novel binder candidates.
BoltzGen was experimentally validated in eight wetlab design campaigns across 26 targets, spanning nanobodies, disulfide-bonded peptides, and protein binders. Testing 15 nanobody and protein binder designs against nine novel targets with low similarity to any known bound structure yielded nanomolar binders for 66% of targets.
Key capabilities: - De novo protein binder design (no template required) - Cyclic and disulfide-bonded peptide design - Nanobody/VHH scaffold redesign with CDR loop generation - Protein design for small molecule binding - Flexible design specification language over covalent bonds, structure constraints, binding sites, and secondary structure
Key Parameters: num_designs vs budget¶
These two parameters are frequently confused because both relate to "how many designs you get", but they control different stages of the pipeline:
| Parameter | Stage | What it controls |
|---|---|---|
num_designs |
Step 1 — Design | Size of the candidate pool generated by the diffusion model |
budget |
Step 7 — Filtering | Size of the final output set after diversity-aware ranking |
num_designs is the total number of 3D backbone structures the diffusion model generates. Every subsequent step — inverse folding, structure prediction, affinity scoring, analysis — processes all num_designs candidates. A larger pool gives the filtering step more diversity to select from, but increases runtime proportionally across all steps.
budget only takes effect in the filtering step. After all candidates are scored, the filtering step ranks them using a quality-vs-diversity trade-off (controlled by alpha) and keeps the best budget designs. These are the designs returned in the response. Must be ≤ num_designs.
Example: num_designs=200, budget=10 means the model generates 200 backbones, runs the full pipeline on all 200, then returns the 10 best diverse-quality designs.
If you skip filtering (by setting steps explicitly without filtering), budget is ignored entirely and the response contains all num_designs candidates from whatever the last completed step produced.
Current limits: both are capped at 500 per request.
Architecture¶
The BoltzGen pipeline runs seven sequential stages, each building on the previous:
BoltzGen Pipeline (7 Stages)
===================================================================
Input: Design spec (YAML) Checkpoints
with entities + constraints loaded from HuggingFace
| |
v v
+-------------------+ +-----------------------+
| 1. DESIGN | | boltzgen1_diverse.ckpt|
| Diffusion model |<---| boltzgen1_adherence |
| generates N 3D | +-----------------------+
| backbone candidates|
+--------+-----------+
| N backbone structures
v
+-------------------+ +-----------------------+
| 2. INVERSE FOLDING| | boltzgen1_ifold.ckpt |
| BoltzIF assigns |<---| (ProteinMPNN-class) |
| amino acid seqs | +-----------------------+
| to each backbone |
+--------+-----------+
| N designed sequences + structures
v
+-------------------+ +-----------------------+
| 3. FOLDING | | boltz2_conf_final.ckpt|
| Boltz-2 refolds |<---| (structure prediction)|
| designed sequences | +-----------------------+
| de novo (QC step) |
+--------+-----------+
| N refolded structures
v
+-------------------+
| 4. DESIGN FOLDING |
| Compare designed |
| vs refolded |
| (RMSD, TM-score) |
+--------+-----------+
| structural quality metrics
v
+-------------------+ +-----------------------+
| 5. AFFINITY | | boltz2_aff.ckpt |
| Boltz-2 predicts |<---| (affinity prediction) |
| binding affinity | +-----------------------+
| (ipTM, pAE, etc.) |
+--------+-----------+
| affinity scores
v
+-------------------+
| 6. ANALYSIS |
| Compute H-bonds, |
| salt bridges, |
| delta-SASA, pLDDT,|
| interface metrics |
+--------+-----------+
| aggregate metrics CSV
v
+-------------------+
| 7. FILTERING |
| Hard filters + |
| diversity-aware |
| ranking to select |
| top B designs |
+--------+-----------+
|
v
Output: B ranked designs
(CIF structures + sequences + metrics)
Key components: - BoltzGen diffusion model: SE(3)-equivariant diffusion over all-atom coordinates with two checkpoint variants (diverse and adherence) that trade off exploration vs. constraint satisfaction - BoltzIF inverse folding: Sequence recovery model comparable to ProteinMPNN/SolubleMPNN, predicting amino acid sequences from 3D backbone geometry - Boltz-2 folding: State-of-the-art biomolecular structure prediction for refolding validation (self-consistency check) - Boltz-2 affinity: Binding affinity predictor approaching FEP accuracy at orders of magnitude faster speed
Model checkpoints (from HuggingFace boltzgen/boltzgen-1):
| Checkpoint | File | Role |
|---|---|---|
| Design (diverse) | boltzgen1_diverse.ckpt |
Backbone generation favoring diversity |
| Design (adherence) | boltzgen1_adherence.ckpt |
Backbone generation favoring constraint adherence |
| Inverse folding | boltzgen1_ifold.ckpt |
Sequence design from backbone |
| Folding | boltz2_conf_final.ckpt |
Structure prediction for QC |
| Affinity | boltz2_aff.ckpt |
Binding affinity prediction |
| Molecule dict | mols.zip (from boltzgen/inference-data) |
Small molecule reference data |
Capabilities & Limitations¶
CAN be used for: - Designing protein binders against protein, peptide, nucleic acid, and small molecule targets - Generating cyclic peptides with disulfide or head-to-tail cyclization - Redesigning nanobody CDR loops while preserving framework scaffold - De novo enzyme pocket design for small molecule substrates - Specifying secondary structure, binding sites, and structural constraints
CANNOT be used for: - Membrane protein design (model trained on soluble complexes) - Multi-state design or allosteric mechanisms - Post-translational modifications beyond disulfide bonds - Sequences longer than 2048 residues (context limit) - Guarantee of experimental success (computational predictions require wet-lab validation) - Real-time inference (pipeline takes 10-60 minutes depending on design parameters)
Other considerations: - Generative outputs are non-deterministic; repeated runs produce different designs - Quality depends heavily on input target structure quality - Small molecule targets require valid CCD codes or SMILES strings - Nanobody scaffold redesign requires careful CDR region specification (residue indices must match the PDB numbering) - Water molecules in input CIF files should be stripped to avoid SASA calculation failures in the analysis step
Protocols¶
BoltzGen supports four design protocols, each targeting a different binder modality:
| Protocol | Slug | Description | Typical Use |
|---|---|---|---|
| Protein-Anything | protein-anything |
De novo protein binder design | Design a new protein (80-200 residues) to bind any target |
| Peptide-Anything | peptide-anything |
Cyclic or linear peptide design | Design short peptides (8-30 residues), optionally cyclic, to bind protein targets |
| Protein-Small Molecule | protein-small_molecule |
Protein design for small molecule binding | Design a protein pocket to accommodate a given ligand (CCD or SMILES) |
| Nanobody-Anything | nanobody-anything |
Nanobody/VHH scaffold redesign | Redesign CDR loops of a nanobody scaffold while keeping framework regions fixed |
Each protocol adjusts internal pipeline parameters (diffusion batch size, step scale, noise scale, filtering thresholds) to suit the target modality.
Design specification is provided as a structured request containing: - Entities: Proteins (de novo or fixed sequence), ligands (CCD or SMILES), or file-based structures (CIF/PDB) with include/exclude chain selectors - Constraints: Covalent bonds (cyclization, disulfides), contact constraints, pocket constraints, total length bounds - Design masks: Specify which residues of a scaffold to redesign (CDR regions) vs. keep fixed (framework) - Structure groups: Control structural flexibility/visibility of different regions - Secondary structure: Enforce helix, sheet, or loop at specified positions
Usage Examples¶
Protein-small molecule design (simplest case)¶
from models.boltzgen.schema import (
BoltzGenDesignRequest,
BoltzGenDesignParams,
BoltzGenDesignRequestItem,
BoltzGenEntity,
BoltzGenLigandEntity,
BoltzGenProteinEntity,
BoltzGenProtocol,
)
request = BoltzGenDesignRequest(
params=BoltzGenDesignParams(
protocol=BoltzGenProtocol.PROTEIN_SMALL_MOLECULE,
num_designs=3,
budget=2,
),
items=[
BoltzGenDesignRequestItem(
entities=[
BoltzGenEntity(
protein=BoltzGenProteinEntity(id="A", sequence="140..180")
),
BoltzGenEntity(
ligand=BoltzGenLigandEntity(id="B", ccd="TSA")
),
],
)
],
)
De novo protein binder design¶
from models.boltzgen.schema import (
BoltzGenDesignRequest,
BoltzGenDesignParams,
BoltzGenDesignRequestItem,
BoltzGenEntity,
BoltzGenProteinEntity,
BoltzGenProtocol,
)
request = BoltzGenDesignRequest(
params=BoltzGenDesignParams(
protocol=BoltzGenProtocol.PROTEIN_ANYTHING,
num_designs=200,
budget=50,
),
items=[
BoltzGenDesignRequestItem(
entities=[
BoltzGenEntity(
protein=BoltzGenProteinEntity(id="A", sequence="80..120")
),
BoltzGenEntity(
protein=BoltzGenProteinEntity(
id="B", sequence="MKLLVVVQVWHHHHHLLLL"
)
),
],
)
],
)
Cyclic peptide design¶
from models.boltzgen.schema import (
BoltzGenDesignRequest,
BoltzGenDesignParams,
BoltzGenDesignRequestItem,
BoltzGenEntity,
BoltzGenProteinEntity,
BoltzGenProtocol,
)
request = BoltzGenDesignRequest(
params=BoltzGenDesignParams(
protocol=BoltzGenProtocol.PEPTIDE_ANYTHING,
num_designs=5,
budget=3,
),
items=[
BoltzGenDesignRequestItem(
entities=[
BoltzGenEntity(
protein=BoltzGenProteinEntity(
id="A", sequence="8..18", cyclic=True
)
),
BoltzGenEntity(
protein=BoltzGenProteinEntity(
id="B", sequence="MKLLVVVQVW"
)
),
],
)
],
)
Testing¶
Tests are split into three tiers with different speed/coverage tradeoffs.
Tier 1 — Unit tests (instant, no GPU)¶
pytest models/boltzgen/test.py -k "not integration and not deployment and not slow" -v
Tests request/response schema validation and pure pipeline helper functions (no subprocess calls).
Tier 2 — Integration tests (<5 min on warm container)¶
pytest models/boltzgen/test.py -m integration --no-cov -v -s
One test:
| Test | Protocol | Steps | What it validates |
|---|---|---|---|
generate-programmatic |
protein-small_molecule | design only | CIF output produced inline in the response |
This runs on every PR via CI. Cost: ~2-3 min GPU per run.
Tier 3 — Slow tests (30-60 min, run before releases)¶
pytest models/boltzgen/test.py -m slow --no-cov -v -s
Two tests that exercise the complete 7-step pipeline at minimum campaign size
(num_designs=3, budget=2). They validate CIF output, sequence extraction, and
metrics for every pipeline step including filtering.
| Test | Protocol | Steps | Target |
|---|---|---|---|
chorismite |
protein-small_molecule | all 7 (design → inv_fold → fold → design_fold → affinity → analysis → filter) | TSA ligand (chorismate synthase) |
nanobody_7eow |
nanobody-anything | 5 (design → inv_fold → fold → analysis → filter) | 7eow CDR loop redesign |
The chorismite test covers protein-small_molecule including affinity scoring.
The nanobody test covers file entity handling, chain selectors, CDR design masks,
and both upstream sed patches applied at image build time.
Run these before deploying significant changes to the pipeline or model weights.
The remaining validated fixtures (cyclic_hiv_9d3d, streptavidin_cyclic,
hard_target_1g13nano) are in R2 and can be added back via fixture.py if needed.
Verification Status¶
Status: VERIFIED (2026-02-17) -- All 5 test cases pass across all 4 design protocols. 2 cases enabled in CI; 3 additional cases validated during initial development.
Use Cases¶
For detailed biological use cases (drug discovery, nanobody engineering, cyclic peptide design, enzyme design, antimicrobial peptide neutralization), see BIOLOGY.md.
Confidence Metrics¶
BoltzGen returns a metrics dictionary per design. Key metrics for evaluating design quality:
| Metric | Range | Interpretation |
|---|---|---|
| pLDDT | 0-100 | Per-residue local confidence from Boltz-2 refolding. >70: confident backbone; >90: high-confidence sidechain |
| ipTM | 0-1 | Interface predicted TM-score from Boltz-2 affinity. >0.5: likely correct interface |
| scRMSD | 0+ (angstroms) | Self-consistency RMSD: designed vs. refolded structure. <2.0: good self-consistency |
| delta-SASA | varies | Change in solvent-accessible surface area upon complex formation. More negative = larger buried interface |
| H-bonds | integer | Number of hydrogen bonds at the interface |
| Salt bridges | integer | Number of salt bridges at the interface |
Note: Exact metrics available depend on which pipeline stages are run. The full 7-stage pipeline produces all metrics; running a subset of stages produces a subset of metrics.
Bug Fixes (Upstream Patches)¶
Two sed patches are applied during container image build to fix upstream bugs in the BoltzGen codebase (pinned commit 617e549). Both are applied in app.py with grep-based verification that fails the build if the patch didn't apply. Neither has been fixed upstream as of the pinned commit (617e549) or current main.
Patch 1: _pdbx_poly_seq_scheme IndexError (mmcif.py:441)¶
Root cause: In add_poly_seq_scheme_cols(), the CIF writer populates the _pdbx_poly_seq_scheme table by iterating over each chain's residues with enumerate(residues, 1) and indexing into label_seq_dict[entity_id][seq_id - 1]. The label_seq_dict is built earlier (line 92-165) and only stores the residue index list for the first chain encountered per entity_id (guarded by if entity_id not in label_seq_dict.keys()). When two chains share an entity (identical sequence) but the second chain has more residues than the first, seq_id - 1 exceeds the length of the stored list, raising IndexError.
Trigger: Any design spec where boltzgen assigns the same entity_id to chains with differing residue counts after filtering — e.g., a homodimer where one chain is partially cropped via include/exclude selectors.
Fix: Replace the dict lookup with the residue's own index, which is always valid:
# Before (line 441):
str(label_seq_dict[entity_id][seq_id - 1])
# After:
str(res["res_idx"].item() + 1)
This is safe because res["res_idx"] is the ground-truth residue index stored in the structure tensor. The label_seq_dict lookup was an unnecessary indirection that assumed 1:1 correspondence between enumerate order and the stored list length.
File: src/boltzgen/data/write/mmcif.py, function add_poly_seq_scheme_cols
Patch 2: Exclude mask variable name typo (schema.py:1798)¶
Root cause: The design spec parser builds two separate masks for chain filtering:
- include_mask (initialized to 0, set to 1 for included residues, lines 1708-1731)
- exclude_mask (initialized to 1, set to 0 for excluded residues, lines 1780-1801)
These are combined at line 1802: include_mask = (include_mask * exclude_mask).astype(bool).
In the exclude handler (line 1797-1798), the whole-chain exclude path writes to the wrong variable:
if "res_index" not in chain:
include_mask[c_start:c_end] = 0 # BUG: should be exclude_mask
This zeroes the include mask directly, which permanently removes those residues from the include set even if they were explicitly included. The per-residue path (line 1800-1801) correctly uses exclude_mask[indices] = 0, confirming this is a copy-paste error from the include handler.
Trigger: Any design spec that uses exclude with a whole-chain selector (no res_index). The resulting design_mask becomes all-False, producing designs with no designable residues.
Fix:
# Before (line 1798):
include_mask[c_start:c_end] = 0
# After:
exclude_mask[c_start:c_end] = 0
File: src/boltzgen/data/parse/schema.py, function that builds the chain filter mask
Related: Referenced as boltzgen issue #48; upstream fix-48 branch exists but has not been merged.
Upstream PR status¶
Both bugs are confirmed present in the pinned commit and the current main branch. Patch 2 has an associated issue (#48) and unmerged branch (fix-48). Patch 1 has no upstream issue. Both fixes are minimal, correct, and would be good candidates for an upstream PR — particularly Patch 2 which has a silent failure mode (all-False design mask) that produces plausible but meaningless outputs without any error. We should submit a PR combining both fixes once we've verified them against the latest upstream commit.
Design Spec Data Flow¶
This section explains how API request fields map through the codebase to the boltzgen YAML spec.
Overview¶
The data flow is:
API Request (Pydantic schema)
→ BoltzGenModel._convert_to_yaml_spec() (app.py)
→ helper functions (helpers.py)
→ YAML dict written to design_spec.yaml
→ boltzgen configure (reads YAML, writes per-step configs)
→ boltzgen execute --steps <step> (runs each step using those configs)
Chain Selectors: include / exclude¶
Chain selectors control cropping — which chains and residues from an input structure file are loaded into the design system. Boltzgen performs the cropping internally when it reads the YAML spec; we do not crop structures ourselves.
| Field | Purpose | Example |
|---|---|---|
include |
Keep only these chains/residues | include: [{id: "A"}, {id: "B", res_index: "26..34"}] |
exclude |
Remove these chains/residues | exclude: [{id: "C"}] — drop chain C |
Schema class: BoltzGenChainSelector (schema.py) with fields id (chain ID) and optional res_index.
Conversion (helpers.py:convert_chain_selectors):
# API input
include=[ChainSelector(id="A"), ChainSelector(id="B", res_index="26..34")]
# YAML output
include:
- chain: {id: A}
- chain: {id: B, res_index: "26..34"}
Design Masks: design / not_design¶
Design masks mark which residues are designable (sequence will be optimised by the diffusion model) vs fixed (held constant). This is distinct from cropping — a chain can be included but not designed.
| Field | Purpose | Example |
|---|---|---|
design |
Mark residues as designable | design: [{chain: "B", res_index: "26..34,52..59"}] |
not_design |
Lock residues (exclude from design) | not_design: [{chain: "B", res_index: "1..25"}] |
Schema class: BoltzGenDesignSpec (schema.py) with fields chain and optional res_index.
Conversion (helpers.py:convert_design_specs):
# API input
design=[DesignSpec(chain="B", res_index="26..34,52..59,98..118")]
# YAML output
design:
- chain: {id: B}
res_index: "26..34,52..59,98..118"
The Implicit Target Mechanism¶
Boltzgen determines what the designed chain binds against using an implicit convention: any chain that is included but not marked as designable is treated as the binding target. There is no explicit target field.
Example — nanobody redesigning CDR loops against a protein target:
# API request
entities:
- file:
cif: "<7EOW structure>"
include:
- {id: "A"} # target protein — included but NOT designed
- {id: "B", res_index: "1..120"} # nanobody scaffold
design:
- {chain: "B", res_index: "26..34,52..59,98..118"} # CDR loops only
Here chain A is the implicit target because it's included but has no design entry. The protocol (nanobody-anything) tells boltzgen the relationship type — the model generates CDR loop structures that bind chain A.
For de novo design (no file entity), the target is typically a separate protein or ligand entity, and the designed chain is specified as a protein entity with a sequence length rather than a fixed sequence.
res_index Format¶
All res_index fields across the schema use the same format:
- 1-based indexing (residue 1 is the first residue)
- Range syntax:
N..M(e.g.,"26..34"= residues 26 through 34 inclusive) - Open ranges:
"..10"(up to 10),"20.."(from 20 onward) - Comma-separated:
"26..34,52..59,98..118"(multiple ranges) - Single integer:
5(just residue 5) - Keyword:
"all"(all residues)
Validated by _ResIndexValidatorMixin in schema.py using the regex ^(?:all|(?:\d+\.\.\d+|\.\.\d+|\d+\.\.|\d+)(?:,(?:\d+\.\.\d+|\.\.\d+|\d+\.\.|\d+))*)$.
reset_res_index¶
When a structure is loaded from a CIF/PDB file, residue numbering often has gaps or starts at arbitrary positions (e.g., chain B residues numbered 26–118 after extraction from a larger complex). Boltzgen's diffusion model uses positional encodings internally that work best with clean 0-based sequential numbering. reset_res_index tells boltzgen to renumber specified chains from 0 before running the model.
Why it matters: If you crop a scaffold to residues 26–34 of chain B but don't reset, boltzgen sees a "chain starting at position 26" which misaligns with the positional encoding the model was trained on.
Where it appears: Can be set at two levels:
- Top-level on BoltzGenDesignRequestItem.reset_res_index — applies globally
- Per-file on BoltzGenFileEntity.reset_res_index — scoped to one entity
Resolution heuristic (app.py:_resolve_reset_res_index):
The function checks three sources in priority order:
- Explicit top-level (
item.reset_res_index) — user directly specifies chains to renumber. Highest priority. - Explicit per-file (
entity.file.reset_res_index) — same thing but scoped to a file entity. - Auto-infer from design specs — if there's a single file entity with
designspecs, the function extracts the chain IDs being designed and resets those. The logic: if you're redesigning chains B and C of a scaffold, those chains almost certainly need renumbering because they came from a cropped/extracted structure. This covers the most common scaffold redesign workflow without requiring users to setreset_res_indexexplicitly.
YAML output:
reset_res_index:
- chain: {id: B}
Full YAML Example (Nanobody Redesign)¶
Putting it all together, here's what a nanobody CDR redesign request produces:
API Request Generated YAML
───────────────────────── ──────────────────────────
entities: entities:
- file: - file:
cif: "<7EOW CIF content>" path: tmp12345.cif
include: include:
- {id: "A"} - chain: {id: A}
- {id: "B"} - chain: {id: B}
design: design:
- chain: "B" - chain: {id: B}
res_index: "26..34,52..59" res_index: "26..34,52..59"
params: (passed to boltzgen configure)
protocol: nanobody-anything --protocol nanobody-anything
num_designs: 100 --num_designs 100
budget: 10 --budget 10
reset_res_index: ← auto-inferred
- chain: {id: B} from design specs
Chain A = implicit target (included, not designed).
Chain B = nanobody scaffold, CDR loops at 26–34 and 52–59 are designable, rest is fixed.
reset_res_index is auto-inferred because there's a single file entity with design specs on chain B.
Constraints¶
Constraints are structural requirements enforced during diffusion sampling:
| Constraint | Use case | YAML format |
|---|---|---|
bond |
Covalent bonds (disulfides, cyclization) | bond: {atom1: [A, 1, SG], atom2: [A, 8, SG]} |
contact |
Distance constraints between residues | contact: {token1: [A, 5], token2: [B, 42], max_distance: 8.0} |
pocket |
Binder must contact pocket residues | pocket: {binder: A, contacts: [[B, 91], [B, 128]]} |
total_len |
Bound total designable residues | total_len: {min: 80, max: 200} |
Code Organization¶
| File | Purpose |
|---|---|
app.py |
Modal app definition, container image build, BoltzGenModel class with generate() and YAML conversion |
schema.py |
Pydantic request/response models, validation, type aliases |
pipeline.py |
BoltzGenPipelineMixin — pipeline orchestration, result reading, subprocess execution |
helpers.py |
Pure utility functions — YAML converters, constants, CIF sequence extraction |
config.py |
Model family configuration |
download.py |
Artifact download definitions (HuggingFace checkpoints) |
test.py |
Unit, integration, and slow tests |
fixture.py |
Test fixture management |
Architecture & training¶
Architecture¶
Model Type & Innovation¶
BoltzGen is a diffusion-based generative model for de novo biomolecular binder design. Unlike structure prediction models (AlphaFold, Boltz) that predict a single native structure from sequence, BoltzGen is a design model that generates novel protein and peptide binders by sampling from the Boltzmann distribution of structures conditioned on a target.
The key architectural innovation is a unified pipeline that jointly generates backbone geometry and amino acid identity using a novel 14-atom geometry-based amino acid representation operating entirely in continuous coordinate space. This eliminates the traditional decoupling of backbone generation from sequence design, enabling joint training on both structure prediction and design tasks.
BoltzGen is built on the Boltz-2 codebase for its folding and affinity prediction stages, but adds a new diffusion model (BoltzGen1) specifically trained for generative design. The model was experimentally validated across eight wet-lab campaigns spanning 26 targets, with nanomolar binders found for 66% of novel targets.
Parameters & Layers¶
BoltzGen orchestrates five distinct neural network checkpoints in a seven-stage pipeline:
| Checkpoint | File | Role | Source |
|---|---|---|---|
| Design (diverse) | boltzgen1_diverse.ckpt |
Backbone generation favoring structural diversity | boltzgen/boltzgen-1 |
| Design (adherence) | boltzgen1_adherence.ckpt |
Backbone generation favoring constraint adherence | boltzgen/boltzgen-1 |
| Inverse folding | boltzgen1_ifold.ckpt |
Sequence design from backbone (ProteinMPNN-class) | boltzgen/boltzgen-1 |
| Folding | boltz2_conf_final.ckpt |
Structure prediction for self-consistency QC | boltzgen/boltzgen-1 |
| Affinity | boltz2_aff.ckpt |
Binding affinity prediction | boltzgen/boltzgen-1 |
| Property | Details |
|---|---|
| Architecture | SE(3)-equivariant diffusion (design) + transformer trunk (folding/affinity) |
| Amino acid representation | 14-atom geometry-based continuous coordinates |
| Input modalities | Protein sequence, SMILES, CIF/PDB structures |
| Output modalities | All-atom 3D structure (mmCIF) + designed sequence |
| Max sequence length | 2048 residues |
| Molecule dictionary | mols.zip from boltzgen/inference-data (CCD reference data) |
Training Data¶
| Property | Details |
|---|---|
| Primary dataset | PDB (Protein Data Bank) |
| Design training | Structure prediction data + generative design objectives |
| Inverse folding | Sequence recovery on PDB structures |
| Folding (Boltz-2) | PDB complexes with temporal cutoff |
| Affinity (Boltz-2) | Experimental IC50/Kd from ChEMBL and PDBBind |
| Experimental validation | 8 wet-lab campaigns, 26 targets, nanobodies + peptides + protein binders |
Known biases: Training is dominated by soluble globular proteins. Membrane proteins, intrinsically disordered regions, and non-standard post-translational modifications are under-represented. The model performs best for targets with structural homologs in the PDB.
Loss Function & Objective¶
Design stage: Denoising score matching loss -- the diffusion model learns to predict the noise added to ground-truth atomic coordinates. Two checkpoint variants trade off exploration vs. constraint satisfaction: - Diverse: Optimized for structural diversity in generated candidates - Adherence: Optimized for satisfying specified constraints (binding sites, secondary structure)
Inverse folding stage: Cross-entropy loss on amino acid identity conditioned on backbone geometry.
Folding stage (Boltz-2): Standard structure prediction loss for self-consistency refolding.
Affinity stage (Boltz-2): Combined regression loss on log10(IC50) and binary binder/non-binder classification loss.
Tokenization / Input Processing¶
- Proteins: Single-letter amino acid sequences or length range specifications (e.g.,
"80..120"for de novo design). Fixed sequences for target chains, range expressions for designed chains. - Ligands: SMILES strings or CCD (Chemical Component Dictionary) codes. Internally converted to molecular graphs using the molecule dictionary.
- Structures: CIF or PDB files for scaffold redesign and target specification. Chains selected via include/exclude selectors with optional residue index filtering.
- Design masks: Residue-level control over which positions are redesigned vs. fixed. Specified via
designandnot_designfields with chain and residue index selectors. - Constraints: Bond constraints (cyclization, disulfides), contact constraints (distance limits), pocket constraints (binding site specification), and total length constraints.
- Secondary structure: Per-residue enforcement of helix, sheet, or loop at specified positions.
The request is converted to a YAML specification matching the BoltzGen CLI format, which drives the seven-stage subprocess pipeline.
Performance & Benchmarks¶
Published Benchmarks¶
Experimental Validation (Stark et al. bioRxiv 2025)¶
BoltzGen was validated in eight wet-lab design campaigns across 26 targets:
| Metric | Value | Notes |
|---|---|---|
| Targets with nanomolar binders | 66% (6/9 novel targets) | 15 nanobody and protein binder designs tested |
| Target types | Nanobodies, disulfide peptides, protein binders | Across diverse modalities |
| Campaigns | 8 wet-lab campaigns | Including yeast display, phage display |
Self-Consistency Metrics¶
Self-consistency measures whether designed structures can be recovered by refolding the designed sequence with Boltz-2 (an independent structure predictor). This is the standard quality metric for generative structure models.
| Metric | Approximate Range | Notes |
|---|---|---|
| scRMSD (design vs. refolded) | Designs passing filtering typically < 2.0 A | Lower is better; threshold set by refolding_rmsd_threshold |
| scTM (design vs. refolded) | Passing designs typically > 0.7 | Higher is better |
| ipTM (Boltz-2 affinity) | Varies by protocol and target | Interface quality of designed complex |
| pLDDT | Varies; higher = more confident local structure | Per-residue confidence from Boltz-2 refolding |
The pipeline's filtering stage (stage 7) applies hard filters on these self-consistency metrics plus diversity-aware ranking to select the top budget designs from num_designs candidates.
BioLM Test Suite Metrics¶
The BioLM implementation validates the following properties on each design:
| Metric | Criterion | Notes |
|---|---|---|
| CIF parseability | Valid mmCIF (gemmi) | Structure must be parseable |
| Sequence validity | All standard amino acids (ACDEFGHIKLMNPQRSTVWY) | No non-standard residues in designed chain |
| Metrics populated | Non-empty dict with numeric values | Pipeline produces quality metrics |
| Design diversity | >= 2 unique sequences out of 3 designs | Generative model produces diverse candidates |
BioLM Verification Results¶
Five test cases validated across all four BoltzGen protocols during initial development (2026-02-17):
| Test Case | Protocol | Target | Status |
|---|---|---|---|
protein_small_molecule_chorismite |
protein-small_molecule | TSA ligand | PASS |
nanobody_7eow_simple |
nanobody-anything | PDB 7EOW | PASS |
cyclic_hiv_9d3d |
peptide-anything | PDB 9D3D | PASS |
streptavidin_cyclic |
peptide-anything | Streptavidin 1MK5 | PASS |
hard_target_1g13nano |
nanobody-anything | PDB 1G13 | PASS |
Two test cases are enabled in CI (protein_small_molecule_chorismite, nanobody_7eow_simple). The remaining three were validated but are disabled to reduce GPU cost (~20-40 minutes of A100 time each).
Comparison to Alternatives¶
| Model | Type | All-Atom | Multi-Molecule | Joint Seq+Struct | When to Prefer |
|---|---|---|---|---|---|
| BoltzGen | Generative (design) | Yes | Yes | Yes | De novo binder design with end-to-end pipeline |
| RFdiffusion3 | Generative (design) | Yes | Yes | No (backbone only, needs MPNN) | Unconditional design, motif scaffolding, symmetric design |
| ProteinMPNN | Inverse folding | N/A | N/A | N/A (seq only) | Sequence design for a given backbone |
| Boltz-2 | Structure prediction | Yes | Yes | No | Predicting structure of known sequences; affinity ranking |
| AlphaFold3 | Structure prediction | Yes | Yes | No | Structure prediction; not design |
Error Bars & Confidence¶
BoltzGen is a stochastic generative model. Each run produces different designs:
- Inter-run variance: Designs from different runs have distinct sequences and structures by design. The
num_designsparameter controls how many candidates are generated, andbudgetcontrols how many survive diversity-aware filtering. - Self-consistency variance: scRMSD and scTM scores vary per design. The filtering stage removes low-quality designs (high scRMSD, low affinity).
- Protocol-dependent quality: Different protocols (protein-anything, peptide-anything, nanobody-anything, protein-small_molecule) use different internal parameters (diffusion batch size, step scale, noise scale) tuned for each modality.
- Alpha parameter: Controls the trade-off between quality (alpha=0.0) and diversity (alpha=1.0) in the final ranking step.
Strengths & Limitations¶
Pros¶
- End-to-end binder design pipeline: structure generation, sequence design, refolding validation, affinity prediction, and diversity-aware filtering in a single workflow
- Joint structure+sequence generation via 14-atom continuous representation -- no separate backbone/sequence design steps needed
- Experimentally validated: nanomolar binders for 66% of novel targets across multiple modalities
- Supports diverse design modalities: de novo proteins, cyclic peptides, nanobody CDR redesign, small molecule pocket design
- Rich constraint language: binding sites, secondary structure, cyclization, disulfide bonds, total length bounds
- Built on Boltz-2 for state-of-the-art refolding and affinity evaluation
Cons¶
- Long inference time: full pipeline takes 10-60 minutes per design campaign on A100 40GB
- Batch size limited to 1 design specification per request
- Maximum sequence length of 2048 residues
- Requires A100 40GB GPU with 64GB system RAM
- No membrane protein support (trained on soluble complexes)
- No multi-state design or allosteric mechanisms
- Computational predictions require wet-lab validation -- no guarantee of experimental success
Known Failure Modes¶
- Water molecules in CIF: Water atoms in input structure files cause SASA calculation failures in the analysis stage. Input structures should be stripped of water molecules.
- Incorrect CDR region indices: Nanobody scaffold redesign requires precise residue index specification matching the PDB numbering. Incorrect indices produce meaningless designs.
- Short peptide designs: Very short peptides (< 8 residues) may not have sufficient structural context for reliable design.
- Function timeout: Each request runs under a 24-hour Modal function timeout. Very large
num_designsvalues with complex targets can approach this limit. - CIF writer IndexError: Upstream bug when chains are filtered (patched in BioLM build -- see Bug Fixes in README.md).
- Design mask all-False: Upstream bug in exclude handler (patched in BioLM build -- see Bug Fixes in README.md).
Implementation Details¶
Inference Pipeline¶
Request (BoltzGenDesignRequest)
|-- 1. Validate request (Pydantic schema)
|-- 2. Convert to YAML specification
| |-- Map entities (protein, ligand, file) to boltzgen format
| |-- Write structure files (CIF/PDB) to temp directory
| |-- Set design masks, constraints, secondary structure
| \-- Configure protocol-specific parameters
|-- 3. Build CLI command (python -m boltzgen)
| |-- Set protocol, num_designs, budget
| |-- Configure checkpoint paths (diverse/adherence, ifold, folding, affinity)
| |-- Set pipeline steps (7-stage default or user-specified subset)
| \-- Set diffusion parameters (step_scale, noise_scale, batch_size)
|-- 4. Execute subprocess (within the 24-hour function timeout)
|-- 5. Process output directory
| |-- Find top-ranked CIF files (sorted by pipeline scoring)
| |-- Extract amino acid sequence from each CIF (gemmi)
| |-- Parse metrics CSV for quality scores
| |-- Optionally create base64-encoded zip of full output
| \-- Build BoltzGenDesignResult per design
\-- 6. Return BoltzGenDesignResponse
Memory & Compute Profile¶
| Input | GPU | Memory (system) | Typical Time | Notes |
|---|---|---|---|---|
| Simple protein-ligand (num_designs=3, budget=2) | A100 40GB | 64 GB | ~10-20 min | Minimal test configuration |
| Nanobody redesign (num_designs=3, budget=2) | A100 40GB | 64 GB | ~20-40 min | File entity + scaffold processing |
| Production campaign (num_designs=500, budget=100) | A100 40GB | 64 GB | ~2-8 hours | Full design campaign (max per-request limit) |
| Cyclic peptide (num_designs=3, budget=2) | A100 40GB | 64 GB | ~15-30 min | With cyclization constraints |
The BioLM deployment allocates 8 CPU cores and 64 GB system memory alongside the A100 40GB GPU. 24-hour maximum timeout accommodates large design campaigns.
Determinism & Reproducibility¶
- Inherently stochastic: BoltzGen is a generative model -- different runs produce different designs by design.
- No fixed seed: The pipeline does not expose a global seed parameter. Stochasticity comes from the diffusion sampling process.
- Test validation: Tests validate structural properties (CIF parseability, valid sequences, metric presence, design diversity) rather than exact output comparison.
- Diversity guarantee: The filtering stage explicitly optimizes for sequence diversity among high-quality candidates.
Caching Behavior¶
- Response caching: Due to the stochastic nature of generative design, cache hits are meaningful only for identical requests (same entities, same parameters).
- R2 caching: Model checkpoints cached in R2 (
biolm-hub/model-weights/models/boltzgen/v1/). HuggingFace fallback for first container builds. - Memory snapshots:
enable_memory_snapshot=Truefor faster cold starts. GPU snapshots disabled (enable_gpu_snapshot: False) due to the large combined model size. - Molecule dictionary:
mols.zipextracted once during container setup and persisted for the container lifetime.
Versions & Changelog¶
| Version | Date | Changes |
|---|---|---|
| v1 | 2026-02 | Initial BoltzGen implementation -- 7-stage pipeline, 4 protocols, 5 validated test cases |
Biology¶
Molecule Coverage¶
Primary Molecule Type(s)¶
BoltzGen is designed for de novo biomolecular binder design -- generating novel proteins and peptides that bind specified targets. It handles four entity types as design targets:
- Proteins: Amino acid sequences from all domains of life. The model designs binder proteins (80-200 residues typically) against protein targets. Works best for soluble globular proteins with well-defined binding surfaces. Supports fixed-sequence targets provided as CIF/PDB structures or as amino acid sequences.
- Small molecules: Drug-like compounds specified as SMILES strings or CCD codes. BoltzGen designs protein pockets to accommodate specific ligands, enabling de novo enzyme and receptor design.
- DNA/RNA: Nucleotide sequences supported as target entities within file-based structure inputs. Not a primary design modality but handled through the Boltz-2 folding and affinity components.
- Complexes: Multi-chain assemblies provided as CIF/PDB files. Scaffold redesign (e.g., nanobody CDR loops) operates on existing complex structures, preserving framework regions while redesigning specified positions.
The model operates in continuous 3D coordinate space using a 14-atom geometry-based amino acid representation. This means it generates physically plausible all-atom structures rather than abstract sequence tokens.
Quality depends on target structure quality: When targets are provided as CIF/PDB files (scaffold redesign, nanobody CDR design), the accuracy of the input structure directly affects design quality. Low-resolution or poorly refined input structures lead to suboptimal designs.
Cross-Applicability¶
| Molecule Type | Applicability | Evidence | Caveats |
|---|---|---|---|
| Antibodies (full IgG) | Low | Not tested; model targets nanobody/VHH fragments | Full IgG is too large and complex; use nanobody protocol instead |
| Nanobodies (VHH) | High | Core protocol; experimentally validated with nanomolar binders | Requires precise CDR residue index specification matching PDB numbering |
| Enzymes | High | protein-small_molecule protocol designs active site pockets | Does not model catalytic mechanisms or transition states explicitly |
| Cyclic peptides | High | Core protocol; supports head-to-tail cyclization and disulfide bonds | Best for 8-30 residues; very short peptides lack structural context |
| Linear peptides | High | Supported via peptide-anything protocol without cyclization | Consider cyclic variants for improved proteolytic stability |
| Antimicrobial peptides | Validated | Paper demonstrated binders neutralizing melittin, indolicidin, protegrin | Specific to sequestration (binding), not direct antimicrobial activity |
| Membrane protein targets | Low | Model trained on soluble complexes | Under-represented in training data; no lipid bilayer modeling |
| Intrinsically disordered targets | Low-Moderate | Paper showed binders for disordered protein regions | Generates single conformations; disordered targets may adopt unexpected bound conformations |
| DNA/RNA-binding proteins | Moderate | Boltz-2 components handle nucleic acids | Not a primary design modality for BoltzGen |
Biological Problems Addressed¶
De Novo Protein Binder Design¶
Biological question: Can we computationally design a novel protein that binds a specific target with high affinity?
Designing proteins that bind desired targets is fundamental to drug development, diagnostics, and research tools. Traditionally, binder discovery relies on experimental screening methods such as phage display, yeast display, or directed evolution -- approaches that are expensive, time-consuming, and limited to accessible target surfaces.
Computational binder design bypasses these limitations by generating candidate binders in silico. However, prior computational methods typically decouple backbone generation from sequence design, requiring separate tools for each step (e.g., RFdiffusion for backbone, ProteinMPNN for sequence). BoltzGen unifies this into a single end-to-end pipeline.
How BoltzGen addresses this: 1. The diffusion model generates diverse backbone geometries complementary to the target surface 2. The inverse folding model assigns amino acid sequences to each backbone 3. Boltz-2 refolds each designed sequence to verify structural self-consistency 4. Boltz-2 predicts binding affinity for each design 5. Analysis computes interface quality metrics (H-bonds, salt bridges, SASA) 6. Diversity-aware filtering selects the top candidates
Output interpretation: Each design includes a CIF structure, designed sequence, and metrics dictionary. Key metrics to evaluate: scRMSD (lower = better self-consistency), ipTM (higher = better predicted interface quality), and pLDDT (higher = more confident local structure).
Practical considerations: The pipeline generates many candidates (default 10,000) and filters to a smaller set (default 100). Top candidates should be further validated computationally (molecular dynamics, additional structure prediction) and experimentally (binding assays, display technologies) before therapeutic or industrial use.
Nanobody CDR Redesign¶
Biological question: Can we redesign the binding loops of a nanobody scaffold to recognize a new target?
Nanobodies (VHH fragments, ~15 kDa) are the smallest naturally occurring antigen-binding fragments. Their compact size, high stability, and ability to access epitopes inaccessible to conventional antibodies make them attractive therapeutics and research tools. However, discovering nanobodies against new targets traditionally requires immunization of camelids or extensive library screening.
BoltzGen's nanobody-anything protocol takes a known nanobody scaffold and redesigns only the complementarity-determining regions (CDRs) -- the loops responsible for target recognition -- while preserving the stable immunoglobulin framework. This is specified by providing the scaffold structure as a CIF/PDB file with design masks on CDR residues and a target structure.
How this works: - CDR loops (typically CDR1: residues ~26-34, CDR2: ~52-59, CDR3: ~98-118) are marked for redesign - Framework regions remain fixed, preserving fold stability and manufacturability - The diffusion model generates novel loop conformations complementary to the target - Self-consistency checks verify the redesigned loops are compatible with the framework
Practical considerations: CDR residue indices must precisely match PDB numbering of the scaffold structure. Incorrect indices lead to meaningless designs. The CDR3 loop is the primary determinant of binding specificity and typically the longest and most variable.
Cyclic Peptide Design¶
Biological question: Can we design cyclic peptides that bind protein targets with therapeutic potential?
Cyclic peptides occupy a chemical space between small molecules and biologics. Their cyclic backbone confers resistance to proteolytic degradation and can improve cell permeability compared to linear peptides. Applications include targeting protein-protein interactions (PPIs) -- a notoriously difficult drug target class -- and developing oral peptide therapeutics.
BoltzGen's peptide-anything protocol designs cyclic peptides (8-30 residues) with explicit support for:
- Head-to-tail backbone cyclization
- Disulfide bond constraints between specified cysteine positions
- Contact constraints to enforce binding site proximity
- Secondary structure enforcement (helix, sheet, loop)
Output interpretation: Designed peptides should be evaluated for: (1) predicted binding affinity from the Boltz-2 affinity stage, (2) self-consistency of the cyclic backbone (scRMSD), and (3) sequence composition (absence of problematic residues like aggregation-prone stretches or oxidation-sensitive methionines).
Protein Pocket Design for Small Molecules¶
Biological question: Can we design a protein with an active site shaped to bind a specific small molecule?
De novo enzyme design and biosensor development require creating protein pockets that accommodate specific substrates, cofactors, or analytes. Traditional approaches use Rosetta-based computational design with extensive manual optimization.
BoltzGen's protein-small_molecule protocol automates this by designing a protein (typically 140-180 residues) around a specified ligand (provided as a CCD code or SMILES string). The diffusion model generates protein backbones with complementary binding pockets, and the inverse folding model assigns sequences that stabilize the designed fold.
Practical considerations: The designed pocket geometry is complementary to the ligand's ground-state conformation. The model does not explicitly optimize for catalytic activity, substrate specificity, or allosteric regulation. Designed proteins should be validated experimentally for binding and, if applicable, catalytic function.
Applied Use Cases¶
Therapeutic Binder Discovery¶
Source: Stark et al. "BoltzGen: Toward Universal Binder Design." bioRxiv (2025). DOI: 10.1101/2025.11.20.689494
The BoltzGen paper reports experimental validation across eight design campaigns:
- Nanobody binders: Designed nanobodies against 9 novel protein targets with low similarity to known bound structures. Nanomolar binders found for 6 of 9 targets (66% success rate).
- Antimicrobial peptide neutralization: Designed protein binders that sequester toxic peptides (melittin, indolicidin, protegrin), neutralizing their hemolytic and antimicrobial activity.
- Disordered protein targeting: Successfully designed binders against intrinsically disordered protein regions, a target class that is traditionally very difficult for structure-based design.
Drug Discovery Pipeline Integration¶
BoltzGen can serve as the first stage of a computational drug discovery pipeline:
- Target identification: Identify protein target from disease biology
- BoltzGen design: Generate diverse binder candidates (protein or peptide)
- Computational filtering: Use Boltz-2 affinity predictions and self-consistency metrics
- Molecular dynamics validation: Simulate top candidates for binding stability
- Experimental validation: Express and test top designs in binding assays
- Lead optimization: Iterate with BoltzGen using refined constraints
This is particularly valuable for targets where traditional small molecule approaches have failed (e.g., protein-protein interactions, disordered regions, flat binding surfaces).
Related Models¶
Predecessor Models¶
- RFdiffusion: Pioneered diffusion-based protein backbone design (Watson et al., Nature 2023). Generated backbone-only structures requiring separate sequence design with ProteinMPNN. BoltzGen extends this concept to joint structure+sequence generation.
- ProteinMPNN: Inverse folding model for sequence design given a backbone structure. BoltzGen incorporates an inverse folding component (BoltzIF) similar to ProteinMPNN within its pipeline.
- Boltz-2: Structure prediction and affinity model that provides the folding and affinity stages of the BoltzGen pipeline. BoltzGen adds the generative design capability on top of Boltz-2's prediction infrastructure.
Complementary Models¶
| Model | Use with BoltzGen | Workflow |
|---|---|---|
| Boltz-2 | Structure validation and affinity ranking | Already integrated as stages 3-5 of the BoltzGen pipeline |
| ProteinMPNN | Alternative sequence design | Can be used for additional sequence optimization of BoltzGen backbones |
| ESM2 | Embedding-based analysis | Analyze designed sequences for evolutionary plausibility using ESM2 embeddings |
| CamSol | Solubility prediction | Screen BoltzGen designs for aggregation propensity before experimental testing |
| ThermoMPNN | Stability prediction | Predict stability changes (ddG) of designed binders |
Alternative Models¶
| Alternative | Advantage over BoltzGen | Disadvantage vs BoltzGen |
|---|---|---|
| RFdiffusion3 | More conditioning modes (symmetric design, partial diffusion, motif scaffolding) | Requires separate ProteinMPNN step; no integrated affinity prediction |
| Chroma | Faster backbone generation; programmable constraints | Backbone-only; no inverse folding or affinity pipeline |
| EvoDiff | Sequence-space diffusion; faster generation | No 3D structure generation; sequence-only output |
| Traditional display (phage/yeast) | Experimentally validated; covers full sequence space | Expensive; slow (months); limited to accessible surfaces |
Biological Background¶
Protein-Protein Interactions¶
Biological function is largely mediated by specific interactions between proteins. These protein-protein interactions (PPIs) govern signaling cascades, immune recognition, gene regulation, and metabolic pathways. Disrupting pathogenic PPIs or engineering new ones is a central goal of drug development and synthetic biology.
The interface between interacting proteins typically spans 1,500-3,000 square angstroms of buried surface area, involving complementary shape, electrostatics, and hydrophobic interactions. Designing a new protein to bind a target requires generating a surface that is complementary to the target's binding site -- a problem involving simultaneous optimization of backbone geometry, sidechain packing, and amino acid identity.
Conformational Sampling and the Boltzmann Distribution¶
Proteins in solution do not adopt a single rigid structure but rather sample an ensemble of conformations weighted by their energies according to the Boltzmann distribution. The probability of observing a conformation with energy E is proportional to exp(-E/kT), where k is the Boltzmann constant and T is temperature.
BoltzGen's name reflects its generative approach: rather than predicting a single "best" structure, the diffusion model samples from a learned approximation of this distribution. This is biologically meaningful because:
- Flexible binding: Many protein interactions involve conformational changes upon binding (induced fit). Generating diverse conformations captures alternative binding modes.
- Allosteric mechanisms: Proteins can transmit signals through conformational changes at sites distant from the binding interface. Ensemble generation can reveal such mechanisms.
- Ensemble docking: Drug discovery benefits from considering multiple target conformations when predicting binding poses. BoltzGen's diverse structural outputs serve as an implicit conformational ensemble for downstream analysis.
Nanobody Biology¶
Nanobodies are the variable heavy-chain domains (VHH) of heavy-chain-only antibodies found naturally in camelids (camels, llamas, alpacas) and cartilaginous fish. At approximately 15 kDa (roughly 130 residues), they are the smallest naturally occurring antigen-binding fragments.
Key biological properties: - Single-domain binding: Unlike conventional antibodies that require paired VH and VL domains, nanobodies bind antigens with a single domain, simplifying engineering and production. - Extended CDR3: Nanobodies typically have a longer CDR3 loop than conventional antibodies, enabling access to concave epitopes (enzyme active sites, receptor clefts) that flat antibody surfaces cannot reach. - High stability: The immunoglobulin fold is inherently stable, with framework regions providing a robust scaffold for diverse CDR loop conformations. - Reformatting flexibility: Nanobodies can be easily linked into multivalent or bispecific formats, conjugated to drugs or labels, or expressed in microbial systems.
BoltzGen's nanobody-anything protocol exploits these properties by preserving the stable framework scaffold while generating novel CDR conformations, particularly the critical CDR3 loop.
Cyclic Peptide Pharmacology¶
Cyclic peptides bridge the gap between small molecule drugs (MW < 500 Da, oral bioavailability) and protein biologics (MW > 5 kDa, injectable). Their cyclic backbone provides:
- Proteolytic resistance: Exopeptidases cannot cleave cyclic backbones, extending in vivo half-life.
- Conformational pre-organization: Cyclization reduces the entropic penalty of binding, potentially increasing affinity.
- PPI targeting: The larger binding surface of peptides (compared to small molecules) can disrupt flat protein-protein interfaces that lack deep binding pockets.
- Membrane permeability: Certain cyclic peptides (especially N-methylated variants) can cross cell membranes, enabling intracellular targets.
Disulfide bonds provide an alternative cyclization mechanism, covalently linking cysteine side chains to constrain the peptide backbone. BoltzGen supports both head-to-tail cyclization and disulfide bond specification as constraints.
Sources & license¶
License: MIT (text)
Papers
- BoltzGen: Toward Universal Binder Design — bioRxiv preprint, 2025 · DOI
Source repositories
- github: https://github.com/HannesStark/boltzgen
- huggingface: https://huggingface.co/boltzgen/boltzgen-1
Cite
@article{stark2025boltzgen,
title={BoltzGen: Toward Universal Binder Design},
author={Stark, Hannes and Faltings, Felix and Choi, MinGyu and Xie, Yuxin
and Hur, Eunsu and O'Donnell, Timothy and Bushuiev, Anton
and U{\c{c}}ar, Talip and Passaro, Saro and Mao, Weian
and Reveiz, Mateo and Bushuiev, Roman and Pluskal, Tom{\'a}{\v{s}}
and Sivic, Josef and Kreis, Karsten and Vahdat, Arash
and Ray, Shamayeeta and Goldstein, Jonathan T. and Savinov, Andrew
and Hambalek, Jacob A. and Gupta, Anshika
and Taquiri-Diaz, Diego A. and Zhang, Yaotian
and Hatstat, A. Katherine and Arada, Angelika
and Kim, Nam Hyeong and Tackie-Yarboi, Ethel and Boselli, Dylan
and Schnaider, Lee and Liu, Chang C. and Li, Gene-Wei
and Hnisz, Denes and Sabatini, David M. and DeGrado, William F.
and Wohlwend, Jeremy and Corso, Gabriele
and Barzilay, Regina and Jaakkola, Tommi},
journal={bioRxiv},
year={2025},
doi={10.1101/2025.11.20.689494}
}