Skip to content

fariha548/MediGuard-AI

BranchesTags

Repository files navigation

🏥 MediGuard-AI

Multi-Agent Clinical Intelligence System

Google Cloud Rapid Agent Hackathon — Building Agents for Real-World Challenges

License: MIT Python 3.11+ Gemini Arize Phoenix OpenInference GCP HIPAA HL7 FHIR PDPA

🌐 Live Demo

Service URL
Clinical Dashboard https://mediguard-ai-602145185457.asia-southeast1.run.app/dashboard
API Root https://mediguard-ai-602145185457.asia-southeast1.run.app
Phoenix Observability https://phoenix-server-602145185457.asia-southeast1.run.app
API Docs https://mediguard-ai-602145185457.asia-southeast1.run.app/docs

🚨 Problem Statement

Problem 1: Fragmented Patient Data

70% of healthcare leaders globally cite data silos as their #1 challenge. Patient records are trapped across hospitals, clinics, labs, and pharmacies — leading to:

  • Duplicate tests and procedures
  • Missed allergies and drug interactions
  • Delayed critical care decisions

Problem 2: Diagnostic Blind Spots

Clinicians make time-critical decisions without real-time evidence synthesis, leading to:

  • Delayed differential diagnosis
  • Outdated treatment protocols
  • Missed red flag symptoms

Problem 3: Medication-Nutrient Conflicts

Chronic patients receive diet plans without cross-referencing their medication list, causing:

  • Dangerous drug-nutrient interactions (e.g. Warfarin ↔ Vitamin K)
  • Unsafe dietary advice for renal/diabetic patients
  • No personalised caloric planning

Problem 4: No Real-Time Evidence at Point of Care

Clinicians lack instant access to current guidelines during consultations, leading to:

  • Decisions based on outdated protocols
  • Missed evidence-based interventions
  • No PICO-structured research synthesis

💡 Solution: MediGuard-AI Multi-Agent System

An 8-agent clinical intelligence platform powered by Gemini 3.1 Flash Lite + Arize Phoenix MCP — giving every agent full traceability, self-introspection, and LLM-as-a-Judge evaluation at point of care.

Every agent call is automatically traced via OpenInference auto-instrumentation, sent to a self-hosted Phoenix server on Cloud Run, and evaluated in real-time with LLM-as-a-Judge evals. The system can query its own traces at runtime and use Gemini to generate self-improvement recommendations — a complete observability-to-improvement loop.

🔭 Arize Phoenix Integration

OpenInference Auto-Instrumentation

Every Gemini API call is automatically traced using the OpenInference instrumentor:

from phoenix.otel import register
from openinference.instrumentation.google_genai import GoogleGenAIInstrumentor

# Self-hosted Phoenix on Cloud Run
PHOENIX_URL = "https://phoenix-server-602145185457.asia-southeast1.run.app"

tracer_provider = register(
    project_name="mediguard-ai",
    endpoint=f"{PHOENIX_URL}/v1/traces",
)
GoogleGenAIInstrumentor().instrument(tracer_provider=tracer_provider)

This instruments all 8 agents automatically — zero manual span creation needed.

Self-Hosted Phoenix on Cloud Run

MediGuard-AI runs its own Phoenix observability server on Google Cloud Run (asia-southeast1), giving full production-grade tracing with no external dependency on Phoenix Cloud.

Phoenix MCP — Agent Self-Introspection

The agent queries its own Phoenix traces at runtime via the MCP server and uses Gemini to analyze its performance:

POST /agent/introspect

The self-improvement loop:

  1. Agent fetches its own spans from Phoenix (/v1/projects/UHJvamVjdDoy/spans)
  2. Gemini 3.1 Flash Lite analyzes the trace data
  3. System generates performance insights + self-improvement recommendations
  4. Confidence score and system health status returned

LLM-as-a-Judge Evaluations

POST /run/evals

Three evaluation dimensions run on every traced span:

Eval Label Options Measures
sentiment_accuracy correct / incorrect / uncertain Is the sentiment label accurate?
hallucination_guard grounded / hallucinated / partial Does the response contain fabricated facts?
response_relevance relevant / irrelevant / partial Is the response on-topic?

Eval results are automatically posted back to Phoenix (/v1/evaluations) — closing the observe → evaluate → improve loop.

🤖 Agent Architecture — 8 Agents

Phase 1 Agents ✅

