Metadata-Version: 2.5
Name: bionexuslab
Version: 0.1.0
Summary: Lean open-source framework for agentic drug discovery — pluggable models, bio tools, labs, and sandboxes behind five core interfaces.
License: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: pydantic>=2.5
Provides-Extra: bio-rdkit
Requires-Dist: rdkit>=2023.9; extra == 'bio-rdkit'
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Provides-Extra: lab-imaging
Requires-Dist: numpy>=1.24; extra == 'lab-imaging'
Provides-Extra: models-openai
Requires-Dist: httpx>=0.27; extra == 'models-openai'
Provides-Extra: sandbox-agentenv
Requires-Dist: httpx>=0.27; extra == 'sandbox-agentenv'
Provides-Extra: store-postgres
Requires-Dist: psycopg[binary]>=3; extra == 'store-postgres'
Description-Content-Type: text/markdown

# 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)

```sh
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`](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:

```sh
.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`](docs/virtual-lab.md).

**CLI:**

```sh
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:

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

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

**Tutorials:** [`notebooks/`](notebooks/) — run a campaign · write an adapter · bring your own model.

**Extend it:**

```sh
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`](docs/ADAPTERS.md) and the
[stability policy](docs/stability.md) — the five core interfaces are stable
surfaces with additive-evolution guarantees.

| Doc | Contents |
|---|---|
| [`docs/QUICKSTART.md`](docs/QUICKSTART.md) | install, run, workflows |
| [`docs/ADAPTERS.md`](docs/ADAPTERS.md) | authoring adapters (labs, models, tools, stores) |
| [`docs/SAFETY.md`](docs/SAFETY.md) | safety rules, LabGateway, audit trail |
| [`docs/domain-review.md`](docs/domain-review.md) | flow fidelity review vs. the real drug-discovery cycle |
| [`docs/benchmarks.md`](docs/benchmarks.md) | public datasets (MoleculeNet, TDC, DOCKSTRING, ProteinGym) + first benchmark results |
| [`docs/virtual-lab.md`](docs/virtual-lab.md) | simulated devices, image-based readouts, QC and failure modes |
| [`docs/security.md`](docs/security.md) | threat model, trust boundaries, agent capability matrix |
| [`docs/stability.md`](docs/stability.md) | versioning, stability tiers, deprecation policy |
| [`docs/PLAN.md`](docs/PLAN.md) | build plan, principles, guardrails |

### Five core interfaces (everything is one of these)

| Interface | Adapters (now → roadmap) |
|---|---|
| `ModelProvider` | openai_compat (OpenAI/ollama/vLLM/stub) → anthropic, gemini |
| `LabAdapter` (+ `SafetyEngine`, `LabGateway`) | simulator, imaging-simulator (synthetic plate images + analysis + Z' QC) → opentrons, cloud labs |
| `Sandbox` | local (copy-on-fork) → AgentENV (real fork/snapshot) |
| `ProvenanceStore` | sqlite → postgres, s3-worm |
| `BioTool` | rdkit descriptors → docking, ADMET, ESMFold |

## 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.

![Layered View](diagrams/svg/01-layered-view.svg)

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

![Design Iteration Loop](diagrams/svg/02-iteration-loop.svg)

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

![Hypothesis Tournament](diagrams/svg/03-tournament.svg)

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

![Wet-Lab Round Trip](diagrams/svg/04-wetlab-roundtrip.svg)

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

![Fork / Snapshot Branching](diagrams/svg/05-branching.svg)

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

![Campaign Pipeline](diagrams/svg/06-campaign.svg)

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

## Repository Layout

| Path | Contents |
|---|---|
| [`docs/architecture.md`](docs/architecture.md) | Architectural blocks A–F, components, responsibilities, interfaces |
| [`docs/flows.md`](docs/flows.md) | End-to-end flows: design iteration loop, fork/branch, review gates, wet-lab round trip |
| [`docs/blocks/`](docs/blocks/) | One deep-dive doc per block (A–F) |
| [`docs/research-landscape.md`](docs/research-landscape.md) | Review vs. Google AI co-scientist, Anthropic, Isomorphic, Cradle, Lila, FutureHouse, Coscientist, OpenAI Rosalind |
| [`contracts/`](contracts/README.md) | The five shared integration contracts (StageTask, ToolInvocation, ProtocolSubmission, AssayResult, ProvenanceRecord) |
| [`diagrams/`](diagrams/) | SVG diagrams + styled HTML artifact pages |

## Architectural Blocks at a Glance

| Block | Name | Layer | Can start with |
|---|---|---|---|
| [A](docs/blocks/A-orchestration.md) | Workflow & Orchestration | L1 | stub tool endpoints |
| [B](docs/blocks/B-agents.md) | Agent Workforce | L2 | virtual lab + mocked models |
| [C](docs/blocks/C-models-knowledge.md) | Model & Knowledge Services | L2 | open-source FMs on a GPU box |
| [D](docs/blocks/D-lab-execution.md) | Lab Execution | L2/L3 | full virtual lab simulator |
| [E](docs/blocks/E-simulation-data.md) | Simulation & Data Services | L2 | existing MD/docking tools |
| [F](docs/blocks/F-infrastructure.md) | Infrastructure (AgentENV) | L3 | exists — integrate |

## 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`](docs/research-landscape.md).

**Key sources:**

- Google — [AI co-scientist](https://research.google/blog/accelerating-scientific-breakthroughs-with-an-ai-co-scientist/) ([paper](https://arxiv.org/abs/2502.18864)) · [AlphaFold 3](https://www.nature.com/articles/s41586-024-07487-w) · [Isomorphic Labs Drug Design Engine](https://www.isomorphiclabs.com/articles/the-isomorphic-labs-drug-design-engine-unlocks-a-new-frontier) · [Bioresilience approach](https://www.isomorphiclabs.com/articles/our-approach-to-bioresilience)
- Anthropic — [Claude for Life Sciences](https://www.anthropic.com/news/claude-for-life-sciences) · [Model Hardware Standard](https://www.anthropic.com/news/model-hardware-standard-research-preview)
- Cradle Bio — [Platform](https://www.cradle.bio/platform) · [Series B / wet-lab expansion](https://techcrunch.com/2024/11/26/cradle-builds-out-its-protein-design-ai-platform-and-wet-lab-with-73m-in-new-funding/)
- FutureHouse — [Robin multi-agent system](https://www.futurehouse.org/research-announcements)
- Lila Sciences — [Agent-driven science on NVIDIA BioNeMo](https://www.lilasciences.com/news/building-the-agent-driven-era-of-science-with-nvidia-bionemo-agent-toolkit)
- Helical — [Virtual AI lab / Helix-mRNA FM](https://www.helical.bio/)
- Coscientist (CMU) — [Autonomous chemical research with LLMs + robotics, Nature 2023](https://www.nature.com/articles/s41586-023-06792-0)
- OpenAI + Retro Biosciences — [GPT-4b micro protein engineering, MIT Tech Review](https://www.technologyreview.com/2024/12/09/1108188/openai-model-for-protein-engineering-gpt-4b-micro-retro-biosciences/)
- Chai Discovery — [chai-1/chai-2 structure & antibody models](https://www.chaidiscovery.com/)
