Proto is not affiliated with Google DeepMind. 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.

### AlphaFold2 Structure Prediction (`alphafold2-prediction`) Predicts the 3D structure of one or more protein chains. Each input complex (a single chain, or several chains folded together) is run through the ColabDesign AlphaFold2 model, returning a predicted `Structure` per complex with confidence metrics: per-residue pLDDT, pTM, interface pTM for multi-chain complexes, 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. 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 Number of recycling iterations through the model. Higher values can improve accuracy at the cost of computation time. Which AlphaFold2 model parameter set to use (1-5). AF2 ships 5 independently trained parameter sets. Different sets can produce different predictions. Mutually exclusive with `num_ensemble_models > 1`; set one or the other. Default: 1. Number of model parameter sets to run and average. Running multiple models and averaging their outputs can improve prediction quality at the cost of increased computation time. Mutually exclusive with `model_num`; when ensembling, models are selected from the full pool (models 1 through N). Range: 1-5. Default: 1. Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). Inherited from `BaseConfig`. Default: `0`. 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`. Whether to generate and use Multiple Sequence Alignments (MSAs) for protein chains using MMseqs2 homology search. Supplied MSAs are always used and override `use_msa=False`. Inherited from `MSAStructurePredictionConfig`. Default: `True`. Configuration for MMseqs2 homology search (MSA generation). Only used when `use_msa=True`. Inherited from `MSAStructurePredictionConfig`. Default: `None`. Whether heterocomplex protein chains should use taxonomy-paired MSA generation. Inherited from `MSAStructurePredictionConfig`. Default: `True`.