👨‍⚕️ Clinician Agent (agents/clinician_agent.py)

  • Unified Patient View — aggregates data from 7 databases
  • Drug interaction detection + allergy cross-referencing
  • Critical lab flag detection
  • Medication reconciliation across facilities

🧑‍⚕️ Patient Agent (agents/patient_agent.py)

  • Real-time procedure cost estimates
  • Hospital comparison (cost + quality)
  • Insurance out-of-pocket calculator
  • Pre-authorization alerts

Phase 2 Agents ✅

🩺 MD Agent (agents/md_agent.py)

  • RED/AMBER/GREEN triage classification
  • Ranked differential diagnosis (up to 5 differentials)
  • Evidence-based workup recommendations
  • Safety alerts wired to ClinicalSafetyEngine
  • Phoenix MCP tracing on every reasoning step

🥗 Nutritionist Agent (agents/nutritionist_agent.py)

  • Drug-nutrient conflict detection (6+ medication classes)
  • Mifflin-St Jeor TDEE calculation
  • Condition-specific diet templates (diabetes, renal, hypertension, obesity)
  • Meal timing guidance
  • Safety flags for HIGH severity conflicts

🔬 Researcher Agent (agents/researcher_agent.py)

  • Live evidence synthesis via Gemini 3.1 Flash Lite
  • PICO framework extraction
  • Real-time guideline retrieval (ESC, ADA, KDIGO, WHO)
  • Fallback evidence cache for offline resilience
  • Full Phoenix MCP tracing

Phase 3 Agents ✅

📋 Intake Agent (agents/intake_agent.py)

  • InstantScan Onboarding — walk-in patients with zero digital record
  • Gemini Vision document extraction (X-Ray, Lab Reports, Prescriptions)
  • HL7 FHIR R4 Patient resource creation with temporary MRN
  • HIPAA §164.512 emergency treatment exception
  • PDPA Section 17 vital interest processing
  • Auto-triage: RED / ORANGE / YELLOW priority assignment

💬 Sentiment Agent (agents/sentiment_agent.py)

  • Patient review analysis at hospital/city level
  • Batch processing with optional BigQuery storage
  • Topic + keyword extraction
  • MCP config endpoint for integration

🚨 Emergency Agent (/agent/emergency)

  • Biometric emergency scan (fingerprint hash + national ID)
  • Multi-country ID type support (Pakistan CNIC, UAE Emirates ID, KSA Iqama)
  • Instant family alert on patient identification
  • Critical allergy + condition surfacing for unconscious patients

🔄 Self-Improvement Loop

Agent Call
    ↓
OpenInference Auto-Instrumentation
    ↓
Phoenix Traces (self-hosted Cloud Run)
    ↓
/agent/introspect — MCP Query
    ↓
Gemini 3.1 Flash Lite Analysis
    ↓
Performance Insights + Recommendations
    ↓
/run/evals — LLM-as-a-Judge
    ↓
Eval Scores posted back to Phoenix
    ↓
Agent improves next call

🏗️ System Architecture

graph TB
    subgraph "UI Layer"
        DASH[Clinical Dashboard\ndashboard URL]
    end

    subgraph "Agent Layer — Cloud Run"
        MDA[MD Agent]
        NTA[Nutritionist Agent]
        RSA[Researcher Agent]
        CAG[Clinician Agent]
        PAG[Patient Agent]
        INA[Intake Agent]
        SNA[Sentiment Agent]
        EMA[Emergency Agent]
    end

    subgraph "Observability — Arize Phoenix MCP"
        PHX[Phoenix Server\nSelf-hosted Cloud Run\nasia-southeast1]
        SPANS[Spans + Traces]
        EVALS[LLM-as-a-Judge Evals]
        INTRO[Self-Introspection\nMCP Query]
    end

    subgraph "AI Layer"
        GEM[Gemini 3.1 Flash Lite\nJudge + Analysis]
        OI[OpenInference\nAuto-Instrumentation]
    end

    subgraph "Compliance Layer"
        HIPAA[HIPAA §164.312]
        FHIR[HL7 FHIR R4]
        PDPA[PDPA Section 17]
        CSE[ClinicalSafetyEngine\nAudit Trail]
    end

    subgraph "Data Layer"
        MCP[MCP Toolbox Server]
        HOSP[(Hospital EHR)]
        LAB[(Lab System)]
        PHARM[(Pharmacy)]
        INS[(Insurance)]
    end

    DASH --> MDA & NTA & RSA & CAG & PAG & INA & SNA & EMA
    MDA & NTA & RSA & CAG & SNA --> OI
    OI --> PHX
    PHX --> SPANS
    SPANS --> EVALS
    SPANS --> INTRO
    INTRO --> GEM
    GEM --> EVALS
    MDA & INA & CAG --> CSE
    INA --> HIPAA & FHIR & PDPA
    CAG & PAG --> MCP
    MCP --> HOSP & LAB & PHARM & INS
