Boltzgen

BoltzGen — Antibody / Nanobody / Binder Design

BoltzGen is an all-atom diffusion model that generates antibody, nanobody, and de novo miniprotein backbones conditioned on a target structure and a set of binding (hotspot) residues. Sequences are assigned by AntiFold, then each design is independently refolded with Protenix to produce ipTM, pTM, pLDDT, ipSAE, and CA-RMSD metrics. This skill teaches the exact Write → Bash → Read pattern for invoking BoltzGen via its CLI on local GPU (default), HPC (RunPod via by-deploy-compute), or Tamarind cloud.

The legacy CLI name was proteus-ab. It has been renamed to BoltzGen throughout. If you see proteus-ab in older docs or scripts, treat it as the same engine — the binary on PATH is now boltzgen.

When to Use This Skill

Use BoltzGen when you have:

• ✅ A cleaned target structure (CIF or PDB) with unambiguous chain IDs
• ✅ A defined epitope or hotspot set expressed in label_seq_id numbering
• ✅ A modality decision in hand — VHH single-domain, full antibody Fab, or de novo miniprotein
• ✅ GPU compute available — local (CUDA-capable, ≥24 GB VRAM), HPC (RunPod), or Tamarind cloud
• ✅ A design budget — typical preview is 10–20 designs; production is 50–200

Do NOT use BoltzGen when:

• ❌ You need to validate a known antibody sequence against a target → use Protenix directly (no design needed)
• ❌ You need to score or filter an existing batch of designs → use by-scoring (ipSAE) and by-screening
• ❌ No epitope is known or characterised → run by-research + by-epitope-analysis first; designing with no binding_types is wasteful
• ❌ You want a small-molecule binder → BoltzGen designs proteins/peptides only
• ❌ You need ranked, published results → use by-display / /by:results

Quick Start

A 20-design VHH preview against TNF-α (PDB 1TNF, epitope residues 45–52 and 78–85) on a local GPU:

# Step 1: write spec via the Write tool — see scripts/boltzgen_submit.py for a builder
# Step 2: submit (dry-run prints the command; remove --dry-run to launch)
python scripts/boltzgen_submit.py \
  --spec workspace/tnf_spec.yaml \
  --protocol nanobody-anything \
  --num-designs 20 \
  --budget 48 \
  --target local \
  --output workspace/tnf_out

# Step 3: parse results into a CSV with sequences + metrics
python scripts/parse_designs.py \
  --output-dir workspace/tnf_out \
  --csv workspace/tnf_designs.csv

Expected runtime: ~10–25 min on a single H100/A100 (Stage 4 Protenix refolding dominates). Expected output: a CSV ranked by iptm descending, typically 60–80% of designs with iptm > 0.4, 20–40% with iptm > 0.6.

Installation

System requirements:

License Compliance: All packages permit commercial use in AI applications.

For HPC (RunPod) deployment, see the by-deploy-compute skill — it handles container image selection, secret injection, GPU type, and S3 mounting. For Tamarind cloud, point the helper scripts at --target tamarind (requires TAMARIND_API_KEY env var).

Inputs

Required:

• Target structure file — CIF (preferred) or PDB
  • Single chain or multi-chain
  • Clean chain IDs (A, B, …) — no 0 or unusual letters
  • Resolved coordinates for the epitope region (no missing density)
• Entities YAML spec — see references/entities-yaml-spec.md
  • Lists the target file, chains to include, and binding_types epitope ranges
  • Optional scaffold entity (Fab framework or nanobody scaffold)
• Protocol — nanobody-anything, antibody-anything, protein-anything, peptide-anything, or protein-redesign

Alternative inputs:

