Proto is not affiliated with Meta AI. This toolkit is open source and builds on the implementation produced by this organization. Product names, logos, and trademarks are the property of their respective owners.

### ESMFold Structure Prediction (`esmfold-prediction`) Predicts the 3D structure of one or more protein chains from their sequences. Each input complex (a single chain, or several chains folded together) is run through ESMFold and returned as a predicted `Structure` per complex with confidence metrics: per-residue pLDDT, a predicted TM-score (pTM), and predicted aligned error. #### API Reference

Source List of complexes to predict structures for. Inherited from `StructurePredictionInput`. Each complex can contain one or more protein chains. The linked length actually folded (summed chain residues plus the inter-chain `chain_linker`, i.e. `len(chain_linker) * (num_chains - 1)`) must not exceed 2,400. Chains in the complex, in input order. Pre-computed MSAs, one entry per complex. Each entry is a `ComplexMSAs` (per-chain MSAs keyed by chain index); `paired=True` marks rows taxonomy-aligned across chains. Populated by preprocess() or supplied directly.

Source Residue numbering gap between chains in multi-chain structures. Used to ensure proper chain separation in the output PDB/CIF files. Higher values create larger gaps in residue numbering between chains. Must be at least 0. Default: 512. Amino acid sequence used to link chains internally for multi-chain prediction. ESMFold predicts multi-chain complexes by linking chains with a flexible linker sequence (typically glycines). The linker is removed in the final output. Default: 25 glycines (`"G" * 25`). Starting cap on total residues per inference batch; auto-halved on CUDA OOM (floor = longest single complex). Must be at least 100. Default: 1200. Recycling iterations through the structure module. Whether to print status messages during execution. Inherited from `StructurePredictionConfig`. Default: `False`. Device to run the model on (`"cuda"`, `"cpu"`). Inherited from `StructurePredictionConfig`. Default: `"cuda"`. Maximum execution time in seconds. `None` waits indefinitely. Random seed. When set, tools run reproducibly up to small GPU float noise (see `BaseToolOutput.approx_equal`), and the seed participates in cache keys. When None, cacheable seed-sensitive tools skip cache until seeded. Inherited. Default: `False`.

Source Predicted structures, each carrying an :class:`ESMFoldMetrics` instance on `.metrics`. Raw structure content in PDB or CIF format. Format of the content string (auto-detected if omitted). What the B-factor column represents. Optional source identifier (filepath or tool name). Associated metrics (e.g., pLDDT, pTM scores, per-chain lists, pairwise matrices). None values are stripped at construction. **Metrics** (one set per `structures` item) | Metric | Type | Range | Availability | | ----------- | ------------------- | ---------- | ------------------------------ | | `avg_plddt` | float | 0.0 to 1.0 | always | | `ptm` | float | 0.0 to 1.0 | depends on model output | | `avg_pae` | float | ≥ 0.0 | depends on model output | | `pae` | list\[list\[float]] | ≥ 0.0 | when include\_pae\_matrix=True |

#### Applications This tool folds a protein sequence into a 3D model for structural analysis or as input to downstream structure based tools. Because ESMFold does not use an MSA, it is well suited to de novo or heavily engineered sequences that have no natural homologs for an alignment to capture. #### Usage Tips * **No MSA or template search is used.** ESMFold does not incorporate MSAs into the prediction. There is no `use_msa` option (unlike Boltz-2 or Protenix), and passing one raises an error; the inherited `msas` input, by contrast, is ignored if supplied, emitting a single logged warning. * **Multi-chain complexes are approximated with an internal glycine linker.** `chain_linker` (default 25 glycines) joins chains before folding and is stripped from the output; this works best for homomeric assemblies and is unreliable for true hetero-complexes. Use AlphaFold3, Boltz2, Chai-1, or Protenix for those. * **Protein sequences only, with a hard cap of 2,400 residues per complex.** DNA, RNA, and ligands are not supported; `X` is allowed for unknown residues. The cap is enforced against the linked length actually folded: the sum of all chain residues plus the inter-chain `chain_linker` inserted between them (`len(chain_linker) * (chains - 1)`, 25 residues per junction by default). A multi-chain complex whose bare residues sum to just under 2,400 can still exceed the cap. * **Confidence is reported as pLDDT, pTM, and PAE.** Average pLDDT (0 to 1) is the primary per-structure quality metric; set `include_pae_matrix` to attach the full per-residue PAE matrix.

