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

### ProGen3 Sampling (`progen3-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` and `top_p` settings, in the chosen `direction`, until `max_new_tokens` residues have been generated (at least `min_new_tokens`). #### API Reference

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

Source ProGen3 weights variant. Sizes range from 112M (fastest) to 3B (highest quality). Available options: `progen3-112m`, `progen3-219m`, `progen3-339m`, `progen3-762m`, `progen3-1b`, `progen3-3b` Override HuggingFace download with a local weights directory. `"forward"` generates N→C, `"reverse"` generates C→N. Available options: `forward`, `reverse` Maximum new tokens to generate per prompt (excludes prompt). Minimum new tokens to generate per prompt before stopping is allowed. 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. If `True`, returned sequences include the prompt and newly generated residues; if `False`, only the newly generated residues. Softmax temperature; lower values are more deterministic, higher values increase diversity. Nucleus sampling threshold over per-position token probabilities. Maximum number of same-length prompts to process simultaneously on GPU.

Source One entry per generated sequence, in input order. The generated sequence.

#### Applications This tool performs de novo protein design, generating novel sequences that resemble natural proteins, optionally conditioned on a prompt. Because generation can run in reverse (C-terminus toward N-terminus), a C-terminal fragment can be used as the prompt and the rest of the sequence grown toward the N-terminus, which a strictly left-to-right model cannot do. #### Usage Tips * **`direction` chooses which terminus is generated.** `"forward"` (the default) continues a prompt from the N-terminus toward the C-terminus; `"reverse"` treats the prompt as a C-terminal fragment and generates toward the N-terminus. Note that the reverse generation will append to the prompt to grow the sequence on the left. All starting sequences should still be provided in the left to right direction from N->C. * **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. This tool exposes only nucleus (`top_p`) sampling for ProGen3; there is no top-k cutoff. * **`max_new_tokens` and `min_new_tokens` bound the generated length.** They count only newly generated residues (default `256` and `1`), 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.

### ProGen3 Scoring (`progen3-score`) Scores existing protein sequences under ProGen3 using bidirectional likelihood. For each sequence it runs both a forward (N→C) and a reverse (C→N) pass, averages the per-position log-likelihoods into a single bidirectional value, and aggregates these into a log-likelihood, an average log-likelihood per residue, and a perplexity. It also exposes the forward, reverse, and bidirectional per-position values, and optionally the per-position logits. #### API Reference

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

Source ProGen3 weights variant. Sizes range from 112M to 3B parameters. Available options: `progen3-112m`, `progen3-219m`, `progen3-339m`, `progen3-762m`, `progen3-1b`, `progen3-3b` Override HuggingFace 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. Whether to include forward-pass per-position logits in the output. Reverse-pass info is already exposed via `per_position_metrics` (forward/reverse/bidirectional log-likelihoods).

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 ProGen3's training distribution, usable as a fitness or plausibility signal without additional task-specific training. Because it uses both directions, every residue is scored with full surrounding context rather than left context only. Use it to rank or filter candidate sequences (including the output of `progen3-sample`), to compare variants of a sequence, or to flag sequences far from the model's training distribution. #### Usage Tips * **Scores are bidirectional, not a single-direction log-likelihood.** The reported `log_likelihood`, `avg_log_likelihood`, and `perplexity` are derived from the averaged forward and reverse per-position values, so they are not directly comparable to a one-directional model's scores. * **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).