bindsight 0.3.5__py3-none-any.whl

bindsight/runners/mock.py

@@ -0,0 +1,167 @@
+# SPDX-FileCopyrightText: 2026 Mikhaeel Atef Rizk Wahba
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Mock GPU runner for CI.
+
+Returns canned-but-realistically-shaped results immediately so CI (and the
+Snakemake DAG / ``bindsight run --backend mock``) can exercise the full
+orchestration — design → validate → rank → report → export — end-to-end without
+a real GPU. The numeric values are clearly labelled as synthetic.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import shutil
+import tarfile
+import tempfile
+import uuid
+from datetime import UTC, datetime
+from pathlib import Path
+
+from bindsight.runners.protocol import CostEstimate, JobHandle, JobStatus
+
+
+def _ATEXIT_CLEANUP(path: Path) -> None:
+    """Remove a scratch directory when the process ends.
+
+    These were created with ``mkdtemp`` and never removed. On a long-lived
+    process -- the hosted app is the obvious one -- that is one directory per
+    invocation, retained for the container's lifetime.
+    """
+    import atexit
+    import shutil
+
+    atexit.register(shutil.rmtree, path, True)
+
+
+# A minimal valid PDB (3 CA atoms) so downstream parsers have something real.
+LOG = logging.getLogger(__name__)
+
+_MOCK_PDB = (
+    "ATOM      1  CA  GLY A   1      0.000   0.000   0.000  1.00  0.00           C\n"
+    "ATOM      2  CA  SER A   2      3.800   0.000   0.000  1.00  0.00           C\n"
+    "ATOM      3  CA  HIS A   3      7.600   0.000   0.000  1.00  0.00           C\n"
+    "END\n"
+)
+
+
+class MockRunner:
+    """Returns a canned tarball of fake results."""
+
+    name = "mock"
+
+    def __init__(self, canned_archive: Path | None = None) -> None:
+        self.canned = canned_archive
+        # handle id -> target accession, so fetch() can namespace binder ids.
+        self._targets: dict[str, str] = {}
+
+    def estimate_cost(self, spec_size: int) -> CostEstimate:
+        """Return a zero-cost estimate; the mock runner never spends money."""
+        return CostEstimate(
+            backend=self.name,
+            gpu_type="mock",
+            gpu_hours=0.0,
+            usd_estimate=0.0,
+            queue_minutes_estimate=0.0,
+            notes="Mock runner — no real compute.",
+        )
+
+    def submit(self, spec_path: Path, *, results_dir: Path) -> JobHandle:
+        """Pretend to submit a job; returns a unique handle immediately.
+
+        The spec's target is recorded against the handle so :meth:`fetch` can
+        namespace the binder ids it invents. A mock that returns the same ids for
+        every target cannot exercise the invariant that binder ids are unique
+        across a run — and that is exactly the bug this mock is meant to catch,
+        since ``binder_id`` is the key the provenance chain is walked by.
+        """
+        results_dir.mkdir(parents=True, exist_ok=True)
+        handle_id = str(uuid.uuid4())
+        target = "MOCK"
+        try:
+            spec = json.loads(Path(spec_path).read_text(encoding="utf-8"))
+            target = str(spec.get("target_uniprot") or "MOCK")
+        except (OSError, ValueError) as e:  # a malformed spec must not break CI
+            LOG.warning("mock runner could not read %s: %s", spec_path, e)
+        self._targets[handle_id] = target
+        return JobHandle(
+            backend=self.name,
+            id=handle_id,
+            submitted_at=datetime.now(UTC).isoformat(timespec="seconds"),
+        )
+
+    def poll(self, handle: JobHandle) -> JobStatus:
+        """Always report 'succeeded' immediately."""
+        return JobStatus(handle=handle, state="succeeded", progress=1.0, log_tail=None)
+
+    def fetch(self, handle: JobHandle) -> Path:
+        """Return the canned archive, or build a realistically-shaped mock one.
+
+        The mock tarball mirrors what :mod:`bindsight.runners.job_exec` produces
+        (``metrics.jsonl`` + ``validate/<binder>/`` JSONs + ``design/<binder>``),
+        with clearly-synthetic numbers, so the whole orchestration runs E2E.
+
+        Binder ids carry the target accession, exactly as the real executor's do.
+        Without that, a multi-target run produces the same ids for every target,
+        the per-binder validation directories overwrite each other on disk, and
+        ``validated.parquet`` acquires duplicate keys — a mock that permits the
+        bug it is supposed to guard against is worse than no mock.
+        """
+        if self.canned is not None:
+            return self.canned
+        target = self._targets.get(handle.id, "MOCK")
+        root = Path(tempfile.mkdtemp(prefix="bindsight_mock_"))
+        _ATEXIT_CLEANUP(root)
+        work = root / "work"
+        design = work / "design"
+        validate = work / "validate"
+        design.mkdir(parents=True, exist_ok=True)
+
+        metrics = []
+        for i in range(2):
+            bid = f"{target}_mock_binder_{i}"
+            (design / f"{bid}.pdb").write_text(_MOCK_PDB, encoding="utf-8", newline="\n")
+            (design / f"{bid}.fasta").write_text(
+                f">{bid}\nGSHMSLEQKKGADIISKIL\n", encoding="utf-8", newline="\n"
+            )
+            vdir = validate / bid
+            vdir.mkdir(parents=True, exist_ok=True)
+            (vdir / f"confidence_{bid}_model_0.json").write_text(
+                json.dumps({"iptm": 0.70 + 0.05 * i, "pae_interaction": 6.0 - i}),
+                encoding="utf-8",
+                newline="\n",
+            )
+            (vdir / f"affinity_{bid}.json").write_text(
+                json.dumps({"affinity_pred_value": -7.0 - i, "affinity_probability_binary": 0.80}),
+                encoding="utf-8",
+                newline="\n",
+            )
+            metrics.append(
+                {
+                    "binder_id": bid,
+                    "target_uniprot": target,
+                    "iptm": 0.70 + 0.05 * i,
+                    "pae_interaction": 6.0 - i,
+                    "affinity_pred_value": -7.0 - i,
+                    "affinity_probability_binary": 0.80,
+                    "validator_name": "mock",
+                    "validator_version": "0",
+                    "notes": "mock runner — synthetic metrics for CI/orchestration only",
+                }
+            )
+        (work / "metrics.jsonl").write_text(
+            "\n".join(json.dumps(m) for m in metrics) + "\n", encoding="utf-8", newline="\n"
+        )
+
+        tarball = root / "results.tar.gz"
+        with tarfile.open(tarball, "w:gz", encoding="utf-8") as tf:
+            for sub in ("design", "validate", "metrics.jsonl"):
+                tf.add(work / sub, arcname=sub)
+        return tarball
+
+    @staticmethod
+    def cleanup(path: Path) -> None:
+        """Remove a temp directory created by :meth:`fetch`."""
+        if path.parent.name.startswith("bindsight_mock_"):
+            shutil.rmtree(path.parent, ignore_errors=True)

