Claude Skill

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

LLM Mart · 0 points · 1 views 0 listing impressions 0 install-command copies
Download AlterLab-IEU-AlterLab-Academic-Skills-skills_bioinformatics_alterlab-esm-3ab6d03.zip · 30 KB

Install

skills CLI npx skills add https://github.com/AlterLab-IEU/AlterLab-Academic-Skills/tree/main/skills/bioinformatics/alterlab-esm
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install alterlab-ieu-alterlab-academic-skills@llmmart
Git 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.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:

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, 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):

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

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.

No comments yet.

Reviews (0)

No reviews yet.