alterlab-esm

Files (6)

• SKILL.md
• evals.json · evals/
• esm-c-api.md · references/
• esm3-api.md · references/
• forge-api.md · references/
• workflows.md · references/

SKILL.md (first lines)

# ESM: Evolutionary Scale Modeling

## Overview

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

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

From AlterLab-IEU/AlterLab-Academic-Skills, MIT.

More from AlterLab-IEU/AlterLab-Academic-Skills