Proto is not affiliated with Salesforce Research. 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.

### ProGen2 Sampling (`progen2-sample`) Generates protein sequences by autoregressive sampling. Given one or more prompt sequences, the model extends each prompt one amino acid at a time, drawing each residue from the model's predicted distribution under the configured `temperature`, `top_p`, and `top_k` settings, until a stop token is produced or `max_new_tokens` new residues have been generated (default 256). #### API Reference

Source Prompt sequences to condition generation on. Can be provided as a single string or a list of strings.

Source ProGen2 weights variant. Sizes range from 151M (small) to 6B (xlarge). Available options: `progen2-small`, `progen2-medium`, `progen2-base`, `progen2-oas`, `progen2-large`, `progen2-BFD90`, `progen2-xlarge` Override the default download with a local weights directory. Top-k truncation; `0` disables and uses top-p only. Maximum number of new tokens to generate per prompt (excludes prompt). Truncate generated sequences at the first stop token. Strip ProGen2 start/stop sentinel tokens (`1`/`2`) from output. Include per-position logits in the output. 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. Include the input prompt at the start of each generated sequence; when `False`, only newly generated tokens are returned. Softmax temperature; lower values are more deterministic. Nucleus sampling threshold over per-position token probabilities. Number of prompts to process simultaneously on GPU.

Source One generated protein sequence per prompt, with its logits. Per-position logits for this sequence (shape: \[generated\_len, vocab\_size]). The generated protein sequence.

#### Applications This tool performs de novo protein design, generating novel sequences that resemble natural proteins conditioned on a prompt such as a starting motif or partial domain. The antibody-trained `progen2-oas` checkpoint targets antibody and immune-repertoire generation specifically. #### Usage Tips * **Generated output is trimmed by default.** Generated sequences are cut at the first stop token with the start/stop sentinels removed (`truncate_at_stop` and `strip_special_tokens`, both `True`); set them `False` to keep the raw model output. * **Sampling defaults are conservative.** `temperature` defaults to `0.2` and `top_p` to `0.95`, which keep generations close to natural-looking sequences; raise `temperature` for more diverse but riskier designs. `top_k` defaults to `0`, which disables top-k truncation so only nucleus (`top_p`) sampling is applied. * **`max_new_tokens` bounds the generated length.** It caps newly generated residues (default `256`), separate from the prompt length. * **Output includes the prompt by default.** `prepend_prompt=True` (the toolkit default) returns the prompt joined to its continuation; set it `False` to receive only the newly generated residues. * **Generated sequences are candidates.** Validate them with downstream tools (for example structure prediction, function annotation, or homology search) before drawing biological conclusions.

### ProGen2 Scoring (`progen2-score`) Scores existing protein sequences using ProGen2. For each sequence it computes the model's predicted probability of every residue given the preceding residues and aggregates these into a log-likelihood, an average log-likelihood per residue, and a perplexity (perplexity is fully determined by the average log-likelihood, computed as `exp(-avg_log_likelihood)`, but is the conventionally reported metric). Optionally returns the per-position logits and the token vocabulary. #### API Reference

Source Sequences to score. Can be provided as a single string or a list of strings.

Source ProGen2 weights variant. Available options: `progen2-small`, `progen2-medium`, `progen2-base`, `progen2-oas`, `progen2-large`, `progen2-BFD90`, `progen2-xlarge` Override the default download with a local weights directory. 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. Number of sequences to process simultaneously on GPU. Include per-position logits in the output.

Source List of scoring outputs, one per input sequence. Each entry is a `Metrics` subclass with scalar metrics (`log_likelihood`, `avg_log_likelihood`, `perplexity`) and optional per-position `_pp`-suffixed list extras; `logits` and `vocab` are declared fields for raw model outputs. Per-position logits array `(seq_len, vocab_size)`. `None` unless `return_logits=True`. 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 This tool gives a zero-shot measure of how consistent a protein sequence is with ProGen2's training distribution, which is used in the paper as a proxy-fitness predictor without additional task-specific training. It can be used to rank or filter candidate sequences (including the output of `progen2-sample`), to compare variants of a sequence, or to flag sequences far from the model's training distribution. #### Usage Tips * **Compare length-normalized scores within one checkpoint.** Total `log_likelihood` scales with sequence length, so use `perplexity` or `avg_log_likelihood` when comparing sequences of different lengths. Different checkpoints learn different distributions that are not calibrated to a common scale, so scores from different `model_checkpoint` values are hard to compare directly. A lower perplexity means the sequence is more consistent with that checkpoint's training distribution. * **`return_logits` defaults to `False`.** Leave it off unless you need the per-position distributions, since the logits tensor is large (sequence length by the token vocabulary). * **A domain-matched checkpoint is not automatically better for scoring.** The ProGen2 paper found the antibody-specific `progen2-oas` checkpoint underperformed the universal checkpoints on antibody fitness prediction, so a universal checkpoint (such as the default `progen2-large`) is often the safer choice for scoring.