### ESMFold Gradient (`esmfold-gradient`) Runs a single differentiable ESMFold confidence pass: one forward-and-backward gradient evaluation, not an iterative design loop. For one or more designated chains, a relaxed `(L, 20)` amino-acid distribution replaces the discrete sequence, and ESMFold folds the complex under that soft input. The resulting pLDDT, pTM, and PAE terms are combined into one weighted scalar loss, and a single backward pass returns its gradient with respect to the input logits, along with the loss value, the per-term metrics, and the predicted `Structure`. #### API Reference

Source Complete complex chain sequences. Entries listed in `target_chain_indices` are replaced by the hard decode of `logits` before folding, but their lengths must match `len(logits)`. Chain positions that should receive the relaxed target logits. Repeated target segments in proto-language should pass each occurrence once; gradients are summed through the shared logits tensor. Target-chain logits in proto amino-acid order. Softmax temperature for the target-chain relaxed sequence.

Source Weights for pLDDT, pTM, and pAE losses. Soft probability blend for relaxed target sequence. Straight-through hard-forward blend for relaxed target sequence. Whether to return the gradient with respect to logits. Whether to print status messages during execution. Inherited from `StructurePredictionConfig`. Default: `False`. Device to run the model on (`"cuda"`, `"cpu"`). Inherited from `StructurePredictionConfig`. Default: `"cuda"`. Maximum execution time in seconds. `None` waits indefinitely. Random seed. When set, tools run reproducibly up to small GPU float noise (see `BaseToolOutput.approx_equal`), and the seed participates in cache keys. When None, cacheable seed-sensitive tools skip cache until seeded. Attach the full per-residue PAE matrix. Residue numbering gap between linked chains. Sequence inserted between chains before folding. Maximum residues per ESMFold inference batch. Structure module recycling iterations.

Source Predicted ESMFold complex structure. Raw structure content in PDB or CIF format. Format of the content string (auto-detected if omitted). What the B-factor column represents. Optional source identifier (filepath or tool name). Associated metrics (e.g., pLDDT, pTM scores, per-chain lists, pairwise matrices). None values are stripped at construction. Gradient matrix matching the input logits shape. Scalar weighted confidence objective value. Confidence metrics and per-term unweighted losses. Amino-acid column ordering for logits and gradient. **Metrics** | Metric | Type | Range | Availability | | ----------- | ------------------- | ---------- | ------------------------------ | | `avg_plddt` | float | 0.0 to 1.0 | always | | `ptm` | float | 0.0 to 1.0 | depends on model output | | `avg_pae` | float | ≥ 0.0 | depends on model output | | `pae` | list\[list\[float]] | ≥ 0.0 | when include\_pae\_matrix=True |

#### Applications This tool supplies the loss and gradient signal that gradient-based or MCMC sequence-design loops optimize for foldability: minimizing the confidence loss pushes a relaxed sequence toward one ESMFold predicts will fold well. With `compute_gradient=False` it instead provides forward-only confidence scoring (loss, metrics, and predicted structure) of a candidate sequence for ranking or filtering. #### Usage Tips * **One pass per call; this tool is not an optimization loop.** It evaluates a single relaxed sequence. Drive it from a sequence-design optimizer, or call it repeatedly, to actually design a sequence. * **`compute_gradient` defaults to `True`.** It runs a forward and backward pass and returns the gradient with respect to the input logits; set it `False` for forward-only scoring (`gradient=None`). The loss, metrics, and predicted structure are identical in both modes. * **`loss_weights` selects and weights the confidence terms.** Non-negative weights over `plddt`, `ptm`, and `pae` (default `{"plddt": 1.0}`); terms with weight `0.0` are skipped, and all-zero weights short-circuit to a zero gradient with `loss=0.0`. * **`logits` and the returned `gradient` share canonical amino-acid order `ACDEFGHIKLMNPQRSTVWY`.** Every chain listed in `target_chain_indices` must have length `len(logits)`; non-target chains fold normally with their fixed sequences. * **`soft` and `hard` trade smoothness for discreteness.** The default (`soft=1.0`, `hard=0.0`) uses pure soft probabilities for smooth optimization; set `hard=1.0` for a straight-through estimator (the forward pass sees argmax tokens while gradients still flow through the soft probabilities).