Loading

🔒 Compliance Architecture

HIPAA (Health Insurance Portability and Accountability Act)

  • §164.312(a)(1) — Emergency access procedure implemented in IntakeAgent
  • §164.312(b) — Audit controls via _audit_log() on every intake event
  • §164.512 — Emergency treatment exception for walk-in patients
  • PHI never committed to version control (.gitignore enforced)
  • Fortress SDK security gateway blocks PHI leakage

HL7 FHIR R4

  • IntakeAgent creates valid FHIR R4 Patient resources with temporary MRN
  • DocumentReference resource for scanned documents
  • FHIR identifier system: https://mediguard.ai/fhir/temp-identifier
  • Compliance metadata embedded in every Patient resource

PDPA (Personal Data Protection Act — Singapore)

  • Section 17 — Vital interest exception for emergency processing
  • Minimal data principle enforced
  • Patient conscious → full consent flow; unconscious → vital interest exception

Security (Fortress SDK)

  • .gitignore blocks all SDK files from public repo
  • mediguard/security/gateway.py — public interface only
  • GitHub Actions security gate on every push
  • PHI data never committed to version control

🛠️ Tech Stack

Layer Technology
AI Model Gemini 3.1 Flash Lite
Agent Framework FastAPI + Custom Agent Architecture
Instrumentation OpenInference google_genai Auto-Instrumentor
Observability Arize Phoenix MCP — Self-hosted on Cloud Run
Evals LLM-as-a-Judge via Gemini 3.1 Flash Lite
Self-Introspection Phoenix MCP /v1/projects/.../spans
Compliance HIPAA §164.312 + HL7 FHIR R4 + PDPA Section 17
Safety ClinicalSafetyEngine + Audit Trail
Database SQLite (demo) → Cloud SQL (production)
Deployment Google Cloud Run — asia-southeast1
Security Fortress SDK (private)
Language Python 3.11+

🚀 Quick Start

# Clone
git clone https://github.com/fariha548/MediGuard-AI.git
cd MediGuard-AI

# Setup
python -m venv venv
venv\Scripts\activate  # Windows
# source venv/bin/activate  # Linux/Mac
pip install -r requirements.txt

# Configure
cp .env.example .env
# Add your GEMINI_API_KEY and PHOENIX_URL to .env

# Run locally
uvicorn main:app --host 0.0.0.0 --port 8080

# Open dashboard
# http://localhost:8080/dashboard

📡 API Endpoints

Method Endpoint Agent Description
GET /dashboard — Clinical Intelligence Dashboard
GET / — System status
GET /health — Health check
POST /agent/md MD Agent Triage + differential diagnosis
POST /agent/clinician Clinician Patient data aggregation
POST /agent/patient Patient Cost + insurance queries
POST /agent/nutritionist Nutritionist Drug-nutrient conflict + diet
POST /agent/researcher Researcher Evidence synthesis (PICO)
POST /agent/intake Intake Walk-in patient onboarding
POST /agent/sentiment Sentiment Patient review analysis
POST /agent/emergency Emergency Biometric emergency scan
POST /agent/introspect Self-Introspect Phoenix MCP self-analysis
POST /run/evals Judge LLM-as-a-Judge evaluations

📁 Project Structure

MediGuard-AI/
├── agents/
│   ├── clinical_safety_engine.py  # Safety + audit trail
│   ├── clinician_agent.py         # Phase 1 ✅
│   ├── patient_agent.py           # Phase 1 ✅
│   ├── md_agent.py                # Phase 2 ✅
│   ├── nutritionist_agent.py      # Phase 2 ✅
│   ├── researcher_agent.py        # Phase 2 ✅
│   ├── intake_agent.py            # Phase 3 ✅ HIPAA+FHIR+PDPA
│   └── sentiment_agent.py         # Phase 3 ✅
├── databases/
│   ├── db_manager.py
│   └── seed/seed_data.py
├── static/
│   └── index.html                 # Clinical Dashboard UI
├── tools/
│   ├── mcp_server.py              # MCP Toolbox + Emergency scan
│   ├── vision_analyzer.py         # Gemini Vision for Intake
│   └── test_simple.py
├── mediguard/security/gateway.py  # Fortress SDK interface
├── evals.py                       # LLM-as-a-Judge pipeline
├── main.py                        # FastAPI app + OpenInference setup
├── Dockerfile
├── .env.example
├── .gitignore
├── LICENSE
└── README.md

