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, showing a protein's 3D structure in the Biohub MCP's Mol* viewer, or choosing an ESM compute route. Do not use for unrelated non-ESM models, generic sequence alignment, or opening a local structure file in a non-Biohub viewer unless the user explicitly asks to compare it with Biohub ESM.
license: MIT
---

# Biohub ESM router

The user's instructions take precedence over guidelines provided in a skill.
If explicit user instructions conflict with a skill's instructions, prioritize the user's instructions.

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, clusters, Atlas structure views | public Biohub MCP | plugin script for the feature catalog, thumbnails, and batch; anonymous Atlas S3 for bulk data |
| Show one protein's ESM Atlas structure or Biohub MCP view | public Biohub MCP `ui_show_protein_structure` | ESMFold2 for a plain structure request, a new prediction, a complex, or a non-protein entity; `$esmc` for a follow-up on a protein it analyzed in this conversation |
| 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 |
| Private, offline, air-gapped, data-resident, customized, fine-tuned, sustained | Hugging Face weights on user-owned compute | user owns capacity and operations |

Binder, minibinder, and scFv design are not offered in this plugin. Answer that plainly, name what the plugin does cover, and stop. Do not hand the request to another skill, run the router or any other script for it, and do not propose a Modal, self-hosted, or managed route for it.

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. Each prompt authorizes only its disclosed exact calls once access is configured: the PETase 259-request managed runtime and its one Biohub MCP structure view, the ATP-synthase RCSB FASTA, managed, and Atlas requests and its one Biohub MCP structure view, and the GLP-1R one-request managed fold. 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` (on macOS, the Terminal steps with the returned `macos_keychain_command`), not a plan they cannot run, then resume automatically once the key is configured. If it reports `unverified`, a sandbox blocked the macOS Keychain; rerun preflight outside the sandbox before any key message, as `$biohub-esm-setup` describes. 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, the three exact plugin-page prompts (PETase, ATP-synthase, and GLP-1R), and every other managed ESMFold2 tutorial fold run without separate confirmation once their exact scope is disclosed. 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, protein names or accessions, MD5 records, clusters, Atlas structure views, the existing Atlas feature catalog, thumbnails, or Atlas batch data: use `$esm-atlas`. It answers through the Biohub MCP tools, so run no router script first, and never choose a chain, isoform, organism, or accession for a protein name before it resolves the name.
- Install, authentication, environment, or preflight problems: use `$biohub-esm-setup`.
- Showing a single protein's structure: every skill can show one with the Biohub MCP's `ui_show_protein_structure`, so the user sees the interactive Mol* viewer where the host renders MCP Apps, or its PNG preview elsewhere.
  A request to see a protein's ESM Atlas structure or its Biohub MCP view, such as `Show me the ESM Atlas structure for P69905.`, needs no new prediction, so hand it to `$esm-atlas`.
  A plain request to show or display a protein's 3D structure, such as `Could you display the 3D structure of GB1?`, stays with `$esmfold2`, except the follow-up below.
  The PETase landscape and the ATP-synthase feature map finish with the protein shown and the residues they singled out highlighted, as `$esmc` describes.
  That Biohub MCP view is their only structure presentation.
  A follow-up request to see the structure of a protein that `$esmc` analyzed in this conversation, such as `show me the structure`, stays with `$esmc`, which shows the same sequence and highlights again.
  An ESMFold2 fold of one unmodified protein chain, including `Show me what GB1 looks like.`, is shown first with the Biohub MCP view, labeled as the server's coordinates rather than the prediction.
  Unsupported structures and requests for the exact prediction file use the separately installed OpenAI Molecular Structure Viewer through the result presentation handoff.
  A missing MCP connection, denied approval, error, or unavailable preview is reported without switching viewers.
  A returned `sequence_too_long_to_fold` may hand an existing prediction to the OpenAI Molecular Structure Viewer without another fold.
  The tool takes one protein chain and folds an Atlas miss only up to 700 residues, so the GLP-1R complex and other multi-chain ESMFold2 results open only through the OpenAI Molecular Structure Viewer handoff.
  Never concatenate chains, strip modifications, or show only the receptor to make a complex fit the MCP tool.
  Read [Show a protein with the Biohub MCP](../../references/structure-viewer-handoff.md#show-a-protein-with-the-biohub-mcp) for highlights, residue numbering, labels, and failures.

## 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, or unverified.
- Script and provider routes preserve machine-readable artifacts and provenance, not UI-only results; Biohub MCP answers write no files and cite their tools and source in the answer instead.
- Finish successful workflows with the default [result presentation](../../references/structure-viewer-handoff.md): show supported protein sequences with the Biohub MCP first, use the OpenAI Molecular Structure Viewer only for unsupported structures or exact prediction files, open each verified artifact once, and keep pending or unavailable presentation separate from scientific artifact success.
- For structures unsupported by the MCP app or exact prediction files, use the [rendered-image fallback](../../references/structure-viewer-handoff.md#rendered-image-fallback) when the OpenAI Molecular Structure Viewer is unavailable.
- Supported sequence requests and MCP operational failures never use a custom replacement viewer.

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

Referenced files: 4

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, connecting the Biohub MCP for Atlas tools and its Mol* structure viewer, or fixing auth, rate-limit, credits, PATH, SDK, or GPU setup. Never ask for secret values.
license: MIT
---

# Biohub ESM setup and auth

The user's instructions take precedence over guidelines provided in a skill.
If explicit user instructions conflict with a skill's instructions, prioritize the user's instructions.

## 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 `biohub_managed.status` is `unverified`, the key may already be saved: a sandbox blocked the macOS Keychain.
Rerun the status-only preflight outside the sandbox before giving any key instruction, as **Keychain access on macOS** describes.

When no verified host credential action is available, give the instruction for the user's platform, alongside the Python blocker when applicable.
When preflight returns `macos_keychain_command` (macOS with the plugin installed), give the user these steps and quote that command exactly:

1. Get a free API key at https://biohub.ai/developer-console/api-keys (existing Forge accounts can sign in), then copy it.
2. Open Terminal (press Command-Space, type Terminal, and press Return), paste this command, and press Return:

   ```bash
   security add-generic-password -U -a "$USER" -s com.openai.codex.biohub-esm.ESM_API_KEY -w
   ```

3. At `password data for new item:`, paste the key and press Return.
   Nothing appears as you paste, so paste only once.
   At `retype password for new item:`, paste it again and press Return.
   If you see `passwords don't match`, paste the key at both prompts again.
