# katherlab/onprem-medical-agents architecture

> Architecture diagram of the GitHub repository katherlab/onprem-medical-agents, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/katherlab/onprem-medical-agents
- Repository: https://github.com/katherlab/onprem-medical-agents

## Overview

On-Prem Medical Agents runs benchmark-configured, multi-turn doctor–patient simulations, using patient-case data and clinical tools to produce conversation logs; separate runners evaluate diagnoses and merge runs, while a confidence pipeline derives features and visualizations. The graph preserves MIMIC and VivaBench paths and the evaluation and analysis branches. Unexcerpted capabilities and wiring are included only where README or source-index references support them; some internal runtime routing remains uncertain.

Main entry points: [`src/simulate.py`](https://github.com/katherlab/onprem-medical-agents/blob/main/src/simulate.py) (Simulation runner), [`src/multi_agents/executor_agent.py`](https://github.com/katherlab/onprem-medical-agents/blob/main/src/multi_agents/executor_agent.py) (Doctor and patient agents), [`src/vis_confidence.py`](https://github.com/katherlab/onprem-medical-agents/blob/main/src/vis_confidence.py) (Confidence pipeline), [`src/conv.py`](https://github.com/katherlab/onprem-medical-agents/blob/main/src/conv.py) (Dialogue engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_simulation["Simulation"]
  node_config["Agent settings<br/>[agent_config.py]"]
  node_runner["Simulation runner<br/>[simulate.py]"]
  node_conversation["Dialogue engine<br/>[conv.py]"]
  node_agents["Doctor and patient agents<br/>[executor_agent.py]"]
  node_prompts["Benchmark prompts<br/>[prompts.py]"]
  node_collector["Conversation logs<br/>[mes_collect.py]"]
end

subgraph group_clinical["Clinical data and tools"]
  node_mimic["MIMIC case loader<br/>[mimic_dataset.py]"]
  node_viva["VivaBench case loader"]
  node_tool_api["Clinical tool definitions<br/>[tool_request.py]"]
  node_tool_dispatch["Tool dispatch<br/>[tool_handler.py]"]
  node_tool_exec["Clinical tool execution<br/>[tool_execs.py]"]
  node_viva_tools["VivaBench tools<br/>[tool_vivabench.py]"]
  node_qdrant[("Procedure search index")]
end

subgraph group_evaluation["Evaluation"]
  node_eval_runner["Diagnosis evaluator<br/>[evaluate.py]"]
  node_eval_core["Evaluation methods<br/>[evaluators.py]"]
  node_merge["Run aggregation<br/>[merge_runs.py]"]
end

subgraph group_confidence["Confidence analysis"]
  node_confidence_runner["Confidence pipeline<br/>[vis_confidence.py]"]
  node_confidence_loader["Analysis data loader<br/>[data_loader.py]"]
  node_feature_engineer["Feature engineering"]
  node_feature_analysis["Confidence analysis<br/>[analysis.py]"]
end

node_user(("Researcher"))

node_user -->|"starts simulation"| node_runner
node_runner -->|"uses settings"| node_config
node_runner -->|"loads MIMIC cases"| node_mimic
node_runner -->|"loads VivaBench cases"| node_viva
node_runner -->|"runs dialogue"| node_conversation
node_runner -->|"configures agents"| node_agents
node_agents -->|"uses instructions"| node_prompts
node_conversation -->|"records turns"| node_collector
node_agents -->|"invokes tools"| node_tool_api
node_tool_api -->|"dispatches requests"| node_tool_dispatch
node_tool_dispatch -->|"fetches results"| node_tool_exec
node_tool_exec -->|"searches procedures"| node_qdrant
node_agents -.->|"uses benchmark tools"| node_viva_tools
node_user -->|"starts evaluation"| node_eval_runner
node_eval_runner -->|"evaluates diagnoses"| node_eval_core
node_user -->|"aggregates runs"| node_merge
node_user -->|"starts analysis"| node_confidence_runner
node_confidence_runner -->|"loads aggregates"| node_confidence_loader
node_confidence_runner -->|"computes features"| node_feature_engineer
node_feature_engineer -.->|"analyzes features"| node_feature_analysis

click node_config "https://github.com/katherlab/onprem-medical-agents/blob/main/src/configs/agent_config.py"
click node_runner "https://github.com/katherlab/onprem-medical-agents/blob/main/src/simulate.py"
click node_conversation "https://github.com/katherlab/onprem-medical-agents/blob/main/src/conv.py"
click node_agents "https://github.com/katherlab/onprem-medical-agents/blob/main/src/multi_agents/executor_agent.py"
click node_prompts "https://github.com/katherlab/onprem-medical-agents/blob/main/src/prompts.py"
click node_collector "https://github.com/katherlab/onprem-medical-agents/blob/main/src/mes_collect.py"
click node_mimic "https://github.com/katherlab/onprem-medical-agents/blob/main/src/dataset/mimic_dataset.py"
click node_viva "https://github.com/katherlab/onprem-medical-agents/blob/main/src/dataset/vivabench_dataset.py"
click node_tool_api "https://github.com/katherlab/onprem-medical-agents/blob/main/src/tools/tool_request.py"
click node_tool_dispatch "https://github.com/katherlab/onprem-medical-agents/blob/main/src/tools/tool_handler.py"
click node_tool_exec "https://github.com/katherlab/onprem-medical-agents/blob/main/src/tools/tool_execs.py"
click node_viva_tools "https://github.com/katherlab/onprem-medical-agents/blob/main/src/tools/tool_vivabench.py"
click node_qdrant "https://github.com/katherlab/onprem-medical-agents/blob/main/src/qdrant_collection.py"
click node_eval_runner "https://github.com/katherlab/onprem-medical-agents/blob/main/src/evaluate.py"
click node_eval_core "https://github.com/katherlab/onprem-medical-agents/blob/main/src/eval/evaluators.py"
click node_merge "https://github.com/katherlab/onprem-medical-agents/blob/main/src/merge_runs.py"
click node_confidence_runner "https://github.com/katherlab/onprem-medical-agents/blob/main/src/vis_confidence.py"
click node_confidence_loader "https://github.com/katherlab/onprem-medical-agents/blob/main/src/confidence/data_loader.py"
click node_feature_engineer "https://github.com/katherlab/onprem-medical-agents/blob/main/src/confidence/feature_engineering.py"
click node_feature_analysis "https://github.com/katherlab/onprem-medical-agents/blob/main/src/confidence/analysis.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_config,node_runner,node_conversation,node_agents,node_prompts,node_collector toneBlue
class node_mimic,node_viva,node_tool_api,node_tool_dispatch,node_tool_exec,node_viva_tools,node_qdrant toneAmber
class node_eval_runner,node_eval_core,node_merge toneMint
class node_confidence_runner,node_confidence_loader,node_feature_engineer,node_feature_analysis toneRose
class node_user toneIndigo
```

## Components

### Simulation

- [Agent settings](https://github.com/katherlab/onprem-medical-agents/blob/main/src/configs/agent_config.py): `src/configs/agent_config.py`
- [Simulation runner](https://github.com/katherlab/onprem-medical-agents/blob/main/src/simulate.py): `src/simulate.py`
- [Dialogue engine](https://github.com/katherlab/onprem-medical-agents/blob/main/src/conv.py): `src/conv.py`
- [Doctor and patient agents](https://github.com/katherlab/onprem-medical-agents/blob/main/src/multi_agents/executor_agent.py): `src/multi_agents/executor_agent.py`
- [Benchmark prompts](https://github.com/katherlab/onprem-medical-agents/blob/main/src/prompts.py): `src/prompts.py`
- [Conversation logs](https://github.com/katherlab/onprem-medical-agents/blob/main/src/mes_collect.py): `src/mes_collect.py`

### Clinical data and tools

- [MIMIC case loader](https://github.com/katherlab/onprem-medical-agents/blob/main/src/dataset/mimic_dataset.py): `src/dataset/mimic_dataset.py`
- [VivaBench case loader](https://github.com/katherlab/onprem-medical-agents/blob/main/src/dataset/vivabench_dataset.py): `src/dataset/vivabench_dataset.py`
- [Clinical tool definitions](https://github.com/katherlab/onprem-medical-agents/blob/main/src/tools/tool_request.py): `src/tools/tool_request.py`
- [Tool dispatch](https://github.com/katherlab/onprem-medical-agents/blob/main/src/tools/tool_handler.py): `src/tools/tool_handler.py`
- [Clinical tool execution](https://github.com/katherlab/onprem-medical-agents/blob/main/src/tools/tool_execs.py): `src/tools/tool_execs.py`
- [VivaBench tools](https://github.com/katherlab/onprem-medical-agents/blob/main/src/tools/tool_vivabench.py): `src/tools/tool_vivabench.py`
- [Procedure search index](https://github.com/katherlab/onprem-medical-agents/blob/main/src/qdrant_collection.py): `src/qdrant_collection.py`

### Evaluation

- [Diagnosis evaluator](https://github.com/katherlab/onprem-medical-agents/blob/main/src/evaluate.py): `src/evaluate.py`
- [Evaluation methods](https://github.com/katherlab/onprem-medical-agents/blob/main/src/eval/evaluators.py): `src/eval/evaluators.py`
- [Run aggregation](https://github.com/katherlab/onprem-medical-agents/blob/main/src/merge_runs.py): `src/merge_runs.py`

### Confidence analysis

- [Confidence pipeline](https://github.com/katherlab/onprem-medical-agents/blob/main/src/vis_confidence.py): `src/vis_confidence.py`
- [Analysis data loader](https://github.com/katherlab/onprem-medical-agents/blob/main/src/confidence/data_loader.py): `src/confidence/data_loader.py`
- [Feature engineering](https://github.com/katherlab/onprem-medical-agents/blob/main/src/confidence/feature_engineering.py): `src/confidence/feature_engineering.py`
- [Confidence analysis](https://github.com/katherlab/onprem-medical-agents/blob/main/src/confidence/analysis.py): `src/confidence/analysis.py`

### Other components

- **Researcher**

## Connections

- Researcher → Simulation runner: starts simulation (evidence: `README.md`)
- Simulation runner → Agent settings: uses settings (evidence: `README.md`)
- Simulation runner → MIMIC case loader: loads MIMIC cases (evidence: `README.md`)
- Simulation runner → VivaBench case loader: loads VivaBench cases (evidence: `README.md`)
- Simulation runner → Dialogue engine: runs dialogue (evidence: `src/simulate.py`)
- Simulation runner → Doctor and patient agents: configures agents (evidence: `src/simulate.py`)
- Doctor and patient agents → Benchmark prompts: uses instructions (evidence: `src/multi_agents/executor_agent.py`)
- Dialogue engine → Conversation logs: records turns (evidence: `src/conv.py`)
- Doctor and patient agents → Clinical tool definitions: invokes tools (evidence: `src/multi_agents/executor_agent.py`)
- Clinical tool definitions → Tool dispatch: dispatches requests (evidence: `src/tools/tool_handler.py`)
- Tool dispatch → Clinical tool execution: fetches results (evidence: `src/tools/tool_handler.py`)
- Clinical tool execution → Procedure search index: searches procedures (evidence: `src/tools/tool_execs.py`)
- Doctor and patient agents → VivaBench tools: uses benchmark tools
- Researcher → Diagnosis evaluator: starts evaluation (evidence: `README.md`)
- Diagnosis evaluator → Evaluation methods: evaluates diagnoses (evidence: `src/eval/evaluators.py`)
- Researcher → Run aggregation: aggregates runs (evidence: `README.md`)
- Researcher → Confidence pipeline: starts analysis (evidence: `README.md`)
- Confidence pipeline → Analysis data loader: loads aggregates (evidence: `README.md`)
- Confidence pipeline → Feature engineering: computes features (evidence: `README.md`)
- Feature engineering → Confidence analysis: analyzes features
