# heykvr/clinic-agent architecture

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

- Interactive diagram: https://gitdiagram.com/heykvr/clinic-agent
- Repository: https://github.com/heykvr/clinic-agent

## Overview

This repository is a clinic appointment-scheduling agent paired with an evaluation and policy-improvement loop. A patient chats with the agent; the agent screens for safety concerns, uses session-scoped tools to verify identity and manage appointments, and replies under a versioned policy. The evaluation loop simulates scenario conversations, checks actual clinic state and tool traces, and uses a judge for qualitative criteria; failures can lead to linted policy patches gated by re-evaluation. The map follows documented capabilities and indexed references; some unsampled implementation details are represented only where README or source-index evidence supports them.

Main entry points: [`src/clinic_agent/graph.py`](https://github.com/heykvr/clinic-agent/blob/main/src/clinic_agent/graph.py) (Turn graph), [`src/clinic_agent/evals/runner.py`](https://github.com/heykvr/clinic-agent/blob/main/src/clinic_agent/evals/runner.py) (Trial runner), [`src/clinic_agent/llm/base.py`](https://github.com/heykvr/clinic-agent/blob/main/src/clinic_agent/llm/base.py) (LLM interface), [`src/clinic_agent/chat.py`](https://github.com/heykvr/clinic-agent/blob/main/src/clinic_agent/chat.py) (Chat CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent["Scheduling agent"]
  node_chat["Chat CLI<br/>[chat.py]"]
  node_conversation["Turn graph<br/>[graph.py]"]
  node_policy["Prompt policy<br/>[policy.py]"]
  node_safety["Safety screen<br/>[safety.py]"]
  node_tools["Authorized tools<br/>[tools.py]"]
end

subgraph group_clinic["Clinic domain"]
  node_clinicdb[("Clinic state<br/>[clinic.py]")]
end

subgraph group_eval["Evaluation loop"]
  node_scenario_suite["Scenario suite<br/>[suite.yaml]"]
  node_runner["Trial runner<br/>[runner.py]"]
  node_simulator["Patient simulator<br/>[simulator.py]"]
  node_checks["Deterministic checks<br/>[checks.py]"]
  node_judge["Evidence judge<br/>[judge.py]"]
  node_improver["Policy improver<br/>[improver.py]"]
  node_loop["Improvement loop<br/>[loop.py]"]
  node_calibrate["Judge calibration<br/>[calibrate_judge.py]"]
  node_judge_gold["Judge gold labels<br/>[judge_gold.yaml]"]
end

subgraph group_models["Model providers"]
  node_llm_factory["Model factory<br/>[__init__.py]"]
  node_llm_base["LLM interface<br/>[base.py]"]
  node_anthropic["Anthropic adapter<br/>[anthropic_llm.py]"]
  node_openai["OpenAI adapter<br/>[openai_llm.py]"]
end

node_patient(("Patient"))

node_patient -->|"sends messages"| node_chat
node_chat -->|"submits turns"| node_conversation
node_chat -->|"initializes clinic"| node_clinicdb
node_chat -->|"loads policy"| node_policy
node_chat -->|"selects model"| node_llm_factory
node_conversation -->|"screens and guards"| node_safety
node_conversation -->|"dispatches tools"| node_tools
node_conversation -->|"renders prompt"| node_policy
node_conversation -->|"builds scheduling graph"| node_clinicdb
node_conversation -->|"requests model turns"| node_llm_base
node_tools -->|"reads and writes"| node_clinicdb
node_llm_factory -->|"creates adapter"| node_anthropic
node_llm_factory -->|"creates adapter"| node_openai
node_anthropic -->|"implements interface"| node_llm_base
node_openai -->|"implements interface"| node_llm_base
node_scenario_suite -->|"defines trials"| node_runner
node_runner -->|"runs agent"| node_conversation
node_runner -->|"simulates patient"| node_simulator
node_runner -->|"scores state and trace"| node_checks
node_runner -->|"requests verdicts"| node_judge
node_runner -->|"creates trial state"| node_clinicdb
node_simulator -->|"requests patient turns"| node_llm_base
node_checks -->|"reads ground truth"| node_clinicdb
node_judge -->|"requests judgments"| node_llm_base
node_judge -->|"uses check results"| node_checks
node_loop -->|"runs baseline and gate"| node_runner
node_loop -->|"requests policy patches"| node_improver
node_loop -->|"loads and promotes"| node_policy
node_improver -->|"requests diagnosis"| node_llm_base
node_improver -->|"uses failed criteria"| node_checks
node_improver -->|"patches policy"| node_policy
node_calibrate -->|"calibrates against labels"| node_judge
node_calibrate -->|"loads hand labels"| node_judge_gold

click node_chat "https://github.com/heykvr/clinic-agent/blob/main/src/clinic_agent/chat.py"
click node_conversation "https://github.com/heykvr/clinic-agent/blob/main/src/clinic_agent/graph.py"
click node_policy "https://github.com/heykvr/clinic-agent/blob/main/src/clinic_agent/policy.py"
click node_safety "https://github.com/heykvr/clinic-agent/blob/main/src/clinic_agent/safety.py"
click node_tools "https://github.com/heykvr/clinic-agent/blob/main/src/clinic_agent/tools.py"
click node_clinicdb "https://github.com/heykvr/clinic-agent/blob/main/src/clinic_agent/clinic.py"
click node_scenario_suite "https://github.com/heykvr/clinic-agent/blob/main/scenarios/suite.yaml"
click node_runner "https://github.com/heykvr/clinic-agent/blob/main/src/clinic_agent/evals/runner.py"
click node_simulator "https://github.com/heykvr/clinic-agent/blob/main/src/clinic_agent/evals/simulator.py"
click node_checks "https://github.com/heykvr/clinic-agent/blob/main/src/clinic_agent/evals/checks.py"
click node_judge "https://github.com/heykvr/clinic-agent/blob/main/src/clinic_agent/evals/judge.py"
click node_improver "https://github.com/heykvr/clinic-agent/blob/main/src/clinic_agent/evals/improver.py"
click node_loop "https://github.com/heykvr/clinic-agent/blob/main/src/clinic_agent/evals/loop.py"
click node_calibrate "https://github.com/heykvr/clinic-agent/blob/main/src/clinic_agent/evals/calibrate_judge.py"
click node_llm_factory "https://github.com/heykvr/clinic-agent/blob/main/src/clinic_agent/llm/__init__.py"
click node_llm_base "https://github.com/heykvr/clinic-agent/blob/main/src/clinic_agent/llm/base.py"
click node_anthropic "https://github.com/heykvr/clinic-agent/blob/main/src/clinic_agent/llm/anthropic_llm.py"
click node_openai "https://github.com/heykvr/clinic-agent/blob/main/src/clinic_agent/llm/openai_llm.py"
click node_judge_gold "https://github.com/heykvr/clinic-agent/blob/main/scenarios/judge_gold.yaml"

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_chat,node_conversation,node_policy,node_safety,node_tools toneBlue
class node_clinicdb toneAmber
class node_scenario_suite,node_runner,node_simulator,node_checks,node_judge,node_improver,node_loop,node_calibrate,node_judge_gold toneMint
class node_llm_factory,node_llm_base,node_anthropic,node_openai toneRose
class node_patient toneIndigo
```

## Components

### Scheduling agent

- [Chat CLI](https://github.com/heykvr/clinic-agent/blob/main/src/clinic_agent/chat.py): `src/clinic_agent/chat.py`
- [Turn graph](https://github.com/heykvr/clinic-agent/blob/main/src/clinic_agent/graph.py): `src/clinic_agent/graph.py`
- [Prompt policy](https://github.com/heykvr/clinic-agent/blob/main/src/clinic_agent/policy.py): `src/clinic_agent/policy.py`
- [Safety screen](https://github.com/heykvr/clinic-agent/blob/main/src/clinic_agent/safety.py): `src/clinic_agent/safety.py`
- [Authorized tools](https://github.com/heykvr/clinic-agent/blob/main/src/clinic_agent/tools.py): `src/clinic_agent/tools.py`

### Clinic domain

- [Clinic state](https://github.com/heykvr/clinic-agent/blob/main/src/clinic_agent/clinic.py): `src/clinic_agent/clinic.py`

### Evaluation loop

- [Scenario suite](https://github.com/heykvr/clinic-agent/blob/main/scenarios/suite.yaml): `scenarios/suite.yaml`
- [Trial runner](https://github.com/heykvr/clinic-agent/blob/main/src/clinic_agent/evals/runner.py): `src/clinic_agent/evals/runner.py`
- [Patient simulator](https://github.com/heykvr/clinic-agent/blob/main/src/clinic_agent/evals/simulator.py): `src/clinic_agent/evals/simulator.py`
- [Deterministic checks](https://github.com/heykvr/clinic-agent/blob/main/src/clinic_agent/evals/checks.py): `src/clinic_agent/evals/checks.py`
- [Evidence judge](https://github.com/heykvr/clinic-agent/blob/main/src/clinic_agent/evals/judge.py): `src/clinic_agent/evals/judge.py`
- [Policy improver](https://github.com/heykvr/clinic-agent/blob/main/src/clinic_agent/evals/improver.py): `src/clinic_agent/evals/improver.py`
- [Improvement loop](https://github.com/heykvr/clinic-agent/blob/main/src/clinic_agent/evals/loop.py): `src/clinic_agent/evals/loop.py`
- [Judge calibration](https://github.com/heykvr/clinic-agent/blob/main/src/clinic_agent/evals/calibrate_judge.py): `src/clinic_agent/evals/calibrate_judge.py`
- [Judge gold labels](https://github.com/heykvr/clinic-agent/blob/main/scenarios/judge_gold.yaml): `scenarios/judge_gold.yaml`

### Model providers

- [Model factory](https://github.com/heykvr/clinic-agent/blob/main/src/clinic_agent/llm/__init__.py): `src/clinic_agent/llm/__init__.py`
- [LLM interface](https://github.com/heykvr/clinic-agent/blob/main/src/clinic_agent/llm/base.py): `src/clinic_agent/llm/base.py`
- [Anthropic adapter](https://github.com/heykvr/clinic-agent/blob/main/src/clinic_agent/llm/anthropic_llm.py): `src/clinic_agent/llm/anthropic_llm.py`
- [OpenAI adapter](https://github.com/heykvr/clinic-agent/blob/main/src/clinic_agent/llm/openai_llm.py): `src/clinic_agent/llm/openai_llm.py`

### Other components

- **Patient**

## Connections

- Patient → Chat CLI: sends messages (evidence: `README.md`)
- Chat CLI → Turn graph: submits turns (evidence: `src/clinic_agent/chat.py`)
- Chat CLI → Clinic state: initializes clinic (evidence: `src/clinic_agent/chat.py`)
- Chat CLI → Prompt policy: loads policy (evidence: `src/clinic_agent/chat.py`)
- Chat CLI → Model factory: selects model (evidence: `src/clinic_agent/chat.py`)
- Turn graph → Safety screen: screens and guards (evidence: `src/clinic_agent/graph.py`)
- Turn graph → Authorized tools: dispatches tools (evidence: `src/clinic_agent/graph.py`)
- Turn graph → Prompt policy: renders prompt (evidence: `src/clinic_agent/graph.py`)
- Turn graph → Clinic state: builds scheduling graph (evidence: `src/clinic_agent/graph.py`)
- Turn graph → LLM interface: requests model turns (evidence: `src/clinic_agent/graph.py`)
- Authorized tools → Clinic state: reads and writes (evidence: `src/clinic_agent/tools.py`)
- Model factory → Anthropic adapter: creates adapter (evidence: `src/clinic_agent/llm/__init__.py`)
- Model factory → OpenAI adapter: creates adapter (evidence: `src/clinic_agent/llm/__init__.py`)
- Anthropic adapter → LLM interface: implements interface (evidence: `src/clinic_agent/llm/anthropic_llm.py`)
- OpenAI adapter → LLM interface: implements interface (evidence: `src/clinic_agent/llm/openai_llm.py`)
- Scenario suite → Trial runner: defines trials (evidence: `README.md`)
- Trial runner → Turn graph: runs agent (evidence: `src/clinic_agent/evals/runner.py`)
- Trial runner → Patient simulator: simulates patient (evidence: `src/clinic_agent/evals/runner.py`)
- Trial runner → Deterministic checks: scores state and trace (evidence: `src/clinic_agent/evals/runner.py`)
- Trial runner → Evidence judge: requests verdicts (evidence: `src/clinic_agent/evals/runner.py`)
- Trial runner → Clinic state: creates trial state (evidence: `src/clinic_agent/evals/runner.py`)
- Patient simulator → LLM interface: requests patient turns (evidence: `src/clinic_agent/evals/simulator.py`)
- Deterministic checks → Clinic state: reads ground truth (evidence: `src/clinic_agent/evals/checks.py`)
- Evidence judge → LLM interface: requests judgments (evidence: `src/clinic_agent/evals/judge.py`)
- Evidence judge → Deterministic checks: uses check results (evidence: `src/clinic_agent/evals/judge.py`)
- Improvement loop → Trial runner: runs baseline and gate (evidence: `src/clinic_agent/evals/loop.py`)
- Improvement loop → Policy improver: requests policy patches (evidence: `src/clinic_agent/evals/loop.py`)
- Improvement loop → Prompt policy: loads and promotes (evidence: `src/clinic_agent/evals/loop.py`)
- Policy improver → LLM interface: requests diagnosis (evidence: `src/clinic_agent/evals/improver.py`)
- Policy improver → Deterministic checks: uses failed criteria (evidence: `src/clinic_agent/evals/improver.py`)
- Policy improver → Prompt policy: patches policy (evidence: `src/clinic_agent/evals/improver.py`)
- Judge calibration → Evidence judge: calibrates against labels (evidence: `src/clinic_agent/evals/calibrate_judge.py`)
- Judge calibration → Judge gold labels: loads hand labels (evidence: `src/clinic_agent/evals/calibrate_judge.py`)
