# gersteinlab/medagents architecture

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

- Interactive diagram: https://gitdiagram.com/gersteinlab/medagents
- Repository: https://github.com/gersteinlab/medagents

## Overview

MedAgents runs medical-question inference using either direct prompting or a multi-disciplinary collaboration workflow. In the collaborative path, `utils.py` orchestrates domain selection, expert analyses, report synthesis, optional consensus-and-revision rounds, and final answer generation; `api_utils.py` sends model requests to Azure OpenAI. `run.py` loads dataset examples and appends prediction records. The README describes evaluation on several datasets, but only the MedQA data directory is present in this tree. The stage wiring is based on the sampled orchestration and prompt code.

Main entry points: [`utils.py`](https://github.com/gersteinlab/medagents/blob/main/utils.py) (Decode workflow), [`run.py`](https://github.com/gersteinlab/medagents/blob/main/run.py) (Inference runner), [`api_utils.py`](https://github.com/gersteinlab/medagents/blob/main/api_utils.py) (API handler), [`data_utils.py`](https://github.com/gersteinlab/medagents/blob/main/data_utils.py) (Dataset loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_execution["Inference execution"]
  node_runner["Inference runner<br/>[run.py]"]
  node_results["Prediction records<br/>[run.py]"]
end

subgraph group_collaboration["Medical collaboration"]
  node_workflow["Decode workflow<br/>[utils.py]"]
  node_domain_select["Domain selection<br/>[utils.py]"]
  node_expert_analysis["Expert analysis<br/>[utils.py]"]
  node_report_synthesis["Report synthesis<br/>[utils.py]"]
  node_consensus["Consensus review<br/>[utils.py]"]
  node_revision["Report revision<br/>[utils.py]"]
  node_decision["Answer decision<br/>[utils.py]"]
  node_prompts["Prompt templates"]
end

subgraph group_data["Dataset handling"]
  node_dataset["Dataset loader<br/>[data_utils.py]"]
  node_medqa["MedQA examples<br/>[test.jsonl]"]
  node_cleaning["Output cleaning<br/>[data_utils.py]"]
end

subgraph group_integration["Model integration"]
  node_api_handler["API handler<br/>[api_utils.py]"]
  node_azure{{"Azure OpenAI"}}
end

node_user(("Inference operator"))

node_user -->|"runs inference"| node_runner
node_runner -->|"loads examples"| node_dataset
node_medqa -->|"provides examples"| node_dataset
node_runner -->|"decodes question"| node_workflow
node_workflow -->|"starts workflow"| node_domain_select
node_domain_select -->|"selects domains"| node_expert_analysis
node_expert_analysis -->|"provides analyses"| node_report_synthesis
node_report_synthesis -->|"submits report"| node_consensus
node_consensus -->|"requests changes"| node_revision
node_revision -->|"rechecks report"| node_consensus
node_report_synthesis -->|"provides report"| node_decision
node_consensus -->|"provides final report"| node_decision
node_workflow -->|"builds prompts"| node_prompts
node_workflow -->|"requests completions"| node_api_handler
node_api_handler -->|"sends requests"| node_azure
node_workflow -->|"cleans responses"| node_cleaning
node_runner -->|"appends records"| node_results

click node_runner "https://github.com/gersteinlab/medagents/blob/main/run.py"
click node_dataset "https://github.com/gersteinlab/medagents/blob/main/data_utils.py"
click node_medqa "https://github.com/gersteinlab/medagents/blob/main/datasets/MedQA/test.jsonl"
click node_workflow "https://github.com/gersteinlab/medagents/blob/main/utils.py"
click node_domain_select "https://github.com/gersteinlab/medagents/blob/main/utils.py"
click node_expert_analysis "https://github.com/gersteinlab/medagents/blob/main/utils.py"
click node_report_synthesis "https://github.com/gersteinlab/medagents/blob/main/utils.py"
click node_consensus "https://github.com/gersteinlab/medagents/blob/main/utils.py"
click node_revision "https://github.com/gersteinlab/medagents/blob/main/utils.py"
click node_decision "https://github.com/gersteinlab/medagents/blob/main/utils.py"
click node_prompts "https://github.com/gersteinlab/medagents/blob/main/prompt_generator.py"
click node_cleaning "https://github.com/gersteinlab/medagents/blob/main/data_utils.py"
click node_api_handler "https://github.com/gersteinlab/medagents/blob/main/api_utils.py"
click node_results "https://github.com/gersteinlab/medagents/blob/main/run.py"

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_runner,node_results toneBlue
class node_workflow,node_domain_select,node_expert_analysis,node_report_synthesis,node_consensus,node_revision,node_decision,node_prompts toneAmber
class node_dataset,node_medqa,node_cleaning toneMint
class node_api_handler,node_azure toneRose
class node_user toneIndigo
```

## Components

### Inference execution

- [Inference runner](https://github.com/gersteinlab/medagents/blob/main/run.py): `run.py`
- [Prediction records](https://github.com/gersteinlab/medagents/blob/main/run.py): `run.py`

### Medical collaboration

- [Decode workflow](https://github.com/gersteinlab/medagents/blob/main/utils.py): `utils.py`
- [Domain selection](https://github.com/gersteinlab/medagents/blob/main/utils.py): `utils.py`
- [Expert analysis](https://github.com/gersteinlab/medagents/blob/main/utils.py): `utils.py`
- [Report synthesis](https://github.com/gersteinlab/medagents/blob/main/utils.py): `utils.py`
- [Consensus review](https://github.com/gersteinlab/medagents/blob/main/utils.py): `utils.py`
- [Report revision](https://github.com/gersteinlab/medagents/blob/main/utils.py): `utils.py`
- [Answer decision](https://github.com/gersteinlab/medagents/blob/main/utils.py): `utils.py`
- [Prompt templates](https://github.com/gersteinlab/medagents/blob/main/prompt_generator.py): `prompt_generator.py`

### Dataset handling

- [Dataset loader](https://github.com/gersteinlab/medagents/blob/main/data_utils.py): `data_utils.py`
- [MedQA examples](https://github.com/gersteinlab/medagents/blob/main/datasets/MedQA/test.jsonl): `datasets/MedQA/test.jsonl`
- [Output cleaning](https://github.com/gersteinlab/medagents/blob/main/data_utils.py): `data_utils.py`

### Model integration

- [API handler](https://github.com/gersteinlab/medagents/blob/main/api_utils.py): `api_utils.py`
- **Azure OpenAI**

### Other components

- **Inference operator**

## Connections

- Inference operator → Inference runner: runs inference
- Inference runner → Dataset loader: loads examples
- MedQA examples → Dataset loader: provides examples
- Inference runner → Decode workflow: decodes question
- Decode workflow → Domain selection: starts workflow
- Domain selection → Expert analysis: selects domains
- Expert analysis → Report synthesis: provides analyses
- Report synthesis → Consensus review: submits report
- Consensus review → Report revision: requests changes
- Report revision → Consensus review: rechecks report
- Report synthesis → Answer decision: provides report
- Consensus review → Answer decision: provides final report
- Decode workflow → Prompt templates: builds prompts
- Decode workflow → API handler: requests completions
- API handler → Azure OpenAI: sends requests
- Decode workflow → Output cleaning: cleans responses
- Inference runner → Prediction records: appends records