bindsight 0.3.5__py3-none-any.whl

bindsight/report/web/templates/try.html.j2

@@ -0,0 +1,155 @@
+{% extends "base.html.j2" %}
+{% block title %}Try it — bindsight{% endblock %}
+
+{% block content %}
+<h1>Try it</h1>
+<p class="lede">
+  The discovery half, end to end, on a real cohort. No GPU, no account, nothing
+  to configure.
+</p>
+
+<div class="card">
+  <h2 class="card__title">What this runs</h3>
+  <div class="grid grid--2">
+    {#- `.fact`, not `.stat`. A `.stat` is a measurement and must carry its
+        denominator or interval; these are descriptions, and borrowing the
+        figure component for them would make that rule unenforceable. -#}
+    {% for key, value in cohort.items() %}
+      <div class="fact">
+        <span class="fact__label">{{ key }}</span>
+        <span class="fact__value">{{ value }}</span>
+      </div>
+    {% endfor %}
+  </div>
+
+  <div class="btn-row">
+    <button class="btn btn--primary" id="start">Run the demo</button>
+  </div>
+
+  <!-- Announced, not just drawn. The run takes minutes on a cold cache and
+       every update happens without the focus moving, so without these a
+       screen-reader user hears nothing between pressing the button and giving
+       up. `polite` for progress, which is a running commentary; the outcome
+       node carries `role="status"` or `role="alert"` depending on which it
+       turns out to be. -->
+  <ol class="steps" id="steps" aria-live="polite" aria-atomic="false" hidden></ol>
+  <div id="outcome" aria-live="polite" aria-atomic="true"></div>
+</div>
+
+<div class="note note--info">
+  <span class="note__glyph" aria-hidden="true">i</span>
+  <div class="note__body">
+    <p class="small" style="margin:0">
+      Well-known antigens appear among the candidates when their signal is
+      present in the cohort. They are not guaranteed to: in whole unstratified
+      TCGA-BRCA, ERBB2 measures a log2 fold change below the filter, and the
+      study says so rather than quietly stratifying until it does not.
+    </p>
+  </div>
+</div>
+{% endblock %}
+
+{% block scripts %}
+<script>
+// Per-stage progress. A single indeterminate spinner cannot tell a reader
+// whether a run is slow or stuck, and on a cold cache this is minutes.
+//
+// Every value below comes from `/api/job/<id>`, whose `error` is `str(exc)`
+// from a bare `except` -- so it carries whatever text the pipeline raised,
+// including a design table's own column names. This built that into markup by
+// string concatenation, which is the defect fixed in `your_data_check.js` and
+// then missed here because the sweep that enforces the rule read `.js` files
+// and this script lives in a template. Nodes and textContent, same as there.
+const GLYPH = { pending: "\u25cb", running: "\u25d0", done: "\u2713", failed: "\u2717" };
+
+function el(tag, className) {
+  const node = document.createElement(tag);
+  if (className) node.className = className;
+  return node;
+}
+
+function note(kind, glyph, bodyNodes) {
+  const wrap = el("div", "note note--" + kind);
+  const mark = el("span", "note__glyph");
+  mark.setAttribute("aria-hidden", "true");
+  mark.textContent = glyph;
+  const body = el("div", "note__body");
+  bodyNodes.forEach(function (n) { body.appendChild(n); });
+  wrap.appendChild(mark);
+  wrap.appendChild(body);
+  return wrap;
+}
+
+function stepItem(s) {
+  const li = el("li");
+  li.setAttribute("data-state", s.state);
+  const glyph = el("span", "steps__glyph");
+  glyph.setAttribute("aria-hidden", "true");
+  glyph.textContent = GLYPH[s.state] || "";
+  const spoken = el("span", "visually-hidden");
+  spoken.textContent = " (" + s.state + ")";
+  li.appendChild(glyph);
+  li.appendChild(document.createTextNode(s.name));
+  li.appendChild(spoken);
+  return li;
+}
+
+document.getElementById("start").addEventListener("click", async function () {
+  const btn = this;
+  btn.disabled = true;
+  btn.textContent = "Running\u2026";
+  const outcome = document.getElementById("outcome");
+  outcome.innerHTML = "";
+  const steps = document.getElementById("steps");
+  steps.hidden = false;
+
+  const started = await fetch("/try/run", { method: "POST" });
+  const { job } = await started.json();
+
+  const poll = setInterval(async function () {
+    const res = await fetch("/api/job/" + job);
+    const state = await res.json();
+
+    steps.innerHTML = "";
+    state.stages.forEach(function (s) { steps.appendChild(stepItem(s)); });
+
+    if (state.state === "done" || state.state === "failed") {
+      clearInterval(poll);
+      btn.disabled = false;
+      btn.textContent = "Run it again";
+
+      let card;
+      if (state.state === "done") {
+        const line = el("p");
+        line.style.margin = "0";
+        const where = el("code");
+        where.textContent = String(state.run_dir);
+        const link = el("a");
+        link.href = "/runs";
+        link.textContent = "browse it";
+        line.appendChild(document.createTextNode("Complete. The run is in "));
+        line.appendChild(where);
+        line.appendChild(document.createTextNode(" \u2014 "));
+        line.appendChild(link);
+        line.appendChild(document.createTextNode("."));
+        card = note("ok", "\u2713", [line]);
+        card.setAttribute("role", "status");
+      } else {
+        const headline = el("p");
+        headline.style.margin = "0";
+        const strong = el("strong");
+        strong.textContent = "The demo did not finish.";
+        headline.appendChild(strong);
+        const detail = el("p", "small");
+        detail.style.margin = ".5rem 0 0";
+        // textContent: this is the one value an attacker can reach.
+        detail.textContent = String(state.error == null ? "" : state.error);
+        card = note("err", "\u2717", [headline, detail]);
+        card.setAttribute("role", "alert");
+      }
+      outcome.appendChild(card);
+    }
+  }, 700);
+});
+</script>
+{% endblock %}

bindsight/report/web/templates/your_data.html.j2

@@ -0,0 +1,46 @@
+{% extends "base.html.j2" %}
+{% block title %}Your data — bindsight{% endblock %}
+
+{% block content %}
+<h1>Your data</h1>
+<p class="lede">
+  A counts matrix and a sample design table naming a two-level factor. Nothing
+  on this path knows about cancer — <code>tumor</code> and <code>normal</code>
+  are values you supply, not values the code expects.
+</p>
+
+<div class="card">
+  <h2 class="card__title">Files</h3>
+  <div class="field">
+    <label for="counts">Counts matrix <span class="muted">(.tsv, .txt, .gz)</span></label>
+    <input type="file" id="counts" accept=".tsv,.txt,.gz">
+    <p class="field__help">Genes as rows, samples as columns, integer counts.</p>
+  </div>
+  <div class="field">
+    <label for="design">Sample design table <span class="muted">(.tsv, .txt, .gz)</span></label>
+    <input type="file" id="design" accept=".tsv,.txt,.gz">
+    <p class="field__help">One row per sample, with a column naming the condition.</p>
+  </div>
+
+  <div id="checks" aria-live="polite" aria-atomic="false"></div>
+</div>
+
+<div class="note note--info">
+  <span class="note__glyph" aria-hidden="true">i</span>
+  <div class="note__body">
+    <p class="small" style="margin:0">
+      Files are checked the moment you choose them — shape, separator, and
+      whether the sample names in the two tables agree. The contrast levels are
+      read from your design file and offered back to you, rather than typed: a
+      mistyped level used to surface as a generic pipeline failure minutes
+      later, after the cohort had already been processed.
+    </p>
+  </div>
+</div>
+{% endblock %}
+
+{% block scripts %}
+{#- The checker is bindsight/report/web/static/your_data_check.js, shared with
+    the published documentation site so the two cannot diverge. -#}
+<script src="/static/your_data_check.js"></script>
+{% endblock %}

bindsight/runners/__init__.py

@@ -0,0 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Mikhaeel Atef Rizk Wahba
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""GPU-runner abstraction (Colab / Modal / Kaggle / local Docker / mock)."""
+
+from bindsight.runners.protocol import CostEstimate, GPURunner, JobHandle, JobStatus
+
+__all__ = ["CostEstimate", "GPURunner", "JobHandle", "JobStatus"]

bindsight/runners/colab.py

@@ -0,0 +1,158 @@
+# SPDX-FileCopyrightText: 2026 Mikhaeel Atef Rizk Wahba
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Colab GPU runner.
+
+Colab is a free-or-cheap GPU on-ramp. bindsight doesn't have a way to *launch*
+a Colab notebook from the CLI (Google's API doesn't permit it for free-tier
+users), so the workflow is:
+
+1. ``submit()`` writes a self-contained ``.ipynb`` to disk and prints the
+   command for the user to open it in Colab.
+2. The notebook installs deps, runs the GPU step, tarballs results, writes
+   them to a known location (Google Drive folder, or anywhere the user can
+   download from).
+3. ``poll()`` checks whether ``results.tar.gz`` has appeared in the local
+   results directory (the user downloads it from Drive after the notebook
+   finishes).
+4. ``fetch()`` returns the local path once it's there.
+
+This is intentionally simple. v0.2 may add Drive API auto-fetch via OAuth;
+v0.0.x explicitly favors "user clicks two buttons in Colab" over "wire
+OAuth and fight rate limits".
+"""
+
+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.protocol import CostEstimate, JobHandle, JobStatus
+
+LOG = logging.getLogger(__name__)
+
+
+class ColabRunner:
+    """Local-disk Colab job orchestrator.
+
+    Args:
+        notebooks_dir: where templated ``.ipynb`` files are written. Default
+            is ``./runs/<run_id>/colab_notebooks/``.
+        designer: passed through to the cost estimator.
+        n_units_per_target: trajectories per design (used for cost estimate).
+        gpu_type: GPU to request from Colab (``T4`` for free, ``A100`` for Pro+).
+    """
+
+    name = "colab"
+
+    def __init__(
+        self,
+        notebooks_dir: Path | None = None,
+        *,
+        designer: str = "rfdiff_mpnn",
+        n_units_per_target: int = 50,
+        gpu_type: str = "T4",
+    ) -> None:
+        self.notebooks_dir = Path(notebooks_dir) if notebooks_dir else None
+        self.designer = designer
+        self.n_units_per_target = n_units_per_target
+        self.gpu_type = gpu_type
+
+    def estimate_cost(self, spec_size: int) -> CostEstimate:
+        """Estimate cost for ``spec_size`` design trajectories."""
+        return estimate(
+            backend=self.name,
+            stage="design",
+            plugin=self.designer,
+            n_units=spec_size,
+            gpu_type=self.gpu_type,
+        )
+
+    def submit(self, spec_path: Path, *, results_dir: Path) -> JobHandle:
+        """Write a Colab notebook + spec to disk, return a JobHandle.
+
+        The user is responsible for opening the notebook in Colab. The
+        ``handle.id`` is used as the cache key for results.
+        """
+        results_dir.mkdir(parents=True, exist_ok=True)
+        handle_id = str(uuid.uuid4())
+        notebook_dest = results_dir / f"{handle_id}.ipynb"
+
+        notebook = self._build_notebook(spec_path=spec_path, handle_id=handle_id)
+        notebook_dest.write_text(notebook, encoding="utf-8", newline="\n")
+
+        LOG.info(
+            "Colab notebook written to %s. Open it in Colab, run all cells, "
+            "and place the resulting %s.tar.gz in %s.",
+            notebook_dest,
+            handle_id,
+            results_dir,
+        )
+
+        return JobHandle(
+            backend=self.name,
+            id=handle_id,
+            submitted_at=datetime.now(UTC).isoformat(timespec="seconds"),
+            notebook_path=str(notebook_dest),
+            results_dir=str(results_dir),
+        )
+
+    def poll(self, handle: JobHandle) -> JobStatus:
+        """Check whether the user has placed the results tarball in the dir."""
+        results_dir = Path((handle.model_extra or {}).get("results_dir") or ".")
+        archive = results_dir / f"{handle.id}.tar.gz"
+        if archive.exists():
+            return JobStatus(handle=handle, state="succeeded", progress=1.0)
+        return JobStatus(
+            handle=handle,
+            state="running",
+            progress=None,
+            log_tail="awaiting results.tar.gz from Colab user",
+        )
+
+    def fetch(self, handle: JobHandle) -> Path:
+        """Return the local path to the results tarball.
+
+        Raises ``FileNotFoundError`` if the user hasn't dropped the tarball
+        in the configured results_dir yet — call :meth:`poll` first.
+        """
+        results_dir = Path((handle.model_extra or {}).get("results_dir") or ".")
+        archive = results_dir / f"{handle.id}.tar.gz"
+        if not archive.exists():
+            raise FileNotFoundError(
+                f"results tarball not yet available: {archive}. "
+                "Run the Colab notebook and place the output here."
+            )
+        return archive
+
+    # ---------------------------------------------------------------- #
+    # Notebook construction                                            #
+    # ---------------------------------------------------------------- #
+    def _build_notebook(self, *, spec_path: Path, handle_id: str) -> str:
+        """Build the design + validation notebook with REAL RFdiff+MPNN+Boltz cells.
+
+        Delegates to :mod:`bindsight.runners.notebook_content` which holds the
+        canonical install + inference cell templates patterned on ColabDesign,
+        dl_binder_design, and the upstream Boltz-2 README.
+        """
+        import json as _json  # local alias keeps it out of module init time
+
+        from bindsight.runners.notebook_content import build_design_notebook
+
+        spec: dict[str, Any] = {}
+        if Path(spec_path).exists():
+            try:
+                spec = _json.loads(Path(spec_path).read_text(encoding="utf-8"))
+            except _json.JSONDecodeError:
+                spec = {}
+
+        notebook = build_design_notebook(
+            handle_id=handle_id,
+            designer=self.designer,
+            gpu_type=self.gpu_type,
+            spec=spec,
+        )
+        return _json.dumps(notebook, indent=1)