How heykvr/clinic-agent works
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: graph.py Turn graph · runner.py Trial runner · base.py LLM interface · chat.py Chat CLI
Components 20
Scheduling agent
- Chat CLI
src/clinic_agent/chat.py - Turn graph
src/clinic_agent/graph.py - Prompt policy
src/clinic_agent/policy.py - Safety screen
src/clinic_agent/safety.py - Authorized tools
src/clinic_agent/tools.py
Clinic domain
- Clinic state
src/clinic_agent/clinic.py
Evaluation loop
- Scenario suite
scenarios/suite.yaml - Trial runner
src/clinic_agent/evals/runner.py - Patient simulator
src/clinic_agent/evals/simulator.py - Deterministic checks
src/clinic_agent/evals/checks.py - Evidence judge
src/clinic_agent/evals/judge.py - Policy improver
src/clinic_agent/evals/improver.py - Improvement loop
src/clinic_agent/evals/loop.py - Judge calibration
src/clinic_agent/evals/calibrate_judge.py - Judge gold labels
scenarios/judge_gold.yaml
Model providers
- Model factory
src/clinic_agent/llm/__init__.py - LLM interface
src/clinic_agent/llm/base.py - Anthropic adapter
src/clinic_agent/llm/anthropic_llm.py - OpenAI adapter
src/clinic_agent/llm/openai_llm.py
Other components
- Patient
Connections 33
- Patient → Chat CLI: sends messages
README.md - Chat CLI → Turn graph: submits turns
src/clinic_agent/chat.py - Chat CLI → Clinic state: initializes clinic
src/clinic_agent/chat.py - Chat CLI → Prompt policy: loads policy
src/clinic_agent/chat.py - Chat CLI → Model factory: selects model
src/clinic_agent/chat.py - Turn graph → Safety screen: screens and guards
src/clinic_agent/graph.py - Turn graph → Authorized tools: dispatches tools
src/clinic_agent/graph.py - Turn graph → Prompt policy: renders prompt
src/clinic_agent/graph.py - Turn graph → Clinic state: builds scheduling graph
src/clinic_agent/graph.py - Turn graph → LLM interface: requests model turns
src/clinic_agent/graph.py - Authorized tools → Clinic state: reads and writes
src/clinic_agent/tools.py - Model factory → Anthropic adapter: creates adapter
src/clinic_agent/llm/__init__.py - Model factory → OpenAI adapter: creates adapter
src/clinic_agent/llm/__init__.py - Anthropic adapter → LLM interface: implements interface
src/clinic_agent/llm/anthropic_llm.py - OpenAI adapter → LLM interface: implements interface
src/clinic_agent/llm/openai_llm.py - Scenario suite → Trial runner: defines trials
README.md - Trial runner → Turn graph: runs agent
src/clinic_agent/evals/runner.py - Trial runner → Patient simulator: simulates patient
src/clinic_agent/evals/runner.py - Trial runner → Deterministic checks: scores state and trace
src/clinic_agent/evals/runner.py - Trial runner → Evidence judge: requests verdicts
src/clinic_agent/evals/runner.py - Trial runner → Clinic state: creates trial state
src/clinic_agent/evals/runner.py - Patient simulator → LLM interface: requests patient turns
src/clinic_agent/evals/simulator.py - Deterministic checks → Clinic state: reads ground truth
src/clinic_agent/evals/checks.py - Evidence judge → LLM interface: requests judgments
src/clinic_agent/evals/judge.py - Evidence judge → Deterministic checks: uses check results
src/clinic_agent/evals/judge.py - Improvement loop → Trial runner: runs baseline and gate
src/clinic_agent/evals/loop.py - Improvement loop → Policy improver: requests policy patches
src/clinic_agent/evals/loop.py - Improvement loop → Prompt policy: loads and promotes
src/clinic_agent/evals/loop.py - Policy improver → LLM interface: requests diagnosis
src/clinic_agent/evals/improver.py - Policy improver → Deterministic checks: uses failed criteria
src/clinic_agent/evals/improver.py - Policy improver → Prompt policy: patches policy
src/clinic_agent/evals/improver.py - Judge calibration → Evidence judge: calibrates against labels
src/clinic_agent/evals/calibrate_judge.py - Judge calibration → Judge gold labels: loads hand labels
src/clinic_agent/evals/calibrate_judge.py