bindsight 0.3.5__py3-none-any.whl

bindsight/design/developability.py

@@ -0,0 +1,140 @@
+# SPDX-FileCopyrightText: 2026 Mikhaeel Atef Rizk Wahba
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Binder developability — sequence-level manufacturability / liability flags.
+
+A high-ipTM design is useless if it won't express, aggregates, or is hard to
+manufacture. This module computes sequence-level biophysical descriptors (no
+network, no GPU) so poor-developability designs can be down-ranked before any
+wet-lab or GPU spend.
+
+**Three of them are combined into ``developability_score``**, and only these
+three affect any ranking:
+
+- **Instability index** (Guruprasad 1990) — > 40 predicts an unstable protein.
+- **GRAVY** (Kyte-Doolittle grand average hydropathy) — higher ⇒ more hydrophobic
+  ⇒ harder to express / more aggregation-prone.
+- **Aggregation-prone fraction** — fraction of the chain inside a hydrophobic
+  (Kyte-Doolittle window) aggregation-prone region (APR), a standard first-order
+  aggregation signal.
+
+**The rest are reported and not scored.** They are real liabilities and a reader
+should see them, but nothing down-ranks a design for them, and saying otherwise
+would claim a filter that does not exist:
+
+- **Isoelectric point** and **aromaticity** — formulation / handling liabilities.
+- **Cysteine count** — ``n_cys`` is the *total* number of cysteines in the
+  sequence, not the free ones. An odd count flags a probable unpaired cysteine
+  and so a disulfide / oxidation liability; pairing cannot be determined from
+  sequence alone, and this module does not read a structure.
+- **Length** and **molecular weight** — context for everything above.
+
+Five descriptors come from Biopython's ``ProtParam`` (the reference
+implementation): molecular weight, GRAVY, instability index, isoelectric point
+and aromaticity. The other three — length, cysteine count and aggregation-prone
+fraction — are computed here; the APR window is this module's own
+implementation, not ProtParam's. All are deterministic, offline and exact.
+
+(T-cell–epitope / immunogenicity scoring, which needs a licensed or heavy MHC
+predictor, is intentionally left for a follow-up so this module ships only
+signals it can compute exactly here.)
+"""
+
+from __future__ import annotations
+
+import logging
+import math
+from dataclasses import asdict, dataclass
+from typing import Any
+
+LOG = logging.getLogger(__name__)
+
+_STANDARD_AA = set("ACDEFGHIKLMNPQRSTVWY")
+
+
+@dataclass(frozen=True)
+class Developability:
+    """Deterministic sequence-level developability descriptors for one binder."""
+
+    length: int
+    molecular_weight: float
+    gravy: float
+    instability_index: float
+    isoelectric_point: float
+    aromaticity: float
+    n_cys: int
+    aggregation_prone_fraction: float
+    developability_score: float  # composite in [0, 1], higher = more developable
+
+    @property
+    def is_stable(self) -> bool:
+        """ProtParam instability index < 40 ⇒ predicted stable."""
+        return self.instability_index < 40.0
+
+    def as_dict(self) -> dict[str, Any]:
+        """Return the descriptors as a plain dict (for TSV/JSON export)."""
+        return asdict(self)
+
+
+def _aggregation_prone_fraction(seq: str, window: int = 7, threshold: float = 1.0) -> float:
+    """Fraction of residues inside a hydrophobic (Kyte-Doolittle) APR window.
+
+    Slides a ``window``-residue window; a window whose mean Kyte-Doolittle
+    hydropathy exceeds ``threshold`` is aggregation-prone, and all its residues
+    are marked. Returns marked / length (0.0 for sequences shorter than a window).
+    """
+    from Bio.SeqUtils.ProtParamData import kd  # Kyte-Doolittle scale
+
+    n = len(seq)
+    if n < window:
+        return 0.0
+    prone = [False] * n
+    for i in range(n - window + 1):
+        w = seq[i : i + window]
+        if sum(kd.get(a, 0.0) for a in w) / window > threshold:
+            for j in range(i, i + window):
+                prone[j] = True
+    return sum(prone) / n
+
+
+def _composite(instability: float, gravy: float, aggregation_prone_fraction: float) -> float:
+    """Combine stability, solubility and aggregation into a [0, 1] developability score."""
+    # Stable below the 40 instability threshold, decaying above it.
+    stability = 1.0 if instability < 40.0 else max(0.0, 1.0 - (instability - 40.0) / 40.0)
+    # Solubility: sigmoid of -GRAVY (GRAVY 0 → 0.5, negative/hydrophilic → higher).
+    solubility = 1.0 / (1.0 + math.exp(gravy))
+    non_aggregating = 1.0 - aggregation_prone_fraction
+    return (stability + solubility + non_aggregating) / 3.0
+
+
+def developability(sequence: str) -> Developability | None:
+    """Compute developability descriptors for a binder amino-acid sequence.
+
+    Returns ``None`` for an empty sequence or one containing non-standard
+    residues (ProtParam is only defined on the 20 standard amino acids).
+    """
+    if not sequence:
+        return None
+    seq = sequence.strip().upper()
+    if not seq or any(a not in _STANDARD_AA for a in seq):
+        return None
+    try:
+        from Bio.SeqUtils.ProtParam import ProteinAnalysis
+
+        pa = ProteinAnalysis(seq)
+        instability = float(pa.instability_index())
+        gravy = float(pa.gravy())
+        apr = _aggregation_prone_fraction(seq)
+        return Developability(
+            length=len(seq),
+            molecular_weight=round(float(pa.molecular_weight()), 2),
+            gravy=round(gravy, 4),
+            instability_index=round(instability, 2),
+            isoelectric_point=round(float(pa.isoelectric_point()), 2),
+            aromaticity=round(float(pa.aromaticity()), 4),
+            n_cys=seq.count("C"),
+            aggregation_prone_fraction=round(apr, 4),
+            developability_score=round(_composite(instability, gravy, apr), 4),
+        )
+    except Exception as e:  # malformed sequence ProtParam can't handle
+        LOG.warning("developability failed for a %d-aa sequence: %s", len(seq), e)
+        return None

bindsight/design/embeddings.py

@@ -0,0 +1,165 @@
+# SPDX-FileCopyrightText: 2026 Mikhaeel Atef Rizk Wahba
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Protein-language-model embeddings + a pre-GPU sequence-space visualizer.
+
+Before spending GPU on structure prediction / validation, it's useful to *see*
+the sequence space of your designed binders (or candidate targets): which designs
+cluster, which are outliers, how diverse the set is. This is the ProtSpace idea —
+project protein-language-model (pLM) embeddings to 2-D.
+
+**pLM choice — ESM-2 (`facebook/esm2_t6_8M_UR50D`, 8 M params).** ESM-2 is the
+de-facto open protein LM; the 8 M (t6) checkpoint runs on a CPU in seconds, needs
+no GPU, and its mean-pooled residue embedding is a strong, standard per-protein
+representation. Larger ESM-2 checkpoints (35 M…3 B) or ProtT5 can be dropped in via
+``model_name`` when accuracy matters more than speed.
+
+Embedding (ESM-2) needs the optional ``embed`` extra (torch + transformers):
+``pip install 'bindsight[embed]'``. The 2-D projection (PCA) is pure NumPy and
+always available, so the visualizer works on any precomputed embedding matrix.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+import numpy as np
+
+LOG = logging.getLogger(__name__)
+
+DEFAULT_PLM = "facebook/esm2_t6_8M_UR50D"
+
+_INSTALL_HINT = (
+    "ESM-2 embeddings need the optional 'embed' extra: pip install 'bindsight[embed]' "
+    "(installs torch + transformers)."
+)
+
+
+def esm2_embed(
+    sequences: list[str],
+    *,
+    model_name: str = DEFAULT_PLM,
+    batch_size: int = 8,
+) -> np.ndarray:
+    """Mean-pooled ESM-2 embeddings for ``sequences`` → array of shape (N, D).
+
+    Real protein-LM inference (no placeholder). Pools over residue token states,
+    excluding the special BOS/EOS and padding tokens. Raises ``ImportError`` (with
+    an install hint) if the ``embed`` extra isn't installed.
+    """
+    if not sequences:
+        return np.zeros((0, 0), dtype=np.float32)
+    try:
+        import torch
+        from transformers import AutoModel, AutoTokenizer
+    except ImportError as e:  # optional extra not installed
+        raise ImportError(_INSTALL_HINT) from e
+
+    tok = AutoTokenizer.from_pretrained(model_name)
+    model = AutoModel.from_pretrained(model_name)
+    model.eval()
+
+    vecs: list[np.ndarray] = []
+    with torch.no_grad():
+        for i in range(0, len(sequences), batch_size):
+            batch = sequences[i : i + batch_size]
+            enc = tok(
+                batch,
+                return_tensors="pt",
+                padding=True,
+                return_special_tokens_mask=True,
+            )
+            special = enc.pop("special_tokens_mask")
+            hidden = model(**enc).last_hidden_state  # (B, L, D)
+            # Real residues only: attended to, and not a special token.
+            keep = (enc["attention_mask"] * (1 - special)).cpu().numpy()
+            vecs.append(mean_pool_residues(hidden.cpu().numpy(), keep))
+    return np.vstack(vecs)
+
+
+def mean_pool_residues(hidden: np.ndarray, keep: np.ndarray) -> np.ndarray:
+    """Mean of ``hidden`` over the positions ``keep`` marks, per sequence.
+
+    Split out of :func:`esm2_embed` so it can be tested. It is arithmetic --
+    no model, no tokenizer, no ``torch`` -- and it is the step that decides the
+    numbers: a padding token or a BOS/EOS marker left in the average shifts
+    every embedding, and the prescreen built on those embeddings decides which
+    designs reach validation. Inside ``esm2_embed`` it was reachable only with
+    the ``embed`` extra installed, which no CI job does, so the one test that
+    exercised it skipped on every platform.
+
+    Args:
+        hidden: ``(B, L, D)`` final hidden states.
+        keep: ``(B, L)`` of 1 for a real residue and 0 for padding or a special
+            token.
+
+    Returns:
+        ``(B, D)`` float32. A sequence with no kept position averages over a
+        count of 1 rather than dividing by zero, giving a zero vector.
+    """
+    weights = keep[..., None].astype(hidden.dtype)
+    summed = (hidden * weights).sum(axis=1)
+    counts = weights.sum(axis=1).clip(min=1.0)
+    pooled: np.ndarray = (summed / counts).astype(np.float32)
+    return pooled
+
+
+def pca_2d(embeddings: np.ndarray) -> np.ndarray:
+    """Project an (N, D) embedding matrix to (N, 2) principal coordinates.
+
+    Pure NumPy (centred SVD) so it needs no scikit-learn/UMAP and runs anywhere.
+    Returns zeros for fewer than 2 rows. An embedding with a single feature has
+    only one principal axis; the second coordinate is then zero, and the shape
+    is still (N, 2) because every caller relies on it.
+    """
+    x = np.asarray(embeddings, dtype=float)
+    if x.ndim != 2 or x.shape[0] < 2:
+        return np.zeros((x.shape[0] if x.ndim == 2 else 0, 2), dtype=float)
+    xc = x - x.mean(axis=0, keepdims=True)
+    _u, _s, vt = np.linalg.svd(xc, full_matrices=False)
+    coords = np.asarray(xc @ vt[:2].T, dtype=float)  # principal coordinates
+    if coords.shape[1] < 2:
+        # A one-dimensional embedding has one principal axis, so `vt[:2]` is a
+        # single row and this returned (N, 1) while promising (N, 2) -- which
+        # `render_embedding_png` then unpacks as x and y. The second axis is not
+        # missing, it is zero: there is no variance left to put on it. Say that
+        # rather than hand back a shape the signature rules out.
+        coords = np.concatenate(
+            [coords, np.zeros((coords.shape[0], 2 - coords.shape[1]), dtype=float)], axis=1
+        )
+    return coords
+
+
+def render_embedding_png(
+    coords: np.ndarray,
+    labels: list[str],
+    out_path: str | Path,
+    *,
+    title: str = "Binder sequence space (ESM-2 → PCA)",
+) -> bool:
+    """Render a 2-D scatter of ``coords`` labelled by ``labels`` to a PNG.
+
+    Returns False (no-op) if matplotlib isn't installed. Used to produce the
+    committed ProtSpace-style visualization of the designed binders.
+    """
+    try:
+        import matplotlib
+
+        matplotlib.use("Agg")
+        import matplotlib.pyplot as plt
+    except ImportError:
+        return False
+
+    fig, ax = plt.subplots(figsize=(7, 6), dpi=120)
+    ax.scatter(coords[:, 0], coords[:, 1], s=40, alpha=0.8, c="#1f77b4")
+    for (x, y), lab in zip(coords, labels, strict=False):
+        ax.annotate(
+            str(lab), (x, y), fontsize=7, alpha=0.75, xytext=(3, 3), textcoords="offset points"
+        )
+    ax.set_xlabel("PC1")
+    ax.set_ylabel("PC2")
+    ax.set_title(title)
+    fig.tight_layout()
+    fig.savefig(out_path)
+    plt.close(fig)
+    return True

bindsight/design/prescreen.py

@@ -0,0 +1,169 @@
+# SPDX-FileCopyrightText: 2026 Mikhaeel Atef Rizk Wahba
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""ESM-2 pre-screen: cut the validation set before it reaches the GPU.
+
+Structure-and-affinity validation is the expensive half of a design run —
+Boltz-2 costs roughly 20 GPU-seconds per design against RFdiffusion+ProteinMPNN's
+~45 for producing one. Validating fifty near-identical backbones is mostly
+wasted compute.
+
+This screen embeds each designed sequence with ESM-2 and keeps a
+*representative* subset: designs closest to the embedding centroid, which are
+the ones the model considers most typical of what the designer produced.
+Outliers are dropped first, on the reasoning that a design far from the rest of
+the batch in sequence space is more often a degenerate backbone than a
+breakthrough.
+
+Deliberate properties:
+
+- **Opt-in.** ``top_k=None`` returns everything untouched, so default runs are
+  bit-identical to before this module existed.
+- **Degrading, never fatal.** ``torch``/``transformers`` live in the optional
+  ``embed`` extra. Without them the screen logs and returns everything: a
+  missing optional dependency must not lose a GPU run that already succeeded.
+- **Deterministic.** Ties break on the input order, so the same batch always
+  yields the same selection.
+- **Auditable.** :func:`prescreen_report` describes exactly what was dropped,
+  and that goes into provenance — silently discarding candidates would violate
+  the project's own contract that failures are recorded, not swallowed.
+
+Reuses :func:`bindsight.design.embeddings.esm2_embed`; this module adds only
+the selection, not a second embedding implementation.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+
+LOG = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class PrescreenResult:
+    """Outcome of a pre-screen pass."""
+
+    kept: list[int]
+    dropped: list[int]
+    applied: bool
+    reason: str
+
+    @property
+    def n_kept(self) -> int:
+        """Number of designs carried forward to validation."""
+        return len(self.kept)
+
+    @property
+    def n_dropped(self) -> int:
+        """Number of designs screened out before validation."""
+        return len(self.dropped)
+
+
+def _fallback(n: int, reason: str, *, benign: bool = False) -> PrescreenResult:
+    """Keep everything, recording why the screen did not run.
+
+    ``benign`` separates "nothing needed screening" from "the screen could not
+    run". Both keep every design and both must be recorded in provenance, but
+    only the second is worth a warning: a run with fewer designs than its cap is
+    behaving exactly as configured, and logging that as a problem trains readers
+    to ignore the line that does signal one.
+    """
+    if reason:
+        LOG.log(
+            logging.INFO if benign else logging.WARNING,
+            "ESM-2 pre-screen not applied: %s; validating all %d designs",
+            reason,
+            n,
+        )
+    return PrescreenResult(kept=list(range(n)), dropped=[], applied=False, reason=reason)
+
+
+def select_representative(sequences: list[str], top_k: int | None) -> PrescreenResult:
+    """Choose which designs to carry into validation.
+
+    Args:
+        sequences: Designed binder sequences, in design order.
+        top_k: How many to keep. ``None`` or a value at least as large as the
+            input keeps everything and skips the embedding entirely.
+
+    Returns:
+        A :class:`PrescreenResult` whose ``kept`` indices are in ascending
+        design order, so downstream output ordering is unchanged.
+    """
+    n = len(sequences)
+    if top_k is None:
+        return _fallback(n, "")
+    if top_k <= 0:
+        return _fallback(n, f"top_k={top_k} is not positive")
+    if n <= top_k:
+        # Distinct from `top_k is None`. The screen *was* configured; there were
+        # simply not enough designs to cut. Reporting both as an empty reason
+        # made the provenance line say "no top_k set" about a run that set one,
+        # so an auditor reading it would conclude the screen had never been
+        # asked for.
+        return _fallback(
+            n,
+            f"only {n} design{'s' if n != 1 else ''} to screen, top_k={top_k}",
+            benign=True,
+        )
+    if any(not s for s in sequences):
+        return _fallback(n, "one or more designs have an empty sequence")
+
+    try:
+        import numpy as np
+
+        from bindsight.design.embeddings import esm2_embed
+    except ImportError as e:  # pragma: no cover - exercised via the extra
+        return _fallback(n, f"the 'embed' extra is not installed ({e})")
+
+    try:
+        emb = esm2_embed(sequences)
+    except Exception as e:  # a screen must never lose an already-successful GPU run
+        return _fallback(n, f"embedding failed ({e})")
+
+    matrix = np.asarray(emb, dtype=float)
+    if matrix.ndim != 2 or matrix.shape[0] != n:
+        return _fallback(n, f"unexpected embedding shape {matrix.shape} for {n} designs")
+
+    centroid = matrix.mean(axis=0)
+    distances = np.linalg.norm(matrix - centroid, axis=1)
+    # argsort is stable, so equal distances keep their original design order.
+    order = np.argsort(distances, kind="stable")
+    kept = sorted(int(i) for i in order[:top_k])
+    dropped = sorted(int(i) for i in order[top_k:])
+
+    LOG.info(
+        "ESM-2 pre-screen: keeping %d of %d designs (dropped %d least-representative)",
+        len(kept),
+        n,
+        len(dropped),
+    )
+    return PrescreenResult(
+        kept=kept,
+        dropped=dropped,
+        applied=True,
+        reason=f"kept the {top_k} designs closest to the ESM-2 embedding centroid",
+    )
+
+
+def prescreen_report(result: PrescreenResult, binder_ids: list[str]) -> str:
+    """Render a one-line, provenance-ready summary of the screen.
+
+    Args:
+        result: The screen outcome.
+        binder_ids: Binder identifiers in design order.
+
+    Returns:
+        A human-readable summary naming the dropped designs.
+    """
+    if not result.applied:
+        return (
+            f"ESM-2 pre-screen not applied ({result.reason or 'no top_k set'}); "
+            f"all {len(binder_ids)} designs validated"
+        )
+    dropped = [binder_ids[i] for i in result.dropped if i < len(binder_ids)]
+    shown = ", ".join(dropped[:10]) + (" …" if len(dropped) > 10 else "")
+    return (
+        f"ESM-2 pre-screen: validated {result.n_kept} of {len(binder_ids)} designs; "
+        f"{result.reason}. Screened out: {shown or 'none'}"
+    )

bindsight/design/protocol.py

@@ -0,0 +1,111 @@
+# SPDX-FileCopyrightText: 2026 Mikhaeel Atef Rizk Wahba
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Designer plugin protocol.
+
+A Designer turns a ``DesignSpec`` (target structure + epitope + params) into
+``DesignResult`` (a tarball of binder PDBs + per-design metrics). All real
+work is offloaded to a :class:`bindsight.runners.GPURunner`; the Designer
+itself only owns the spec shape and result schema.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal, Protocol, runtime_checkable
+
+from pydantic import BaseModel, ConfigDict, Field
+
+# A real import, not a TYPE_CHECKING one. ``submit`` annotates this type, and
+# the annotation was previously silenced with ``# type: ignore[name-defined]``
+# plus a ``noqa: F821`` directive -- which quieted two checkers rather than
+# telling either
+# what the name is, so ``typing.get_type_hints`` on this Protocol raised and
+# nothing could introspect the contract. ``bindsight.runners.protocol`` imports
+# nothing from this package, so there is no cycle to avoid.
+from bindsight.runners.protocol import GPURunner
+
+
+class DesignSpec(BaseModel):
+    """Inputs to a single design job (one target × N trajectories)."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    target_uniprot: str
+    target_structure_path: str = Field(..., description="Local path to mmCIF/PDB.")
+    epitope_chain: str = "A"
+    # Hotspot residues to focus the binder on. Empty = whole-target design
+    # (valid before SURFACE-Bind epitope prediction is wired); RFdiffusion then
+    # runs without ``ppi.hotspot_res``.
+    epitope_residues: list[int] = Field(default_factory=list)
+    # Inclusive residue ranges of the target the binder may be designed against —
+    # the extracellular domain(s) annotated by discovery. Empty means no topology
+    # was available, so the whole chain (transmembrane helix and cytoplasmic tail
+    # included) is the design surface; the executor says so rather than implying
+    # the full-length receptor was intended.
+    design_ranges: list[tuple[int, int]] = Field(default_factory=list)
+    binder_length_min: int = 50
+    binder_length_max: int = 100
+    n_trajectories: int = 50
+    seed: int = 0
+    extra_params: dict[str, str | int | float | bool] = Field(default_factory=dict)
+
+
+class DesignResult(BaseModel):
+    """Result of a design job."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    spec: DesignSpec
+    results_archive_path: str = Field(..., description="Local path to the .tar.gz of PDBs.")
+    metrics_jsonl_path: str = Field(
+        ..., description="Local path to per-design metrics JSONL (one row per design)."
+    )
+    designer_name: str
+    designer_version: str = Field(
+        ...,
+        description=(
+            "Version of the bindsight adapter, NOT of the upstream tool it drives. "
+            "The upstream revision is pinned in designer_commit_sha and in the "
+            "spec's extra_params (e.g. rfdiff_commit, proteinmpnn_commit), which "
+            "are what the cache key and reproducibility depend on."
+        ),
+    )
+    designer_commit_sha: str | None = None
+    weights_sha256: str | None = None
+    cache_key: str = Field(..., description="Used to deduplicate identical jobs across runs.")
+    cache_status: Literal["hit", "miss"] = Field(
+        "miss",
+        description=(
+            "Whether this result was reused from a previous run with the same cache_key "
+            "('hit') or newly computed ('miss'). Recorded so a manifest shows which units "
+            "actually consumed GPU time."
+        ),
+    )
+
+
+@runtime_checkable
+class Designer(Protocol):
+    """Protocol every designer plugin must implement."""
+
+    name: str
+    version: str
+
+    def make_spec(
+        self,
+        *,
+        target_uniprot: str,
+        target_structure_path: Path,
+        epitope_residues: list[int],
+        epitope_chain: str = "A",
+        design_ranges: list[tuple[int, int]] | None = None,
+        n_trajectories: int = 50,
+        seed: int = 0,
+        binder_length_min: int = 50,
+        binder_length_max: int = 100,
+    ) -> DesignSpec:
+        """Build a designer-specific DesignSpec from generic inputs."""
+        ...
+
+    def submit(self, spec: DesignSpec, runner: GPURunner) -> DesignResult:
+        """Execute the design job (synchronous from the caller's POV)."""
+        ...

bindsight/design/rfdiff_mpnn.py

@@ -0,0 +1,93 @@
+# SPDX-FileCopyrightText: 2026 Mikhaeel Atef Rizk Wahba
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""RFdiffusion + ProteinMPNN designer plugin.
+
+The default designer. Generates backbones with `RFdiffusion
+<https://github.com/RosettaCommons/RFdiffusion>`_ (BSD-3, weights open) and
+fills in sequences with `ProteinMPNN <https://github.com/dauparas/ProteinMPNN>`_
+(MIT). Both fit in 16 GB VRAM, so this designer works on free Colab T4 — that
+is why it's the default over BindCraft (which needs ≥32 GB).
+
+The actual GPU work runs in :mod:`bindsight.runners.job_exec` (via whichever
+runner backend the user picks). This module owns the plugin entry point and the
+spec it builds; the submit body is shared via :mod:`bindsight.design._common`.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from bindsight.design._common import make_cache_key, submit_via_runner
+from bindsight.design.protocol import DesignResult, DesignSpec
+from bindsight.runners.protocol import GPURunner
+from bindsight.runners.tools import PROTEINMPNN_COMMIT, RFDIFF_COMMIT
+
+LOG = logging.getLogger(__name__)
+
+# Pinned real upstream revisions (resolved via git ls-remote; see runners.tools).
+DEFAULT_RFDIFF_COMMIT = RFDIFF_COMMIT
+DEFAULT_PROTEINMPNN_COMMIT = PROTEINMPNN_COMMIT
+
+
+class RFdiffMPNNDesigner:
+    """Plugin: RFdiffusion backbone + ProteinMPNN sequence."""
+
+    name = "rfdiff_mpnn"
+    # The adapter's own version, not the upstream tool's. Pinned upstream
+    # revisions live in the spec's extra_params and in the cache key; this
+    # number moves only when this adapter's behaviour does.
+    version = "0.1.0"
+    license_notice = "RFdiffusion: BSD-3. ProteinMPNN: MIT. Both commercial-OK."
+
+    def make_spec(
+        self,
+        *,
+        target_uniprot: str,
+        target_structure_path: Path,
+        epitope_residues: list[int],
+        epitope_chain: str = "A",
+        design_ranges: list[tuple[int, int]] | None = None,
+        n_trajectories: int = 50,
+        seed: int = 0,
+        binder_length_min: int = 50,
+        binder_length_max: int = 100,
+    ) -> DesignSpec:
+        """Build a DesignSpec carrying the RFdiff+MPNN parameters."""
+        return DesignSpec(
+            target_uniprot=target_uniprot,
+            target_structure_path=str(target_structure_path),
+            epitope_chain=epitope_chain,
+            epitope_residues=epitope_residues,
+            design_ranges=list(design_ranges or []),
+            n_trajectories=n_trajectories,
+            seed=seed,
+            binder_length_min=binder_length_min,
+            binder_length_max=binder_length_max,
+            extra_params={
+                "designer": self.name,
+                "designer_version": self.version,
+                "rfdiff_commit": DEFAULT_RFDIFF_COMMIT,
+                "proteinmpnn_commit": DEFAULT_PROTEINMPNN_COMMIT,
+                "binder_length_min": binder_length_min,
+                "binder_length_max": binder_length_max,
+            },
+        )
+
+    def submit(self, spec: DesignSpec, runner: GPURunner) -> DesignResult:
+        """Ship the spec+structure to the runner and stage the results."""
+        cache_key = make_cache_key(
+            spec,
+            extra=(
+                str(spec.extra_params.get("rfdiff_commit", "")),
+                str(spec.extra_params.get("proteinmpnn_commit", "")),
+            ),
+        )
+        return submit_via_runner(
+            spec,
+            runner,
+            designer_name=self.name,
+            designer_version=self.version,
+            designer_commit_sha=DEFAULT_RFDIFF_COMMIT,
+            cache_key=cache_key,
+        )

bindsight/epitopes/__init__.py

@@ -0,0 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Mikhaeel Atef Rizk Wahba
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Epitope identification — SURFACE-Bind targetable-site lookup.
+
+An fpocket fallback for proteins SURFACE-Bind does not cover is planned and
+not implemented; this docstring previously named it as though it shipped.
+"""