Biohub ESM

View saved version →

---
name: biohub-esm
description: Route Biohub ESM requests to ESMC, ESMFold2, ESM Atlas, Modal, or private open weights. Use for explicitly ESM/Biohub work, ESM protein representations or mutation scoring, ESMFold2 folding, Atlas discovery, ESM binder design, or choosing an ESM compute route. Do not use for unrelated non-ESM models, generic sequence alignment, or standalone structure viewing unless the user explicitly asks to compare it with Biohub ESM.
---

# Biohub ESM router

Use this as the implicit entry point. Identify the scientific goal before choosing a model or provider; ESMC, ESMFold2, and Atlas are different artifacts.

## Route first

| User need | Default | Escalation |
| --- | --- | --- |
| Existing-protein discovery, functional neighborhoods, Atlas feature catalog, clusters | public Atlas alpha API | anonymous Atlas S3 for bulk data |
| SAE activation extraction or interpretation for an input sequence | Biohub managed ESMC | pinned ESMC weights for private or custom work |
| Public ESMC inference, including bounded concurrent calls | Biohub managed API | self-host for private, custom, sustained, or owned-compute work |
| One or modest structure predictions | Biohub managed ESMFold2 | full + MSA for difficult targets; Modal for bulk |
| Many independent folds or sweeps | Modal open weights | user-owned GPUs |
| Minibinder, binder, or scFv design | Modal or self-hosted open weights | never Biohub managed API until documented |
| Private, offline, air-gapped, data-resident, customized, fine-tuned, sustained | Hugging Face weights on user-owned compute | user owns capacity and operations |

Run the deterministic router when the route is not already explicit:

```bash
python3 <plugin-root>/scripts/biohub_esm.py route --task fold --item-count 500
```

The 32-item scale-out threshold applies to folding. It is a planning heuristic, not a Biohub account quota. Public ESMC calls stay on the managed API; the plugin ships no ESMC Modal function. Do not hardcode account-specific capacity limits.

## Natural starter experiences

Treat the plugin page's exact prompts as outcome-rich launchers into the official tutorial contracts in `../../examples/tutorial-use-cases.json`:

- `Map the mutational landscape of PETase and show me where it is most constrained or tolerant.`
- `Show me what ESMC has learned about ATP synthase and map the strongest features onto its structure.`
- `Model how a modified GLP-1 peptide with a lipid linker might engage GLP-1R, then show me the complex.`

Resolve their hidden scientific inputs, select the specialist and model, produce the tutorial-shaped analysis, and present the visual result without making the user translate the request into sequences or SDK objects. The focused GB1 regression launchers in `../../examples/starter-examples.json` remain supported:

- `What might W43F do to GB1?`
- `Show me what GB1 looks like.`
- `Find proteins similar to GB1.`

The three exact plugin-page prompts are curated official-tutorial launchers. Before adopting their pinned target or construct, disclose its exact identity together with the execution route, model, item and call counts, parameters, artifact plan, and available cost information. The PETase prompt authorizes only its disclosed exact 259-request managed runtime once access is configured. The ATP-synthase and GLP-1R prompts do not authorize provider calls; obtain separate explicit current-turn confirmation for their disclosed exact calls. No prompt authorizes a substituted target, a different request scope, or Modal, self-hosted, or bulk-transfer work. An explicit planning-only or no-network request overrides execution. Outside those three exact prompts, resolve a bundled literal only for an explicitly named tutorial example. A generic target request, or a prompt that says “my A3M/MSA,” must use the user's supplied biological input or pause for the missing input; never substitute a tutorial fixture. The 259-context PETase landscape runs on the managed API through the shipped replay-safe command, fanned out through a bounded pool of concurrent managed calls as the quickstart documents.

Do not ask the user to paste the bundled GB1 sequence or recite implementation details already owned by the contract. Resolve these launchers to the pinned RCSB 1PGA chain-A record, then validate the internal literal sequence, digest, and mutation numbering. For other named targets, prefer a user-provided file or stable identifier; otherwise resolve an authoritative sequence source and ask one question only when ambiguity would change the biological input.

For a managed route, run status-only preflight first; it reads no credential value and costs nothing. If it reports `missing`, load `$biohub-esm-setup` and give the user its key message with the returned `obtain_key_url`, not a plan they cannot run, then resume automatically once the key is configured. Otherwise resolve and validate the input locally, then follow that workflow's authorization boundary and execute only its exact pinned request count without implicit retries. The focused GB1 starters and exact PETase runtime run without separate confirmation; ATP-synthase and GLP-1R require it as stated above. Managed requests may incur cost. Report provider-returned credit or token usage when available; otherwise state that the API did not report usage or cost, and never invent an estimate. Continue automatically through local recovery and result presentation after successful artifact creation. Lead with the result, not with a description of what you are about to do. Small public Atlas API reads need no spend confirmation, but still obey a caller's explicit no-network or planning-only boundary. Before a bulk anonymous-S3 transfer, freeze the exact source prefix, destination, estimated bytes, storage and egress impact, and cost ceiling, then obtain separate explicit current-turn confirmation.