4. Come back and send any message.
   No restart is needed.

These steps work in the desktop app, which does not inherit variables set in Terminal, and in the CLI.
Running the command again replaces the key it saved, and the plugin reads that item before any other.
Never run the command yourself; the user types the key into it, outside the chat.
Never suggest creating the item in the Keychain Access app: only this command is verified to create an item the plugin can read without a macOS approval prompt.
If the user already created one there, have them delete it in Keychain Access, then run the command.

Otherwise, on Linux, on Windows, or in a standalone skill install without the plugin's preflight, use this instruction:

> 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.

Always write the full URL as plain text, exactly `https://biohub.ai/developer-console/api-keys`.
Never hide it behind Markdown link text such as "Biohub's API key page", because some hosts show only the link text and leave the user with no clickable link and no address.

Preflight returns `obtain_key_url`, `variable`, `esm_sdk_runtime`, and on macOS `macos_keychain_command` 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, the exact
pinned `esm` and `transformers` wheels, 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`, `unverified`, `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, including every ESMFold2 tutorial fold, run without a separate confirmation; Modal, self-hosted, and bulk-transfer routes require the route-specific confirmation first. Run preflight and managed commands yourself when tool execution is available; the Keychain command under **No key yet** and the host command under **Biohub MCP connection** are the only commands the user runs. Never open or display `.modal.toml`; file presence is enough for preflight.

## Keychain access on macOS