✅ Live Agent Responses — Tested & Verified

Agent Status Sample Output
MD Agent ✅ Live RED triage — Pulmonary Embolism, ACS, Heart Failure differentials
Clinician Agent ✅ Live Unified patient view — drug interactions + allergy cross-referencing
Nutritionist Agent ✅ Live Metformin↔B12 conflict detected — 2073 kcal personalised meal plan
Researcher Agent ✅ Live ACC/AHA 2023 guideline — INR 3.2 management with evidence level B-R
Emergency Agent ✅ Live NADRA CNIC 35201-1234567-1 → IDENTIFIED SG-2024-001
Intake Agent ✅ Live FHIR MRN TEMP-20260610090602 created — YELLOW triage forwarded
Sentiment Agent ✅ Live Positive 0.90 — Aga Khan Hospital emergency team review
Patient Agent ⚠️ In Progress Pricing DB migration in progress — endpoint live

🔭 Observability Results

Metric Value
Total Traces 24
Latency P50 989ms
Latency P99 13.7s
Total Cost $0
Eval Score — Sentiment Accuracy 1.0 ✅
Eval Score — Response Relevance 1.0 ✅
Hallucination Guard 0.0 ⚠️ (eval calibration needed)
Self-Introspection Confidence 0.95 ✅
System Health Healthy

🩺 MD Agent — Sample Response

Query: Patient presents with chest pain, shortness of breath, history of atrial fibrillation | MRN: SG-2024-001

🔴 TRIAGE LEVEL: RED Differentials: [1] Pulmonary Embolism — CRITICAL [2] Acute Coronary Syndrome — CRITICAL [3] Decompensated Heart Failure — HIGH [4] Rapid Atrial Fibrillation — HIGH [5] Pneumonia — MODERATE

🚨 Emergency Agent — Sample Response

Query: National ID: 35201-1234567-1 | ID Type: Pakistan NADRA CNIC | Country: PK

Status: IDENTIFIED · SG-2024-001 Method: National ID — PK:NADRA HIPAA Exception: Emergency Treatment — 45 CFR §164.512 Family Alert: Sent

🔬 Researcher Agent — Sample Response

Query: Latest evidence for anticoagulation therapy in atrial fibrillation | MRN: SG-2024-001

Guideline : 2023 ACC/AHA/ACCP/HRS Guideline for AF Management Finding : INR 3.2 — omit/reduce Warfarin dose, monitor INR frequently Evidence : Level B-R (Moderate quality, randomized trials) Source : January, C.T. et al. JACC 2023

🥗 Nutritionist Agent — Sample Response

Query: Diet plan for patient on Warfarin with cardiac conditions | MRN: SG-2024-001

Drug-Nutrient Conflict : Metformin ↔ Vitamin B12 [MODERATE] Daily Calories : 2073 kcal/day (Mifflin-St Jeor) Macros : Carbs 45% | Protein 25% | Fat 30% Condition Template : Diabetes — Low GI foods, avoid refined sugars

| Patient Agent | ⚠️ In Progress | Pricing DB migration in progress — endpoint live, cost query under fix |

Note: Patient Agent endpoint is live and routing correctly. Procedure cost queries return null due to pricing database seeding limitation in Cloud Run ephemeral storage. Fix in progress — Cloud SQL migration planned for production.

🏆 Hackathon

Google Cloud Rapid Agent Hackathon Building Agents for Real-World Challenges
Track Arize Phoenix ($10K prize pool)
Submission deadline June 11, 2026 — 2:00 PM PDT
Devpost fariha80imr

📄 License

MIT License — see LICENSE for details.

Built with ❤️ for real-world healthcare challenges — tested live across global deployments Powered by Gemini 3.1 Flash Lite + Arize Phoenix MCP + OpenInference Auto-Instrumentation

About

Multi-Agent Clinical Intelligence System — Gemini + Arize Phoenix MCP

mediguard-ai-602145185457.asia-southeast1.run.app

Topics

mcp google-cloud gemini healthcare-ai arize-phoenix

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages