Improve README: feature drug safety check, all 6 quests, clean architecture

README.md

@@ -21,102 +21,130 @@ tags:
   - tiny-titan
 ---
 
-# 🩺 ClinIQ — Privacy-First Clinical Document Assistant
+# ClinIQ — Privacy-First Clinical Document Assistant
 
-> **Gradio Build Small Hackathon 2026** · Track: Backyard AI · Model: Qwen2.5-3B-Instruct (≤4B ✅)
+> **Gradio Build Small Hackathon 2026** · Qwen2.5-3B-Instruct (Q4_K_M) · llama.cpp on Modal A10G
+
+## The one thing no other clinical RAG does
+
+**Proactive Drug Safety Check** — the moment you upload patient documents, ClinIQ automatically scans ALL medications and allergies across every document and flags dangerous combinations. No question needed. A 3B pharmacist runs in the background.
+
+Example: upload a discharge summary (Aspirin 81mg prescribed) and an intake note (Aspirin allergy — bronchospasm) from two separate visits. ClinIQ instantly surfaces:
+
+```
+DANGER  Aspirin allergy contraindication — patient is prescribed Aspirin 81mg
+        but has documented bronchospasm reaction to aspirin
+        Recommendation: Switch to Clopidogrel (per cardiology consult)
+```
+
+This catches cross-document drug-allergy conflicts that a human reading one chart at a time would miss.
+
+---
 
 ## What it does
 
-ClinIQ lets clinic staff upload patient forms, discharge summaries, and consult notes, then ask
-plain-English questions — answered instantly, with full source citations and a live agent trace.
+Upload any mix of PDFs and TXT clinical documents, then:
+
+- **Proactive safety scan** runs automatically — no question needed
+- **Ask anything** in plain English — answered in ~2 seconds
+- **Structured extraction** returns clean tables (medications, allergies, diagnoses, vitals)
+- **Cross-document reasoning** works across multiple patient records simultaneously
+- **Live agent trace** shows every reasoning step as it happens
 
-**Example questions:**
-| Question | Query type |
-|----------|-----------|
-| *"What medications is this patient on?"* | Structured → returns a table |
-| *"Do any medications interact with the patient's allergies?"* | Complex → multi-hop reasoning |
-| *"How have the medications changed between the intake note and the consult?"* | Comparison → cross-document |
-| *"Summarize the discharge instructions"* | Simple |
+| Question | Query type | What happens |
+|----------|-----------|-------------|
+| *"List all medications"* | Structured | Returns name/dose/frequency/route table |
+| *"Is it safe to give this patient aspirin?"* | Complex | Multi-hop reasoning across all docs |
+| *"What alternative was recommended instead of aspirin?"* | Simple | Retrieves Clopidogrel from consult note |
+| *"Who is the attending physician?"* | Simple | Direct fact lookup with source |
+
+---
 
 ## Architecture
 
 ```
-Upload PDFs/TXT
+Upload PDFs / TXT
       ↓
 Chunking (400 tokens, 80-token overlap)
       ↓
 Hybrid Retrieval — BM25 (rank_bm25) + Dense (MiniLM-L6-v2) + score fusion
       ↓
-LangGraph Agent (5 nodes):
-  classify_query → decompose → retrieve → generate → reflect
-        ↑_________________________(retry if not grounded, max 2x)
+LangGraph 5-node Agent:
+  classify → decompose → retrieve → build_context → generate → reflect → END
       ↓
-Qwen2.5-3B-Instruct · llama.cpp Q4_K_M · Modal A10G GPU
+Qwen2.5-3B-Instruct · llama.cpp Q4_K_M · Modal A10G GPU (~2s/query)
       ↓
-Streaming answer + live trace in custom HTML frontend (gr.Server)
+Streaming answer + live trace in custom HTML/CSS/JS frontend (gr.Server)
+
+PARALLEL: Drug Safety Checker
+  regex extraction (no LLM) → Qwen safety reasoning → colour-coded alerts
 ```
 
-## Hackathon Bonus Quests — all 5 achievable
+---
 
-| Quest | ✅ | How |
-|-------|---|-----|
-| 🎨 **Off-Brand** | ✅ | `gr.Server` + full custom HTML/CSS/JS — no default Gradio UI |
-| 🦙 **Llama Champion** | ✅ | llama.cpp Q4_K_M via Modal (`modal_inference.py`) |
-| 📡 **Sharing is Caring** | ✅ | Every query's trace auto-pushed to [HF Hub dataset](https://huggingface.co/datasets/karthikmulugu08/cliniq-traces) |
-| 🎯 **Well-Tuned** | ✅ | Qwen2.5-3B-Instruct (instruction fine-tuned, published on Hub) |
-| 📓 **Field Notes** | ✅ | [Blog post](./blog_post.md) |
+## Hackathon Bonus Quests
 
