domains / science / protein-language-modeling / esm

esm

Skill card

combined

The three skills cover the same domain (ESM protein models) but diverge significantly on the current state of the SDK and API. The K-Dense-AI skill is the most up-to-date, explicitly targeting `esm 3.4.1.post1` and the migration from 'Forge' to 'Biohub', while the other two rely on the older 'Forge' API and deprecated class names (e.g., `ESMC` vs `EsmcForMaskedLM`). The K-Dense skill also provides critical safety constraints (isolated environments, error handling for `ESMProteinError`) that the others lack. Conversely, the other skills provide specific implementation patterns for 'Chain-of-Thought' generation and inverse folding that are not detailed in the K-Dense skill. Because the K-Dense skill is the 'authentic' current procedure but the others contain unique workflow steps (CoT, specific inverse folding examples) that are not contradictory but additive, and because the K-Dense skill's strict version pinning conflicts with the others' generic installation advice, a combined instruction is necessary to provide a complete, safe, and up-to-date guide.

Repositories

Other copies

Combined skill

---
name: esm
description: Uses the Biohub esm Python SDK for ESM3 protein generation, ESMC embeddings, and ESMFold2 all-atom folding. Applies to local model inference and Biohub hosted clients.
license: MIT
compatibility: Requires Python 3.12+ and esm 3.4.1.post1. Use an isolated environment.
metadata:
  version: "2.0"
  skill-author: Combined
  last-reviewed: "2026-09-30"
  upstream-version: "3.4.1.post1"
---

# ESM: Protein Generation, Embeddings, and Folding

## When to use
Use for Biohub's `esm` SDK: ESM3 masked multimodal generation, ESMC sequence representations, and ESMFold2 all-atom prediction. The former Forge platform migrated to `https://biohub.ai`. This skill targets **esm 3.4.1.post1**.

`fair-esm` is Meta's separate, older distribution. Both packages import as `esm`; install them in separate environments.

## Setup

```bash
uv venv --python 3.12 .venv-esm
uv pip install --python .venv-esm/bin/python "esm==3.4.1.post1"
```

The release declares Python >=3.12, Torch >=2.11,<2.12 and Transformers >=4.57.6,<5.

## Workflow

1. **Specify Input**: Define sequence/chain/residue mapping. Reject accidental gaps or headers in plain sequences.
2. **Choose Model**: Select local checkpoint (e.g., `esm3-sm-open-v1`) or hosted ID (e.g., `esm3-medium-2024-08`).
3. **Execute & Validate**: Check for `ESMProteinError`. Use finite timeouts. Validate output contract (length, fixed residues, confidence).
4. **Save**: Save with settings and identifiers. Avoid caches keyed only by sequence.

## ESM3 Generation

### Sequence Completion
```python
import torch
from esm.models.esm3 import ESM3
from esm.sdk.api import ESMProtein, ESMProteinError, GenerationConfig

model = ESM3.from_pretrained("esm3-sm-open-v1", device=torch.device("cpu"))
prompt = "MPRT___KEND"
completed = model.generate(
    ESMProtein(sequence=prompt),
    GenerationConfig(track="sequence", num_steps=3, temperature=0.7),
)
if isinstance(completed, ESMProteinError):
    raise completed
```

### Structure Prediction & Inverse Folding
*   **Structure**: Generate on `track="structure"` to get coordinates/PDB.
*   **Inverse Folding**: Load PDB, set `sequence=None`, generate on `track="sequence"`.

### Chain-of-Thought Generation
Iteratively refine designs by alternating tracks:
1. Generate structure from partial sequence.
2. Refine sequence based on structure.
3. Predict function.

## ESMC Embeddings

Use `EsmcForMaskedLM` and `EsmcTokenizer` for correct residue pooling. The legacy `ESMC` class is deprecated.

```python
from esm.models.esmc import EsmcForMaskedLM, EsmcTokenizer

model = EsmcForMaskedLM.from_pretrained("biohub/ESMC-300M")
tokenizer = EsmcTokenizer.from_pretrained("biohub/ESMC-300M")
# Use tokenizer to process sequence, then model for embeddings
```

## Hosted Inference (Biohub)

Use `ESM_API_KEY` for hosted clients. The legacy `FORGE_TOKEN` and `forge.evolutionaryscale.ai` endpoints are deprecated in favor of Biohub.

```python
# Example for hosted ESM3
from esm.sdk.api import ESM3InferenceClient # Check current SDK for Biohub client class
# client = ESM3InferenceClient(model="esm3-medium-2024-08", api_key=os.environ["ESM_API_KEY"])
```