ImmuneBuilder¶

Ensemble of EGNN-based deep learning models for predicting 3D structures of antibodies, nanobodies, and T-cell receptors from sequence alone.

License: BSD-3-Clause · Molecules: antibody, nanobody, tcr · Tasks: structure_prediction

Actions: fold · Variants: 4

At a glance¶

Use it when

You need to predict structures for multiple immune protein types (antibodies, nanobodies, and TCRs) using a single unified model family with consistent output format
You want CPU-only structure prediction for cost-effective high-throughput screening of immune protein libraries without GPU infrastructure
You need nanobody (VHH) structure prediction with a model specifically trained on single-domain antibody structures from SAbDab
You need TCR structure prediction (alpha/beta chains) and want the choice between TCRBuilder2 and the updated TCRBuilder2Plus with expanded training data
You want to provide predicted structures as input for downstream tools like AntiFold (inverse folding) or structure-based developability analysis
You are benchmarking antibody structure prediction methods and need a well-established reference with published accuracy metrics

Strengths

Broadest immune protein coverage in this catalog: four dedicated sub-models for conventional antibodies (ABodyBuilder2), nanobodies (NanoBodyBuilder2), TCRs (TCRBuilder2), and updated TCRs (TCRBuilder2Plus)
CPU-only inference for all variants (8 GB RAM, no GPU), making it the most cost-effective structural prediction tool for immune proteins in this catalog
EGNN ensemble architecture captures geometric constraints of the immunoglobulin fold with built-in uncertainty estimation from multiple model predictions
OpenMM relaxation ensures physically realistic bond geometries, producing PDB structures that are immediately usable for downstream molecular modeling tools
Dedicated NanoBodyBuilder2 variant specifically trained on VHH structures from SAbDab, accounting for extended CDR3 loops and adapted framework residues unique to nanobodies
Published in Communications Biology (2023) with extensive benchmarking against AlphaFold2, ESMFold, and earlier methods; widely cited in the antibody modeling community
Single-sequence prediction without MSA requirement, enabling fast structural characterization of immune protein sequences from sequencing campaigns
BSD-3-Clause license with no commercial restrictions, widely adopted in academic and industrial antibody/TCR engineering pipelines

Limitations

Lower CDR accuracy compared to newer PLM-enhanced methods (AbodyBuilder3 language variant, ImmuneFold) that incorporate protein language model embeddings
Does not predict antibody-antigen complex structures; only models unbound immune receptor structures -- use ImmuneFold for complex prediction
No per-residue confidence scores (pLDDT) for quality assessment -- unlike AbodyBuilder3 and ImmuneFold, users cannot identify which regions are predicted with high or low confidence
Single action (fold) with no embedding, scoring, or sequence generation capabilities -- purely a structure prediction tool
ABodyBuilder2 sub-model has been superseded by AbodyBuilder3 for conventional antibody structure prediction, making the antibody variant no longer state-of-the-art
Does not support gamma/delta TCRs; trained primarily on alpha/beta TCR structures
Four separate deployments required for full coverage, increasing infrastructure overhead compared to a single unified model

Reach for something else when

You need the highest-accuracy antibody structure prediction and have GPU resources available -- use AbodyBuilder3 (language variant) or ImmuneFold, which leverage protein language model embeddings
You need antibody-antigen complex structure prediction -- use ImmuneFold, which accepts antigen PDB input for complex modeling
You need per-residue confidence scores (pLDDT) to assess prediction quality -- use AbodyBuilder3 or ImmuneFold, both of which provide pLDDT scores
You need sequence-level analysis (embeddings, scoring, generation) rather than structure prediction -- use AbLang2, IgBERT, or IgT5
You need TCR-pMHC complex modeling with peptide and MHC context -- use ImmuneFold (TCR variant), which takes four-chain input including peptide and MHC
You need general protein structure prediction for non-immune targets -- use ESMFold or Chai-1
You need the fastest possible antibody structure prediction for a single candidate -- ImmuneBuilder's OpenMM relaxation adds latency

