bindsight 0.3.5__py3-none-any.whl

bindsight/validate/boltz2.py

@@ -0,0 +1,256 @@
+# SPDX-FileCopyrightText: 2026 Mikhaeel Atef Rizk Wahba
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Boltz-2 validator.
+
+Wraps `Boltz-2 <https://github.com/jwohlwend/boltz>`_ (MIT for both code and
+weights). Boltz-2 takes a target+binder spec and produces:
+
+- ``ipTM``, ``pAE_interaction`` from the structure prediction
+- ``affinity_pred_value`` (continuous, log(IC50)-like: **lower = stronger**
+  predicted binder; the ranker inverts it). Ligand-only, so it stays ``None``
+  for the protein binders bindsight designs.
+- ``affinity_probability_binary`` (probability the design is a binder vs decoy)
+
+This module's responsibility is the *parsing + composition* layer:
+
+- :func:`build_boltz_yaml` produces the YAML config Boltz-2 ingests.
+- :func:`parse_boltz_output` reads Boltz's output JSON into a
+  :class:`bindsight.validate.protocol.ValidationResult`.
+- :class:`Boltz2Validator` is the plugin entry point used by the orchestrator.
+
+The actual GPU inference happens in the runner (Colab / Modal / local Docker)
+because Boltz-2 needs CUDA. Calling :meth:`Boltz2Validator.validate` from the
+orchestrator either:
+
+1. Reads pre-computed Boltz output from the run's ``validate/`` directory
+   (when the runner has already returned results), OR
+2. Raises :class:`MissingValidationError` with a clear message pointing the
+   user at the runner step.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import statistics
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from bindsight.validate.protocol import (
+    UNRECORDED_VERSION,
+    ValidationResult,
+    installed_version,
+    note_unmeasured,
+)
+
+LOG = logging.getLogger(__name__)
+
+#: The Boltz-2 release this project pins, audited and installed.
+#:
+#: Single source of truth: ``bindsight.runners.tools.BOLTZ_PIP`` is built from
+#: it. The dependency runs that way round because ``tools`` already imports this
+#: module.
+PINNED_BOLTZ2_VERSION = "2.0.3"
+
+
+def installed_boltz_version() -> str | None:
+    """The Boltz-2 actually importable here, or ``None`` where there is none.
+
+    ``validator_version`` used to be :data:`PINNED_BOLTZ2_VERSION` written
+    straight into every metrics row, which made it a label rather than a record:
+    the pin was a range, so any 2.x could have produced a number, and the row
+    said ``2.0.1`` regardless. A provenance field that reports a constant is
+    worse than an absent one, because it answers the question wrongly instead of
+    leaving it open.
+
+    Returns ``None`` rather than the pin when Boltz is not installed — which is
+    the case wherever the parser runs outside the GPU environment. Substituting
+    the pinned version there would recreate the same fiction one level down.
+    """
+    return installed_version("boltz")
+
+
+class MissingValidationError(FileNotFoundError):
+    """Raised when validation output for a binder hasn't been produced yet."""
+
+
+def build_boltz_yaml(
+    *,
+    target_id: str,
+    target_sequence: str,
+    binder_id: str,
+    binder_sequence: str,
+    predict_affinity: bool = True,
+) -> dict[str, Any]:
+    """Build the YAML config Boltz-2 expects on stdin.
+
+    See https://github.com/jwohlwend/boltz/blob/main/docs/prediction.md for
+    the full schema. We stay on the documented happy path (two protein chains
+    + one affinity property) so the spec is portable across Boltz-2 minor
+    versions.
+    """
+    # Boltz-2 chain IDs must be short identifiers (single letters), not our
+    # binder_id tracking string ("binder_0_seq0" makes Boltz-2 skip the input).
+    # Use target_id for the target chain and a distinct single letter for the
+    # binder; binder_id is kept only for our own bookkeeping/filenames.
+    binder_chain = "B" if target_id != "B" else "C"
+    spec: dict[str, Any] = {
+        "version": 1,
+        "sequences": [
+            {"protein": {"id": target_id, "sequence": target_sequence}},
+            {"protein": {"id": binder_chain, "sequence": binder_sequence}},
+        ],
+    }
+    if predict_affinity:
+        spec["properties"] = [{"affinity": {"binder": binder_chain}}]
+    return spec
+
+
+def write_boltz_yaml(spec: dict[str, Any], path: Path) -> Path:
+    """Write a Boltz-2 spec dict to disk as YAML."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(yaml.safe_dump(spec, sort_keys=False), encoding="utf-8", newline="\n")
+    return path
+
+
+def parse_boltz_output(
+    *,
+    output_dir: Path,
+    binder_id: str,
+    target_uniprot: str,
+) -> ValidationResult:
+    """Parse Boltz-2's per-design output directory into a ValidationResult.
+
+    Boltz-2 writes one ``predictions/<run>/`` directory per spec, containing:
+
+    - ``confidence_<run>_model_0.json``  — per-residue + interface confidence
+      (we extract ``iptm`` and ``ptm``).
+    - ``affinity_<run>.json`` (when affinity prediction enabled) —
+      ``affinity_pred_value`` and ``affinity_probability_binary``.
+
+    Both files are read; missing fields become ``None`` (not an error — the
+    user may have disabled affinity prediction).
+    """
+    # Boltz writes to <out_dir>/predictions/<name>/confidence_*.json, so search
+    # recursively (rglob) rather than only the top level.
+    #
+    # *Every* one of them, not the first. With --diffusion_samples > 1 Boltz
+    # writes one per draw and ranks them by confidence descending, so
+    # ``model_0`` is the best draw rather than a representative one. Reading
+    # whichever file turned up first therefore reported a maximum over k — an
+    # estimate that improves as more samples are bought, with no change to the
+    # design. Averaging is the estimate of the distribution's centre; the best
+    # draw is not an estimate of anything.
+    confidence_paths = sorted(output_dir.rglob("confidence_*.json"))
+    affinity_path = next(output_dir.rglob("affinity_*.json"), None)
+
+    iptm = pae_interaction = affinity_value = affinity_prob = None
+    iptm_samples: list[float] = []
+    pae_samples: list[float] = []
+
+    n_parsed = 0
+    for path in confidence_paths:
+        try:
+            cdata = json.loads(path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError) as e:
+            LOG.warning("failed to parse %s: %s", path, e)
+            continue
+        n_parsed += 1
+        value = _safe_float(cdata.get("iptm"))
+        if value is not None:
+            iptm_samples.append(value)
+        pae = _safe_float(cdata.get("pae_interaction") or cdata.get("interface_pae"))
+        if pae is not None:
+            pae_samples.append(pae)
+
+    if iptm_samples:
+        iptm = statistics.fmean(iptm_samples)
+    if pae_samples:
+        pae_interaction = statistics.fmean(pae_samples)
+
+    if affinity_path is not None:
+        try:
+            adata = json.loads(affinity_path.read_text(encoding="utf-8"))
+            affinity_value = _safe_float(adata.get("affinity_pred_value"))
+            affinity_prob = _safe_float(adata.get("affinity_probability_binary"))
+        except (json.JSONDecodeError, OSError) as e:
+            LOG.warning("failed to parse %s: %s", affinity_path, e)
+
+    result = ValidationResult(
+        binder_id=binder_id,
+        target_uniprot=target_uniprot,
+        iptm=iptm,
+        iptm_n_samples=len(iptm_samples) or None,
+        iptm_sd=statistics.stdev(iptm_samples) if len(iptm_samples) > 1 else None,
+        pae_interaction=pae_interaction,
+        affinity_pred_value=affinity_value,
+        affinity_probability_binary=affinity_prob,
+        validator_name="boltz2",
+        validator_version=installed_boltz_version() or UNRECORDED_VERSION,
+        notes=(
+            # Files parsed, of files found. This counted the files present, so a
+            # directory of unreadable JSON reported the same sample count as a
+            # directory of good ones and the row carried no trace of it.
+            f"parsed confidence={n_parsed} of {len(confidence_paths)} file(s), "
+            f"affinity={'yes' if affinity_path else 'no'}"
+        ),
+    )
+    return note_unmeasured(
+        result,
+        reason=(
+            f"none of the {len(confidence_paths)} confidence file(s) under "
+            f"{output_dir} yielded an iptm or pae_interaction value"
+        ),
+        log=LOG,
+    )
+
+
+def _safe_float(v: object) -> float | None:
+    if v is None:
+        return None
+    try:
+        return float(v)  # type: ignore[arg-type]
+    except (TypeError, ValueError):
+        return None
+
+
+class Boltz2Validator:
+    """Plugin: Boltz-2 structure + affinity prediction.
+
+    The validator class itself is a thin parser; the GPU inference happens
+    in whichever runner the user picks (Colab / Modal / local Docker). The
+    orchestrator (``bindsight validate``) is responsible for shipping the
+    spec to the runner and pulling back the JSON outputs into
+    ``<run>/validate/<binder_id>/``.
+    """
+
+    name = "boltz2"
+    version = PINNED_BOLTZ2_VERSION
+    license_notice = "Boltz-2: MIT (code + weights). Commercial-OK."
+
+    def validate(
+        self,
+        target_uniprot: str,
+        binder_id: str,
+        binder_sequence: str,
+        target_structure_path: str,
+    ) -> ValidationResult:
+        """Look up Boltz-2 output for this binder + parse it.
+
+        Looks in ``<cwd>/validate/<binder_id>/`` for the JSONs Boltz-2 wrote.
+        Raises :class:`MissingValidationError` if not found — the orchestrator
+        catches this and prints a hint about running the GPU step first.
+        """
+        cwd = Path("validate") / binder_id
+        if not cwd.exists():
+            raise MissingValidationError(
+                f"no Boltz-2 output found at {cwd}; "
+                "run the GPU validation step first (see docs/colab-design-howto.md)"
+            )
+        return parse_boltz_output(
+            output_dir=cwd,
+            binder_id=binder_id,
+            target_uniprot=target_uniprot,
+        )

bindsight/validate/chai1r.py

@@ -0,0 +1,42 @@
+# SPDX-FileCopyrightText: 2026 Mikhaeel Atef Rizk Wahba
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Chai-1 validator plugin.
+
+`Chai-1 <https://github.com/chaidiscovery/chai-lab>`_ (Apache-2) is an
+alternative to Boltz-2 for cross-model agreement. The GPU inference runs in
+:mod:`bindsight.runners.job_exec`; this plugin's :meth:`validate` parses the
+Chai output the runner produced into a :class:`ValidationResult`.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from bindsight.validate.boltz2 import MissingValidationError
+from bindsight.validate.protocol import ValidationResult
+
+
+class Chai1rValidator:
+    """Plugin: Chai-1 structure + confidence prediction (parser side)."""
+
+    name = "chai1r"
+    version = "0.6"
+    license_notice = "Chai-1: Apache-2.0. Commercial-OK."
+
+    def validate(
+        self,
+        target_uniprot: str,
+        binder_id: str,
+        binder_sequence: str,
+        target_structure_path: str,
+    ) -> ValidationResult:
+        """Parse Chai-1 output for this binder from ``validate/<binder_id>/``."""
+        from bindsight.runners.tools import parse_chai_output
+
+        cwd = Path("validate") / binder_id
+        if not cwd.exists():
+            raise MissingValidationError(
+                f"no Chai-1 output found at {cwd}; run the GPU validation step first "
+                "(bindsight validate --validator chai1r)"
+            )
+        return parse_chai_output(cwd, binder_id=binder_id, target_uniprot=target_uniprot)

bindsight/validate/protocol.py

@@ -0,0 +1,188 @@
+# SPDX-FileCopyrightText: 2026 Mikhaeel Atef Rizk Wahba
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Validator protocol.
+
+Validators take a designed binder (sequence + maybe a structural model) plus
+the target, and predict the complex structure + binding affinity. We treat
+``Boltz-2`` as the default; users can opt into ``Chai-1r`` for cross-model
+agreement or ``AF2-IG`` for the gold-standard Bennet/Baker filtering pipeline
+(PyRosetta is free only for non-commercial use — banner shown at CLI time).
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Protocol, runtime_checkable
+
+from pydantic import BaseModel, ConfigDict, Field
+
+#: What a validator reports when its tool's version cannot be established.
+#:
+#: Deliberately not a version-shaped string. Every parser here used to write a
+#: literal into :attr:`ValidationResult.validator_version` — ``"2.0.1"``,
+#: ``"0.6"``, ``"1.0"`` — regardless of what was installed, which made the one
+#: field that looks like provenance answer from a constant. A reader checking
+#: which model produced a result got a confident wrong answer instead of an
+#: obviously missing one, and no substitute that *looks* like a version fixes
+#: that.
+UNRECORDED_VERSION = "unrecorded"
+
+
+def installed_version(distribution: str) -> str | None:
+    """The installed version of ``distribution``, or ``None`` if it is absent.
+
+    Validators parse output on whatever machine holds the files, which is not
+    always the machine that produced them; ``None`` is the honest answer there,
+    and callers turn it into :data:`UNRECORDED_VERSION`.
+
+    Args:
+        distribution: the installed distribution name, e.g. ``"boltz"``.
+
+    Returns:
+        The version string, or ``None`` when the distribution is not installed.
+    """
+    from importlib.metadata import PackageNotFoundError, version
+
+    try:
+        return version(distribution)
+    except PackageNotFoundError:
+        return None
+
+
+class ValidationResult(BaseModel):
+    """Per-design validation metrics."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    binder_id: str
+    target_uniprot: str
+    iptm: float | None = Field(None, ge=0.0, le=1.0)
+    ptm: float | None = Field(
+        None,
+        ge=0.0,
+        le=1.0,
+        description=(
+            "Predicted TM-score for the complex — a structure-confidence metric, NOT an "
+            "affinity. Kept in its own field so it can never be mistaken for one."
+        ),
+    )
+    plddt_binder: float | None = Field(
+        None,
+        ge=0.0,
+        le=100.0,
+        description=(
+            "Mean pLDDT over the binder chain (0-100 scale) — a structure-confidence "
+            "metric, NOT an affinity."
+        ),
+    )
+    pae_interaction: float | None = Field(None, ge=0.0)
+    rmsd_to_designed: float | None = Field(None, ge=0.0)
+    affinity_pred_value: float | None = Field(
+        None,
+        description=(
+            "Predicted binding affinity from a validator that actually predicts one. "
+            "LOWER IS STRONGER: Boltz-2 reports a log(IC50)-like value, so -8.0 is a "
+            "tighter binder than -6.0, and the ranker inverts it accordingly. Validators "
+            "that do not predict affinity MUST leave this None rather than substituting a "
+            "confidence metric — see ptm and plddt_binder."
+        ),
+    )
+    affinity_probability_binary: float | None = Field(
+        None,
+        ge=0.0,
+        le=1.0,
+        description="Probability the design is a binder vs. a decoy (early-discovery filter).",
+    )
+    iptm_n_samples: int | None = Field(
+        None,
+        ge=1,
+        description=(
+            "How many independent draws ``iptm`` averages. Boltz-2 builds "
+            "structures by diffusion, so one draw is a sample, not a "
+            "measurement — a reader cannot otherwise tell a single draw from an "
+            "average of five. ``None`` means the run predates this field and "
+            "the count is unknown."
+        ),
+    )
+    iptm_sd: float | None = Field(
+        None,
+        ge=0.0,
+        description=(
+            "Spread of ``iptm`` across those draws, or ``None`` when there was "
+            "only one. This is the metric's own noise, measured on the same "
+            "input in the same job, and it is what any difference between two "
+            "designs has to be larger than to mean anything."
+        ),
+    )
+    validator_name: str
+    validator_version: str
+    notes: str | None = None
+
+    @property
+    def measured(self) -> bool:
+        """True when the validator produced at least one metric.
+
+        A result whose every metric is ``None`` is still a valid row: it reaches
+        metrics.jsonl, the ranker and the report looking exactly like a design
+        that was scored and scored badly. It is not the same thing, and the
+        difference is invisible unless something says so.
+        """
+        return any(
+            value is not None
+            for value in (
+                self.iptm,
+                self.ptm,
+                self.plddt_binder,
+                self.pae_interaction,
+                self.affinity_pred_value,
+            )
+        )
+
+
+@runtime_checkable
+class Validator(Protocol):
+    """Protocol every validator plugin must implement."""
+
+    name: str
+    version: str
+    license_notice: str  # Shown by the CLI before each run.
+
+    def validate(
+        self,
+        target_uniprot: str,
+        binder_id: str,
+        binder_sequence: str,
+        target_structure_path: str,
+    ) -> ValidationResult:
+        """Run the validator and return metrics."""
+        ...
+
+
+#: The phrase a validator's ``notes`` carries when it parsed no metric at all.
+#: Checked across every parser by the test suite, so the guarantee is uniform
+#: rather than whichever parser someone remembered to handle.
+NO_METRICS_NOTE = "no metrics parsed"
+
+
+def note_unmeasured(
+    result: ValidationResult, *, reason: str, log: logging.Logger
+) -> ValidationResult:
+    """Warn and annotate when ``result`` carries no metric; pass it through otherwise.
+
+    The AF2 initial-guess parser returned an all-``None`` result for a score file
+    that was missing, truncated to its header, or written with different column
+    names -- three real failure modes, none of which produced a warning or left
+    any trace in the row. This is the single place that decides what such a
+    result says about itself.
+    """
+    if result.measured:
+        return result
+    log.warning(
+        "%s parsed no metrics for %s: %s",
+        result.validator_name,
+        result.binder_id,
+        reason,
+    )
+    existing = (result.notes or "").strip()
+    note = f"{NO_METRICS_NOTE}: {reason}"
+    return result.model_copy(update={"notes": f"{existing}; {note}" if existing else note})

