AntiFold¶

Antibody-specific inverse folding model that designs CDR and framework sequences conditioned on 3D backbone structure, supporting conventional antibodies and nanobodies.

License: BSD-3-Clause · Molecules: antibody, nanobody · Tasks: inverse_folding, embedding

Actions: encode, generate, score, log_prob · Variants: 1

At a glance¶

Use it when

Designing CDR variant libraries for phage or yeast display campaigns where structural compatibility with a known backbone conformation is required
Humanizing a non-human antibody by redesigning framework regions while keeping CDR sequences fixed, using structure-informed suggestions
Scoring how well an existing antibody sequence fits its observed crystal structure to identify structurally strained or liability-prone positions
Generating diverse CDR-H3 sequences conditioned on a known binding-competent backbone geometry for affinity maturation
Extracting antibody structural embeddings for downstream ML tasks such as clustering, paratope prediction, or developability scoring
Optimizing nanobody (VHH) CDR loops when a crystal or cryo-EM structure of the nanobody is available
Comparing the structural fitness of wild-type versus engineered antibody variants using per-residue log-probability profiles
Building focused combinatorial libraries targeting specific CDR subsets (e.g., CDRH1 + CDRH2 only) with controlled expected variation

Strengths

Antibody-specialized inverse folding with significantly higher CDR sequence recovery than general-purpose models (ESM-IF1, ProteinMPNN) on Fab structures, as shown in Hoie et al. 2024 and PLoS ONE 2025 benchmark
IMGT-aware region targeting allows precise control over which CDRs or framework regions to redesign (e.g., CDRH3-only, all CDRs, framework-only for humanization)
Supports both conventional paired antibodies (VH/VL) and single-domain nanobodies (VHH) with dedicated chain modes
High-throughput library generation: can produce up to 50,000 structure-compatible sequences per request with tunable diversity via sampling temperature
Lightweight CPU-only inference (2 GB RAM, no GPU required), enabling fast and cost-effective batch processing
Antigen-context conditioning: including the antigen chain as structural context improves design quality for interface-proximal residues
Multiple output modes in a single model: sequence generation, per-residue log-probabilities, global scoring, and residue-level embeddings
Fine-tuned from ESM-IF1 on SAbDab crystallographic structures, inheriting general inverse folding knowledge while specializing for immunoglobulin folds

Limitations

Requires a 3D backbone structure as input (PDB format with IMGT numbering); cannot operate on sequence alone
Not applicable to non-antibody proteins: training is limited to immunoglobulin variable domains from SAbDab, so predictions on general proteins are unreliable
Training data is biased toward human and mouse antibodies; performance on antibodies from other species (rabbit, chicken, shark) is less validated
Does not model antigen-antibody binding affinity directly; designed sequences are structurally compatible but not guaranteed to bind the target antigen
Nanobody training set is smaller than the conventional antibody set, so CDR predictions for VHH may be less diverse
Cannot design constant region (Fc) sequences; limited to variable domain engineering only
Autoregressive decoder means sequence generation is sequential, which adds latency compared to single-pass masked models for very large batch sizes
Relies on the accuracy of the input structure: errors in the backbone (e.g., from low-confidence computational models) propagate directly into sequence predictions

Reach for something else when

You need to design sequences for non-antibody proteins such as enzymes, receptors, or de novo scaffolds (use mpnn or esm_if1 instead -- they handle arbitrary protein backbones)
No 3D structure is available and you want sequence-only antibody design or scoring (use ablang2 for antibody sequence likelihood or igbert for paired heavy/light analysis)
You need to predict or generate the 3D structure of an antibody from sequence (use abodybuilder3 or immunefold for antibody structure prediction)
You want to predict binding affinity or antigen specificity rather than structural compatibility of sequences (use specialized binding predictors or docking tools)
You need to design multi-domain constructs including Fc regions, bispecific formats, or full-length IgG engineering (AntiFold only handles variable domains)
You are working with T-cell receptors (TCRs), which have different CDR definitions and structural conventions not represented in AntiFold training data
You need general protein fitness prediction from sequence alone without structural context (use esm2 pseudo-log-likelihoods or esmc embeddings instead)

Alternatives

Model	Better when	Worse when
mpnn	Designing sequences for any non-antibody protein or multi-chain complex; ProteinMPNN handles arbitrary backbone geometries and is validated across diverse folds.	When the target is an antibody or nanobody; it lacks IMGT-aware region targeting and achieves lower CDR sequence recovery on immunoglobulin structures.
esm_if1	General proteins, or when you want the un-specialized base model covering all CATH 4.3 folds.	Antibody CDR/framework design; AntiFold fine-tunes ESM-IF1 on SAbDab and outperforms it on antibody sequence recovery.

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.

`encode`¶

Call it

curl -X POST http://127.0.0.1:8000/api/v1/antifold/encode \
  -H "Content-Type: application/json" \
  -d '{
  "params": {},
  "items": [
    {
      "pdb": "<contents of a .pdb file>"
    }
  ]
}'

Request — AntiFoldEncodeRequest

Field	Type	Required	Constraints	Description
`params`	AntiFoldEncodeRequestParams	yes		Parameters controlling this action; required because they carry the PDB chain selectors (at least one of heavy_chain_id / light_chain_id must be provided).
`items`	list[AntiFoldBaseRequestItem]	yes	items 1–32	Batch of inputs to process in a single request. Up to 32 structures per request.

Nested types

AntiFoldBaseRequestItem

Field	Type	Required	Constraints	Description
`pdb`	string	yes	len 1–2500000	Input structure in PDB format.

AntiFoldEncodeIncludeOptions

Allowed values: mean, per_residue, per_residue, logits

AntiFoldEncodeRequestParams

Field	Type	Required	Constraints	Description
`heavy_chain_id`	string \| null	no		PDB chain identifier for the antibody heavy chain (VH) or nanobody (VHH) chain. For nanobody inputs, omit light_chain_id.
`light_chain_id`	string \| null	no		PDB chain identifier for the antibody light chain (VL).
`antigen_chain_id`	string \| null	no		Optional PDB chain identifier for the antigen chain, providing structural context during inference.
`include`	list[AntiFoldEncodeIncludeOptions]	no	default `['mean']`	Optional outputs to compute and include in the response.

Raw JSON Schema

