BioScientist/README.md

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

1. Propose hypotheses and strategies
2. Validate them with increasing rigor (L1 -> L4)
3. Capture execution evidence and insights
4. 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)

```text
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)

```text
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

```bash
conda activate biomni_e1
```

### 2) Install the official pip package first

```bash
pip install biomni --upgrade
```

### 3) Run the unified setup script

```bash
# from the repository root
bash setup.sh
```

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

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

```bash
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):

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

### 2) Run the End-to-End Loop

```bash
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

```bash
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

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

### Consult mode (strategy only)

```bash
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`).