PolicyAI โ Health Insurance Intelligence Platform
AI that reads every page of your health insurance policy โ including the hidden traps โ so you don't have to.
---
## ๐ The Problem
**68% of health insurance claims in India get rejected** โ not because the treatment isn't covered, but because policyholders don't understand the fine print. Policies are 50โ60 page legal documents filled with hidden sub-limits, proportional deductions, narrow definitions, and buried waiting periods.
No existing tool reads the **actual policy PDF** and explains coverage in plain English while detecting hidden traps.
## ๐ก The Solution
**PolicyAI** is an end-to-end AI-powered platform covering the **full health insurance lifecycle** โ from finding the right policy to filing a successful claim. It uses a **3-layer hybrid RAG pipeline** to cross-reference definitions, exclusions, and conditions, detecting **8 types of hidden policy traps** that cause real-world claim rejections.
---
## โจ Features
### 1. ๐ Natural Language Policy Discovery
> _"I need maternity coverage, have diabetes, budget โน18,000/year, family of 3"_
- GPT-4o-mini extracts structured requirements (needs, budget, conditions, policy type)
- `PolicyRanker` scores and ranks all catalog policies by budget fit, coverage match, PED wait, exclusion risk, network size
- Returns scored policy cards with match percentage and reasons
### 2. โ๏ธ Side-by-Side Policy Comparison
- Select 2โ3 policies โ generates a **19-dimension comparison matrix**
- Covers premiums, waiting periods, co-pay, room rent, maternity, OPD, mental health, AYUSH, dental, NCB, restoration, network hospitals
- AI-generated comparison summary with "best for" recommendations
### 3. ๐ง Hybrid RAG Policy Q&A + Hidden Conditions Detector
> _"Is knee replacement surgery covered?"_
Upload any policy PDF and ask any coverage question. The **3-layer hybrid RAG pipeline** retrieves the most relevant clauses:
| Layer | Method | What It Searches |
|---|---|---|
| **Layer 1** | Semantic (pgvector) + Keyword (tsvector) โ RRF Fusion | Direct answer clauses (top 5) |
| **Layer 2** | Section-filtered semantic search | Definitions section (top 3) |
| **Layer 3** | Section-filtered semantic search | Exclusions + Conditions + Limits + Waiting Periods (top 3) |
**Output includes:**
- **Verdict:** COVERED / NOT_COVERED / PARTIALLY_COVERED / AMBIGUOUS
- **Practical Claimability:** ๐ข GREEN / ๐ก AMBER / ๐ด RED
- **Confidence Score:** 0โ100%
- **8 Hidden Trap Types** detected with evidence and impact
- **Citations** with exact clause text and page numbers
- **Actionable Recommendation** for the policyholder
### 4. ๐ฅ Medical Report โ Smart Policy Matching
- Input free text or upload a medical report PDF
- AI extracts conditions (name, ICD hint, type, severity)
- Matches against all catalog policies' exclusion lists
- Returns ranked policies flagged with per-condition exclusion risks
### 5. ๐ Claim Eligibility Advisory
- Select policy + enter diagnosis + choose treatment type
- Computes **Claim Feasibility Score (0โ100)** with deductions for hidden traps
- Returns required documents checklist by claim type (hospitalization, surgery, maternity, OPD, critical illness)
### 6. ๐ Coverage Gap Analyzer
- Scans any policy against a standard coverage checklist (7 critical areas + 3 dynamic checks)
- Each gap rated by severity (HIGH / MEDIUM / LOW) with plain-English explanation and recommendation
---
## ๐ต๏ธ The 8 Hidden Trap Types
| Type | What It Means |
|---|---|
| `room_rent_trap` | Room rent cap โ ALL charges proportionally reduced |
| `pre_auth_required` | Pre-authorization missed โ entire claim denied |
| `proportional_deduction` | Sub-limit breach โ entire bill cut proportionally |
| `definition_trap` | Key terms defined narrowly (e.g., "Hospitalization" = 24+ hrs only) |
| `waiting_period` | Specific illness or PED waiting period applies |
| `sub_limit` | Cap on specific treatments within broad coverage |
| `documentation` | Non-obvious or time-sensitive document requirements |
| `network_restriction` | Non-network hospital co-pay or full exclusion |
---
## ๐๏ธ Architecture
```
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ FRONTEND (Vercel) โ
โ Next.js 14 + Tailwind CSS + Lucide Icons โ
โ โ
โ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโ โ
โ โ /discover โ โ /qa โ โ /claim โ โ
โ โ Discovery & โ โ Policy Q&A โ โ Claim Advisory + โ โ
โ โ Comparison โ โ + Upload โ โ Medical Match + โ โ
โ โ โ โ โ โ Gap Analysis โ โ
โ โโโโโโโโฌโโโโโโโโ โโโโโโโโฌโโโโโโโโ โโโโโโโโโโฌโโโโโโโโโโโโ โ
โโโโโโโโโโโโผโโโโโโโโโโโโโโโโโโโผโโโโโโโโโโโโโโโโโโโโผโโโโโโโโโโโโโโโโโ
โ โ โ
โผ โผ โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ BACKEND (Render) โ
โ FastAPI ยท Python 3.11 โ
โ โ
โ โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโ โ
โ โ Routers (3) โ โ Services (7) โ โ Skills (3) โ โ
โ โ discovery.py โ โ embedder.py โ โ HiddenConditions โ โ
โ โ qa.py โ โ llm.py โ โ Detector โ โ
โ โ claim.py โ โ pdf_parser.py โ โ CoverageGap โ โ
โ โ โ โ vector_store โ โ Scanner โ โ
โ โ 10 API endpoints โ โ med_extractor โ โ PolicyRanker โ โ
โ โ โ โ tools.py โ โ โ โ
โ โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโฌโโโโโโโโ โโโโโโโโโโโโโโโโโโโโ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโผโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โโโโโโโโโโโโโโโโโโโผโโโโโโโโโโโโโโโโโโโ
โผ โผ โผ
โโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโ
โ Supabase โ โ OpenAI โ โ OpenAI โ
โ PostgreSQL + โ โ Embeddings โ โ GPT-4o-mini โ
โ pgvector โ โ text-emb- โ โ Structured JSON โ
โ tsvector โ โ 3-small โ โ temp=0.1 โ
โโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโ
```
### RAG Pipeline Flow
```
User Question
โ
โผ
Embed Query (text-embedding-3-small โ 1536-dim)
โ
โโโโบ Layer 1a: Semantic Search (pgvector, top 8) โโโ
โโโโบ Layer 1b: Keyword Search (tsvector, top 8) โโโคโโโบ RRF Fusion (k=60) โ top 5
โโโโบ Layer 2: Section Search (definitions, top 3) โโโโโโโโโโโโโโโโโโ
โโโโบ Layer 3: Section Search (exclusions+conditions+limits, top 3) โค
โผ
GPT-4o-mini Synthesis
(Senior Claims Consultant prompt)
โ
โผ
Structured JSON Verdict
+ Hidden Conditions
+ Citations + Recommendation
```
---
## ๐ ๏ธ Tech Stack
| Layer | Technology | Purpose |
|---|---|---|
| **Frontend** | Next.js 14 (App Router) | Server/client components, file-based routing |
| **Styling** | Tailwind CSS + Lucide Icons | Responsive UI with icon system |
| **API Client** | Axios | HTTP client for backend communication |
| **Backend** | FastAPI (Python 3.11) | High-performance async REST API |
| **LLM** | OpenAI GPT-4o-mini | Structured JSON reasoning at temperature 0.1 |
| **Embeddings** | OpenAI text-embedding-3-small | 1536-dim vectors with retry + batch support |
| **Vector DB** | Supabase pgvector | Cosine similarity ANN search (IVFFlat index) |
| **Keyword Search** | PostgreSQL tsvector | BM25-style full-text search (GIN index) |
| **Search Fusion** | Reciprocal Rank Fusion (RRF) | Merges semantic + keyword results (k=60) |
| **PDF Parsing** | PyMuPDF (fitz) | Section-aware chunking with regex heading detection |
| **Deployment** | Vercel + Render | Frontend CDN + Backend auto-deploy |
---
## ๐ Project Structure
```
PolicyAI/
โโโ CLAUDE.md # Project documentation
โโโ render.yaml # Render deployment config
โ
โโโ backend/
โ โโโ main.py # FastAPI app + lifespan startup seeder
โ โโโ requirements.txt # Python dependencies
โ โโโ data/
โ โ โโโ schema.sql # Supabase schema (tables + indexes + RPCs)
โ โ โโโ seed_policies.json # 10-insurer structured catalog
โ โโโ routers/
โ โ โโโ discovery.py # /api/discover, /api/compare
โ โ โโโ qa.py # /api/upload, /api/policies, /api/ask
โ โ โโโ claim.py # /api/claim-check, /api/extract-*, /api/match-*, /api/gap-*
โ โโโ scripts/
โ โ โโโ seed_db.py # Populate insurance_policies catalog table
โ โ โโโ startup_seeder.py # Auto-embed all PDFs from policies/ on boot
โ โโโ services/
โ โโโ embedder.py # OpenAI embedding wrapper (single + batch + retry)
โ โโโ llm.py # GPT-4o-mini structured JSON + text helpers
โ โโโ pdf_parser.py # Section-aware PDF chunking (30+ regex patterns)
โ โโโ vector_store.py # Supabase: semantic, keyword, section, RRF, catalog CRUD
โ โโโ medical_extractor.py # Condition extraction from text/PDF + exclusion matching
โ โโโ skills.py # HiddenConditionsDetector, CoverageGapScanner, PolicyRanker
โ โโโ tools.py # 8 tool implementations + OpenAI function-call schemas
โ
โโโ frontend/
โ โโโ package.json
โ โโโ next.config.ts
โ โโโ tsconfig.json
โ โโโ app/
โ โ โโโ layout.tsx # Root layout
โ โ โโโ page.tsx # Landing page โ 3-mode selector
โ โ โโโ globals.css # Tailwind base styles
โ โ โโโ discover/page.tsx # Feature 1+2: Discovery + Comparison
โ โ โโโ qa/page.tsx # Feature 3: Policy Q&A + Upload
โ โ โโโ claim/page.tsx # Feature 4+5+6: Claim + Medical + Gap
โ โโโ components/
โ โ โโโ AnswerCard.tsx # Verdict badge, claimability, hidden conditions, citations
โ โ โโโ ComparisonTable.tsx # 19-dimension comparison matrix
โ โ โโโ PolicyCard.tsx # Scored policy card with match % and feature pills
โ โโโ lib/
โ โโโ api.ts # All API client functions (Axios)
โ
โโโ Policies/
โโโ tata/ # 30+ real Tata AIG policy PDFs
โโโ *.pdf
```
---
## ๐๏ธ Database Schema
### Tables
| Table | Purpose |
|---|---|
| `insurance_policies` | Structured catalog โ premiums, coverage flags, exclusions, waiting periods for 10 insurers |
| `uploaded_policies` | Tracks embedded PDF documents โ filename, insurer, chunk count |
| `policy_chunks` | Text chunks with `embedding VECTOR(1536)` + `content_tsv TSVECTOR` + `section_type` |
### Indexes
| Index | Type | Purpose |
|---|---|---|
| `policy_chunks_embedding_idx` | IVFFlat (lists=100) | Fast ANN cosine similarity on embeddings |
| `policy_chunks_tsv_idx` | GIN | Full-text keyword search on tsvector |
| `policy_chunks_policy_section_idx` | B-tree composite | Fast section-filtered queries |
### Supabase RPC Functions
| Function | Purpose |
|---|---|
| `match_chunks_direct()` | Direct semantic similarity search |
| `match_chunks_by_section()` | Section-filtered semantic search |
| `keyword_search_chunks()` | Full-text keyword search with `ts_rank_cd` ranking |
---
## ๐ API Endpoints
| Method | Endpoint | Feature | Description |
|---|---|---|---|
| `GET` | `/api/health` | System | Health check |
| `POST` | `/api/discover` | Discovery | NL query โ extracted requirements โ ranked policies |
| `POST` | `/api/compare` | Comparison | 2โ3 policy IDs โ 19-dimension comparison matrix + AI summary |
| `GET` | `/api/policies` | Q&A | List all uploaded/embedded policies |
| `POST` | `/api/upload` | Q&A | Upload PDF โ section-aware chunk โ embed โ store |
| `POST` | `/api/ask` | Q&A | Question + policy โ 3-layer hybrid RAG โ verdict + hidden traps |
| `POST` | `/api/claim-check` | Claim | Diagnosis + policy โ feasibility score + document checklist |
| `POST` | `/api/extract-conditions` | Medical | Free text โ extracted medical conditions |
| `POST` | `/api/extract-conditions-file` | Medical | PDF upload โ extracted medical conditions |
| `POST` | `/api/match-conditions` | Medical | Conditions array โ ranked policies with exclusion flags |
| `GET` | `/api/gap-analysis/{id}` | Gap | Policy ID โ coverage gaps sorted by severity |
---
## ๐ Getting Started
### Prerequisites
- **Node.js** 18+ and npm
- **Python** 3.11+
- **Supabase** account (free tier works)
- **OpenAI** API key
### 1. Clone the Repository
```bash
git clone https://github.com/your-username/PolicyAI.git
cd PolicyAI
```
### 2. Set Up Supabase
1. Create a new Supabase project
2. Go to **SQL Editor** โ paste and run `backend/data/schema.sql`
3. Copy your **Project URL** and **Service Role Key**
### 3. Configure Environment Variables
**Backend** โ create `backend/.env`:
```env
OPENAI_API_KEY=sk-...
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_KEY=eyJ...
```
**Frontend** โ create `frontend/.env.local`:
```env
NEXT_PUBLIC_API_URL=http://localhost:8000
```
### 4. Start the Backend
```bash
cd backend
pip install -r requirements.txt
python scripts/seed_db.py # Seed the structured catalog (run once)
uvicorn main:app --reload --port 8000
```
> On startup, the backend automatically scans `Policies/` and embeds any new PDFs.
### 5. Start the Frontend
```bash
cd frontend
npm install
npm run dev
```
Open [http://localhost:3000](http://localhost:3000) โ you're ready to go!
### 6. Add More Policy PDFs (Optional)
```bash
mkdir -p Policies/hdfc
# Drop PDF files into the folder
# Restart the backend โ the startup seeder handles the rest
```
**Convention:** `Policies/{insurer_slug}/{policy_filename}.pdf`
---
## ๐ Data
### 10 Insurers in Structured Catalog
| # | Insurer | Plan Name | Type |
|---|---|---|---|
| 1 | Star Health and Allied Insurance | Star Health Assure | Individual |
| 2 | HDFC ERGO General Insurance | HDFC Ergo Optima Secure | Family Floater |
| 3 | Niva Bupa Health Insurance | Niva Bupa ReAssure 2.0 | Family Floater |
| 4 | Care Health Insurance | Care Supreme | Individual |
| 5 | Bajaj Allianz General Insurance | Bajaj Allianz Health Care Supreme | Family Floater |
| 6 | ICICI Lombard General Insurance | ICICI Lombard Complete Health | Family Floater |
| 7 | Aditya Birla Health Insurance | Activ Health Platinum Enhanced | Individual |
| 8 | New India Assurance Company | New India Mediclaim | Individual |
| 9 | Tata AIG General Insurance | Tata AIG Medicare Premier | Family Floater |
| 10 | ManipalCigna Health Insurance | ManipalCigna ProHealth Prime | Individual |
### 30+ Real Policy PDFs
Tata AIG Medicare Premier collection โ fully parsed, chunked, and embedded in Supabase pgvector.
---
## โ๏ธ Deployment
### Frontend โ Vercel
```bash
cd frontend
npx vercel --prod
```
Set environment variable: `NEXT_PUBLIC_API_URL=https://your-backend.onrender.com`
### Backend โ Render
The included `render.yaml` configures automatic deployment:
```yaml
services:
- type: web
name: policyai-backend
runtime: python
startCommand: uvicorn main:app --host 0.0.0.0 --port $PORT
rootDir: backend
envVars:
- key: OPENAI_API_KEY
- key: SUPABASE_URL
- key: SUPABASE_SERVICE_KEY
```
---
## ๐งช Testing
```bash
cd backend
python -m pytest tests/
```
---
## ๐ Technical Decisions
| Decision | Why |
|---|---|
| **Hybrid RAG (semantic + keyword)** | Legal documents have exact terms ("Code-Excl01") that semantic search alone misses |
| **RRF Fusion (k=60)** | Rank-based merge โ no score normalization needed across different retrieval methods |
| **Section-aware chunking** | Must cross-reference definitions โ exclusions to catch hidden traps |
| **3-layer search** | Single query misses definition and exclusion cross-references |
| **GPT-4o-mini** | Best cost-to-quality ratio for structured JSON output at low temperature |
| **Supabase pgvector** | Single database for vectors + keywords + metadata โ no separate vector DB needed |
| **IVFFlat index** | Good accuracy/speed tradeoff for <100K chunks; faster index builds than HNSW |
| **PyMuPDF** | Superior text extraction quality for formatted insurance PDFs vs. alternatives |
| **400-token chunks, 80 overlap** | Balanced granularity โ large enough for context, small enough for precision |
---
## ๐ Project Stats
| Metric | Value |
|---|---|
| Python source files | 12 |
| TypeScript source files | 9 |
| API endpoints | 10 |
| AI skills | 3 |
| Tool implementations | 8 |
| Hidden trap types | 8 |
| Insurers in catalog | 10 |
| Real policy PDFs | 30+ |
| Section regex patterns | 30+ |
| Comparison dimensions | 19 |
| Gap checklist items | 10 |
| Database tables | 3 |
| Database indexes | 3 |
| RPC functions | 3 |
| Embedding dimensions | 1,536 |
---
## ๐ฎ Future Scope
- **Multi-turn Conversational Agent** โ follow-up questions with context memory
- **PDF-to-PDF Comparison** โ compare two uploaded policy documents directly
- **Multi-language Support** โ Hindi, Tamil, Telugu policy Q&A
- **WhatsApp Bot Integration** โ policy Q&A for broader accessibility
- **Real-time Premium Quotes** โ integrate insurer APIs for live pricing
- **Claim Tracking Dashboard** โ real-time claim status monitoring
- **Policy Renewal Advisor** โ proactive recommendations at renewal time
---
## ๐ License
This project is built for educational and demonstration purposes.
---
PolicyAI โ Because understanding your health insurance shouldn't require a law degree.