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

### ESM-IF1 Sampling (`esm-if1-sample`) Designs new sequences for a given backbone. Each input structure is encoded once and decoded into one or more candidate sequences, each returned with its average log-likelihood under the model. #### API Reference

Source Per-structure inputs, each containing a structure plus optional `chains_to_redesign` and `fixed_positions` selections. Chains to redesign. `None` means redesign every chain in the structure. Accepts shorthand `"A"` or `["A", "B"]` at construction. Per-chain positions whose residue identity is held fixed during design (1-indexed). Accepts shorthand `{"A": [1, 2, 3]}` at construction. Protein structure. Accepts a file path, raw PDB/CIF content string, `Structure` object, or a dict in the shape produced by `Structure.model_dump(mode='json')`.

Source Which model weights to use. 'esmif' loads vanilla ESM-IF1, 'protein\_dpo' loads DPO-aligned weights optimized for protein stability. Available options: `esmif`, `protein_dpo` 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 model on. Options include 'cuda' (NVIDIA GPU), 'cpu' (CPU execution), or specific GPU devices like 'cuda:0'. Defaults to 'cuda'. Maximum execution time in seconds. `None` waits indefinitely. Random seed for sampling reproducibility. Total number of sequences to generate per structure. Number of sequences to process simultaneously on GPU. Sampling temperature; ESM-IF1's tuned default is 1.0.

Source One `ESMIF1DesignSet` per input structure, in input order. The complexes generated for one input, each a complete multi-chain complex with a per-design log-likelihood.

#### Applications Use this to redesign a natural protein or to generate sequences for a de novo backbone, including multi-chain complexes and binding interfaces where the surrounding chains are kept as context. With the default ProteinDPO weights the designs are biased toward higher experimental stability, which suits stabilization campaigns. #### Usage Tips * **`temperature` defaults to `1.0`, rather than the `0.1` used by the other inverse-folding tools.** ESM-IF1's reference inference samples at `1.0`, and this toolkit retains that default, so its designs are more diverse than those produced by the backbone-MPNN models. Lower it toward `0.1` for conservative, near-greedy designs, and raise it for greater variation. * **`batch_size` controls how many sequences are produced per worker dispatch.** It defaults to `num_sequences_per_structure`, so the whole request is handled in one dispatch; the model still decodes the sequences one at a time. Lower it to bound peak GPU memory when a large request or long backbone exhausts memory. * **Non-redesigned chains still shape the design.** Chains you do not select stay as fixed structural context rather than being ignored, so designing one chain of a complex accounts for its partners. `fixed_positions` is counted from 1, not 0 to follow biological conventions for residue selection. * **Output is structured per design.** `output.design_sets[i].complexes[j]` is an `ESMIF1Design`; the designed target sequence is `design.designed_chains[0].sequence` and the log-likelihood is `design.metrics["log_likelihood"]`. `ESMIF1Design` is a `Complex` subclass and can be passed directly to structure predictors.

### ESM-IF1 Scoring (`esm-if1-score`) Evaluates how well existing sequences fit a structure. Each sequence is scored against its paired structure using the full multi-chain context, returning the average log-likelihood and perplexity. #### API Reference

Source List of pairs to score. Each pair contains a target chain sequence, a structure, and the chain ID within that structure whose sequence is being scored. Target chain sequence to score. Length must equal the number of residues in the chain identified by `target_chain`. Protein structure providing the (optionally multi-chain) coordinate context. Chain within `structure` whose sequence is being scored. `None` is permitted only for single-chain structures, in which case the sole chain is used. For multi-chain structures this field is required.

Source Which model weights to use. 'esmif' loads vanilla ESM-IF1, 'protein\_dpo' loads DPO-aligned weights optimized for protein stability. Available options: `esmif`, `protein_dpo` 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 model 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 List of scoring outputs, one per input sequence-structure pair. Each entry is a `Metrics` subclass with scalar metrics (accessed via `score.perplexity` or `score["perplexity"]`) plus declared `logits` / `vocab` fields. Per-position logits array `(seq_len, vocab_size)`. `None` unless the tool returns logits. Token ordering for `logits`. Name of the metric that best summarizes the result overall (e.g. `"avg_plddt"` for AlphaFold2). Used by downstream UI and reporting to pick a headline value. Concrete Metrics subclass tag; enables typed reconstruction after a serialization round-trip. **Metrics** (one set per `scores` item) | Metric | Type | Range | Availability | | -------------------- | ----- | ----- | ------------ | | `log_likelihood` | float | ≤ 0.0 | always | | `avg_log_likelihood` | float | ≤ 0.0 | always | | `perplexity` | float | ≥ 1.0 | always |

#### Applications Use this to rank candidate sequences or assess point mutations by structural compatibility without generating new ones. With the default ProteinDPO weights the score also better reflects predicted stability, which is useful for prioritizing stabilizing variants. #### Usage Tips * **Lower perplexity is better, and it tracks the log-likelihood directly.** Perplexity is `exp(-avg_log_likelihood)`, so the two metrics rank candidates identically. Treat the score as compatibility under the model, not a guarantee the sequence folds, and confirm shortlisted candidates with a structure predictor.