bindsight-0.3.5.data/data/bindsight_demo/config.yaml

@@ -0,0 +1,54 @@
+# bindsight demo config — runs the discovery half on a REAL TCGA breast-cancer
+# cohort (NIH/GDC). It discovers cell-surface, antibody-tractable antigens that
+# are over-expressed in tumor vs. adjacent normal, ranked with full provenance.
+# Well-known breast-cancer surface antigens (e.g. ERBB2/HER2) surface among the
+# candidates when their signal is present in the sampled cohort; EGFR is often
+# lower in bulk tumor than in normal breast epithelium, so it may rank as a
+# down-regulated DEG rather than a top up-regulated target — that's the real
+# biology, not a scripted result.
+#
+# On first run, `bindsight discover`/`demo` auto-downloads the cohort (STAR -
+# Counts) from the GDC open-access API into the cache below, populates the full
+# SURFY surfaceome list, and enriches the top up-regulated DEGs via Open
+# Targets; subsequent runs are cached. Needs network the first time; takes a few
+# minutes (real DESeq2 + enrichment on real data), not 30 seconds.
+
+name: bindsight_demo_tcga_brca
+out_dir: runs/demo
+
+inputs:
+  # Auto-downloaded from GDC if absent (see bindsight/io/gdc.py). Cached here.
+  counts: data/gdc_cache/tcga_brca/counts.tsv.gz
+  design: data/gdc_cache/tcga_brca/design.tsv
+  download:
+    project: TCGA-BRCA
+    n_tumor: 20
+    n_normal: 20
+    gene_types: ["protein_coding"]
+
+params:
+  deg:
+    design_formula: "~ condition"
+    contrast: ["condition", "tumor", "normal"]
+    fdr_threshold: 0.05
+    log2fc_threshold: 1.0
+    min_replicates: 3
+    min_count: 10
+
+  target_discovery:
+    require_surfy: true
+    surfy_allow_offline_fallback: true   # attempt full SURFY; fall back if offline
+    use_open_targets: true               # genuine discovery across the surfaceome
+    # The demo is expected to run offline, where Open Targets is unreachable
+    # and every safety-event count is unknown. A real run withholds those
+    # candidates; the demo accepts them so it still shows a full pipeline
+    # without a network. This is a deliberate loosening, stated here rather
+    # than hidden in a default.
+    open_targets_require_measured: false
+    require_tractable_modality: []       # don't pre-filter modality in the demo
+    max_safety_events: 100
+    require_surface_bind_site: false
+    top_n: 10
+
+backend: colab
+cheap_profile: false