Alternatives

Model	Better when	Worse when
abodybuilder3	Higher CDR accuracy via the language (ProtT5) variant and per-residue pLDDT confidence scores for quality assessment.	Antibody-only (paired VH/VL); cannot predict nanobody or TCR structures, and the language variant needs a GPU whereas ImmuneBuilder runs CPU-only.
immunefold	ESM-2-based representations for the highest CDR accuracy, supports antibody-antigen and TCR-pMHC complex prediction, and returns pTM/pLDDT confidence.	Requires a T4 GPU (16 GB) and has no dedicated nanobody variant, while ImmuneBuilder runs entirely on CPU and covers nanobodies.
esmfold	General single-sequence folder that also handles immune chains (concatenate heavy/light with ':') plus any non-immune protein, and returns pTM/mean pLDDT confidence in one tool.	No immune-specific training or dedicated nanobody/TCR/CDR handling, requires an A10G GPU, and is generally less accurate on antibody CDR loops than ImmuneBuilder's specialized sub-models.

API & schema¶

Variants

Variant	Endpoint slug	GPU	CPU	Memory
tcrbuilder2	`immunebuilder-tcrbuilder2`	CPU	2.0	8 GB
tcrbuilder2plus	`immunebuilder-tcrbuilder2plus`	CPU	2.0	8 GB
abodybuilder2	`immunebuilder-abodybuilder2`	CPU	2.0	8 GB
nanobodybuilder2	`immunebuilder-nanobodybuilder2`	CPU	2.0	8 GB

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.

`fold`¶

Call it

curl -X POST http://127.0.0.1:8000/api/v1/immunebuilder-tcrbuilder2/fold \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {}
  ]
}'

Request — ImmuneBuilderFoldRequest

Field	Type	Required	Constraints	Description
`items`	list[ImmuneBuilderFoldRequestItem]	yes	items 1–8	Batch of inputs to process in a single request. Up to 8 sequences per request.
`params`	ImmuneBuilderFoldParams \| null	no		Optional parameters controlling this action (defaults are used when omitted).

Nested types

ImmuneBuilderFoldParams

Field	Type	Required	Constraints	Description
`seed`	integer	no	≥0; default `42`	Random seed for reproducible sampling.

ImmuneBuilderFoldRequestItem

Field	Type	Required	Description
`heavy_chain`	string \| null	no	Antibody heavy-chain amino-acid sequence; provide alone for nanobody (VHH) prediction.
`light_chain`	string \| null	no	Antibody light-chain amino-acid sequence.
`tcr_alpha`	string \| null	no	TCR alpha-chain amino-acid sequence; pair with tcr_beta for TCR structure prediction.
`tcr_beta`	string \| null	no	TCR beta-chain amino-acid sequence; pair with tcr_alpha for TCR structure prediction.

Raw JSON Schema

