# ryanwangzf/biodsa architecture

> Architecture diagram of the GitHub repository ryanwangzf/biodsa, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ryanwangzf/biodsa
- Repository: https://github.com/ryanwangzf/biodsa

## Overview

#### Purpose and entry points
BioDSA is a Python framework for building and running LLM-driven biomedical research agents. Primary programmatic entry is the agent package, especially `biodsa/agents/base_agent.py`, with runnable examples in `scripts/run_dswizard_agent.py`, `scripts/run_deepevidence_agent.py`, and `scripts/run_react_agent.py`. Users instantiate an agent, optionally register a local workspace, then call its execution method to obtain structured results and artifacts.

#### Agent foundation and workflow model
`BaseAgent` centralizes model configuration, execution lifecycle, retries, and result handling; shared agent state and LLM configuration are in `biodsa/agents/state.py` and `biodsa/agents/llm_config.py`. Agent implementations model workflows as LangGraph-style state graphs, separating:
- prompts and decision policy,
- typed/shared workflow state,
- tool registration and invocation,
- graph nodes and conditional transitions.
The generic ReAct pattern is represented by `biodsa/agents/react_agent.py`; code-oriented execution is supported by `biodsa/agents/coder_agent.py`.

#### Specialized agent layer
Published agents are independently packaged workflow applications over the shared foundation. Important architectural variants include:
- DSWizard’s planning-to-implementation data-analysis flow: `biodsa/agents/dswizard/agent.py`, `biodsa/agents/dswizard/analysis_plan_tool.py`.
- DeepEvidence’s hierarchical research orchestration and execution graph: `biodsa/agents/deepevidence/agent.py`, `biodsa/agents/deepevidence/execution.py`, `biodsa/agents/deepevidence/schema.py`.
- Clinical/literature pipelines such as `biodsa/agents/trialgpt/agent.py`, `biodsa/agents/trialmind_slr/agent.py`, and `biodsa/agents/informgen/agent.py`.
- Collaborative or verification-oriented designs: `biodsa/agents/virtuallab/participant.py`, `biodsa/agents/geneagent/agent.py`, and `biodsa/agents/agentmd/agent.py`.

Each agent owns its prompt, state, and tools, limiting cross-agent coupling while retaining common execution infrastructure.

#### Biomedical knowledge access boundary
Low-level clients and domain operations live under `biodsa/tools/`; agents should access them through LangChain-compatible adapters in `biodsa/tool_wrappers/`. This boundary keeps API-specific request/response behavior separate from LLM tool schemas and orchestration. Representative integrations include literature retrieval (`biodsa/tools/pubmed/pubmed_api.py`), trials (`biodsa/tools/clinical_trials/trials.py`), drug/target evidence (`biodsa/tools/chembl/client.py`, `biodsa/tools/opentargets/client.py`), and biological annotation (`biodsa/tools/ensembl/client.py`, `biodsa/tools/uniprot/client.py`). Unified search modules normalize cross-source entity lookup, e.g. `biodsa/tools/genes/unified_gene_search.py` and `biodsa/tools/diseases/unified_disease_search.py`.

#### Execution, artifacts, and memory
Potentially unsafe analysis code is isolated behind the sandbox abstraction in `biodsa/sandbox/sandbox_interface.py` and `biodsa/sandbox/execution.py`; the Python runtime image is defined in `biodsa_env/python_sandbox/Dockerfile`. This is the principal trust boundary between agent-generated code and the host environment. Execution returns structured traces, generated files, and reportable outputs. Persistent/retrievable research context is modeled as a graph with BM25 indexing in `biodsa/memory/memory_graph/graph.py`, `biodsa/memory/memory_graph/bm25_index.py`, and exposed as a tool via `biodsa/memory/memory_graph/tool.py`.

#### Runtime, external dependencies, and evaluation
The runtime is Python with dependencies locked in `Pipfile.lock`; API credentials are environment-driven through `.env.example`. Supported LLM providers include OpenAI, Anthropic, Azure OpenAI, and Google. External biomedical services include PubMed/NCBI, ClinicalTrials.gov, ChEMBL, Open Targets, Ensembl, UniProt, Reactome, PubChem, UMLS, and related sources represented under `biodsa/tools/`.

