BioScientist Agent System

An orchestration layer for agentic bioinformatics workflows that combines:

Dynamic MCP tool registration
Dual-mode reasoning (T1) and execution (V1)
Layered validation (E1) with Agent System integration
File-based shared memory for continual improvement

Why This Repository Exists

BioScientist/agent_system is designed to run practical computational biology tasks with a structured loop:

Propose hypotheses and strategies
Validate them with increasing rigor (L1 -> L4)
Capture execution evidence and insights
Reuse those insights for better next-round planning

This gives you a reproducible bridge between LLM reasoning, MCP tools, and real data artifacts.

Architecture Overview

Core Components

V1 Executor (engines/v1_executor.py)
- Pipeline-style task executor
- Routes tools through MCP servers
- Supports local and Docker backends
- Persists run artifacts and reports
T1 Consultant (engines/t1_consultant.py)
- Reflection and strategy engine
- Generates hypotheses (with data-grounded operations)
- Ranks hypotheses by historical success proxies
E1 Validator (engines/e1_validator.py)
- Multi-level validation engine:
  - L1: rule consistency
  - L2: Agent System/MCP readiness
  - L3: lightweight data-backed validation
  - L4: extended data-backed validation
- Calls Agent System runtime A1.go(...) when available
Shared Knowledge Space (shared_memory.py)
- File-based memory bridge across modules
- Stores experiment reports, hypotheses, validation reports, insights, and summary statistics
Orchestrator (orchestrator.py)
- Unified entrypoint wiring V1 + T1 + E1
- Exposes high-level modes like:
  - execute
  - consult
  - autopilot
  - hypothesis-generate
  - hypothesis-loop

Runtime Flow (Hypothesis Loop)

User Query
   |
   v
T1: generate + rank hypotheses
   |
   v
E1: optional MCP registration -> validation (L1/L2/L3/L4)
   |
   v
Agent System runtime (A1 + add_mcp + go) [when enabled/available]
   |
   v
Artifacts + Reports + Insights -> Shared Knowledge

Project Layout (Key Paths)

BioScientist/
├── agent_system/
│   ├── main.py
│   ├── orchestrator.py
│   ├── engines/
│   │   ├── v1_executor.py
│   │   ├── t1_consultant.py
│   │   └── e1_validator.py
│   ├── shared_memory.py
│   ├── toolbase/
│   │   ├── data/biomni_data/
│   │   └── register_mcp_servers_to_biomni.py
│   └── results/
└── README.md

Environment Setup (Required)

Our software environment is large. We provide a single setup script to bootstrap dependencies.

1) Activate the E1 environment first

conda activate biomni_e1

2) Install the official pip package first

pip install biomni --upgrade

3) Run the unified setup script

# from the repository root
bash setup.sh

4) (Optional, recommended) Install the latest Biomni from source

pip install git+https://github.com/snap-stanford/Biomni.git@main

Quick Start: Hypothesis Loop (Single-Cell Normalization)

1) Set Environment Variables

Use your current setup pattern:

export GEMINI_API_KEY="<YOUR_GEMINI_API_KEY>"
export T1_MODEL_BACKEND="gemini"
export GEMINI_MODEL="gemini-2.5-flash-lite"
export GEMINI_TEMPERATURE="0.2"
export GEMINI_TIMEOUT_SECONDS="60"
export BIOMNI_PATH=/225040511/project/Biomni/data
export BIOMNI_SOURCE="Gemini"

Optional (recommended for explicit control):

export BIOCLAW_BIOMNI_ROOT=/225040511/project/BioScientist/agent_system/engines/v1_executor_backup

2) Run the End-to-End Loop

python -m agent_system.main \
  --project_root /225040511/project/BioScientist \
  hypothesis-loop \
  --task_scope single_cell_normalization \
  --user_query "Give me new ideas for normalizing single-cell data" \
  --n 2 \
  --top_k 1 \
  --validate_top_m 1 \
  --validation_level L4 \
  --register_mcp true

3) Where to Find Outputs

Loop-level result:
- agent_system/results/hypothesis-loop_<timestamp>.json
Validation runtime reports:
- agent_system/results/e1_runtime/*.json
Data-backed L3/L4 artifacts:
- agent_system/results/l3_reports/*.json
- agent_system/results/l4_reports/*.json
Agent System execution payloads:
- agent_system/results/biomni_exec/*.json

Other CLI Modes

Generate hypotheses only

python -m agent_system.main \
  --project_root /225040511/project/BioScientist \
  hypothesis-generate \
  --task_scope single_cell_normalization \
  --user_query "Give me new ideas for normalizing single-cell data" \
  --n 10 \
  --top_k 5

Register MCP servers only

python -m agent_system.main \
  --project_root /225040511/project/BioScientist \
  register-mcp

Consult mode (strategy only)

python -m agent_system.main \
  --project_root /225040511/project/BioScientist \
  consult \
  --task_scope single_cell_normalization \
  --user_goal "Design a robust normalization strategy for cross-batch scRNA-seq."

Notes and Troubleshooting

If Agent System runtime returns API/provider errors (for example region restrictions), E1 may return inconclusive even when local data checks succeed.
L3/L4 still produce useful tabular evidence (rows_scanned, missing_rate, numeric summaries, relevance scores).
If you want fully offline execution, switch to a local model source (for example Ollama) and update relevant environment variables.
Large MCP sets are automatically reduced in E1 probe mode via minimal config generation for faster startup.

Status Semantics

success: validation/execution reached expected criteria
inconclusive: partial evidence available but one or more critical external/runtime checks failed
failed: contradiction or hard runtime failure detected

License

This repository is released under the MIT License (see LICENSE).