# snap-stanford/biodiscoveryagent architecture

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

- Interactive diagram: https://gitdiagram.com/snap-stanford/biodiscoveryagent
- Repository: https://github.com/snap-stanford/biodiscoveryagent

## Overview

##### Main Components
- CLI/Entry Point: The primary execution script (research_assistant.py) parses arguments (task type, model selection, dataset name, run name, etc.).
- LLM Interface: The LLM.py module is responsible for interacting with external LLM APIs (Claude, GPT) and handling messaging.
- Tools Module: A collection of scripts that enrich the agent’s capability:
- achilles.py, baseline.py, gene.py, get_gene_summary.py, get_lit_review.py, and tools.py provide various functions including gene searching, summary generation, literature reviews, and additional analysis.
- Datasets Management: The datasets directory contains ground truth CSVs, JSON task prompt definitions, and NumPy arrays (topmovers) for experiment data. This is the backbone for experiment configuration and evaluation.
- Analysis: The analyze.py script handles evaluation of predictions (calculating hit rates and overall performance).
- External Resources/Dependencies:
- API integrations (Claude, possibly OpenAI) are key for enabling the closed-loop design.
- Additional external tools (e.g., Reactome pathway search) and literature search services.
- Utilities and Configuration:

##### Visualizing Relationships and Interactions
- Research Assistant as the central orchestrator, accepting inputs via the CLI.
- Separate modules (gene.py, get_gene_summary.py, get_lit_review.py, tools.py) as “Tools” that feed into and augment the responses from the LLM. These tools interact with the agent to provide critiques, gene insights, and literature support.
- Datasets repository as a data source and endpoint:
- Analysis module (analyze.py) receiving processed outputs to evaluate prediction quality and hit rates.
- External interactions:

##### Architectural Patterns and Design Principles
- Modular design: Each Python script acts as a stand-alone component and can be updated/replaced independently.
- Command-Line Driven Workflow: The application’s interaction model is based on CLI arguments, which trigger specific modules or tool integrations.
- Extensibility: The clear separation between core orchestration, dataset management, and analytical tools makes it easier to add new functionalities (or plug in new models/APIs).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Main Components
    CLI["CLI/Research Assistant"]:::cli
    LLM["LLM Interface"]:::llm
    External["External API (Claude/GPT)"]:::external
    Datasets["Dataset Repository"]:::dataset
    Analysis["Analysis Evaluator"]:::analysis

    %% Subgraph for Tools Module
    subgraph "Tools Module"
        GEN["gene.py"]:::tool
        ACH["achilles.py"]:::tool
        BAS["baseline.py"]:::tool
        TOL["tools.py"]:::tool
        GENSUM["get_gene_summary.py"]:::tool
        LITREV["get_lit_review.py"]:::tool
    end

    %% Subgraph for Utilities and Configuration
    subgraph "Utilities and Config"
        REQ["requirements.txt"]:::util
        ASSET["assets/"]:::util
    end

    %% Relationships and Data Flow
    CLI -->|"parses_arguments"| LLM
    LLM -->|"makes_API_calls"| External
    LLM -->|"calls_tools"| GEN
    REQ -->|"configures"| CLI
    ASSET -->|"provides_assets"| CLI
    Datasets -->|"provides_data"| CLI
    Datasets -->|"supplies_experiment_data"| Analysis
    CLI -->|"sends_processed_outputs"| Analysis
    GEN -->|"accesses_data"| Datasets

    %% Click Events
    click CLI "https://github.com/snap-stanford/biodiscoveryagent/blob/master/research_assistant.py"
    click LLM "https://github.com/snap-stanford/biodiscoveryagent/blob/master/LLM.py"
    click GEN "https://github.com/snap-stanford/biodiscoveryagent/blob/master/gene.py"
    click ACH "https://github.com/snap-stanford/biodiscoveryagent/blob/master/achilles.py"
    click BAS "https://github.com/snap-stanford/biodiscoveryagent/blob/master/baseline.py"
    click TOL "https://github.com/snap-stanford/biodiscoveryagent/blob/master/tools.py"
    click GENSUM "https://github.com/snap-stanford/biodiscoveryagent/blob/master/get_gene_summary.py"
    click LITREV "https://github.com/snap-stanford/biodiscoveryagent/blob/master/get_lit_review.py"
    click Datasets "https://github.com/snap-stanford/biodiscoveryagent/tree/master/datasets/"
    click Analysis "https://github.com/snap-stanford/biodiscoveryagent/blob/master/analyze.py"
    click REQ "https://github.com/snap-stanford/biodiscoveryagent/blob/master/requirements.txt"
    click ASSET "https://github.com/snap-stanford/biodiscoveryagent/tree/master/assets/"

    %% Styles
    classDef cli fill:#add8e6,stroke:#000,stroke-width:1px;
    classDef llm fill:#90ee90,stroke:#000,stroke-width:1px;
    classDef tool fill:#ffeb99,stroke:#000,stroke-width:1px;
    classDef dataset fill:#ffcccb,stroke:#000,stroke-width:1px;
    classDef analysis fill:#ffa07a,stroke:#000,stroke-width:1px;
    classDef external fill:#d3d3d3,stroke:#000,stroke-width:1px;
    classDef util fill:#e6e6fa,stroke:#000,stroke-width:1px;
```
