# Fair Esm2

Embed proteins with Meta AI's ESM-2 (`fair-esm` package).

- Repository: https://github.com/aipoch/open-science (5414 stars)
- Category: Data and ML
- License: Apache-2.0
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add aipoch/open-science --skill fair-esm2 -g -a claude-code -y`
Codex: `npx skills add aipoch/open-science --skill fair-esm2 -g -a codex -y`
Cursor: `npx skills add aipoch/open-science --skill fair-esm2 -g -a cursor -y`
Gemini CLI: `npx skills add aipoch/open-science --skill fair-esm2 -g -a gemini-cli -y`

## Description

Embed proteins with Meta AI's ESM-2 (`fair-esm` package). Use this skill when: (1) Extracting per-residue or per-sequence embeddings for downstream ML, (2) Masked-LM likelihood / mutation effect scoring, (3) Contact prediction from a sequence.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# fair-esm2, ESM-2 (Meta AI)

ESM-2 code and weights are MIT (Meta AI, github.com/facebookresearch/esm).

> **Package disambiguation.** `pip install fair-esm` gives you `import esm`
> with `esm.pretrained.*` (ESM-1/2). Biohub's github.com/Biohub/esm fork
> (MIT) gives you `from esm.models.esmfold2 import ESMFold2InputBuilder`, > see the **`esmfold2`** skill. Both share the `esm` namespace but are
> different libraries. This skill covers **fair-esm** (the Meta package).

## Prerequisites

| Requirement | Minimum                 | Recommended        |
| ----------- | ----------------------- | ------------------ |
| Python      | 3.8+                    | 3.11               |
| CUDA        | 11.7+                   | 12.x               |
| GPU VRAM    | 8 GB (8M), 16 GB (650M) | 24 GB+ (650M / 3B) |

## How to run

### Embeddings

```python
import torch, esm

model, alphabet = esm.pretrained.esm2_t33_650M_UR50D()
model = model.eval().cuda()
bc = alphabet.get_batch_converter()

_, _, toks = bc([("ubq", "MQIFVKTLTGKTITLEVEPSDTIENVK")])
with torch.no_grad():
    out = model(toks.cuda(), repr_layers=[33])
emb = out["representations"][33]      # (1, L+2, 1280), includes BOS/EOS
seq_emb = emb[0, 1:-1].mean(0)        # per-sequence mean
```

### Masked-LM scoring

```python
with torch.no_grad():
    out = model(toks.cuda(), repr_layers=[33])
logits = out["logits"][0, 1:-1]       # (L, |vocab|)
# WT marginal log-likelihood; for mutation scoring, mask the position and
# compare logit[mut] − logit[wt].
```

### Contact prediction

```python
with torch.no_grad():
    out = model(toks.cuda(), repr_layers=[33], return_contacts=True)
contacts = out["contacts"][0]         # (L, L)
```

## Models

The rest: https://github.com/aipoch/open-science/blob/HEAD/resources/skills/fair-esm2/SKILL.md