Proto is not affiliated with Institute for Protein Design. 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.

### LigandMPNN Sampling (`ligandmpnn-sample`) Designs new sequences for a backbone in the presence of its non-protein context. Each input structure is encoded once, with any ligand, nucleotide, or metal atoms included, and decoded into one or more candidate sequences with a perplexity and sequence recovery score. #### 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 LigandMPNN implementation. `ligand_mpnn` (default) is the Foundry implementation; `original` runs the original LigandMPNN code and weights, auto-provisioned on first use, and emits packed full-atom structures. Available options: `ligand_mpnn`, `original` Whether ligand-aware variants encode ligand atom context. Optional explicit LigandMPNN checkpoint path. Whether to condition on fixed-residue sidechain atoms. Ligand-residue distance cutoff (Å) for the ligand-interface recovery score. One-letter codes of amino acids to exclude. Side-chain denoising steps. Only used when model\_type is `original`. Side-chain packing samples. Only used when model\_type is `original`. 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 to use for sampling. Total number of sequences to generate per input structure. Number of sequences to process simultaneously on GPU. Defaults to num\_sequences\_per\_structure. Controls randomness in sampling from logits.

Source One `LigandMPNNDesignSet` per input structure, in input order. The complexes generated for one input structure, each a complete multi-chain complex with recovery metrics.

#### Applications Use this to design or redesign binding sites, enzyme active sites, nucleic-acid-binding interfaces, and metal-coordination sites, where the identity of nearby non-protein atoms determines which residues work. It is the right choice over backbone-only ProteinMPNN whenever a ligand, cofactor, nucleic acid, or metal is part of the target. #### Usage Tips * **Keep `use_atom_context` enabled.** It defaults to `True` and is the whole point of LigandMPNN: it encodes the surrounding ligand, nucleotide, and metal atoms. Turning it off makes the model effectively ligand-blind, close to plain ProteinMPNN. * **Set `use_side_chain_context` to `True` to honor a fixed motif.** It conditions on the sidechain atoms of fixed residues, which helps when redesigning around a preserved catalytic or binding motif. It defaults to `False`. * **Set `model_type="original"` when you need packed full-atom outputs.** The default `ligand_mpnn` uses the Foundry implementation and emits redesigned-backbone structures. `original` instead runs the original LigandMPNN code and weights, so sampling returns sequence-consistent full-atom (packed) structures. The code and weights are auto-provisioned into the model cache on first use, so no manual setup is needed; advanced users can override the sequence checkpoint with `checkpoint_path`. * **`fixed_positions` is counted from 1, not 0**, to match biological residue selection conventions. Listed positions keep their input residue, and chains or atoms you do not redesign still act as context rather than being removed.

### LigandMPNN Scoring (`ligandmpnn-score`) Evaluates how well existing sequences fit a structure and its non-protein context, returning log-likelihood-based metrics with optional per-position logits. #### API Reference

Source Sequence and structure pairs to score; each pair may carry per-pair `fixed_positions` excluded from the metrics. Protein sequence to score against the structure. Protein structure to score the sequence against. Per-chain 1-indexed positions excluded from the aggregate scoring metrics. Accepts `{"A": [1, 2]}`.

Source Whether to include per-position logits. Single-position or autoregressive scoring mode. Available options: `single_aa`, `autoregressive` LigandMPNN implementation. `ligand_mpnn` (default) is the Foundry implementation; `original` runs the original LigandMPNN code and weights, auto-provisioned on first use. Available options: `ligand_mpnn`, `original` Optional explicit LigandMPNN checkpoint path. Whether ligand-aware variants encode ligand atom context. Whether to condition on fixed-residue sidechain atoms. Ligand-residue distance cutoff (Å). 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 designs or assess mutations near ligands, nucleic acids, or metals, where backbone-only scoring would miss the very interactions that matter. Lower perplexity indicates a better fit to the structure and its bound environment. #### Usage Tips * **`scoring_mode` changes what the score means.** `single_aa` (the default) scores each position from its own conditional probability and is order-independent, which is what you usually want for ranking. `autoregressive` scores along one seed-determined decoding order, so it depends on the seed. * **`fixed_positions` excludes residues from the aggregate score.** Set it per (sequence, structure) input pair as a `{chain: [positions]}` selection counted from 1, not 0, to match biological residue selection conventions, so the score reflects only the residues you care about. * **`return_logits` (default `False`) has a size trade-off.** Enabling it adds a per-position logit array per sequence for residue-level analysis, which dominates output size and memory for long sequences, so leave it off unless you need it.