{
  "$defs": {
    "AntiFoldBaseRequestItem": {
      "additionalProperties": false,
      "properties": {
        "pdb": {
          "description": "Input structure in PDB format.",
          "maxLength": 2500000,
          "minLength": 1,
          "title": "Pdb",
          "type": "string"
        }
      },
      "required": [
        "pdb"
      ],
      "title": "AntiFoldBaseRequestItem",
      "type": "object"
    },
    "AntiFoldEncodeIncludeOptions": {
      "enum": [
        "mean",
        "per_residue",
        "per_residue",
        "logits"
      ],
      "title": "AntiFoldEncodeIncludeOptions",
      "type": "string"
    },
    "AntiFoldEncodeRequestParams": {
      "additionalProperties": false,
      "properties": {
        "heavy_chain_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "PDB chain identifier for the antibody heavy chain (VH) or nanobody (VHH) chain. For nanobody inputs, omit light_chain_id.",
          "title": "Heavy Chain Id"
        },
        "light_chain_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "PDB chain identifier for the antibody light chain (VL).",
          "title": "Light Chain Id"
        },
        "antigen_chain_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Optional PDB chain identifier for the antigen chain, providing structural context during inference.",
          "title": "Antigen Chain Id"
        },
        "include": {
          "description": "Optional outputs to compute and include in the response.",
          "items": {
            "$ref": "#/$defs/AntiFoldEncodeIncludeOptions"
          },
          "title": "Include",
          "type": "array",
          "default": [
            "mean"
          ]
        }
      },
      "title": "AntiFoldEncodeRequestParams",
      "type": "object"
    }
  },
  "additionalProperties": false,
  "properties": {
    "params": {
      "$ref": "#/$defs/AntiFoldEncodeRequestParams",
      "description": "Parameters controlling this action; required because they carry the PDB chain selectors (at least one of heavy_chain_id / light_chain_id must be provided)."
    },
    "items": {
      "description": "Batch of inputs to process in a single request. Up to 32 structures per request.",
      "items": {
        "$ref": "#/$defs/AntiFoldBaseRequestItem"
      },
      "maxItems": 32,
      "minItems": 1,
      "title": "Items",
      "type": "array"
    }
  },
  "required": [
    "params",
    "items"
  ],
  "title": "AntiFoldEncodeRequest",
  "type": "object"
}

Response — AntiFoldEncodeResponse

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

Nested types

AntiFoldEncodeResponseResult

Field	Type	Required	Description
`embeddings`	list[number] \| null	no	Mean-pooled embedding vector for the sequence.
`residue_embeddings`	list[list[number]] \| null	no	Per-residue embedding vectors.
`logits`	list[list[number]] \| null	no	Per-position logits over the model vocabulary.
`pdb_posins`	list[integer] \| null	no	IMGT-based residue position numbers for each position in the output.
`pdb_chain`	list[string] \| null	no	PDB chain identifier for each output position.
`pdb_res`	list[string] \| null	no	Native amino-acid residue type at each output position.
`top_res`	list[string] \| null	no	Highest-probability predicted amino acid at each position.
`perplexity`	list[number] \| null	no	Per-position perplexity values for the sequence under the model (lower means more likely).
`vocab_tokens`	list[string] \| null	no	Vocabulary token order corresponding to the logits columns.

Raw JSON Schema

