BioAgent

An autonomous bioinformatics research agent — it plans, reads the literature, acquires real datasets, runs the analysis, and writes up publishable results.

BioAgent is a multi-agent system built on LangGraph that drives a full computational research loop end to end. An orchestrator routes between research phases — literature review, gap analysis, hypothesis generation, experiment design, data acquisition, code execution, validation, writing, and figure generation — while specialised agents and tool sets carry out each step.

It is designed for reproducibility: every run is checkpointed, every artifact is tracked with provenance, and configurable token/cost budgets keep long autonomous loops bounded.

---

✨ Features

• Phase-based orchestration — A research director agent decides the next phase from the current state, with loop-detection and forced forward-progression so the graph never gets stuck re-running a step.
• Multi-agent collaboration — Specialised agents for literature, planning, data acquisition, analysis, visualization, and writing, each driven by its own prompt.
• Real data acquisition — Downloads datasets from GEO, NCBI (Entrez/SRA), cBioPortal, GDC, ENCODE, and ENA, with Asia-friendly mirror fallback (EBI/ENA/10x CDN) and retry/backoff for flaky links.
• Code execution — Writes and runs bioinformatics code (sequence, genomic, expression analysis) inside a sandboxed executor with timeouts and iteration budgets.
• Publishable outputs — Exports results as LaTeX, Markdown, and BibTeX, with publication-quality figures.
• Provenance & checkpoints — SQLite checkpointing lets you resume any run; provenance tracking records the lineage of every result.
• Budgets & safety — Hard limits on tokens, estimated USD cost, iterations, and tool calls; optional human-in-the-loop approval before execution and submission.

---

🧠 Architecture

START
  │
  ▼
orchestrator ──► (phase node) ──► orchestrator ──► ... ──► review ──► END
                       ▲                                   │
                       │           (optional)              │
                       └──────── human approval gate ◄────┘

Agent / Node	Responsibility
orchestrator	Research director — routes to the next phase based on state
literature	Search and read papers, build a knowledge base
planner	Gap analysis, hypothesis generation, experiment design
data_acquisition	Fetch real datasets from public repositories
analyst	Write and execute analysis code
visualization	Generate publication-quality figures
writer	Draft paper sections (Abstract → Discussion)
review	Self-review the complete output for quality

The graph is defined in graph/research_graph.py; per-phase nodes live in graph/nodes.py and routing in graph/routing.py.

---

📦 Project structure

bioagent/
├── agents/            # LLM agents (orchestrator, planner, analyst, ...)
├── prompts/           # Markdown system prompts per agent
├── graph/             # LangGraph workflow: nodes, routing, build
├── tools/             # Tool sets: bioinformatics, data, literature, visualization
├── llm/               # LLM clients (Anthropic/OpenAI-compatible)
├── config/            # Pydantic-settings configuration
├── state/             # Research state schema and reducers
├── evaluation/        # Metrics & provenance
├── export/            # LaTeX / Markdown / BibTeX exporters
├── cli/               # `bioagent` command-line interface
└── utils/             # Logging, serialization

---

🚀 Getting started

Prerequisites

• Python 3.11+
• An Anthropic API key (or any OpenAI-compatible endpoint)

Install

git clone https://github.com/Nigmat-future/Bioagent.git
cd Bioagent
python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e .                                     # or pip install -r requirements.txt

Configure

BioAgent reads configuration from environment variables prefixed with BIOAGENT_ (or a .env file at the project root). It also falls back to ANTHROPIC_AUTH_TOKEN, ANTHROPIC_BASE_URL, and ANTHROPIC_MODEL, so it works out of the box inside Claude Code.

# .env
BIOAGENT_ANTHROPIC_API_KEY=sk-ant-...
BIOAGENT_NCBI_API_KEY=...            # optional, raises Entrez rate limits
BIOAGENT_PRIMARY_MODEL=claude-sonnet-4-5-20250929
BIOAGENT_TOKEN_BUDGET=500000
BIOAGENT_COST_BUDGET_USD=10.0

All API keys are read from the environment — none are committed to the repo.

Run

bioagent "Identify resistance mechanisms in pan-cancer immune checkpoint blockade cohorts and test on GSE163558"

---

⚙️ Configuration highlights

Setting	Default	Description
token_budget	500000	Max total tokens (input + output) per run
cost_budget_usd	10.0	Max estimated cost in USD per run
max_iterations	5	Max analysis retry iterations
max_tool_calls	20	Max tool calls per phase
human_in_loop	False	Enable human approval gates
prefer_mirrors	True	Prefer EBI/ENA/10x mirrors before NCBI
use_sqlite_checkpoints	True	Persist run state to resume later

---

🔒 Reproducibility

Every run is checkpointed to SQLite under checkpoints/ and a workspace tree is written under workspace/. Provenance records link each result back to the dataset, code, and prompt that produced it, so a full run can be audited or resumed at any phase.

---

📄 License

MIT © Nigmat Rahim