{
  "$defs": {
    "ImmuneBuilderFoldParams": {
      "additionalProperties": false,
      "properties": {
        "seed": {
          "default": 42,
          "description": "Random seed for reproducible sampling.",
          "minimum": 0,
          "title": "Seed",
          "type": "integer"
        }
      },
      "title": "ImmuneBuilderFoldParams",
      "type": "object"
    },
    "ImmuneBuilderFoldRequestItem": {
      "additionalProperties": false,
      "properties": {
        "heavy_chain": {
          "anyOf": [
            {
              "maxLength": 2048,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Antibody heavy-chain amino-acid sequence; provide alone for nanobody (VHH) prediction.",
          "title": "Heavy Chain"
        },
        "light_chain": {
          "anyOf": [
            {
              "maxLength": 2048,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Antibody light-chain amino-acid sequence.",
          "title": "Light Chain"
        },
        "tcr_alpha": {
          "anyOf": [
            {
              "maxLength": 2048,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "TCR alpha-chain amino-acid sequence; pair with tcr_beta for TCR structure prediction.",
          "title": "Tcr Alpha"
        },
        "tcr_beta": {
          "anyOf": [
            {
              "maxLength": 2048,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "TCR beta-chain amino-acid sequence; pair with tcr_alpha for TCR structure prediction.",
          "title": "Tcr Beta"
        }
      },
      "title": "ImmuneBuilderFoldRequestItem",
      "type": "object"
    }
  },
  "additionalProperties": false,
  "properties": {
    "items": {
      "description": "Batch of inputs to process in a single request. Up to 8 sequences per request.",
      "items": {
        "$ref": "#/$defs/ImmuneBuilderFoldRequestItem"
      },
      "maxItems": 8,
      "minItems": 1,
      "title": "Items",
      "type": "array"
    },
    "params": {
      "anyOf": [
        {
          "$ref": "#/$defs/ImmuneBuilderFoldParams"
        },
        {
          "type": "null"
        }
      ],
      "description": "Optional parameters controlling this action (defaults are used when omitted)."
    }
  },
  "required": [
    "items"
  ],
  "title": "ImmuneBuilderFoldRequest",
  "type": "object"
}

Response — ImmuneBuilderFoldResponse

Field	Type	Required	Constraints	Description
`results`	list[ImmuneBuilderFoldResponseResult]	yes		Per-input results, returned in the same order as the request items.

Nested types

ImmuneBuilderFoldResponseResult

Field	Type	Required	Constraints	Description
`pdb`	string	yes		Predicted structure in PDB format.

Raw JSON Schema

{
  "$defs": {
    "ImmuneBuilderFoldResponseResult": {
      "properties": {
        "pdb": {
          "description": "Predicted structure in PDB format.",
          "title": "Pdb",
          "type": "string"
        }
      },
      "required": [
        "pdb"
      ],
      "title": "ImmuneBuilderFoldResponseResult",
      "type": "object"
    }
  },
  "properties": {
    "results": {
      "description": "Per-input results, returned in the same order as the request items.",
      "items": {
        "$ref": "#/$defs/ImmuneBuilderFoldResponseResult"
      },
      "title": "Results",
      "type": "array"
    }
  },
  "required": [
    "results"
  ],
  "title": "ImmuneBuilderFoldResponse",
  "type": "object"
}

Usage¶

One-line summary: Ensemble of EGNN-based deep learning models for predicting 3D structures of antibodies, nanobodies, and T-cell receptors from sequence alone.

Overview¶

ImmuneBuilder is a structure prediction framework developed by Abanades et al. (2023) at the Oxford Protein Informatics Group (OPIG). It comprises four specialized sub-models -- ABodyBuilder2 (paired antibody), NanoBodyBuilder2 (single-domain nanobody), TCRBuilder2 (alpha/beta TCR), and TCRBuilder2Plus (improved TCR) -- each trained on curated immune protein structural databases using equivariant graph neural networks (EGNNs).

Given amino acid sequences for the appropriate chain pair, ImmuneBuilder predicts full-atom 3D structures in PDB format. No MSA or template structure is required. Structures are refined via OpenMM energy minimization for physically realistic geometries.

Architecture¶

Property	Value
Architecture	Equivariant Graph Neural Network (EGNN) ensemble (4 models per variant)
Training data	SAbDab (antibodies/nanobodies), STCRDab (TCRs)
Input	Amino acid sequences (single-letter code)
Output	PDB-format 3D atomic coordinates
Post-processing	OpenMM AMBER force field energy minimization

Capabilities & Limitations¶

CAN be used for: - Predicting 3D structures of antibodies from paired VH/VL sequences - Predicting nanobody (VHH) structures from heavy chain sequence only - Predicting alpha/beta TCR structures from paired alpha and beta chain sequences - Providing input structures for downstream tools (ProperMAB, AntiFold, docking)

CANNOT be used for: - General protein structure prediction (use AlphaFold2 or ESMFold) - Antibody-antigen complex prediction (use ImmuneFold with antigen PDB) - Gamma/delta TCR prediction - Constant region (Fc) structure prediction - Sequence design or inverse folding (use AntiFold)

Usage Examples¶

Antibody structure prediction¶

from models.immunebuilder.schema import (
    ImmuneBuilderFoldRequest,
    ImmuneBuilderFoldRequestItem,
    ImmuneBuilderFoldParams,
)

request = ImmuneBuilderFoldRequest(
    items=[
        ImmuneBuilderFoldRequestItem(
            heavy_chain="EVQLVESGGGLVQPGGSLRLSCAASGFTFSDYAMSWVRQAPGKGLEWVSGISGSGGSTYYADSVKGRFTISRDNSKNTLYLQMNSLRAEDTAVYYCAKDRLSITIRPRYYGLDVWGQGTTVTVSS",
            light_chain="DIQMTQSPSSLSASVGDRVTITCRASQSISSYLNWYQQKPGKAPKLLIYAASSLQSGVPSRFSGSGSGTDFTLTISSLQPEDFATYYCQQSYSTPLTFGGGTKVEIK",
        )
    ],
    params=ImmuneBuilderFoldParams(seed=42),
)

Nanobody structure prediction¶

request = ImmuneBuilderFoldRequest(
    items=[
        ImmuneBuilderFoldRequestItem(
            heavy_chain="QVQLQESGGGLVQPGGSLRLSCAASGRTFSSYAMGWFRQAPGKEREFVAAISWSGGSTYYADSVKGRFTISRDNAKNTVYLQMNSLKPEDTAVYYCAADSTIYASYYECGHGLSTGGYGYDSWGQGTQVTVSS",
        )
    ],
)

TCR structure prediction¶

request = ImmuneBuilderFoldRequest(
    items=[
        ImmuneBuilderFoldRequestItem(
            tcr_alpha="AQEVTQIPAALSVPEGENLVLNCSFTDSAIYNLQWFRQDPGKGLTSLLLIQSSQREQTSGRLNASLDKSSGRSTLYIAASQPGDSATYLCAVRPTSGGSYIPTFGRGTSLIVHPY",
            tcr_beta="DAGVTQTPRNHVTISEGDKITVRCEKSTVSNFLYELFWYRQDPGLGLRLIYFSYDVKMKEKGDIPDGYSVSRNKKPNFYEALISKLNVSDSALYFCASSQETQYFGPGTRLTVL",
        )
    ],
)

Architecture & training¶

Architecture¶

Model Type & Innovation¶

ImmuneBuilder is an ensemble of deep learning models for predicting the 3D structures of immune proteins -- antibodies, nanobodies, and T-cell receptors (TCRs). It consists of four specialized sub-models, each trained on distinct structural classes: ABodyBuilder2 (antibody VH/VL), NanoBodyBuilder2 (single-domain VHH), TCRBuilder2 (alpha/beta TCR), and TCRBuilder2Plus (improved TCR with updated weights). Each sub-model uses an equivariant graph neural network (EGNN) architecture that operates directly on residue-level graphs, iteratively refining predicted 3D coordinates.

The key innovation is decomposing the immune protein structure prediction problem into specialized sub-models, each trained on curated structural databases (SAbDab for antibodies, STCRDab for TCRs). This specialization yields higher accuracy on immune proteins compared to general-purpose structure predictors. The models output PDB-format structures with relaxed coordinates via OpenMM energy minimization.

Parameters & Layers¶

Component	Details
Architecture	Equivariant Graph Neural Network (EGNN) ensemble
Sub-models	ABodyBuilder2, NanoBodyBuilder2, TCRBuilder2, TCRBuilder2Plus
Ensemble members	4 per sub-model (antibody_model_1..4, nanobody_model_1..4, tcr_model_1..4, tcr2_model_1..4)
Input	Amino acid sequences for appropriate chain pairs
Output	PDB-format 3D atomic coordinates
Coordinate refinement	OpenMM energy minimization with AMBER force field
Numbering	ANARCI / IMGT for antibody and TCR region identification

Training Data¶

Property	Details
Antibody training	SAbDab (Structural Antibody Database) -- paired VH/VL crystal structures
Nanobody training	SAbDab -- single-domain VHH structures
TCR training	STCRDab (Structural TCR Database) -- paired alpha/beta TCR structures
TCRBuilder2Plus	Updated weights on expanded TCR structural data
Numbering scheme	IMGT (ImMunoGeneTics) numbering via ANARCI

Loss Function & Objective¶

Each EGNN sub-model is trained to minimize the distance between predicted and experimental atomic coordinates, using a combination of coordinate RMSD loss and auxiliary geometric losses (bond lengths, angles). The ensemble of 4 models per sub-type provides robustness -- final predictions are obtained by averaging over ensemble members.

Tokenization / Input Processing¶

Input format: Amino acid sequences provided as single-letter codes
Chain specification: heavy_chain, light_chain for antibodies; tcr_alpha, tcr_beta for TCRs; heavy_chain only for nanobodies (legacy single-letter aliases H/L/A/B are still accepted)
Validation: Extended amino acid alphabet (including ambiguous residues)
Type inference: The model type is automatically inferred from the chain combination:
heavy_chain + light_chain => ABodyBuilder2
heavy_chain only => NanoBodyBuilder2
tcr_alpha + tcr_beta => TCRBuilder2 and TCRBuilder2Plus
Numbering: ANARCI assigns IMGT numbering before structure prediction
Post-processing: OpenMM relaxation produces physically realistic bond geometries

Performance & Benchmarks¶

Published Benchmarks¶

Antibody Structure Prediction (ABodyBuilder2)¶

Model	CDR-H3 RMSD (A)	Overall VH/VL RMSD (A)	Notes
ABodyBuilder2	2.81	~1.5	Avg on SAbDab test set
AlphaFold2	3.42	~1.8	General-purpose
ABlooper	3.15	--	CDR-only predictor

Abanades et al., Communications Biology (2023). Table values are approximate from paper figures.

Nanobody Structure Prediction (NanoBodyBuilder2)¶

Model	CDR-H3 RMSD (A)	Notes
NanoBodyBuilder2	~2.5	Specialized for VHH
AlphaFold2	~3.0	Not nanobody-specific

TCR Structure Prediction (TCRBuilder2)¶

Model	CDR3-alpha RMSD (A)	CDR3-beta RMSD (A)	Notes
TCRBuilder2	~1.8	~2.2	Specialized for TCR
AlphaFold2	~2.5	~3.0	General-purpose

BioLM Verification Results¶

Variant	Action	Tolerance	Status
abodybuilder2	fold	rel_tol 1e-4, PDB RMSD < 1.5 Å	PASS
nanobodybuilder2	fold	rel_tol 1e-4, PDB RMSD < 1.5 Å	PASS
tcrbuilder2	fold	rel_tol 1e-4, PDB RMSD < 1.5 Å	PASS
tcrbuilder2plus	fold	rel_tol 1e-4, PDB RMSD < 1.5 Å	PASS

Comparison to Alternatives¶

Model	Strength	When to prefer
ImmuneBuilder	Immune protein specialist; fast; no MSA needed	Antibody/nanobody/TCR structure prediction
AlphaFold2	General-purpose; higher accuracy on some targets	Non-immune proteins; when MSA available
ESMFold	Single-sequence; very fast	Quick single-chain protein folding
ImmuneFold	PLM-enhanced antibody/TCR folding	When higher accuracy on antibodies is needed

Strengths & Limitations¶

Pros¶

Specialized for immune proteins with dedicated sub-models for each structural class
No MSA required -- single-sequence input for fast predictions
Supports antibodies, nanobodies, and TCRs in a unified framework
OpenMM energy minimization produces physically realistic structures
Lightweight CPU-only inference (no GPU required)
Deterministic with fixed random seed

Cons¶

Limited to immune protein variable domains (not for general proteins)
CDR-H3 accuracy lower than AlphaFold2 Multimer for some targets
No antigen-bound complex prediction
Ensemble of 4 models per variant adds overhead vs single-model approaches
Maximum sequence length of 2048 residues per chain

Known Failure Modes¶

Sequences that fail ANARCI numbering (highly unusual or non-standard immune protein sequences) will produce errors
Very long CDR-H3 loops (>25 residues) may have reduced accuracy
Proteins that are not antibodies, nanobodies, or TCRs will produce meaningless results

Implementation Details¶

Inference Pipeline¶

Request
  |-- 1. Validate amino acid sequences
  |-- 2. Infer model type from chain combination (H+L, H-only, A+B)
  |-- 3. Route to appropriate sub-model (ABodyBuilder2/NanoBodyBuilder2/TCRBuilder2/TCRBuilder2Plus)
  |-- 4. Run EGNN ensemble (4 models) to predict coordinates
  |-- 5. Average ensemble predictions
  |-- 6. OpenMM energy minimization (AMBER force field)
  |-- 7. Write to temporary PDB file
  |-- 8. Read PDB string and clean up
  |-- 9. Return PDB string in response

Memory & Compute Profile¶

Resource	Value
GPU	None (CPU-only)
Memory	8 GB RAM
CPU	2.0 cores
Batch size	8
Max sequence length	2048

Determinism & Reproducibility¶

Setting	Value
Torch manual seed	Yes (42 at model load)
CUDA manual seed	Yes (42, if available)
NumPy seed	Set per-request
User-specified seed	Supported via `seed` parameter (default: 42)
PYTHONHASHSEED	Set to seed value
cuDNN deterministic	Enabled

Caching Behavior¶

Response caching is handled by the serving layer, not by the model container itself: - In-memory caching (Modal Dict) for fast repeated lookups - R2 object storage for persistent cross-container caching - Cache keys determined by full request payload

Versions & Changelog¶

Version	Date	Changes
v1	2025	Initial implementation with 4 sub-model variants

Biology¶

Molecule Coverage¶

Primary Molecule Type(s)¶

ImmuneBuilder is designed for the three major classes of adaptive immune receptor proteins:

Conventional antibodies: Paired heavy chain (VH) and light chain (VL) variable regions. Predicted by ABodyBuilder2.
Nanobodies: Single-domain antibodies (VHH) from camelid heavy-chain-only antibodies. Predicted by NanoBodyBuilder2.
T-cell receptors (TCRs): Paired alpha and beta chain variable regions. Predicted by TCRBuilder2 and TCRBuilder2Plus.

All sub-models operate on amino acid sequences and produce full-atom 3D structures in PDB format. No MSA or template structure is required -- predictions are single-sequence.

Cross-Applicability¶

Molecule Type	Applicability	Evidence	Caveats
Conventional antibodies (VH/VL)	High	Primary target of ABodyBuilder2	Requires both H and L chain sequences
Nanobodies (VHH)	High	Dedicated NanoBodyBuilder2 sub-model	H chain only input
Alpha/beta TCRs	High	Dedicated TCRBuilder2/TCRBuilder2Plus sub-models	Requires both A and B chain sequences
Gamma/delta TCRs	Low	Not specifically trained	Structural differences from alpha/beta
General proteins	Not applicable	Model is immune-protein-specific	Use AlphaFold2 or ESMFold instead
Antibody-antigen complexes	Not applicable	Does not model antigen binding	Use ImmuneFold or AlphaFold2 Multimer

Biological Problems Addressed¶

Antibody Structure Prediction¶

Biological context: Knowing the 3D structure of an antibody, particularly the conformation of its CDR loops, is essential for understanding antigen binding, performing structure-based design, and assessing developability. Experimental structure determination by X-ray crystallography or cryo-EM is slow and expensive. Computational prediction from sequence alone enables rapid structural characterization of antibody candidates.

How ImmuneBuilder helps: ABodyBuilder2 takes paired VH/VL sequences and predicts the full 3D structure including all CDR loops. The EGNN ensemble captures the geometric constraints of the immunoglobulin fold, and OpenMM relaxation ensures physically realistic bond geometries. This enables rapid structural characterization of antibody candidates from sequencing data alone.

Output interpretation: The output PDB file contains atomic coordinates for all heavy atoms. The structure can be used for downstream analysis such as paratope identification, epitope prediction, docking, or feature extraction (e.g., with ProperMAB).

Nanobody Structure Prediction¶

Biological context: Nanobodies are emerging as therapeutic and diagnostic reagents due to their small size (~15 kDa), high stability, and ease of production. Their CDR3 loops tend to be longer and more structurally diverse than conventional antibodies, making structure prediction challenging.

How ImmuneBuilder helps: NanoBodyBuilder2 is specifically trained on VHH structures from SAbDab, accounting for the unique structural features of nanobodies including extended CDR3 loops and adapted framework residues that compensate for the absence of a light chain.

TCR Structure Prediction¶

Biological context: T-cell receptors recognize peptide-MHC complexes and are central to adaptive immunity, cancer immunotherapy (e.g., TCR-T cell therapy), and autoimmune disease. Structural knowledge of TCRs is critical for understanding antigen recognition specificity and designing engineered TCR therapeutics.

How ImmuneBuilder helps: TCRBuilder2 and TCRBuilder2Plus predict alpha/beta TCR structures from paired chain sequences. TCRBuilder2Plus uses updated weights trained on an expanded structural database for improved accuracy. These predictions enable rational TCR engineering and binding mode analysis.

Applied Use Cases¶

ImmuneBuilder addresses computational structure prediction for immune proteins. Key published and anticipated use cases include:

Antibody discovery pipelines: Rapid structural characterization of candidates from NGS sequencing campaigns
Structure-based antibody design: Providing input structures for inverse folding (e.g., AntiFold) or feature extraction (e.g., ProperMAB)
TCR-pMHC interaction modeling: Predicting TCR structures for docking studies with peptide-MHC complexes
Nanobody engineering: Structural assessment of nanobody libraries for CDR loop optimization

Predecessor Models¶

ABodyBuilder (Leem et al., 2016): The original antibody structure prediction tool that ImmuneBuilder extends. Used homology modeling and loop prediction rather than deep learning.
ABlooper (Abanades et al., 2022): CDR loop-only predictor from the same group, which informed the EGNN approach used in ImmuneBuilder.

Complementary Models¶

ProperMAB: Uses ABodyBuilder2 structures as input for extracting 34 biophysical developability features. Pipeline: ImmuneBuilder -> ProperMAB.
AntiFold: Antibody inverse folding model that requires 3D structures. ImmuneBuilder can provide predicted structures when experimental structures are unavailable.
ESM2: Protein language model embeddings can complement ImmuneBuilder structures for sequence fitness assessment.

Alternative Models¶

Alternative	Advantage over ImmuneBuilder	Disadvantage vs ImmuneBuilder
ImmuneFold	PLM-enhanced; higher accuracy on some targets	Larger model; requires GPU
AlphaFold2	Handles any protein; MSA-enhanced accuracy	Slower; requires MSA; not immune-specialized
ESMFold	Very fast single-sequence prediction	Not immune-protein-specialized

Biological Background¶

Adaptive Immune Receptors¶

The adaptive immune system relies on two classes of antigen receptors: antibodies (produced by B cells) and T-cell receptors (produced by T cells). Both use a similar structural framework -- the immunoglobulin fold -- but recognize antigens through different mechanisms:

Antibodies: Bind soluble or cell-surface antigens directly via CDR loops in VH/VL variable domains
TCRs: Recognize processed peptide fragments presented by MHC molecules on cell surfaces

Immunoglobulin Fold¶

The immunoglobulin fold is a conserved structural motif consisting of two beta-sheets packed face-to-face, stabilized by a conserved disulfide bond. Both antibody variable domains (VH, VL) and TCR variable domains (V-alpha, V-beta) adopt this fold. The CDR loops emerge from one end of the beta-sandwich and form the antigen-binding surface.

Variable Domain Structure:
  |-- Framework Region 1 (FR1)   -- beta-strand
  |-- CDR1                       -- loop
  |-- Framework Region 2 (FR2)   -- beta-strand
  |-- CDR2                       -- loop
  |-- Framework Region 3 (FR3)   -- beta-strand
  |-- CDR3                       -- loop (most variable)
  |-- Framework Region 4 (FR4)   -- beta-strand

CDR Loop Diversity¶

CDR3, particularly CDR-H3 in antibodies and CDR3-beta in TCRs, is the most structurally diverse loop. It is generated by V(D)J recombination with junctional diversity and is the primary determinant of antigen specificity. Predicting CDR3 conformation is the hardest part of immune protein structure prediction and is where specialized models like ImmuneBuilder provide the greatest advantage over general-purpose predictors.

Nanobodies vs Conventional Antibodies¶

Nanobodies (VHH) lack a light chain entirely, relying on: - Extended CDR-H3 loops (often 15-25+ residues) that provide a large binding surface - Adapted framework residues at positions that would normally contact VL - Higher thermal stability and solubility than conventional antibody fragments

These structural differences necessitate a dedicated prediction model (NanoBodyBuilder2) rather than using the conventional antibody predictor.

Sources & license¶

License: BSD-3-Clause (text)

Papers

ImmuneBuilder: Deep-Learning models for predicting the structures of immune proteins — Communications Biology, 2023 · DOI arXiv

Source repositories

github: https://github.com/oxpig/ImmuneBuilder
pypi: https://pypi.org/project/ImmuneBuilder/

Cite

@article{abanades2023immunebuilder,
  title={ImmuneBuilder: Deep-Learning models for predicting the structures of immune proteins},
  author={Abanades, Brennan and Wong, Wing Ki and Boyles, Fergus and Georges, Guy and Bujotzek, Alexander and Deane, Charlotte M},
  journal={Communications Biology},
  volume={6},
  pages={575},
  year={2023},
  doi={10.1038/s42003-023-04927-7}
}

ImmuneBuilder¶

At a glance¶

API & schema¶

fold¶

Usage¶

Overview¶

Architecture¶

Capabilities & Limitations¶

Usage Examples¶

Antibody structure prediction¶

Nanobody structure prediction¶

TCR structure prediction¶

Architecture & training¶

Architecture¶

Model Type & Innovation¶

Parameters & Layers¶

Training Data¶

Loss Function & Objective¶

Tokenization / Input Processing¶

Performance & Benchmarks¶

Published Benchmarks¶

Antibody Structure Prediction (ABodyBuilder2)¶

Nanobody Structure Prediction (NanoBodyBuilder2)¶

TCR Structure Prediction (TCRBuilder2)¶

BioLM Verification Results¶

Comparison to Alternatives¶

Strengths & Limitations¶

Pros¶

Cons¶

Known Failure Modes¶

Implementation Details¶

Inference Pipeline¶

Memory & Compute Profile¶

Determinism & Reproducibility¶

Caching Behavior¶

Versions & Changelog¶

Biology¶

Molecule Coverage¶

Primary Molecule Type(s)¶

Cross-Applicability¶

Biological Problems Addressed¶

Antibody Structure Prediction¶

Nanobody Structure Prediction¶

TCR Structure Prediction¶

Applied Use Cases¶

Related Models¶

Predecessor Models¶

Complementary Models¶

Alternative Models¶

Biological Background¶

Adaptive Immune Receptors¶

Immunoglobulin Fold¶

CDR Loop Diversity¶

Nanobodies vs Conventional Antibodies¶

Sources & license¶

`fold`¶