{
  "$defs": {
    "AntiFoldEncodeResponseResult": {
      "exclude_none": true,
      "exclude_unset": true,
      "properties": {
        "embeddings": {
          "anyOf": [
            {
              "items": {
                "type": "number"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Mean-pooled embedding vector for the sequence.",
          "title": "Embeddings"
        },
        "residue_embeddings": {
          "anyOf": [
            {
              "items": {
                "items": {
                  "type": "number"
                },
                "type": "array"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Per-residue embedding vectors.",
          "title": "Residue Embeddings"
        },
        "logits": {
          "anyOf": [
            {
              "items": {
                "items": {
                  "type": "number"
                },
                "type": "array"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Per-position logits over the model vocabulary.",
          "title": "Logits"
        },
        "pdb_posins": {
          "anyOf": [
            {
              "items": {
                "type": "integer"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "IMGT-based residue position numbers for each position in the output.",
          "title": "Pdb Posins"
        },
        "pdb_chain": {
          "anyOf": [
            {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "PDB chain identifier for each output position.",
          "title": "Pdb Chain"
        },
        "pdb_res": {
          "anyOf": [
            {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Native amino-acid residue type at each output position.",
          "title": "Pdb Res"
        },
        "top_res": {
          "anyOf": [
            {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Highest-probability predicted amino acid at each position.",
          "title": "Top Res"
        },
        "perplexity": {
          "anyOf": [
            {
              "items": {
                "type": "number"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Per-position perplexity values for the sequence under the model (lower means more likely).",
          "title": "Perplexity"
        },
        "vocab_tokens": {
          "anyOf": [
            {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Vocabulary token order corresponding to the logits columns.",
          "title": "Vocab Tokens"
        }
      },
      "title": "AntiFoldEncodeResponseResult",
      "type": "object"
    }
  },
  "properties": {
    "results": {
      "description": "Per-input results, returned in the same order as the request items.",
      "items": {
        "$ref": "#/$defs/AntiFoldEncodeResponseResult"
      },
      "title": "Results",
      "type": "array"
    }
  },
  "required": [
    "results"
  ],
  "title": "AntiFoldEncodeResponse",
  "type": "object"
}

`generate`¶

Call it

curl -X POST http://127.0.0.1:8000/api/v1/antifold/generate \
  -H "Content-Type: application/json" \
  -d '{
  "params": {},
  "items": [
    {
      "pdb": "<contents of a .pdb file>"
    }
  ]
}'

Request — AntiFoldGenerateRequest

Field	Type	Required	Constraints	Description
`params`	AntiFoldGenerateRequestParams	yes		Parameters controlling this action; required because they carry the PDB chain selectors (at least one of heavy_chain_id / light_chain_id must be provided).
`items`	list[AntiFoldBaseRequestItem]	yes	items 1–1	Batch of inputs to process in a single request. Up to 1 structure per request.

Nested types

AntiFoldBaseRequestItem

Field	Type	Required	Constraints	Description
`pdb`	string	yes	len 1–2500000	Input structure in PDB format.

AntiFoldGenerateIncludeOptions

Allowed values: logprobs, logits

AntiFoldGenerateRequestParams

Field	Type	Required	Constraints	Description
`heavy_chain_id`	string \| null	no		PDB chain identifier for the antibody heavy chain (VH) or nanobody (VHH) chain. For nanobody inputs, omit light_chain_id.
`light_chain_id`	string \| null	no		PDB chain identifier for the antibody light chain (VL).
`antigen_chain_id`	string \| null	no		Optional PDB chain identifier for the antigen chain, providing structural context during inference.
`seed`	integer \| null	no		Random seed for reproducible sampling.
`include`	list[AntiFoldGenerateIncludeOptions] \| null	no		Optional outputs to compute and include in the response.
`num_seq_per_target`	integer	no	≥1; ≤50000; default `1`	Number of sequences to generate per input.
`sampling_temp`	number	no	≥0.0; ≤4.0; default `0.2`	Sampling temperature; higher values increase diversity.
`regions`	list[AntiFoldValidRegions] \| list[integer]	no	default `['CDR1', 'CDR2', 'CDR3']`	Antibody regions to redesign; accepts named regions (e.g. "CDR3", "FWH1") or a list of 1-based residue positions.
`limit_expected_variation`	boolean \| null	no	default `False`	If true, constrain sequence sampling to the natural variation range observed in antibody databases.
`exclude_heavy`	boolean \| null	no	default `False`	If true, exclude the heavy chain from sequence sampling (the light chain is designed instead).
`exclude_light`	boolean \| null	no	default `False`	If true, exclude the light chain from sequence sampling (the heavy chain is designed instead).

AntiFoldValidRegions

Allowed values: all, allH, allL, FWH, FWL, CDRH, CDRL, FW1, FWH1, FWL1, CDR1, CDRH1, CDRL1, FW2, FWH2, FWL2, CDR2, CDRH2, CDRL2, FW3, FWH3, FWL3, CDR3, CDRH3, CDRL3, FW4, FWH4, FWL4

Raw JSON Schema

{
  "$defs": {
    "AntiFoldBaseRequestItem": {
      "additionalProperties": false,
      "properties": {
        "pdb": {
          "description": "Input structure in PDB format.",
          "maxLength": 2500000,
          "minLength": 1,
          "title": "Pdb",
          "type": "string"
        }
      },
      "required": [
        "pdb"
      ],
      "title": "AntiFoldBaseRequestItem",
      "type": "object"
    },
    "AntiFoldGenerateIncludeOptions": {
      "enum": [
        "logprobs",
        "logits"
      ],
      "title": "AntiFoldGenerateIncludeOptions",
      "type": "string"
    },
    "AntiFoldGenerateRequestParams": {
      "additionalProperties": false,
      "properties": {
        "heavy_chain_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "PDB chain identifier for the antibody heavy chain (VH) or nanobody (VHH) chain. For nanobody inputs, omit light_chain_id.",
          "title": "Heavy Chain Id"
        },
        "light_chain_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "PDB chain identifier for the antibody light chain (VL).",
          "title": "Light Chain Id"
        },
        "antigen_chain_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Optional PDB chain identifier for the antigen chain, providing structural context during inference.",
          "title": "Antigen Chain Id"
        },
        "seed": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Random seed for reproducible sampling.",
          "title": "Seed"
        },
        "include": {
          "anyOf": [
            {
              "items": {
                "$ref": "#/$defs/AntiFoldGenerateIncludeOptions"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Optional outputs to compute and include in the response.",
          "title": "Include"
        },
        "num_seq_per_target": {
          "default": 1,
          "description": "Number of sequences to generate per input.",
          "maximum": 50000,
          "minimum": 1,
          "title": "Num Seq Per Target",
          "type": "integer"
        },
        "sampling_temp": {
          "default": 0.2,
          "description": "Sampling temperature; higher values increase diversity.",
          "maximum": 4.0,
          "minimum": 0.0,
          "title": "Sampling Temp",
          "type": "number"
        },
        "regions": {
          "anyOf": [
            {
              "items": {
                "$ref": "#/$defs/AntiFoldValidRegions"
              },
              "type": "array"
            },
            {
              "items": {
                "type": "integer"
              },
              "type": "array"
            }
          ],
          "description": "Antibody regions to redesign; accepts named regions (e.g. \"CDR3\", \"FWH1\") or a list of 1-based residue positions.",
          "title": "Regions",
          "default": [
            "CDR1",
            "CDR2",
            "CDR3"
          ]
        },
        "limit_expected_variation": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": false,
          "description": "If true, constrain sequence sampling to the natural variation range observed in antibody databases.",
          "title": "Limit Expected Variation"
        },
        "exclude_heavy": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": false,
          "description": "If true, exclude the heavy chain from sequence sampling (the light chain is designed instead).",
          "title": "Exclude Heavy"
        },
        "exclude_light": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": false,
          "description": "If true, exclude the light chain from sequence sampling (the heavy chain is designed instead).",
          "title": "Exclude Light"
        }
      },
      "title": "AntiFoldGenerateRequestParams",
      "type": "object"
    },
    "AntiFoldValidRegions": {
      "enum": [
        "all",
        "allH",
        "allL",
        "FWH",
        "FWL",
        "CDRH",
        "CDRL",
        "FW1",
        "FWH1",
        "FWL1",
        "CDR1",
        "CDRH1",
        "CDRL1",
        "FW2",
        "FWH2",
        "FWL2",
        "CDR2",
        "CDRH2",
        "CDRL2",
        "FW3",
        "FWH3",
        "FWL3",
        "CDR3",
        "CDRH3",
        "CDRL3",
        "FW4",
        "FWH4",
        "FWL4"
      ],
      "title": "AntiFoldValidRegions",
      "type": "string"
    }
  },
  "additionalProperties": false,
  "properties": {
    "params": {
      "$ref": "#/$defs/AntiFoldGenerateRequestParams",
      "description": "Parameters controlling this action; required because they carry the PDB chain selectors (at least one of heavy_chain_id / light_chain_id must be provided)."
    },
    "items": {
      "description": "Batch of inputs to process in a single request. Up to 1 structure per request.",
      "items": {
        "$ref": "#/$defs/AntiFoldBaseRequestItem"
      },
      "maxItems": 1,
      "minItems": 1,
      "title": "Items",
      "type": "array"
    }
  },
  "required": [
    "params",
    "items"
  ],
  "title": "AntiFoldGenerateRequest",
  "type": "object"
}

Response — AntiFoldGenerateResponse

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

Nested types

AntiFoldGenerateResponseResult

Field	Type	Required	Description
`sequences`	list[AntiFoldGenerateResponseResultSamples]	yes	Generated antibody sequence samples for this input.
`logprobs`	list[list[number]] \| null	no	Per-position softmax log-probabilities over the vocabulary (included when logprobs is in the include list).
`logits`	list[list[number]] \| null	no	Per-position logits over the model vocabulary.
`pdb_posins`	list[integer] \| null	no	IMGT-based residue position numbers for each position in the output.
`pdb_chain`	list[string] \| null	no	PDB chain identifier for each output position.
`pdb_res`	list[string] \| null	no	Native amino-acid residue type at each output position.
`top_res`	list[string] \| null	no	Highest-probability predicted amino acid at each position.
`perplexity`	list[number] \| null	no	Per-position perplexity values for the sequence under the model (lower means more likely).
`vocab_tokens`	list[string] \| null	no	Vocabulary token order corresponding to the logits columns.

AntiFoldGenerateResponseResultSamples

Field	Type	Required	Description
`global_score`	number	yes	Mean per-residue inverse-folding log-likelihood over the full antibody sequence given the backbone structure.
`score`	number	yes	Mean per-residue inverse-folding log-likelihood over the designed region(s) of this sample.
`heavy_chain`	string	yes	Antibody heavy-chain amino-acid sequence.
`light_chain`	string \| null	no	Antibody light-chain amino-acid sequence.
`temperature`	number	yes	Sampling temperature; higher values increase diversity.
`mutations`	integer	yes	Number of amino-acid mutations relative to the native input sequence.
`seq_recovery`	number	yes	Fraction of positions matching the native sequence (sequence recovery rate, 0–1).

Raw JSON Schema

{
  "$defs": {
    "AntiFoldGenerateResponseResult": {
      "exclude_none": true,
      "exclude_unset": true,
      "properties": {
        "sequences": {
          "description": "Generated antibody sequence samples for this input.",
          "items": {
            "$ref": "#/$defs/AntiFoldGenerateResponseResultSamples"
          },
          "title": "Sequences",
          "type": "array"
        },
        "logprobs": {
          "anyOf": [
            {
              "items": {
                "items": {
                  "type": "number"
                },
                "type": "array"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Per-position softmax log-probabilities over the vocabulary (included when logprobs is in the include list).",
          "title": "Logprobs"
        },
        "logits": {
          "anyOf": [
            {
              "items": {
                "items": {
                  "type": "number"
                },
                "type": "array"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Per-position logits over the model vocabulary.",
          "title": "Logits"
        },
        "pdb_posins": {
          "anyOf": [
            {
              "items": {
                "type": "integer"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "IMGT-based residue position numbers for each position in the output.",
          "title": "Pdb Posins"
        },
        "pdb_chain": {
          "anyOf": [
            {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "PDB chain identifier for each output position.",
          "title": "Pdb Chain"
        },
        "pdb_res": {
          "anyOf": [
            {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Native amino-acid residue type at each output position.",
          "title": "Pdb Res"
        },
        "top_res": {
          "anyOf": [
            {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Highest-probability predicted amino acid at each position.",
          "title": "Top Res"
        },
        "perplexity": {
          "anyOf": [
            {
              "items": {
                "type": "number"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Per-position perplexity values for the sequence under the model (lower means more likely).",
          "title": "Perplexity"
        },
        "vocab_tokens": {
          "anyOf": [
            {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Vocabulary token order corresponding to the logits columns.",
          "title": "Vocab Tokens"
        }
      },
      "required": [
        "sequences"
      ],
      "title": "AntiFoldGenerateResponseResult",
      "type": "object"
    },
    "AntiFoldGenerateResponseResultSamples": {
      "exclude_none": true,
      "exclude_unset": true,
      "properties": {
        "global_score": {
          "description": "Mean per-residue inverse-folding log-likelihood over the full antibody sequence given the backbone structure.",
          "title": "Global Score",
          "type": "number"
        },
        "score": {
          "description": "Mean per-residue inverse-folding log-likelihood over the designed region(s) of this sample.",
          "title": "Score",
          "type": "number"
        },
        "heavy_chain": {
          "description": "Antibody heavy-chain amino-acid sequence.",
          "title": "Heavy Chain",
          "type": "string"
        },
        "light_chain": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Antibody light-chain amino-acid sequence.",
          "title": "Light Chain"
        },
        "temperature": {
          "description": "Sampling temperature; higher values increase diversity.",
          "title": "Temperature",
          "type": "number"
        },
        "mutations": {
          "description": "Number of amino-acid mutations relative to the native input sequence.",
          "title": "Mutations",
          "type": "integer"
        },
        "seq_recovery": {
          "description": "Fraction of positions matching the native sequence (sequence recovery rate, 0\u20131).",
          "title": "Seq Recovery",
          "type": "number"
        }
      },
      "required": [
        "global_score",
        "score",
        "heavy_chain",
        "temperature",
        "mutations",
        "seq_recovery"
      ],
      "title": "AntiFoldGenerateResponseResultSamples",
      "type": "object"
    }
  },
  "properties": {
    "results": {
      "description": "Per-input results, returned in the same order as the request items.",
      "items": {
        "$ref": "#/$defs/AntiFoldGenerateResponseResult"
      },
      "title": "Results",
      "type": "array"
    }
  },
  "required": [
    "results"
  ],
  "title": "AntiFoldGenerateResponse",
  "type": "object"
}

`score`¶

Call it

curl -X POST http://127.0.0.1:8000/api/v1/antifold/score \
  -H "Content-Type: application/json" \
  -d '{
  "params": {},
  "items": [
    {
      "pdb": "<contents of a .pdb file>"
    }
  ]
}'

Request — AntiFoldPredictRequest

Field	Type	Required	Constraints	Description
`params`	AntiFoldPredictRequestParams	yes		Parameters controlling this action; required because they carry the PDB chain selectors (at least one of heavy_chain_id / light_chain_id must be provided).
`items`	list[AntiFoldBaseRequestItem]	yes	items 1–32	Batch of inputs to process in a single request. Up to 32 structures per request.

Nested types

AntiFoldBaseRequestItem

Field	Type	Required	Constraints	Description
`pdb`	string	yes	len 1–2500000	Input structure in PDB format.

AntiFoldPredictRequestParams

Field	Type	Required	Description
`heavy_chain_id`	string \| null	no	PDB chain identifier for the antibody heavy chain (VH) or nanobody (VHH) chain. For nanobody inputs, omit light_chain_id.
`light_chain_id`	string \| null	no	PDB chain identifier for the antibody light chain (VL).
`antigen_chain_id`	string \| null	no	Optional PDB chain identifier for the antigen chain, providing structural context during inference.

Raw JSON Schema

{
  "$defs": {
    "AntiFoldBaseRequestItem": {
      "additionalProperties": false,
      "properties": {
        "pdb": {
          "description": "Input structure in PDB format.",
          "maxLength": 2500000,
          "minLength": 1,
          "title": "Pdb",
          "type": "string"
        }
      },
      "required": [
        "pdb"
      ],
      "title": "AntiFoldBaseRequestItem",
      "type": "object"
    },
    "AntiFoldPredictRequestParams": {
      "additionalProperties": false,
      "properties": {
        "heavy_chain_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "PDB chain identifier for the antibody heavy chain (VH) or nanobody (VHH) chain. For nanobody inputs, omit light_chain_id.",
          "title": "Heavy Chain Id"
        },
        "light_chain_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "PDB chain identifier for the antibody light chain (VL).",
          "title": "Light Chain Id"
        },
        "antigen_chain_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Optional PDB chain identifier for the antigen chain, providing structural context during inference.",
          "title": "Antigen Chain Id"
        }
      },
      "title": "AntiFoldPredictRequestParams",
      "type": "object"
    }
  },
  "additionalProperties": false,
  "properties": {
    "params": {
      "$ref": "#/$defs/AntiFoldPredictRequestParams",
      "description": "Parameters controlling this action; required because they carry the PDB chain selectors (at least one of heavy_chain_id / light_chain_id must be provided)."
    },
    "items": {
      "description": "Batch of inputs to process in a single request. Up to 32 structures per request.",
      "items": {
        "$ref": "#/$defs/AntiFoldBaseRequestItem"
      },
      "maxItems": 32,
      "minItems": 1,
      "title": "Items",
      "type": "array"
    }
  },
  "required": [
    "params",
    "items"
  ],
  "title": "AntiFoldPredictRequest",
  "type": "object"
}

Response — AntiFoldScoreResponse

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

Nested types

AntiFoldScoreResponseResult

Field	Type	Required	Description
`global_score`	number	yes	Mean per-residue inverse-folding log-likelihood over the full antibody sequence given the backbone structure.
`heavy_chain`	string	yes	Antibody heavy-chain amino-acid sequence.
`light_chain`	string \| null	no	Antibody light-chain amino-acid sequence.

Raw JSON Schema

{
  "$defs": {
    "AntiFoldScoreResponseResult": {
      "exclude_none": true,
      "exclude_unset": true,
      "properties": {
        "global_score": {
          "description": "Mean per-residue inverse-folding log-likelihood over the full antibody sequence given the backbone structure.",
          "title": "Global Score",
          "type": "number"
        },
        "heavy_chain": {
          "description": "Antibody heavy-chain amino-acid sequence.",
          "title": "Heavy Chain",
          "type": "string"
        },
        "light_chain": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Antibody light-chain amino-acid sequence.",
          "title": "Light Chain"
        }
      },
      "required": [
        "global_score",
        "heavy_chain"
      ],
      "title": "AntiFoldScoreResponseResult",
      "type": "object"
    }
  },
  "properties": {
    "results": {
      "description": "Per-input results, returned in the same order as the request items.",
      "items": {
        "$ref": "#/$defs/AntiFoldScoreResponseResult"
      },
      "title": "Results",
      "type": "array"
    }
  },
  "required": [
    "results"
  ],
  "title": "AntiFoldScoreResponse",
  "type": "object"
}

`log_prob`¶

Call it

curl -X POST http://127.0.0.1:8000/api/v1/antifold/log_prob \
  -H "Content-Type: application/json" \
  -d '{
  "params": {},
  "items": [
    {
      "pdb": "<contents of a .pdb file>"
    }
  ]
}'

Request — AntiFoldPredictRequest

Field	Type	Required	Constraints	Description
`params`	AntiFoldPredictRequestParams	yes		Parameters controlling this action; required because they carry the PDB chain selectors (at least one of heavy_chain_id / light_chain_id must be provided).
`items`	list[AntiFoldBaseRequestItem]	yes	items 1–32	Batch of inputs to process in a single request. Up to 32 structures per request.

Nested types

AntiFoldBaseRequestItem

Field	Type	Required	Constraints	Description
`pdb`	string	yes	len 1–2500000	Input structure in PDB format.

AntiFoldPredictRequestParams

Field	Type	Required	Description
`heavy_chain_id`	string \| null	no	PDB chain identifier for the antibody heavy chain (VH) or nanobody (VHH) chain. For nanobody inputs, omit light_chain_id.
`light_chain_id`	string \| null	no	PDB chain identifier for the antibody light chain (VL).
`antigen_chain_id`	string \| null	no	Optional PDB chain identifier for the antigen chain, providing structural context during inference.

Raw JSON Schema

{
  "$defs": {
    "AntiFoldBaseRequestItem": {
      "additionalProperties": false,
      "properties": {
        "pdb": {
          "description": "Input structure in PDB format.",
          "maxLength": 2500000,
          "minLength": 1,
          "title": "Pdb",
          "type": "string"
        }
      },
      "required": [
        "pdb"
      ],
      "title": "AntiFoldBaseRequestItem",
      "type": "object"
    },
    "AntiFoldPredictRequestParams": {
      "additionalProperties": false,
      "properties": {
        "heavy_chain_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "PDB chain identifier for the antibody heavy chain (VH) or nanobody (VHH) chain. For nanobody inputs, omit light_chain_id.",
          "title": "Heavy Chain Id"
        },
        "light_chain_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "PDB chain identifier for the antibody light chain (VL).",
          "title": "Light Chain Id"
        },
        "antigen_chain_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Optional PDB chain identifier for the antigen chain, providing structural context during inference.",
          "title": "Antigen Chain Id"
        }
      },
      "title": "AntiFoldPredictRequestParams",
      "type": "object"
    }
  },
  "additionalProperties": false,
  "properties": {
    "params": {
      "$ref": "#/$defs/AntiFoldPredictRequestParams",
      "description": "Parameters controlling this action; required because they carry the PDB chain selectors (at least one of heavy_chain_id / light_chain_id must be provided)."
    },
    "items": {
      "description": "Batch of inputs to process in a single request. Up to 32 structures per request.",
      "items": {
        "$ref": "#/$defs/AntiFoldBaseRequestItem"
      },
      "maxItems": 32,
      "minItems": 1,
      "title": "Items",
      "type": "array"
    }
  },
  "required": [
    "params",
    "items"
  ],
  "title": "AntiFoldPredictRequest",
  "type": "object"
}

Response — AntiFoldLogProbResponse

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

Nested types

AntiFoldLogProbResponseResult

Field	Type	Required	Constraints	Description
`log_prob`	number	yes		Log-likelihood of the sequence under the model.

Raw JSON Schema

{
  "$defs": {
    "AntiFoldLogProbResponseResult": {
      "properties": {
        "log_prob": {
          "description": "Log-likelihood of the sequence under the model.",
          "title": "Log Prob",
          "type": "number"
        }
      },
      "required": [
        "log_prob"
      ],
      "title": "AntiFoldLogProbResponseResult",
      "type": "object"
    }
  },
  "properties": {
    "results": {
      "description": "Per-input results, returned in the same order as the request items.",
      "items": {
        "$ref": "#/$defs/AntiFoldLogProbResponseResult"
      },
      "title": "Results",
      "type": "array"
    }
  },
  "required": [
    "results"
  ],
  "title": "AntiFoldLogProbResponse",
  "type": "object"
}

Usage¶

One-line summary: Antibody-specific inverse folding model that designs CDR and framework sequences conditioned on 3D backbone structure, supporting conventional antibodies and nanobodies.

Overview¶

AntiFold is an inverse folding model for antibodies developed by Hoie et al. (2024) at the Oxford Protein Informatics Group (OPIG). It is built by fine-tuning ESM-IF1 on antibody-antigen structural data from the Structural Antibody Database (SAbDab), using IMGT numbering for consistent region identification.

Given a 3D antibody structure in PDB format, AntiFold predicts amino acid probabilities at each position, enabling structure-based sequence design for CDR optimization, humanization, and library generation. It supports conventional antibodies (VH/VL pairs), heavy-chain-only inputs, and nanobodies (VHH), with optional antigen chain context.

Architecture¶

Property	Value
Architecture	GNN encoder + autoregressive decoder (fine-tuned ESM-IF1)
Embedding dimensions	512
Training data	SAbDab antibody-antigen complexes (IMGT-numbered)
Input	PDB backbone coordinates (N, CA, C, O)
Output	Per-residue amino acid probabilities (20 standard amino acids)

Capabilities & Limitations¶

CAN be used for: - Designing CDR sequences conditioned on antibody backbone structure - Generating large sequence libraries (up to 50,000 sequences per request) for experimental screening - Computing structure-conditioned embeddings (mean or per-residue) for antibody structures - Scoring how well a native sequence fits its observed structure - Computing log-probabilities for sequence fitness assessment - Targeting specific regions: individual CDRs (CDRH1, CDRL2, etc.), all CDRs, framework regions, or specific residue positions - Working with conventional antibodies (VH/VL), heavy-chain-only, and nanobodies (VHH) - Including antigen chain context for interface-aware design

CANNOT be used for: - Sequence-only inputs (a 3D structure in PDB format is required) - General protein inverse folding (use ESM-IF1 or ProteinMPNN instead) - Constant region (Fc) engineering -- only variable domains are supported - Structure prediction (use ABodyBuilder3 or ESMFold to generate structures first) - Non-standard amino acids

Other considerations: - The generate action is stochastic by default; provide a seed for reproducibility - Generate batch size is limited to 1 PDB per request (encode/score/log_prob support up to 32) - PDB structures should use IMGT-compatible numbering for correct region identification

Usage Examples¶

Encode (extract embeddings)¶

from models.antifold.schema import (
    AntiFoldEncodeRequest,
    AntiFoldEncodeRequestParams,
    AntiFoldBaseRequestItem,
    AntiFoldEncodeIncludeOptions,
)

request = AntiFoldEncodeRequest(
    params=AntiFoldEncodeRequestParams(
        heavy_chain_id="H",
        light_chain_id="L",
        include=[AntiFoldEncodeIncludeOptions.MEAN],
    ),
    items=[AntiFoldBaseRequestItem(pdb=pdb_string)],
)

Generate (design new sequences)¶

from models.antifold.schema import (
    AntiFoldGenerateRequest,
    AntiFoldGenerateRequestParams,
    AntiFoldBaseRequestItem,
    AntiFoldValidRegions,
)

request = AntiFoldGenerateRequest(
    params=AntiFoldGenerateRequestParams(
        heavy_chain_id="H",
        light_chain_id="L",
        num_seq_per_target=100,
        sampling_temp=0.2,
        regions=[AntiFoldValidRegions.CDRH3],
        seed=42,
    ),
    items=[AntiFoldBaseRequestItem(pdb=pdb_string)],
)

Score (evaluate native sequence)¶

from models.antifold.schema import (
    AntiFoldPredictRequest,
    AntiFoldPredictRequestParams,
    AntiFoldBaseRequestItem,
)

request = AntiFoldPredictRequest(
    params=AntiFoldPredictRequestParams(
        heavy_chain_id="H",
        light_chain_id="L",
    ),
    items=[AntiFoldBaseRequestItem(pdb=pdb_string)],
)

Nanobody design¶

For nanobodies (VHH), supply only heavy_chain_id (no light_chain_id). The model automatically uses single-domain mode.

from models.antifold.schema import (
    AntiFoldGenerateRequest,
    AntiFoldGenerateRequestParams,
    AntiFoldBaseRequestItem,
    AntiFoldValidRegions,
)

request = AntiFoldGenerateRequest(
    params=AntiFoldGenerateRequestParams(
        heavy_chain_id="A",  # VHH chain; omit light_chain_id for nanobody mode
        num_seq_per_target=50,
        sampling_temp=0.3,
        regions=[AntiFoldValidRegions.CDR1, AntiFoldValidRegions.CDR2, AntiFoldValidRegions.CDR3],
    ),
    items=[AntiFoldBaseRequestItem(pdb=nanobody_pdb_string)],
)

Architecture & training¶

Architecture¶

Model Type & Innovation¶

AntiFold is an antibody-specific inverse folding model built by fine-tuning ESM-IF1 (Inverse Folding) on paired antibody-antigen structural data. While ESM-IF1 is a general-purpose protein inverse folding model, AntiFold specializes it for antibody sequences by training on antibody-antigen complexes from the Structural Antibody Database (SAbDab) with IMGT-numbered residues.

The key innovation is that AntiFold conditions sequence predictions on the 3D backbone structure of the antibody, including the antigen context when available. This allows it to propose amino acid substitutions that are structurally compatible with the antibody fold while maintaining or improving binding properties. Unlike sequence-only models, AntiFold captures the geometric constraints imposed by the CDR loop conformations.

The model uses a GNN-based encoder (from ESM-IF1) that processes backbone coordinates to produce structure-conditioned representations, followed by an autoregressive decoder that generates amino acid probabilities at each position.

Parameters & Layers¶

Component	Details
Architecture	GNN encoder + autoregressive decoder (ESM-IF1 backbone)
Base model	ESM-IF1 (ESM Inverse Folding 1)
Fine-tuning	Antibody-antigen complexes from SAbDab
Embedding dimensions	512
Vocabulary	20 standard amino acids
Input	Backbone atom coordinates (N, CA, C, O) from PDB structures
Output	Per-residue amino acid log-probabilities

Training Data¶

Property	Details
Base model training	ESM-IF1 trained on CATH 4.3 structures (12M backbones from ~19K structures)
Fine-tuning dataset	SAbDab (Structural Antibody Database) antibody-antigen complexes
Numbering scheme	IMGT (ImMunoGeneTics) numbering
Chain types	Heavy chain (VH), light chain (VL), nanobody (VHH)
Antigen context	Optional antigen chain included during training
Data augmentation	Structural noise and masking strategies for robust learning

Loss Function & Objective¶

AntiFold is trained with a cross-entropy loss over the 20 standard amino acid types at each residue position, conditioned on the 3D backbone coordinates. The training objective is:

L = -sum_i log P(aa_i | backbone_coordinates, context)

where the sum runs over all residue positions in the antibody chain(s) and the context includes neighboring residues and optional antigen coordinates.

Tokenization / Input Processing¶

Input format: PDB-format structure strings containing backbone atom coordinates
Chain specification: Users specify heavy chain, light chain (or nanobody chain), and optionally antigen chain by PDB chain ID
Coordinate extraction: Backbone atoms (N, CA, C, O) are extracted per residue using Biotite
IMGT numbering: Residues are mapped to IMGT positions for consistent CDR/framework region identification
Multi-chain handling: Heavy and light chains are processed together; antigen chain provides structural context
Graph construction: Backbone coordinates are converted to a graph representation for the GNN encoder

Performance & Benchmarks¶

Published Benchmarks¶

Inverse Folding Recovery Rate¶

AntiFold reports improved sequence recovery rates compared to ESM-IF1 and ProteinMPNN on antibody CDR regions:

Model	CDR-H3 Recovery ↑	Overall Recovery ↑	Notes
AntiFold	~38%	~45%	Antibody-specific fine-tuning
ESM-IF1	~28%	~38%	General protein inverse folding
ProteinMPNN	~30%	~40%	General protein design

Results are from the AntiFold paper (Hoie et al., 2024), evaluated on held-out SAbDab structures.

BioLM Verification Results¶

The BioLM implementation is verified against the original AntiFold codebase using test structures from PDB:

Test Structure	Action	Verification	Status
3HFM	encode	Cosine distance < 0.02, rel_tol 3e-4	PASS
8OI2 (IMGT)	encode	Cosine distance < 0.02, rel_tol 3e-4	PASS
3HFM	log_prob	rel_tol 1e-4	PASS
3HFM	score	rel_tol 1e-4	PASS
3HFM	generate	Structure validation (sequence count)	PASS
8OI2 (IMGT)	generate	Structure validation (sequence count)	PASS
6Y1L (IMGT)	generate	Structure validation (sequence count)	PASS

Comparison to Alternatives¶

Model	Task	Strength	When to prefer
AntiFold	Antibody inverse folding	Antibody-specific, CDR-aware	Antibody/nanobody design
ESM-IF1	General inverse folding	Broader protein coverage	Non-antibody proteins
ProteinMPNN	General inverse folding	Robust, well-validated	General protein design

Strengths & Limitations¶

Pros¶

Antibody-specialized: significantly better CDR sequence recovery than general inverse folding models
Supports both conventional antibodies (VH/VL) and nanobodies (VHH)
Antigen-aware: can condition sequence design on the antigen interface
Region-specific design: users can target specific CDRs, framework regions, or individual positions
Lightweight: runs on CPU (no GPU required), making it cost-effective
Provides multiple output types: sequences, embeddings, log-probabilities, and per-position logits

Cons¶

Limited to antibody and nanobody structures; not suitable for general proteins
Requires a 3D structure as input (PDB format), not sequence-only
Based on IMGT numbering; structures must be IMGT-numbered or compatible
Single variant only (no model size options)
CDR-H3 is inherently difficult to predict due to high structural diversity

Known Failure Modes¶

Structures with unusual or non-standard IMGT numbering may produce incorrect region assignments
Very long CDR-H3 loops (>20 residues) may have lower prediction quality
Antigen chains that are far from the antibody paratope provide minimal useful context
PDB files with missing backbone atoms will cause processing errors

Implementation Details¶

Inference Pipeline¶

Request
  |-- 1. Validate PDB string and chain IDs
  |-- 2. Write PDB to temporary file
  |-- 3. Build input DataFrame (chain assignments)
  |-- 4. Extract backbone coordinates (Biotite)
  |-- 5. Construct graph representation
  |-- 6. Forward pass through GNN encoder
  |-- 7. Autoregressive decoding (for generate) or single-pass (for encode/score)
  |-- 8. Post-process outputs (logits, embeddings, sequences)
  |-- 9. Clean up temporary files
  |-- 10. Format and return response

Memory & Compute Profile¶

Resource	Value
GPU	None (CPU-only)
Memory	2 GB RAM
CPU	1.0 cores
Batch size (encode/score/log_prob)	32
Batch size (generate)	1

The model runs entirely on CPU, which is sufficient given the relatively small model size. The GNN encoder processes backbone coordinates efficiently without requiring GPU acceleration.

Determinism & Reproducibility¶

Setting	Value
Torch manual seed	Yes (42 at model load)
CUDA manual seed	Yes (42, if available)
NumPy seed	Set per-request for generate
User-specified seed	Supported via `seed` parameter in generate

The encode, score, and log_prob actions are deterministic. The generate action is stochastic by default (time-based seed) but can be made reproducible by providing a seed parameter.

Caching Behavior¶

Response caching is available as an optional, off-by-default gateway feature (BIOLM_CACHE_ENABLED) -- see the gateway docs; it is not handled by the model container. Cache keys are determined by the full request payload (PDB content + parameters).

Versions & Changelog¶

Version	Date	Changes
v1	2024	Initial implementation with encode, generate, score, log_prob actions

Biology¶

Molecule Coverage¶

Primary Molecule Type(s)¶

AntiFold is designed for antibody and nanobody structures. Specifically:

Conventional antibodies: Paired heavy chain (VH) and light chain (VL) variable regions
Nanobodies: Single-domain antibodies (VHH) derived from camelid heavy-chain-only antibodies
Antibody-antigen complexes: When antigen structure is available, it can be included as context

The model operates on 3D structures in PDB format and uses IMGT numbering to identify CDR and framework regions. It is trained on structures from the Structural Antibody Database (SAbDab), which predominantly contains crystallographic structures of human and mouse antibodies, with some representation from other species.

Important coverage notes: - Works best on structures with standard IMGT numbering - Handles both paired (VH/VL) and unpaired (VH-only or VHH) formats - Antigen chain inclusion is optional but improves context-aware design - Not designed for constant region (Fc) engineering -- only variable domains

Cross-Applicability¶

Molecule Type	Applicability	Evidence	Caveats
Conventional antibodies (VH/VL)	High	Primary training target	Requires PDB structure input
Nanobodies (VHH)	High	Explicitly supported with dedicated chain mode	Smaller training set than conventional antibodies
T-cell receptors (TCRs)	Low	Not trained on TCR structures	Structural similarities exist but CDR definitions differ
General proteins	Not applicable	Model is antibody-specific	Use ESM-IF1 or ProteinMPNN instead
Peptides	Not applicable	Too short for meaningful inverse folding	Not relevant

Biological Problems Addressed¶

Antibody CDR Optimization¶

Biological context: Complementarity-Determining Regions (CDRs) are the hypervariable loops of antibodies that directly contact antigens. Optimizing CDR sequences while maintaining the structural fold is central to improving antibody affinity, specificity, and developability. Experimentally, this requires constructing and screening large combinatorial libraries, which is expensive and time-consuming.

How AntiFold helps: Given a known antibody structure (e.g., from X-ray crystallography or computational modeling), AntiFold can propose alternative CDR sequences that are compatible with the observed backbone conformation. Users can target specific CDRs (e.g., CDRH3 only, or all CDRs simultaneously) and control sequence diversity via sampling temperature. The model outputs multiple candidate sequences ranked by global score, allowing prioritization for experimental testing.

Output interpretation: The global_score reflects the overall log-likelihood of the designed sequence given the structure. Higher (less negative) scores indicate better structural compatibility. The seq_recovery metric shows what fraction of positions match the wild-type sequence, and mutations counts the number of changed positions.

Antibody Humanization¶

Biological context: Therapeutic antibodies often originate from non-human species (typically mouse). To reduce immunogenicity in human patients, the antibody framework regions must be humanized -- replaced with human-like sequences -- while preserving the antigen-binding CDRs. Traditional humanization requires expert knowledge and iterative experimental validation.

How AntiFold helps: By conditioning on the antibody backbone structure, AntiFold can suggest framework sequences that are structurally compatible with the existing CDR conformations. Users can restrict redesign to framework regions only (FWH, FWL, or specific frameworks like FWH1-FWH4) while keeping CDR sequences fixed. This provides a structure-informed starting point for humanization that preserves the geometric constraints needed for antigen binding.

Antibody Sequence Liability Assessment¶

Biological context: Certain amino acid motifs in antibodies are associated with manufacturing or clinical liabilities, such as deamidation (NG motifs), oxidation (exposed methionine), or aggregation-prone hydrophobic patches. Identifying and removing these liabilities while maintaining function is a key step in antibody developability assessment.

How AntiFold helps: The score action evaluates how well the current sequence fits the observed structure, providing a global compatibility score. The log_prob action gives a per-structure log-probability that can be used to compare wild-type versus engineered variants. Positions with low per-residue log-probabilities may indicate residues that are structurally strained and could be targets for optimization.

Structure-Based Antibody Library Design¶

Biological context: Synthetic antibody libraries are widely used in phage display, yeast display, and other selection platforms. Designing libraries with high functional diversity while maintaining structural integrity requires balancing sequence variation with fold stability.

How AntiFold helps: The generate action can produce large numbers (up to 50,000 per request) of structure-compatible sequences across specified regions. By using the regions parameter to target specific CDRs and adjusting sampling_temp to control diversity, users can design focused libraries enriched for sequences that are compatible with the target backbone conformation. The limit_expected_variation option further constrains sampling to the natural range of variation observed in known antibody structures.

Applied Use Cases¶

Since its publication in 2024, AntiFold has been evaluated in several applied and benchmark studies:

CDR benchmark (PLoS ONE 2025) — Li et al. (BioMap Research) benchmarked AntiFold against ProteinMPNN, ESM-IF, and LM-Design on Fab and VHH CDR sequence recovery tasks, finding AntiFold superior for conventional Fab antibody design. (DOI: 10.1371/journal.pone.0324566)
Computational antibody design pipeline (Nature 2025) — Demonstrated in the RFdiffusion antibody paper (Bennett et al.) as part of a multi-stage pipeline where inverse folding tools including AntiFold are used for CDR sequence optimization after backbone diffusion. (DOI: 10.1038/s41586-025-09721-5)
Binding affinity maturation benchmark (AbBiBench 2025) — Benchmarked AntiFold alongside 14 other protein models on 184,500+ experimental antibody-antigen binding measurements. Inverse folding models as a class outperformed all other model categories, though AntiFold showed a small correlation drop versus ESM-IF in the complex-level binding prediction setting, suggesting some trade-offs from antibody-specific fine-tuning. (arXiv: 2506.04235)
nanoFOLD comparison (bioRxiv 2025) — A nanobody-specific inverse folding model (nanoFOLD) fine-tuned from ESM-IF was benchmarked directly against AntiFold on VHH sequence recovery and binder enrichment. nanoFOLD outperforms AntiFold on nanobody-specific tasks (75% VHH recovery vs AntiFold), while AntiFold retains superiority on Fab antibody design, quantifying the domain-specificity trade-off. (DOI: 10.1101/2025.04.29.651236)
GPCR-peptide drug discovery benchmark (Briefings in Bioinformatics 2025) — Contextualizes antibody-specific inverse folding tools (including AntiFold) in the broader landscape of structure prediction and sequence design for drug discovery. (DOI: 10.1093/bib/bbaf186)

Predecessor Models¶

ESM-IF1 (Hsu et al., 2022): The general-purpose inverse folding model that AntiFold is built upon. ESM-IF1 uses a GNN encoder to process backbone coordinates and an autoregressive decoder for sequence generation. It was trained on CATH 4.3 structures covering diverse protein folds. AntiFold fine-tunes ESM-IF1 specifically for antibody structures, yielding significant improvements in CDR sequence recovery.

Complementary Models¶

AntiFold works well in combination with other models in this catalog:

Structure prediction models (e.g., ABodyBuilder3, ESMFold): Generate the input 3D structure needed by AntiFold when an experimental structure is unavailable. Pipeline: predict structure with ABodyBuilder3, then design sequences with AntiFold.
Protein language models (e.g., ESM2): Use ESM2 pseudo-log-likelihoods to independently score AntiFold-designed sequences for general protein fitness.

Alternative Models¶

Alternative	Advantage over AntiFold	Disadvantage vs AntiFold
ESM-IF1	Handles any protein, not just antibodies	Lower CDR recovery rates on antibodies
ProteinMPNN	Well-validated, handles multi-chain complexes	Not antibody-specialized, no IMGT-aware regions
AbLang / IgBert	Sequence-only input (no structure needed)	Cannot condition on 3D structure

Biological Background¶

Antibody Structure¶

Antibodies (immunoglobulins) are Y-shaped proteins produced by B cells of the immune system. Each antibody consists of two heavy chains and two light chains linked by disulfide bonds. The antigen-binding site is formed by the variable domains of the heavy chain (VH) and light chain (VL).

Variable domain architecture:

Variable Domain (VH or VL)
  |-- Framework Region 1 (FR1/FW1)
  |-- CDR1 (Complementarity-Determining Region 1)
  |-- Framework Region 2 (FR2/FW2)
  |-- CDR2
  |-- Framework Region 3 (FR3/FW3)
  |-- CDR3
  |-- Framework Region 4 (FR4/FW4)

Framework regions (FR/FW): Structurally conserved beta-sheet scaffold that maintains the immunoglobulin fold. Relatively tolerant of sequence variation within the same germline family.
CDRs: Hypervariable loops that protrude from the framework scaffold and make direct contact with the antigen. CDR-H3 (the third CDR of the heavy chain) is the most diverse in both sequence and structure, and is often the primary determinant of antigen specificity.

IMGT Numbering¶

The IMGT (ImMunoGeneTics) numbering system provides a standardized way to number antibody residues across different species and germlines. It assigns fixed position numbers to framework and CDR residues, enabling consistent identification of equivalent positions across different antibodies. AntiFold uses IMGT numbering internally to define regions for targeted sequence design.

Nanobodies¶

Nanobodies (VHH domains) are single-domain antibodies derived from the heavy-chain-only antibodies found in camelids (llamas, camels, alpacas). They lack a light chain entirely, relying on an extended CDR-H3 loop and adapted framework residues to achieve antigen binding. Nanobodies are smaller (~15 kDa vs ~50 kDa for conventional Fab), more stable, and easier to produce, making them attractive for therapeutic and diagnostic applications.

Inverse Folding¶

Inverse folding is the computational problem of predicting which amino acid sequences are compatible with a given 3D backbone structure. It is the inverse of the protein folding problem (which predicts structure from sequence). In the context of antibody engineering, inverse folding enables structure-based sequence design: given a desired CDR loop conformation, what sequences will adopt that conformation?

This approach is particularly valuable for: - Affinity maturation: Proposing mutations in CDRs that maintain the binding geometry - Stability engineering: Identifying framework mutations that reinforce the immunoglobulin fold - Library design: Generating diverse but structurally viable sequence candidates for experimental screening

Sources & license¶

License: BSD-3-Clause (text)

Papers

AntiFold: Improved antibody structure-based design using inverse folding — Bioinformatics, 2024 · DOI arXiv

Source repositories

github: https://github.com/oxpig/AntiFold

Cite

@article{hoie2024antifold,
  title={AntiFold: Improved antibody structure-based design using inverse folding},
  author={Hoie, Magnus Haraldson and Hummer, Alissa M and Olsen, Tobias H and Nielsen, Morten and Deane, Charlotte M},
  journal={Bioinformatics},
  year={2024},
  doi={10.1093/bioinformatics/btae403}
}

AntiFold¶

At a glance¶

API & schema¶

encode¶

generate¶

score¶

log_prob¶

Usage¶

Overview¶

Architecture¶

Capabilities & Limitations¶

Usage Examples¶

Encode (extract embeddings)¶

Generate (design new sequences)¶

Score (evaluate native sequence)¶

Nanobody design¶

Architecture & training¶

Architecture¶

Model Type & Innovation¶

Parameters & Layers¶

Training Data¶

Loss Function & Objective¶

Tokenization / Input Processing¶

Performance & Benchmarks¶

Published Benchmarks¶

Inverse Folding Recovery Rate¶

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 CDR Optimization¶

Antibody Humanization¶

Antibody Sequence Liability Assessment¶

Structure-Based Antibody Library Design¶

Applied Use Cases¶

Related Models¶

Predecessor Models¶

Complementary Models¶

Alternative Models¶

Biological Background¶

Antibody Structure¶

IMGT Numbering¶

Nanobodies¶

Inverse Folding¶

Sources & license¶

`encode`¶

`generate`¶

`score`¶

`log_prob`¶