-**Special award targets:** 🐜 Tiny Titan (≤4B) · 🤖 Best Agent · 🎬 Best Demo
+| Quest | Status | How |
+|-------|--------|-----|
+| Off-Brand | achieved | `gr.Server` — zero default Gradio UI. Full custom HTML/CSS/JS served via FastAPI endpoints |
+| Llama Champion | achieved | llama.cpp Q4_K_M quantization on Modal A10G GPU (`modal_inference.py`) |
+| Sharing is Caring | achieved | Every agent trace auto-pushed to [HF Hub dataset](https://huggingface.co/datasets/karthikmulugu08/cliniq-traces) |
+| Well-Tuned | achieved | Qwen2.5-3B-Instruct — instruction fine-tuned, published on HF Hub |
+| Tiny Titan | achieved | 3B parameter model, ~1.8GB on disk, inference in ~2s |
+| Field Notes | achieved | [Blog post — building ClinIQ](https://huggingface.co/karthikmulugu08) |
 
-## Smart Clinical Templates
+---
 
-One-click buttons for the most common clinical queries:
-💊 Medication List · ⚠️ Allergy Summary · 🏥 Diagnoses · 📅 Follow-up Plan · 💓 Vital Signs · 📋 Discharge Summary
+## Why Qwen2.5-3B works here
 
-## Running locally
+Clinical document extraction is a **retrieval + pattern matching** problem, not a reasoning problem. You don't need 70B parameters to find "Metformin 1000mg BID" in a discharge summary. The 3B model:
 
-```bash
-pip install -r requirements.txt
-python app.py          # visit http://localhost:7860
-```
+- Extracts structured medication lists accurately
+- Reasons about drug-allergy interactions given clean lists
+- Runs on A10G in ~2s for ~$0.001/query
+- Fits the Tiny Titan constraint (≤4B) with room to spare
 
-## Deploying (Modal + HF Space)
+The hard work is done by the hybrid retriever and the two-step safety checker (regex extraction first, LLM reasoning second) — the model just needs to synthesize clean inputs.
 
-```bash
-# Deploy Modal GPU inference
-pip install modal
-modal setup            # authenticate once
-modal deploy modal_inference.py
-# → Copy the printed web endpoint URL
+---
 
-# Then push to HF Space:
-bash deploy.sh
-```
+## Drug Safety Check — technical detail
+
+Most clinical RAG systems answer questions reactively. ClinIQ's safety checker is proactive:
 
-## Space Secrets
+**Step 1 — Regex extraction** (no LLM, instantaneous):  
+Scans ALL MEDICATIONS and ALLERGIES sections across all uploaded documents using regex with deduplication. Finds cross-document conflicts a single-document scan would miss.
 
-Set in Space → Settings → Variables & Secrets:
+**Step 2 — LLM safety reasoning** (Qwen2.5-3B):  
+Feeds clean medication and allergy lists to the model. Asks only: "are there dangerous combinations?" Returns structured alerts with DANGER / WARNING / INFO severity.
 
-| Secret | Value |
-|--------|-------|
-| `MODAL_ENDPOINT` | URL from `modal deploy` output |
-| `HF_TOKEN` | Your HF write token |
-| `HF_DATASET_REPO` | `karthikmulugu08/cliniq-traces` |
+This two-step design is reliable — Step 1 never hallucinates (it's regex), and Step 2 only reasons about clean, extracted lists (not raw document text).
 
-## Why small models work here
+---
+
+## Model & Dataset
 
-Qwen2.5-3B-Instruct is the honest, efficient choice for clinical extraction tasks.
-Medications, allergies, diagnoses, and follow-up dates are all **retrievable facts** —
-you don't need 70B parameters to find "Metformin 1000mg BID" in a document.
-The 3B model runs inference in **~2 seconds** on A10G, costs ~$0.001/query,
-and fits entirely within the ≤4B Tiny Titan constraint.
+**Model:** [bartowski/Qwen2.5-3B-Instruct-GGUF](https://huggingface.co/bartowski/Qwen2.5-3B-Instruct-GGUF) Q4_K_M — Apache 2.0
 
-## Model
+**Demo documents:** Synthetic clinical notes (discharge summary, intake note, cardiology consult) styled after MTSamples. Three documents, two patients, intentional cross-document drug-allergy conflict.
 
-[Qwen/Qwen2.5-3B-Instruct](https://huggingface.co/Qwen/Qwen2.5-3B-Instruct) — Apache 2.0  
-Quantized: `bartowski/Qwen2.5-3B-Instruct-GGUF` Q4_K_M (~1.8GB)
+**Traces:** Live agent traces shared at [karthikmulugu08/cliniq-traces](https://huggingface.co/datasets/karthikmulugu08/cliniq-traces)
 
-## Dataset
+---
+
+## Running locally
 
-Demo documents are synthetic clinical notes styled after [MTSamples](https://www.mtsamples.com/).
-Agent traces from live queries are shared at [karthikmulugu08/cliniq-traces](https://huggingface.co/datasets/karthikmulugu08/cliniq-traces).
+```bash
+pip install -r requirements.txt
+python app.py   # http://localhost:7860
+```
+
+## Deploy (Modal + HF Space)
+
+```bash
+pip install modal
+modal setup
+modal deploy modal_inference.py   # prints endpoint URL
+
+# Set Space secrets: MODAL_ENDPOINT, HF_TOKEN, HF_DATASET_REPO
+```