ryanwangzf/biodsa

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.