# shan23chen/medbrowsecomp architecture

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

- Interactive diagram: https://gitdiagram.com/shan23chen/medbrowsecomp
- Repository: https://github.com/shan23chen/medbrowsecomp

## Overview

##### Project type and purpose
- MedBrowseComp is an open-source Python benchmarking and agentic‐system toolkit for multi-hop medical fact retrieval and synthesis.
- It glues together data files (ClinicalTrials.gov & PubMed), preprocessing utilities, LLM-based inference modules (Gemini, OpenAI, Sonar), and a Dockerized Streamlit demo agent.

##### File structure
- Top‐level scripts:
- process_NCT_predictions.py – orchestrates end-to-end predictions
- gemini_inference.py, openai_search_inference.py, sonar_inference.py – per-model adapters
- encode_decode.py, csv_generator.py – data encoding/decoding and sample generation
- Helpers: random_helper/ – utilities for data download, PubMed API, preprocessing, and notebooks
- Data: data/ – raw & encoded CSVs, prompts, EOBZIP files
- Agents demo: agents/computer-use-demo/ – Python package with loop.py, run_prompts.py, tools/ (bash, computer, edit, etc.), Streamlit UI, Dockerfile, entrypoint & HTTP server
- Results: results/ – output CSVs, analysis scripts, archived runs

##### README insights
- Core workflow: ingest benchmark CSV → optional encoding/decoding → run process_NCT_predictions with chosen model & flags → produce results CSV → analyze via notebooks/scripts
- External dependencies: GEMINI_API_KEY, OPENAI_API_KEY, SONAR_API_KEY, ClinicalTrials.gov API, Bio.Entrez (PubMed), optional Google Search tool