Source Predicted structures, each carrying an :class:`AlphaFold2Metrics` 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 | always | | `iptm` | float | 0.0 to 1.0 | multi-chain input only | | `avg_pae` | float | ≥ 0.0 | always | | `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, docking, or as input to downstream structure tools. Running it on a multi-chain complex additionally estimates how confidently the chains are placed relative to each other through the interface pTM and PAE, which is informative for assessing predicted protein-protein interfaces. #### Usage Tips * **`use_msa` defaults to `True`.** An MSA is then generated by a ColabFold search for each protein chain; set it `False` for single-sequence prediction (faster, usually lower accuracy), or attach precomputed MSAs to the input to skip the search. * **`model_num` and `num_ensemble_models` are mutually exclusive.** `model_num` (default `1`) selects one of AlphaFold2's five trained parameter sets; `num_ensemble_models` runs several and averages them for higher accuracy at higher cost. Setting both raises an error. * **Confidence is reported as pLDDT, pTM, ipTM, and PAE.** Average pLDDT (0 to 1) is the primary per-structure quality metric; ipTM is populated only for multi-chain complexes. Set `include_pae_matrix` to attach the full per-residue PAE matrix. * **Protein sequences only.** DNA, RNA, and ligands are not supported; `X` is allowed for unknown residues.

### AlphaFold2 Gradient (`alphafold2-gradient`) Scores and differentiates a binder against a frozen target structure. Given a target-plus-binder template, it runs AlphaFold2 (through ColabDesign's binder-design path) on the binder against the fixed target and returns the design loss, the predicted `Structure`, and, by default, the gradient of the loss with respect to the binder sequence logits. #### API Reference

Source Target+binder template PDB. Accepts a file path, raw PDB/CIF content string, `Structure` object, or a dict in the shape produced by `Structure.model_dump(mode='json')`. 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. Chain ID(s) of the frozen target in the PDB. Comma-separated hotspot residue indices on the target. Binder template chain to redesign; None (default) designs de novo. Zero-based binder residue indices for loss focus (e.g. CDR loops). Germinal backend only. Inherited — relaxed sequence logits (L x 20). Inherited — softmax temperature.

Source Attach full per-residue PAE matrix. Default: `False`. Persistent softmax bias toward wildtype at non-design positions. Germinal backend only. Amino acids to ban (e.g. `["C", "W"]`). AF2 recycling iterations. Which recycle's output is used for loss/gradient. `"last"` matches Germinal's VHH default; `"average"` averages across recycles; `"sample"` picks one uniformly; `"first"` uses only recycle 0. Available options: `last`, `sample`, `average`, `first` AF2 parameter set (1-5). Randomly sample model sets each forward pass. Use AlphaFold multimer parameters for binder protocol. Mask target template sequence in `prep_inputs`. Mask target template side chains in `prep_inputs`. Mask inter-chain template contacts in `prep_inputs`. ColabDesign softmax blending (0=raw logits, 1=full softmax). Passed per-step by the gradient optimizer. ColabDesign hard-sequence blending (0=relaxed, 1=straight-through argmax). `"base"` (upstream ColabDesign) or `"germinal"` (Germinal fork with alpha, bias, framework contacts, extension losses). Available options: `base`, `germinal` Run backward pass and return gradient; `False` for forward-only scoring (returns `gradient=None`). Optional one-letter AA string used to seed the binder before gradient updates. Germinal backend only; length must equal `len(logits)`. Binder-objective weights. Base keys: plddt, i\_plddt, pae, i\_pae, con, i\_con, exp\_res, rmsd, dgram\_cce, fape. Germinal extension keys: rg, i\_ptm, NC, helix, beta\_strand. Intra-chain contacts per residue. Intra-chain distance cutoff (Å). Interface contacts per residue. Interface distance cutoff (Å). Framework contact penalty offset in the Germinal inter-chain contact loss. Germinal backend only. Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). `True` is coerced to `1` and `False` to `0`. Device to run the tool on. 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.

Source Predicted target+binder complex from the forward pass. B-factors are at the raw 0-100 PDB scale; `b_factor_type=PLDDT` means `Structure.per_residue_plddt` normalizes them to `[0, 1]`. 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, or `None` when `compute_gradient=False`. Scalar objective value. Scalar auxiliary metrics (avg\_plddt, ptm, iptm, avg\_pae, plus per-loss values for every weighted ColabDesign loss term). Amino-acid column ordering. **Metrics** | Metric | Type | Range | Availability | | ----------- | ------------------- | ---------- | ------------------------------ | | `avg_plddt` | float | 0.0 to 1.0 | always | | `ptm` | float | 0.0 to 1.0 | always | | `iptm` | float | 0.0 to 1.0 | multi-chain input only | | `avg_pae` | float | ≥ 0.0 | always | | `pae` | list\[list\[float]] | ≥ 0.0 | when include\_pae\_matrix=True |

#### Applications This tool supplies the loss and gradient signal that gradient-based binder-design methods optimize against a chosen target. With `compute_gradient=False` it instead provides forward-only scoring of a candidate binder (loss, metrics, and predicted structure) for ranking or filtering. #### Usage Tips * **Use this for protein binder objectives, not ligand generation.** The input binder is an amino-acid chain and the returned losses describe a predicted protein-protein interface. For small-molecule compounds, choose chemistry-aware ligand tools instead. * **One binder configuration per call; this tool is not an optimization loop.** It evaluates a single binder against the fixed target. Drive it from a binder-design optimizer, or call it repeatedly, to actually design a binder. * **`compute_gradient` defaults to `True`.** It runs a forward and backward pass and returns the gradient with respect to the binder logits; set it `False` for forward-only scoring (`gradient=None`). The loss, metrics, and predicted structure are identical in both modes. * **`backend` selects the loss set.** `"base"` (the default) uses the upstream ColabDesign losses; `"germinal"` adds the Germinal fork's alpha, bias, framework-contact, and extension losses. `starting_binder_seq` is only valid with `"germinal"`. * **`target_hotspot` focuses the design on chosen target residues.** Supply comma-separated residue indices on the target to bias the binder toward a specific epitope; `loss_weights` (only the validated keys) tunes the objective terms.