DOCSEARCHbyAlgolia
Submit Docs

EvolutionaryScale open model repository (esm)

repository·main·Indexed 25 days ago

https://github.com/biohub/esm

A world model for protein biology providing tools for prediction, design, and discovery. It includes ESMC (a protein language model for sequence embedding and mutation analysis), ESMFold2 (a structure prediction model for proteins, DNA, RNA, and small molecules), and ESM3 (a generative model for protein sequence, structure, and function). The repository provides tools for interpreting protein features via Sparse Autoencoders (SAEs) and supports local execution via Hugging Face or remote execution via the Biohub Platform API.

Tokens
20.6K
Snippets
61
Records
76
Agent score
84%

What's inside esm

  1. Set up a clean development environment for esm

    main

    To test the package in a clean environment, use micromamba to create a Python 3.10 environment, install the package in editable mode from the repository root, and install the example requirements. You must also authenticate with Hugging Face.

    Note: When testing the local version, ensure you comment out any pip install esm commands in your scripts so you are testing the local release candidate rather than the published package.

    micromamba create -n esm
micromamba activate esm
micromamba install -c conda-forge python=3.10

# in root level of repo
pip install -e .
pip install examples/requirements.txt
python -c 'from huggingface_hub import login; login()'

  3. Run ESMFold2 via the Biohub Platform API

    main

    Use the SequenceStructureForgeInferenceClient to run ESMFold2 inference through the Biohub platform. This approach uses a remote API instead of local compute.

    Requirements:

    • Install the esm package.
    • An API token from biohub.ai.
    from esm.sdk.forge import SequenceStructureForgeInferenceClient
from esm.sdk.api import FoldingConfig
from esm.utils.structure.input_builder import ProteinInput, StructurePredictionInput

client = SequenceStructureForgeInferenceClient(model="esmfold2-fast-2026-05", url="https://biohub.ai", token="<your API token>")

# Human carbonic anhydrase II (PDB 2CBA)
ca2_sequence = (
    "MSHHWGYGKHNGPEHWHKDFPIAKGERQSPVDIDTHTAKYDPSLKPLSVSYDQATSLRILNNGHAFNVEFDD"
    "SQDKAVLKGGPLDGTYRLIQFHFHWGSLDGQGSEHTVDKKKYAAELHLVHWNTKYGDFGKAVQQPDGLAVL"
    "GIFLKVGSAKPGLQKVVDVLDSIKTKGKSADFTNFDPRGLLPESLDYWTYPGSLTTPPLLECVTWIVLKEP"
    "ISVSSEQVLKFRKLNFNGEGEPEELMVDNWRPAQPLKNRQIKASFK"
)
ca2_input = StructurePredictionInput(
    sequences=[ProteinInput(id="A", sequence=ca2_sequence)]
)

config = FoldingConfig(
    num_loops=20,
    num_sampling_steps=100
)
result = client.fold_all_atom(ca2_input, config=config)

with open("result.cif", "w") as f:
    f.write(result.complex.to_mmcif())

  5. Predict 3D structures with ESMFold2

    main

    ESMFold2 predicts 3D protein structures from sequences, including DNA, RNA, and small molecules. Available workflows include:

    • Folding: Fold proteins in combination with DNA, RNA, and small-molecule ligands (esmfold2.ipynb).
    • Binder design: Design antibodies and minibinders with high hit rates using protocols for nanomolar affinity and target specificity (binder_design.ipynb).

  6. Run ESM3 locally

    main

    To run ESM3 on your own machine, you must authenticate with Hugging Face and download the model weights. The esm3-sm-open-v1 model is available for local use.

    1. Install the library via pip.
    2. Use huggingface_hub.login() to authenticate (requires a Hugging Face token with "Read" permission).
    3. Instantiate the model using ESM3.from_pretrained("esm3-sm-open-v1") and move it to your device ("cuda" or "cpu").
    from huggingface_hub import login
from esm.models.esm3 import ESM3
from esm.sdk.api import ESM3InferenceClient, ESMProtein, GenerationConfig

# Authenticate with Hugging Face
login()

# Download weights and instantiate locally
model: ESM3InferenceClient = ESM3.from_pretrained("esm3-sm-open-v1").to("cuda")

  7. Explore ESMC protein language model capabilities

    main

    ESMC is a protein language model used for embedding sequences into numerical representations for analysis, classification, and interpretation. You can use the following tutorial notebooks to learn specific workflows:

    • Embedding sequences: Explore how different transformer layers encode structural and functional information (embed.ipynb).
    • Mutation analysis: Compute per-position entropy and log-likelihood ratios to identify constrained vs. mutation-tolerant sites (esmc_mutation_scoring.ipynb).
    • Layer sweep: Find the optimal layer for tasks like enzyme function classification (esmc_layer_sweep.ipynb).
    • Fine-tuning: Use Parameter Efficient Fine-tuning (PEFT) to add classification or regression heads to your dataset (esmc_finetune.ipynb).

  8. Run ESM3 through the Biohub Platform

    main

    You can access ESM3 models via the Biohub platform using an API token. This allows you to use larger models without local hardware constraints.

    1. Install the library via pip.
    2. Use esm.sdk.client to instantiate the model with your Biohub API token.
    from esm.sdk.forge import ESM3ForgeInferenceClient
from esm.sdk import client
from esm.sdk.api import ESMProtein, ESMProteinError, LogitsConfig, LogitsOutput

model: ESM3InferenceClient = esm.sdk.client("esm3-medium-2024-08", token="<your API token>")

  9. Install the esm package

    main

    To use ESMFold2, install the esm package directly from the GitHub repository. A PyPI release is not yet available.

    pip install esm@git+https://github.com/Biohub/esm.git@main

  10. Verify cookbook scripts and tutorials

    main

    Ensure the following scripts and tutorials run without errors to validate the package. Some require treon for notebook execution.

    Non-GPU specific scripts:

    ESM_API_KEY=$ESM_API_KEY PYTHONPATH='.' python cookbook/snippets/esm3.py
pip install treon
treon cookbook/tutorials/1_esmprotein.ipynb
treon cookbook/tutorials/2_embed.ipynb
treon cookbook/tutorials/3_gfp_design.ipynb
treon cookbook/tutorials/4_forge_generate.ipynb

    GPU required scripts:

    python cookbook/snippets/esm3.py
python cookbook/snippets/esmc.py
python cookbook/local/raw_forwards.py

  11. Run ESM3 snippets and verify Forge interaction

    main

    To verify that the package correctly interacts with Forge, run the ESM3 snippets. This requires an API key from forge.evolutionaryscale.ai provided via the ESM_API_KEY environment variable.

    ESM_API_KEY=$ESM_API_KEY PYTHONPATH='.' python cookbook/snippets/esm3.py

  12. Design and generate proteins with ESM3

    main

    ESM3 is a generative model that reasons jointly over protein sequence, structure, and function. Use it for designing or editing proteins through these workflows:

    • ESMProtein class: Learn how ESM3 represents proteins (esmprotein.ipynb).
    • Protein generation: Scaffold functional motifs, edit secondary structure, and guide design using solvent exposure (esm3_generate.ipynb).
    • Novel protein design: Follow prompting strategies to design novel proteins, such as a fluorescent protein (GFP) with no close natural relatives (gfp_design.ipynb).
    • Guided generation: Incorporate scoring functions (e.g., structural quality, sequence constraints) into the generation process (esm3_guided_generation.ipynb).