##### Main components
a. Data Sources & Storage
- Raw benchmark CSVs (data/final50.csv, data/final121.csv)
- Encoded CSV variants (data/..._b64.csv, _shift.csv)
- EOBZIP files, prompts CSVs
b. Data Preparation Layer
- encode_decode.py, csv_generator.py, random_helper/* utilities (download_nct_data, process_NCT_dataset, pubmed_utils)
c. Orchestrator / CLI
- process_NCT_predictions.py (accepts --csv_path, --model, --use_tools, --max_workers)
d. Inference Modules
- gemini_inference.py
- openai_search_inference.py
- sonar_inference.py
- (All call respective LLM APIs and external services)
e. Agent Demo (Dockerized)
- loop.py (agent control loop)
- run_prompts.py (invoke agent on prompts)
- tools/ (modular tool interfaces for bash, computer, edit, run)
- streamlit.py (web UI)
- HTTP server & static content (image/ folder)
f. External Services
- ClinicalTrials.gov API
- PubMed Bio.Entrez API
- LLM backends: Gemini, OpenAI, Sonar
- Optional Google Search tool
g. Results & Analysis
- results/ CSV outputs, merge_csv.py, hop_correctness_summary.py, notebooks

##### Relationships and interactions
- Data Files → Data Preparation → Orchestrator
- Orchestrator → Inference Module (selected per --model) → External LLM API + ClinicalTrials.gov/PubMed
- Inference returns predictions → Orchestrator writes Results CSV
- Post-processing → merge_csv.py, summary scripts → Notebooks & final analysis
- Separate “computer-use-demo” Docker container: accepts user input via Streamlit UI → loop.py invokes tools → displays agent actions in browser (via HTTP server + noVNC)

##### Architectural patterns and design principles
- Modular “one-script-per-responsibility” CLI pattern
- Agent pattern with pluggable tools (tools/*.py)
- Adapter pattern for multiple LLM backends
- Data pipeline flow (extract → transform → infer → load)
- Container boundary for demo agent

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Sources & Storage
    subgraph "Data Sources & Storage"
        direction TB
        DS1["final50_cell_combo_shift3_b64.csv"]:::data
        DS2["final121_cell_combo_shift3_b64.csv"]:::data
        DS3["final_nct_121_with_effecacy_group.csv"]:::data
        DS4["EOBZIP_2025_03/"]:::data
        DS5["agent_prompts/"]:::data
    end

    %% Data Preparation Layer
    subgraph "Data Preparation Layer"
        direction TB
        Prep1["encode_decode.py"]:::core
        Prep2["csv_generator.py"]:::core
        Prep3["download_nct_data.py"]:::core
        Prep4["process_NCT_dataset.py"]:::core
        Prep5["pubmed_utils.py"]:::core
        Prep6["process_predictions.py"]:::core
        Prep7["drop_correct_predictions.py"]:::core
    end

    %% Orchestrator / CLI
    Orchestrator["process_NCT_predictions.py"]:::core

    %% Inference Modules
    subgraph "Inference Modules"
        direction TB
        Gem["gemini_inference.py"]:::core
        OSA["openai_search_inference.py"]:::core
        Sonar["sonar_inference.py"]:::core
    end

    %% External Services
    subgraph "External Services"
        direction TB
        CTAPI["ClinicalTrials.gov API"]:::external
        PubMed["PubMed Bio.Entrez API"]:::external
        GeminiAPI["Gemini LLM API"]:::external
        OpenAIAPI["OpenAI LLM API"]:::external
        SonarAPI["Sonar LLM API"]:::external
        GoogleSearch["Google Search (optional)"]:::external
    end

    %% Results & Analysis
    subgraph "Results & Analysis"
        direction TB
        Res1["hop_correctness_summary.py"]:::core
        Res2["merge_csv.py"]:::core
        Res3["checker.ipynb"]:::data
        Res4["old_results/"]:::data
    end

    %% Demo Agent Container
    subgraph "computer-use-demo Container" 
        direction TB
        style computeruse-demo fill:#E8D5F7,stroke:#7D3C98,stroke-width:2px
        UI["streamlit.py"]:::ui
        Loop["loop.py"]:::core
        RunP["run_prompts.py"]:::core
        subgraph Tools
            direction TB
            TB1["base.py"]:::core
            TB2["bash.py"]:::core
            TB3["computer.py"]:::core
            TB4["edit.py"]:::core
            TB5["run.py"]:::core
            TB6["collection.py"]:::core
            TB7["groups.py"]:::core
        end
        HTTP["http_server.py"]:::core
        Entrypoint["entrypoint.sh"]:::core
        Launch["launch_containers.sh"]:::core
        UI --> Loop
        Loop --> RunP
        Loop --> Tools
        RunP --> HTTP
        HTTP --> UI
        Entrypoint --> Launch
    end

    %% Connections
    DS1 --> Prep1
    DS2 --> Prep1
    DS3 --> Prep1
    DS4 --> Prep3
    DS5 --> Prep2

    Prep1 --> Orchestrator
    Prep2 --> Orchestrator
    Prep3 --> Orchestrator
    Prep4 --> Orchestrator
    Prep5 --> Orchestrator
    Prep6 --> Orchestrator
    Prep7 --> Orchestrator

    Orchestrator --> Gem
    Orchestrator --> OSA
    Orchestrator --> Sonar

    Gem -->|API Call| GeminiAPI
    OSA -->|API Call| OpenAIAPI
    Sonar -->|API Call| SonarAPI
    Gem -->|PubMed| PubMed
    OSA -->|ClinicalTrials| CTAPI
    Sonar -->|Google| GoogleSearch

    Gem --> Orchestrator
    OSA --> Orchestrator
    Sonar --> Orchestrator

    Orchestrator --> Res1
    Orchestrator --> Res2
    Res2 --> Res3
    Res2 --> Res4

    %% Click Events
    click DS1 "https://github.com/shan23chen/medbrowsecomp/blob/main/data/final50_cell_combo_shift3_b64.csv"
    click DS2 "https://github.com/shan23chen/medbrowsecomp/blob/main/data/final121_cell_combo_shift3_b64.csv"
    click DS3 "https://github.com/shan23chen/medbrowsecomp/blob/main/data/final_nct_121_with_effecacy_group.csv"
    click DS4 "https://github.com/shan23chen/medbrowsecomp/tree/main/data/EOBZIP_2025_03/"
    click DS5 "https://github.com/shan23chen/medbrowsecomp/tree/main/data/agent_prompts/"
    click Prep1 "https://github.com/shan23chen/medbrowsecomp/blob/main/data/encode_decode.py"
    click Prep2 "https://github.com/shan23chen/medbrowsecomp/blob/main/data/csv_generator.py"
    click Prep3 "https://github.com/shan23chen/medbrowsecomp/blob/main/random_helper/download_nct_data.py"
    click Prep4 "https://github.com/shan23chen/medbrowsecomp/blob/main/random_helper/process_NCT_dataset.py"
    click Prep5 "https://github.com/shan23chen/medbrowsecomp/blob/main/random_helper/pubmed_utils.py"
    click Prep6 "https://github.com/shan23chen/medbrowsecomp/blob/main/random_helper/process_predictions.py"
    click Prep7 "https://github.com/shan23chen/medbrowsecomp/blob/main/random_helper/drop_correct_predictions.py"
    click Orchestrator "https://github.com/shan23chen/medbrowsecomp/blob/main/process_NCT_predictions.py"
    click Gem "https://github.com/shan23chen/medbrowsecomp/blob/main/gemini_inference.py"
    click OSA "https://github.com/shan23chen/medbrowsecomp/blob/main/openai_search_inference.py"
    click Sonar "https://github.com/shan23chen/medbrowsecomp/blob/main/sonar_inference.py"
    click Res1 "https://github.com/shan23chen/medbrowsecomp/blob/main/results/hop_correctness_summary.py"
    click Res2 "https://github.com/shan23chen/medbrowsecomp/blob/main/results/merge_csv.py"
    click Res3 "https://github.com/shan23chen/medbrowsecomp/blob/main/results/checker.ipynb"
    click Res4 "https://github.com/shan23chen/medbrowsecomp/tree/main/results/old_results/"
    click UI "https://github.com/shan23chen/medbrowsecomp/blob/main/agents/computer-use-demo/computer_use_demo/streamlit.py"
    click Loop "https://github.com/shan23chen/medbrowsecomp/blob/main/agents/computer-use-demo/computer_use_demo/loop.py"
    click RunP "https://github.com/shan23chen/medbrowsecomp/blob/main/agents/computer-use-demo/computer_use_demo/run_prompts.py"
    click TB1 "https://github.com/shan23chen/medbrowsecomp/blob/main/agents/computer-use-demo/computer_use_demo/tools/base.py"
    click TB2 "https://github.com/shan23chen/medbrowsecomp/blob/main/agents/computer-use-demo/computer_use_demo/tools/bash.py"
    click TB3 "https://github.com/shan23chen/medbrowsecomp/blob/main/agents/computer-use-demo/computer_use_demo/tools/computer.py"
    click TB4 "https://github.com/shan23chen/medbrowsecomp/blob/main/agents/computer-use-demo/computer_use_demo/tools/edit.py"
    click TB5 "https://github.com/shan23chen/medbrowsecomp/blob/main/agents/computer-use-demo/computer_use_demo/tools/run.py"
    click TB6 "https://github.com/shan23chen/medbrowsecomp/blob/main/agents/computer-use-demo/computer_use_demo/tools/collection.py"
    click TB7 "https://github.com/shan23chen/medbrowsecomp/blob/main/agents/computer-use-demo/computer_use_demo/tools/groups.py"
    click HTTP "https://github.com/shan23chen/medbrowsecomp/blob/main/agents/computer-use-demo/image/http_server.py"
    click Entrypoint "https://github.com/shan23chen/medbrowsecomp/blob/main/agents/computer-use-demo/image/entrypoint.sh"
    click Launch "https://github.com/shan23chen/medbrowsecomp/blob/main/agents/computer-use-demo/launch_containers.sh"

    %% Styles
    classDef data fill:#D0E6FF,stroke:#1F78B4
    classDef core fill:#D5F5E3,stroke:#27AE60
    classDef external fill:#FDEBD0,stroke:#E67E22
    classDef ui fill:#F5EEF8,stroke:#8E44AD
```
