BioNexus

A lean open-source framework for agentic drug discovery — pluggable models, bio tools, labs, and sandboxes behind five core interfaces.

Core dependencies: pydantic only. Everything else (models, labs, sandboxes, stores) is an adapter you opt into.

Quickstart (simulator-first, no network needed)

python -m venv .venv && .venv/bin/pip install -e . dev-dependencies...  # see pyproject
.venv/bin/pip install -e ".[dev]"
.venv/bin/python examples/iteration_loop.py   # full design round on the virtual lab
.venv/bin/python -m pytest                    # 11 tests, <1s, offline

The example runs: candidate generation → hypothesis tournament → human-approvable protocol → safety engine → virtual wet lab → fork branch → safety rejection demo → hash-chained provenance. See docs/PLAN.md for the full build plan.

Simulated lab devices with image readouts

The virtual lab goes one level deeper: a simulated imaging plate reader. A protocol run captures raw fluorescence micrographs per well (96-well plate), an analysis pipeline fits dose–response IC50s from the images, and assay QC is a Z' factor computed from controls. Measured IC50s recover the seeded ground truth within realistic noise, and the raw well images are kept as evidence that agents (or vision-capable LLMs) can inspect:

.venv/bin/pip install numpy                       # [lab-imaging] extra
.venv/bin/python examples/demo_imaging.py
# run img-c2f0183b: Z'=0.938 (controls PASS)
#   compound    measured IC50   ground truth
#   C2              11.98 uM      10.85 uM
# raw evidence: 14 well images in .data/images/

Failure modes are simulated too: well artifacts (pipetting spikes, bubbles, edge effects) are flagged, weak compounds are right-censored (no IC50 — test higher concentrations), and runs failing Z' QC are marked unusable. See docs/virtual-lab.md.

CLI:

bn run examples/workflow.yml       # tournament + assay on the configured lab
bn sim                             # reference round on the virtual lab
bn prove <branch> --html out.html  # tamper-evident provenance + shareable report
bn mcp                             # MCP server: drive BioNexus from Claude/Cursor

Works with Claude / Cursor / any MCP client — add to your MCP config:

{"bionexus": {"command": "bn", "args": ["mcp"]}}

Exposes generate_candidates, run_assay (dose-response + IC50), propose_hypothesis, and list_lab_capabilities as agent tools.

Tutorials: notebooks/ — run a campaign · write an adapter · bring your own model.

Extend it:

bn new-adapter lab my_robot      # scaffold a tested LabAdapter in seconds
bn new-adapter tool my_docking --cap e.sim.docking

See docs/ADAPTERS.md and the stability policy — the five core interfaces are stable surfaces with additive-evolution guarantees.

Five core interfaces (everything is one of these)

Architecture Diagrams

Hand-drawn blueprint-style diagrams (SVG — rendered directly on GitHub):

1 · Layered View — L0 governance → L3 infrastructure, with the five architectural blocks between.

2 · Design Iteration Loop — one active-learning round, from dossier to next-round proposals.

3 · Hypothesis Tournament — Generate → Reflect → Rank → Evolve, plus the fine-tuning flywheel.

4 · Wet-Lab Round Trip — protocol through the safety boundary, instruments, and back as provenance.

5 · Fork / Snapshot Branching — sandbox lifecycle as experiment tree.

6 · Campaign Pipeline — target ID through trial design with human gates and failure loops.

Styled HTML versions (dark blueprint pages with legends/captions) live in diagrams/artifacts/ — open locally in a browser.

Repository Layout

Architectural Blocks at a Glance

Design Principles

1. Contract-first integration — blocks communicate only through five versioned schemas; nothing else couples them.
2. Hardware behind an abstraction — agents see the Instrument Abstraction Layer (IAL) only; a Virtual Lab Simulator is a drop-in stand-in for real robots.
3. State is snapshot-able — every experiment branch runs in a sandbox that can be forked, paused at review gates, and replayed for audits.
4. Provenance is immutable — every artifact carries full lineage (inputs, model versions, prompts, instrument run IDs) in WORM storage.
5. Safety is non-bypassable — a policy engine sits in the physical-action path, outside any agent's trust boundary.

References & Sources

The architecture draws on published work from teams operating in this space. The full review — what each system does, how it compares, and which learnings were folded into this design — is in docs/research-landscape.md.

Key sources:

• Google — AI co-scientist (paper) · AlphaFold 3 · Isomorphic Labs Drug Design Engine · Bioresilience approach
• Anthropic — Claude for Life Sciences · Model Hardware Standard
• Cradle Bio — Platform · Series B / wet-lab expansion
• FutureHouse — Robin multi-agent system
• Lila Sciences — Agent-driven science on NVIDIA BioNeMo
• Helical — Virtual AI lab / Helix-mRNA FM
• Coscientist (CMU) — Autonomous chemical research with LLMs + robotics, Nature 2023
• OpenAI + Retro Biosciences — GPT-4b micro protein engineering, MIT Tech Review
• Chai Discovery — chai-1/chai-2 structure & antibody models