CareFlow — Multi-Agent Patient Operations Platform

A clinic's front office, run by a coordinated team of AI agents: patient intake, request routing, scheduling, follow-ups and manager insights with a multi-role web UI (Patient / Front Desk / Manager) and a full audit trail.

Demo project with synthetic data. CareFlow performs clinic operations only it never gives medical advice. Anything clinical, ambiguous or urgent is escalated to a human. See "Safety design" below.

---

Architecture

                     SUPERVISOR (LangGraph)
      ┌──────────┬───────────┼────────────┬─────────────┐
   INTAKE     ROUTING     SCHEDULING   FOLLOW-UP     INSIGHTS
   extracts   classifies  finds/books  reminders,    manager
   structured type +      slots via    surveys       dashboard
   record     urgency,    booking      (human-       (volumes,
   from free  routes or   tools        approved)     trends,
   text       ESCALATES                              summaries)

Status: All five agents complete Intake, Routing, Scheduling, Follow-up and Insights orchestrated by a conditional LangGraph pipeline, with three UI roles (Patient / Front Desk / Manager), idempotent booking, human-approval gates, a full audit trail, and an evaluation suite.

Evaluation results (golden set, 10 cases)

Metric	Score
Request-type accuracy	100%
Urgency accuracy	100%
Escalation accuracy	100%
Safety misses (should-escalate that didn't)	0

The eval suite caught a real gap during development: the model didn't escalate a test-results request. The fix was a deterministic policy rule in code (test results and prescription refills always require human review), not a prompt tweak — safety-critical behaviour should never depend on the model alone. Run the evals anytime with python evals/run_evals.py.

What makes this more than a chatbot

• One agent, one job. Intake only extracts; Routing only decides. Small prompts, clear boundaries, independently testable.
• Defense in depth. The LLM classifies urgency, but a deterministic red-flag safety net runs after it — emergency terms force escalation no matter what the model says. Safety-critical branches never rely on a model alone.
• Escalate on doubt. Symptoms, ambiguity, or urgency → a human reviews it.
• Audit everything. Every agent decision is recorded and inspectable in the UI — "why did the AI do that?" always has an answer.
• Idempotent by design. (Phase 2) booking tools can run twice without double-booking.

Two ways to run it

CareFlow ships with a production-shaped architecture a FastAPI backend (the agents as a REST service) and a Next.js frontend plus a Streamlit app for quick demos.

Option A Full product (FastAPI + Next.js)

# 1. Install and configure
pip install -r requirements.txt
# copy .env.example to .env and add your free Groq key (console.groq.com/keys)

# 2. Start the API (terminal 1)
uvicorn api:app --port 8000
# interactive docs: http://localhost:8000/docs

# 3. Start the frontend (terminal 2)
cd frontend
npm install
npm run dev
# open http://localhost:3000

Option B Quick demo (Streamlit)

pip install -r requirements.txt
streamlit run app.py

Either way: try the Patient view (submit a request), then Front Desk to see it classified, routed, scheduled and queued — then Manager for the dashboard.

Safety design (honest notes)

• No medical advice, diagnosis or clinical judgement — hard boundary in every prompt.
• Deterministic emergency safety net on top of LLM classification.
• All data is synthetic; no real patient information anywhere.
• This demo is HIPAA-aware (audit trail, role separation, minimal data), not HIPAA-certified — a real deployment would need BAAs, encryption at rest, access controls and compliance review.

Tech stack

Backend: Python · FastAPI · LangGraph · Groq (Llama-3.3-70B, JSON mode) · Pydantic v2 · SQLite Frontend: Next.js 15 · React 19 · TypeScript · Tailwind CSS Alt UI: Streamlit (quick demos)