When `ESM_API_KEY` is not set, the plugin reads the generic-password item that the Terminal command saves, then any other item whose service is `com.openai.codex.biohub-esm.ESM_API_KEY`.
A command sandbox can block the Keychain; the Codex sandbox does when its network access is off.
Inside such a sandbox, `security` fails with `SecKeychainSearchCreateFromAttributes: One or more parameters passed to a function were not valid.`, so a saved key looks absent.
Preflight reports that case as `unverified` with source `macos-keychain-unreachable`, and a managed command fails with a message that says the Keychain was unreachable.
When you see either, rerun that command outside the sandbox: request escalated permissions, and say the plugin needs to read the Biohub API key from the macOS Keychain.
Act on the outside-sandbox result, and never tell the user a key is missing because of a sandboxed result alone.
If the host cannot run the command outside its sandbox, give one handoff: the plugin reads the Keychain only when its commands run outside the sandbox, so the user approves that request or switches to a permission mode that allows it, then sends any message.
If the user has not saved a key yet, put the Terminal steps under **No key yet** in that same handoff.
If a managed command reports that a Keychain item exists but macOS did not release its value, give the Terminal steps again without asking for a new key; the plugin reads the item that command saves first.

## 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 for the user's platform. When preflight returned `macos_keychain_command`, give the Terminal steps under **No key yet**. Otherwise: get a free key at https://biohub.ai/developer-console/api-keys, set it as `ESM_API_KEY` in the environment that launches Codex, then restart Codex so it inherits the setting. 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 the user saves it with the Terminal steps under **No key yet** when preflight returns `macos_keychain_command`, or sets it in the environment that launches Codex and restarts 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.

## Biohub MCP connection

The public Biohub MCP at `https://biohub.ai/mcp` gives every Biohub ESM skill the ESM Atlas tools and `ui_show_protein_structure`.
That tool shows a protein's 3D structure in the interactive Mol* viewer where the host renders MCP Apps, and as a PNG preview in every other host.
The server is anonymous: it needs no key or sign-in, and preflight does not check it.
The plugin declares it in `.mcp.json` as the server `biohub`, so a plugin install connects it.

The MCP is connected when the tool catalog lists `ui_show_protein_structure` and the ESM Atlas tools, with or without a host prefix.
A `ui_show_protein_structure` that takes only a `structure_id` comes from a different Biohub server; the skills need the public one, whose tool takes `sequence`.
If the public tools are missing, give the user the one command for their host, because it changes their host configuration:

- Claude Code: `claude mcp add --transport http biohub https://biohub.ai/mcp`, then check it with `claude mcp list`.
- Codex: `codex mcp add biohub --url https://biohub.ai/mcp`, then check it with `codex mcp list`.
- Any other host: add a streamable HTTP server at `https://biohub.ai/mcp` with no authentication.

The host loads the new tools only after it restarts or reloads its MCP servers, so tell the user to do that, then resume the original request on their next message.
Resume only the steps that did not run: when an analysis finished and only its Biohub MCP view failed, make only that view call, and never repeat its provider requests.
Some hosts ask the user to approve a Biohub MCP tool before it runs; a denied approval is a tool failure, not a missing connection.

## Source/model-pinned install

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

```bash
python3.12 -m venv .venv
.venv/bin/python -m pip install "esm==3.4.1.post1" "transformers==4.57.6"
.venv/bin/python <plugin-root>/scripts/biohub_esm.py verify-install
```

Both pins are exact PyPI wheels.
`transformers==4.57.6` is the only release inside the range `esm==3.4.1.post1` declares, so the two resolve together in one install.
`verify-install` checks that each installed distribution is an index or wheel-file install whose version and payload digest match the pins, that every RECORD-listed file is present and unmodified, that no unlisted file sits in the package tree, and that the import location is the verified install.
Bytecode caches for recorded sources are trusted rather than re-verified.
It then prints the upstream source commits recorded in provenance.
On Linux without a GPU, add `--extra-index-url https://download.pytorch.org/whl/cpu` to the install to take the smaller CPU PyTorch build.
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 the auth failure without guessing other causes, then replace the key as below.
- `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.
- Replacing a rejected key: point at https://biohub.ai/developer-console/api-keys for a new one. If preflight reports source `macos-keychain`, give the Terminal steps under **No key yet** again; the command replaces the key it saved. If it reports source `environment`, the user replaces `ESM_API_KEY` where it is set, because it takes precedence over the Keychain.
- `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 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: 3

