Sequence-based protein–protein interaction scoring using ESM protein language model embeddings.

PPIQuest is a Python package and command-line tool for scoring candidate protein-protein interactions (PPIs) from pairs of amino-acid sequences. It supports ESM2, ESM3, and ESM-C sequence embeddings followed by fitted PCA, scaling, and compact neural classifiers.

Interpretation: PPIQuest produces computational prioritization scores. A high score is not experimental proof of direct physical binding.

• src/ppiquest/: installable Python package and CLI;
• src/ppiquest/model_assets/: bundled PPIQuest PCA/scaler/classifier assets for ESM2, ESM3, and ESM-C;
• examples/: one-pair and five-pair examples;
• tests/: offline tests that do not download the large upstream ESM models;
• validation/reference_outputs/: reference outputs supplied with the original bundle;
• MODEL_CARD.md: intended use, limitations, and missing reproducibility information.

The small PPIQuest downstream model assets are bundled. The much larger upstream ESM base-model weights are not redistributed and are downloaded by their respective libraries when first used.

• Python 3.10 or newer;
• PyTorch appropriate for your CPU/CUDA platform;
• internet access for the first upstream model download;
• substantially more RAM/VRAM for ESM3 and ESM-C than for package unit tests.

git clone https://github.com/enio23/PPIQuest.git
cd PPIQuest

python -m venv .venv
source .venv/bin/activate                 # Linux/macOS
# .venv\Scripts\activate                  # Windows PowerShell

python -m pip install --upgrade pip

Install one of the following configurations:

# ESM2 only
python -m pip install -e ".[esm2]"

# ESM2 + ESM3 + ESM-C
python -m pip install -e ".[all]"

# Development and tests, without downloading ESM backends
python -m pip install -e ".[dev]"

For a CUDA machine, it is often preferable to install the correct PyTorch build first using the instructions for your CUDA version, then install PPIQuest.

python -m pip install "ppiquest[esm2] @ git+https://github.com/enio23/PPIQuest.git"

For all supported backends:

python -m pip install "ppiquest[all] @ git+https://github.com/enio23/PPIQuest.git"

ppiquest --version
ppiquest info
ppiquest models validate

The final command should report available: true for esm2, esm3, and esmc because the PPIQuest downstream assets are included in the package.

ESM2 is downloaded through Hugging Face Transformers. ESM3 and ESM-C are loaded through the EvolutionaryScale esm package. Some upstream models require accepting their model terms and logging in to Hugging Face before the first download:

python -m pip install -U huggingface-hub
hf auth login

Upstream software and base-model weights have licenses separate from PPIQuest; review THIRD_PARTY_NOTICES.md and the relevant upstream model pages.

The following sequences are short demonstration sequences included only to show the interface.

ppiquest pair \
  --pair-id demo_pair_1 \
  --protein-a demo_A \
  --protein-b demo_B \
  --sequence-a "MKTAYIAKQRQISFVKSHFSRQDILDLWIYHTQGYFP" \
  --sequence-b "MSDSEVNQEAKPEVKPEVKPETHINLVEK" \
  --models esm2 \
  --device auto \
  --json-output single_pair_prediction.json

The first run downloads and caches the upstream ESM2 model. Subsequent runs reuse both the upstream model cache and PPIQuest sequence-embedding cache.

Use the bundled model directory:

from ppiquest import PPIPredictor
from ppiquest.assets import default_model_dir

predictor = PPIPredictor.from_local(
    model_dir=default_model_dir(),
    models=("esm2",),
    device="auto",
)

result = predictor.predict_pair(
    sequence_a="MKTAYIAKQRQISFVKSHFSRQDILDLWIYHTQGYFP",
    sequence_b="MSDSEVNQEAKPEVKPEVKPETHINLVEK",
    protein_a="demo_A",
    protein_b="demo_B",
    pair_id="demo_pair_1",
)

print(result["pred_prob_esm2"])
print(result["pred_label_esm2"])

A runnable version is provided at examples/single_pair_python.py.

The input CSV must contain sequence_a and sequence_b. pair_id, protein_a, and protein_b are recommended but optional.

pair_id,protein_a,protein_b,sequence_a,sequence_b
pair_01,A01,B01,MNLGTHIEWQ...,MMVKEWVAYT...
pair_02,A02,B02,MCQIAVVYKY...,MYNRMSYNEH...

A complete five-row example is included at:

examples/data/five_protein_pairs.csv

Run ESM2 batch prediction:

ppiquest predict \
  --input examples/data/five_protein_pairs.csv \
  --output five_pair_predictions_esm2.csv \
  --models esm2 \
  --device auto \
  --embedding-batch-size 1 \
  --prediction-batch-size 4096

Run all three sequence models:

ppiquest predict \
  --input examples/data/five_protein_pairs.csv \
  --output five_pair_predictions_all_models.csv \
  --models esm2 esm3 esmc \
  --device cuda \
  --embedding-batch-size 1 \
  --prediction-batch-size 4096

The default CLI also writes companion tables:

• *_robust_positive.csv: rows positive across all available models;
• *_discordant.csv: rows where model labels disagree;
• *_summary.csv: basic run counts.

Runnable shell and Python examples are available in examples/.

For each selected model, PPIQuest writes:

• pred_prob_<model>: model score after the fitted classifier;
• pred_label_<model>: thresholded label, using the bundle threshold unless overridden;
• orientation_delta_<model>: difference between pair orientations when symmetrization is used;
• embedding_error_<model>: backend error for the row, when present;
• sequence_truncated_<model>: whether configured sequence truncation occurred.

For multi-model runs it also writes mean/weighted ensemble scores, agreement indicators, and counts of available/positive models. See docs/output_columns.md.

PPIQuest resolves model files in this order:

1. --model-dir supplied to the CLI;
2. PPIQUEST_MODEL_DIR environment variable;
3. model assets bundled with the installed package.

Example override:

export PPIQUEST_MODEL_DIR=/path/to/ppiquest-models
ppiquest models validate

By default, embeddings are cached in the platform-specific user cache directory. To select another location:

ppiquest predict \
  --input examples/data/five_protein_pairs.csv \
  --output predictions.csv \
  --models esm2 \
  --cache-dir .embedding_cache

These tests use deterministic fake embeddings and the real bundled downstream assets. They do not download ESM2, ESM3, or ESM-C:

python -m pip install -e ".[dev]"
pytest -q

python -m build
python -m twine check dist/*

python -m pip install -e ".[esm2]"
bash examples/run_single_pair_cli.sh

Run on a suitable CUDA machine after accepting upstream model terms and authenticating:

python -m pip install -e ".[all]"
hf auth login
bash examples/run_five_pairs_all_models.sh

TODO: Use CITATION.cff for the software citation. Also cite the upstream ESM publication(s) corresponding to the embedding model(s) used in your analysis.

The PPIQuest source code is released under the MIT License. Upstream ESM software and model weights are governed by their respective licenses. The public license for the bundled downstream PPIQuest model assets should be explicitly confirmed before the first public release.