# talhaahmed86402/medibuddy architecture

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

- Interactive diagram: https://gitdiagram.com/talhaahmed86402/medibuddy
- Repository: https://github.com/talhaahmed86402/medibuddy

## Overview

MediBuddy-Bench is an offline, deterministic benchmark for agents assisting an international resident in Korea. Its main workflow is to generate synthetic scenarios, expose task cards and tools to an agent, run the interaction, score task-specific answers and safety failures, and record results for comparison. The product covers hospital choice, triage, interpretation, visit summaries, cross-visit memory, and full journeys; it also supports remote agents through A2A and model sweeps. Edges reflect README statements and SOURCE INDEX references; unsampled implementation details are not inferred.

Main entry points: [`medibuddy_bench/runner.py`](https://github.com/talhaahmed86402/medibuddy/blob/main/medibuddy_bench/runner.py) (Episode runner), [`medibuddy_bench/gen/build.py`](https://github.com/talhaahmed86402/medibuddy/blob/main/medibuddy_bench/gen/build.py) (Dataset builder), [`medibuddy_bench/a2a_green.py`](https://github.com/talhaahmed86402/medibuddy/blob/main/medibuddy_bench/a2a_green.py) (A2A assessment flow), [`medibuddy_bench/gen/choice.py`](https://github.com/talhaahmed86402/medibuddy/blob/main/medibuddy_bench/gen/choice.py) (Hospital scenarios)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_scenario["Scenario generation"]
  node_generator["Dataset builder<br/>[build.py]"]
  node_hospital_gen["Hospital scenarios<br/>[choice.py]"]
  node_encounter_gen["Encounter scenarios<br/>[encounters.py]"]
  node_triage_gen["Triage scenarios<br/>[triage.py]"]
  node_journey_gen["Journey scenarios<br/>[journey.py]"]
  node_phrasing["Scenario phrasing<br/>[phrasing.py]"]
end

subgraph group_runtime["Agent assessment"]
  node_cards["Task cards<br/>[taskcards.py]"]
  node_tools["Agent tools<br/>[tools.py]"]
  node_runner["Episode runner<br/>[runner.py]"]
end

subgraph group_domain["Task domains"]
  node_world["Simulated world<br/>[world.py]"]
  node_knowledge["World knowledge<br/>[knowledge.py]"]
end

subgraph group_evaluation["Scoring and results"]
  node_task_scoring["Task scoring<br/>[choice.py]"]
  node_fact_scoring["Fact checking<br/>[facts.py]"]
  node_aggregate["Score aggregation<br/>[aggregate.py]"]
  node_results["Run records<br/>[results.py]"]
  node_leaderboard["Leaderboard<br/>[leaderboard.py]"]
end

subgraph group_integrations["Agent integrations"]
  node_agent["Benchmark agent<br/>[base.py]"]
  node_baselines["Reference agents<br/>[baselines.py]"]
  node_remote["Remote agent protocol<br/>[protocol.py]"]
  node_openai["OpenAI-compatible agent"]
  node_a2a_service["A2A assessment service<br/>[green_server.py]"]
  node_a2a_flow["A2A assessment flow<br/>[a2a_green.py]"]
end

node_user(("Benchmark user"))
node_model_server(("Model endpoint"))
node_a2a_agent(("External A2A agent"))

node_user -->|"builds data"| node_generator
node_generator -->|"generates"| node_hospital_gen
node_generator -->|"generates"| node_encounter_gen
node_generator -->|"generates"| node_triage_gen
node_generator -->|"generates"| node_journey_gen
node_generator -->|"uses"| node_world
node_hospital_gen -->|"uses"| node_phrasing
node_hospital_gen -->|"checks constraints"| node_world
node_encounter_gen -->|"uses facts"| node_knowledge
node_triage_gen -->|"uses facts"| node_knowledge
node_journey_gen -->|"combines scenarios"| node_hospital_gen
node_journey_gen -->|"combines scenarios"| node_encounter_gen
node_runner -->|"builds cards"| node_cards
node_runner -->|"provides tools"| node_tools
node_runner -->|"loads world"| node_world
node_runner -->|"starts session"| node_agent
node_baselines -->|"implements"| node_agent
node_runner -->|"scores tasks"| node_task_scoring
node_runner -->|"checks facts"| node_fact_scoring
node_task_scoring -->|"uses checkers"| node_fact_scoring
node_user -->|"runs assessment"| node_runner
node_model_server -->|"serves completions"| node_openai
node_openai -->|"adapts replies"| node_remote
node_a2a_agent -->|"sends assessment"| node_a2a_service
node_a2a_service -->|"dispatches assessment"| node_a2a_flow
node_a2a_flow -->|"runs episodes"| node_runner
node_a2a_flow -->|"uses protocol"| node_remote
node_a2a_flow -->|"aggregates scores"| node_aggregate
node_runner -->|"records runs"| node_results
node_results -->|"supplies episodes"| node_aggregate
node_leaderboard -->|"reads records"| node_results

click node_generator "https://github.com/talhaahmed86402/medibuddy/blob/main/medibuddy_bench/gen/build.py"
click node_hospital_gen "https://github.com/talhaahmed86402/medibuddy/blob/main/medibuddy_bench/gen/choice.py"
click node_encounter_gen "https://github.com/talhaahmed86402/medibuddy/blob/main/medibuddy_bench/gen/encounters.py"
click node_triage_gen "https://github.com/talhaahmed86402/medibuddy/blob/main/medibuddy_bench/gen/triage.py"
click node_journey_gen "https://github.com/talhaahmed86402/medibuddy/blob/main/medibuddy_bench/gen/journey.py"
click node_phrasing "https://github.com/talhaahmed86402/medibuddy/blob/main/medibuddy_bench/gen/phrasing.py"
click node_world "https://github.com/talhaahmed86402/medibuddy/blob/main/medibuddy_bench/world.py"
click node_knowledge "https://github.com/talhaahmed86402/medibuddy/blob/main/medibuddy_bench/knowledge.py"
click node_cards "https://github.com/talhaahmed86402/medibuddy/blob/main/medibuddy_bench/taskcards.py"
click node_tools "https://github.com/talhaahmed86402/medibuddy/blob/main/medibuddy_bench/tools.py"
click node_runner "https://github.com/talhaahmed86402/medibuddy/blob/main/medibuddy_bench/runner.py"
click node_agent "https://github.com/talhaahmed86402/medibuddy/blob/main/medibuddy_bench/agents/base.py"
click node_baselines "https://github.com/talhaahmed86402/medibuddy/blob/main/medibuddy_bench/agents/baselines.py"
click node_remote "https://github.com/talhaahmed86402/medibuddy/blob/main/medibuddy_bench/protocol.py"
click node_openai "https://github.com/talhaahmed86402/medibuddy/blob/main/medibuddy_bench/agents/llm_openai_compat.py"
click node_a2a_service "https://github.com/talhaahmed86402/medibuddy/blob/main/medibuddy_bench/a2a/green_server.py"
click node_a2a_flow "https://github.com/talhaahmed86402/medibuddy/blob/main/medibuddy_bench/a2a_green.py"
click node_task_scoring "https://github.com/talhaahmed86402/medibuddy/blob/main/medibuddy_bench/scoring/choice.py"
click node_fact_scoring "https://github.com/talhaahmed86402/medibuddy/blob/main/medibuddy_bench/scoring/facts.py"
click node_aggregate "https://github.com/talhaahmed86402/medibuddy/blob/main/medibuddy_bench/scoring/aggregate.py"
click node_results "https://github.com/talhaahmed86402/medibuddy/blob/main/medibuddy_bench/results.py"
click node_leaderboard "https://github.com/talhaahmed86402/medibuddy/blob/main/medibuddy_bench/leaderboard.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_generator,node_hospital_gen,node_encounter_gen,node_triage_gen,node_journey_gen,node_phrasing,node_user toneBlue
class node_cards,node_tools,node_runner toneAmber
class node_world,node_knowledge toneMint
class node_task_scoring,node_fact_scoring,node_aggregate,node_results,node_leaderboard toneRose
class node_agent,node_baselines,node_remote,node_openai,node_a2a_service,node_a2a_flow,node_model_server,node_a2a_agent toneIndigo
```

## Components

### Scenario generation

- [Dataset builder](https://github.com/talhaahmed86402/medibuddy/blob/main/medibuddy_bench/gen/build.py): `medibuddy_bench/gen/build.py`
- [Hospital scenarios](https://github.com/talhaahmed86402/medibuddy/blob/main/medibuddy_bench/gen/choice.py): `medibuddy_bench/gen/choice.py`
- [Encounter scenarios](https://github.com/talhaahmed86402/medibuddy/blob/main/medibuddy_bench/gen/encounters.py): `medibuddy_bench/gen/encounters.py`
- [Triage scenarios](https://github.com/talhaahmed86402/medibuddy/blob/main/medibuddy_bench/gen/triage.py): `medibuddy_bench/gen/triage.py`
- [Journey scenarios](https://github.com/talhaahmed86402/medibuddy/blob/main/medibuddy_bench/gen/journey.py): `medibuddy_bench/gen/journey.py`
- [Scenario phrasing](https://github.com/talhaahmed86402/medibuddy/blob/main/medibuddy_bench/gen/phrasing.py): `medibuddy_bench/gen/phrasing.py`

### Agent assessment

- [Task cards](https://github.com/talhaahmed86402/medibuddy/blob/main/medibuddy_bench/taskcards.py): `medibuddy_bench/taskcards.py`
- [Agent tools](https://github.com/talhaahmed86402/medibuddy/blob/main/medibuddy_bench/tools.py): `medibuddy_bench/tools.py`
- [Episode runner](https://github.com/talhaahmed86402/medibuddy/blob/main/medibuddy_bench/runner.py): `medibuddy_bench/runner.py`

### Task domains

- [Simulated world](https://github.com/talhaahmed86402/medibuddy/blob/main/medibuddy_bench/world.py): `medibuddy_bench/world.py`
- [World knowledge](https://github.com/talhaahmed86402/medibuddy/blob/main/medibuddy_bench/knowledge.py): `medibuddy_bench/knowledge.py`

### Scoring and results

- [Task scoring](https://github.com/talhaahmed86402/medibuddy/blob/main/medibuddy_bench/scoring/choice.py): `medibuddy_bench/scoring/choice.py`
- [Fact checking](https://github.com/talhaahmed86402/medibuddy/blob/main/medibuddy_bench/scoring/facts.py): `medibuddy_bench/scoring/facts.py`
- [Score aggregation](https://github.com/talhaahmed86402/medibuddy/blob/main/medibuddy_bench/scoring/aggregate.py): `medibuddy_bench/scoring/aggregate.py`
- [Run records](https://github.com/talhaahmed86402/medibuddy/blob/main/medibuddy_bench/results.py): `medibuddy_bench/results.py`
- [Leaderboard](https://github.com/talhaahmed86402/medibuddy/blob/main/medibuddy_bench/leaderboard.py): `medibuddy_bench/leaderboard.py`

### Agent integrations

- [Benchmark agent](https://github.com/talhaahmed86402/medibuddy/blob/main/medibuddy_bench/agents/base.py): `medibuddy_bench/agents/base.py`
- [Reference agents](https://github.com/talhaahmed86402/medibuddy/blob/main/medibuddy_bench/agents/baselines.py): `medibuddy_bench/agents/baselines.py`
- [Remote agent protocol](https://github.com/talhaahmed86402/medibuddy/blob/main/medibuddy_bench/protocol.py): `medibuddy_bench/protocol.py`
- [OpenAI-compatible agent](https://github.com/talhaahmed86402/medibuddy/blob/main/medibuddy_bench/agents/llm_openai_compat.py): `medibuddy_bench/agents/llm_openai_compat.py`
- [A2A assessment service](https://github.com/talhaahmed86402/medibuddy/blob/main/medibuddy_bench/a2a/green_server.py): `medibuddy_bench/a2a/green_server.py`
- [A2A assessment flow](https://github.com/talhaahmed86402/medibuddy/blob/main/medibuddy_bench/a2a_green.py): `medibuddy_bench/a2a_green.py`

### Other components

- **Benchmark user**
- **Model endpoint**
- **External A2A agent**

## Connections

- Benchmark user → Dataset builder: builds data
- Dataset builder → Hospital scenarios: generates (evidence: `medibuddy_bench/gen/build.py`)
- Dataset builder → Encounter scenarios: generates (evidence: `medibuddy_bench/gen/build.py`)
- Dataset builder → Triage scenarios: generates (evidence: `medibuddy_bench/gen/build.py`)
- Dataset builder → Journey scenarios: generates (evidence: `medibuddy_bench/gen/build.py`)
- Dataset builder → Simulated world: uses (evidence: `medibuddy_bench/gen/build.py`)
- Hospital scenarios → Scenario phrasing: uses (evidence: `medibuddy_bench/gen/choice.py`)
- Hospital scenarios → Simulated world: checks constraints (evidence: `medibuddy_bench/gen/choice.py`)
- Encounter scenarios → World knowledge: uses facts (evidence: `medibuddy_bench/gen/encounters.py`)
- Triage scenarios → World knowledge: uses facts (evidence: `medibuddy_bench/gen/triage.py`)
- Journey scenarios → Hospital scenarios: combines scenarios (evidence: `medibuddy_bench/gen/journey.py`)
- Journey scenarios → Encounter scenarios: combines scenarios (evidence: `medibuddy_bench/gen/journey.py`)
- Episode runner → Task cards: builds cards (evidence: `medibuddy_bench/runner.py`)
- Episode runner → Agent tools: provides tools (evidence: `medibuddy_bench/runner.py`)
- Episode runner → Simulated world: loads world (evidence: `medibuddy_bench/runner.py`)
- Episode runner → Benchmark agent: starts session (evidence: `medibuddy_bench/runner.py`)
- Reference agents → Benchmark agent: implements (evidence: `medibuddy_bench/agents/baselines.py`)
- Episode runner → Task scoring: scores tasks (evidence: `medibuddy_bench/runner.py`)
- Episode runner → Fact checking: checks facts (evidence: `medibuddy_bench/runner.py`)
- Task scoring → Fact checking: uses checkers
- Benchmark user → Episode runner: runs assessment
- Model endpoint → OpenAI-compatible agent: serves completions (evidence: `medibuddy_bench/agents/llm_openai_compat.py`)
- OpenAI-compatible agent → Remote agent protocol: adapts replies (evidence: `medibuddy_bench/agents/llm_openai_compat.py`)
- External A2A agent → A2A assessment service: sends assessment
- A2A assessment service → A2A assessment flow: dispatches assessment (evidence: `medibuddy_bench/a2a/green_server.py`)
- A2A assessment flow → Episode runner: runs episodes (evidence: `medibuddy_bench/a2a_green.py`)
- A2A assessment flow → Remote agent protocol: uses protocol (evidence: `medibuddy_bench/a2a_green.py`)
- A2A assessment flow → Score aggregation: aggregates scores (evidence: `medibuddy_bench/a2a_green.py`)
- Episode runner → Run records: records runs (evidence: `medibuddy_bench/execute.py`)
- Run records → Score aggregation: supplies episodes (evidence: `medibuddy_bench/results.py`)
- Leaderboard → Run records: reads records (evidence: `medibuddy_bench/leaderboard.py`)