bindsight/runners/modal_runner.py

@@ -0,0 +1,199 @@
+# SPDX-FileCopyrightText: 2026 Mikhaeel Atef Rizk Wahba
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Modal serverless-GPU runner.
+
+`Modal <https://modal.com/>`_ provisions a GPU, runs
+:mod:`bindsight.runners.job_exec` (the same executor as the local/Kaggle
+paths), and tears down — per-second billing, A100 ≈ $3/hr. Requires the
+``runners`` extra (``modal``) and a Modal token (``modal token new``).
+
+``import modal`` happens lazily inside the methods via :func:`_require_modal`,
+so ``import bindsight`` works without the extra installed. Execution is
+synchronous from the caller's point of view (``submit`` runs the job and caches
+the tarball; ``fetch`` returns it), matching the Designer ``submit→fetch``
+contract.
+
+**Verification status.** Modal is the paid escape hatch for the components free
+hardware cannot reach: Chai-1r needs bfloat16 (compute capability 8.0+, which no
+free-tier GPU has), and full-receptor BindCraft and BoltzGen need more VRAM than
+a 16 GB free card. The image below is built to contain the whole design stack
+rather than only the validator, but it has not been executed end-to-end — running
+it costs money. Treat it as prepared, not proven, until a run is recorded.
+"""
+
+from __future__ import annotations
+
+import logging
+import uuid
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from bindsight.cost import estimate
+from bindsight.runners import tools
+from bindsight.runners.protocol import CostEstimate, JobHandle, JobStatus
+
+
+def _ATEXIT_CLEANUP(path: Path) -> None:
+    """Remove a scratch directory when the process ends.
+
+    These were created with ``mkdtemp`` and never removed. On a long-lived
+    process -- the hosted app is the obvious one -- that is one directory per
+    invocation, retained for the container's lifetime.
+    """
+    import atexit
+    import shutil
+
+    atexit.register(shutil.rmtree, path, True)
+
+
+LOG = logging.getLogger(__name__)
+
+#: Repository bindsight itself is installed from inside the remote image.
+#: bindsight is not published to PyPI, so a bare ``pip install bindsight``
+#: silently resolves to nothing.
+_BINDSIGHT_REPO = "https://github.com/mikhaeelatefrizk/bindsight.git"
+
+#: CUDA base image for the remote container. Devel rather than runtime because
+#: RFdiffusion's SE3-Transformer builds CUDA extensions at install time.
+_MODAL_CUDA_IMAGE = "nvidia/cuda:12.4.1-devel-ubuntu22.04"
+
+# Map bindsight GPU names to Modal gpu= strings.
+_MODAL_GPU = {
+    "A100-40GB": "A100",
+    "A100-80GB": "A100-80GB",
+    "T4": "T4",
+    "L4": "L4",
+    "A10G": "A10G",
+    "H100": "H100",
+}
+
+# handle id -> local tarball path (submit runs synchronously and caches here).
+_RESULTS: dict[str, Path] = {}
+
+
+def _require_modal() -> Any:
+    """Import Modal with a clear, actionable error if the extra isn't installed."""
+    try:
+        import modal
+    except ImportError as e:
+        raise RuntimeError(
+            'Modal runner needs the "runners" extra: pip install -e ".[runners]" '
+            "and a Modal token (run: modal token new)."
+        ) from e
+    return modal
+
+
+class ModalRunner:
+    """Serverless-GPU runner that executes the design+validation job on Modal."""
+
+    name = "modal"
+
+    def __init__(
+        self,
+        *,
+        designer: str = "rfdiff_mpnn",
+        n_units_per_target: int = 50,
+        gpu_type: str = "A100-40GB",
+        app_name: str = "bindsight",
+        timeout_s: int = 3600,
+    ) -> None:
+        self.designer = designer
+        self.n_units_per_target = n_units_per_target
+        self.gpu_type = gpu_type
+        self.app_name = app_name
+        self.timeout_s = timeout_s
+
+    def estimate_cost(self, spec_size: int) -> CostEstimate:
+        """Estimate cost for ``spec_size`` design trajectories on Modal."""
+        return estimate(
+            backend=self.name,
+            stage="design",
+            plugin=self.designer,
+            n_units=spec_size,
+            gpu_type=self.gpu_type,
+        )
+
+    def _build_app(self) -> tuple[Any, Any]:
+        """Define the Modal app + GPU function lazily."""
+        modal = _require_modal()
+        image = (
+            # A CUDA *devel* base, not debian_slim: RFdiffusion's SE3-Transformer
+            # compiles CUDA extensions during install, so a runtime-only image
+            # cannot build it. debian_slim additionally ships no CUDA at all, so
+            # the previous image could run the Boltz-2 validator and nothing else.
+            modal.Image.from_registry(_MODAL_CUDA_IMAGE, add_python="3.11")
+            .apt_install("git", "wget", "build-essential")
+            # bindsight is not on PyPI. `pip_install("bindsight")` resolved to
+            # nothing, so this image never contained the executor it exists to run.
+            .pip_install(
+                f"bindsight @ git+{_BINDSIGHT_REPO}",
+                tools.BOLTZ_PIP,
+                "pandas",
+                "pyarrow",
+                "biopython",
+            )
+        )
+        app = modal.App(self.app_name)
+        gpu = _MODAL_GPU.get(self.gpu_type, "A100")
+
+        @app.function(gpu=gpu, image=image, timeout=self.timeout_s)  # type: ignore[untyped-decorator]
+        def _run_remote(spec_json: str, files: dict[str, bytes]) -> bytes:
+            import json as _json
+            import tempfile
+            from pathlib import Path as _P
+
+            from bindsight.runners import job_exec
+
+            work = _P(tempfile.mkdtemp(prefix="bindsight_modal_"))
+            _ATEXIT_CLEANUP(work)
+            spec_dir = work / "spec"
+            spec_dir.mkdir(parents=True, exist_ok=True)
+            (spec_dir / "spec.json").write_text(spec_json, encoding="utf-8", newline="\n")
+            for name, data in files.items():
+                (spec_dir / name).write_bytes(data)
+            spec = _json.loads(spec_json)
+            job_exec.materialise_target(spec, spec_dir, work / "run")
+            tarball = job_exec.run_job(spec, work / "run", tarball=work / "results.tar.gz")
+            return tarball.read_bytes()
+
+        return app, _run_remote
+
+    def submit(self, spec_path: Path, *, results_dir: Path) -> JobHandle:
+        """Run the job on Modal (synchronously) and cache the tarball locally."""
+        results_dir.mkdir(parents=True, exist_ok=True)
+        handle_id = str(uuid.uuid4())
+        tarball = results_dir / f"{handle_id}.tar.gz"
+
+        spec_json = spec_path.read_text(encoding="utf-8")
+        files = {
+            f.name: f.read_bytes()
+            for f in spec_path.parent.iterdir()
+            if f.is_file() and f.name != spec_path.name
+        }
+        app, run_remote = self._build_app()
+        LOG.info("modal submit: running job on %s (gpu=%s)", self.app_name, self.gpu_type)
+        with app.run():
+            data: bytes = run_remote.remote(spec_json, files)
+        tarball.write_bytes(data)
+        _RESULTS[handle_id] = tarball
+        return JobHandle(
+            backend=self.name,
+            id=handle_id,
+            submitted_at=datetime.now(UTC).isoformat(timespec="seconds"),
+            results_dir=str(results_dir),
+            tarball=str(tarball),
+        )
+
+    def poll(self, handle: JobHandle) -> JobStatus:
+        """Report status (submit is synchronous, so a known handle is done)."""
+        tarball = _RESULTS.get(handle.id) or Path(getattr(handle, "tarball", ""))
+        state = "succeeded" if Path(tarball).exists() else "failed"
+        return JobStatus(handle=handle, state=state, progress=1.0 if state == "succeeded" else None)
+
+    def fetch(self, handle: JobHandle) -> Path:
+        """Return the locally-cached results tarball written by :meth:`submit`."""
+        tarball = _RESULTS.get(handle.id) or Path(getattr(handle, "tarball", ""))
+        if not Path(tarball).exists():
+            raise RuntimeError(f"modal job {handle.id} produced no results at {tarball}")
+        return Path(tarball)