View saved version →

---
name: esm-atlas
description: Use when the user wants proteins similar to a protein, a protein name or accession resolved to a sequence, an Atlas record, SAE feature profile, or cluster context for a sequence, one Atlas SAE feature explained, or a protein structure viewed, all through the public Biohub MCP. Also use for the full Atlas feature catalog, thumbnails, batch jobs, MD5-only records, or anonymous S3 data, which stay on the plugin script. Use ESMC instead to extract SAE activations with a chosen ESMC checkpoint. Atlas is public data, not a model to deploy, and needs no client key.
license: MIT
---

# ESM Atlas

The user's instructions take precedence over guidelines provided in a skill.
If explicit user instructions conflict with a skill's instructions, prioritize the user's instructions.

Atlas is public data and discovery infrastructure, not a model to run on Modal or Hugging Face.
Answer Atlas questions through the public Biohub MCP, which is anonymous and needs no client key, and never through the plugin script, `curl`, or another HTTP client.
The plugin script remains only for the work the MCP does not cover: the full feature catalog, thumbnails, batch jobs, MD5-only records, and anonymous S3 data.
Every reply, including a clarifying question, states limits and choices as facts about the Atlas and never mentions, quotes, or links this skill, its rules, or its file.

## Tools

Resolve these logical tool names in the connected catalog.
A host may show a server prefix around a name, so match the logical name and never hard-code a prefix.

| Need | Tool |
| --- | --- |
| Protein name or UniProt accession to sequence | `esm_atlas_search_uniprot` |
| UniParc, MGnify, or IMG accession to sequence | `esm_atlas_lookup_accession` |
| Similar proteins | `esm_atlas_search_similar_protein_clusters` |
| Atlas record and top SAE features | `esm_atlas_get_protein_details` |
| Cluster context for a sequence | `esm_atlas_get_cluster_info` |
| One SAE feature | `esm_atlas_get_sae_feature_detail` |
| Structure view | `ui_show_protein_structure` |

If these tools are not in the catalog, say the Biohub MCP is not connected and point to `$biohub-esm-setup`.
Read [the MCP tool reference](references/mcp-tools.md) for arguments, returned fields, and error codes.

## Resolve the input

- Raw sequence or FASTA: drop the header and whitespace, keep every residue letter, and pass it on unchanged.
- UniProt accession, such as `P69905`: call `esm_atlas_search_uniprot` once with the accession as `query` and `size=1`, and accept only a record whose accession matches exactly.
- Protein name, such as `hemoglobin`: call `esm_atlas_search_uniprot` once with the name verbatim as `query` and `size=6`; never rewrite it, field it, or guess an accession first.
  When several candidates return, list their accessions, protein names, and organisms, and ask the user to choose without recommending one, even one you already mentioned.
- UniParc, MGnify, or IMG accession: call `esm_atlas_lookup_accession`, which does not accept UniProt accessions.
- A 32-character MD5 protein hash with no sequence: the MCP is keyed by sequence, so read the stored record with the script's `atlas protein --protein-hash` command and continue with its returned sequence.
- Starter launcher `Find proteins similar to GB1.`: resolve the pinned fixture in `../../examples/starter-examples.json`; never ask the user to paste the bundled sequence.

Function text returned while resolving an input describes the input, not the Atlas result, so never present it as Atlas evidence.

## Length limits

Never clip, truncate, or window a sequence yourself.

- Similarity search and SAE features take at most 2,048 residues.
  For a longer sequence, do not call the search; name the limit and the sequence length, and ask the user for a domain or residue range.
  A `sequence_too_long_for_features` error from `esm_atlas_get_protein_details` gets the same answer.