Benchmark datasets are repository assets rather than a serving subsystem: `benchmarks/BioDSA-1K/dataset/biodsa_1k_hypothesis.parquet`, `benchmarks/BioDSBench-Python/dataset/python_tasks_with_class.jsonl`, and `benchmarks/TrialPanoramaBench/evidence_synthesis_50.csv`. Local cBioPortal example data under `biomedical_data/cBioPortal/datasets/acbc_mskcc_2015/` supports workspace-based analysis workflows.

Main entry points: [`biodsa/agents/base_agent.py`](https://github.com/ryanwangzf/biodsa/blob/main/biodsa/agents/base_agent.py) (BaseAgent), [`biodsa/agents/dswizard/agent.py`](https://github.com/ryanwangzf/biodsa/blob/main/biodsa/agents/dswizard/agent.py) (DSWizard), [`biodsa/sandbox/execution.py`](https://github.com/ryanwangzf/biodsa/blob/main/biodsa/sandbox/execution.py) (Sandbox execution), [`biodsa/sandbox/sandbox_interface.py`](https://github.com/ryanwangzf/biodsa/blob/main/biodsa/sandbox/sandbox_interface.py) (Sandbox interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agents["Agent framework"]
  node_base_agent["BaseAgent<br/>agent lifecycle<br/>[base_agent.py]"]
  node_agent_state["State and LLM config<br/>shared models<br/>[state.py]"]
  node_react_coder["ReAct and coder agents<br/>workflow patterns<br/>[react_agent.py]"]
end

subgraph group_specialized["Published workflows"]
  node_dswizard["DSWizard<br/>analysis workflow<br/>[agent.py]"]
  node_deepevidence["DeepEvidence<br/>research workflow<br/>[agent.py]"]
  node_clinical_agents["Clinical and literature agents<br/>workflow applications<br/>[agent.py]"]
  node_collaborative_agents["Collaborative and verification agents<br/>workflow applications<br/>[participant.py]"]
end

subgraph group_knowledge["Knowledge access"]
  node_tool_wrappers{{"Tool wrappers<br/>LangChain adapters"}}
  node_biomedical_tools["Biomedical clients<br/>domain integrations"]
  node_unified_search["Unified gene search<br/>entity normalization"]
  node_external_services(("Biomedical services<br/>external APIs"))
end

subgraph group_runtime["Execution and memory"]
  node_sandbox{{"Sandbox interface<br/>trust boundary"}}
  node_sandbox_execution["Sandbox execution<br/>code runner<br/>[execution.py]"]
  node_sandbox_image["Python sandbox image<br/>Docker runtime"]
  node_memory[("Research memory graph<br/>persistent context<br/>[graph.py]")]
  node_memory_tool["Memory tool<br/>agent tool<br/>[tool.py]"]
end

node_entry["Runnable examples<br/>Python scripts"]
node_artifacts["Structured results and artifacts<br/>execution output"]
node_benchmarks[("Benchmark datasets<br/>repository assets")]

node_entry -->|"runs"| node_base_agent
node_base_agent -->|"uses"| node_agent_state
node_base_agent -->|"supports"| node_react_coder
node_base_agent -->|"foundation for"| node_dswizard
node_base_agent -->|"foundation for"| node_deepevidence
node_base_agent -->|"foundation for"| node_clinical_agents
node_base_agent -->|"foundation for"| node_collaborative_agents
node_dswizard -->|"invokes"| node_tool_wrappers
node_deepevidence -->|"invokes"| node_tool_wrappers
node_clinical_agents -->|"invokes"| node_tool_wrappers
node_collaborative_agents -->|"invokes"| node_tool_wrappers
node_tool_wrappers -->|"adapts"| node_biomedical_tools
node_biomedical_tools -->|"includes"| node_unified_search
node_biomedical_tools -->|"queries"| node_external_services
node_dswizard -->|"executes code in"| node_sandbox
node_react_coder -->|"executes code in"| node_sandbox
node_sandbox -->|"delegates to"| node_sandbox_execution
node_sandbox_execution -->|"runs in"| node_sandbox_image
node_sandbox_execution -->|"produces"| node_artifacts
node_base_agent -.->|"can register"| node_memory_tool
node_memory_tool -->|"retrieves and persists"| node_memory
node_base_agent -->|"returns"| node_artifacts
node_benchmarks -.->|"evaluates"| node_dswizard

click node_entry "https://github.com/ryanwangzf/biodsa/blob/main/scripts/run_dswizard_agent.py"
click node_base_agent "https://github.com/ryanwangzf/biodsa/blob/main/biodsa/agents/base_agent.py"
click node_agent_state "https://github.com/ryanwangzf/biodsa/blob/main/biodsa/agents/state.py"
click node_react_coder "https://github.com/ryanwangzf/biodsa/blob/main/biodsa/agents/react_agent.py"
click node_dswizard "https://github.com/ryanwangzf/biodsa/blob/main/biodsa/agents/dswizard/agent.py"
click node_deepevidence "https://github.com/ryanwangzf/biodsa/blob/main/biodsa/agents/deepevidence/agent.py"
click node_clinical_agents "https://github.com/ryanwangzf/biodsa/blob/main/biodsa/agents/trialgpt/agent.py"
click node_collaborative_agents "https://github.com/ryanwangzf/biodsa/blob/main/biodsa/agents/virtuallab/participant.py"
click node_unified_search "https://github.com/ryanwangzf/biodsa/blob/main/biodsa/tools/genes/unified_gene_search.py"
click node_sandbox "https://github.com/ryanwangzf/biodsa/blob/main/biodsa/sandbox/sandbox_interface.py"
click node_sandbox_execution "https://github.com/ryanwangzf/biodsa/blob/main/biodsa/sandbox/execution.py"
click node_sandbox_image "https://github.com/ryanwangzf/biodsa/blob/main/biodsa_env/python_sandbox/Dockerfile"
click node_memory "https://github.com/ryanwangzf/biodsa/blob/main/biodsa/memory/memory_graph/graph.py"
click node_memory_tool "https://github.com/ryanwangzf/biodsa/blob/main/biodsa/memory/memory_graph/tool.py"
click node_benchmarks "https://github.com/ryanwangzf/biodsa/blob/main/benchmarks/BioDSA-1K/dataset/biodsa_1k_hypothesis.parquet"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_base_agent,node_agent_state,node_react_coder toneBlue
class node_dswizard,node_deepevidence,node_clinical_agents,node_collaborative_agents toneAmber
class node_tool_wrappers,node_biomedical_tools,node_unified_search,node_external_services toneMint
class node_sandbox,node_sandbox_execution,node_sandbox_image,node_memory,node_memory_tool toneRose
class node_entry,node_artifacts,node_benchmarks toneNeutral
```

## Components

### Agent framework

- [BaseAgent](https://github.com/ryanwangzf/biodsa/blob/main/biodsa/agents/base_agent.py): agent lifecycle · Centralizes model setup, retries, execution, and results. · `biodsa/agents/base_agent.py`
- [State and LLM config](https://github.com/ryanwangzf/biodsa/blob/main/biodsa/agents/state.py): shared models · `biodsa/agents/state.py`
- [ReAct and coder agents](https://github.com/ryanwangzf/biodsa/blob/main/biodsa/agents/react_agent.py): workflow patterns · `biodsa/agents/react_agent.py`

### Published workflows

- [DSWizard](https://github.com/ryanwangzf/biodsa/blob/main/biodsa/agents/dswizard/agent.py): analysis workflow · Plans and implements data-analysis tasks. · `biodsa/agents/dswizard/agent.py`
- [DeepEvidence](https://github.com/ryanwangzf/biodsa/blob/main/biodsa/agents/deepevidence/agent.py): research workflow · Hierarchical research orchestration and execution. · `biodsa/agents/deepevidence/agent.py`
- [Clinical and literature agents](https://github.com/ryanwangzf/biodsa/blob/main/biodsa/agents/trialgpt/agent.py): workflow applications · `biodsa/agents/trialgpt/agent.py`
- [Collaborative and verification agents](https://github.com/ryanwangzf/biodsa/blob/main/biodsa/agents/virtuallab/participant.py): workflow applications · `biodsa/agents/virtuallab/participant.py`

### Knowledge access

- **Tool wrappers**: LangChain adapters · Expose domain operations as LLM-compatible tools.
- **Biomedical clients**: domain integrations · API-specific retrieval and evidence operations.
- [Unified gene search](https://github.com/ryanwangzf/biodsa/blob/main/biodsa/tools/genes/unified_gene_search.py): entity normalization · Normalizes cross-source gene lookup. · `biodsa/tools/genes/unified_gene_search.py`
- **Biomedical services**: external APIs · PubMed, trials, drug-target, and annotation sources.

### Execution and memory

- [Sandbox interface](https://github.com/ryanwangzf/biodsa/blob/main/biodsa/sandbox/sandbox_interface.py): trust boundary · Isolates agent-generated analysis code from the host. · `biodsa/sandbox/sandbox_interface.py`
- [Sandbox execution](https://github.com/ryanwangzf/biodsa/blob/main/biodsa/sandbox/execution.py): code runner · `biodsa/sandbox/execution.py`
- [Python sandbox image](https://github.com/ryanwangzf/biodsa/blob/main/biodsa_env/python_sandbox/Dockerfile): Docker runtime · `biodsa_env/python_sandbox/Dockerfile`
- [Research memory graph](https://github.com/ryanwangzf/biodsa/blob/main/biodsa/memory/memory_graph/graph.py): persistent context · Graph-backed context with BM25 retrieval. · `biodsa/memory/memory_graph/graph.py`
- [Memory tool](https://github.com/ryanwangzf/biodsa/blob/main/biodsa/memory/memory_graph/tool.py): agent tool · `biodsa/memory/memory_graph/tool.py`

### Other components

- [Runnable examples](https://github.com/ryanwangzf/biodsa/blob/main/scripts/run_dswizard_agent.py): Python scripts · Instantiate and execute published agents. · `scripts/run_dswizard_agent.py`
- **Structured results and artifacts**: execution output · Traces, generated files, and reportable outputs.
- [Benchmark datasets](https://github.com/ryanwangzf/biodsa/blob/main/benchmarks/BioDSA-1K/dataset/biodsa_1k_hypothesis.parquet): repository assets · `benchmarks/BioDSA-1K/dataset/biodsa_1k_hypothesis.parquet`

## Connections

- Runnable examples → BaseAgent: runs
- BaseAgent → State and LLM config: uses
- BaseAgent → ReAct and coder agents: supports
- BaseAgent → DSWizard: foundation for
- BaseAgent → DeepEvidence: foundation for
- BaseAgent → Clinical and literature agents: foundation for
- BaseAgent → Collaborative and verification agents: foundation for
- DSWizard → Tool wrappers: invokes
- DeepEvidence → Tool wrappers: invokes
- Clinical and literature agents → Tool wrappers: invokes
- Collaborative and verification agents → Tool wrappers: invokes
- Tool wrappers → Biomedical clients: adapts
- Biomedical clients → Unified gene search: includes
- Biomedical clients → Biomedical services: queries
- DSWizard → Sandbox interface: executes code in
- ReAct and coder agents → Sandbox interface: executes code in
- Sandbox interface → Sandbox execution: delegates to
- Sandbox execution → Python sandbox image: runs in
- Sandbox execution → Structured results and artifacts: produces
- BaseAgent → Memory tool: can register
- Memory tool → Research memory graph: retrieves and persists
- BaseAgent → Structured results and artifacts: returns
- Benchmark datasets → DSWizard: evaluates