Clinical Flow Coordinator

An AI-powered clinical workflow orchestration system that automates diagnostic exam scheduling, patient readiness assessment, consent verification, financial clearance, and care team coordination using Google's MedGemma LLM.

Built for the MedGemma Impact Challenge on Kaggle.

Architecture

The system uses a multi-agent architecture with 7 specialized reasoning agents:

Agent	Role	Output
AcuityReasoner	Triage — analyzes vitals & procedure urgency	EMERGENT / URGENT / ROUTINE
ReadinessReasoner	Checklist — verifies clinical prerequisites (NPO, labs, IV)	Blocking / non-blocking items
ComplianceReasoner	Consent — evaluates decision-making capacity	COMPLETED / REQUIRED_MISSING
FinancialClearanceReasoner	Prior Auth — assesses insurance & PA requirements	APPROVED / REQUIRED_MISSING
ResourceCoordinationReasoner	ETA — estimates wait time	Minutes until ready
OperationalPrioritizationReasoner	Priority — computes dynamic priority score	0.0–1.0 score
CareTeamCommunicationAgent	Communication — generates role-specific dispatch messages	Actionable messages for RN, Coordinator, Financial

Agents 1–5 run in parallel, followed by sequential execution of Priority and Communication agents. Results are streamed to the UI in real-time via Server-Sent Events (SSE).

Design Patterns

• Blackboard Pattern — shared ClinicalBlackboard for inter-agent communication
• Structured Output Validation — Pydantic models enforce LLM response format
• Human-in-the-Loop Gate — clinician approval before EHR writes
• Dual-Mode LLM Client — Vertex AI or local GPU inference
• Streaming SSE — real-time agent workflow updates to frontend

Tech Stack

Category	Technologies
Language	Python 3.10+
Web Framework	FastAPI + Uvicorn
Frontend	Vue.js 3 (embedded SPA)
Data Validation	Pydantic v2
LLM	Google MedGemma (Vertex AI or local HuggingFace)
ASR	Google MedASR
ML Libraries	PyTorch, Transformers
Cloud	Google Cloud (Vertex AI, Cloud Healthcare API)
API Standard	FHIR Bundles, REST

Project Structure

├── api_server.py                  # REST API + Vue.js dashboard
├── clinical_flow_coordinator.py   # Multi-agent orchestration & LLM client
├── domain_model.py                # Pydantic data models & enums
├── intent_engine.py               # Clinical intent inference logic
├── pyproject.toml                 # Project configuration & dependencies
├── uv.lock                        # Dependency lock file
└── static/
    └── vue.js                     # Vue.js library

Prerequisites

• Python 3.10+
• uv package manager
• Google Cloud project with Vertex AI enabled (for Vertex mode)
• GPU with CUDA support (for local mode)

Setup

1. Clone the repository

   git clone <repository-url>
   cd 0224_17am

2. Install dependencies

   uv sync

3. Configure environment variables

   # Google Cloud
   export GCP_PROJECT_ID="your-project-id"
   export VERTEX_LOCATION="us-central1"
   
   # MedGemma
   export VERTEX_MEDGEMMA_LOCATION="us-central1"
   export VERTEX_MEDGEMMA_MODEL_ID="your-model-id"
   export VERTEX_MEDGEMMA_ENDPOINT="your-endpoint"     # optional, for deployed endpoint
   
   # MedASR (optional)
   export VERTEX_MEDASR_LOCATION="us-central1"
   export MEDASR_MODEL_ID="your-medasr-model-id"
   export MEDASR_ENDPOINT="your-medasr-endpoint"
   
   # Authentication tokens
   export ORCHESTRATOR_READ_TOKEN="your-read-token"
   export CLINICIAN_WRITE_TOKEN="your-write-token"
   
   # Backend mode: "vertex" (default) or "local"
   export MODEL_BACKEND="vertex"
   
   # Optional features
   export ENABLE_SA_IMPERSONATION="false"
   export ENABLE_CLOUD_HEALTHCARE_WRITE="false"

4. Authenticate with Google Cloud (Vertex mode)

   gcloud auth application-default login

Usage

Start the server:

uv run uvicorn api_server:app --host 0.0.0.0 --port 8000

Open http://localhost:8000 in your browser to access the dashboard.

Dashboard

The Vue.js dashboard provides a 3-column layout:

• Left — EMR panel with patient clinical data
• Center — Patient queue with dynamic priority ranking and agent execution logs
• Right — Chat interface with AI responses and MedASR voice input

Demo Scenarios

5 predefined patient scenarios are available in the dashboard:

Patient	Scenario	Key Feature
P1 (Lee, S.)	Routine chest CT	Standard workflow
P2 (Park, J.)	Prep blocker	Outdated creatinine lab
P3 (Kim, D.)	Consent issue	Confused patient requiring surrogate
P4 (Choi, M.)	STAT emergency	Acute mental status change
P5 (Han, K.)	PA blocker	HMO prior authorization required

API Endpoints

Endpoint	Method	Description
/	GET	Dashboard UI
/api/flow/run_patient_stream	POST	Stream clinical workflow orchestration
/api/chat/tool_call	POST	LLM-based tool routing
/api/asr/transcribe	POST	MedASR audio transcription
/api/fhir/draft	POST	Generate FHIR bundle
/api/hitl/approve_execute	POST	Human-in-the-loop approval gate
/api/system/gpu	GET	GPU telemetry

License

This project is part of the MedGemma Impact Challenge submission.