bindsight 0.3.5__py3-none-any.whl

bindsight/targets/gtex.py

@@ -0,0 +1,250 @@
+# SPDX-FileCopyrightText: 2026 Mikhaeel Atef Rizk Wahba
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Normal-tissue expression from GTEx (on-target / off-tumor safety).
+
+A good antibody / ADC target is over-expressed in tumour but **low in vital normal
+tissues** — otherwise the binder attacks healthy heart, brain, liver or lung
+(on-target/off-tumor toxicity). bindsight ranks candidates from tumour RNA-seq;
+this module adds the missing other half: median expression across normal tissues,
+straight from GTEx v8 (the reference normal-tissue RNA atlas), so a candidate's
+vital-tissue expression can gate it.
+
+Data (real, cached): GTEx v8 gene-level median TPM per tissue (GCT), ~7 MB:
+    https://storage.googleapis.com/adult-gtex/bulk-gex/v8/rna-seq/
+        GTEx_Analysis_2017-06-05_v8_RNASeQCv1.1.9_gene_median_tpm.gct.gz
+
+Fails closed. The gate exists to keep unsafe targets out, so "we could not check"
+must never read as "checked and safe": an unavailable reference raises
+:class:`GTExUnavailableError`, and a gene the reference does not cover is reported
+as ``unassessed`` (:meth:`GTExTissueExpression.assess`) rather than silently
+passing the gate.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+import pandas as pd
+import requests
+from tenacity import (
+    retry,
+    retry_if_exception_type,
+    stop_after_attempt,
+    wait_exponential,
+)
+
+from bindsight.io.paths import cache_dir
+
+LOG = logging.getLogger(__name__)
+
+GTEX_MEDIAN_TPM_URL = (
+    "https://storage.googleapis.com/adult-gtex/bulk-gex/v8/rna-seq/"
+    "GTEx_Analysis_2017-06-05_v8_RNASeQCv1.1.9_gene_median_tpm.gct.gz"
+)
+
+
+class GTExUnavailableError(RuntimeError):
+    """The GTEx reference could not be obtained or parsed.
+
+    Raised instead of returning "no expression found", which a caller would read
+    as a clean safety verdict on a target whose normal-tissue expression was in
+    fact never checked.
+    """
+
+
+@dataclass(frozen=True)
+class TissueSafety:
+    """One gene's normal-tissue verdict against a vital-tissue TPM ceiling."""
+
+    status: Literal["safe", "unsafe", "unassessed"]
+    max_tpm: float | None
+    reason: str
+    #: The vital tissues this verdict actually looked at, and those it could not.
+    #:
+    #: A requested tissue with no matching GTEx column was silently dropped and
+    #: the maximum taken over whatever remained, so a gene highly expressed in a
+    #: dropped tissue was reported "safe" by a check that never looked at it.
+    #: A safety verdict has to say what it examined.
+    tissues_checked: tuple[str, ...] = ()
+    tissues_unrecognised: tuple[str, ...] = ()
+
+
+def normalize_tissue(name: str) -> str:
+    """Normalise a GTEx tissue label to a config-friendly key.
+
+    'Heart - Left Ventricle' -> 'heart_left_ventricle'; 'Brain - Cortex' ->
+    'brain_cortex'; 'Liver' -> 'liver'.
+    """
+    return name.strip().lower().replace(" - ", "_").replace(" ", "_").replace("-", "_")
+
+
+class GTExTissueExpression:
+    """Cached GTEx median-TPM-by-tissue lookup, keyed by Ensembl gene id."""
+
+    def __init__(
+        self,
+        cache_subdir: str = "gtex",
+        url: str = GTEX_MEDIAN_TPM_URL,
+        gct_path: Path | str | None = None,
+        timeout: float = 180.0,
+        session: requests.Session | None = None,
+    ) -> None:
+        self.cache = cache_dir(cache_subdir)
+        self.url = url
+        # When provided (tests / vendored data) the GCT is read directly, no network.
+        self.gct_path = Path(gct_path) if gct_path else None
+        self.timeout = timeout
+        self.session = session or requests.Session()
+        self.session.headers.setdefault(
+            "User-Agent", "bindsight/0.0.1 (+https://github.com/mikhaeelatefrizk/bindsight)"
+        )
+        self._df: pd.DataFrame | None = None
+
+    def _parquet_cache_path(self) -> Path:
+        return self.cache / "gene_median_tpm.parquet"
+
+    @retry(
+        retry=retry_if_exception_type(requests.RequestException),
+        wait=wait_exponential(multiplier=1, min=2, max=30),
+        stop=stop_after_attempt(5),
+        reraise=True,
+    )
+    def _download(self, url: str) -> bytes:
+        resp = self.session.get(url, timeout=self.timeout)
+        resp.raise_for_status()
+        return resp.content
+
+    def _ensure_gct(self) -> Path:
+        cached = self.cache / "gene_median_tpm.gct.gz"
+        if cached.exists():
+            return cached
+        try:
+            payload = self._download(self.url)
+        except requests.RequestException as e:
+            raise GTExUnavailableError(f"GTEx download failed: {e}") from e
+        cached.write_bytes(payload)
+        return cached
+
+    def _load(self) -> pd.DataFrame:
+        """Return a DataFrame indexed by unversioned Ensembl id, columns = tissues.
+
+        Raises:
+            GTExUnavailableError: The reference is missing or unparseable, so no
+                normal-tissue claim can be made about any gene.
+        """
+        if self._df is not None:
+            return self._df
+        # Fast path: parsed parquet cache (only for the live/downloaded source).
+        parq = self._parquet_cache_path()
+        if self.gct_path is None and parq.exists():
+            try:
+                self._df = pd.read_parquet(parq)
+                return self._df
+            except Exception as e:  # corrupt cache — rebuild
+                LOG.warning("GTEx parquet cache unreadable (%s); rebuilding", e)
+
+        gct = self.gct_path or self._ensure_gct()
+        if not Path(gct).exists():
+            raise GTExUnavailableError(f"GTEx reference not found at {gct}")
+        try:
+            df = pd.read_csv(gct, sep="\t", skiprows=2)
+            df["__gene"] = df["Name"].str.split(".").str[0]
+            df = df.drop(columns=["Name", "Description"]).set_index("__gene")
+            df.columns = [normalize_tissue(c) for c in df.columns]
+            df = df[~df.index.duplicated(keep="first")]
+        except Exception as e:
+            raise GTExUnavailableError(f"GTEx GCT parse failed for {gct}: {e}") from e
+        self._df = df
+        if self.gct_path is None:
+            # parquet cache is an optimisation, not required
+            with contextlib.suppress(Exception):
+                df.to_parquet(parq)
+        return df
+
+    def max_expression(self, ensembl_id: str, tissues: list[str]) -> float | None:
+        """Max median TPM of ``ensembl_id`` across ``tissues``.
+
+        ``None`` means *not measured here* — no gene id, the gene isn't in GTEx,
+        or none of the requested tissues exist. It never means "low expression";
+        use :meth:`assess` to get that distinction as a verdict.
+
+        Raises:
+            GTExUnavailableError: The reference itself is unavailable.
+        """
+        if not ensembl_id:
+            return None
+        df = self._load()
+        gene = ensembl_id.split(".")[0]
+        if gene not in df.index:
+            return None
+        cols = [c for c in (normalize_tissue(t) for t in tissues) if c in df.columns]
+        if not cols:
+            return None
+        return float(df.loc[gene, cols].max())
+
+    def coverage(self, tissues: list[str]) -> tuple[tuple[str, ...], tuple[str, ...]]:
+        """Split ``tissues`` into those GTEx can answer for and those it cannot.
+
+        Returns ``(checked, unrecognised)``, both in config spelling. The
+        unrecognised half used to be dropped without a word, which turned a
+        partial check into a clean bill of health.
+        """
+        try:
+            columns = set(self._load().columns)
+        except Exception:  # a reference that will not load answers for nothing
+            return (), tuple(tissues)
+        checked = tuple(t for t in tissues if normalize_tissue(t) in columns)
+        return checked, tuple(t for t in tissues if normalize_tissue(t) not in columns)
+
+    def assess(self, ensembl_id: str, tissues: list[str], max_tpm: float) -> TissueSafety:
+        """Verdict for one gene against the vital-tissue ceiling ``max_tpm``.
+
+        Args:
+            ensembl_id: Ensembl gene id (a version suffix is stripped).
+            tissues: Vital tissues to check, in config spelling.
+            max_tpm: Median-TPM ceiling above which the target is unsafe.
+
+        Returns:
+            A :class:`TissueSafety` whose ``status`` separates a measured pass
+            (``safe``) from an absent measurement (``unassessed``). Only ``safe``
+            may be presented as having cleared the normal-tissue gate.
+
+        Raises:
+            GTExUnavailableError: The reference is unavailable, so the gate cannot
+                be applied to any candidate at all.
+        """
+        value = self.max_expression(ensembl_id, tissues)
+        checked, unrecognised = self.coverage(tissues)
+        # Named in every verdict, not only the failing ones: a reader checking
+        # whether brain was examined should not have to infer it from silence.
+        gap = f" Not examined (no GTEx column): {', '.join(unrecognised)}." if unrecognised else ""
+        if value is None:
+            return TissueSafety(
+                status="unassessed",
+                max_tpm=None,
+                reason=f"{ensembl_id or '<no gene id>'} has no GTEx median-TPM entry for "
+                f"{', '.join(tissues) or '<no tissues>'}" + gap,
+                tissues_checked=checked,
+                tissues_unrecognised=unrecognised,
+            )
+        if value > max_tpm:
+            return TissueSafety(
+                status="unsafe",
+                max_tpm=value,
+                reason=f"median TPM {value:.1f} exceeds the {max_tpm:.1f} vital-tissue ceiling"
+                + gap,
+                tissues_checked=checked,
+                tissues_unrecognised=unrecognised,
+            )
+        return TissueSafety(
+            status="safe",
+            max_tpm=value,
+            reason=f"median TPM {value:.1f} is at or below the {max_tpm:.1f} "
+            f"vital-tissue ceiling" + gap,
+            tissues_checked=checked,
+            tissues_unrecognised=unrecognised,
+        )