bindsight/runners/notebook.py

@@ -0,0 +1,116 @@
+# SPDX-FileCopyrightText: 2026 Mikhaeel Atef Rizk Wahba
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Helpers for building Colab/Kaggle notebooks programmatically.
+
+The notebook format is just JSON; we construct it as Python dicts and serialize
+with the standard library, instead of carrying a heavy ``nbformat`` dependency.
+This keeps the install lean and CI fast.
+
+A notebook has a small fixed envelope and a list of cells. Each cell is either:
+
+- ``code`` — a list of source lines + execution metadata
+- ``markdown`` — a list of source lines
+
+We emit Colab-flavored notebooks (the ``colab`` metadata block tells Colab
+which runtime to provision; e.g. ``GPU`` with ``T4`` or ``A100``).
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Literal
+
+from jinja2 import BaseLoader, Environment, StrictUndefined
+
+NotebookGPU = Literal["T4", "L4", "A100", "V100"]
+
+
+def _code_cell(src: str | list[str]) -> dict[str, Any]:
+    if isinstance(src, str):
+        src = src.splitlines(keepends=True)
+    return {
+        "cell_type": "code",
+        "execution_count": None,
+        "metadata": {},
+        "outputs": [],
+        "source": src,
+    }
+
+
+def _markdown_cell(src: str | list[str]) -> dict[str, Any]:
+    if isinstance(src, str):
+        src = src.splitlines(keepends=True)
+    return {
+        "cell_type": "markdown",
+        "metadata": {},
+        "source": src,
+    }
+
+
+def build_notebook(
+    *,
+    cells: list[dict[str, Any]],
+    gpu: NotebookGPU = "T4",
+    title: str = "bindsight job",
+) -> dict[str, Any]:
+    """Return a Jupyter v4 notebook dict with the given cells and Colab GPU runtime.
+
+    Pass the result to :func:`json.dumps` (or use :func:`write_notebook`) to
+    save as ``.ipynb``.
+    """
+    return {
+        "nbformat": 4,
+        "nbformat_minor": 0,
+        "metadata": {
+            "colab": {
+                "name": title,
+                "provenance": [],
+                "gpuType": gpu,
+                "machine_shape": "hm",
+            },
+            "kernelspec": {
+                "display_name": "Python 3",
+                "name": "python3",
+                "language": "python",
+            },
+            "accelerator": "GPU",
+            "language_info": {"name": "python"},
+        },
+        "cells": cells,
+    }
+
+
+def write_notebook(notebook: dict[str, Any], path: Path) -> Path:
+    """Write a notebook dict to ``path`` as JSON. Creates parent dirs."""
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(notebook, indent=1), encoding="utf-8", newline="\n")
+    return path
+
+
+def render_template(template_str: str, context: dict[str, Any]) -> str:
+    """Render a Jinja2 template string against ``context`` with strict undefined.
+
+    Strict-undefined means a missing variable raises immediately rather than
+    silently producing empty output — important when the template generates
+    code that will run on a remote GPU we can't easily debug.
+    """
+    env = Environment(
+        loader=BaseLoader(),
+        undefined=StrictUndefined,
+        autoescape=False,
+        trim_blocks=True,
+        lstrip_blocks=True,
+    )
+    return env.from_string(template_str).render(**context)
+
+
+def code_cell_from_template(template_str: str, context: dict[str, Any]) -> dict[str, Any]:
+    """Convenience: render a Jinja template and wrap as a code cell."""
+    return _code_cell(render_template(template_str, context))
+
+
+def markdown_cell(src: str | list[str]) -> dict[str, Any]:
+    """Public alias for the markdown cell constructor."""
+    return _markdown_cell(src)