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, including ESM3; SDK class names still contain Forge. This skill targets the released esm 3.4.1.post1, verified against its wheel and current official documentation.

fair-esm is Meta's separate, older ESM2/ESMFold/ESM-IF distribution. Both packages import as esm; install them in separate environments. The legacy esm.pretrained.esm2_* interface is not the Biohub ESMC interface. Hugging Face Transformers' native ESMC implementation is another API: do not interchange its version requirements or output types with this SDK.

Setup and model choice

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. Python 3.12, Torch 2.11.0 and Transformers 4.57.6 were tested on

CPU. Linux x86_64 installs include GPU-specific dependencies; use a supported inference machine and budget disk space. Flash Attention is optional; it is unnecessary for the tiny CPU tests. Do not install this stack into a shared environment containing incompatible Transformers or Torch pins.

ESMC 6B weights are now available locally. Current Biohub model cards identify MIT licensing, with ESMC cards also linking third-party notices; review the exact selected artifact's card and access requirements. The older ESMC class remains as a deprecated compatibility wrapper. Local model sizes, hosted availability and account quotas are different constraints; a larger model does not guarantee better performance on a particular assay.

Workflow

1. Specify the sequence/chain/residue mapping and whether the objective is generation, representation extraction or folding. Preserve input IDs and source provenance. Reject accidental ..., spaces, FASTA headers or gaps in plain single-chain sequences rather than silently deleting them.
2. Choose a local checkpoint or explicit hosted model ID. Record SDK, checkpoint revision, model settings, mask locations and random seed where supported.
3. Check every SDK result for ESMProteinError. Hosted failures may be returned as values. Use finite request timeouts, context managers and bounded concurrency. See hosted contracts.
4. Validate the output contract: sequence length and fixed residues, residue-only embedding axes, or chain/atom mapping and confidence. Keep model predictions separate from experimental validation.
5. Save sequences/structures with settings and identifiers. Avoid caches keyed only by sequence when model, structure, function or generation settings differ.

ESM3 completion and fresh structure prediction

Illustrative pretrained inference; no weights or hosted jobs were run in this refresh. This toy sequence demonstrates API mechanics, not a functional design.

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
assert completed.sequence is not None and len(completed.sequence) == len(prompt)
assert "_" not in completed.sequence
assert all(a == "_" or a == b for a, b in zip(prompt, completed.sequence))

# A fresh sequence-only prompt prevents old coordinates conditioning the check.
folded = model.generate(
    ESMProtein(sequence=completed.sequence),
    GenerationConfig(track="structure", num_steps=8),
)
if isinstance(folded, ESMProteinError):
    raise folded
assert folded.coordinates is not None
folded.to_pdb("candidate.pdb")

Generation fills masked positions. Calling it again on a completed track does not implement refinement or temperature annealing; explicitly remask selected positions or clear the track. ESM3 structure generation and ESMFold2 prediction use different models and result types. See ESM3 for inverse folding, function vocabulary and coordinate conventions.

ESMC embeddings with correct residue pooling

Illustrative pretrained loading; the same API and pooling were executed with a tiny randomly initialized model on CPU. Add this skill's scripts/ directory to PYTHONPATH when importing the bundled helper.

from esm.models.esmc import EsmcForMaskedLM, EsmcTokenizer
from esm_embeddings import embed_sequences

model = EsmcForMaskedLM.from_pretrained("biohub/ESMC-300M", device="cpu").eval()
tokenizer = EsmcTokenizer()
sequences = ["MPRTKEINDAGLIVHSPQWFYK", "ACDEFGHIK"]
features = embed_sequences(model, tokenizer, sequences)
assert features.shape == (2, 960)

output.last_hidden_state has shape (B,T,D) and includes CLS, EOS and padding; T is not the raw residue count. scripts/esm_embeddings.py performs one real padded batch, excludes special/padding tokens, validates the residue count, and returns (B,D) CPU features in input order. Choose batch size by sequence lengths and available memory. It does not truncate, download weights or contact a service. See ESMC for hosted output types, per-residue extraction, gradient behavior and migration details.

Hosted authentication and folding

Read only the intended credential from the environment; pass it explicitly so it is resolved when the client is created. SDK factory defaults capture ESM_API_KEY at import time. Create keys in the Biohub developer console.

Illustrative authenticated inference:

import os
from esm.sdk import esmfold2_client
from esm.sdk.api import ESMProteinError, FoldingConfig
from esm.utils.structure.input_builder import ProteinInput, StructurePredictionInput

fold_input = StructurePredictionInput(
    sequences=[ProteinInput(id="A", sequence="MPRTKEINDAGLIVHSPQWFYK")]
)
with esmfold2_client(
    model="esmfold2-fast-2026-05", url="https://biohub.ai",
    token=os.environ["ESM_API_KEY"], request_timeout=300,
) as client:
    result = client.fold_all_atom(fold_input, config=FoldingConfig())
if isinstance(result, ESMProteinError):
    raise result
with open("candidate.cif", "w") as handle:
    handle.write(result.complex.to_mmcif())

Use the Biohub/ESMFold2 reference for MSA, confidence and complex-input conventions. The fast hosted model ignores MSAs. Public source and mocked requests validate the client contract; they do not establish account access, service availability or prediction quality.

Scientific checks

• Function annotations use supported tokenizer labels and 1-based inclusive ranges; arbitrary labels such as enzymatic_activity are not valid prompts.
• ESM3 coordinates are tensors in atom37 layout; missing atoms use NaN. Tensor copies use .clone(). Specify a PDB chain instead of assuming the default selects one chain; the current default is chain_id="all".
• Predicted coordinates, pLDDT and pTM do not measure thermodynamic stability, binding affinity or catalytic activity. Inverse-folded sequences need fresh prediction, matched-residue structural comparison and experimental screening.
• Embedding similarity is not a homology/function guarantee. Evaluate supervised models with homology-aware splits; fit normalization and dimensionality reduction on training data. Report uncertainty and independent holdout metrics.
• See worked workflows for variant libraries, structure-conditioned design, and clustering without unsupported stability scores or fixed PCA/t-SNE settings that fail on tiny datasets.

Verification and sources

references/review.md records official sources, executed CPU tests and limitations. Run python tests/run_all.py --isolated esm from the repository to exercise synthetic local models, pooling, input serialization, PDB round trips and mocked hosted contracts. Pretrained ESM3/ESMC/ESMFold2, CUDA inference and authenticated services were not executed.

Follow the selected model's terms and the Biohub acceptable-use policy.