An enterprise-grade, multi-agent AI system that autonomously processes medical insurance claims — from clinical documentation through coding audit, denial prediction, and appeal generation — in under 90 seconds.
Medical insurance claim denials represent a $262B–$300B annual loss in the US healthcare system. A human billing specialist takes 2 to 4 hours to manually audit a claim, cross-reference payer policies, and draft an appeal letter.
MedClaim replaces this tedious manual workflow with a deterministic, LangGraph-orchestrated multi-agent state machine. Utilizing Retrieval-Augmented Generation (RAG) across four distinct medical vector databases, intelligent LLM routing (Groq for speed, Gemini 1.5 Flash for massive context windows), and a full production LLMOps observability suite, MedClaim drastically reduces resolution time while maintaining compliance through strict Human-in-the-Loop (HITL) gateways.
- ⚡ 98% Faster Processing: Reduces claim processing time from 2-4 hours to under 90 seconds
- 🎯 85% Accuracy: Achieves high accuracy in code audit and denial prediction through RAG-enhanced LLMs
- 💰 Cost-Efficient: Entire architecture runs on free-tier cloud services
- 🔄 Self-Learning: Continuous learning loop improves denial prediction over time
- 🛡️ Enterprise-Grade: Full observability, monitoring, and compliance features
See MedClaim process an end-to-end insurance claim in real time, including eligibility verification, code audit, denial prediction, appeal generation, and observability dashboards.
▶ Click the image above to watch the full walkthrough.
MedClaim is composed of six modular, decoupling layers working in tandem:
┌─────────────────────────────────────────────────────────────────────┐
│ INTERFACE LAYER │
│ React (Vite) Dashboard │ Voice AI (Whisper + Coqui) │ REST API │
├─────────────────────────────────────────────────────────────────────┤
│ APPLICATION BACKEND │
│ FastAPI (Async) + Redis Token Rate Limiter │
├─────────────────────────────────────────────────────────────────────┤
│ MULTI-AGENT ORCHESTRATION (LANGGRAPH) │
│ │
│ ┌───────────┐ ┌──────────┐ ┌────────────┐ ┌────────────────┐ │
│ │ Eligibility│─▶ Code Audit│─▶ Denial │─▶ Appeal Drafting │ │
│ │ Agent │ │ Agent │ │ Prediction │ │ Agent │ │
│ └───────────┘ └──────────┘ └────────────┘ └────────────────┘ │
│ Supervisor Node (Deterministic Edge Router) │
├─────────────────────────────────────────────────────────────────────┤
│ RAG KNOWLEDGE LAYER (QDRANT) │
│ coding_rules │ payer_policies │ denial_patterns │ clinical_guides │
├─────────────────────────────────────────────────────────────────────┤
│ PERSISTENCE & CONTINUOUS LEARNING │
│ Supabase PostgreSQL (State) │ Supabase Edge Functions (Feedback) │
├─────────────────────────────────────────────────────────────────────┤
│ LLMOPS & OBSERVABILITY │
│ LangSmith (Tracing/Evals) │ Prometheus (Metrics) │ Grafana (UI) │
└─────────────────────────────────────────────────────────────────────┘
For comprehensive technical documentation, please refer to the /docs folder:
- Architecture Overview - System design, component interactions, and data flow
- Agent System - Multi-agent orchestration, state management, and agent logic
- Agent Logic - Detailed decision-making logic and business rules
- RAG Pipeline - Vector databases, embedding generation, and retrieval strategies
- Database Design - Schema design, relationships, and data persistence
- Data Handling - Ingestion pipelines, synthetic data generation, and ETL
- LLMOps & Observability - Tracing, monitoring, evaluation, and continuous learning
- API Routers - REST API endpoints, authentication, and error handling
- Services Layer - Business logic services and integration patterns
- Voice AI - Speech-to-text, intent classification, and text-to-speech
- Workflows & Approval - Approval workflows, escalation, and notifications
At the core of MedClaim is a LangGraph State Machine. Unlike naive LLM chains, MedClaim uses a Deterministic Supervisor Node to route claims between specialized agents based on strict conditional Python logic. The agents share a ClaimState object that gets updated at every node.
graph TD
A[Claim Received] --> B[Eligibility Check]
B -->|Insurance Active| C[Code Audit]
B -->|Insurance Inactive| Z[Pipeline Halted]
C -->|Issues Found| D[Denial Prediction]
C -->|No Issues| E[Ready for Submission]
D -->|Risk ≤ 70%| E
D -->|Risk > 70%| F[Human Review]
D -->|Correction Needed| C
E -->|Claim Denied| G[Appeal Drafting]
E -->|Claim Approved| H[Submission Complete]
G --> I[Awaiting Approval]
F --> J[Specialist Review]
-
Eligibility Agent: Acts as the first gatekeeper. It hits a mock hospital API to verify if the patient's insurance was active on the date of service and if the provider is in-network. If it fails, the pipeline halts immediately to save compute.
-
Code Audit Agent: Performs dense RAG. It queries the
coding_rulesQdrant vector index for official ICD-10-CM and CPT guidelines. It hands these rules to the Groq LLM to check for Upcoding, Unbundling, or Missing Modifiers, returning a strictly typed JSON output using Pydantic parsers. -
Denial Prediction Agent: Queries the
denial_patternsQdrant collection to find historical claims similar to the current one. It generates a probabilistic Denial Risk Score (0-100) and flags the exact reasons why a payer might reject the claim. -
Appeal Drafting Agent: Triggered only if a claim is denied. It queries the
payer_policiesindex for the specific legal clause the payer used, and theclinical_guidelinesindex for medical necessity proof. It routes to Gemini 1.5 Flash (to handle massive 1M+ token policy PDFs) to generate a legally sound, highly formal HTML/PDF appeal letter. -
Resolution Tracker (Background Task): A continuous watcher that alerts managers via email if claims or appeals are approaching their regulatory filing deadlines.
Every technology in this stack was chosen to maximize speed, reliability, and cost-efficiency (the entire architecture can be run on free tiers).
- LangGraph: Orchestrates the multi-agent state machine. Crucial for persisting states across steps and deterministic routing.
- Groq (Llama 3.1 70B): The primary LLM. Chosen for its extreme inference speed (500+ tokens/sec), making real-time sequential agent workflows viable.
- Google Gemini 1.5 Flash: The secondary LLM. Handles tasks requiring massive context windows, such as injecting 100-page payer policy PDFs into the Appeal Drafting Agent.
- LangChain: Utilized exclusively for prompt management, LLM wrappers, and Pydantic output parsing.
- Qdrant: The vector database powering the semantic search over medical rules. Segregated into 4 distinct collections to prevent cross-contamination of contexts.
- LlamaIndex: Handles ingestion, chunking (512 tokens + 64 token overlap), and metadata extraction for massive policy PDFs.
- Ollama (nomic-embed-text): Runs locally to generate 768-dimensional text embeddings at zero cost.
- FastAPI: Provides an async HTTP layer capable of non-blocking LLM execution.
- Supabase (PostgreSQL): Stores relational claim data, agent decisions, and audit outcomes. Utilizes Supabase Realtime to push live WebSocket updates to the frontend.
- Upstash Redis: Acts as an asynchronous rolling-window token tracker to implement a Circuit Breaker, protecting the system from Groq's 6,000 tokens/minute rate limit.
- HAPI FHIR: An HL7 FHIR R4 standard simulator that demonstrates integration capability with enterprise hospital Electronic Health Record (EHR) systems.
- React (Vite) + TailwindCSS + ShadCN: A beautifully responsive, glassmorphic dashboard for billing specialists to view claim states and approve agent interventions.
- Whisper + Coqui XTTS-v2: Powers the Voice AI interface, allowing billing staff to literally talk to the dashboard (e.g., "What is the status of claim C-1042?").
- LangSmith: Captures full trace trees of every LangGraph node, LLM call, and RAG retrieval. Also hosts our automated Evaluation Suite to catch prompt regressions.
- Prometheus & Grafana: Infrastructure-level observability. Tracks HTTP latencies, Groq token burn rates, and RAG retrieval similarity scores in real-time.
- Structlog: Emits structured, machine-readable JSON logs for deterministic tracking.
MedClaim doesn't just process claims; it learns.
When a human billing specialist marks an appeal as APPROVED_ON_APPEAL, a Supabase trigger fires a webhook to the FastAPI backend (POST /feedback/claim-outcome). The backend extracts the entire context of that successful claim, converts it to an embedding via Ollama, and silently upserts it into the denial_patterns Qdrant vector index. The next time the Denial Prediction Agent evaluates a similar claim, it actively uses this newly learned strategy as a few-shot example.
graph LR
A[Human Specialist] -->|Approves Appeal| B[Supabase Trigger]
B --> C[Webhook to FastAPI]
C --> D[Extract Claim Context]
D --> E[Generate Embedding]
E --> F[Upsert to Qdrant]
F --> G[Denial Prediction Agent]
G --> H[Improved Future Predictions]
MedClaim/
├── backend/
│ ├── app/ # FastAPI routers, Pydantic models, and Supabase services
│ ├── agents/ # LangGraph nodes (Supervisor, CodeAudit, Appeal, etc.)
│ ├── rag/ # Qdrant client, chunking logic, and ingestion scripts
│ ├── llmops/ # Prometheus metrics, LangSmith Evaluator, structured logging
│ └── tests/ # Pytest suite (Unit, Integration, and LLM output tests)
├── frontend/ # React (Vite) billing dashboard and UI components
├── data/ # Medical fixtures and the Synthetic Claim Generator
├── docs/ # Comprehensive technical documentation
│ ├── 01-architecture.md
│ ├── 02-agents.md
│ ├── 03-rag.md
│ ├── 04-database.md
│ ├── 05-data-handling.md
│ └── 06-llmops.md
└── infra/ # Docker Compose, Prometheus config, Grafana Dashboards
Prerequisites: Python 3.11+, Docker Desktop, Ollama (with nomic-embed-text pulled).
-
Clone & Install Dependencies
git clone https://github.com/YOUR_USERNAME/MedClaim.git cd MedClaim python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate pip install -r requirements.txt
-
Environment Configuration Copy the example environment file and fill in your free-tier API keys.
cp .env.example .env
-
Spin up the Observability Stack & FHIR Server
docker-compose -f infra/docker-compose.yml up -d
-
Seed the Databases Run the synthetic data generator to populate Qdrant with historical denial patterns.
python -m data.generate_claims
-
Start the Application
# Terminal 1: Backend uvicorn backend.app.main:app --reload --port 8000 # Terminal 2: Frontend cd frontend npm install && npm run dev
To showcase the full capability of MedClaim:
- Open the dashboard at
http://localhost:5173. - View the Grafana Dashboard at
http://localhost:3001to monitor active token consumption and agent latencies. - Submit a synthetic claim with known coding errors via the UI.
- Watch the claim transition seamlessly through
QUEUED➔RUNNING➔HUMAN_REVIEW_REQUIREDvia WebSockets. - Review the auto-generated Code Audit Report and its RAG-backed confidence scores.
- Approve the LLM's suggested corrections and watch the Denial Risk Score plummet in real-time.
- Trigger the Voice AI from the dashboard to ask: "What is the status of my claim?"
This project is licensed under the MIT License. See the LICENSE file for details.