• Binding residue list (Python list of ints) — converted to range notation by boltzgen_submit.py (see range table in references/entities-yaml-spec.md)
• Pre-built scaffold YAML — point a second entity at $BOLTZGEN_DIR/example/fab_scaffolds/*.yaml or nanobody_scaffolds/*.yaml

Optional:

• MSA mode — none (default), precomputed (A3M files), or nim (NVIDIA NIM API)
• Budget — diffusion steps; 48 preview, 96–128 production
• --prefilter — drops low-quality designs before the expensive Protenix refolding (recommended for num_designs ≥ 50)

⚠️ CRITICAL: Binding residues use label_seq_id (1-indexed, sequential, per-chain). Mistakenly using auth_seq_id is the single most common cause of wasted campaigns.

See references/entities-yaml-spec.md for the full schema and conversion rules.

Outputs

All outputs land under the directory passed as --output.

Primary results:

CSV columns (in order):

Sorted by iptm descending. Hard filters applied downstream by by-scoring: ipTM > 0.5, pLDDT > 70, RMSD < 3.5 Å. The composite score combines ipSAE_min (0.50), ipTM (0.30), and inverted liability count (0.20).

The helper script scripts/parse_designs.py flattens multi-seed ensembles into a single CSV and adds the seed column.

Clarification Questions

⚠️ CRITICAL: ASK THIS FIRST — confirm the target structure, epitope, and modality before running anything.

1. Target structure (ASK THIS FIRST) — Do you have a cleaned CIF/PDB for the target, with confirmed chain IDs? If only a UniProt accession, run by-research + Protenix first to obtain a structure.
2. Epitope / hotspot residues — Which residues should the binder target? Provide as a Python list of label_seq_id integers per chain. If unknown, run by-epitope-analysis first.
3. Modality — VHH single-domain, full antibody (VH/VL Fab), or de novo miniprotein? See references/antibody-design-best-practices.md for selection criteria.
4. Design count — How many designs? Preview (10–20) for quick sanity check; production (50–200) once epitope is validated.
5. Compute target — Local GPU (default), HPC via RunPod, or Tamarind cloud? Local is preferred when a GPU is present; HPC for batched runs > 100 designs.
6. Scaffold preference — Use a specific therapeutic framework (e.g., adalimumab) or let BoltzGen pick defaults? Most runs use defaults; specify a scaffold only when humanization or framework matching is required.
7. MSA mode — Default none is fine for the first pass. Switch to precomputed or nim only if pLDDT < 70 across the top designs.

See references/antibody-design-best-practices.md for the modality decision tree and expected pass rates by target class.

Standard Workflow

🚨 MANDATORY: USE SCRIPTS EXACTLY AS SHOWN — DO NOT WRITE INLINE CODE 🚨

This skill follows the Write → Bash → Read pattern. The two scripts under scripts/ are the canonical entry points.

Step 1 — Write the entities YAML

Use the Write tool to create the spec file. The minimal form:

# workspace/design_spec.yaml
entities:
- file:
    path: ./target.cif
    include:
    - chain:
        id: A
    binding_types:
    - chain:
        id: A
        binding: 45..52,78..85

Range notation rules and conversion tables: references/entities-yaml-spec.md.

✅ VERIFICATION: yamllint workspace/design_spec.yaml returns no errors.

Step 2 — Submit via boltzgen_submit.py

python scripts/boltzgen_submit.py \
  --spec workspace/design_spec.yaml \
  --protocol nanobody-anything \
  --num-designs 20 \
  --budget 48 \
  --msa-mode none \
  --target local \
  --output workspace/output \
  --prefilter

Targets:

✅ VERIFICATION: Console shows ✓ boltzgen completed: <N> designs written to <path> on success.

Step 3 — Parse and rank

python scripts/parse_designs.py \
  --output-dir workspace/output \
  --csv workspace/designs.csv

This walks final_ranked_designs/, handles multi-seed ensembles by merging all final_designs_metrics_*.csv files, and writes a single canonical CSV.

✅ VERIFICATION: Console shows ✓ parse_designs completed: <N> rows / <path>.

Step 4 — Hand off to by-scoring / by-screening

The CSV is the input to downstream skills. Do not re-derive metrics inline.

⚠️ CRITICAL — DO NOT:

• ❌ Write inline subprocess.run(["boltzgen", ...]) calls → use boltzgen_submit.py
• ❌ Parse the CSV with ad-hoc pd.read_csv filtering → use parse_designs.py then by-scoring
• ❌ Edit the entities YAML by hand on every run → use the script's --binding-residues flag to generate ranges
• ❌ Use absolute /mnt/... paths in spec files → use paths relative to the spec file

When Scripts Fail

Follow the standard script-failure hierarchy:

Common decision tree:

• Missing env var → Step 1 (export LAYERNORM_TYPE=openfold; export PROTEUS_MODELS_DIR=~/.cache/boltzgen)
• CUDA OOM → Step 1 (reduce --num-designs or --budget)
• New CLI flag in a BoltzGen upgrade → Step 2 (add the flag to boltzgen_submit.py)
• Multi-seed run with a non-standard directory layout → Step 3
• Output schema renamed columns → Step 4

Decision Points

Protocol selection

Compute target

MSA mode

See references/antibody-design-best-practices.md for budget × protocol × hit-rate guidance.

Common Issues

Best Practices

1. 🚨 CRITICAL: Always export LAYERNORM_TYPE=openfold and PROTEUS_MODELS_DIR before running — silent NaNs otherwise.
2. 🚨 CRITICAL: Binding residues use label_seq_id, not auth_seq_id. Verify the conversion before launching.
3. ✅ REQUIRED: Run a 10–20 design preview before any production run > 50 designs. Confirms epitope is reachable.
4. ✅ REQUIRED: Enable --prefilter for num_designs ≥ 50. Saves 20–50% GPU time.
5. ✅ Prefer local GPU as the default compute target. Only escalate to HPC (RunPod) for batches > 100 or when no local GPU is available. Tamarind is the last-resort cloud fallback.
6. ✅ Choose VHH (nanobody-anything) unless Fc effector function is required — faster, fewer designs needed.
7. ✅ Use the helper scripts (boltzgen_submit.py, parse_designs.py); do not hand-craft boltzgen run invocations.
8. ✅ Always pass output to by-scoring and by-screening — never rank by iptm alone for a final shortlist.
9. ✨ Optional: Pin a specific Fab scaffold when humanization is a downstream requirement (see scaffold catalog below).
10. ❌ DON'T rerun a campaign with a different epitope without first checking SASA — buried residues waste compute.

Suggested Next Steps

After BoltzGen completes, route through the standard scoring → screening → display pipeline.

Chain rationale: BoltzGen produces raw structural metrics; by-scoring normalises and combines them; by-screening adds biophysical filters; by-display is the user-facing artifact. The campaign manager closes the loop with state and history.

Related Skills

Upstream (run before BoltzGen):

• by-research — Target dossier, prior art, scaffold suggestions
• by-epitope-analysis — Hotspot residues with SASA and conservation
• by-hypothesis-debate — Strategy selection (modality, scaffold, budget) when multiple approaches are viable
• Protenix — If only a sequence is available, predict the target structure first

Downstream (run after BoltzGen):

• by-scoring — ipSAE recomputation + composite score
• by-screening — Full developability and liability battery
• by-display — Format and present ranked designs
• by-campaign-manager — State checkpoint and next-iteration decision

Alternative / complementary:

• pxdesign — De novo miniprotein binder design (non-antibody). Use boltzgen protein-anything only as a fallback when pxdesign is unavailable.
• by-deploy-compute — HPC (RunPod) and Tamarind deployment details for offloading BoltzGen runs

Scaffold Templates

Pre-built scaffold YAMLs ship with BoltzGen under $BOLTZGEN_DIR/example/. Add a second entity in the spec to use one; omit for built-in defaults.

Fab scaffolds (14)

Nanobody scaffolds (4)

Example with explicit scaffold:

entities:
- file:
    path: ./target.cif
    include:
    - chain:
        id: A
    binding_types:
    - chain:
        id: A
        binding: 45..52,78..85
- file:
    path: $BOLTZGEN_DIR/example/fab_scaffolds/adalimumab.6cr1.yaml

References

Detailed documentation:

• references/entities-yaml-spec.md — Full schema for the entities YAML: target entity, include blocks, binding ranges, scaffold entities, and common mistakes.
• references/pipeline-stages.md — Six-stage internal pipeline (Design → Inverse Fold → Pre-filter → Refold → Analysis → Filtering) with per-stage timing and success indicators.
• references/antibody-design-best-practices.md — VHH vs scFv vs Fab selection, MSA mode choice, expected pass rates by target difficulty, hotspot count recommendations.

Scripts:

• scripts/boltzgen_submit.py — Reads the entities YAML + flags, builds the CLI command, and invokes locally or hands off to HPC / Tamarind. Supports --dry-run.
• scripts/parse_designs.py — Walks a BoltzGen output directory, merges multi-seed CSVs, and writes a single canonical CSV of design IDs, scores, and sequences.

External documentation:

• BoltzGen repository — https://github.com/HannesStark/boltzgen
• Protenix (refolding engine) — https://github.com/bytedance/Protenix
• AntiFold (inverse folding) — https://github.com/oxpig/AntiFold

License: All referenced engines (BoltzGen, Protenix, AntiFold) permit commercial use.