bindsight/targets/open_targets.py

@@ -0,0 +1,239 @@
+# SPDX-FileCopyrightText: 2026 Mikhaeel Atef Rizk Wahba
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Open Targets Platform GraphQL client.
+
+Open Targets aggregates target-disease association evidence from ~20 sources
+(literature, genetic associations, somatic mutations, drug evidence, etc.).
+We use it to enrich differentially-expressed candidates with druggability,
+known disease links, safety liabilities, and tractability scores.
+
+API docs: https://platform-docs.opentargets.org/data-access/graphql-api
+Endpoint: https://api.platform.opentargets.org/api/v4/graphql
+
+Rate limits are generous but not unlimited. We back off with tenacity.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import time as _time
+from pathlib import Path
+from typing import Any
+
+import requests
+from pydantic import BaseModel, ConfigDict, Field
+from tenacity import (
+    retry,
+    retry_if_exception_type,
+    stop_after_attempt,
+    wait_exponential,
+)
+
+from bindsight.io.paths import cache_dir
+
+LOG = logging.getLogger(__name__)
+
+OPEN_TARGETS_URL = "https://api.platform.opentargets.org/api/v4/graphql"
+
+# A focused query: per Ensembl gene ID, fetch the bits we actually use for
+# target prioritization downstream. Kept small to stay friendly to the API.
+_TARGET_QUERY = """
+query Target($ensemblId: String!) {
+  target(ensemblId: $ensemblId) {
+    id
+    approvedSymbol
+    approvedName
+    biotype
+    proteinIds {
+      id
+      source
+    }
+    tractability {
+      modality
+      label
+      value
+    }
+    safetyLiabilities {
+      event
+      datasource
+    }
+    associatedDiseases(page: { index: 0, size: 20 }) {
+      count
+      rows {
+        score
+        disease {
+          id
+          name
+          therapeuticAreas {
+            id
+            name
+          }
+        }
+      }
+    }
+  }
+}
+"""
+
+
+class TargetEvidence(BaseModel):
+    """Slim record of Open Targets evidence for a single gene."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    ensembl_id: str
+    symbol: str | None = None
+    name: str | None = None
+    biotype: str | None = None
+    uniprot_ids: list[str] = Field(default_factory=list)
+    tractability_modalities: list[str] = Field(
+        default_factory=list,
+        description="e.g. ['Antibody', 'SmallMolecule', 'PROTAC']. Sourced from "
+        "tractability.value=true rows.",
+    )
+    safety_event_count: int = 0
+    top_disease_associations: list[dict[str, Any]] = Field(default_factory=list)
+
+
+#: How long an Open Targets response may be reused. Their releases are roughly
+#: quarterly and move association scores, which move the ranking; an entry older
+#: than this describes a different release from the one a run claims to have
+#: used. Refetching costs one request against a cache that is otherwise warm.
+CACHE_MAX_AGE_DAYS = 30
+
+
+class OpenTargetsClient:
+    """Cached, retrying GraphQL client for Open Targets."""
+
+    def __init__(
+        self,
+        endpoint: str = OPEN_TARGETS_URL,
+        cache_subdir: str = "opentargets",
+        timeout: float = 30.0,
+        session: requests.Session | None = None,
+    ) -> None:
+        self.endpoint = endpoint
+        self.cache = cache_dir(cache_subdir)
+        self.timeout = timeout
+        self.session = session or requests.Session()
+        self.session.headers.setdefault(
+            "User-Agent", "bindsight/0.0.1 (+https://github.com/mikhaeelatefrizk/bindsight)"
+        )
+
+    def _cache_key(self, query: str, variables: dict[str, Any]) -> Path:
+        """Where a response is cached.
+
+        The endpoint is part of the key, and the file records when it was
+        fetched. Neither was true before: the key was a hash of the query text
+        and variables alone, and a hit was returned unconditionally however old
+        it was and whichever endpoint produced it. So a warm cache from an
+        earlier Open Targets release supplied that release's association scores
+        to today's run while the provenance recorded today's date -- two
+        machines, the same command, different candidate rankings, and nothing in
+        either manifest saying which.
+
+        The repository already accepted exactly this reasoning for the
+        surfaceome (``tests/test_silent_success.py`` -- "two runs on two machines
+        could use different surfaceome lists ... and nothing in either manifest
+        would say which"). Open Targets is a larger input to the ranking than
+        the surfaceome is.
+        """
+        payload = json.dumps(
+            {"endpoint": self.endpoint, "query": query, "variables": variables},
+            sort_keys=True,
+        )
+        sig = hashlib.sha256(payload.encode()).hexdigest()
+        return self.cache / f"{sig}.json"
+
+    @retry(
+        retry=retry_if_exception_type(requests.RequestException),
+        wait=wait_exponential(multiplier=1, min=2, max=30),
+        stop=stop_after_attempt(5),
+        reraise=True,
+    )
+    def _post(self, query: str, variables: dict[str, Any]) -> dict[str, Any]:
+        resp = self.session.post(
+            self.endpoint,
+            json={"query": query, "variables": variables},
+            timeout=self.timeout,
+        )
+        resp.raise_for_status()
+        body = resp.json()
+        if "errors" in body:
+            raise RuntimeError(f"Open Targets GraphQL errors: {body['errors']}")
+        data: dict[str, Any] = body["data"]
+        return data
+
+    def query(self, query: str, variables: dict[str, Any]) -> dict[str, Any]:
+        """Execute a raw GraphQL query, with on-disk caching.
+
+        A cached entry older than :data:`CACHE_MAX_AGE_DAYS` is refetched. The
+        cache used to have no expiry at all, so a response fetched months ago
+        was served to a run whose provenance stamped today -- the run was
+        reproducible against that machine's disk and against nothing else.
+        """
+        key = self._cache_key(query, variables)
+        if key.exists():
+            try:
+                envelope = json.loads(key.read_text(encoding="utf-8"))
+            except (OSError, json.JSONDecodeError):
+                envelope = None
+            if isinstance(envelope, dict) and "fetched_at" in envelope:
+                age = _time.time() - float(envelope.get("fetched_at") or 0)
+                if age <= CACHE_MAX_AGE_DAYS * 86400:
+                    cached: dict[str, Any] = envelope.get("data") or {}
+                    return cached
+                LOG.info(
+                    "Open Targets cache entry is %.0f days old; refetching",
+                    age / 86400,
+                )
+            else:
+                # An entry from before the cache recorded its age. Its release
+                # is unknown, so it cannot be trusted to describe today's run.
+                LOG.info("Open Targets cache entry predates age recording; refetching")
+
+        data = self._post(query, variables)
+        key.write_text(
+            json.dumps({"fetched_at": _time.time(), "endpoint": self.endpoint, "data": data}),
+            encoding="utf-8",
+            newline="\n",
+        )
+        return data
+
+    def get_target(self, ensembl_id: str) -> TargetEvidence | None:
+        """Fetch the target evidence record for an Ensembl gene ID.
+
+        Returns ``None`` if Open Targets has no record for the gene.
+        """
+        data = self.query(_TARGET_QUERY, {"ensemblId": ensembl_id})
+        t = data.get("target")
+        if t is None:
+            return None
+
+        uniprot_ids = [
+            p["id"] for p in (t.get("proteinIds") or []) if p.get("source") == "uniprot_swissprot"
+        ]
+        modalities = sorted(
+            {row["modality"] for row in (t.get("tractability") or []) if row.get("value") is True}
+        )
+        diseases = [
+            {
+                "score": row["score"],
+                "disease_id": row["disease"]["id"],
+                "disease_name": row["disease"]["name"],
+                "therapeutic_areas": [ta["name"] for ta in row["disease"]["therapeuticAreas"]],
+            }
+            for row in (t.get("associatedDiseases", {}) or {}).get("rows", [])
+        ]
+        return TargetEvidence(
+            ensembl_id=t["id"],
+            symbol=t.get("approvedSymbol"),
+            name=t.get("approvedName"),
+            biotype=t.get("biotype"),
+            uniprot_ids=uniprot_ids,
+            tractability_modalities=modalities,
+            safety_event_count=len(t.get("safetyLiabilities") or []),
+            top_disease_associations=diseases,
+        )

bindsight/validate/__init__.py

@@ -0,0 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Mikhaeel Atef Rizk Wahba
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Validator plugin interface (Boltz-2, Chai-1r, AF2-IG)."""
+
+from bindsight.validate.protocol import ValidationResult, Validator
+
+__all__ = ["ValidationResult", "Validator"]

bindsight/validate/af2_ig.py

@@ -0,0 +1,49 @@
+# SPDX-FileCopyrightText: 2026 Mikhaeel Atef Rizk Wahba
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""AF2-IG validator plugin (opt-in; PyRosetta is free only for non-commercial use).
+
+AF2 with initial guess (`Bennett/Baker dl_binder_design
+<https://github.com/nrbennet/dl_binder_design>`_) is the gold-standard binder
+filter — but depends on PyRosetta, which is free only for non-commercial use; the
+AlphaFold2 parameters themselves are CC BY 4.0. The CLI prints
+a license banner before invoking this plugin. The GPU inference runs in
+:mod:`bindsight.runners.job_exec`; this plugin's :meth:`validate` parses the
+AF2 initial-guess score file the runner produced.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from bindsight.validate.boltz2 import MissingValidationError
+from bindsight.validate.protocol import ValidationResult
+
+
+class AF2IGValidator:
+    """Plugin: AlphaFold2 with initial guess (PyRosetta: non-commercial use only)."""
+
+    name = "af2_ig"
+    version = "1.0"
+    license_notice = (
+        "AF2-IG depends on PyRosetta, which is free only for non-commercial use; "
+        "the AlphaFold2 parameters are CC BY 4.0. See LICENSING.md § 3."
+    )
+
+    def validate(
+        self,
+        target_uniprot: str,
+        binder_id: str,
+        binder_sequence: str,
+        target_structure_path: str,
+    ) -> ValidationResult:
+        """Parse AF2 initial-guess output for this binder from ``validate/<binder_id>/``."""
+        from bindsight.runners.tools import parse_af2ig_output
+
+        cwd = Path("validate") / binder_id
+        score_file = cwd / "af2_scores.sc"
+        if not score_file.exists():
+            raise MissingValidationError(
+                f"no AF2-IG output found at {score_file}; run the GPU validation step first "
+                "(bindsight validate --validator af2_ig)"
+            )
+        return parse_af2ig_output(score_file, binder_id=binder_id, target_uniprot=target_uniprot)