skills/esmc/SKILL.md

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