skills/biohub-esm/references/routing.md

# Routing details

The product distinctions come from the [Biohub protein world model](https://biohub.ai/esm/protein), [get-started guide](https://biohub.ai/esm/protein/get-started), and [Biohub/esm source](https://github.com/Biohub/esm).

## Decision order

1. If the goal is lookup/discovery across existing proteins, the existing Atlas feature catalog, or cluster context, choose Atlas. Use anonymous S3 only for bulk datasets. If the goal is to extract or interpret SAE activations for a supplied sequence, choose ESMC; a combined workflow may then query Atlas descriptions only for the exact compatible SAE dictionary.
2. If the goal is binder design, exclude Biohub managed inference. Choose Modal unless privacy/customization/owned infrastructure points to self-hosting.
3. If privacy, offline execution, data residency, custom heads, fine-tuning, or sustained ownership is required, choose pinned Hugging Face weights on user-owned compute. Public weights need no `HF_TOKEN`.
4. For public ESMC inference, choose the Biohub managed API and use `ESM_API_KEY`, including bounded concurrent calls that the managed backend can auto-batch. The plugin ships no ESMC Modal function. If the user specifically wants owned compute, choose pinned self-hosted weights instead.
5. If folding work is many independent calls or long running, use pinned weights on suitable user-owned GPUs when they are available; otherwise choose Modal. Public weights on owned compute need no key, and Modal needs Modal auth but no `ESM_API_KEY`.
6. Otherwise, choose Biohub managed ESMFold2 and use `ESM_API_KEY`.

Small public Atlas API reads need no spend confirmation. Bulk anonymous-S3 access is different: before any multi-gigabyte or multi-terabyte transfer, freeze the exact source prefix, destination, estimated bytes, storage and egress impact, and cost ceiling, then obtain separate explicit current-turn confirmation.

## ESMFold2 variant

- Full: accuracy-priority targets, difficult complexes, optional MSA.
- Fast: single-sequence latency and throughput; never promise MSA conditioning.

## Examples

| Request | Result |
| --- | --- |
| "What might W43F do to GB1?" | Resolve the pinned GB1 fixture, validate W43F numbering, run preflight, make one managed `esmc-600m-2024-12` request, and display the resulting score card. 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. |
| "Show me what GB1 looks like." | Resolve the pinned single-chain fixture, run `preflight --endpoint fold` in the provisioned Python 3.12 runtime, make one managed `esmfold2-fast-2026-05` request, and open the prediction in the Structure Viewer with pLDDT coloring |
| "Find proteins similar to GB1." | Run one public Atlas similarity search, return validated ranked hits, and display a returned structure or top-hit pLDDT thumbnail |
| "Map the mutational landscape of PETase and show me where it is most constrained or tolerant." | Disclose the pinned CaPETase tutorial sequence, then run all 259 masked contexts against managed `esmc-600m-2024-12` concurrently through a bounded pool, and summarize the separately named tutorial entropy and 19 genuine substitutions per site. 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. |
| "Show me what ESMC has learned about ATP synthase and map the strongest features onto its structure." | Disclose pinned experimental PDB 2XND chain A plus the calls it makes: one RCSB FASTA, one RCSB structure, one managed encode, one managed logits, and five Atlas feature fetches. Obtain separate explicit current-turn confirmation, then use normalized exact-dictionary activations, the strict `> 0.01` predicate, top-10 maximum and prevalence rankings, top-five descriptions, and top-three aligned structure maps with named raw/derived/provenance artifacts |
| "Model how a modified GLP-1 peptide with a lipid linker might engage GLP-1R, then show me the complex." | Disclose the tagged receptor construct, representative non-therapeutic linker, exact fold, and artifacts; obtain separate explicit current-turn confirmation; then preserve covalent indexing and open the model hypothesis automatically |
| "Reproduce the official Biohub RNase H1 RNA-DNA hybrid ESMFold2 tutorial example." | Resolve the pinned tutorial literals, run the managed all-atom call, preserve chain-aware confidence, and open the result automatically |
| "Using my supplied ubiquitin A3M, follow the official Biohub ESMFold2 tutorial example and show the structure and confidence." | Retain the user's A3M, apply the pinned query-first insertion-removal preprocessing, route to full managed ESMFold2, run it, and open the result with pLDDT coloring |
| "Fold 500 designs" | pinned `biohub/ESMFold2-Fast` on suitable owned GPUs when available; otherwise Modal; use full for accuracy/MSA |
| "Design minibinders" | Modal or self-hosted only |
| "My sequence cannot leave our VPC" | pinned self-hosted weights |

The `item_count > 32` code branch is a conservative folding-orchestration heuristic to surface scale-out early. It does not apply to ESMC and is not an account quota or provider guarantee.

The expanded use-case details are pinned to Biohub's official notebooks in [`examples/tutorial-use-cases.json`](../../../examples/tutorial-use-cases.json). The PETase prompt authorizes only its exact shipped 259-request managed runtime; ATP-synthase and GLP-1R require separate explicit current-turn confirmation. Planning-only or no-network requests override, and Modal, self-hosted, and bulk-transfer work requires route-specific confirmation.