- `ui_show_protein_structure` returns stored Atlas coordinates at any supported length, and folds a miss only up to 700 residues.
  On `sequence_too_long_to_fold`, explain the 700-residue fold limit with the returned `actual_length`, and ask for a domain of at most 700 residues without retrying.

## Find similar proteins

For `Find proteins similar to GB1.`, or any similar-protein request:

1. Call `esm_atlas_search_similar_protein_clusters` exactly once with the resolved sequence, `top_k=10`, and `uncharacterized_only=false`, unless the user asked only for uncharacterized clusters.
2. Report up to ten hits in the returned order with accession, protein name, length, similarity score, and cluster size, and never manufacture missing hits.
3. For a non-empty result, call `ui_show_protein_structure` once with the top-ranked hit's returned `sequence`.
4. Make zero script calls, and make no cluster, protein-detail, or feature-detail follow-up calls unless the user asks what the neighbors are or do.

Read hits correctly:

- `similarity_score` is cosine similarity between sparse-autoencoder (SAE) feature vectors, not sequence identity, alignment, or homology.
- The search runs over cluster representatives only, so a missing relative can reflect index coverage rather than absence.
- A short or empty hit list means nothing cleared the service's unreported similarity floor, never that nothing exists.
- A nonzero `restricted_count` means results were withheld; say so without guessing what they held.
- `top_features_across_results` lists SAE features shared across hits; report counts as `occurrence_count` out of the returned hit count.
- A hit that scores far above the rest, is very short yet scores high, or has a `cluster_size` of one may be lab contamination such as an expression construct; flag it rather than feature it.

When the user asks what a protein does or which neighbors are informative, call `esm_atlas_get_cluster_info` for every hit, in parallel where the host allows, with each hit's returned `sequence`.
Rank neighbors by `cluster_pct_characterized`, then by how specific `top_pfam_domains` is, then by `cluster_size`, and never by similarity score alone.
Every cluster field describes the neighbor's cluster, never the query, and characterized means Pfam-annotated, not experimentally studied.

## Read a protein's record and features

Call `esm_atlas_get_protein_details` once with the exact sequence.
Report `sae_features` in returned order, copying each `label` verbatim.
Report `value` with its `label_reliability` band as signal strength only; the band is never a judgement of the label's quality.
Report `residue_regions` positions as returned, and never compare their raw `mean_activation` with the normalized `value`.
When `features_computed_on_miss` is true, say the sequence is not in the Atlas and its features were computed on demand; infer nothing more.
For a feature-profile request, call `esm_atlas_get_sae_feature_detail` once for each of the three features with the highest `value`, breaking ties by lowest `feature_index`, and use its `label`, `summary`, and `description` as the only biological wording; skip it for a plain record lookup.

Atlas features come from the fixed 16,384-feature dictionary of `esmc-6b-2024-12-sae-layer60-k64-codebook16384`.
Never apply them to another checkpoint, model, layer, or codebook; extract activations for a different SAE with `$esmc`.

## Show a structure

