How pprathik07/self-improving-clinic-agent works
This repository is a clinic appointment-scheduling agent with an accompanying evaluation harness and policy-improvement loop. The main user workflow runs a conversation through identity verification, intent and availability selection, confirmation, and a guarded appointment action against clinic data. The evaluation workflow exercises scenarios and checks database/session outcomes, tool traces, and judge assessments; improvement uses train failures to propose policy-only patches and gates reruns. The graph follows documented and indexed relationships; unsampled implementation details are represented only where the README or source index supports them.
Main entry points: runner.py Conversation Runner · run_eval.py Scenario Eval Runner · improve.py Improvement Orchestrator · db.py Clinic Database
Components 22
Scheduling Agent
- Conversation Runner
clinic_agent/agent/runner.py - State Machine
clinic_agent/agent/machine.py - Session State
clinic_agent/agent/state.py - Policy Loader
clinic_agent/agent/policy.py - Policy Rules
policy/policy_v1.yaml - LLM Adapter
clinic_agent/llm.py
Clinic Domain
- Scheduling Tools
clinic_agent/tools/impl.py - Safety Guards
clinic_agent/tools/guards.py - Clinic Database
clinic_agent/clinic/db.py - Clinic Models
clinic_agent/clinic/models.py
Evaluation Harness
- Scenario Eval Runner
clinic_agent/evals/run_eval.py - Scenario Schema
clinic_agent/evals/scenario_schema.py - Patient Simulator
clinic_agent/evals/simulator.py - State And Trace Scorers
clinic_agent/evals/scorers.py - LLM Judge
clinic_agent/evals/judge.py - Failure Reports
clinic_agent/evals/failures.py - Results Report
clinic_agent/evals/report.py
Policy Improvement
- Improvement Orchestrator
clinic_agent/loop/improve.py - Failure Reflector
clinic_agent/loop/reflector.py - Patch Validator
clinic_agent/loop/patch.py - Regression Gate
clinic_agent/loop/gate.py
Other components
- Patient
Connections 28
- Patient → Conversation Runner: converses with
README.md - Conversation Runner → Policy Loader: loads policy
clinic_agent/agent/runner.py - Policy Loader → Policy Rules: reads rules
README.md - Conversation Runner → State Machine: checks transitions
clinic_agent/agent/runner.py - Conversation Runner → Session State: tracks conversation
clinic_agent/agent/runner.py - Conversation Runner → LLM Adapter: requests responses
clinic_agent/agent/runner.py - Conversation Runner → Scheduling Tools: dispatches tool calls
clinic_agent/agent/runner.py - Conversation Runner → Clinic Database: initializes database
clinic_agent/agent/runner.py - Scheduling Tools → Safety Guards: applies checks
clinic_agent/tools/impl.py - Scheduling Tools → Clinic Database: reads and writes
clinic_agent/tools/impl.py - Safety Guards → Clinic Database: checks ownership and slots
clinic_agent/tools/guards.py - Clinic Database → Clinic Models: uses domain types
clinic_agent/clinic/db.py - Scenario Eval Runner → Scenario Schema: loads scenarios
clinic_agent/evals/run_eval.py - Scenario Eval Runner → Patient Simulator: runs patient turns
clinic_agent/evals/run_eval.py - Scenario Eval Runner → Conversation Runner: executes conversations
clinic_agent/evals/run_eval.py - Scenario Eval Runner → State And Trace Scorers: scores outcomes
clinic_agent/evals/run_eval.py - Scenario Eval Runner → LLM Judge: requests assessment
clinic_agent/evals/run_eval.py - Scenario Eval Runner → Failure Reports: records failures
clinic_agent/evals/run_eval.py - Patient Simulator → LLM Adapter: generates patient turns
clinic_agent/evals/simulator.py - LLM Judge → LLM Adapter: requests judgment
clinic_agent/evals/judge.py - Improvement Orchestrator → Scenario Eval Runner: runs evaluations
clinic_agent/loop/improve.py - Improvement Orchestrator → Failure Reports: prepares failure summaries
clinic_agent/loop/improve.py - Improvement Orchestrator → Failure Reflector: requests patch proposal
clinic_agent/loop/improve.py - Failure Reflector → Patch Validator: produces structured patch
clinic_agent/loop/reflector.py - Improvement Orchestrator → Patch Validator: validates patch
clinic_agent/loop/improve.py - Patch Validator → Policy Loader: updates policy sections
clinic_agent/loop/patch.py - Improvement Orchestrator → Regression Gate: checks regression results
clinic_agent/loop/improve.py - Improvement Orchestrator → Results Report: renders comparison
clinic_agent/loop/improve.py