alterlab-esm
Run ESM protein language models — ESMC for embeddings and representations, ESMFold2 for structure prediction, and ESM3 for generative multimodal protein design across sequence, structure, and function — locally or through the hosted Biohub Platform API (formerly Forge). Use when
Install
npx skills add https://github.com/AlterLab-IEU/AlterLab-Academic-Skills/tree/main/skills/bioinformatics/alterlab-esm
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install alterlab-ieu-alterlab-academic-skills@llmmart
git clone https://github.com/AlterLab-IEU/AlterLab-Academic-Skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole alterlab-ieu/alterlab-academic-skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
ESM: Evolutionary Scale Modeling
Overview
Keyless by default. The open weights — ESMC 300M/600M and ESM3-sm-open-v1 — are public on Hugging Face (verified: not gated, no HF_TOKEN needed) and run locally. Embeddings, logits, masked-sequence completion, inverse folding, and generative design all work offline on these weights; a small ESMC model runs on CPU (slowly) when no GPU is available. The hosted Biohub Platform (the 7B/98B ESM3 models, ESMC-6B, ESMFold2) is an optional add-on that uses an ESM_API_KEY; when no token is set, use the open local model instead.
ESM provides state-of-the-art protein language models for understanding, generating, and designing proteins. Three families ship in the same esm package:
- ESMC — the current representation model (300M / 600M open weights, 6B via the hosted platform), used for embeddings, logits, and downstream ML features.
- ESMFold2 — structure prediction built on ESMC-6B, hosted via
esmfold2_client. - ESM3 — the generative multimodal model over sequence / structure / function tracks.
Naming and hosting changed — read this before copying old code
EvolutionaryScale now operates as Biohub. The practical consequences:
- The hosted API moved from
forge.evolutionaryscale.aitohttps://biohub.ai; every client inesm.sdkdefaults to that URL and reads the token fromESM_API_KEY. The classes are still named*ForgeInferenceClientfor backwards compatibility. - Model weights live under the
biohubHugging Face organisation (biohub/ESMC-6B,biohub/esm3-sm-open-v1,biohub/ESMFold2). - ESMC and ESMFold2 are also available through Hugging Face Transformers v5.16+, which is
a different dependency stack from the
esmpackage's optimized inference path.
When to Use This Skill
Use this skill when the user wants protein embeddings or logits, a protein structure from an ESM model, inverse folding, or generative sequence design.
Does NOT Trigger
| Scenario | Use Instead |
|---|---|
| Fold a protein or complex with AlphaFold2/ColabFold | alterlab-alphafold |
| Co-fold with a ligand, or predict binding affinity | alterlab-boltz |
| Antibody–antigen or mixed multi-entity complexes | alterlab-chai |
| Design a sequence for a fixed backbone (ProteinMPNN family) | alterlab-proteinmpnn, alterlab-ligandmpnn |
| Generate a de-novo backbone to design onto | alterlab-rfdiffusion |
| Low-dimensional latent embedding / batch integration of single-cell RNA-seq (cells, not proteins) | alterlab-scvi-tools |
| Deterministic sequence bookkeeping — molecular weight, isoelectric point, parsing a FASTA | alterlab-biopython |
Hand-off rule. When the request matches a row above, open your answer by naming that skill by its exact id (for example alterlab-alphafold) and saying in one line why it fits better, then stop applying this skill's procedure. Name it even when you also need to ask for missing input. If only part of the request is out of scope, name the skill for that part and do only the in-scope part. A brief general pointer is fine; the named skill does the work.
Core Capabilities
1. Protein Sequence Generation with ESM3
Generate novel protein sequences with desired properties using multimodal generative modeling.
When to use:
- Designing proteins with specific functional properties
- Completing partial protein sequences
- Generating variants of existing proteins
- Creating proteins with desired structural characteristics
Basic usage:
from esm.models.esm3 import ESM3
from esm.sdk.api import ESM3InferenceClient, ESMProtein, GenerationConfig
# Load model locally
model: ESM3InferenceClient = ESM3.from_pretrained("esm3-sm-open-v1").to("cuda")
# Create protein prompt
protein = ESMProtein(sequence="MPRT___KEND") # '_' represents masked positions
# Generate completion
protein = model.generate(protein, GenerationConfig(track="sequence", num_steps=8))
print(protein.sequence)
For remote/cloud usage via the Biohub Platform:
import esm
from esm.sdk.api import ESMProtein, GenerationConfig
# url defaults to https://biohub.ai and token to os.environ["ESM_API_KEY"]
model = esm.sdk.client("esm3-medium-2024-08")
protein = model.generate(protein, GenerationConfig(track="sequence", num_steps=8))
See references/esm3-api.md for detailed ESM3 model specifications, advanced generation configurations, and multimodal prompting examples.
2. Structure Prediction and Inverse Folding
Use ESM3's structure track for structure prediction from sequence or inverse folding (sequence design from structure).
Structure prediction:
from esm.sdk.api import ESM3InferenceClient, ESMProtein, GenerationConfig
# Predict structure from a complete sequence
protein = ESMProtein(sequence="MPRTKEINDAGLIVHSP")
protein_with_structure = model.generate(
protein,
# num_steps controls how many structure tokens are decoded per step;
# use the sequence length (not a "_" count — the sequence is complete here)
GenerationConfig(track="structure", num_steps=len(protein.sequence))
)
# Access predicted structure
coordinates = protein_with_structure.coordinates # 3D coordinates
pdb_string = protein_with_structure.to_pdb()
Inverse folding (sequence from structure):
# Design sequence for a target structure
protein_with_structure = ESMProtein.from_pdb("target_structure.pdb")
protein_with_structure.sequence = None # Remove sequence
# Generate sequence that folds to this structure
designed_protein = model.generate(
protein_with_structure,
GenerationConfig(track="sequence", num_steps=50, temperature=0.7)
)
3. Protein Embeddings with ESM C
Generate high-quality embeddings for downstream tasks like function prediction, classification, or similarity analysis.
When to use:
- Extracting protein representations for machine learning
- Computing sequence similarities
- Feature extraction for protein classification
- Transfer learning for protein-related tasks
Basic usage:
from esm.models.esmc import ESMC
from esm.sdk.api import ESMProtein, LogitsConfig
# Load ESMC locally (local from_pretrained names use UNDERSCORES; default is esmc_600m)
model = ESMC.from_pretrained("esmc_300m").to("cuda")
# Encode, then request embeddings via the logits() API
protein = ESMProtein(sequence="MPRTKEINDAGLIVHSP")
protein_tensor = model.encode(protein)
out = model.logits(protein_tensor, LogitsConfig(sequence=True, return_embeddings=True))
embeddings = out.embeddings # (1, L+2, hidden_dim), incl. BOS/EOS tokens
logits = out.logits.sequence # per-position amino-acid logits
Do NOT call model.forward(...) to get embeddings — forward returns a raw model output, not a usable representation tensor. Use model.logits(..., LogitsConfig(return_embeddings=True)).embeddings.
Batch processing:
# Encode multiple proteins and pull mean-pooled embeddings
proteins = [
ESMProtein(sequence="MPRTKEIND"),
ESMProtein(sequence="AGLIVHSPQ"),
ESMProtein(sequence="KTEFLNDGR"),
]
cfg = LogitsConfig(sequence=True, return_embeddings=True)
embeddings_list = [
model.logits(model.encode(p), cfg).embeddings.mean(dim=1) for p in proteins
]
See references/esm-c-api.md for ESM C model details, efficiency comparisons, and advanced embedding strategies.
4. Function Conditioning and Annotation
Use ESM3's function track to generate proteins with specific functional annotations or predict function from sequence.
Function-conditioned generation:
from esm.sdk.api import ESMProtein, FunctionAnnotation, GenerationConfig
# Create protein with desired function
protein = ESMProtein(
sequence="_" * 200, # Generate 200 residue protein
function_annotations=[
FunctionAnnotation(label="fluorescent_protein", start=50, end=150)
]
)
# Generate sequence with specified function
functional_protein = model.generate(
protein,
GenerationConfig(track="sequence", num_steps=200)
)
5. Chain-of-Thought Generation
Iteratively refine protein designs using ESM3's chain-of-thought generation approach.
from esm.sdk.api import GenerationConfig
# Multi-step refinement
protein = ESMProtein(sequence="MPRT" + "_" * 100 + "KEND")
# Step 1: Generate initial structure
config = GenerationConfig(track="structure", num_steps=50)
protein = model.generate(protein, config)
# Step 2: Refine sequence based on structure
config = GenerationConfig(track="sequence", num_steps=50, temperature=0.5)
protein = model.generate(protein, config)
# Step 3: Predict function
config = GenerationConfig(track="function", num_steps=20)
protein = model.generate(protein, config)
6. Batch processing against the hosted platform
The client exposes both an async API and a parallel executor that handles retries and a progress bar:
import asyncio
import esm
from esm.sdk import parallel_executor
from esm.sdk.api import ESMProtein, GenerationConfig
client = esm.sdk.client("esm3-medium-2024-08") # token from ESM_API_KEY
proteins = [ESMProtein(sequence=f"MPRT{'_' * 50}KEND") for _ in range(10)]
cfg = GenerationConfig(track="sequence", num_steps=8)
# Option A: async fan-out
async def run():
return await asyncio.gather(*(client.async_generate(p, cfg) for p in proteins))
results = asyncio.run(run())
# Option B: managed executor (retries + progress)
with parallel_executor() as executor:
results = executor.execute_batch(client.generate, protein=proteins, config=cfg)
Also available: client.batch_generate(...) / async_batch_generate(...), and
async_fold / async_inverse_fold / async_logits for the other tracks.
See references/forge-api.md for platform documentation, authentication, rate limits, and
batch processing patterns.
Model Selection Guide
ESM3 Models (Generative):
esm3-sm-open-v1(1.4B, aliasesesm3_sm_open_v1/esm3-open) — open weights, localesm3-medium-2024-08(7B) — balance of quality and speed (hosted only)esm3-large-2024-03(98B) — highest quality, slower (hosted only)
ESMC Models (Representations):
esmc_300m— lightweight, fast; open weights, runs locallyesmc_600m— balanced; open weights, runs locally, and thefrom_pretraineddefaultesmc_6b/ hostedesmc-6b-2024-12— maximum representation quality
ESMFold2 (Structure): esmfold2-fast-2026-05 (the esmfold2_client default),
esmfold2-2026-05, esmfold2-2026-05-cutoff-2025.
Naming gotcha: local from_pretrained(...) names use underscores (esmc_300m,
esmc_600m, esmc_6b). Hosted client strings use hyphens with a date
(esmc-600m-2024-12, esm3-medium-2024-08, esmfold2-fast-2026-05).
Selection criteria:
- Local development/testing:
esmc_300mfor embeddings,esm3-sm-open-v1for generation - Production quality:
esm3-medium-2024-08oresmc-6b-2024-12via the Biohub Platform - Structure prediction:
esmfold2_client()rather than the ESM3 structure track - High throughput: hosted clients plus
esm.sdk.parallel_executor/ batch client - Cost optimization: smaller models, cache embeddings
Installation
Basic installation (pin the minor — the SDK still changes across releases):
uv pip install "esm>=3.4,<3.5" # 3.4.1.post1 as of 2026-09; needs Python >= 3.12
With Flash Attention (optional, faster GPU inference):
uv pip install flash-attn --no-build-isolation
Local weights for the open models (esmc_300m, esmc_600m, esm3-sm-open-v1) are pulled
from the public Hugging Face biohub repos and need no Hugging Face login — the repos
are not gated. huggingface_hub.login() is only needed if you point at a gated/private
repo or want higher download rate limits.
The hosted clients (esm.sdk.client, esmc_client, esmfold2_client) ship inside the
esm package — no extra install, and only used for the larger hosted-only models. For
those, create an API token in the Biohub developer console
(https://biohub.ai/developer-console/api-keys) and export it as ESM_API_KEY.
ESMC through the Biohub Platform:
from esm.sdk import esmc_client
from esm.sdk.api import ESMProtein, LogitsConfig
model = esmc_client(model="esmc-600m-2024-12") # url/token default as above
out = model.logits(model.encode(ESMProtein(sequence="MPRTKEINDAGLIVHSP")),
LogitsConfig(sequence=True, return_embeddings=True))
print(out.logits, out.embeddings)
Common Workflows
For detailed examples and complete workflows, see references/workflows.md which includes:
- Novel GFP design with chain-of-thought
- Protein variant generation and screening
- Structure-based sequence optimization
- Function prediction pipelines
- Embedding-based clustering and analysis
References
This skill includes comprehensive reference documentation:
references/esm3-api.md- ESM3 model architecture, API reference, generation parameters, and multimodal promptingreferences/esm-c-api.md- ESM C model details, embedding strategies, and performance optimizationreferences/forge-api.md- Forge platform documentation, authentication, batch processing, and deploymentreferences/workflows.md- Complete examples and common workflow patterns
These references contain detailed API specifications, parameter descriptions, and advanced usage patterns. Load them as needed for specific tasks.
Best Practices
For generation tasks:
- Start with smaller models for prototyping (
esm3-sm-open-v1) - Use temperature parameter to control diversity (0.0 = deterministic, 1.0 = diverse)
- Implement iterative refinement with chain-of-thought for complex designs
- Validate generated sequences with structure prediction or wet-lab experiments
For embedding tasks:
- Batch process sequences when possible for efficiency
- Cache embeddings for repeated analyses
- Normalize embeddings when computing similarities
- Use appropriate model size based on downstream task requirements
For production deployment:
- Use the hosted Biohub Platform for scalability and the largest models
- Implement error handling and retry logic for API calls
- Monitor token usage and implement rate limiting
- Consider AWS SageMaker deployment for dedicated infrastructure
Resources and Documentation
- GitHub Repository: https://github.com/Biohub/esm (ESM3 docs live in
_assets/ESM3_README.md) - Biohub Platform: https://biohub.ai — API keys at https://biohub.ai/developer-console/api-keys
- ESM Atlas: https://biohub.ai/esm/protein/atlas
- ESM3 paper: Hayes et al., Science — https://www.science.org/doi/10.1126/science.ads0018
- Tutorials: https://github.com/Biohub/esm/tree/main/cookbook/tutorials
- Model Weights: Hugging Face
biohuborganization
Responsible Use
ESM is designed for beneficial applications in protein engineering, drug discovery, and scientific research. Biohub publishes an Acceptable Use Policy and ran a biosafety/biosecurity risk assessment before release — follow that policy, and the Responsible Biodesign Framework (https://responsiblebiodesign.ai/), when designing novel proteins. Think through biosafety and dual-use implications before experimental validation, because a designed sequence leaves the computational realm the moment it is ordered.
Part of the AlterLab Academic Skills suite.
Files (alterlab-academic-skills)
-
evals
-
evals.json 4.9 KB
Loading…
-
-
references
-
esm-c-api.md 17.6 KB
Loading… -
esm3-api.md 12.5 KB
Loading… -
forge-api.md 18.4 KB
Loading… -
workflows.md 20.7 KB
Loading…
-
-
SKILL.md 16.5 KB
--- name: alterlab-esm description: Run ESM protein language models — ESMC for embeddings and representations, ESMFold2 for structure prediction, and ESM3 for generative multimodal protein design across sequence, structure, and function — locally or through the hosted Biohub Platform API (formerly Forge). Use when working with protein sequences, structures, or function prediction, designing novel proteins, generating protein embeddings, performing inverse folding, or doing protein-engineering tasks. Part of the AlterLab Academic Skills suite. license: MIT allowed-tools: Read Write Edit Bash(python:*) Bash(uv:*) compatibility: "No API key required: the open ESMC (300M/600M) and ESM3-sm-open-v1 weights are public on Hugging Face (no HF_TOKEN) and run locally under `uv run python` with the `esm` package (3.4.1.post1 as of 2026-09; Python >= 3.12, torch >= 2.11) — a CUDA GPU is fastest, CPU works for small ESMC embeddings (slow). The hosted Biohub Platform (larger ESM3 / ESMC-6B / ESMFold2 models) is an optional extra that uses an ESM_API_KEY." metadata: skill-author: AlterLab credentials: "optional: ESM_API_KEY (hosted Biohub Platform — ESM3 medium/large, ESMC-6B, ESMFold2; the open local weights need none); HF_TOKEN (only for gated HF repos — the ESMC and ESM3-open weights are public)" version: "1.1.1" last_updated: "2026-09-23" --- # ESM: Evolutionary Scale Modeling ## Overview **Keyless by default.** The open weights — ESMC 300M/600M and ESM3-sm-open-v1 — are public on Hugging Face (verified: not gated, no `HF_TOKEN` needed) and run locally. Embeddings, logits, masked-sequence completion, inverse folding, and generative design all work offline on these weights; a small ESMC model runs on CPU (slowly) when no GPU is available. The hosted Biohub Platform (the 7B/98B ESM3 models, ESMC-6B, ESMFold2) is an optional add-on that uses an `ESM_API_KEY`; when no token is set, use the open local model instead. ESM provides state-of-the-art protein language models for understanding, generating, and designing proteins. Three families ship in the same `esm` package: - **ESMC** — the current representation model (300M / 600M open weights, 6B via the hosted platform), used for embeddings, logits, and downstream ML features. - **ESMFold2** — structure prediction built on ESMC-6B, hosted via `esmfold2_client`. - **ESM3** — the generative multimodal model over sequence / structure / function tracks. ### Naming and hosting changed — read this before copying old code EvolutionaryScale now operates as **Biohub**. The practical consequences: - The hosted API moved from `forge.evolutionaryscale.ai` to **`https://biohub.ai`**; every client in `esm.sdk` defaults to that URL and reads the token from `ESM_API_KEY`. The classes are still named `*ForgeInferenceClient` for backwards compatibility. - Model weights live under the **`biohub`** Hugging Face organisation (`biohub/ESMC-6B`, `biohub/esm3-sm-open-v1`, `biohub/ESMFold2`). - ESMC and ESMFold2 are also available through Hugging Face Transformers v5.16+, which is a different dependency stack from the `esm` package's optimized inference path. ## When to Use This Skill Use this skill when the user wants protein embeddings or logits, a protein structure from an ESM model, inverse folding, or generative sequence design. ### Does NOT Trigger | Scenario | Use Instead | |----------|-------------| | Fold a protein or complex with AlphaFold2/ColabFold | `alterlab-alphafold` | | Co-fold with a ligand, or predict binding affinity | `alterlab-boltz` | | Antibody–antigen or mixed multi-entity complexes | `alterlab-chai` | | Design a sequence for a fixed backbone (ProteinMPNN family) | `alterlab-proteinmpnn`, `alterlab-ligandmpnn` | | Generate a de-novo backbone to design onto | `alterlab-rfdiffusion` | | Low-dimensional latent embedding / batch integration of single-cell RNA-seq (cells, not proteins) | `alterlab-scvi-tools` | | Deterministic sequence bookkeeping — molecular weight, isoelectric point, parsing a FASTA | `alterlab-biopython` | **Hand-off rule.** When the request matches a row above, open your answer by naming that skill by its exact id (for example `alterlab-alphafold`) and saying in one line why it fits better, then stop applying this skill's procedure. Name it even when you also need to ask for missing input. If only part of the request is out of scope, name the skill for that part and do only the in-scope part. A brief general pointer is fine; the named skill does the work. ## Core Capabilities ### 1. Protein Sequence Generation with ESM3 Generate novel protein sequences with desired properties using multimodal generative modeling. **When to use:** - Designing proteins with specific functional properties - Completing partial protein sequences - Generating variants of existing proteins - Creating proteins with desired structural characteristics **Basic usage:** ```python from esm.models.esm3 import ESM3 from esm.sdk.api import ESM3InferenceClient, ESMProtein, GenerationConfig # Load model locally model: ESM3InferenceClient = ESM3.from_pretrained("esm3-sm-open-v1").to("cuda") # Create protein prompt protein = ESMProtein(sequence="MPRT___KEND") # '_' represents masked positions # Generate completion protein = model.generate(protein, GenerationConfig(track="sequence", num_steps=8)) print(protein.sequence) ``` **For remote/cloud usage via the Biohub Platform:** ```python import esm from esm.sdk.api import ESMProtein, GenerationConfig # url defaults to https://biohub.ai and token to os.environ["ESM_API_KEY"] model = esm.sdk.client("esm3-medium-2024-08") protein = model.generate(protein, GenerationConfig(track="sequence", num_steps=8)) ``` See `references/esm3-api.md` for detailed ESM3 model specifications, advanced generation configurations, and multimodal prompting examples. ### 2. Structure Prediction and Inverse Folding Use ESM3's structure track for structure prediction from sequence or inverse folding (sequence design from structure). **Structure prediction:** ```python from esm.sdk.api import ESM3InferenceClient, ESMProtein, GenerationConfig # Predict structure from a complete sequence protein = ESMProtein(sequence="MPRTKEINDAGLIVHSP") protein_with_structure = model.generate( protein, # num_steps controls how many structure tokens are decoded per step; # use the sequence length (not a "_" count — the sequence is complete here) GenerationConfig(track="structure", num_steps=len(protein.sequence)) ) # Access predicted structure coordinates = protein_with_structure.coordinates # 3D coordinates pdb_string = protein_with_structure.to_pdb() ``` **Inverse folding (sequence from structure):** ```python # Design sequence for a target structure protein_with_structure = ESMProtein.from_pdb("target_structure.pdb") protein_with_structure.sequence = None # Remove sequence # Generate sequence that folds to this structure designed_protein = model.generate( protein_with_structure, GenerationConfig(track="sequence", num_steps=50, temperature=0.7) ) ``` ### 3. Protein Embeddings with ESM C Generate high-quality embeddings for downstream tasks like function prediction, classification, or similarity analysis. **When to use:** - Extracting protein representations for machine learning - Computing sequence similarities - Feature extraction for protein classification - Transfer learning for protein-related tasks **Basic usage:** ```python from esm.models.esmc import ESMC from esm.sdk.api import ESMProtein, LogitsConfig # Load ESMC locally (local from_pretrained names use UNDERSCORES; default is esmc_600m) model = ESMC.from_pretrained("esmc_300m").to("cuda") # Encode, then request embeddings via the logits() API protein = ESMProtein(sequence="MPRTKEINDAGLIVHSP") protein_tensor = model.encode(protein) out = model.logits(protein_tensor, LogitsConfig(sequence=True, return_embeddings=True)) embeddings = out.embeddings # (1, L+2, hidden_dim), incl. BOS/EOS tokens logits = out.logits.sequence # per-position amino-acid logits ``` Do NOT call `model.forward(...)` to get embeddings — `forward` returns a raw model output, not a usable representation tensor. Use `model.logits(..., LogitsConfig(return_embeddings=True)).embeddings`. **Batch processing:** ```python # Encode multiple proteins and pull mean-pooled embeddings proteins = [ ESMProtein(sequence="MPRTKEIND"), ESMProtein(sequence="AGLIVHSPQ"), ESMProtein(sequence="KTEFLNDGR"), ] cfg = LogitsConfig(sequence=True, return_embeddings=True) embeddings_list = [ model.logits(model.encode(p), cfg).embeddings.mean(dim=1) for p in proteins ] ``` See `references/esm-c-api.md` for ESM C model details, efficiency comparisons, and advanced embedding strategies. ### 4. Function Conditioning and Annotation Use ESM3's function track to generate proteins with specific functional annotations or predict function from sequence. **Function-conditioned generation:** ```python from esm.sdk.api import ESMProtein, FunctionAnnotation, GenerationConfig # Create protein with desired function protein = ESMProtein( sequence="_" * 200, # Generate 200 residue protein function_annotations=[ FunctionAnnotation(label="fluorescent_protein", start=50, end=150) ] ) # Generate sequence with specified function functional_protein = model.generate( protein, GenerationConfig(track="sequence", num_steps=200) ) ``` ### 5. Chain-of-Thought Generation Iteratively refine protein designs using ESM3's chain-of-thought generation approach. ```python from esm.sdk.api import GenerationConfig # Multi-step refinement protein = ESMProtein(sequence="MPRT" + "_" * 100 + "KEND") # Step 1: Generate initial structure config = GenerationConfig(track="structure", num_steps=50) protein = model.generate(protein, config) # Step 2: Refine sequence based on structure config = GenerationConfig(track="sequence", num_steps=50, temperature=0.5) protein = model.generate(protein, config) # Step 3: Predict function config = GenerationConfig(track="function", num_steps=20) protein = model.generate(protein, config) ``` ### 6. Batch processing against the hosted platform The client exposes both an async API and a parallel executor that handles retries and a progress bar: ```python import asyncio import esm from esm.sdk import parallel_executor from esm.sdk.api import ESMProtein, GenerationConfig client = esm.sdk.client("esm3-medium-2024-08") # token from ESM_API_KEY proteins = [ESMProtein(sequence=f"MPRT{'_' * 50}KEND") for _ in range(10)] cfg = GenerationConfig(track="sequence", num_steps=8) # Option A: async fan-out async def run(): return await asyncio.gather(*(client.async_generate(p, cfg) for p in proteins)) results = asyncio.run(run()) # Option B: managed executor (retries + progress) with parallel_executor() as executor: results = executor.execute_batch(client.generate, protein=proteins, config=cfg) ``` Also available: `client.batch_generate(...)` / `async_batch_generate(...)`, and `async_fold` / `async_inverse_fold` / `async_logits` for the other tracks. See `references/forge-api.md` for platform documentation, authentication, rate limits, and batch processing patterns. ## Model Selection Guide **ESM3 Models (Generative):** - `esm3-sm-open-v1` (1.4B, aliases `esm3_sm_open_v1` / `esm3-open`) — open weights, local - `esm3-medium-2024-08` (7B) — balance of quality and speed (hosted only) - `esm3-large-2024-03` (98B) — highest quality, slower (hosted only) **ESMC Models (Representations):** - `esmc_300m` — lightweight, fast; open weights, runs locally - `esmc_600m` — balanced; open weights, runs locally, and the `from_pretrained` default - `esmc_6b` / hosted `esmc-6b-2024-12` — maximum representation quality **ESMFold2 (Structure):** `esmfold2-fast-2026-05` (the `esmfold2_client` default), `esmfold2-2026-05`, `esmfold2-2026-05-cutoff-2025`. Naming gotcha: local `from_pretrained(...)` names use **underscores** (`esmc_300m`, `esmc_600m`, `esmc_6b`). Hosted client strings use **hyphens with a date** (`esmc-600m-2024-12`, `esm3-medium-2024-08`, `esmfold2-fast-2026-05`). **Selection criteria:** - **Local development/testing:** `esmc_300m` for embeddings, `esm3-sm-open-v1` for generation - **Production quality:** `esm3-medium-2024-08` or `esmc-6b-2024-12` via the Biohub Platform - **Structure prediction:** `esmfold2_client()` rather than the ESM3 structure track - **High throughput:** hosted clients plus `esm.sdk.parallel_executor` / batch client - **Cost optimization:** smaller models, cache embeddings ## Installation **Basic installation** (pin the minor — the SDK still changes across releases): ```bash uv pip install "esm>=3.4,<3.5" # 3.4.1.post1 as of 2026-09; needs Python >= 3.12 ``` **With Flash Attention (optional, faster GPU inference):** ```bash uv pip install flash-attn --no-build-isolation ``` Local weights for the open models (`esmc_300m`, `esmc_600m`, `esm3-sm-open-v1`) are pulled from the public Hugging Face `biohub` repos and need **no** Hugging Face login — the repos are not gated. `huggingface_hub.login()` is only needed if you point at a gated/private repo or want higher download rate limits. The hosted clients (`esm.sdk.client`, `esmc_client`, `esmfold2_client`) ship inside the `esm` package — no extra install, and only used for the larger hosted-only models. For those, create an API token in the Biohub developer console (`https://biohub.ai/developer-console/api-keys`) and export it as `ESM_API_KEY`. **ESMC through the Biohub Platform:** ```python from esm.sdk import esmc_client from esm.sdk.api import ESMProtein, LogitsConfig model = esmc_client(model="esmc-600m-2024-12") # url/token default as above out = model.logits(model.encode(ESMProtein(sequence="MPRTKEINDAGLIVHSP")), LogitsConfig(sequence=True, return_embeddings=True)) print(out.logits, out.embeddings) ``` ## Common Workflows For detailed examples and complete workflows, see `references/workflows.md` which includes: - Novel GFP design with chain-of-thought - Protein variant generation and screening - Structure-based sequence optimization - Function prediction pipelines - Embedding-based clustering and analysis ## References This skill includes comprehensive reference documentation: - `references/esm3-api.md` - ESM3 model architecture, API reference, generation parameters, and multimodal prompting - `references/esm-c-api.md` - ESM C model details, embedding strategies, and performance optimization - `references/forge-api.md` - Forge platform documentation, authentication, batch processing, and deployment - `references/workflows.md` - Complete examples and common workflow patterns These references contain detailed API specifications, parameter descriptions, and advanced usage patterns. Load them as needed for specific tasks. ## Best Practices **For generation tasks:** - Start with smaller models for prototyping (`esm3-sm-open-v1`) - Use temperature parameter to control diversity (0.0 = deterministic, 1.0 = diverse) - Implement iterative refinement with chain-of-thought for complex designs - Validate generated sequences with structure prediction or wet-lab experiments **For embedding tasks:** - Batch process sequences when possible for efficiency - Cache embeddings for repeated analyses - Normalize embeddings when computing similarities - Use appropriate model size based on downstream task requirements **For production deployment:** - Use the hosted Biohub Platform for scalability and the largest models - Implement error handling and retry logic for API calls - Monitor token usage and implement rate limiting - Consider AWS SageMaker deployment for dedicated infrastructure ## Resources and Documentation - **GitHub Repository:** https://github.com/Biohub/esm (ESM3 docs live in `_assets/ESM3_README.md`) - **Biohub Platform:** https://biohub.ai — API keys at https://biohub.ai/developer-console/api-keys - **ESM Atlas:** https://biohub.ai/esm/protein/atlas - **ESM3 paper:** Hayes et al., *Science* — https://www.science.org/doi/10.1126/science.ads0018 - **Tutorials:** https://github.com/Biohub/esm/tree/main/cookbook/tutorials - **Model Weights:** Hugging Face `biohub` organization ## Responsible Use ESM is designed for beneficial applications in protein engineering, drug discovery, and scientific research. Biohub publishes an Acceptable Use Policy and ran a biosafety/biosecurity risk assessment before release — follow that policy, and the Responsible Biodesign Framework (https://responsiblebiodesign.ai/), when designing novel proteins. Think through biosafety and dual-use implications before experimental validation, because a designed sequence leaves the computational realm the moment it is ordered. Part of the AlterLab Academic Skills suite.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.