## Hand off

After choosing the route, explicitly load exactly the focused specialist(s) needed for the request. These specialists are explicit-only so the router stays the single implicit entry point.

- Representation, logits, entropy, mutation, SAE activation extraction/interpretation, fitted-head, or fine-tuning requests: use `$esmc`.
- Protein/DNA/RNA/modified-residue/ligand folding: use `$esmfold2`.
- Similar proteins, MD5 records, clusters, the existing Atlas feature catalog, thumbnails, or Atlas batch data: use `$esm-atlas`.
- Binder/minibinder/scFv design: use `$esmfold2-binder-design`.
- Install, authentication, environment, or preflight problems: use `$biohub-esm-setup`.

## Invariants

- Atlas is a public data/discovery API and anonymous dataset, not a model to deploy on Modal or Hugging Face.
- Biohub managed inference needs `ESM_API_KEY`.
- Modal public-weight workflows need Modal authentication, not `ESM_API_KEY`.
- Public Hugging Face weights do not require `HF_TOKEN`; it is optional for authenticated Hub access.
- Do not ask for credentials in chat or print, persist, screenshot, or commit them. Preflight reports only configured/missing.
- Preserve machine-readable artifacts and provenance, not UI-only results.
- Finish successful workflows with the default [result presentation handoff](../../references/structure-viewer-handoff.md): use semantic viewing/display capabilities, open each verified artifact once, and keep pending or unavailable presentation separate from scientific artifact success.

Read [routing details](references/routing.md), [failure handling](references/failures.md), and the shared [safety/provenance contract](../../references/safety-and-provenance.md).

Referenced files: 3

View saved version →

---
name: biohub-esm-setup
description: Set up and preflight Biohub ESM, Atlas, Modal, and Hugging Face access. Use when installing pinned ESM dependencies, checking credentials, or fixing auth, rate-limit, credits, PATH, SDK, or GPU setup. Never ask for secret values.
---

# Biohub ESM setup and auth

## No key yet

When `biohub_managed.status` is `missing`, inspect `esm_sdk_runtime` before starting credential setup. If the selected managed workflow imports the pinned `esm` SDK and `esm_sdk_runtime.status` is `unsupported`, report both blockers in the same handoff: say that the workflow requires Python 3.12, and quote the reported interpreter and remedy. This applies to managed ESMC mutation scoring, `esmc-landscape`, and ESMFold2 response serialization. Do not wait until after the key is configured to reveal the Python blocker.

When no verified host credential action is available, use this credential instruction alongside the Python blocker when applicable:

> Get a free API key at <https://biohub.ai/developer-console/api-keys> (existing Forge accounts can sign in), set it as `ESM_API_KEY` in the environment that launches Codex, then restart Codex.

Preflight returns `obtain_key_url`, `variable`, and `esm_sdk_runtime` alongside the status, so quote those rather than composing your own setup requirements. If a verified credential action is available, follow **Seamless credential recovery** below instead. Apart from current setup blockers, do not describe routes, models, request counts, or costs before the key exists — none of it is actionable yet. Once the key and runtime are configured, resume the original request automatically without asking the user to repeat it.

## Safe preflight

The agent runs the base status-only check directly for credentials, Atlas, and
routes that do not materialize a managed structure:

```bash
python3 <plugin-root>/scripts/biohub_esm.py preflight
```

For a managed fold, run the selected endpoint's capability preflight with the
same provisioned Python 3.12 interpreter that will execute the request:

```bash
<python-3.12-with-pinned-esm> <plugin-root>/scripts/biohub_esm.py preflight --endpoint fold
<python-3.12-with-pinned-esm> <plugin-root>/scripts/biohub_esm.py preflight --endpoint fold_all_atom
```

Run only the applicable endpoint command. Its
`managed_structure_materialization` report verifies the interpreter, exact ESM
and Transformers source revisions, endpoint-specific imports, and a tiny offline
serialization. A blocked report must stop the workflow before credential access,
output creation, or provider submission; apply its bounded remediation and rerun
that endpoint preflight. Resolve the placeholder to the provisioned interpreter
(`.venv/bin/python` for the install below) and use that exact interpreter for the
subsequent managed command.

Credential entries report only `configured`, `missing`, `optional-missing`, or `not-required`; `esm_sdk_runtime` separately reports `supported` or `unsupported`. On macOS, preflight probes only whether the recognized Keychain item exists; it never requests the value or uses `security ... -w`. Execution-time resolution may retrieve the existing item only when the selected route is authorized to run: tutorial-scale managed Biohub requests run without a separate confirmation, while Modal, self-hosted, and bulk-transfer routes require the route-specific confirmation first. Do not hand the command to the user when tool execution is available. Never open or display `.modal.toml`; file presence is enough for preflight.

## Seamless credential recovery

When managed Biohub access reports `missing`, keep the current request intact while setup completes.

