README.md

# Biohub ESM plugin

This plugin turns natural protein questions into the scientifically appropriate ESM workflow:

- Biohub managed API for public ESMC inference, including bounded concurrent calls, and interactive ESMFold2 inference
- ESM Atlas public alpha API or anonymous S3 for discovery and public data
- Modal for bulk or long-running folds and binder-design campaigns
- pinned Hugging Face weights on user-owned compute for private, offline, data-resident, customized, fine-tuned, or sustained workloads

It intentionally does not add a hosted MCP server. The small standard-library client under `scripts/` handles deterministic routing, validation, readiness checks, Atlas HTTP, durable Modal job state, result presentation, and provenance. Managed HTTP stays lightweight; when `managed-post --output-dir` serializes a real ESMFold2 response for display, it lazily requires and verifies Biohub's exact pinned `esm` SDK revision.

Successful folds emit `presentation-request.json`; consumers use its verified absolute coordinate artifact and exact retained `openIntentId` for one open through an available molecular-structure-viewing capability, with predicted-confidence coloring requested only after readiness. Pending or unavailable presentation is reported separately from scientific success. Mutation scoring produces a compact SVG score card, and Atlas displays a returned structure or a public pLDDT thumbnail when available. Visuals are summaries; checksummed result and provenance artifacts remain authoritative. The plugin does not copy viewer code or generate a fallback HTML/JavaScript renderer. The [handoff reference](references/structure-viewer-handoff.md) records the current host adapter mapping.

## Marketplace starter experiences

The plugin page highlights one visual, outcome-rich workflow from each official Biohub tutorial:

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

The machine-readable [`examples/tutorial-use-cases.json`](examples/tutorial-use-cases.json) is the source of truth for those visible defaults and the broader prompt gallery. It binds each natural question to the pinned official [mutation-scoring](https://github.com/Biohub/esm/blob/main/cookbook/tutorials/esmc_mutation_scoring.ipynb), [SAE interpretation](https://github.com/Biohub/esm/blob/main/cookbook/tutorials/esmc_sae_feature_interpretation.ipynb), or [ESMFold2](https://github.com/Biohub/esm/blob/main/cookbook/tutorials/esmfold2.ipynb) workflow, plus exact hidden inputs, scientific invariants, and automatic presentation.

The PETase card invokes the shipped `esmc-landscape --tutorial petase` command. That command validates the pinned sequence, makes all 259 managed logits calls through a bounded 16-worker pool, and writes raw-response, JSON, CSV, and provenance artifacts before returning the constrained and tolerant positions.

## Reproducible GB1 regression experiences

The original focused-skill starters remain available as compact, exactly executable regression workflows:

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

The packaged [`examples/starter-examples.json`](examples/starter-examples.json) contract resolves `GB1` to the pinned RCSB 1PGA chain-A sequence and owns the exact input, route, request, output, and presentation details. Users do not need to paste an amino-acid sequence or specify internal artifact names to get a traceable result. The fold request is separately materialized at [`examples/gb1-esmfold2-fast-fold-request.json`](examples/gb1-esmfold2-fast-fold-request.json). Validate the contract and every prompt surface with:

Selecting a starter runs it. Status-only preflight goes first, and when managed access is missing the plugin hands back the API-key page rather than a plan. Managed Biohub inference at tutorial scale then runs without a 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. Modal, self-hosted GPU campaigns, and bulk transfers still show the exact route, request scope, artifact plan, and cost ceiling and ask a plain yes/no question first. Small public Atlas API reads need no confirmation either, but every route still respects an explicit planning-only or no-network request. 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. Automatic SVG or Structure Viewer presentation happens only after successful checksummed artifact creation.

Atlas protein-record lookup is non-folding by default. On-demand folding requires an explicit opt-in and a guarded preliminary lookup that returns the actual stored sequence, verifies its MD5 binding and supported alphabet, and proves it is no longer than 699 residues. Missing sequence evidence, length-only metadata, a hash mismatch, an unsupported residue, or an over-limit sequence stops before a fold request.

```bash
python3 plugins/biohub-esm/scripts/validate_starter_examples.py
```

## Additional tutorial-informed use cases

The official Biohub notebooks also inform a broader prompt gallery. The three exact marketplace prompts above are curated tutorial launchers: the plugin discloses the pinned tutorial target or construct, route, and request count, then runs the managed workflow and leads with the result. Other prompts that use a bundled tutorial literal say so explicitly; prompts that say “my” retain the user's supplied input and never substitute tutorial data:

- `Reproduce the official Biohub PETase ESMC mutation-landscape tutorial example.`
- `Reproduce the official Biohub ATP synthase SAE feature-interpretation tutorial example.`
- `Reproduce the official Biohub RNase H1 RNA-DNA hybrid ESMFold2 tutorial example.`
- `Using my supplied ubiquitin A3M, follow the official Biohub ESMFold2 tutorial example and show the structure and confidence.`
- `Reproduce the official Biohub modified GLP-1 peptide with lipid linker ESMFold2 tutorial example.`
- `Using my supplied paired antibody-antigen A3Ms, follow the official Biohub ESMFold2 tutorial example.`

The machine-readable [`examples/tutorial-use-cases.json`](examples/tutorial-use-cases.json) maps those prompts and their shorter tutorial-shaped aliases to the pinned official [mutation-scoring](https://github.com/Biohub/esm/blob/main/cookbook/tutorials/esmc_mutation_scoring.ipynb), [SAE interpretation](https://github.com/Biohub/esm/blob/main/cookbook/tutorials/esmc_sae_feature_interpretation.ipynb), and [ESMFold2](https://github.com/Biohub/esm/blob/main/cookbook/tutorials/esmfold2.ipynb) workflows. It records plugin-specific corrections, compatibility rules, route/call-count boundaries, exact target-disclosure rules, and which routes run directly versus which ask before spending.
## Local validation

Run these commands from the repository's `biohub-esm/` marketplace directory.
The development harness and contract tests live under `plugins/biohub-esm/tests/` and travel with the complete plugin source.
The source-owned runtime builder excludes the development harness, its own development-only helper, ignored Python bytecode, Ruff and test caches, and untracked files.
Tests remain tracked in the repository but are not included in runtime packages.

```bash
PYTHONPATH=plugins/biohub-esm python3 -m unittest discover -s plugins/biohub-esm/tests -p 'test_*.py' -v
python3 plugins/biohub-esm/scripts/validate_starter_examples.py
python3 plugins/biohub-esm/scripts/biohub_esm.py preflight
.venv/bin/python plugins/biohub-esm/scripts/biohub_esm.py preflight --endpoint fold_all_atom
python3 plugins/biohub-esm/scripts/build_runtime_package.py \
  /absolute/new/path/biohub-esm \
  --commit HEAD
```

Development-only live-smoke details live in `tests/README.md`. Installed copies remain self-contained and do not rely on the development-only test directory.

The upstream OpenAI repository owns the maintainer release workflow.
This mirror keeps the checked-in runtime builder separately from the installed plugin.

The complete plugin component inventory is recorded in [`references/component-contract-audit.md`](references/component-contract-audit.md). The managed and Atlas endpoint matrix, coverage boundaries, and known discrepancies inside the published references are in [`references/api-contract-audit.md`](references/api-contract-audit.md).