The workbench.
A reactive planner that chooses its next move from what the run has learned, a typed tool registry it chooses from, and a live notebook kernel where the analysis actually happens. This is the machinery behind a Science run.
§ 01The reactive loop
A Science run is not a fixed pipeline. It is a loop: read the current state, select the next tool, run it, fold the result back into state, decide whether to continue. The selector reads a compact state brief — the hypothesis, the current posterior, what has been retrieved, what remains unresolved — and picks the action with the best expected information gain for its cost.
Each registered tool declares what it needs and what it produces (requires_state, produces_state) plus a cost hint covering estimated tokens, wall time, and external calls. The selector uses those declarations, so a tool that cannot contribute yet is never chosen, and an expensive tool has to earn its slot.
BIOMED_PLANNER_LOOP). Turning it off falls back to the legacy linear runner, which is retained for compatibility rather than parity — the workbench described here assumes the loop.Forced reflection
Left alone, any agent loop will confirm itself. Every K iterations the loop is required to step out of execution and reflect — reflect.step_back, reflect.steelman_opposite, reflect.what_would_change_my_mind. The cadence tightens with depth: every four iterations on scan, every three on deep_dive, every two on exhaustive. Deeper runs are more suspicious of themselves, not less.
The scratchpad
Working memory for the run. The loop reads and writes it through a dedicated tool, and every write is streamed as a biomed.scratchpad.patch event, so the notes the run keeps for itself are visible while it works rather than reconstructed afterwards.
Stop conditions
Each run carries explicit ceilings — maximum iterations, wall seconds, and total tokens — clamped against the caps for its depth mode. A plan cannot request more headroom than its mode allows.
§ 02The tool registry
Retrieval tools reach the databases; skills and compute tools do the work. The full roster of connectors behind these is in Data sources.
| Tool | What it does |
|---|---|
| biomed.search_literature | Search the enabled literature connectors and record the hits. |
| biomed.fetch_sequence | Protein and gene records from UniProt and Ensembl, by accession or gene symbol. |
| biomed.fetch_structure | 3D structures from the RCSB PDB and AlphaFold DB; emits viewable structure artifacts. |
| biomed.query_clinical | Registered trials on the topic from ClinicalTrials.gov. |
| biomed.query_pathways | Curated pathways for a gene, molecule, or process (Reactome). |
| biomed.query_variants | Clinical significance of germline and somatic variants (ClinVar). |
| biomed.fetch_expression | Public gene-expression datasets and series, bulk and single-cell (GEO). |
| biomed.rank_targets | Target ↔ disease associations ranked by score (Open Targets). |
| biomed.run_skill | Run a computational-biology skill — see below. |
| biomed.build_model | Build an interactive 3D model artifact from a structure, a sequence, or coordinates. |
| biomed.design_protein | Inverse-fold a target backbone into candidate sequences. |
| biomed.notebook_exec | Execute a Python cell in the run's persistent kernel. |
Alongside these sit the analysis and reflection families the planner draws on: meta-analysis and pooled effects, sensitivity and causal analysis, Bayesian updating, preregistration, multiverse specification curves, replication search, cross-source triangulation, pattern analysis, information-gain estimation, ledger lookups, and synthesis. Their behaviour is documented in Verification.
Skills
| Skill | Provides |
|---|---|
| sequence_tools | GC content, translation, ORF finding, and pairwise alignment (Biopython). |
| single_cell_qc | scverse-style single-cell RNA-seq QC — per-cell metrics with MAD outlier flagging. |
§ 03The notebook kernel
The kernel is stateful and scoped to one run: a namespace assigned in cell one is still there in cell nine. That is what makes the analysis cumulative rather than a series of disconnected snippets — load a GEO series once, then keep working on it.
Available libraries cover the analysis surface the engine needs: numpy, scipy, pandas, networkx, and Biopython, with scanpy and anndata loaded lazily for single-cell work.
# cell 1
import pandas as pd
effects = pd.DataFrame(pooled_effects)
effects.describe()
# cell 2 — `effects` is still bound
effects.groupby("study_design")["hedges_g"].agg(["mean", "count"])Cells can be run programmatically as well as by the planner:
What the kernel will not do
Persistence adds a retained namespace and nothing else — it does not relax validation. Every cell passes the same static AST validator used by the stateless sandbox before it executes: no underscore or dunder access, no escape-enabling builtins, no open, eval, exec, or getattr, an import safelist, and a thread plus wall-clock timeout. The safelist is wider than the stateless sandbox's — it has to include the data-science libraries — but those are compute libraries, not network or subprocess capabilities.
The sandboxed shell
On deep_dive and exhaustive, the loop also gets a constrained bash sandbox for work the typed tools do not cover — pulling a specific paper by ID, running jq over state files, grepping a literature pool, reshaping a CSV. Each command runs in its own subprocess with resource limits applied before exec: CPU time, address space, per-file size, and open file descriptors are all capped, so a bad command's blast radius stays small. It is off in scan, where a single call would consume the entire budget.
§ 04Structures and design
biomed.build_model produces an interactive 3D artifact — rotate, zoom, label, click — from any of several starting points:
- A PDB id, fetched from the RCSB PDB.
- A UniProt accession, resolved to its AlphaFold prediction.
- A raw amino-acid sequence, folded de novo with ESMFold.
- A nucleotide sequence, rendered as a B-DNA double helix.
- Inline PDB coordinates.
biomed.design_protein runs the inverse problem: given a target backbone — a PDB id, an accession, a sequence folded first to get a backbone, or inline coordinates — it returns candidate sequences predicted to fold to that shape, and folds the top design so you can see it.
BIO_HUB_API_KEY enables inverse folding for protein design and provides a more reliable folding fallback.§ 05Reading a run
Because every step is a declared tool call against declared state, a finished run reads as a sequence rather than a black box: the tool chosen, why it was chosen, what it returned, and how the posterior moved. Timelines and sources for a run are retrievable after the fact — see Run timelines for the shared platform surface.