Call `ui_show_protein_structure` once with the exact sequence; pass `view_options` only when the user asks for a representation, confidence coloring, or highlighted residues.
Highlight a residue on chain `A` by its one-based position in that sequence, and set `expected_residue` to its three-letter code.
In a host that renders MCP Apps, the result opens the interactive Mol* viewer (`ui://biohub-public/structure-viewer/v1`).
Every host also receives a PNG preview and a text descriptor; describe what the preview shows in words, and never say a structure is shown above, write viewer code, draw your own image of the structure, or hand the result to a different viewer.
If `preview_status` is not `available`, say visual inspection is unresolved.
Atlas coordinates and on-demand folds are model hypotheses, not experimental structures.
When the user asks for an experimental method, resolution, or citation, say the Atlas does not provide one.
The other Biohub ESM skills use this same tool, as [Show a protein with the Biohub MCP](../../references/structure-viewer-handoff.md#show-a-protein-with-the-biohub-mcp) describes.

## Write the answer

Report only what the tools returned; never add proteins, structures, PDB entries, or literature from memory.
MCP answers write no files.
End every MCP answer with one source line naming each tool called, the Atlas version, and the license, for example:

`Source: Biohub MCP esm_atlas_search_similar_protein_clusters, ui_show_protein_structure; ESM Atlas v1 through the v1alpha1 API; CC-BY-4.0.`

Follow it with one link to <https://biohub.ai/esm/protein/atlas>.

## When a tool fails

Branch on the returned `code`, not on the message text.
`rate_limited` means wait as the error advises before one retry.
`indeterminate` means the compute outcome is unknown, so never retry it automatically.
`invalid_input`, `not_found`, `restricted`, `dependency_unavailable`, `resource_too_large`, and `internal_error` on the search or input resolution stop the answer without a biological conclusion.
A call the host blocks, for example by denying approval, is a failure too.
Name the failed tool and code, never retry with different arguments or switch to the script, and never fill the gap with results from memory, literature, or your own sequence comparison.

## Script route

The script needs no client key and writes `raw-response.json`, `result.json`, and `provenance.json` with each result.

```bash
# Full 16,384-feature catalog
python3 <plugin-root>/scripts/biohub_esm.py atlas features \
  --output-dir /absolute/path/features

# Stored record for an MD5 protein hash with no known sequence
python3 <plugin-root>/scripts/biohub_esm.py atlas protein \
  --protein-hash <md5> --output-dir /absolute/path/protein

# pLDDT or pct-characterized thumbnail for an MD5 protein hash
python3 <plugin-root>/scripts/biohub_esm.py atlas thumbnail \
  --protein-hash <md5> --thumbnail-type plddt \
  --output /absolute/path/thumbnail.png

# Batch of up to 500 unique MD5 hashes, with atomic resumable state
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
python3 <plugin-root>/scripts/biohub_esm.py atlas batch-cancel \
  --state /absolute/path/batch-state.json
```

Never pass `--fold-on-miss` to `atlas protein`; structures go through `ui_show_protein_structure`.
Small batches may return a zip immediately, and larger batches return resumable job state.
An interrupted submit without a durably captured `job_id` becomes `submission-indeterminate`: preserve it, reconcile manually with Atlas operators, and never resume or resubmit that state.
A definitive `400`, `401`, `402`, `403`, `404`, `422`, or `429` becomes `submission-rejected`, and only a new `batch-submit` for the exact same request may retry, never before the persisted `Retry-After` deadline.
To adopt an older job once, pass both `--state <new-path>` and `--job-id <id>`.
Cancellation is idempotent, and completed results can remain available.

Read the [script-route HTTP contract](references/api.md), the shared [safety and provenance contract](../../references/safety-and-provenance.md), and the [batch and S3 guidance](references/bulk-data.md), whose confirmation rules apply before any multi-gigabyte or multi-terabyte S3 transfer.

Referenced files: 5

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, or wants to see an analyzed protein's highlighted residues again in the Biohub MCP structure view. Sequence only; not for folding, Atlas lookup, or calling an untrained classifier predictive.
license: MIT
---

# ESMC

The user's instructions take precedence over guidelines provided in a skill.
If explicit user instructions conflict with a skill's instructions, prioritize the user's instructions.

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. Then show the protein with the Biohub MCP view, as [Show residues on the structure](#show-residues-on-the-structure) describes, and include that one view in the disclosure. 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 the RCSB FASTA sequence of 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 managed encode request, one managed logits request, five Atlas feature-detail fetches, and one Biohub MCP `ui_show_protein_structure` view. Reproduce managed rather than local tokenization, normalized features, the strict `activation > 0.01` predicate, top 10 rankings by both maximum activation and prevalence, and descriptions for the top five maximum-activation features. Map the top three maximum-activation features onto the structure with the Biohub MCP view, as [Show residues on the structure](#show-residues-on-the-structure) describes; do not fetch the experimental 2XND coordinates. Preserve the named raw, feature, ranking, structure-view, and provenance artifacts. After the exact disclosure, run preflight and then the RCSB, managed, Atlas, and Biohub MCP requests without asking first.

Lead with the science. Order every answer this way:

1. The result: the Biohub MCP structure view, the ranked features, or the score card. Show 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. If it is `unverified`, a sandbox blocked the macOS Keychain; rerun preflight outside the sandbox before any key handoff, as `$biohub-esm-setup` describes. The focused GB1 starter, the exact PETase runtime, and the exact ATP-synthase workflow run without separate 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. 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.

## Show residues on the structure

ESMC takes sequence only, so show its results on a structure with the Biohub MCP's `ui_show_protein_structure`.
Hosts that render MCP Apps show its interactive Mol* viewer, and other hosts get its PNG preview.
It is the only structure presentation for this skill.
Never draw a structure image or an activation map yourself with plotting, rendering, or viewer code, such as matplotlib, SVG, PyMOL, or py3Dmol.
Never show other coordinates, such as an experimental PDB entry, in place of the view.

After a successful analysis of one protein that singles out residues, call it once with the exact analyzed sequence:

- PETase landscape: highlight every position in `summary.most_constrained` of `mutation-landscape.json` in `#D55E00`, and every position in `summary.most_tolerant` in `#009E73`.
- ATP-synthase feature map: for each of the top three maximum-activation features in rank order, highlight its 10 highest-activation residues with `activation > 0.01` that no higher-ranked feature already highlights, and break a tie by the lower position.
  Color the first, second, and third feature `#D55E00`, `#009E73`, and `#CC79A7`, and name each color with its feature in the answer.
  Record the exact call arguments, the returned `descriptor`, and `preview_status` in `structure-view.json`.
  The view shows a stored Atlas prediction or an on-demand fold of the 2XND chain A sequence, not the experimental 2XND coordinates, so say that in the answer.
  The view highlights residues and cannot color by a value, so `per-residue-activations.csv` keeps every activation value.
  Say that each color marks only the feature's 10 strongest residues, not its full extent, and give the feature's count of residues with `activation > 0.01`.
  Name each residue by its position in the analyzed sequence, and say so.
  The 2XND chain A author number of a residue is its position plus 18, so give that number too when the answer links or compares with the 2XND entry or the literature.
  Never pass a 2XND author number as a highlight.
- A single mutation score, such as W43F in GB1: highlight the mutated residue when the user asks where it sits.

The PETase and ATP-synthase tutorial contracts name this call, so include it in their disclosures.
For other pinned workflows, name the view only in the answer's source line.
Highlight each residue on chain `A` by its one-based position in the analyzed sequence, and set `expected_residue` to the three-letter code of its wild-type residue.
This numbering needs no sequence-to-coordinate alignment, because the view folds or looks up the exact sequence passed.
If the call returns `invalid_input` because a highlighted residue identity does not match, correct the numbering one time; never remove `expected_residue`.
Highlight at most 32 residues: keep the 32 that the analysis ranks highest, and state how many it left out.
Describe the PNG preview in words, and if `preview_status` is not `available`, say that visual inspection is unresolved.
The highlights show where the model score or activation is, not a measured effect.
Name `ui_show_protein_structure` in the answer's source line.

When the user asks to see the structure again, call the view again with the same sequence and highlights, such as the arguments in `structure-view.json`.
This is not a refresh or a poll, so the one-call rule does not block it.
Do not fold the protein with ESMFold2 for that request.
An on-demand fold can compute again, so compare the new `descriptor.sha256` with the recorded one, and say when the coordinates differ.
When the user asks for the experimental 2XND structure, say that the Biohub MCP view cannot open a PDB entry, and link <https://www.rcsb.org/structure/2XND>.
Give the 2XND author numbers of the highlighted residues with that link.
If the tool is not in the catalog, returns an error code, or reports a `preview_status` other than `available`, give the analysis without a structure view and name the tool and the reason.
When the view could not run, write `structure-view.json` with the planned arguments, `called: false`, and the reason.
When the tool is not in the catalog, also say that the Biohub MCP is not connected and point to `$biohub-esm-setup`.
After the user connects it, make only the recorded view call, and never repeat the RCSB, managed, or Atlas requests.
The analysis result stands without the view, and a failed view never permits a self-drawn replacement.
Read [Show a protein with the Biohub MCP](../../references/structure-viewer-handoff.md#show-a-protein-with-the-biohub-mcp) for the full contract.

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

Referenced files: 5

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, or Atlas discovery.
license: MIT
---

# ESMFold2

The user's instructions take precedence over guidelines provided in a skill.
If explicit user instructions conflict with a skill's instructions, prioritize the user's instructions.

## 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 or `unverified`, 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 complex with an 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. After that disclosure, run preflight and its exact one-request managed fold without asking first. For every other tutorial fold (RNase H1, ubiquitin, and paired antibody-antigen), disclose the exact route, model, request count, parameters, construct, artifacts, and available cost information, then run that exact managed fold without asking first. 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.

## Present the result

- After every successful fold, present the result without waiting for another request.
- Choose the viewer from the input and the user's request before calling it.

1. For one unmodified protein sequence of 1 to 4,000 residues, call the Biohub MCP's `ui_show_protein_structure` once with the exact sequence unless the user requests the exact prediction file.
   Hosts that render MCP Apps show the interactive Mol* viewer, and other hosts get a PNG preview when available.
   The view shows stored Atlas coordinates or the server's own on-demand fold for that sequence, not this ESMFold2 prediction.
   Label it that way, and take pLDDT, pAE, pTM, and iPTM only from this fold's artifacts.
   Pass `color_by: confidence` only to show the view's own pLDDT, and highlight residues using the shared [MCP view contract](../../references/structure-viewer-handoff.md#show-a-protein-with-the-biohub-mcp).
2. For multiple chains, modified residues, ligands, DNA/RNA, a sequence outside the MCP input limits, or a request to see the exact prediction file, use the separately installed OpenAI Molecular Structure Viewer.
   Skip the MCP call for these inputs; never concatenate chains, remove modifications, or substitute a receptor-only view.
   Consume the validated `presentation-request.json` and open its verified absolute mmCIF or PDB once with its exact retained `openIntentId`.
   Retain the returned same-task session, verify the primary object, and request predicted-confidence styling only when ready.
   Generate a new ID only for a legacy artifact set without that request file.
   Discover the viewer's file-opening capability; if unavailable, render an image from the verified coordinate artifact using the shared rendered-image fallback below.
3. A missing MCP tool, denied approval, timeout, server error, or unavailable preview does not change the input's compatibility.
   Report the failure without switching viewers or repeating the fold.
   On `sequence_too_long_to_fold`, report the 700-residue Atlas-miss fold limit and returned `actual_length`, then hand the already-generated prediction to the OpenAI Molecular Structure Viewer without retrying the MCP call.
   Preserve pending or unavailable presentation separately from successful inference.

- Use the shared [result presentation handoff](../../references/structure-viewer-handoff.md) for the exact open, readiness, verification, and timeout-reconciliation contract.
- A follow-up asking to open an existing prediction uses that artifact without another provider request.

- Always return the checksummed artifacts.
- For structures unsupported by the MCP app, including exact prediction files, an agent-generated rendering image is allowed when the OpenAI Molecular Structure Viewer is unavailable.
- Follow the [rendered-image fallback](../../references/structure-viewer-handoff.md#rendered-image-fallback) to render the actual saved coordinates, display the image, and verify it.
- Do not generate a replacement viewer for supported sequence requests or MCP operational failures.
When the user asks to see a protein that `$esmc` analyzed in this conversation, do not fold it: `$esmc` shows it again with its highlights.
Presentation status never changes scientific success.
Read [Show a protein with the Biohub MCP](../../references/structure-viewer-handoff.md#show-a-protein-with-the-biohub-mcp) for the full contract of the view.

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: 5