AGENT SKILL

fair-esm2

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.

License 许可
Apache-2.0
最近更新
2026-11-14
Stars
★ 3
Forks
0

01 前言 Front Matter

name
fair-esm2
license
Apache-2.0
category
biomodels
metadata
{ "third_party": [ { "kind": "weights", "name": "ESM-2", "license": "MIT", "provider": "Meta AI", "terms_url": "https://github.com/facebookresearch/esm/blob/main/LICENSE" } ], "display-name": "ESM-2" }
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.
requirements
[ "gpu" ]

03 SKILL.md 正文

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

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

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

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

Models

Name Layers Dim Params Use
esm2_t6_8M_UR50D 6 320 8 M Fast smoke / tiny embeddings
esm2_t33_650M_UR50D 33 1280 650 M Default embedding model
esm2_t36_3B_UR50D 36 2560 3 B Best embeddings, 24 GB+

Output format

out["representations"][layer] is (B, L+2, D); slice [ :, 1:-1, : ] to drop BOS/EOS. out["contacts"] (when return_contacts=True) is (B, L, L).

Remote compute

Needs ≥16 GB VRAM (650M model) and either pre-cached .pt checkpoints or egress to dl.fbaipublicfiles.com. Read compute_details({provider, mode:'read'}) for an environment with fair-esm and a torch-hub weight cache, then:

c = host.compute.create(provider)
job = c.submit_job(
    intent="ESM-2 650M embeddings for 200 sequences — 1×GPU, ~2 min",
    inputs=[
        {"src": "seqs.fasta", "dst_filename": "seqs.fasta"},
        {"src": "embed_esm2.py", "dst_filename": "embed_esm2.py"},
    ],
    command="python3 embed_esm2.py",
    environment=...,   # env name from compute_details
    outputs=["embeddings.pt"],
    timeout_seconds=1800,
)
print(job.job_id)   # cell ends here — kernel never blocks on compute

Then call the wait_for_notification brain-tool. When the compute_done notification arrives, act on its payload:

save_artifacts(payload["featured_files"])   # paths under hpc/<job_id>/

For the full result dict (output_files, remote_workdir, …), re-enter the kernel: c.attach_job(job_id).result() then c.close(). See the remote-compute-ssh / remote-compute-modal skill for the orchestration details.

Inside embed_esm2.py, set TORCH_HOME to the provider's torch-hub cache mount (path is in compute_details) so esm.pretrained.* resolves locally.

Troubleshooting

Symptom Cause Fix
ModuleNotFoundError: No module named 'esm.models' You want Biohub's esm fork, not fair-esm See esmfold2 skill; this skill uses esm.pretrained.*
Slow first call Downloading weights via torch.hub Set TORCH_HOME to a cached location

Next: feed embeddings to a classifier. For structure prediction, use esmfold2.

04 同仓库更多 Skills

pengqianhan
pengqianhan/AI-Human-Research-OS

workflow-skill-creator

Distills a completed user workflow or interaction into a reusable agent skill. Use when the user asks to turn their workflow, interaction, or multi-step process into a skill, or when they say "make this a skill", "create a skill from what we just did", "package this workflow" or similar. Do not use for creating skills from scratch without an existing workflow (use a generic skill-creator for that).

★ 3
pengqianhan
pengqianhan/AI-Human-Research-OS

uv

Checks whether the uv Python package manager is installed and installs it if missing. Ensures uv is on PATH. Use when another skill requires uv as a prerequisite.

★ 3
pengqianhan
pengqianhan/AI-Human-Research-OS

uniprot-database

Access protein metadata, function, taxonomy, and sequences across UniProtKB, UniParc, and UniRef. Use when searching for proteins, mapping identifiers, or retrieving functional annotations and publications. Don't use for sequence alignment, protein folding, or sequence similarity search (use specialized skills for those tasks).

★ 3
pengqianhan
pengqianhan/AI-Human-Research-OS

unibind-database

Queries the UniBind database for experimentally validated transcription factor (TF) binding sites. Use when retrieving direct TF-DNA interaction datasets, downloading binding site coordinates (BED/FASTA) for local analysis, or listing available datasets by species, cell line, or TF name. Don't use to query specific intervals, locations, genes, motif models or expression data.

★ 3
pengqianhan
pengqianhan/AI-Human-Research-OS

ucsc-conservation-and-tfbs

Fetch Evolutionary Conservation scores (phyloP, phastCons) and Transcription Factor Binding Sites (TFBS) from the UCSC Genome Browser. Use when analyzing whether genomic variants or regions are evolutionarily conserved, functionally important, or bounded by TF regulators across major projects (ENCODE, JASPAR, ReMap).

★ 3
pengqianhan
pengqianhan/AI-Human-Research-OS

string-database

Query the STRING database for protein-protein interactions (PPIs), functional enrichment, and homology. Use when the user asks about interactions between specific proteins, interaction evidence, confidence scores, protein interaction partners, or pathway enrichments.

★ 3