vitalview-labs

# VitalView Labs **Making lab reports patient-friendly** *A FutureFramesAI Project — The Future, Frame by Frame* --- ## What is VitalView Labs? VitalView Labs is an AI-powered lab report simplifier that transforms complex medical lab reports into patient-friendly educational summaries. It uses a multi-agent AI architecture where three specialist AI agents collaborate to extract, analyze, and simplify lab results — with a doctor approving everything before the patient sees it. **Three Pillars:** AI-Powered · Doctor-Verified · Patient-Friendly --- ## Architecture ### Multi-Agent Pipeline Instead of one AI doing everything, VitalView Labs uses three specialist agents in sequence: ``` [PDF/Text Input] → Agent 1: Extractor (GPT-4o-mini) — Reads values from the report → Agent 2: Analyzer (GPT-4o + MCP) — Compares against reference ranges → Agent 3: Simplifier (GPT-4o-mini) — Writes patient-friendly language ``` Each agent has a **fallback agent** using a different model. If the primary fails, the backup catches it automatically. ### System Overview ``` ┌──────────────────────────────────────────────────────────────────────┐ │ VITALVIEW LABS SYSTEM │ │ │ │ ┌──────────┐ ┌──────────────┐ ┌───────────────┐ │ │ │ Lovable │───→│ Workflow 1: │───→│ Workflow 2: │ │ │ │ Web App │ │ Generate │ │ Send to │ │ │ │ (Staff) │ │ Summary │ │ Doctor │ │ │ └──────────┘ │ │ └───────┬───────┘ │ │ │ 3 AI Agents │ │ │ │ │ + 3 Fallbacks│ ▼ │ │ │ + MCP Client │ ┌───────────────┐ │ │ └──────┬───────┘ │ Workflow 3: │ │ │ │ │ Doctor Review │ │ │ │ │ (Form) │ │ │ ┌──────┴───────┐ └───────────────┘ │ │ │ Workflow 4: │ │ │ │ MCP Server │◄── Agent 2 calls this │ │ │ (Ref Ranges) │ via MCP Client Tool │ │ └──────────────┘ │ │ │ │ ┌──────────────┐ ┌───────────────┐ │ │ │ Workflow 5: │───→│ Calls │ │ │ │ MCP Server │ │ Workflow 1 │ │ │ │ (VitalView) │ └───────────────┘ │ │ └──────┬───────┘ │ │ ▲ │ └─────────────────────────┼────────────────────────────────────────────┘ │ ┌───────┴───────┐ │ External AI │ │ (Claude │ │ Desktop etc.)│ └───────────────┘ ``` ### 5 Workflows | # | Workflow | Purpose | Triggered By | |---|---------|---------|-------------| | 1 | Generate Summary | Multi-agent AI processing + PDF extraction | Lovable app (staff) | | 2 | Send to Doctor | Save to Google Sheets + email doctor | Lovable app (staff) | | 3 | Doctor Review | Form-based approve/revise/reject | Doctor via email link | | 4 | MCP Server - Reference Ranges | Lookup tool for standard lab ranges | MCP Client (Agent 2) | | 5 | MCP Server - VitalView Labs | Exposes the simplifier as an MCP tool | External AI agents (Claude Desktop, etc.) | ### Workflow 1 — Detailed Node Map ``` [Webhook] → [Anonymize Patient Data] → [IF: PDF?] ├── true → [PDF Binary] → [Extract] → [Prepare Text] ─┐ └── false ─────────────────────────────────────────────┤ ↓ [Build Extractor Prompt] → [Agent 1: Extractor (GPT-4o-mini)] ├── success → [Parse] → [Normalize Values] └── error → [Fallback 1 (GPT-4o)] → [Parse] → [Normalize Values] ↓ [Build Analyzer Prompt] → [Agent 2: Analyzer (GPT-4o) + MCP Client Tool] ├── success → [Parse + Sanitize] └── error → [Fallback 2 (GPT-4o-mini)] → [Parse + Sanitize] ↓ [Build Simplifier Prompt] → [Agent 3: Simplifier (GPT-4o-mini)] ├── success → [Merge All Results] → [Respond to Webhook] └── error → [Fallback 3 (GPT-4o)] → [Parse] → [Merge] → [Respond] ``` --- ## Key Features ### Multi-Agent Architecture - **Agent 1 (Extractor):** Reads raw lab text and extracts structured values with standardized test names - **Agent 2 (Analyzer):** Compares values against reference ranges, flags abnormals, assesses clinical significance - **Agent 3 (Simplifier):** Translates medical analysis into warm, educational patient language ### Fallback AI (Fault Tolerance) Each agent has a backup model. If the primary fails (API outage, rate limit, timeout), the fallback catches it automatically using n8n's error output routing. ``` [Primary Agent] ── success → [Continue] │ └── error (red) → [Fallback Agent] → [Continue] ``` | Agent | Primary Model | Fallback Model | |-------|--------------|----------------| | Extractor | GPT-4o-mini | GPT-4o | | Analyzer | GPT-4o | GPT-4o-mini | | Simplifier | GPT-4o-mini | GPT-4o | ### MCP Integration (Bidirectional) **Direction 1 — MCP Client (Agent USES external tools):** Agent 2 connects to a Reference Range MCP Server via MCP Client Tool. The agent autonomously decides when to call the tool — if the lab report already includes ranges, it skips the call. If ranges are missing, it calls the MCP server to look them up. **Direction 2 — MCP Server (Workflow BECOMES a tool):** The entire VitalView Labs system is exposed as an MCP Server. Claude Desktop or any MCP-compatible AI agent can discover and call it to simplify lab reports. ### Clinical Safety (7 CMO Fixes) 1. Framed as "patient education" not "medical interpretation" 2. Doctor sees original values + AI summary side by side 3. Doctor approval via form review with verification checkbox 4. Patient data anonymized before AI processing 5. Lab-specific reference ranges supported 6. Urgency flags removed before patient-facing Simplifier agent 7. Informed consent checkbox required ### Data Anonymization Patient identity (name, email) is stripped before any AI processing. Only clinical data (age, gender, lab values) reaches the AI agents. Identity is re-attached after processing for delivery. ``` [Raw Input: "Ramesh Kumar, 45, Male, Hemoglobin 11.2"] ↓ [Anonymize] → identity: {name: "Ramesh Kumar", email: "..."} (stored in n8n) → clinical: {age: 45, gender: "Male", Hb: 11.2} (sent to AI) ↓ [AI Agents process clinical data only — never see patient name] ↓ [Re-attach identity for email delivery] ``` ### Urgency Sanitization The Analyzer produces urgency flags ("follow-up recommended"). The doctor sees these. The Simplifier agent never receives them — it literally cannot include urgency in the patient summary because the data is stripped at the code level, not the prompt level. ``` Analyzer output → TWO versions: ├── analysisForDoctor: { urgency: "follow-up", ... } ← Doctor sees this └── analysisForSimplifier: { concern: "...", ... } ← No urgency field exists ``` --- ## Tech Stack | Component | Technology | |-----------|-----------| | Automation Engine | n8n (self-hosted on Hostinger VPS) | | AI Models | OpenAI GPT-4o, GPT-4o-mini | | AI Agent Framework | n8n AI Agent nodes (LangChain-based) | | MCP Protocol | n8n MCP Server Trigger + MCP Client Tool | | Frontend | Lovable (AI-generated React app) | | Database | Google Sheets (audit trail) | | Email | Gmail API (doctor + patient delivery) | | PDF Processing | n8n Extract From File node | | Hosting | Hostinger VPS (Ubuntu) | --- ## How It Works (User Flow) ### 1. Staff Input Clinic staff opens the VitalView Labs web app, uploads a lab report PDF (or pastes values), enters patient details, and clicks "Generate Summary." ### 2. AI Processing (30-60 seconds) Three AI agents process the report in sequence: - **Extractor** reads all values and standardizes test names (handles Thyrocare, SRL, Dr. Lal PathLabs, any Indian lab format) - **Analyzer** compares against reference ranges (using MCP tool when needed) and flags abnormals - **Simplifier** writes a warm, educational summary with no urgency language Patient identity is anonymized during this entire process. ### 3. Staff Review Staff previews the AI summary with color-coded findings: - 🟢 Green: "Within range" - 🟡 Amber: "Above typical range" - 🔴 Red: "Below typical range" ### 4. Doctor Approval Staff clicks "Send to Doctor." The doctor receives an email with: - Original lab values (source of truth) - AI summary (for comparison) - Clinical urgency flags (doctor-only — never shown to patient) - "Review and Approve" button linking to an n8n form ### 5. Patient Delivery After doctor approval, the patient receives an educational summary email — warm, simple, no urgency language, with wellness tips and a clear disclaimer. --- ## Cost Per Report | Agent | Model | Cost | |-------|-------|------| | Extractor | GPT-4o-mini | ~₹0.30 | | Analyzer | GPT-4o | ~₹1.50 | | Simplifier | GPT-4o-mini | ~₹0.30 | | **Total** | | **~₹2.10 per report** | 50 reports/day × ₹2.10 = approximately ₹3,150/month (~$38/month) --- ## Project Structure ``` vitalview-labs/ ├── README.md # This file ├── workflows/ │ ├── workflow1-multi-agent.json # n8n workflow — Generate Summary │ └── workflow4-mcp-reference.json # n8n workflow — Reference Range MCP Server ├── lovable/ │ └── ui-prompt.md # Complete Lovable UI generation prompt └── assets/ └── sample-cbc-report.pdf # Sample CBC report for testing ``` --- ## Concepts Demonstrated | Concept | Implementation | |---------|---------------| | Multi-Agent AI (Chain Pattern) | 3 specialist agents in sequence | | Agent Autonomy | AI Agent nodes with autonomous tool-calling | | MCP Client | Agent 2 discovers and calls tools via MCP protocol | | MCP Server Trigger | Workflow exposed as discoverable tool for external AI | | Call n8n Workflow Tool | MCP Server delegates to sub-workflow | | Fallback / Fault Tolerance | Error output routing to backup models | | Data Anonymization | Strip identity before AI, re-attach after | | Data Sanitization | Remove urgency before patient-facing agent | | Data Normalization | Force consistent structure from inconsistent AI output | | Human-in-the-Loop | Doctor approval gate before patient delivery | | PDF Processing Pipeline | base64 → binary → Extract From File → text | | Build Prompt Pattern | Code nodes pre-build prompts for AI Agent nodes | | Webhook Architecture | POST triggers, form triggers, response nodes | | Google Sheets as State Store | Shared state between asynchronous workflows | --- ## What I Learned Building This 1. **Multi-agent > single agent** for complex tasks — each agent's prompt is short and focused, producing better results than one giant prompt 2. **Data-level controls > prompt-level controls** for safety — stripping urgency from the data is more reliable than telling the AI "don't include urgency" 3. **MCP is the USB for AI tools** — one standard protocol lets any AI agent use any tool without custom integration code 4. **The "Build Prompt" pattern** — AI Agent nodes in n8n struggle with complex expressions; pre-building the prompt in a Code node and passing `{{ $json.prompt }}` solves this reliably 5. **Fallback adds resilience at near-zero cost** — the backup only runs when the primary fails, so normal operation costs nothing extra 6. **Node name matching is critical** — `$('Node Name')` requires character-perfect matching, including spaces and capitalization --- ## Built By **Viswaath Ganesan** — [FutureFramesAI] *The future belongs to the curious.* --- ## License This project is shared for educational purposes. The architecture, prompts, and workflow designs are original work by FutureFramesAI.