1. Use the host's existing secure credential setup action for `ESM_API_KEY`, when one is actually available. Invoke it once and tell the user the verified host surface where its masked prompt will appear, such as a credential sheet in the app. Never claim that a terminal prompt exists unless the invoked action actually opens one.
2. Let that host action collect and persist the credential. Never ask the user to paste, repeat, or reveal the value in chat, and never clear or overwrite a configured credential.
3. When the setup action completes, automatically run the status-only preflight once. Resume a waiting tutorial-scale managed Biohub request immediately; it needs no separate confirmation. Resume Modal, self-hosted, or bulk-transfer work only when its exact frozen scope already has a still-current confirmation. Report the status without exposing the value if it is not configured.

Do not ask the user to say "done" and do not create a repeated setup loop. If this host exposes no callable secure setup action, do not imply that it does. Give exactly one user-executed fallback: set `ESM_API_KEY` in the environment that launches Codex, then restart Codex so it inherits the setting. On macOS, preflight and managed requests also recognize an existing generic-password item with service `com.openai.codex.biohub-esm.ESM_API_KEY`. Stop there; on the user's next message, run preflight automatically instead of asking whether setup was completed.

A configured credential persists in the host's secret, environment store, or recognized macOS Keychain item until the user explicitly asks to replace or remove it. The plugin never mutates or removes the Keychain item, and setup must not unset any credential after a run.

## Credentials

- Biohub managed ESMC/ESMFold2: `ESM_API_KEY`. Create a free key at <https://biohub.ai/developer-console/api-keys> — name it, click Create, copy it. Existing Forge users sign in with the same credentials and do not need a new account. Use a verified host credential action when one exists; otherwise set it in the environment that launches Codex and restart Codex. Never ask the user to paste it in chat, and preserve an existing configured value.
- Atlas API and `s3://esm-protein-atlas/v1/`: no client credential in the current alpha.
- Modal: `MODAL_TOKEN_ID` plus `MODAL_TOKEN_SECRET`, or an authenticated Modal profile. Environment values override the profile.
- Hugging Face public weights: no token required. `HF_TOKEN` is optional for authenticated Hub access and rate-limit handling.

## Source/model-pinned install

Use an isolated environment and the pin in [`source-pins.md`](../../references/source-pins.md):

```bash
python3.12 -m venv .venv
.venv/bin/python -m pip install \
  "esm @ git+https://github.com/Biohub/esm.git@ba4d7124864eed323a93bf3cfefcd958f573b75a"
.venv/bin/python -m pip install --force-reinstall --no-deps \
  "transformers @ git+https://github.com/Biohub/transformers.git@ef32577f55da19a4989cd7b22e004dc43a4998cb"
.venv/bin/python <plugin-root>/scripts/biohub_esm.py verify-install
```

ESM currently declares the Transformers fork from mutable `main`. The second layer must replace it with the exact direct-VCS revision; a single combined install does not even preserve the intended source pin when `requested_revision` remains `main`. These commands pin first-party code and model selection, but they are not a complete environment lock: the ESM package retains broad transitive dependency ranges, and hardware/runtime details can also affect outputs.

For Modal, use an already authenticated official CLI and install the validated `modal==1.5.2` SDK in an isolated environment. The generic durable control plane also requires the immutable positive deployment version returned by Modal and passes it to `Function.from_name(..., version=...)`; an app/function name alone is mutable. Do not place tokens on a command line. The [Modal config reference](https://modal.com/docs/sdk/py/latest/modal.config) documents environment and profile resolution, and the [Modal changelog](https://modal.com/docs/sdk/py/changelog) is the authority to review before updating the client pin.

## Diagnose without weakening tests

- `401`: missing, invalid, or expired Biohub key. Report auth failure only.
- `500` with an empty body on a managed call: most often a rejected key, because the managed API currently returns a bodyless `500` rather than `401` for an invalid bearer token. Say the key looks wrong and point at <https://biohub.ai/developer-console/api-keys> before treating it as an outage; a configured-but-rejected key is not the same as a missing one.
- `402` or credit message: account-specific credits; direct the user to <https://biohub.ai/developer-console> without inventing a quota.
- `429`: honor `Retry-After`; reduce concurrency or resume later.
- timeout/5xx: preserve durable state and partial artifacts. Retry only a proven-idempotent setup or public read with bounded backoff; never retry a managed call whose outcome is indeterminate.
- Atlas schema error: retain raw response, compare the live alpha schema, and update validation intentionally.
- OOM/hardware mismatch: for ESMC, select a smaller managed model or pinned weights on a suitable user-owned GPU; use Modal only for supported fold or binder workflows. Do not silently lower scientific parameters.

Read [setup details](references/setup.md), the shared [source pins](../../references/source-pins.md), and [safety/provenance contract](../../references/safety-and-provenance.md).

Referenced files: 2

View saved version →

---
name: esm-atlas
description: Use when the user needs ESM Atlas similarity search, MD5 protein lookup, structures, clusters, Pfam/taxonomy context, the existing 16,384-feature Atlas SAE catalog, thumbnails, batch jobs, or anonymous S3 data. Use ESMC instead to extract SAE activations for a supplied sequence. Atlas is not a deployable model and currently needs no client key.
---

# ESM Atlas

Atlas is public data/discovery infrastructure, not another model to run through Modal or Hugging Face. The current `v1alpha1` API needs no client-side key and is explicitly unstable/not recommended for production assumptions.

Atlas feature details cover the 16,384-feature catalog for the pinned tutorial's `esmc-6b-2024-12-sae-layer60-k64-codebook16384`. Do not apply them across checkpoints, models, layers, or codebooks. Extract activations with `$esmc`; record normalization separately because it changes scaling and ranking, not feature-index identity. The k64 SAE retains at most 64 positive features per residue. `per_residue_activations` is the complete post-sparsification tensor, not API truncation, although quantization can round small values to zero.

For `Find proteins similar to GB1.`, resolve the pinned fixture through `../../examples/starter-examples.json`; do not ask the user to paste the bundled sequence. Make exactly one public similarity-search GET with `topk_results=10`, `topk_features=20`, `min_similarity=0.5`, and `include_cluster_info=true`, writing to `/absolute/path/gb1-atlas-similarity-search`. Return up to ten hits only after validating unique MD5s, non-empty accessions, client-required positive integer lengths, scores in 0–1 and at or above 0.5, and nonincreasing score order. Use only cluster metadata embedded in that search response and make zero protein or cluster-detail follow-ups. Preserve `raw-response.json`, `result.json`, and `provenance.json`; optional `search-<n>.pdb` artifacts exist only for hits with provider-embedded coordinates. Atlas needs no client-side key, so run it directly and do not substitute a model deployment.

## Conservative boundaries

- similarity search: raw Atlas accepts 1 to 2,048 sequence characters; the bundled plugin must validate at no more than 800 residues. Never clip; ask for a domain or search labeled windows.
- on-demand fold: opt-in only. The partner-inspected backend accepts 1 to 700 sequence characters, while published guidance says <700; the plugin exposes only hash-based fold-on-miss and caps the returned stored sequence at 699 sequence characters. It first performs a non-folding lookup and proceeds only when the actual returned sequence matches the MD5 and plugin-supported alphabet and the record lacks coordinates; `sequence_length` alone or missing sequence evidence is rejected. It cannot fold an unknown hash or caller-supplied sequence; do not bypass it with an ad hoc request. Start with similarity search when the input is a sequence.
- feature index: 0–16,383
- batch: at most 500 unique MD5 hashes. The plugin rejects malformed hashes before submission; the raw API instead returns per-protein errors.

Only relax a boundary after a live schema/probe is captured and tests are updated. Preserve the raw alpha response before normalization.

## Workflows

```bash
# Learned-feature similarity search
python3 <plugin-root>/scripts/biohub_esm.py atlas search \
  --sequence "$SEQUENCE" --topk-results 10 --include-cluster-info \
  --output-dir /absolute/path/atlas-search

# Separate opt-in protein and representative-cluster traversal; not part of the canonical starter
python3 <plugin-root>/scripts/biohub_esm.py atlas protein \
  --protein-hash <md5> --output-dir /absolute/path/protein
python3 <plugin-root>/scripts/biohub_esm.py atlas cluster \
  --protein-hash <cluster-representative-md5> --output-dir /absolute/path/cluster

# Feature catalog/detail with raw response and provenance
python3 <plugin-root>/scripts/biohub_esm.py atlas features \
  --output-dir /absolute/path/features
python3 <plugin-root>/scripts/biohub_esm.py atlas feature \
  --feature-index 42 --output-dir /absolute/path/feature-42

# Batch submit creates atomic resumable state. --output handles a possible
# synchronous zip; the same path can be supplied again when waiting.
python3 <plugin-root>/scripts/biohub_esm.py atlas batch-submit \
  --hashes /absolute/path/hashes.json \
  --state /absolute/path/batch-state.json \
  --output /absolute/path/batch.zip
python3 <plugin-root>/scripts/biohub_esm.py atlas batch-status \
  --state /absolute/path/batch-state.json
python3 <plugin-root>/scripts/biohub_esm.py atlas batch-wait \
  --state /absolute/path/batch-state.json \
  --output /absolute/path/batch.zip
# Or request cancellation; terminal states are preserved as no-ops.
python3 <plugin-root>/scripts/biohub_esm.py atlas batch-cancel \
  --state /absolute/path/batch-state.json
```

Support feature catalog/list/detail, `pct-characterized` and `plddt` thumbnails, batch submit/poll/cancel/download, and empty-hit results. Small batches may return a zip immediately; large batches return `202` job state. Each state transition is atomically replaced under a per-state advisory lock; after a completed operation, its separate provenance sidecar is refreshed while that lock is held and repaired from authoritative state after a process crash. An interrupted submit without a durably captured `job_id` becomes `submission-indeterminate`: preserve its input digest, reconcile manually with Atlas operators, and never resume or resubmit that state. Atlas has no public recovery endpoint for a lost job ID; only consider a distinct new state and submission after separate explicit confirmation and a duplicate-work warning. A definitive `400`/`401`/`402`/`403`/`404`/`422`/`429` response instead becomes `submission-rejected`. After remediating the response, only a newly invoked `batch-submit` for the exact same request may retry, and not before the persisted `Retry-After` deadline. A synchronous HTTP 200 completion has no remote `job_id`, so status/wait return its persisted evidence and cancellation is a terminal no-op. An interrupted idempotent cancellation remains `cancellation-requested` with unknown acceptance and may safely retry DELETE. Otherwise, a new process can resume using only `--state`. Ephemeral signed download URLs are used in memory and deliberately omitted from state. To adopt an older job once, pass both `--state <new-path>` and `--job-id <id>`. Cancellation is idempotent but completed results can remain available.

Use `cluster_pct_characterized_max=0` only as the documented proxy for clusters without characterized Pfam annotations; do not call that proof of unknown function. Preserve Atlas CC-BY-4.0 attribution.

Finish searches with the [result presentation handoff](../../references/structure-viewer-handoff.md). Open the first verified absolute coordinate artifact once through the available structure-viewing capability and retain presentation status independently of the search result. Otherwise, for non-empty results, make at most one public `atlas thumbnail --thumbnail-type plddt` request for the first-ranked hit, save it as `top-hit-plddt.png` with its provenance sidecar, and display it inline. Empty results remain a valid artifact-only outcome. Atlas coordinates and thumbnails are predictions; an experimental record or PDB container does not change their provenance. For requested experimental method, resolution, or citation evidence, query RCSB or PDBe when possible and report it separately; otherwise state the lookup limitation.

Read the exact [alpha HTTP contract](references/api.md), [batch and S3 guidance](references/bulk-data.md), and shared [safety/provenance contract](../../references/safety-and-provenance.md).

Referenced files: 3

View saved version →

---
name: esmc
description: Use when the user needs ESMC embeddings, hidden states, logits, entropy, zero-shot mutation scoring, SAE features, fitted heads, or fine-tuning. Sequence only; not for folding, Atlas lookup, or calling an untrained classifier predictive.
---

# ESMC

ESMC is a sequence-only masked protein language model. Validate the input before inference:

```bash
python3 <plugin-root>/scripts/biohub_esm.py validate-sequence \
  --target esmc --sequence-file /absolute/path/query.fasta
```

The context is 2,048 tokens. Because current tokenizers add BOS/EOS, the helper uses a conservative 2,046-residue raw-sequence cap unless a pinned tokenizer probe proves a different count. Do not pass structures, DNA, RNA, or ligands.

## Model and route

| Route | IDs |
| --- | --- |
| Biohub managed | `esmc-300m-2024-12`, `esmc-600m-2024-12`, `esmc-6b-2024-12` |
| Hugging Face | `biohub/ESMC-300M`, `biohub/ESMC-600M`, `biohub/ESMC-6B` |

Default to managed ESMC for public inference, including bounded concurrent calls that the managed backend can auto-batch. The plugin ships no ESMC Modal function. Use pinned Hugging Face weights on user-owned compute for private, offline, custom-head, fine-tuned, sustained, or explicitly owned-compute workloads.

## Analysis contract

1. Preserve the normalized sequence digest and exact model/revision.
2. Request only the outputs needed: sequence logits, per-residue embedding, mean embedding, selected hidden states, or named SAE models.
3. For the default biological residue-entropy metric, mask the evaluated residue, predeclare the allowed residue-token set, exclude special/control tokens, and renormalize over only those residue tokens. Keep full-vocabulary log probabilities separate. When explicitly reproducing the official PETase notebook, report its complete-vocabulary entropy in bits as a separately named tutorial metric with its token set and log base; never relabel it as residue entropy.
4. For zero-shot mutation scoring, report the documented score definition, typically `log P(mutant | masked context) - log P(wild type | masked context)`. Keep raw log probabilities and residue numbering.
5. Treat embeddings and SAE activations as features, not biological labels.
6. A downstream classifier/regressor becomes a prediction only after fitting on appropriate labeled data and validating on held-out, leakage-controlled data. Never run an untrained classification head and name its random output.
7. Record outputs and provenance atomically; large tensors should be files with checksums, not pasted into chat.

Biohub's pinned official mutation-landscape and SAE tutorials define two page-facing workflows in `../../examples/tutorial-use-cases.json`:

- `Map the mutational landscape of PETase and show me where it is most constrained or tolerant.` is a curated tutorial launcher. Disclose the pinned CaPETase literal before adopting it, run status-only preflight, then execute the exact `runtime.command` from the tutorial contract using the verified Python 3.12 environment; do not recreate the analysis in generated code. The shipped `esmc-landscape --tutorial petase` path validates the literal digest, uses a bounded 16-worker `ThreadPoolExecutor` for all 259 host-pinned managed logits calls, and writes exact-request-bound per-position checkpoints before producing `raw-responses.json`, `mutation-landscape.json`, `mutation-landscape.csv`, and `provenance.json`. If interrupted, use only `runtime.resume_command`; never replay an indeterminate submission. Present its constrained/tolerant summary, separately named full-vocabulary tutorial entropy, genuine-substitution fraction, and canonical-amino-acid LLRs. Do not route this to Modal: the plugin ships no ESMC Modal function.
- `Show me what ESMC has learned about ATP synthase and map the strongest features onto its structure.` is a curated launcher for experimental PDB 2XND chain A, using managed `esmc-6b-2024-12` with SAE `esmc-6b-2024-12-sae-layer60-k64-codebook16384`. Disclose that identity and the calls it makes: one RCSB FASTA fetch, one RCSB structure fetch, one managed encode request, one managed logits request, and five Atlas feature-detail fetches. Reproduce managed rather than local tokenization, normalized features, the strict `activation > 0.01` predicate, top 10 rankings by both maximum activation and prevalence, descriptions for the top five maximum-activation features, and a structure coloured by activation for the top three maximum-activation features, only after explicit sequence-to-coordinate alignment. Preserve the named raw, feature, ranking, alignment, Structure Viewer handoff, and provenance artifacts. This contract does not authorize provider calls: after the exact disclosure, obtain separate explicit current-turn confirmation before the RCSB, managed, or Atlas requests.

Lead with the science. Order every answer this way:

For the ATP structure map, follow the shared [result presentation handoff](../../references/structure-viewer-handoff.md): open the verified absolute artifact once, style only when ready, and report pending or unavailable viewing separately from the completed analysis.

1. The result: the ranked features, the score card, or the structure. Open or display it
   automatically; never ask permission to show a result.
2. Two or three sentences a scientist can react to — which positions or regions are
   constrained, which are tolerant, what stands out.
3. One line of scientific status: this is a model hypothesis, not an experimental
   measurement, and it needs validation.
4. The artifact paths, listed briefly.
5. Provenance, collapsed: pinned model revision, SDK revisions, input digest, checksums,
   and the exact route.
6. A link back to the relevant model card, such as <https://biohub.ai/models/esmc>.

Do not open with a plan, a list of the calls you intend to make, a cost estimate, or a
request for permission. If the user explicitly asks for a dry run or a planning-only answer, describe
the plan and say plainly that no provider call was made — that is the only case where a
no-call answer is correct.

The two exact page-facing prompts above may resolve their disclosed pinned tutorial targets. Otherwise resolve a bundled sequence only when the user explicitly names the official tutorial example. A generic PETase, ATP-synthase, A3M, or MSA request uses the user's supplied inputs or pauses for them; never silently substitute tutorial literals. Keep mutation analysis in the ESMC model family. For SAE interpretation, ESMC owns activation extraction; Atlas is an optional description lookup for the exact compatible feature dictionary, not a substitute inference route.

Run status-only preflight first; it reads no credential value and costs nothing. If managed access is missing, hand the user the key page from `$biohub-esm-setup` instead of a plan, then resume automatically once it is configured. The focused GB1 starter and exact PETase runtime run without separate confirmation; the ATP-synthase workflow requires the confirmation stated above. Managed requests may incur cost. Report provider-returned credit or token usage when available; otherwise state that the API did not report usage or cost, and never invent an estimate. Self-hosted GPU work and bulk data transfers are different: freeze the exact route, model/revision, item and call counts, input digest, output paths, persistence plan, and cost ceiling, show that scope, and ask a plain yes/no question before spending. Never require the user to repeat a specific phrase back to you.

For `What might W43F do to GB1?`, resolve the pinned fixture through `../../examples/starter-examples.json`; do not ask the user to paste the bundled sequence. Its managed path performs exactly one no-retry logits request and writes `raw-response.json`, `mutation-score.json`, `mutation-score.svg`, and `provenance.json`. The score records the masked context, both natural-log probabilities, one-based residue and zero-based tensor indices, exact model and SDK revisions, and checksums. After successful materialization, display `mutation-score.svg` inline by default; it is a visual summary of the model score, not evidence of fitness, stability, activity, binding, or function.

Read the exact [managed/SDK contract](references/api.md), [analysis guidance](references/analysis.md), and [self-hosting guidance](references/self-hosted.md).

Referenced files: 4

View saved version →

---
name: esmfold2
description: Use when the user needs ESMFold2 all-atom folding for proteins, DNA, RNA, modified residues, or ligands, including Fast/full routing, MSA, confidence, structures, and provenance. Not for dynamics, experimental truth, Atlas discovery, or binder campaigns.
---

# ESMFold2

## Choose the model

| Need | Managed | Hugging Face |
| --- | --- | --- |
| accuracy, difficult complexes, or optional MSA | `esmfold2-2026-05` | `biohub/ESMFold2` |
| fast single-sequence throughput | `esmfold2-fast-2026-05` | `biohub/ESMFold2-Fast` |

Fast is not MSA-conditioned. If the user supplies or requires an MSA, route to full ESMFold2 and validate query alignment. Missing MSA is not an error for a single-sequence fold unless the user explicitly required MSA conditioning.

For `Show me what GB1 looks like.`, resolve the thin launcher through `../../examples/starter-examples.json`; do not ask the user to paste the bundled sequence. Validate the pinned fixture and exact one-request contract in `../../examples/gb1-esmfold2-fast-fold-request.json`, then run it. Complete `preflight --endpoint fold` with the provisioned Python 3.12 runtime first and any `$biohub-esm-setup` work if access is missing, then execute one managed `POST /api/v1/fold` request with `include_pae=true`, the Fast parameters, and the `prediction.pdb`, `presentation-request.json`, `result.json`, `raw-response.json`, and `provenance.json` outputs. A single managed fold at this scale needs no confirmation. Managed requests may incur cost. Report provider-returned credit or token usage when available; otherwise state that the API did not report usage or cost, and never invent an estimate. Continue through local artifact recovery without repeating the provider request.

Also recognize the official-tutorial-shaped launchers in `../../examples/tutorial-use-cases.json`: an RNase H1–RNA/DNA hybrid, ubiquitin with a user-supplied A3M, a modified peptide–receptor complex with a covalent linker, and an antibody–antigen complex with user-supplied paired A3Ms. The exact plugin-page launcher `Model how a modified GLP-1 peptide with a lipid linker might engage GLP-1R, then show me the complex.` may resolve the pinned tutorial construct only after disclosing the tagged receptor construct, representative non-therapeutic linker, chemistry, covalent indices, route, model, request count, artifacts, and available cost information in the frozen plan. This tutorial contract does not authorize a provider call; obtain separate explicit current-turn confirmation for that exact fold. Outside that exact launcher or an explicitly named tutorial example, retain the user's sequences/MSAs or pause for missing biological input; never silently substitute the tutorial target. Modal and self-hosted GPU work also requires a frozen scope, cost ceiling, and plain yes/no confirmation. Present a successful structure by default without making the user translate the request into SDK objects, and lead with the structure rather than with a description of what you are about to do.

## Recover an accepted response

Use recovery only when a saved response proves the provider accepted and returned the request but local conversion or materialization failed. It makes zero provider calls. Never use it for an indeterminate submission, and always choose a new output directory that does not exist.

```bash
<python-3.12-with-pinned-esm> <plugin-root>/scripts/biohub_esm.py managed-recover \
  --endpoint fold_all_atom \
  --input /absolute/path/frozen-request.json \
  --raw-response /absolute/path/raw-response.json \
  [--source-provenance /absolute/path/provenance.json] \
  --output-dir /absolute/path/new-recovery-output
```

Use `--endpoint fold` for a saved sequence-fold response. Omit `--source-provenance` only when no matching incomplete provenance exists. Consume the new directory's validated `presentation-request.json` exactly; it retains the artifact identity and `openIntentId` for the presentation handoff.

## Build and validate input

Use the official pinned SDK's `StructurePredictionInput` with `ProteinInput`, `DNAInput`, `RNAInput`, `LigandInput`, and zero-based `Modification` positions. The managed wire schema permits omitted/null entity IDs; local/Hugging Face SDK execution requires explicit IDs. In either route, use unique explicit IDs for every entity referenced by pocket, distogram, or covalent-bond conditioning. A ligand uses either SMILES or CCD identifiers. Managed `/fold_all_atom` accepts either this `all_atom_input` shape or `sequence` with optional MSA, never both.

Load tutorial A3M input with `MSA.from_a3m(..., remove_insertions=True, max_sequences=1000)`, keep the insertion-removed query as row zero, and verify its ungapped sequence against the corresponding chain. Reject a tutorial MSA deeper than 1,000 rows before execution. The pinned SDK serializes non-empty A3M headers, and Biohub's paired-MSA tutorial requires standalone `key=<positive-decimal-taxonomy-id>` tokens in non-query headers to pair rows across chains. Preserve them on all-atom per-chain full-model requests and describe a row as paired only when the same exact key occurs in at least two chain MSAs. Top-level single-chain managed MSA requests omit headers because cross-chain pairing cannot apply there. Fast remains invalid whenever an MSA is supplied, even if a notebook initialized one Fast client before later MSA examples.

For modified/covalent complexes, the packaged validator checks zero-based residue bounds and nonnegative integer atom-index shape; it does not prove atom existence, valence, bond chemistry, or tutorial atom-index identity. Before execution, independently verify atom indices against the parsed residue templates and molecular graph. A SMILES atom index is not a character offset into the SMILES string. Preserve the exact construct and chemistry supplied; a tagged receptor or representative linker must not be described as the exact therapeutic molecule.

```bash
python3 <plugin-root>/scripts/biohub_esm.py validate-fold \
  --model esmfold2-2026-05 \
  --input /absolute/path/fold-input.json \
  --config /absolute/path/folding-config.json
```

For an official tutorial MSA workflow, use the stricter contract before showing the execution plan:

```bash
python3 <plugin-root>/scripts/biohub_esm.py validate-fold \
  --model esmfold2-2026-05 \
  --input /absolute/path/fold-input.json \
  --config /absolute/path/folding-config.json \
  --require-msa \
  --require-msa-insertions-removed \
  --msa-max-depth 1000
```

Add `--require-paired-msa-keys` for the paired antibody–antigen workflow.

Do not universalize the Biohub web UI's 700-residue entry cap as an architectural model limit. For managed model IDs, validate hosted parameters exactly: loops 0–20, sampling steps 1–100, LM dropout/mask fraction 0–1, MSA depth 1–16,384 or null, and MSA column mask fraction 0–1. For Hugging Face model IDs, validate the pinned local `ESMFold2InputBuilder.fold` contract instead; its sampling-step default is 200 and it additionally supports diffusion sample count, seed, sampler overrides, early exit, and complex ID. Do not apply hosted caps to self-hosted runs.

## Outputs

Prefer mmCIF for all-atom complexes; PDB can be lossy for complex chemistry. Preserve coordinates, pLDDT, pAE, pTM, iPTM, pair-chain iPTM, and requested distograms/embeddings when returned. The current managed API documents `include_pair_chains_iptm` for both `/fold` and `/fold_all_atom`; use the validated direct request when an SDK convenience method exposes a narrower signature. Record pLDDT on its current 0–1 scale and pAE in angstroms. For sequence `/fold`, their scopes are per-residue and residue-pair. For `/fold_all_atom`, their scopes are per-token and token-pair over the returned `complex.sequence` entries aligned by `complex.token_to_atoms`, including non-protein entity tokens. Record pTM/iPTM on their current 0–1 scale; PDB B-factors may encode pLDDT after an explicit SDK scale conversion.

Explain that the result is a static model hypothesis, not dynamics, affinity, or experimental truth. Low confidence, disorder, interfaces, ligands, modified residues, and unexpected topology require special caution and experimental validation.


Visibly report every returned `quality_warnings` item. Never silently repair coordinates, and never let high pLDDT override a chemistry or geometry warning.
After every successful fold, perform the [result presentation handoff](../../references/structure-viewer-handoff.md) without waiting for another request. Consume the validated `presentation-request.json`, give the available structure-viewing capability its verified absolute mmCIF or PDB once with its exact retained `openIntentId`, retain and verify the returned same-task session, and request predicted-confidence styling only when ready. Generate a new ID only for a legacy artifact set without that request file. Report viewer pending or unavailable separately, return checksummed artifacts, and do not create a custom viewer; presentation status never changes scientific success.

Read the [managed/SDK contract](references/api.md), [inputs and results](references/inputs-and-results.md), and [self-hosting/Modal guidance](references/self-hosted.md).

Referenced files: 4

View saved version →

---
name: esmfold2-binder-design
description: Use when the user needs ESMFold2 inversion for minibinder, binder, or scFv campaigns, Modal scale-out, candidate selection, persistence, or private self-hosting. Never route to Biohub managed API; not for ordinary folding or single-seed efficacy claims.
---

# ESMFold2 binder design

Binder design is not available through the Biohub managed API today. Route only to the released open-weight workflow on Modal or suitable user-owned compute. Modal public-weight execution needs Modal authentication, not `ESM_API_KEY`.

## Campaign contract

1. Validate target sequence/structure, binder modality (minibinder or scFv), templates, constraints, and biosafety/AUP fit.
2. Pin `Biohub/esm`, ESMFold2/ESMC weights, helper code, and every seed.
3. Explain scale honestly: useful campaigns normally need hundreds and often about 1,000 designs across seeds/templates. A one-seed smoke test verifies integration only and is not representative screening depth or efficacy.
4. Set explicit candidate-count, GPU, timeout, persistence, and concurrency bounds in the pinned campaign contract. Refresh current provider pricing and payment readiness, show the scope and a cost ceiling, and obtain separate explicit current-turn confirmation before material GPU spend.
5. Only after that confirmation, spawn no more than the confirmed job count, persist every call ID immediately, gather with partial-failure handling, and support cancellation/resume. A runtime `--confirm-cost` flag records the confirmed boundary; it never creates consent by itself.
6. Preserve sequences, trajectories, structures, raw metrics, selection table, exact critic configuration, and provenance. Do not select on one metric alone or claim affinity from structural confidence.
7. Require experimental screening and appropriate safety review before any biological conclusion.

The official Modal example uses an H100, persistent model/results Volumes, `spawn()` plus `FunctionCall.gather`, deterministic algorithms, and a server-side selection pass. The model plus four critic models are roughly 50 GB. A bounded live smoke uses exactly one seed and batch size one.

Read [Modal execution](references/modal.md), [campaign design and interpretation](references/campaign.md), and shared [safety/provenance](../../references/safety-and-provenance.md).

Referenced files: 3