Upload folder using huggingface_hub

.gitattributes

@@ -1,35 +1,38 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text
+venv/Lib/site-packages/pymupdf/mupdfcpp64.dll filter=lfs diff=lfs merge=lfs -text
+venv/Scripts/python.exe filter=lfs diff=lfs merge=lfs -text
+venv/Scripts/uvicorn.exe filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,14 @@
+.env
+.env.local
+__pycache__/
+*.py[cod]
+*.pyo
+.pytest_cache/
+.mypy_cache/
+*.egg-info/
+dist/
+build/
+venv/
+.venv/
+*.log
+.DS_Store

Dockerfile

@@ -0,0 +1,34 @@
+# LabCard AI Backend — Hugging Face Spaces Docker
+# HF Spaces: non-root user, port 7860, /tmp writable only
+
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# System deps for PyMuPDF (fitz) and pdfplumber
+RUN apt-get update && apt-get install -y \
+    libmupdf-dev \
+    libfreetype6-dev \
+    libharfbuzz-dev \
+    libffi-dev \
+    gcc \
+    g++ \
+    && rm -rf /var/lib/apt/lists/*
+
+# HF Spaces non-root user requirement
+RUN useradd -m -u 1000 user
+USER user
+ENV PATH="/home/user/.local/bin:$PATH"
+ENV HOME="/home/user"
+
+WORKDIR /home/user/app
+
+COPY --chown=user requirements.txt .
+RUN pip install --no-cache-dir --upgrade -r requirements.txt
+
+COPY --chown=user . .
+
+# HF Spaces MUST use port 7860
+EXPOSE 7860
+
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860", "--workers", "1"]

README.md

@@ -1,10 +1,100 @@
----
-title: Labcardai Backend
-emoji: 🏆
-colorFrom: green
-colorTo: yellow
-sdk: docker
-pinned: false
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+---
+title: LabCard AI Backend
+emoji: 🩺
+colorFrom: purple
+colorTo: green
+sdk: docker
+pinned: false
+app_port: 7860
+---
+
+# LabCard AI Backend
+
+FastAPI backend for [LabCard AI](https://labcardai.vercel.app) — India's first AI-powered lab report health card.
+
+## Architecture
+
+- **Tier 1–2**: Deterministic PDF parsing + biomarker scoring (zero LLM cost)
+- **Tier 3**: Gemini 2.5 Flash / Groq for explanations (free)
+- **Tier 4**: Claude Sonnet for premium deep analysis
+
+## API Docs
+
+Visit `/docs` for Swagger UI.
+
+## Stack
+
+- FastAPI 0.111 + Python 3.11
+- pdfplumber + PyMuPDF (dual PDF engine)
+- Supabase PostgreSQL + Upstash Redis
+- Deployed on Hugging Face Spaces (Docker SDK)
+
+---
+
+## Deploy to Hugging Face Spaces
+
+### 1. Create HF Space
+
+```bash
+# Install HF CLI
+pip install huggingface_hub
+
+# Login
+huggingface-cli login
+
+# Create Space (Docker SDK, public)
+huggingface-cli repo create labcard-backend --type space --space-sdk docker
+```
+
+### 2. Push code
+
+```bash
+cd labcard-backend
+git init
+git add .
+git commit -m "Initial LabCard AI backend"
+git remote add origin https://huggingface.co/spaces/YOUR-USERNAME/labcard-backend
+git push -u origin main
+```
+
+### 3. Add Secrets in HF Space Settings
+
+Go to: https://huggingface.co/spaces/YOUR-USERNAME/labcard-backend/settings
+
+Add these secrets (same as .env.example):
+```
+ANTHROPIC_API_KEY=sk-ant-...
+GEMINI_API_KEY=AIza...
+GROQ_API_KEY=gsk_...
+SUPABASE_URL=https://xxx.supabase.co
+SUPABASE_SERVICE_KEY=eyJ...
+SUPABASE_JWT_SECRET=your-jwt-secret
+UPSTASH_REDIS_REST_URL=https://xxx.upstash.io
+UPSTASH_REDIS_REST_TOKEN=...
+ALLOWED_ORIGINS=https://labcardai.vercel.app,http://localhost:3000
+```
+
+### 4. Your backend URL
+
+```
+https://YOUR-USERNAME-labcard-backend.hf.space
+```
+
+Update frontend `.env.local`:
+```
+NEXT_PUBLIC_BACKEND_URL=https://YOUR-USERNAME-labcard-backend.hf.space
+```
+
+### 5. Verify
+
+```bash
+curl https://YOUR-USERNAME-labcard-backend.hf.space/api/health
+# Should return: {"status":"healthy","is_warm":true,...}
+```
+
+### Notes
+
+- **Cold start**: HF Spaces free tier sleeps after 48h inactivity. First request after sleep takes ~30s.
+- **Port**: Must be 7860 (HF Spaces requirement — already set in Dockerfile).
+- **Non-root user**: Dockerfile already uses `user 1000` as required by HF Spaces.
+- **Logs**: View at https://huggingface.co/spaces/YOUR-USERNAME/labcard-backend/logs

app/__init__.py

@@ -0,0 +1 @@
+# LabCard AI Backend

app/api/__init__.py

@@ -0,0 +1 @@
+# LabCard AI Backend

app/api/analyze.py

@@ -0,0 +1,377 @@
+"""
+LabCard AI — POST /api/analyze
+================================
+Full 4-tier pipeline orchestrator.
+
+Tier 1 — PDF extraction (pdfplumber + PyMuPDF)       [always, zero LLM]
+Tier 2 — Biomarker parse + score (deterministic)     [always, zero LLM]
+Tier 3 — AI explanations (Gemini Flash → Groq)       [always, ₹0]
+Tier 4 — Deep analysis (Claude Sonnet)               [premium only, ~₹4–5]
+
+Performance target: p50 < 3s for free tier (no Claude call)
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from typing import Any
+
+from fastapi import APIRouter, File, Form, Header, HTTPException, UploadFile
+from fastapi.responses import JSONResponse
+
+from app.core.ai_router import generate_deep_analysis, generate_explanations
+from app.core.biomarker_parser import parse_biomarkers, resolve_and_classify
+from app.core.pdf_extractor import extract_patient_metadata, extract_text_from_pdf
+from app.core.scorer import compute_health_metrics
+from app.models.report import AnalyzeResponse, LabReport, UserTier
+
+log = logging.getLogger("labcard.analyze")
+
+# ── Supabase persistence (optional — non-blocking) ────────────────────────────
+# Imported lazily so the route still works if Supabase is not configured.
+async def _persist_report(token: str, report: LabReport) -> None:
+    """
+    Fire-and-forget Supabase write.
+    Runs concurrently — NEVER blocks the HTTP response.
+    Failures are logged as warnings only.
+    """
+    try:
+        from app.db.supabase_client import save_report
+        await save_report(token, report)
+    except Exception as exc:  # noqa: BLE001
+        log.warning("Supabase persist failed (non-fatal): %s", exc)
+
+
+# ── Template summaries (free tier — zero LLM cost) ────────────────────────────
+def _template_summary(
+    abnormal_count: int,
+    score:          int,
+    grade:          str,
+    lang:           str,
+) -> tuple[str, str]:
+    """Return (summary_en, summary_hi) template strings for free tier."""
+    en = (
+        f"Your report shows {abnormal_count} value(s) outside the normal range. "
+        f"Your health score is {score}/100 ({grade}). "
+        "Review the color-coded cards below and consult your doctor."
+    )
+    hi = (
+        f"आपकी रिपोर्ट में {abnormal_count} मान सामान्य सीमा से बाहर हैं। "
+        f"आपका स्वास्थ्य स्कोर {score}/100 ({grade}) है। "
+        "नीचे दिए गए कार्ड देखें और अपने डॉक्टर से मिलें।"
+    )
+    return en, hi
+
+
+# ── Timing helper ─────────────────────────────────────────────────────────────
+class _Timer:
+    """Lightweight step timer for pipeline instrumentation."""
+    def __init__(self) -> None:
+        self._steps: dict[str, float] = {}
+        self._start = time.monotonic()
+
+    def mark(self, step: str) -> None:
+        self._steps[step] = round((time.monotonic() - self._start) * 1000)
+
+    def log_summary(self, extra_fields: dict[str, Any] | None = None) -> None:
+        summary = {**self._steps, **(extra_fields or {})}
+        log.info("Pipeline timing (ms): %s", summary)
+
+    @property
+    def total_ms(self) -> int:
+        return round((time.monotonic() - self._start) * 1000)
+
+
+# ── Route ──────────────────────────────────────────────────────────────────────
+
+router = APIRouter()
+
+
+@router.post("/analyze", response_model=AnalyzeResponse, summary="Analyze a lab report PDF or text")
+async def analyze(
+    file:          UploadFile | None = File(None,   description="PDF file upload (optional if text provided)"),
+    text:          str | None        = Form(None,   description="Raw report text (optional if file provided)"),
+    lang:          str               = Form("en",   description="Response language: 'en' or 'hi'"),
+    tier:          str               = Form("free", description="User tier: 'free' or 'premium'"),
+    authorization: str | None        = Header(None, description="Bearer JWT from Supabase Auth"),
+    x_user_tier:   str | None        = Header(None, alias="x-user-tier"),
+) -> AnalyzeResponse:
+
+    timer = _Timer()
+
+    # ── Resolve tier (header takes precedence over form field) ───────────────
+    resolved_tier_str = (x_user_tier or tier or "free").lower().strip()
+    resolved_tier     = UserTier.PREMIUM if resolved_tier_str == "premium" else UserTier.FREE
+    is_premium        = resolved_tier == UserTier.PREMIUM
+
+    # ── Step 1: Input validation ─────────���────────────────────────────────────
+    if file is None and not text:
+        raise HTTPException(
+            status_code=400,
+            detail="Either a PDF file or report text is required.",
+        )
+
+    if file is not None:
+        ctype = (file.content_type or "").lower()
+        if ctype not in ("application/pdf", "text/plain", ""):
+            raise HTTPException(
+                status_code=415,
+                detail=f"Unsupported file type: {ctype}. Only PDF and .txt are supported.",
+            )
+
+    timer.mark("step1_validation")
+
+    # ── Step 2: Text extraction (Tier 1) ──────────────────────────────────────
+    extracted_text = ""
+    extraction_warnings: list[str] = []
+
+    if file is not None:
+        file_bytes = await file.read()
+
+        # Guard: 10 MB max
+        if len(file_bytes) > 10 * 1024 * 1024:
+            raise HTTPException(
+                status_code=413,
+                detail="File too large. Maximum size is 10 MB.",
+            )
+
+        ctype = (file.content_type or "").lower()
+
+        if ctype == "text/plain":
+            try:
+                extracted_text = file_bytes.decode("utf-8", errors="replace")
+            except Exception as exc:  # noqa: BLE001
+                raise HTTPException(
+                    status_code=422,
+                    detail=f"Could not read text file: {exc}",
+                ) from exc
+        else:
+            # Treat as PDF
+            try:
+                result = await extract_text_from_pdf(file_bytes)
+                extracted_text    = result.text
+                extraction_warnings = result.warnings
+
+                if result.is_likely_scanned:
+                    log.warning(
+                        "Possible scanned PDF (char_count=%d, pages=%d). "
+                        "OCR not yet supported.",
+                        result.char_count, result.page_count,
+                    )
+
+                log.info(
+                    "PDF extracted: method=%s pages=%d chars=%d",
+                    result.method_used, result.page_count, result.char_count,
+                )
+
+            except Exception as exc:  # noqa: BLE001
+                log.error("PDF extraction error: %s", exc)
+                raise HTTPException(
+                    status_code=422,
+                    detail=(
+                        "Could not parse this PDF format. "
+                        "Try copy-pasting the report text instead."
+                    ),
+                ) from exc
+    else:
+        # Direct text submission
+        extracted_text = str(text or "").strip()
+
+    if len(extracted_text.strip()) < 50:
+        raise HTTPException(
+            status_code=400,
+            detail="Could not extract meaningful text from the uploaded file. "
+                   "Please try pasting the report text manually.",
+        )
+
+    timer.mark("step2_extraction")
+
+    # ── Step 3: Patient metadata ──────────────────────────────────────────────
+    metadata = extract_patient_metadata(extracted_text)
+    patient_gender = metadata.get("patient_gender", "unknown")
+    patient_age    = metadata.get("patient_age",    "")
+
+    log.info(
+        "Patient: name=%r age=%r gender=%r lab=%r",
+        metadata.get("patient_name"),
+        patient_age,
+        patient_gender,
+        metadata.get("lab_name"),
+    )
+
+    timer.mark("step3_metadata")
+
+    # ── Step 4: Biomarker parsing + classification (Tier 2) ───────────────────
+    raw_biomarkers = parse_biomarkers(extracted_text)
+    classified     = resolve_and_classify(raw_biomarkers, gender=patient_gender)
+
+    log.info(
+        "Biomarkers: raw=%d classified=%d abnormal=%d",
+        len(raw_biomarkers),
+        len(classified),
+        sum(1 for b in classified if b.status.value != "Normal"),
+    )
+
+    if not classified:
+        raise HTTPException(
+            status_code=422,
+            detail=(
+                "No biomarkers found in this report. "
+                "Please ensure this is a standard Indian pathology report "
+                "(Thyrocare, Dr. Lal, Apollo, SRL, etc.)."
+            ),
+        )
+
+    timer.mark("step4_parsing")
+
+    # ── Step 5: Health scoring (Tier 2 — deterministic) ───────────────────────
+    metrics = compute_health_metrics(classified, patient_age, patient_gender)
+
+    log.info(
+        "Metrics: score=%d grade=%s bio_age=%d critical=%s",
+        metrics.health_score,
+        metrics.health_grade,
+        metrics.biological_age,
+        metrics.has_critical_alert,
+    )
+
+    timer.mark("step5_scoring")
+
+    # ── Step 6: AI explanations (Tier 3 — free for all) ───────────────────────
+    patient_context = (
+        f"{patient_gender.capitalize()}, {patient_age} years, "
+        f"{metadata.get('lab_name', 'Indian lab')} report"
+    )
+
+    try:
+        classified_enriched = await generate_explanations(
+            classified, patient_context, lang
+        )
+    except Exception as exc:  # noqa: BLE001
+        # AI explanations failed — still return deterministic data
+        log.error("Tier 3 explanation generation failed (non-fatal): %s", exc)
+        classified_enriched = classified   # use unenriched biomarkers
+
+    timer.mark("step6_explanations")
+
+    # ── Step 7: Deep analysis (Tier 4 — premium only) ─────────────────────────
+    abnormal_count = sum(1 for b in classified_enriched if b.status.value != "Normal")
+
+    # Build preliminary report (will be updated with deep analysis if premium)
+    summary_en, summary_hi = _template_summary(
+        abnormal_count, metrics.health_score, metrics.health_grade, lang
+    )
+
+    # Preliminary bio_age_insight from scorer factors
+    bio_age_insight = ""
+    if metrics.chronological_age > 0 and metrics.biological_age > 0:
+        diff = metrics.biological_age - metrics.chronological_age
+        if diff > 0:
+            bio_age_insight = (
+                f"Your body is functioning approximately {diff} year(s) older than your "
+                f"actual age of {metrics.chronological_age}, primarily due to nutritional deficiencies."
+            )
+        elif diff < 0:
+            bio_age_insight = (
+                f"Great news — your body is functioning {abs(diff)} year(s) younger than "
+                f"your actual age of {metrics.chronological_age}!"
+            )
+        else:
+            bio_age_insight = (
+                f"Your biological age matches your chronological age of {metrics.chronological_age}."
+            )
+
+    preliminary_report = LabReport(
+        # Patient
+        patient_name=metadata.get("patient_name",   ""),
+        patient_age=patient_age,
+        patient_gender=patient_gender,
+        report_date=metadata.get("report_date",     ""),
+        lab_name=metadata.get("lab_name",           ""),
+        # Scores (deterministic)
+        health_score=metrics.health_score,
+        health_grade=metrics.health_grade,          # type: ignore[arg-type]
+        # Bio age (deterministic baseline)
+        biological_age=metrics.biological_age,
+        chronological_age=metrics.chronological_age,
+        bio_age_insight=bio_age_insight,
+        bio_age_protocol=[],
+        # Summaries
+        summary=summary_en,
+        summary_hindi=summary_hi,
+        doctor_note="",
+        top_priority=metrics.top_priority,
+        # Alerts
+        has_critical_alert=metrics.has_critical_alert,
+        critical_alert_text=metrics.critical_alert_text,
+        # Biomarkers
+        biomarkers=classified_enriched,
+        # Metadata
+        tier_used=resolved_tier,
+        processing_time_ms=timer.total_ms,
+        ai_provider_used="tier2_only",
+    )
+
+    final_report = preliminary_report
+
+    if is_premium:
+        try:
+            deep = await generate_deep_analysis(preliminary_report, lang)
+            # Merge Tier 4 fields into report
+            final_report = preliminary_report.model_copy(update={
+                "summary":          deep.summary          or summary_en,
+                "summary_hindi":    deep.summary_hindi    or summary_hi,
+                "doctor_note":      deep.doctor_note,
+                "bio_age_insight":  deep.bio_age_insight  or bio_age_insight,
+                "bio_age_protocol": deep.bio_age_protocol,
+                "ai_provider_used": "claude",
+            })
+            log.info("Tier 4 deep analysis merged successfully")
+        except Exception as exc:  # noqa: BLE001
+            log.error("Tier 4 deep analysis failed (non-fatal): %s", exc)
+            # Return deterministic + Tier 3 data — deep analysis fields stay as templates
+            final_report = preliminary_report.model_copy(update={
+                "ai_provider_used": "tier3_only",
+            })
+    else:
+        # Free tier — use template summaries, empty protocol
+        final_report = preliminary_report.model_copy(update={
+            "ai_provider_used": "gemini_groq",
+        })
+
+    timer.mark("step7_deep_analysis")
+
+    # ── Step 8: Set final processing time ─────────────────────────────────────
+    final_report = final_report.model_copy(update={
+        "processing_time_ms": timer.total_ms,
+    })
+
+    timer.mark("step8_assemble")
+
+    # ── Step 9: Persist to Supabase (fire-and-forget) ─────────────────────────
+    if authorization and authorization.startswith("Bearer "):
+        token = authorization.removeprefix("Bearer ").strip()
+        asyncio.create_task(_persist_report(token, final_report))
+
+    timer.mark("step9_persist_scheduled")
+
+    # ���─ Step 10: Log timing + return ──────────────────────────────────────────
+    timer.log_summary({
+        "tier":            resolved_tier_str,
+        "total_ms":        timer.total_ms,
+        "biomarkers":      len(classified_enriched),
+        "abnormal":        abnormal_count,
+        "health_score":    metrics.health_score,
+        "is_premium":      is_premium,
+    })
+
+    log.info(
+        "Analysis complete: score=%d grade=%s tier=%s total_ms=%d",
+        metrics.health_score,
+        metrics.health_grade,
+        resolved_tier_str,
+        timer.total_ms,
+    )
+
+    return final_report   # type: ignore[return-value]

app/api/chat.py

@@ -0,0 +1,222 @@
+"""
+LabCard AI — POST /api/chat
+============================
+Contextual chat with the patient's report as grounded context.
+
+Supports:
+  - Pure English ("why is my Vitamin D low?")
+  - Pure Hindi ("मेरा विटामिन D कम क्यों है?")
+  - Hinglish ("mera vitamin D low kyun hai?")
+  - Misspelled medical terms ("haemogloobin", "thyriod")
+
+Tier routing:
+  - Free    → Gemini 2.5 Flash (₹0) → Groq fallback (₹0)
+  - Premium → Claude Sonnet → Gemini → Groq
+
+Rate limit:
+  - Free:    10 messages per session (checked from message history length)
+  - Premium: unlimited
+"""
+from __future__ import annotations
+
+import json
+import logging
+
+from fastapi import APIRouter, HTTPException
+
+from app.core.ai_router import call_with_fallback
+from app.models.biomarker import BiomarkerStatus
+from app.models.report import ChatRequest, ChatResponse, LabReport, UserTier
+
+log = logging.getLogger("labcard.chat")
+
+# ── Rate limits ────────────────────────────────────────────────────────────────
+FREE_CHAT_LIMIT = 10   # max user turns per session for free tier
+
+
+# ── Hinglish normalization + chat system prompt ────────────────────────────────
+HINGLISH_NORMALIZER_PROMPT = """
+You are processing a patient's question about their lab report.
+The question may be in:
+- Pure Hindi (Devanagari: "मेरा हीमोग्लोबिन कम क्यों है?")
+- Pure English ("why is my hemoglobin low?")
+- Hinglish — Hindi-English mix, often romanized ("mera sugar high hai kyun?")
+- Medical terms misspelled ("haemogloobin", "thyriod", "शुगर", "खून की कमी")
+
+Your task: understand the patient's intent regardless of language or spelling.
+
+Rules:
+- Keep responses under 80 words
+- Never diagnose any disease or condition
+- Never recommend specific medications or dosages
+- For serious concerns, always say "please consult your doctor"
+- Be warm and reassuring — you are talking to a non-expert who may be worried
+- Use simple words, not medical jargon
+- If asked something unrelated to the report, gently redirect to the report context
+""".strip()
+
+
+def _build_system_prompt(report: LabReport, lang: str) -> str:
+    """
+    Inject classified report data as grounded context.
+    AI does NOT re-analyze — it only explains what the algorithms already found.
+    """
+    # Compact abnormal list — avoid sending the full biomarker object list
+    abnormal = [
+        f"{b.name}: {b.value_raw} {b.unit} ({b.status.value}, normal: {b.normal_range_text})"
+        for b in report.biomarkers
+        if b.status != BiomarkerStatus.NORMAL
+    ]
+    normal_count   = sum(1 for b in report.biomarkers if b.status == BiomarkerStatus.NORMAL)
+    abnormal_count = len(abnormal)
+
+    lang_instruction = (
+        "Hindi using proper Devanagari script (not romanized Hindi)"
+        if lang == "hi"
+        else "simple conversational Indian English"
+    )
+
+    # Build concise context block (controls token cost)
+    context_lines = [
+        f"Patient: {report.patient_name or 'Patient'}, {report.patient_age or 'unknown age'}, {report.patient_gender}",
+        f"Lab: {report.lab_name or 'Indian lab'}, Date: {report.report_date or 'unknown'}",
+        f"Health Score: {report.health_score}/100 ({report.health_grade})",
+        f"Biomarkers: {normal_count} normal, {abnormal_count} abnormal",
+    ]
+
+    if report.top_priority:
+        context_lines.append(f"Top priority: {report.top_priority}")
+
+    if abnormal:
+        # Cap at 12 to control context length
+        shown = abnormal[:12]
+        context_lines.append("Abnormal findings:")
+        context_lines.extend(f"  - {item}" for item in shown)
+        if len(abnormal) > 12:
+            context_lines.append(f"  ... and {len(abnormal) - 12} more")
+
+    if report.biological_age and report.chronological_age:
+        context_lines.append(
+            f"Biological age: {report.biological_age} years "
+            f"(actual: {report.chronological_age} years)"
+        )
+
+    context_block = "\n".join(context_lines)
+
+    return f"""{HINGLISH_NORMALIZER_PROMPT}
+
+Patient's Classified Report (pre-analyzed — do NOT re-analyze these values, they are correct):
+{context_block}
+
+Language instruction: Respond ONLY in {lang_instruction}.
+Keep your response under 80 words.
+If the patient asks about something not in the report, say you can only discuss what's in their report."""
+
+
+def _rate_limit_reply(lang: str) -> str:
+    """Return the rate-limit message in the user's language."""
+    if lang == "hi":
+        return (
+            "आपकी 10 free messages समाप्त हो गई हैं। "
+            "अधिक chat के लिए premium upgrade करें। 🙏"
+        )
+    return (
+        "You've reached the 10-message free chat limit. "
+        "Upgrade to premium for unlimited chat with Claude AI."
+    )
+
+
+def _error_reply(lang: str) -> str:
+    """Return the AI connection error message in the user's language."""
+    if lang == "hi":
+        return (
+            "अभी कनेक्शन में समस्या है। "
+            "कृपया थोड़ी देर बाद पुनः प्रयास करें। 🙏"
+        )
+    return (
+        "I'm having trouble connecting right now. "
+        "Please try again in a moment."
+    )
+
+
+# ── Route ──────────────────────────────────────────────────────────────────────
+
+router = APIRouter()
+
+
+@router.post("/chat", response_model=ChatResponse, summary="Chat about a lab report")
+async def chat(request: ChatRequest) -> ChatResponse:
+    """
+    Contextual chat endpoint.
+
+    The patient's classified report is injected as system context.
+    AI only generates language — all medical values are pre-verified
+    by the deterministic scoring pipeline.
+    """
+    lang = request.lang if request.lang in ("en", "hi") else "en"
+
+    # ── Validate messages ─────────────────────────────────────────────────────
+    if not request.messages:
+        raise HTTPException(
+            status_code=400,
+            detail="messages list cannot be empty.",
+        )
+
+    # ── Rate limiting (session-level — free tier only) ────────────────────────
+    # Count user turns from the message history sent by the client
+    if request.tier == UserTier.FREE:
+        user_turn_count = sum(1 for m in request.messages if m.role == "user")
+        if user_turn_count > FREE_CHAT_LIMIT:
+            log.info("Free chat rate limit hit (user_turns=%d)", user_turn_count)
+            return ChatResponse(
+                reply=_rate_limit_reply(lang),
+                lang=lang,
+            )
+
+    # ── Parse report_data ─────────────────────────────────────────────────────
+    try:
+        report_dict = json.loads(request.report_data)
+        report      = LabReport.model_validate(report_dict)
+    except (json.JSONDecodeError, ValueError) as exc:
+        log.warning("Could not parse report_data: %s", exc)
+        # Degrade gracefully — chat without full report context
+        report = LabReport(
+            health_score=0,
+            health_grade="Fair",   # type: ignore[arg-type]
+            biomarkers=[],
+        )
+
+    # ── Build system prompt with report context ───────────────────────────────
+    system_prompt = _build_system_prompt(report, lang)
+
+    # ── Convert ChatMessage list → provider dict format ───────────────────────
+    messages = [
+        {"role": m.role, "content": m.content}
+        for m in request.messages
+    ]
+
+    # ── Route by tier ─────────────────────────────────────────────────────────
+    preferred = "claude" if request.tier == UserTier.PREMIUM else "gemini"
+
+    try:
+        raw_reply, provider = await call_with_fallback(
+            messages=messages,
+            system=system_prompt,
+            preferred=preferred,
+            max_tokens=300,    # 80-word limit → 300 tokens is generous
+        )
+        reply = raw_reply.strip()
+
+        log.info(
+            "Chat reply: tier=%s provider=%s lang=%s chars=%d",
+            request.tier.value,
+            provider,
+            lang,
+            len(reply),
+        )
+
+    except Exception as exc:  # noqa: BLE001
+        log.error("Chat AI failure (all providers): %s", exc)
+        reply = _error_reply(lang)
+
+    return ChatResponse(reply=reply, lang=lang)

app/api/health.py

@@ -0,0 +1,31 @@
+"""
+LabCard AI — GET /api/health
+Health check + warm-up endpoint.
+HF Spaces free tier sleeps after 48h inactivity.
+Frontend pings this on mount to wake the container before the user uploads.
+"""
+from __future__ import annotations
+
+import sys
+import time
+from datetime import datetime, timezone
+
+from fastapi import APIRouter
+
+router = APIRouter()
+
+_START_TIME = time.monotonic()
+
+
+@router.get("/health", summary="Health check + warm-up ping")
+async def health_check() -> dict[str, str | float | bool]:
+    uptime_seconds = round(time.monotonic() - _START_TIME, 1)
+    return {
+        "status":          "healthy",
+        "service":         "labcard-backend",
+        "version":         "1.0.0",
+        "python":          sys.version.split()[0],
+        "uptime_seconds":  uptime_seconds,
+        "timestamp":       datetime.now(timezone.utc).isoformat(),
+        "is_warm":         uptime_seconds > 5,   # False on cold start
+    }

app/config.py

@@ -0,0 +1,47 @@
+"""
+LabCard AI Backend — Configuration
+All settings loaded from environment variables via pydantic-settings.
+"""
+from pydantic_settings import BaseSettings
+from functools import lru_cache
+
+
+class Settings(BaseSettings):
+    # AI keys
+    anthropic_api_key: str = ""
+    gemini_api_key: str = ""
+    groq_api_key: str = ""
+
+    # Supabase
+    supabase_url: str = ""
+    supabase_service_key: str = ""
+    supabase_jwt_secret: str = ""
+
+    # Upstash Redis
+    upstash_redis_rest_url: str = ""
+    upstash_redis_rest_token: str = ""
+
+    # CORS — comma-separated Vercel + localhost
+    allowed_origins: str = "http://localhost:3000"
+
+    # App
+    environment: str = "development"
+    log_level: str = "info"
+
+    @property
+    def origins_list(self) -> list[str]:
+        return [o.strip() for o in self.allowed_origins.split(",")]
+
+    @property
+    def is_production(self) -> bool:
+        return self.environment == "production"
+
+    model_config = {"env_file": ".env", "extra": "ignore"}
+
+
+@lru_cache()
+def get_settings() -> Settings:
+    return Settings()
+
+
+settings = get_settings()

app/core/__init__.py

@@ -0,0 +1 @@
+# LabCard AI Backend

app/core/ai_router.py

@@ -0,0 +1,484 @@
+"""
+LabCard AI — AI Router (Tier 3 + Tier 4)
+==========================================
+Tier 3 — Gemini 2.5 Flash (FREE, 10 RPM) → Groq fallback
+         Used ONLY for language generation (explanations, advice, foods).
+         Status/classification already done by deterministic scorer.py.
+
+Tier 4 — Claude Sonnet (premium users only)
+         Deep analysis: bio-age narrative, doctor note, summaries.
+         Falls back to Gemini → Groq if Claude fails.
+
+Key insight: AI here generates WORDS, not medical judgments.
+If AI hallucinates, only the advice text is wrong — the health card is always correct.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import time
+from dataclasses import dataclass, field
+from typing import Literal
+
+import httpx
+from anthropic import AsyncAnthropic
+from groq import AsyncGroq
+
+from app.config import settings
+from app.models.biomarker import Biomarker, BiomarkerStatus
+from app.models.report import LabReport
+
+log = logging.getLogger("labcard.ai_router")
+
+# ── Client singletons (initialized once at module load) ──────────────────────
+# Connection pooling: reuse connections across requests
+_groq_client:    AsyncGroq       | None = None
+_claude_client:  AsyncAnthropic  | None = None
+_http_client:    httpx.AsyncClient | None = None   # for Gemini REST
+
+
+def _get_groq() -> AsyncGroq:
+    global _groq_client
+    if _groq_client is None:
+        _groq_client = AsyncGroq(api_key=settings.groq_api_key)
+    return _groq_client
+
+
+def _get_claude() -> AsyncAnthropic:
+    global _claude_client
+    if _claude_client is None:
+        _claude_client = AsyncAnthropic(api_key=settings.anthropic_api_key)
+    return _claude_client
+
+
+def _get_http() -> httpx.AsyncClient:
+    global _http_client
+    if _http_client is None:
+        _http_client = httpx.AsyncClient(timeout=30.0)
+    return _http_client
+
+
+# ── Output dataclass ──────────────────────────────────────────────────────────
+
+@dataclass
+class DeepAnalysisResult:
+    """Output of Tier 4 Claude analysis."""
+    summary:            str
+    summary_hindi:      str
+    doctor_note:        str
+    bio_age_insight:    str
+    bio_age_protocol:   list[str] = field(default_factory=list)
+
+
+# ── System prompts ────────────────────────────────────────────────────────────
+
+_TIER3_SYSTEM = """You are a medical report interpreter for Indian patients. You receive pre-classified
+biomarker data (status already determined by validated medical algorithms).
+Your ONLY job is to write patient-friendly language. Do NOT reclassify or second-guess
+the status values — they are correct.
+
+Rules:
+- Keep each explanation under 25 words
+- Use simple language a non-medical person understands
+- Hindi must be in Devanagari script (not romanized)
+- Indian foods: use common names + Hindi name in brackets e.g. "Palak (पालक)"
+- Never use words: "alarming", "dangerous", "serious", "critical" — status is already shown
+- Never diagnose. Just explain and advise.
+- Respond ONLY with valid JSON array. No markdown, no preamble, no code fences."""
+
+_TIER4_SYSTEM = """You are a senior physician reviewing an Indian patient's lab report. The report has
+already been analyzed and classified by validated algorithms. Your task is ONLY to:
+1. Write a 2-sentence patient summary (English)
+2. Write the same summary in Hindi (Devanagari)
+3. Write a brief clinical note for a doctor (max 50 words)
+4. Write one sentence comparing the patient's biological age to chronological age
+5. List exactly 3 actionable protocol steps to improve biological age
+
+Return ONLY valid JSON (no markdown, no code fences):
+{
+  "summary": "...",
+  "summary_hindi": "...",
+  "doctor_note": "...",
+  "bio_age_insight": "...",
+  "bio_age_protocol": ["step 1", "step 2", "step 3"]
+}
+
+You are NOT re-analyzing the report. The classifications are correct. Focus on
+clear, warm, actionable communication for an Indian patient.
+Never diagnose. Always recommend consulting a doctor for treatment decisions."""
+
+# ── Normal biomarker template (zero AI cost) ──────────────────────────────────
+
+def _normal_template(bm: Biomarker, lang: str) -> dict[str, str | list[str]]:
+    """
+    Hardcoded template for NORMAL biomarkers.
+    Saves API quota — no need to send normal values to AI.
+    """
+    en = (
+        f"Your {bm.name} is {bm.value_raw} {bm.unit}, "
+        f"which is within the normal range ({bm.normal_range_text}). Keep it up!"
+    )
+    hi = (
+        f"आपका {bm.name} {bm.value_raw} {bm.unit} है, "
+        f"जो सामान्य सीमा ({bm.normal_range_text}) में है। बढ़िया है!"
+    )
+    return {
+        "name":                bm.name,
+        "explanation":         en,
+        "explanation_hindi":   hi,
+        "advice":              "Continue your current healthy habits.",
+        "indian_foods":        [],
+    }
+
+
+# ── Provider: Gemini 2.5 Flash (REST) ────────────────────────────────────────
+
+async def call_gemini(prompt: str, max_tokens: int = 2000) -> str:
+    """
+    Call Gemini 2.5 Flash via REST API (no SDK — lighter dependency).
+    Model: gemini-2.5-flash (GA as of 2026; gemini-1.5-flash is retired → 404)
+    Free tier: 10 RPM, 1M tokens/day on Google AI Studio key.
+    """
+    if not settings.gemini_api_key:
+        raise ValueError("GEMINI_API_KEY not set")
+
+    url = (
+        f"https://generativelanguage.googleapis.com/v1beta/models/"
+        f"gemini-2.5-flash:generateContent?key={settings.gemini_api_key}"
+    )
+    body = {
+        "contents": [{"parts": [{"text": prompt}]}],
+        "generationConfig": {
+            "maxOutputTokens": max_tokens,
+            "temperature":     0.2,    # low temp for consistent JSON
+            "topP":            0.8,
+        },
+    }
+
+    http = _get_http()
+    resp = await http.post(url, json=body)
+    resp.raise_for_status()
+    data = resp.json()
+
+    text: str = data["candidates"][0]["content"]["parts"][0]["text"]
+    return text.strip()
+
+
+# ── Provider: Groq ────────────────────────────────────────────────────────────
+
+async def call_groq(
+    messages:   list[dict[str, str]],
+    system:     str,
+    max_tokens: int = 2000,
+) -> str:
+    """
+    Call Groq Llama-3.3-70b (free: 30 RPM, 6000 TPM).
+    Used as Tier 3 fallback when Gemini quota exceeded.
+    """
+    if not settings.groq_api_key:
+        raise ValueError("GROQ_API_KEY not set")
+
+    client = _get_groq()
+    resp   = await client.chat.completions.create(
+        model="llama-3.3-70b-versatile",
+        messages=[{"role": "system", "content": system}, *messages],
+        max_tokens=max_tokens,
+        temperature=0.2,
+    )
+    content = resp.choices[0].message.content
+    if not content:
+        raise ValueError("Groq returned empty response")
+    return content.strip()
+
+
+# ── Provider: Claude ──────────────────────────────────────────────────────────
+
+async def call_claude(
+    messages:   list[dict[str, str]],
+    system:     str,
+    max_tokens: int = 1000,
+) -> str:
+    """
+    Call Claude Sonnet 4 (Tier 4 — premium users only).
+    Best medical reasoning. ~₹4–5 per analysis.
+    """
+    if not settings.anthropic_api_key:
+        raise ValueError("ANTHROPIC_API_KEY not set")
+
+    client = _get_claude()
+    resp   = await client.messages.create(
+        model="claude-sonnet-4-20250514",
+        max_tokens=max_tokens,
+        system=system,
+        messages=messages,  # type: ignore[arg-type]
+    )
+    text = resp.content[0].text if resp.content else ""
+    if not text:
+        raise ValueError("Claude returned empty response")
+    return text.strip()
+
+
+# ── Fallback orchestrator ─────────────────────────────────────────────────────
+
+async def call_with_fallback(
+    messages:   list[dict[str, str]],
+    system:     str,
+    preferred:  Literal["gemini", "claude"],
+    max_tokens: int = 2000,
+) -> tuple[str, str]:
+    """
+    Route AI call with automatic fallback.
+
+    Tier 3 (preferred="gemini"):
+      gemini-2.5-flash → groq/llama-3.3 → raise
+
+    Tier 4 (preferred="claude"):
+      claude-sonnet-4 → gemini-2.5-flash → groq/llama-3.3 → raise
+
+    Returns: (response_text, provider_name_used)
+    Logs: provider, latency_ms, success/failure
+    """
+    user_prompt = "\n".join(m["content"] for m in messages if m["role"] == "user")
+
+    # Build provider chain based on preferred
+    if preferred == "gemini":
+        chain: list[tuple[str, object]] = [
+            ("gemini", lambda: call_gemini(f"{system}\n\n{user_prompt}", max_tokens)),
+            ("groq",   lambda: call_groq(messages, system, max_tokens)),
+        ]
+    else:  # claude
+        chain = [
+            ("claude", lambda: call_claude(messages, system, max_tokens)),
+            ("gemini", lambda: call_gemini(f"{system}\n\n{user_prompt}", max_tokens)),
+            ("groq",   lambda: call_groq(messages, system, max_tokens)),
+        ]
+
+    last_error: Exception | None = None
+
+    for provider_name, fn in chain:
+        t0 = time.monotonic()
+        try:
+            result: str = await fn()  # type: ignore[operator]
+            latency = round((time.monotonic() - t0) * 1000)
+            log.info(
+                "AI call success",
+                extra={
+                    "provider": provider_name,
+                    "latency_ms": latency,
+                    "tokens_est": len(result.split()) * 1.3,
+                },
+            )
+            return result, provider_name
+        except Exception as exc:  # noqa: BLE001
+            latency = round((time.monotonic() - t0) * 1000)
+            log.warning(
+                "AI provider failed — trying next",
+                extra={
+                    "provider":   provider_name,
+                    "latency_ms": latency,
+                    "error":      str(exc)[:120],
+                },
+            )
+            last_error = exc
+
+    raise RuntimeError(
+        f"All AI providers failed. Last error: {last_error}"
+    ) from last_error
+
+
+# ── Tier 3: Generate biomarker explanations ───────────────────────────────────
+
+async def generate_explanations(
+    biomarkers:      list[Biomarker],
+    patient_context: str,
+    lang:            str = "en",
+) -> list[Biomarker]:
+    """
+    Tier 3 — Gemini Flash (free) + Groq fallback.
+
+    Strategy:
+    - Normal biomarkers → hardcoded template (zero API cost)
+    - Abnormal biomarkers → single batched Gemini/Groq call
+    - Merges results back into biomarker list
+
+    patient_context: brief string e.g. "Male, 28 years, Thyrocare report"
+    """
+    abnormal = [b for b in biomarkers if b.status != BiomarkerStatus.NORMAL]
+    normal   = [b for b in biomarkers if b.status == BiomarkerStatus.NORMAL]
+
+    # ── Normal → template (free) ──────────────────────────────────────────────
+    enriched_normal: dict[str, dict[str, str | list[str]]] = {
+        b.name: _normal_template(b, lang)
+        for b in normal
+    }
+
+    # ── Abnormal → AI call ────────────────────────────────────────────────────
+    enriched_abnormal: dict[str, dict[str, str | list[str]]] = {}
+
+    if abnormal:
+        payload = [
+            {
+                "name":   b.name,
+                "value":  b.value_raw,
+                "unit":   b.unit,
+                "status": b.status.value,
+                "range":  b.normal_range_text,
+            }
+            for b in abnormal
+        ]
+
+        user_msg = (
+            f"Patient context: {patient_context}\n\n"
+            f"Classify and explain these abnormal biomarkers:\n"
+            f"{json.dumps(payload, ensure_ascii=False)}"
+        )
+
+        messages = [{"role": "user", "content": user_msg}]
+
+        try:
+            raw, provider = await call_with_fallback(
+                messages=messages,
+                system=_TIER3_SYSTEM,
+                preferred="gemini",
+                max_tokens=2000,
+            )
+
+            # Strip markdown fences if present
+            clean = raw.strip()
+            clean = clean.removeprefix("```json").removeprefix("```").removesuffix("```").strip()
+
+            items: list[dict] = json.loads(clean)
+            for item in items:
+                name = item.get("name", "")
+                if name:
+                    enriched_abnormal[name] = item
+
+        except Exception as exc:  # noqa: BLE001
+            log.error("Tier 3 explanation generation failed: %s", exc)
+            # Fallback: give abnormal markers a generic message
+            for b in abnormal:
+                enriched_abnormal[b.name] = {
+                    "name":              b.name,
+                    "explanation":       f"Your {b.name} is {b.value_raw} {b.unit} ({b.status.value}). Consult your doctor.",
+                    "explanation_hindi": f"आपका {b.name} {b.value_raw} {b.unit} ({b.status.value}) है। अपने डॉक्टर से मिलें।",
+                    "advice":            "Please consult your doctor for guidance.",
+                    "indian_foods":      [],
+                }
+
+    # ── Merge enrichments back into biomarker objects ─────────────────────────
+    all_enriched = {**enriched_normal, **enriched_abnormal}
+    result: list[Biomarker] = []
+
+    for b in biomarkers:
+        enrichment = all_enriched.get(b.name)
+        if enrichment:
+            # Return new Biomarker with AI fields populated
+            result.append(b.model_copy(update={
+                "explanation":       str(enrichment.get("explanation", "")),
+                "explanation_hindi": str(enrichment.get("explanation_hindi", "")),
+                "advice":            str(enrichment.get("advice", "")),
+                "indian_foods":      list(enrichment.get("indian_foods", [])),
+            }))
+        else:
+            result.append(b)
+
+    return result
+
+
+# ── Tier 4: Deep analysis (Claude — premium only) ─────────────────────────────
+
+async def generate_deep_analysis(
+    report: LabReport,
+    lang:   str = "en",
+) -> DeepAnalysisResult:
+    """
+    Tier 4 — Claude Sonnet (premium users only). Falls back to Gemini/Groq.
+
+    Sends the full classified report to Claude for:
+    - Patient summaries (EN + HI)
+    - Doctor handoff note
+    - Biological age insight sentence
+    - 3-step improvement protocol
+    """
+    # Build concise report digest for Claude
+    # Don't send raw PDF text — only classified results
+    abnormal = [b for b in report.biomarkers if b.status != BiomarkerStatus.NORMAL]
+    normal_count   = len(report.biomarkers) - len(abnormal)
+    critical_count = sum(1 for b in abnormal if b.status.value == "Critical")
+
+    abnormal_summary = [
+        f"{b.name}: {b.value_raw} {b.unit} [{b.status.value}] (normal: {b.normal_range_text})"
+        for b in abnormal
+    ]
+
+    report_digest = {
+        "patient_age":          report.patient_age,
+        "patient_gender":       report.patient_gender,
+        "lab_name":             report.lab_name,
+        "health_score":         report.health_score,
+        "health_grade":         report.health_grade,
+        "biological_age":       report.biological_age,
+        "chronological_age":    report.chronological_age,
+        "total_biomarkers":     len(report.biomarkers),
+        "normal_count":         normal_count,
+        "abnormal_count":       len(abnormal),
+        "critical_count":       critical_count,
+        "abnormal_findings":    abnormal_summary[:15],  # cap at 15 to control tokens
+    }
+
+    user_msg = (
+        f"Generate patient communication for this analyzed report:\n"
+        f"{json.dumps(report_digest, ensure_ascii=False, indent=2)}"
+    )
+
+    messages = [{"role": "user", "content": user_msg}]
+
+    raw, provider = await call_with_fallback(
+        messages=messages,
+        system=_TIER4_SYSTEM,
+        preferred="claude",
+        max_tokens=1000,
+    )
+
+    log.info("Tier 4 analysis completed via %s", provider)
+
+    # Parse response
+    clean = raw.strip()
+    clean = clean.removeprefix("```json").removeprefix("```").removesuffix("```").strip()
+
+    try:
+        data: dict = json.loads(clean)
+    except json.JSONDecodeError as exc:
+        log.error("Tier 4 JSON parse failed: %s\nRaw: %s", exc, clean[:300])
+        # Return safe defaults
+        return DeepAnalysisResult(
+            summary=f"Your health score is {report.health_score}/100 ({report.health_grade}). "
+                    f"Please review the findings below and consult your doctor.",
+            summary_hindi=(
+                f"आपका स्वास्थ्य स्कोर {report.health_score}/100 ({report.health_grade}) है। "
+                "कृपया नीचे दिए गए परिणामों की समीक्षा करें और अपने डॉक्टर से परामर्श लें।"
+            ),
+            doctor_note=(
+                f"Patient: {report.patient_age}, {report.patient_gender}. "
+                f"Health score: {report.health_score}/100. "
+                f"{len(abnormal)} abnormal findings. Please review."
+            ),
+            bio_age_insight=(
+                "Biological age estimated from blood biomarkers. "
+                "Consult your doctor for detailed interpretation."
+            ),
+            bio_age_protocol=[
+                "Follow up with your doctor about abnormal findings.",
+                "Maintain a balanced diet with adequate iron and vitamins.",
+                "Get re-tested in 3 months to track improvement.",
+            ],
+        )
+
+    return DeepAnalysisResult(
+        summary=data.get("summary", ""),
+        summary_hindi=data.get("summary_hindi", ""),
+        doctor_note=data.get("doctor_note", ""),
+        bio_age_insight=data.get("bio_age_insight", ""),
+        bio_age_protocol=data.get("bio_age_protocol", [])[:3],
+    )

app/core/biomarker_parser.py

@@ -0,0 +1,497 @@
+"""
+LabCard AI — Biomarker Regex Parser
+=====================================
+100% deterministic. Zero LLM. Zero I/O.
+
+Handles all major Indian lab report formats:
+  Format A (Thyrocare): "Hemoglobin           : 10.2  g/dL        [13.0 - 17.0]"
+  Format B (Dr. Lal):   "HEMOGLOBIN (Hb)      10.2   g/dL    13.0 - 17.0   L"
+  Format C (Apollo):    "Haemoglobin   10.2g/dL   Ref: 13.0-17.0"
+  Format D (plain):     "Hb: 10.2 g/dL (N: 13-17)"
+"""
+from __future__ import annotations
+
+import re
+from typing import Optional
+
+from app.models.biomarker import Biomarker, BiomarkerCategory, BiomarkerRaw, BiomarkerStatus
+
+# ── Skip keywords — lines containing these are headers/footers, not data ───────
+_SKIP_KEYWORDS: frozenset[str] = frozenset({
+    "unit", "parameter", "test name", "test  name", "result", "reference",
+    "ref. range", "ref range", "normal range", "biological ref",
+    "---", "===", "page", "report", "printed", "signature",
+    "interpretation", "note:", "footnote", "pathologist",
+    "dr.", "mbbs", "md ", "phd", "this is", "generated",
+    "authorised", "authorized", "checked by",
+})
+
+# Textbook / footer / contact noise — block before parsing
+_NOISE_SUBSTRINGS: frozenset[str] = frozenset({
+    "edition", "chapter", "diagnosis", "fifth", "page", "disclaimer",
+    "signature", "queries", "www.", "http", "©", "tel:", "mob:",
+    "copyright", "all rights", "pathology", "laboratory report end",
+})
+
+# Biomarker names containing these are never valid analytes
+_NOISE_NAME_SUBSTRINGS: frozenset[str] = frozenset({
+    "edition", "chapter", "diagnosis", "fifth", "molecular diagnosis",
+    "disclaimer", "signature", "www.", "http", "copyright", "page ",
+    "printed on", "report id", "barcode", "specimen",
+})
+
+# ── Parenthetical suffixes to strip from test names ────────────────────────────
+_STRIP_SUFFIXES: tuple[str, ...] = (
+    r"\(automated\)",
+    r"\(quantitative\)",
+    r"\(serum\)",
+    r"\(blood\)",
+    r"\(plasma\)",
+    r"\(urine\)",
+    r"\(random\)",
+    r"\(fasting\)",
+    r"\(whole blood\)",
+    r"\(enzymatic\)",
+    r"\(colorimetric\)",
+    r"\(nephelometry\)",
+    r"\(calculated\)",
+    r"\(direct\)",
+    r"\(indirect\)",
+)
+
+# ── Compiled regex patterns ────────────────────────────────────────────────────
+
+# Format A + B: colon or tabular — most common Thyrocare / Dr. Lal layout
+# Groups: (name)(value)(unit)(range)
+PRIMARY_PATTERN = re.compile(
+    r"([A-Za-z][A-Za-z0-9\s\(\)\.\/\-]{2,40}?)"   # test name  (non-greedy, 3-41 chars)
+    r"\s*:?\s*"                                      # optional colon separator
+    r"([\d]+\.?[\d]*)"                               # numeric value
+    r"\s+"                                           # mandatory space
+    r"([\w\/\%µμ]+(?:\/[\w]+)?)"                    # unit (handles g/dL, mEq/L, µg/mL)
+    r"\s*[\[\(]?\s*"                                 # optional opening bracket
+    r"([\d\.]+\s*[-–]\s*[\d\.]+|[<>]\s*[\d\.]+)"   # range: X-Y or <Y or >X
+    r"\s*[\]\)]?",                                   # optional closing bracket
+    re.IGNORECASE,
+)
+
+# Format C: no brackets, optional "Ref:" prefix
+# Groups: (name)(value)(unit)(range)
+SECONDARY_PATTERN = re.compile(
+    r"([A-Za-z][A-Za-z0-9\s\(\)\.]{2,40}?)"        # test name
+    r"\s+"
+    r"([\d]+\.?[\d]*)"                               # value
+    r"\s*"
+    r"([\w\/\%]+)"                                   # unit
+    r"\s+"
+    r"(?:[Rr]ef\s*[:\-]\s*)?"                       # optional "Ref:"
+    r"([\d\.]+\s*[-–]\s*[\d\.]+)",                  # range X-Y only
+    re.IGNORECASE,
+)
+
+# Format D: inline abbreviated "Hb: 10.2 g/dL (N: 13-17)"
+# Groups: (name)(value)(unit)(range)
+INLINE_PATTERN = re.compile(
+    r"([A-Za-z][A-Za-z0-9\s]{1,30}?)"              # test name (shorter)
+    r"\s*:\s*"                                       # colon required
+    r"([\d\.]+)"                                     # value
+    r"\s*"
+    r"([\w\/\%]+)"                                   # unit
+    r"\s+"
+    r"\(?"                                           # optional opening paren
+    r"(?:[Nn]\s*[:\-]\s*)?"                         # optional "N:" prefix
+    r"([\d\.]+\s*[-–]\s*[\d\.]+)"                  # range X-Y
+    r"\)?",                                          # optional closing paren
+    re.IGNORECASE,
+)
+
+# TSV format from pdfplumber table extraction
+# "Hemoglobin\t10.2\tg/dL\t13.0 - 17.0"
+TSV_PATTERN = re.compile(
+    r"^(.+?)\t"                                      # name (tab separated)
+    r"([\d]+\.?[\d]*)\t"                             # value
+    r"([\w\/\%µμ]+)\t"                              # unit
+    r"([\d\.]+\s*[-–]\s*[\d\.]+|[<>]\s*[\d\.]+)",  # range
+    re.IGNORECASE,
+)
+
+# All patterns in priority order
+_ALL_PATTERNS: list[tuple[str, re.Pattern[str]]] = [
+    ("tsv",       TSV_PATTERN),
+    ("primary",   PRIMARY_PATTERN),
+    ("secondary", SECONDARY_PATTERN),
+    ("inline",    INLINE_PATTERN),
+]
+
+
+# ── Helper functions ──────────────────────────────────────────────────────────
+
+def clean_test_name(raw: str) -> str:
+    """
+    Normalize a raw test name string.
+    - Strip whitespace
+    - Remove meaningless parenthetical suffixes
+    - Title case
+    - Max 50 chars
+    """
+    name = raw.strip()
+
+    # Remove meaningless suffixes (case-insensitive)
+    for suffix_pat in _STRIP_SUFFIXES:
+        name = re.sub(suffix_pat, "", name, flags=re.IGNORECASE)
+
+    # Collapse multiple spaces
+    name = re.sub(r"\s{2,}", " ", name).strip()
+
+    # Title case (handles ALL CAPS from some labs)
+    # Only title-case if predominantly uppercase
+    if name.upper() == name and len(name) > 3:
+        name = name.title()
+
+    # Trim to 50 chars
+    return name[:50]
+
+
+def parse_value(raw: str) -> float | None:
+    """
+    Parse a value string to float.
+
+    Handles:
+      "10.2"      → 10.2
+      "10,200"    → 10200.0   (Indian comma for thousands)
+      "<0.1"      → 0.05      (half of the threshold)
+      ">100"      → 101.0     (just above threshold)
+      "10.2 L"    → 10.2      (strip trailing letter flags)
+    """
+    if not raw:
+        return None
+
+    raw = raw.strip()
+
+    # Strip trailing single-letter flags like "L" (Low) or "H" (High)
+    raw = re.sub(r"\s+[LHlh]$", "", raw)
+
+    # Handle "< X" — report as half of value (below detectable)
+    m = re.match(r"^[<≤]\s*([\d,.]+)$", raw)
+    if m:
+        try:
+            v = float(m.group(1).replace(",", ""))
+            return round(v * 0.5, 4)
+        except ValueError:
+            return None
+
+    # Handle "> X"
+    m = re.match(r"^[>≥]\s*([\d,.]+)$", raw)
+    if m:
+        try:
+            v = float(m.group(1).replace(",", ""))
+            return round(v + 1, 4)
+        except ValueError:
+            return None
+
+    # Standard float — remove Indian comma notation
+    cleaned = raw.replace(",", "")
+    try:
+        return float(cleaned)
+    except ValueError:
+        return None
+
+
+def parse_range(raw: str) -> tuple[float | None, float | None]:
+    """
+    Parse range text → (low, high).
+
+    Handles all real-world Indian lab formats:
+      "13.0 - 17.0"   → (13.0, 17.0)
+      "13.0 – 17.0"   → (13.0, 17.0)   [en-dash]
+      "< 200"          → (None, 200.0)
+      "> 40"           → (40.0, None)
+      "150000-400000"  → (150000.0, 400000.0)
+      "0.4 - 4.0"      → (0.4, 4.0)
+    """
+    if not raw:
+        return None, None
+
+    t = raw.strip()
+
+    # "< X" or "<X"
+    m = re.match(r"^[<≤]\s*([\d,\.]+)$", t)
+    if m:
+        try:
+            return None, float(m.group(1).replace(",", ""))
+        except ValueError:
+            return None, None
+
+    # "> X" or ">X"
+    m = re.match(r"^[>≥]\s*([\d,\.]+)$", t)
+    if m:
+        try:
+            return float(m.group(1).replace(",", "")), None
+        except ValueError:
+            return None, None
+
+    # "X - Y" or "X – Y" or "X~Y" or "X to Y"
+    m = re.match(
+        r"^([\d,\.]+)\s*(?:[-–~]|[Tt][Oo])\s*([\d,\.]+)$",
+        t.replace(" ", ""),  # collapse spaces for match, restore values via groups
+    )
+    # Try with spaces preserved too
+    if not m:
+        m = re.match(
+            r"^([\d,\.]+)\s*[-–~]\s*([\d,\.]+)$",
+            t,
+        )
+    if m:
+        try:
+            low  = float(m.group(1).replace(",", ""))
+            high = float(m.group(2).replace(",", ""))
+            if low > high:
+                low, high = high, low  # swap if inverted
+            return low, high
+        except ValueError:
+            return None, None
+
+    return None, None
+
+
+def _should_skip_line(line: str) -> bool:
+    """Return True if this line is a header/footer that should not be parsed."""
+    line_lower = line.lower().strip()
+
+    if not line_lower or len(line_lower) < 5:
+        return True
+
+    for kw in _SKIP_KEYWORDS:
+        if kw in line_lower:
+            return True
+
+    if re.match(r"^[-=_\s]{3,}$", line_lower):
+        return True
+
+    return False
+
+
+def _is_noise_line(line: str) -> bool:
+    """Footer/textbook/contact noise — drop before regex parsing."""
+    stripped = line.strip()
+    if not stripped:
+        return True
+
+    line_lower = stripped.lower()
+    for sub in _NOISE_SUBSTRINGS:
+        if sub in line_lower:
+            return True
+
+    words = stripped.split()
+    if len(words) < 2:
+        return True
+
+    # Purely numeric line with no analyte name (≥3 letters)
+    if not re.search(r"[a-zA-Z]{3,}", stripped):
+        if re.match(r"^[\d\s\.\,\-\+\<\>\[\]\(\)\%\/]+$", stripped):
+            return True
+
+    return False
+
+
+def _is_noise_biomarker(name: str) -> bool:
+    """Reject parsed names that are clearly PDF footer/textbook garbage."""
+    n = name.lower().strip()
+    if len(n) < 2:
+        return True
+    for sub in _NOISE_NAME_SUBSTRINGS:
+        if sub in n:
+            return True
+    # Long prose fragments are not analyte names
+    if len(name.split()) > 5:
+        return True
+    return False
+
+
+def filter_report_noise(text: str) -> str:
+    """Remove noise lines from extracted PDF text before biomarker parsing."""
+    if not text:
+        return ""
+    kept: list[str] = []
+    for line in text.split("\n"):
+        line = line.strip()
+        if not line:
+            continue
+        if _should_skip_line(line) or _is_noise_line(line):
+            continue
+        kept.append(line)
+    return "\n".join(kept)
+
+
+def _dedup_key(name: str, value_raw: str) -> str:
+    """Canonical dedup key — merges Serum Creatinine / Creatinine duplicates."""
+    from app.core.range_db import resolve_test_name
+    canonical = resolve_test_name(name).lower()
+    value_key = re.sub(r"\s+", "", value_raw.strip().lower())
+    return f"{canonical}|{value_key}"
+
+
+# ── Main parser ───────────────────────────────────────────────────────────────
+
+def parse_biomarkers(text: str) -> list[BiomarkerRaw]:
+    """
+    Parse extracted report text into BiomarkerRaw objects.
+
+    Strategy:
+    1. Split into lines (and handle TSV rows from table extraction)
+    2. Skip header/footer lines
+    3. Try all 4 patterns in priority order on each line
+    4. Validate: value must parse as float
+    5. De-duplicate by canonical test name (prefer match with range)
+    """
+    if not text:
+        return []
+
+    text = filter_report_noise(text)
+    lines = text.split("\n")
+    seen: dict[str, BiomarkerRaw] = {}
+
+    for line in lines:
+        line = line.strip()
+
+        if _should_skip_line(line) or _is_noise_line(line):
+            continue
+
+        for pattern_name, pattern in _ALL_PATTERNS:
+            m = pattern.search(line)
+            if not m:
+                continue
+
+            raw_name  = m.group(1)
+            raw_value = m.group(2)
+            raw_unit  = m.group(3) if m.lastindex and m.lastindex >= 3 else ""
+            raw_range = m.group(4) if m.lastindex and m.lastindex >= 4 else ""
+
+            name = clean_test_name(raw_name)
+            if not name or len(name) < 2 or _is_noise_biomarker(name):
+                continue
+
+            value_float = parse_value(raw_value)
+            if value_float is None:
+                continue
+
+            key      = _dedup_key(name, raw_value)
+            existing = seen.get(key)
+
+            candidate = BiomarkerRaw(
+                name=name,
+                value_raw=raw_value.strip(),
+                unit=raw_unit.strip(),
+                range_raw=raw_range.strip(),
+                line_text=line,
+                page_num=0,
+            )
+
+            if existing is None:
+                seen[key] = candidate
+            elif not existing.range_raw and candidate.range_raw:
+                seen[key] = candidate
+
+            break
+
+    return list(seen.values())
+
+
+# ── Post-processing: classify and build Biomarker models ─────────────────────
+
+def resolve_and_classify(
+    raw_list: list[BiomarkerRaw],
+    gender: str = "unknown",
+    db: Optional[dict] = None,
+) -> list[Biomarker]:
+    """
+    Convert BiomarkerRaw → Biomarker with status + category.
+    AI-generated fields (explanation, advice, etc.) are left empty here —
+    they are filled in Tier 3/4 by the AI router.
+
+    Steps per biomarker:
+    1. Resolve canonical name via ALIASES
+    2. Get reference range (lab range → ICMR fallback)
+    3. Parse value as float
+    4. Classify status (deterministic)
+    5. Build Biomarker model
+    """
+    from app.core.range_db import (
+        classify_status,
+        get_reference_range,
+        resolve_test_name,
+    )
+    from app.core.unit_validator import validate_unit
+
+    results: list[Biomarker] = []
+
+    for raw in raw_list:
+        value = parse_value(raw.value_raw)
+        if value is None:
+            continue
+
+        if _is_noise_biomarker(raw.name):
+            continue
+
+        canonical = resolve_test_name(raw.name)
+
+        unit, unit_error = validate_unit(canonical, raw.unit)
+
+        ref = get_reference_range(
+            test_name=canonical,
+            gender=gender,
+            lab_range_text=raw.range_raw or None,
+        )
+
+        # Parse range for Biomarker fields
+        low, high = parse_range(raw.range_raw) if raw.range_raw else (None, None)
+        if ref and low is None:
+            low  = ref.get("low")
+        if ref and high is None:
+            high = ref.get("high")
+
+        # Classify status
+        status = classify_status(value, ref, canonical) if ref else BiomarkerStatus.NORMAL
+
+        # Map category string → enum
+        cat_str = (ref or {}).get("category", "Other")
+        try:
+            category = BiomarkerCategory(cat_str)
+        except ValueError:
+            category = BiomarkerCategory.OTHER
+
+        # Source of range used
+        source = (ref or {}).get("source", "icmr")
+
+        # Build normalized range text
+        if raw.range_raw:
+            range_text = raw.range_raw
+        elif low is not None and high is not None:
+            range_text = f"{low} - {high}"
+        elif high is not None:
+            range_text = f"< {high}"
+        elif low is not None:
+            range_text = f"> {low}"
+        else:
+            range_text = ""
+
+        biomarker = Biomarker(
+            name=canonical,
+            value=value,
+            value_raw=raw.value_raw,
+            unit=unit,
+            normal_range_low=low,
+            normal_range_high=high,
+            normal_range_text=range_text,
+            status=status,
+            category=category,
+            source=source,
+            explanation="",
+            explanation_hindi="",
+            advice="",
+            indian_foods=[],
+            parsing_error=unit_error,
+        )
+        results.append(biomarker)
+
+    return results

app/core/pdf_extractor.py

@@ -0,0 +1,436 @@
+"""
+LabCard AI — PDF Extraction Pipeline
+=====================================
+ZERO LLM — pure deterministic text extraction.
+
+Strategy:
+  1. pdfplumber  → best for columnar/tabular Indian lab layouts (Thyrocare, Dr. Lal, SRL)
+  2. PyMuPDF     → fallback, faster, handles more complex layouts and encodings
+  3. Scanned PDF → detected and flagged (char_count < 200) for future OCR
+
+All CPU-bound PDF work runs in asyncio.to_thread() to avoid blocking FastAPI's event loop.
+"""
+from __future__ import annotations
+
+import asyncio
+import io
+import re
+import unicodedata
+from dataclasses import dataclass, field
+
+
+@dataclass
+class ExtractionResult:
+    """Output of the PDF extraction pipeline."""
+    text:              str
+    page_count:        int
+    method_used:       str        # "pdfplumber" | "pymupdf" | "direct_text"
+    char_count:        int
+    is_likely_scanned: bool       # True if char_count < 200 and page_count > 0
+    warnings:          list[str]  = field(default_factory=list)
+
+
+# ── Internal sync workers (run inside asyncio.to_thread) ─────────────────────
+
+def _group_words_into_lines(words: list[dict], y_tolerance: float = 4.0) -> list[str]:
+    """
+    Group pdfplumber word dicts into reading-order lines by Y-coordinate.
+    Fixes multi-column PDFs where extract_text() interleaves columns.
+    """
+    if not words:
+        return []
+
+    sorted_words = sorted(
+        words,
+        key=lambda w: (round(float(w.get("top", 0)) / y_tolerance), float(w.get("x0", 0))),
+    )
+
+    lines_of_words: list[list[dict]] = []
+    current_key: int | None = None
+    current: list[dict] = []
+
+    for w in sorted_words:
+        row_key = round(float(w.get("top", 0)) / y_tolerance)
+        if current_key is None:
+            current_key = row_key
+            current = [w]
+        elif row_key == current_key:
+            current.append(w)
+        else:
+            if current:
+                lines_of_words.append(current)
+            current = [w]
+            current_key = row_key
+
+    if current:
+        lines_of_words.append(current)
+
+    result: list[str] = []
+    for line_words in lines_of_words:
+        line_words.sort(key=lambda w: float(w.get("x0", 0)))
+        text = " ".join(
+            str(w.get("text", "")).strip()
+            for w in line_words
+            if w.get("text")
+        )
+        if text.strip():
+            result.append(text)
+    return result
+
+
+def _pdfplumber_worker(pdf_bytes: bytes) -> str:
+    """
+    Sync worker for pdfplumber extraction.
+    Uses extract_words() + Y-coordinate row grouping (not extract_text layout mode).
+    Also extracts tabular data as TSV when tables are detected.
+    """
+    import pdfplumber  # type: ignore[import-untyped]
+
+    parts: list[str] = []
+
+    with pdfplumber.open(io.BytesIO(pdf_bytes)) as pdf:
+        for page in pdf.pages:
+            words = page.extract_words(
+                x_tolerance=2,
+                y_tolerance=3,
+                keep_blank_chars=False,
+                use_text_flow=False,
+            )
+            for line in _group_words_into_lines(words):
+                parts.append(line)
+
+            tables = page.extract_tables()
+            for table in tables:
+                for row in table:
+                    if row:
+                        row_str = "\t".join(
+                            (cell.strip() if cell else "") for cell in row
+                        )
+                        if row_str.strip():
+                            parts.append(row_str)
+
+    return "\n\n".join(parts)
+
+
+def _pymupdf_worker(pdf_bytes: bytes) -> str:
+    """
+    Sync worker for PyMuPDF extraction.
+    sort=True ensures reading order is preserved left-to-right, top-to-bottom.
+    """
+    import fitz  # type: ignore[import-untyped]   # PyMuPDF
+
+    parts: list[str] = []
+    page_count = 0
+
+    with fitz.open(stream=pdf_bytes, filetype="pdf") as doc:
+        page_count = doc.page_count
+        for page in doc:
+            text = page.get_text("text", sort=True)
+            if text.strip():
+                parts.append(text)
+
+    return "\n\n".join(parts)
+
+
+def _pymupdf_page_count(pdf_bytes: bytes) -> int:
+    """Get page count via PyMuPDF (used as fallback metadata)."""
+    import fitz  # type: ignore[import-untyped]
+    with fitz.open(stream=pdf_bytes, filetype="pdf") as doc:
+        return doc.page_count
+
+
+# ── Async extraction functions ────────────────────────────────────────────────
+
+async def _extract_pdfplumber(pdf_bytes: bytes) -> str:
+    """
+    Async wrapper — runs pdfplumber in thread pool to avoid blocking event loop.
+    Best for: Thyrocare, Dr. Lal PathLabs, SRL, Metropolis (columnar layouts).
+    """
+    try:
+        text = await asyncio.to_thread(_pdfplumber_worker, pdf_bytes)
+        return text
+    except Exception as exc:  # noqa: BLE001
+        raise RuntimeError(f"pdfplumber extraction failed: {exc}") from exc
+
+
+async def _extract_pymupdf(pdf_bytes: bytes) -> str:
+    """
+    Async wrapper — PyMuPDF fallback.
+    Handles: complex layouts, embedded fonts, some encrypted PDFs.
+    """
+    try:
+        text = await asyncio.to_thread(_pymupdf_worker, pdf_bytes)
+        return text
+    except Exception as exc:  # noqa: BLE001
+        raise RuntimeError(f"PyMuPDF extraction failed: {exc}") from exc
+
+
+# ── Text normalizer ───────────────────────────────────────────────────────────
+
+def _normalize_text(raw: str) -> str:
+    """
+    Normalize extracted text for the regex biomarker parser.
+
+    Operations (in order):
+    1. Strip BOM
+    2. Unicode normalize → NFC (handles composed characters)
+    3. Normalize Unicode dashes → ASCII hyphen
+    4. Replace tabs with spaces
+    5. Collapse 3+ consecutive newlines → 2
+    6. Strip trailing whitespace from each line
+    7. Strip leading/trailing blank lines
+    8. Fix common OCR misreads in numeric contexts only
+    """
+    if not raw:
+        return ""
+
+    # 1. Strip BOM
+    text = raw.lstrip("\ufeff\ufffe")
+
+    # 2. Unicode NFC normalization
+    text = unicodedata.normalize("NFC", text)
+
+    # 3. Normalize all dash/hyphen variants to ASCII hyphen
+    # en-dash, em-dash, minus sign, figure dash, etc.
+    text = re.sub(r"[–—−‐‑‒―]", "-", text)
+
+    # 4. Tabs → spaces (but not newlines)
+    text = text.replace("\t", "  ")
+
+    # 5. Collapse 3+ newlines → 2
+    text = re.sub(r"\n{3,}", "\n\n", text)
+
+    # 6. Strip trailing whitespace from each line
+    lines = [line.rstrip() for line in text.split("\n")]
+    text = "\n".join(lines)
+
+    # 7. Strip leading/trailing blank
+    text = text.strip()
+
+    # 8. Fix common OCR misreads — ONLY in positions where a digit is expected
+    # Pattern: number-like contexts where "l" → "1" or "O" → "0"
+    # Example: "l0.2" → "10.2",  "O.4" → "0.4"
+    # Only fix when surrounded by digits or decimal points
+    # OCR fix: 'l' between digit and digit/dot → '1'
+    text = re.sub(r"(?<=[0-9])l(?=[0-9.])", "1", text)
+    # OCR fix: 'O' at word boundary before decimal → '0' (e.g. O.4 → 0.4)
+    text = re.sub(r"\bO(?=\.[0-9])", "0", text)
+
+    return text
+
+
+# ── Main entry point ──────────────────────────────────────────────────────────
+
+async def extract_text_from_pdf(pdf_bytes: bytes) -> ExtractionResult:
+    """
+    Main extraction pipeline.
+
+    1. Try pdfplumber (layout-aware, best for Indian lab tables)
+    2. Fall back to PyMuPDF if result is < 100 chars
+    3. Normalize text in both paths
+    4. Flag scanned PDFs
+    """
+    warnings: list[str] = []
+    page_count = 0
+
+    # ── Path 1: pdfplumber ───────────────────────────────────────────────────
+    plumber_text = ""
+    try:
+        plumber_text = await _extract_pdfplumber(pdf_bytes)
+    except RuntimeError as exc:
+        warnings.append(f"pdfplumber error: {exc}")
+
+    if len(plumber_text.strip()) >= 100:
+        normalized = _normalize_text(plumber_text)
+        # Get page count via PyMuPDF (lightweight)
+        try:
+            page_count = await asyncio.to_thread(_pymupdf_page_count, pdf_bytes)
+        except Exception:  # noqa: BLE001
+            page_count = 1
+
+        char_count = len(normalized)
+        return ExtractionResult(
+            text=normalized,
+            page_count=page_count,
+            method_used="pdfplumber",
+            char_count=char_count,
+            is_likely_scanned=(char_count < 200 and page_count > 0),
+            warnings=warnings,
+        )
+
+    # ── Path 2: PyMuPDF fallback ─────────────────────────────────────────────
+    if len(plumber_text.strip()) < 100:
+        warnings.append(
+            f"pdfplumber returned {len(plumber_text.strip())} chars — "
+            "falling back to PyMuPDF"
+        )
+
+    pymupdf_text = ""
+    try:
+        pymupdf_text = await _extract_pymupdf(pdf_bytes)
+        page_count_raw = await asyncio.to_thread(_pymupdf_page_count, pdf_bytes)
+        page_count = page_count_raw
+    except RuntimeError as exc:
+        warnings.append(f"PyMuPDF error: {exc}")
+        page_count = 0
+
+    # Use whichever gave more content
+    best_raw = (
+        plumber_text if len(plumber_text) > len(pymupdf_text) else pymupdf_text
+    )
+    normalized = _normalize_text(best_raw)
+    char_count = len(normalized)
+
+    if char_count < 200 and page_count > 0:
+        warnings.append(
+            "Very little text extracted — PDF may be image-based (scanned). "
+            "OCR support coming in a future version. "
+            "Please try copy-pasting the report text instead."
+        )
+
+    return ExtractionResult(
+        text=normalized,
+        page_count=page_count,
+        method_used="pymupdf",
+        char_count=char_count,
+        is_likely_scanned=(char_count < 200 and page_count > 0),
+        warnings=warnings,
+    )
+
+
+# ── Patient metadata extractor ────────────────────────────────────────────────
+
+# Lab name patterns — checked against first 500 chars of report
+_LAB_PATTERNS: list[tuple[str, str]] = [
+    (r"THYROCARE",                           "Thyrocare Technologies"),
+    (r"DR\.?\s*LAL\s*PATH",                  "Dr. Lal PathLabs"),
+    (r"APOLLO\s*DIAG",                       "Apollo Diagnostics"),
+    (r"\bSRL\b",                             "SRL Diagnostics"),
+    (r"METROPOLIS",                           "Metropolis Healthcare"),
+    (r"AGILUS",                              "Agilus Diagnostics"),
+    (r"VIJAYA\s*DIAG",                       "Vijaya Diagnostics"),
+    (r"SUBURBAN\s*DIAG",                     "Suburban Diagnostics"),
+    (r"MEDANTA",                             "Medanta Diagnostics"),
+    (r"FORTIS\s*DIAG",                       "Fortis Diagnostics"),
+    (r"MAX\s*LAB",                           "Max Lab"),
+    (r"MANIPAL\s*PATH",                      "Manipal Pathology"),
+    (r"NATIONAL\s*REFERENCE\s*LAB",          "National Reference Laboratory"),
+    (r"CORE\s*DIAG",                         "Core Diagnostics"),
+    (r"HEALTHIANS",                          "Healthians"),
+]
+
+
+def extract_patient_metadata(text: str) -> dict[str, str]:
+    """
+    Extract patient metadata from report text using ordered regex.
+
+    Returns:
+        patient_name, patient_age, patient_gender, report_date, lab_name
+    All values are strings (empty string if not found).
+    """
+    result: dict[str, str] = {
+        "patient_name":   "",
+        "patient_age":    "",
+        "patient_gender": "",
+        "report_date":    "",
+        "lab_name":       "",
+    }
+
+    if not text:
+        return result
+
+    # Work on first 3000 chars — patient info is always at the top
+    header = text[:3000]
+
+    # ── Patient name ─────────────────────────────────────────────────────────
+    name_patterns = [
+        r"Patient\s+Name\s*[:\-]\s*(.+?)(?:\n|$)",
+        r"Patient\s*[:\-]\s*(.+?)(?:\n|$)",
+        r"Name\s*[:\-]\s*(.+?)(?:\n|$)",
+        r"Mr\.?\s+([A-Z][a-z]+(?:\s+[A-Z][a-z]+)+)",
+        r"Mrs\.?\s+([A-Z][a-z]+(?:\s+[A-Z][a-z]+)+)",
+        r"Ms\.?\s+([A-Z][a-z]+(?:\s+[A-Z][a-z]+)+)",
+    ]
+    for pattern in name_patterns:
+        m = re.search(pattern, header, re.IGNORECASE)
+        if m:
+            raw = m.group(1).strip()
+            # Clean up: remove lab codes, numbers appended
+            raw = re.sub(r"\s*\|.*$", "", raw)
+            raw = re.sub(r"\s{2,}.*$", "", raw)
+            raw = raw.strip()
+            if 2 < len(raw) < 60 and not re.search(r"\d{4}", raw):
+                result["patient_name"] = raw
+                break
+
+    # ── Age + Gender (often same line) ───────────────────────────────────────
+    age_gender_patterns = [
+        # "Age / Gender : 28 Years / Male"
+        r"Age\s*/\s*(?:Sex|Gender)\s*[:\-]\s*(\d+)\s*(?:Year|Yr)s?\s*/\s*(Male|Female|M|F)",
+        # "28 Years / Male" standalone
+        r"(\d{1,3})\s*(?:Year|Yr)s?\s*/\s*(Male|Female|M|F)",
+        # "Age : 28  Gender : Male" on separate parts
+        r"Age\s*[:\-]\s*(\d{1,3})\s*(?:Year|Yr)s?",
+    ]
+    for pattern in age_gender_patterns:
+        m = re.search(pattern, header, re.IGNORECASE)
+        if m:
+            result["patient_age"] = m.group(1).strip()
+            if m.lastindex and m.lastindex >= 2:
+                gender_raw = m.group(2).strip().upper()
+                result["patient_gender"] = (
+                    "Male" if gender_raw in ("M", "MALE") else "Female"
+                )
+            break
+
+    # ── Gender standalone (if not found above) ────────────────────────────────
+    if not result["patient_gender"]:
+        gender_patterns = [
+            r"(?:Sex|Gender)\s*[:\-]\s*(Male|Female|M|F)\b",
+            r"\b(Male|Female)\b",
+        ]
+        for pattern in gender_patterns:
+            m = re.search(pattern, header, re.IGNORECASE)
+            if m:
+                g = m.group(1).strip().upper()
+                result["patient_gender"] = "Male" if g in ("M", "MALE") else "Female"
+                break
+
+    # ── Report date ───────────────────────────────────────────────────────────
+    date_patterns = [
+        r"Report\s+Date\s*[:\-]\s*(\d{1,2}[\s\-/]\w{3,9}[\s\-/]\d{4})",
+        r"Date\s+of\s+Report\s*[:\-]\s*(\d{1,2}[\s\-/]\w{3,9}[\s\-/]\d{4})",
+        r"Sample\s+(?:Collected|Date)\s*[:\-]\s*(\d{1,2}[\s\-/]\w{3,9}[\s\-/]\d{4})",
+        r"Collection\s+Date\s*[:\-]\s*(\d{1,2}[\s\-/]\w{3,9}[\s\-/]\d{4})",
+        r"Date\s*[:\-]\s*(\d{1,2}[/\-]\d{1,2}[/\-]\d{2,4})",
+        r"Dated\s*[:\-]\s*(\d{1,2}[\s\-/]\w{3,9}[\s\-/]\d{4})",
+        # Catch "15 May 2025" style anywhere in header
+        r"(\d{1,2}\s+(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)\w*\s+\d{4})",
+    ]
+    for pattern in date_patterns:
+        m = re.search(pattern, header, re.IGNORECASE)
+        if m:
+            result["report_date"] = m.group(1).strip()
+            break
+
+    # ── Lab name ──────────────────────────────────────────────────────────────
+    header_upper = header[:500].upper()
+    for pattern, lab_name in _LAB_PATTERNS:
+        if re.search(pattern, header_upper):
+            result["lab_name"] = lab_name
+            break
+
+    # Fallback: first all-caps line in first 10 lines
+    if not result["lab_name"]:
+        for line in header.split("\n")[:10]:
+            stripped = line.strip()
+            if (
+                stripped
+                and stripped.isupper()
+                and len(stripped) > 5
+                and not re.match(r"^[\d\W]+$", stripped)
+            ):
+                result["lab_name"] = stripped.title()
+                break
+
+    return result

app/core/range_db.py

@@ -0,0 +1,395 @@
+"""
+LabCard AI — Reference Range Database + Status Classifier
+=========================================================
+ZERO LLM — all logic is deterministic Python.
+
+Priority order for reference range resolution:
+  1. Lab's own printed range (extracted from report text)
+  2. ICMR/AIIMS hardcoded fallback
+
+Status classification is also 100% deterministic — no AI involved.
+If this function gets the status wrong, the report card is wrong.
+AI (Tier 3/4) only enriches explanations and advice — never the status.
+"""
+from __future__ import annotations
+
+import json
+import re
+from functools import lru_cache
+from pathlib import Path
+
+from app.models.biomarker import BiomarkerCategory, BiomarkerStatus
+
+# ── Alias table ────────────────────────────────────────────────────────────────
+# Maps every real-world Indian lab variant → canonical ICMR key.
+# Extend this table when new lab formats are encountered.
+ALIASES: dict[str, str] = {
+    # ── Hemoglobin ─────────────────────────────────────────────────────────
+    "Hb":                         "Hemoglobin",
+    "HGB":                        "Hemoglobin",
+    "Haemoglobin":                "Hemoglobin",
+    "Hgb":                        "Hemoglobin",
+    # ── CBC derived ────────────────────────────────────────────────────────
+    "RBC":                        "RBC Count",
+    "WBC":                        "WBC Count",
+    "TLC":                        "WBC Count",      # Total Leucocyte Count
+    "Total Leucocyte Count":      "WBC Count",
+    "Total WBC Count":            "WBC Count",
+    "Platelets":                  "Platelet Count",
+    "Platelet":                   "Platelet Count",
+    "PLT":                        "Platelet Count",
+    "Thrombocytes":               "Platelet Count",
+    "PCV":                        "Hematocrit",
+    "Packed Cell Volume":         "Hematocrit",
+    "HCT":                        "Hematocrit",
+    # ── Thyroid ────────────────────────────────────────────────────────────
+    "TSH (Ultrasensitive)":       "TSH",
+    "TSH 3rd Gen":                "TSH",
+    "TSH Ultrasensitive":         "TSH",
+    "T3 (Triiodothyronine)":      "T3",
+    "T4 (Thyroxine)":             "T4",
+    "Triiodothyronine":           "T3",
+    "Thyroxine":                  "T4",
+    "FT3":                        "Free T3",
+    "FT4":                        "Free T4",
+    "Free Triiodothyronine":      "Free T3",
+    "Free Thyroxine":             "Free T4",
+    # ── Vitamins ───────────────────────────────────────────────────────────
+    "Vitamin D (25-OH)":          "Vitamin D",
+    "25-OH Vitamin D":            "Vitamin D",
+    "Vit D3":                     "Vitamin D",
+    "Vit D":                      "Vitamin D",
+    "25 Hydroxy Vitamin D":       "Vitamin D",
+    "25(OH)D":                    "Vitamin D",
+    "Cholecalciferol":            "Vitamin D",
+    "Vit B12":                    "Vitamin B12",
+    "B12":                        "Vitamin B12",
+    "Cyanocobalamin":             "Vitamin B12",
+    "Cobalamin":                  "Vitamin B12",
+    "Folate":                     "Folic Acid",
+    "Serum Folate":               "Folic Acid",
+    "Folic Acid Serum":           "Folic Acid",
+    # ── Sugar / Diabetes ───────────────────────────────────────────────────
+    "Fasting Glucose":            "Fasting Blood Glucose",
+    "FBS":                        "Fasting Blood Glucose",
+    "Blood Sugar Fasting":        "Fasting Blood Glucose",
+    "BSF":                        "Fasting Blood Glucose",
+    "Glucose Fasting":            "Fasting Blood Glucose",
+    "Fasting Blood Sugar":        "Fasting Blood Glucose",
+    "Glycated Hemoglobin":        "HbA1c",
+    "Glycosylated Hemoglobin":    "HbA1c",
+    "Hemoglobin A1c":             "HbA1c",
+    "PPBS":                       "Post Prandial Glucose",
+    "Post Prandial Blood Sugar":  "Post Prandial Glucose",
+    "RBS":                        "Random Blood Glucose",
+    "Random Blood Sugar":         "Random Blood Glucose",
+    # ── Liver ──────────────────────────────────────────────────────────────
+    "ALT":                        "SGPT",
+    "SGPT (ALT)":                 "SGPT",
+    "Alanine Aminotransferase":   "SGPT",
+    "ALT (SGPT)":                 "SGPT",
+    "AST":                        "SGOT",
+    "SGOT (AST)":                 "SGOT",
+    "Aspartate Aminotransferase": "SGOT",
+    "AST (SGOT)":                 "SGOT",
+    "ALP":                        "Alkaline Phosphatase",
+    "Bilirubin Total":            "Total Bilirubin",
+    "Bilirubin (Total)":          "Total Bilirubin",
+    "S. Bilirubin Total":         "Total Bilirubin",
+    "Bilirubin Direct":           "Direct Bilirubin",
+    "Bilirubin Indirect":         "Indirect Bilirubin",
+    "GGT":                        "GGT",
+    "Gamma GT":                   "GGT",
+    "Gamma Glutamyl Transferase": "GGT",
+    # ── Kidney ─────────────────────────────────────────────────────────────
+    "Creatinine":                 "Serum Creatinine",
+    "S. Creatinine":              "Serum Creatinine",
+    "Serum Creatinine (S. Cr)":  "Serum Creatinine",
+    "Blood Urea Nitrogen":        "BUN",
+    "Urea":                       "BUN",
+    "Blood Urea":                 "BUN",
+    "S. Urea":                    "BUN",
+    "Uric Acid Serum":            "Uric Acid",
+    "S. Uric Acid":               "Uric Acid",
+    # ── Lipids ─────────────────────────────────────────────────────────────
+    "Cholesterol":                "Total Cholesterol",
+    "Total Cholesterol (TC)":     "Total Cholesterol",
+    "HDL":                        "HDL Cholesterol",
+    "HDL-C":                      "HDL Cholesterol",
+    "LDL":                        "LDL Cholesterol",
+    "LDL-C":                      "LDL Cholesterol",
+    "TGL":                        "Triglycerides",
+    "TG":                         "Triglycerides",
+    "Trig":                       "Triglycerides",
+    "VLDL Cholesterol":           "VLDL",
+    # ── Iron studies ───────────────────────────────────────────────────────
+    "S. Iron":                    "Serum Iron",
+    "Iron":                       "Serum Iron",
+    "Iron Serum":                 "Serum Iron",
+    "Ferritin":                   "Serum Ferritin",
+    "S. Ferritin":                "Serum Ferritin",
+    "Serum Ferritin (SF)":        "Serum Ferritin",
+    "Iron Binding Capacity":      "TIBC",
+    "Total Iron Binding Capacity":"TIBC",
+    # ── Inflammation ───────────────────────────────────────────────────────
+    "C-Reactive Protein":         "CRP",
+    "hs CRP":                     "hs-CRP",
+    "High Sensitivity CRP":       "hs-CRP",
+    "High Sensitivity C-Reactive Protein": "hs-CRP",
+    # ── Electrolytes ───────────────────────────────────────────────────────
+    "Na":                         "Sodium",
+    "K":                          "Potassium",
+    "Cl":                         "Chloride",
+    "Mg":                         "Magnesium",
+    "Serum Calcium":              "Calcium",
+    "S. Calcium":                 "Calcium",
+    "Serum Sodium":               "Sodium",
+    "Serum Potassium":            "Potassium",
+}
+
+# ── Critical thresholds (override everything — life-threatening values) ────────
+# These are hard safety limits — patient must seek immediate care.
+_CRITICAL_OVERRIDES: dict[str, list[tuple[str, float]]] = {
+    "Hemoglobin":           [("lt", 7.0)],
+    "WBC Count":            [("gt", 30000), ("lt", 1500)],
+    "Platelet Count":       [("lt", 20000)],
+    "Fasting Blood Glucose":[("gt", 400)],
+    "Random Blood Glucose": [("gt", 400)],
+    "HbA1c":                [("gt", 10.0)],
+    "TSH":                  [("gt", 10.0), ("lt", 0.1)],
+    "Serum Creatinine":     [("gt", 8.0)],
+    "Potassium":            [("gt", 6.5), ("lt", 2.5)],
+    "Sodium":               [("gt", 155), ("lt", 120)],
+}
+
+# ── Deficient thresholds (vitamins + iron — below these need DEFICIENT status) ─
+_DEFICIENT_OVERRIDES: dict[str, float] = {
+    "Vitamin D":     20.0,   # ng/mL  — ICMR deficiency cutoff
+    "Vitamin B12":  140.0,   # pg/mL  — ICMR deficiency cutoff
+    "Serum Ferritin": 12.0,  # ng/mL  — WHO deficiency cutoff
+}
+
+# ── Elevated categories (use ELEVATED instead of HIGH for these markers) ───────
+_ELEVATED_CATEGORIES: set[str] = {"Liver", "Lipid", "Other"}
+
+# ── Deficient categories (use DEFICIENT instead of LOW for these markers) ──────
+_DEFICIENT_CATEGORIES: set[str] = {"Vitamin", "Blood"}
+
+
+# ── DB loader ─────────────────────────────────────────────────────────────────
+
+@lru_cache(maxsize=1)
+def load_icmr_db() -> dict[str, dict]:
+    """Load and cache ICMR ranges JSON. Called once on first use."""
+    db_path = Path(__file__).parent.parent.parent / "data" / "icmr_ranges.json"
+    with open(db_path, encoding="utf-8") as f:
+        return json.load(f)
+
+
+# ── Name resolution ──────────────────────────────────────────────────────────
+
+def resolve_test_name(raw_name: str) -> str:
+    """
+    Map raw lab report test name → canonical ICMR key.
+    Strategy:
+      1. Exact match in ALIASES
+      2. Case-insensitive match in ALIASES
+      3. Return raw_name unchanged (may still match ICMR DB directly)
+    """
+    name = raw_name.strip()
+
+    # 1. Exact match
+    if name in ALIASES:
+        return ALIASES[name]
+
+    # 2. Case-insensitive scan
+    name_lower = name.lower()
+    for alias, canonical in ALIASES.items():
+        if alias.lower() == name_lower:
+            return canonical
+
+    # 3. Partial match — for names like "Vitamin D Total" → "Vitamin D"
+    for alias, canonical in ALIASES.items():
+        if alias.lower() in name_lower or name_lower in alias.lower():
+            return canonical
+
+    return name   # unchanged — will be looked up directly in ICMR DB
+
+
+# ── Lab range text parser ────────────────────────────────────────────────────
+
+def _parse_lab_range(range_text: str) -> tuple[float | None, float | None]:
+    """
+    Parse printed range text from lab report into (low, high).
+
+    Handles all real-world Indian lab formats:
+      "13.0 - 17.0"     → (13.0, 17.0)
+      "13.0–17.0"        → (13.0, 17.0)   [en-dash]
+      "13.0 to 17.0"    → (13.0, 17.0)
+      "< 200"            → (None, 200.0)
+      "<200"             → (None, 200.0)
+      "> 40"             → (40.0, None)
+      "Up to 150"        → (None, 150.0)
+      "Upto 150"         → (None, 150.0)
+      "0.4 - 4.0"        → (0.4, 4.0)
+    """
+    if not range_text:
+        return None, None
+
+    t = range_text.strip()
+
+    # "< X" or "<X"
+    m = re.match(r'^[<≤]\s*([\d.]+)', t)
+    if m:
+        return None, float(m.group(1))
+
+    # "> X" or ">=X"
+    m = re.match(r'^[>≥]\s*([\d.]+)', t)
+    if m:
+        return float(m.group(1)), None
+
+    # "Up to X" / "Upto X"
+    m = re.match(r'^[Uu]p\s*[Tt]o\s*([\d.]+)', t)
+    if m:
+        return None, float(m.group(1))
+
+    # "X - Y" / "X–Y" / "X to Y" / "X ~ Y"
+    m = re.match(r'^([\d.]+)\s*[-–~]|[Tt][Oo]\s*([\d.]+)$', t)
+    m = re.match(
+        r'^([\d.]+)\s*(?:[-–~]|[Tt][Oo])\s*([\d.]+)$',
+        t.replace(',', '')
+    )
+    if m:
+        return float(m.group(1)), float(m.group(2))
+
+    return None, None
+
+
+# ── Main range resolver ──────────────────────────────────────────────────────
+
+def get_reference_range(
+    test_name:      str,
+    gender:         str = "unknown",
+    lab_range_text: str | None = None,
+) -> dict | None:
+    """
+    Resolve reference range for a biomarker.
+
+    Priority:
+      1. Parse lab's own printed range (most clinically relevant)
+      2. ICMR/AIIMS database lookup
+
+    Returns dict with keys: low, high, category, source
+    Returns None if no range found.
+    """
+    canonical   = resolve_test_name(test_name)
+    gender_key  = gender.lower() if gender.lower() in ("male", "female") else "any"
+    category    = "Other"
+
+    # ── Priority 1: Lab printed range ───────────────────────────────────────
+    if lab_range_text:
+        low, high = _parse_lab_range(lab_range_text)
+        if low is not None or high is not None:
+            # Try to get category from ICMR DB even if we use lab range
+            db   = load_icmr_db()
+            data = db.get(canonical, {})
+            cat_entry = data.get("any") or data.get(gender_key)
+            if cat_entry:
+                category = cat_entry.get("category", "Other")
+            return {
+                "low":      low,
+                "high":     high,
+                "category": category,
+                "source":   "lab",
+            }
+
+    # ── Priority 2: ICMR DB ─────────────────────────────────────────────────
+    db   = load_icmr_db()
+    data = db.get(canonical, {})
+
+    if not data:
+        return None   # Unknown biomarker — can't classify
+
+    # Gender-specific → any fallback
+    entry = data.get(gender_key) or data.get("any")
+    if not entry:
+        return None
+
+    return {
+        "low":      entry.get("low"),
+        "high":     entry.get("high"),
+        "category": entry.get("category", "Other"),
+        "source":   "icmr",
+    }
+
+
+# ── Status classifier ────────────────────────────────────────────────────────
+
+def classify_status(
+    value:     float,
+    ref:       dict | None,
+    test_name: str,
+) -> BiomarkerStatus:
+    """
+    Classify a biomarker value into a status.
+    100% deterministic — zero LLM.
+
+    Order of precedence:
+      1. Critical overrides (life-threatening)
+      2. Deficient overrides (vitamin/iron specific)
+      3. Standard range comparison
+    """
+    if ref is None:
+        return BiomarkerStatus.NORMAL   # Can't classify without range
+
+    canonical = resolve_test_name(test_name)
+    low       = ref.get("low")
+    high      = ref.get("high")
+    category  = ref.get("category", "Other")
+
+    # ── 1. Critical overrides ────────────────────────────────────────────────
+    overrides = _CRITICAL_OVERRIDES.get(canonical, [])
+    for op, threshold in overrides:
+        if op == "lt" and value < threshold:
+            return BiomarkerStatus.CRITICAL
+        if op == "gt" and value > threshold:
+            return BiomarkerStatus.CRITICAL
+
+    # ── 2. Deficient overrides (vitamins + ferritin) ─────────────────────────
+    deficient_cutoff = _DEFICIENT_OVERRIDES.get(canonical)
+    if deficient_cutoff is not None and value < deficient_cutoff:
+        return BiomarkerStatus.DEFICIENT
+
+    # ── 3. Standard range logic ──────────────────────────────────────────────
+    below_low  = (low  is not None and value < low)
+    above_high = (high is not None and value > high)
+
+    if below_low:
+        # Vitamins and iron markers → DEFICIENT instead of LOW
+        if category in _DEFICIENT_CATEGORIES and canonical not in {
+            "Hemoglobin", "RBC Count", "WBC Count", "Platelet Count",
+            "Hematocrit", "Neutrophils", "Lymphocytes",
+        }:
+            return BiomarkerStatus.DEFICIENT
+        return BiomarkerStatus.LOW
+
+    if above_high:
+        # Liver + lipid markers → ELEVATED instead of HIGH
+        if category in _ELEVATED_CATEGORIES:
+            return BiomarkerStatus.ELEVATED
+        return BiomarkerStatus.HIGH
+
+    return BiomarkerStatus.NORMAL
+
+
+def get_category(test_name: str, gender: str = "any") -> BiomarkerCategory:
+    """
+    Convenience: get BiomarkerCategory for a test name.
+    Used by pdf_extractor when assembling BiomarkerRaw list.
+    """
+    ref = get_reference_range(test_name, gender)
+    cat_str = (ref or {}).get("category", "Other")
+    try:
+        return BiomarkerCategory(cat_str)
+    except ValueError:
+        return BiomarkerCategory.OTHER

app/core/scorer.py

@@ -0,0 +1,399 @@
+"""
+LabCard AI — Health Scorer (Deterministic)
+==========================================
+ZERO LLM. 100% math.
+
+Computes health score, health grade, preliminary biological age,
+top priority finding, and critical alert from classified biomarkers.
+
+Claude (Tier 4 premium) can refine the biological age with deeper reasoning,
+but the baseline here is already scientifically grounded.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+from app.models.biomarker import Biomarker, BiomarkerCategory, BiomarkerStatus
+
+# ── Status deduction table ────────────────────────────────────────────────────
+
+STATUS_DEDUCTIONS: dict[BiomarkerStatus, float] = {
+    BiomarkerStatus.NORMAL:    0.0,
+    BiomarkerStatus.LOW:       5.0,
+    BiomarkerStatus.HIGH:      5.0,
+    BiomarkerStatus.DEFICIENT: 10.0,
+    BiomarkerStatus.ELEVATED:  10.0,
+    BiomarkerStatus.CRITICAL:  25.0,
+}
+
+# ── Category weight multipliers ────────────────────────────────────────────────
+# Reflects Indian disease burden: diabetes + anemia + kidney disease are primary risks
+
+CATEGORY_WEIGHT: dict[str, float] = {
+    "Blood":   1.2,   # Anemia is endemic in India
+    "Sugar":   1.3,   # Diabetes epidemic
+    "Lipid":   1.1,   # Rising cardiovascular risk
+    "Liver":   1.1,   # NAFLD increasing
+    "Kidney":  1.2,   # CKD underdiagnosed
+    "Thyroid": 1.0,
+    "Vitamin": 0.8,   # Deficiencies very common — slightly lower weight
+    "Other":   0.9,
+}
+
+# ── Priority order for "top finding" selection ────────────────────────────────
+
+_STATUS_PRIORITY: dict[BiomarkerStatus, int] = {
+    BiomarkerStatus.CRITICAL:  5,
+    BiomarkerStatus.DEFICIENT: 4,
+    BiomarkerStatus.ELEVATED:  3,
+    BiomarkerStatus.LOW:       2,
+    BiomarkerStatus.HIGH:      2,
+    BiomarkerStatus.NORMAL:    0,
+}
+
+
+# ── Output dataclass ──────────────────────────────────────────────────────────
+
+@dataclass
+class HealthMetrics:
+    health_score:        int
+    health_grade:        str
+    biological_age:      int
+    chronological_age:   int
+    bio_age_delta:       int          # years added/subtracted
+    bio_age_factors:     list[str]    = field(default_factory=list)  # reasons
+    top_priority:        str          = ""
+    has_critical_alert:  bool         = False
+    critical_alert_text: str          = ""
+
+
+# ── Helper: parse age string ──────────────────────────────────────────────────
+
+def _parse_age(age_str: str) -> int:
+    """
+    Parse patient age from various formats:
+      "28 Years" → 28
+      "28"       → 28
+      "28Y"      → 28
+      ""         → 0
+    """
+    if not age_str:
+        return 0
+    m = re.search(r"(\d{1,3})", age_str)
+    if m:
+        age = int(m.group(1))
+        return age if 1 <= age <= 120 else 0
+    return 0
+
+
+# ── Helper: fast biomarker lookup ─────────────────────────────────────────────
+
+def _find(biomarkers: list[Biomarker], *name_fragments: str) -> Biomarker | None:
+    """Find first biomarker whose name contains ANY of the given fragments (case-insensitive)."""
+    for bm in biomarkers:
+        name_lower = bm.name.lower()
+        if any(frag.lower() in name_lower for frag in name_fragments):
+            return bm
+    return None
+
+
+def _find_all(biomarkers: list[Biomarker], *name_fragments: str) -> list[Biomarker]:
+    """Find all biomarkers whose name contains ANY of the given fragments."""
+    results = []
+    for bm in biomarkers:
+        name_lower = bm.name.lower()
+        if any(frag.lower() in name_lower for frag in name_fragments):
+            results.append(bm)
+    return results
+
+
+# ── Score calculation ─────────────────────────────────────────────────────────
+
+def _compute_score(biomarkers: list[Biomarker]) -> int:
+    """
+    Compute 0–100 health score with category weighting.
+    Each abnormal biomarker deducts points weighted by its category's importance.
+    """
+    total_deduction = 0.0
+
+    for bm in biomarkers:
+        deduction = STATUS_DEDUCTIONS.get(bm.status, 0.0)
+        if deduction == 0.0:
+            continue
+        weight = CATEGORY_WEIGHT.get(bm.category.value, 1.0)
+        total_deduction += deduction * weight
+
+    raw = 100.0 - total_deduction
+    return max(0, min(100, round(raw)))
+
+
+def _score_to_grade(score: int) -> str:
+    """Map numeric score → grade string."""
+    if score >= 85:
+        return "Excellent"
+    if score >= 70:
+        return "Good"
+    if score >= 55:
+        return "Fair"
+    if score >= 40:
+        return "Poor"
+    return "Critical"
+
+
+# ── Biological age estimation ─────────────────────────────────────────────────
+
+def _estimate_bio_age(
+    biomarkers:  list[Biomarker],
+    chrono_age:  int,
+) -> tuple[int, int, list[str]]:
+    """
+    Estimate biological age using additive delta rules.
+    Returns: (biological_age, delta, factors_list)
+
+    Claude (Tier 4) can refine this further with deeper pattern analysis.
+    This baseline is scientifically grounded in:
+    - Levine phenotypic age algorithm (simplified)
+    - ICMR population health data for India
+    """
+    delta    = 0
+    factors: list[str] = []
+
+    # ── Negative factors (add years) ─────────────────────────────────────────
+
+    # 1. Anemia combo: Hemoglobin low/deficient + Ferritin low
+    hb      = _find(biomarkers, "hemoglobin", "haemoglobin")
+    ferritin = _find(biomarkers, "ferritin")
+    if hb and hb.status in (BiomarkerStatus.LOW, BiomarkerStatus.DEFICIENT, BiomarkerStatus.CRITICAL):
+        if ferritin and ferritin.status in (BiomarkerStatus.LOW, BiomarkerStatus.DEFICIENT):
+            delta += 3
+            factors.append("Iron-deficiency anemia (Hemoglobin + Ferritin low) +3 yrs")
+        else:
+            delta += 2
+            factors.append("Low Hemoglobin +2 yrs")
+
+    # 2. Vitamin D deficiency
+    vit_d = _find(biomarkers, "vitamin d", "vit d")
+    if vit_d and vit_d.value < 20:
+        delta += 2
+        factors.append("Severe Vitamin D deficiency (<20 ng/mL) +2 yrs")
+    elif vit_d and vit_d.value < 30:
+        delta += 1
+        factors.append("Vitamin D insufficiency (<30 ng/mL) +1 yr")
+
+    # 3. Vitamin B12 deficiency
+    b12 = _find(biomarkers, "b12", "vitamin b12", "cobalamin")
+    if b12 and b12.value < 200:
+        delta += 2
+        factors.append("Vitamin B12 deficiency (<200 pg/mL) +2 yrs")
+    elif b12 and b12.value < 300:
+        delta += 1
+        factors.append("Low Vitamin B12 (<300 pg/mL) +1 yr")
+
+    # 4. Glycaemic control
+    hba1c = _find(biomarkers, "hba1c", "hemoglobin a1c", "glycated", "glycosylated")
+    if hba1c:
+        if hba1c.value > 6.4:
+            delta += 6
+            factors.append(f"Diabetic HbA1c ({hba1c.value}%) +6 yrs")
+        elif hba1c.value >= 5.7:
+            delta += 3
+            factors.append(f"Pre-diabetic HbA1c ({hba1c.value}%) +3 yrs")
+
+    # 5. Lipid double hit: LDL > 130 AND TG > 150
+    ldl = _find(biomarkers, "ldl")
+    tg  = _find(biomarkers, "triglyceride", "tgl", "tg")
+    if (
+        ldl and ldl.value > 130
+        and tg  and tg.value  > 150
+    ):
+        delta += 3
+        factors.append(f"High LDL ({ldl.value}) + High Triglycerides ({tg.value}) +3 yrs")
+    elif ldl and ldl.status in (BiomarkerStatus.HIGH, BiomarkerStatus.ELEVATED):
+        delta += 1
+        factors.append(f"Elevated LDL ({ldl.value} mg/dL) +1 yr")
+
+    # 6. Critical markers — +5 per CRITICAL
+    critical_bm = [b for b in biomarkers if b.status == BiomarkerStatus.CRITICAL]
+    if critical_bm:
+        add = len(critical_bm) * 5
+        delta += add
+        names = ", ".join(b.name for b in critical_bm)
+        factors.append(f"Critical values ({names}) +{add} yrs")
+
+    # 7. Liver stress: BOTH SGPT and SGOT elevated
+    sgpt = _find(biomarkers, "sgpt", "alt")
+    sgot = _find(biomarkers, "sgot", "ast")
+    if (
+        sgpt and sgpt.status in (BiomarkerStatus.HIGH, BiomarkerStatus.ELEVATED, BiomarkerStatus.CRITICAL)
+        and sgot and sgot.status in (BiomarkerStatus.HIGH, BiomarkerStatus.ELEVATED, BiomarkerStatus.CRITICAL)
+    ):
+        delta += 3
+        factors.append(f"Both liver enzymes elevated (SGPT {sgpt.value}, SGOT {sgot.value}) +3 yrs")
+
+    # 8. Kidney impairment: Creatinine elevated
+    creat = _find(biomarkers, "creatinine")
+    if creat and creat.status in (BiomarkerStatus.HIGH, BiomarkerStatus.ELEVATED, BiomarkerStatus.CRITICAL):
+        delta += 2
+        factors.append(f"Elevated Creatinine ({creat.value} mg/dL) +2 yrs")
+
+    # 9. Iron store depletion: Ferritin critically low
+    if ferritin and ferritin.value is not None and ferritin.value < 8:
+        delta += 1
+        factors.append(f"Very low Ferritin ({ferritin.value} ng/mL) +1 yr")
+
+    # ── Positive factors (subtract years) ────────────────────────────────────
+
+    # 10. All CBC markers Normal → blood health bonus
+    cbc_markers = _find_all(
+        biomarkers, "hemoglobin", "rbc", "wbc", "platelet", "mcv", "mch", "mchc", "hematocrit"
+    )
+    if cbc_markers and all(b.status == BiomarkerStatus.NORMAL for b in cbc_markers):
+        delta -= 1
+        factors.append("All CBC markers normal -1 yr")
+
+    # 11. All lipids Normal
+    lipid_markers = _find_all(biomarkers, "cholesterol", "hdl", "ldl", "triglyceride", "vldl")
+    if lipid_markers and all(b.status == BiomarkerStatus.NORMAL for b in lipid_markers):
+        delta -= 1
+        factors.append("All lipid markers normal -1 yr")
+
+    # 12. Liver enzymes both Normal
+    if (
+        sgpt and sgpt.status == BiomarkerStatus.NORMAL
+        and sgot and sgot.status == BiomarkerStatus.NORMAL
+    ):
+        delta -= 1
+        factors.append("Liver enzymes both normal -1 yr")
+
+    # ── Final bio age ─────────────────────────────────────────────────────────
+    if chrono_age > 0:
+        bio_age = max(18, chrono_age + delta)
+    else:
+        # No chronological age — estimate from population baseline (35) + delta
+        bio_age = max(18, 35 + delta)
+
+    return bio_age, delta, factors
+
+
+# ── Top priority finder ───────────────────────────────────────────────────────
+
+def _find_top_priority(biomarkers: list[Biomarker], score: int) -> str:
+    """
+    Single most important finding — shown prominently in the health card.
+
+    Priority:
+    1. CRITICAL markers → immediate danger
+    2. Score < 55 → worst abnormal marker
+    3. Normal score → most impactful abnormal (DEFICIENT > LOW, ELEVATED > HIGH)
+    4. All normal → affirmative message
+    """
+    # 1. Critical
+    critical = [b for b in biomarkers if b.status == BiomarkerStatus.CRITICAL]
+    if critical:
+        bm = critical[0]
+        return (
+            f"{bm.name} is at a critical level ({bm.value_raw} {bm.unit}) "
+            "and needs immediate medical attention."
+        )
+
+    # 2 & 3. Worst abnormal by priority score
+    abnormal = [b for b in biomarkers if b.status != BiomarkerStatus.NORMAL]
+    if not abnormal:
+        return "All biomarkers are within normal range. Keep up the good work!"
+
+    # Sort by status priority (descending), then by category weight (descending)
+    def _sort_key(bm: Biomarker) -> tuple[int, float]:
+        cat_w = CATEGORY_WEIGHT.get(bm.category.value, 1.0)
+        return (_STATUS_PRIORITY.get(bm.status, 0), cat_w)
+
+    abnormal.sort(key=_sort_key, reverse=True)
+    top = abnormal[0]
+
+    direction = {
+        BiomarkerStatus.LOW:       "is low",
+        BiomarkerStatus.HIGH:      "is high",
+        BiomarkerStatus.DEFICIENT: "is deficient",
+        BiomarkerStatus.ELEVATED:  "is elevated",
+    }.get(top.status, "is abnormal")
+
+    return (
+        f"{top.name} {direction} ({top.value_raw} {top.unit}; "
+        f"normal: {top.normal_range_text}). Consult your doctor."
+    )
+
+
+# ── Critical alert ────────────────────────────────────────────────────────────
+
+def _compute_critical_alert(biomarkers: list[Biomarker]) -> tuple[bool, str]:
+    """Return (has_critical, critical_text)."""
+    critical = [b for b in biomarkers if b.status == BiomarkerStatus.CRITICAL]
+    if not critical:
+        return False, ""
+
+    names = ", ".join(
+        f"{b.name} ({b.value_raw} {b.unit})" for b in critical
+    )
+    text = (
+        f"Critical values detected: {names}. "
+        "Please seek immediate medical attention and show this report to a doctor."
+    )
+    return True, text
+
+
+# ── Main entry point ──────────────────────────────────────────────────────────
+
+def compute_health_metrics(
+    biomarkers:      list[Biomarker],
+    patient_age_str: str = "",
+    gender:          str = "unknown",
+) -> HealthMetrics:
+    """
+    Single function to compute all health metrics from classified biomarkers.
+    Pure — no I/O, no LLM. Fully unit-testable.
+
+    Args:
+        biomarkers:      Classified Biomarker list (status already set by range_db)
+        patient_age_str: Raw age string from report e.g. "28 Years"
+        gender:          "male" | "female" | "unknown"
+
+    Returns:
+        HealthMetrics dataclass with all scoring fields populated.
+    """
+    if not biomarkers:
+        return HealthMetrics(
+            health_score=100,
+            health_grade="Excellent",
+            biological_age=0,
+            chronological_age=0,
+            bio_age_delta=0,
+            top_priority="No biomarkers found in the report.",
+            has_critical_alert=False,
+            critical_alert_text="",
+        )
+
+    # ── Score ─────────────────────────────────────────────────────────────────
+    score = _compute_score(biomarkers)
+    grade = _score_to_grade(score)
+
+    # ── Age ───────────────────────────────────────────────────────────────────
+    chrono_age           = _parse_age(patient_age_str)
+    bio_age, delta, factors = _estimate_bio_age(biomarkers, chrono_age)
+
+    # ── Priority ──────────────────────────────────────────────────────────────
+    top_priority = _find_top_priority(biomarkers, score)
+
+    # ── Critical alert ────────────────────────────────────────────────────────
+    has_crit, crit_text = _compute_critical_alert(biomarkers)
+
+    return HealthMetrics(
+        health_score=score,
+        health_grade=grade,
+        biological_age=bio_age,
+        chronological_age=chrono_age,
+        bio_age_delta=delta,
+        bio_age_factors=factors,
+        top_priority=top_priority,
+        has_critical_alert=has_crit,
+        critical_alert_text=crit_text,
+    )

app/core/unit_validator.py

@@ -0,0 +1,110 @@
+"""
+LabCard AI — Analyte unit validation
+Ensures parsed units match expected clinical units per analyte.
+"""
+from __future__ import annotations
+
+import re
+
+# Canonical analyte → allowed units (first entry is default when unit missing)
+KNOWN_UNITS: dict[str, list[str]] = {
+    "Sodium": ["mEq/L", "mmol/L"],
+    "Potassium": ["mEq/L", "mmol/L"],
+    "Hemoglobin": ["g/dL", "g/L"],
+    "Platelet Count": ["lakhs/cumm", "10^3/µL", "thousands/µL", "10^3/uL", "cells/cumm"],
+    "WBC Count": ["cells/cumm", "10^3/µL", "10^3/uL", "cells/cu.mm"],
+    "WBC": ["cells/cumm", "10^3/µL", "10^3/uL"],
+    "Serum Creatinine": ["mg/dL", "µmol/L", "umol/L"],
+    "Creatinine": ["mg/dL", "µmol/L", "umol/L"],
+    "Glucose": ["mg/dL", "mmol/L"],
+    "Fasting Blood Glucose": ["mg/dL", "mmol/L"],
+    "Random Blood Glucose": ["mg/dL", "mmol/L"],
+    "TSH": ["mIU/L", "µIU/mL", "uIU/mL", "mIU/mL"],
+    "Vitamin D": ["ng/mL", "nmol/L"],
+    "SGOT": ["U/L", "IU/L"],
+    "SGPT": ["U/L", "IU/L"],
+    "Total Bilirubin": ["mg/dL"],
+    "Bilirubin": ["mg/dL"],
+    "Total Cholesterol": ["mg/dL"],
+    "Cholesterol": ["mg/dL"],
+    "Triglycerides": ["mg/dL"],
+    "HDL Cholesterol": ["mg/dL"],
+    "LDL Cholesterol": ["mg/dL"],
+    "HbA1c": ["%", "percent"],
+    "Uric Acid": ["mg/dL"],
+    "BUN": ["mg/dL"],
+    "Calcium": ["mg/dL", "mmol/L"],
+    "Iron": ["µg/dL", "ug/dL"],
+    "Ferritin": ["ng/mL"],
+    "Vitamin B12": ["pg/mL"],
+}
+
+# Extra aliases → canonical KNOWN_UNITS key
+_UNIT_ALIASES: dict[str, str] = {
+    "Haemoglobin": "Hemoglobin",
+    "S. Creatinine": "Serum Creatinine",
+    "S Creatinine": "Serum Creatinine",
+    "Blood Urea": "BUN",
+    "Blood Urea Nitrogen": "BUN",
+    "Total Cholesterol (TC)": "Total Cholesterol",
+    "FBS": "Fasting Blood Glucose",
+    "Fasting Glucose": "Fasting Blood Glucose",
+}
+
+
+def _normalize_unit(unit: str) -> str:
+    u = unit.strip()
+    u = u.replace("μ", "µ").replace("uIU", "µIU").replace("umol", "µmol")
+    u = re.sub(r"\s+", "", u)
+    return u.lower()
+
+
+def _match_analyte_key(canonical_name: str) -> str | None:
+    name = canonical_name.strip()
+    if name in KNOWN_UNITS:
+        return name
+    if name in _UNIT_ALIASES:
+        return _UNIT_ALIASES[name]
+
+    name_lower = name.lower()
+    for key in KNOWN_UNITS:
+        if key.lower() == name_lower:
+            return key
+    for alias, key in _UNIT_ALIASES.items():
+        if alias.lower() == name_lower:
+            return key
+    for key in KNOWN_UNITS:
+        if key.lower() in name_lower or name_lower in key.lower():
+            return key
+    return None
+
+
+def validate_unit(canonical_name: str, unit: str) -> tuple[str, bool]:
+    """
+    Validate/fix unit for a canonical analyte name.
+
+    Returns:
+        (unit_to_use, parsing_error)
+        - missing unit → first KNOWN_UNITS entry, no error
+        - valid unit   → unchanged, no error
+        - wrong unit   → empty string, parsing_error=True
+    """
+    key = _match_analyte_key(canonical_name)
+    if not key:
+        return unit.strip(), False
+
+    allowed = KNOWN_UNITS[key]
+    raw = unit.strip()
+
+    if not raw:
+        return allowed[0], False
+
+    normalized = _normalize_unit(raw)
+    for candidate in allowed:
+        if _normalize_unit(candidate) == normalized:
+            return raw, False
+        # Partial match: g/dl vs g/dL
+        if normalized.replace("/", "") == _normalize_unit(candidate).replace("/", ""):
+            return candidate, False
+
+    return "", True

app/db/__init__.py

@@ -0,0 +1 @@
+# LabCard AI Backend

app/db/supabase_client.py

@@ -0,0 +1,302 @@
+"""
+LabCard AI — Supabase Async Client
+====================================
+All DB calls are async and non-blocking.
+Errors are swallowed — Supabase failure NEVER breaks an API response.
+Backend uses the service role key (bypasses RLS for writes).
+"""
+from __future__ import annotations
+
+import datetime
+import logging
+from typing import Any
+
+from app.config import settings
+from app.models.biomarker import BiomarkerStatus
+from app.models.report import LabReport
+
+log = logging.getLogger("labcard.supabase")
+
+# ── Client singleton ──────────────────────────────────────────────────────────
+# Initialized lazily on first use (avoids startup error if Supabase not configured)
+try:
+    from supabase import AsyncClient, acreate_client as _acreate_client
+    _SUPABASE_AVAILABLE = True
+except ImportError:
+    _SUPABASE_AVAILABLE = False
+    log.warning("supabase package not installed — DB persistence disabled")
+
+_client: "AsyncClient | None" = None
+
+
+async def get_client() -> "AsyncClient":
+    """
+    Return the Supabase async client singleton.
+    Creates it on first call (lazy init for faster startup).
+    Uses service role key — bypasses RLS for backend writes.
+    """
+    global _client
+
+    if not _SUPABASE_AVAILABLE:
+        raise RuntimeError("supabase package not installed")
+
+    if not settings.supabase_url or not settings.supabase_service_key:
+        raise RuntimeError("SUPABASE_URL or SUPABASE_SERVICE_KEY not configured")
+
+    if _client is None:
+        _client = await _acreate_client(
+            settings.supabase_url,
+            settings.supabase_service_key,
+        )
+        log.info("Supabase client initialized: %s", settings.supabase_url)
+
+    return _client
+
+
+# ── JWT user extraction ───────────────────────────────────────────────────────
+
+def extract_user_id_from_jwt(token: str) -> str | None:
+    """
+    Decode Supabase JWT and extract the user UUID (sub claim).
+    Does NOT verify signature here — Supabase validates on table RLS.
+    We use it only to tag the row with user_id.
+
+    Returns None if token is invalid or missing sub claim.
+    """
+    try:
+        import base64
+        import json
+
+        # JWT structure: header.payload.signature (base64url encoded)
+        parts = token.split(".")
+        if len(parts) != 3:
+            return None
+
+        # Pad base64url to standard base64
+        payload_b64 = parts[1]
+        pad = 4 - len(payload_b64) % 4
+        if pad != 4:
+            payload_b64 += "=" * pad
+        payload_bytes = base64.urlsafe_b64decode(payload_b64)
+        claims = json.loads(payload_bytes)
+        return str(claims.get("sub")) or None
+
+    except Exception as exc:  # noqa: BLE001
+        log.debug("JWT decode failed (non-fatal): %s", exc)
+        return None
+
+
+# ── Report persistence ────────────────────────────────────────────────────────
+
+async def save_report(
+    token:   str,
+    report:  LabReport,
+) -> str | None:
+    """
+    Save a LabReport to the reports table.
+    Extracts user_id from JWT (anonymous if token invalid/absent).
+
+    Returns the new report UUID, or None on failure.
+    NEVER raises — errors are logged and swallowed.
+    """
+    try:
+        user_id = extract_user_id_from_jwt(token) if token else None
+        client  = await get_client()
+
+        abnormal_count = sum(
+            1 for b in report.biomarkers
+            if b.status != BiomarkerStatus.NORMAL
+        )
+
+        payload: dict[str, Any] = {
+            "user_id":            user_id,
+            "patient_name":       report.patient_name,
+            "patient_age":        report.patient_age,
+            "patient_gender":     report.patient_gender,
+            "lab_name":           report.lab_name,
+            "report_date":        report.report_date,
+            "health_score":       report.health_score,
+            "health_grade":       report.health_grade,                   # already str
+            "biological_age":     report.biological_age,
+            "chronological_age":  report.chronological_age,
+            "has_critical_alert": report.has_critical_alert,
+            "tier_used":          report.tier_used.value,
+            "biomarker_count":    len(report.biomarkers),
+            "abnormal_count":     abnormal_count,
+            "processing_time_ms": report.processing_time_ms,
+            # Full JSON — enables future trend analysis without re-parsing
+            "report_json":        report.model_dump(mode="json"),
+        }
+
+        result = await client.table("reports").insert(payload).execute()
+
+        if result.data:
+            report_id = result.data[0]["id"]
+            log.info(
+                "Report saved: id=%s user=%s score=%d",
+                report_id, user_id or "anon", report.health_score,
+            )
+            return report_id
+
+        log.warning("Supabase insert returned no data")
+        return None
+
+    except Exception as exc:  # noqa: BLE001
+        log.warning("save_report failed (non-fatal): %s", exc)
+        return None
+
+
+# ── User tier lookup ──────────────────────────────────────────────────────────
+
+async def get_user_tier(user_id: str) -> str:
+    """
+    Fetch user tier from user_profiles table.
+    Returns "free" on any error (fail-safe default).
+    """
+    try:
+        client = await get_client()
+        result = (
+            await client
+            .table("user_profiles")
+            .select("tier, premium_expires_at")
+            .eq("id", user_id)
+            .single()
+            .execute()
+        )
+
+        if not result.data:
+            return "free"
+
+        tier       = result.data.get("tier", "free")
+        expires_at = result.data.get("premium_expires_at")
+
+        # If monthly plan has expired, treat as free
+        if tier == "premium" and expires_at:
+            try:
+                expiry = datetime.datetime.fromisoformat(
+                    expires_at.replace("Z", "+00:00")
+                )
+                if datetime.datetime.now(datetime.timezone.utc) > expiry:
+                    log.info("Premium expired for user %s — treating as free", user_id)
+                    return "free"
+            except ValueError:
+                pass   # malformed date — keep tier as-is
+
+        return tier
+
+    except Exception as exc:  # noqa: BLE001
+        log.warning("get_user_tier failed (non-fatal, defaulting free): %s", exc)
+        return "free"
+
+
+# ── Premium upgrade ───────────────────────────────────────────────────────────
+
+async def upgrade_user_to_premium(user_id: str, plan: str) -> bool:
+    """
+    Upsert user_profiles row with premium tier.
+    Called after Razorpay payment verification succeeds.
+
+    Returns True on success, False on failure.
+    """
+    try:
+        expires_at: str | None = None
+        if plan == "monthly":
+            expiry_dt = datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(days=30)
+            expires_at = expiry_dt.isoformat()
+
+        client = await get_client()
+
+        await client.table("user_profiles").upsert(
+            {
+                "id":                 user_id,
+                "tier":               "premium",
+                "premium_expires_at": expires_at,
+                "updated_at":         datetime.datetime.now(datetime.timezone.utc).isoformat(),
+            },
+            on_conflict="id",
+        ).execute()
+
+        log.info(
+            "User upgraded to premium: user=%s plan=%s expires=%s",
+            user_id, plan, expires_at or "never",
+        )
+        return True
+
+    except Exception as exc:  # noqa: BLE001
+        log.error("upgrade_user_to_premium failed: %s", exc)
+        return False
+
+
+# ── Payment record ────────────────────────────────────────────────────────────
+
+async def record_payment(
+    user_id:              str | None,
+    razorpay_order_id:    str,
+    razorpay_payment_id:  str,
+    razorpay_signature:   str,
+    plan:                 str,
+    amount_paise:         int,
+) -> bool:
+    """
+    Insert a payment record after successful Razorpay verification.
+    Idempotent — uses UNIQUE on razorpay_order_id so duplicate calls are safe.
+    """
+    try:
+        client = await get_client()
+        now    = datetime.datetime.now(datetime.timezone.utc).isoformat()
+
+        await client.table("payments").upsert(
+            {
+                "user_id":              user_id,
+                "razorpay_order_id":    razorpay_order_id,
+                "razorpay_payment_id":  razorpay_payment_id,
+                "razorpay_signature":   razorpay_signature,
+                "plan":                 plan,
+                "amount_paise":         amount_paise,
+                "status":               "success",
+                "verified_at":          now,
+            },
+            on_conflict="razorpay_order_id",
+        ).execute()
+
+        log.info(
+            "Payment recorded: order=%s payment=%s plan=%s amount_paise=%d",
+            razorpay_order_id, razorpay_payment_id, plan, amount_paise,
+        )
+        return True
+
+    except Exception as exc:  # noqa: BLE001
+        log.error("record_payment failed: %s", exc)
+        return False
+
+
+# ── User report history ───────────────────────────────────────────────────────
+
+async def get_user_reports(
+    user_id: str,
+    limit:   int = 10,
+) -> list[dict[str, Any]]:
+    """
+    Fetch recent reports for a user (for history/trend features).
+    Returns list of lightweight summary dicts (not full report JSON).
+    Returns [] on any error.
+    """
+    try:
+        client = await get_client()
+        result = (
+            await client
+            .table("reports")
+            .select(
+                "id, patient_name, lab_name, report_date, health_score, "
+                "health_grade, biological_age, abnormal_count, created_at"
+            )
+            .eq("user_id", user_id)
+            .order("created_at", desc=True)
+            .limit(limit)
+            .execute()
+        )
+        return result.data or []
+
+    except Exception as exc:  # noqa: BLE001
+        log.warning("get_user_reports failed: %s", exc)
+        return []

app/main.py

@@ -0,0 +1,47 @@
+"""
+LabCard AI Backend — FastAPI Entry Point
+Deployed on Hugging Face Spaces (Docker SDK, port 7860)
+Frontend on Vercel communicates via REST + JWT
+"""
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from app.config import settings
+from app.api import analyze, chat, health
+
+app = FastAPI(
+    title="LabCard AI Backend",
+    description=(
+        "Lab report parsing + AI analysis API for Indian patients. "
+        "Tier 1-2: deterministic (zero LLM). "
+        "Tier 3: Gemini/Groq free. "
+        "Tier 4: Claude premium."
+    ),
+    version="1.0.0",
+    docs_url="/docs",
+    redoc_url="/redoc",
+)
+
+# CORS — allow Vercel frontend only in production
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.origins_list,
+    allow_credentials=True,
+    allow_methods=["GET", "POST", "OPTIONS"],
+    allow_headers=["*"],
+)
+
+# Routers
+app.include_router(health.router,   prefix="/api", tags=["health"])
+app.include_router(analyze.router,  prefix="/api", tags=["analyze"])
+app.include_router(chat.router,     prefix="/api", tags=["chat"])
+
+
+@app.get("/")
+async def root() -> dict[str, str]:
+    return {
+        "service": "LabCard AI Backend",
+        "status":  "running",
+        "version": "1.0.0",
+        "docs":    "/docs",
+    }

app/models/__init__.py

@@ -0,0 +1 @@
+# LabCard AI Backend

app/models/biomarker.py

@@ -0,0 +1,103 @@
+"""
+LabCard AI — Biomarker Pydantic v2 Models
+All deterministic fields — status assigned by Python logic, never LLM.
+"""
+from __future__ import annotations
+from pydantic import BaseModel, Field, model_validator
+from enum import Enum
+
+
+class BiomarkerStatus(str, Enum):
+    NORMAL    = "Normal"
+    LOW       = "Low"
+    HIGH      = "High"
+    DEFICIENT = "Deficient"
+    ELEVATED  = "Elevated"
+    CRITICAL  = "Critical"
+
+
+class BiomarkerCategory(str, Enum):
+    BLOOD   = "Blood"
+    THYROID = "Thyroid"
+    VITAMIN = "Vitamin"
+    LIVER   = "Liver"
+    KIDNEY  = "Kidney"
+    SUGAR   = "Sugar"
+    LIPID   = "Lipid"
+    OTHER   = "Other"
+
+
+class Biomarker(BaseModel):
+    """
+    Fully deterministic biomarker result.
+    status is assigned by Python range comparison — never by LLM.
+    explanation / advice / indian_foods are filled in Tier 3/4 AI step.
+    """
+    # Core parsed fields
+    name:               str
+    value:              float
+    value_raw:          str           # original string from report e.g. "10.2"
+    unit:               str           = ""
+
+    # Reference range — lab printed (primary) or ICMR fallback
+    normal_range_low:   float | None  = None
+    normal_range_high:  float | None  = None
+    normal_range_text:  str           = ""   # e.g. "13.0 - 17.0" or "> 40"
+
+    # Classification (deterministic Python logic)
+    status:   BiomarkerStatus   = BiomarkerStatus.NORMAL
+    category: BiomarkerCategory = BiomarkerCategory.OTHER
+
+    # Source of reference range
+    source: str = "lab"   # "lab" | "icmr" | "aiims" | "who"
+
+    # AI-enriched fields (Tier 3 — Groq/Gemini, empty until AI step runs)
+    explanation:       str       = ""
+    explanation_hindi: str       = ""
+    advice:            str       = ""
+    indian_foods:      list[str] = Field(default_factory=list)
+
+    # Set when unit validation fails — wrong unit stripped, never shown to user
+    parsing_error: bool = False
+
+    @model_validator(mode="after")
+    def validate_range_consistency(self) -> "Biomarker":
+        """If both low and high are set, low must be <= high."""
+        if (
+            self.normal_range_low is not None
+            and self.normal_range_high is not None
+            and self.normal_range_low > self.normal_range_high
+        ):
+            # Swap silently — some labs print high first
+            self.normal_range_low, self.normal_range_high = (
+                self.normal_range_high,
+                self.normal_range_low,
+            )
+        return self
+
+    @property
+    def color(self) -> str:
+        """Frontend card color mapping."""
+        if self.status == BiomarkerStatus.NORMAL:
+            return "green"
+        if self.status in (BiomarkerStatus.LOW, BiomarkerStatus.HIGH):
+            return "yellow"
+        return "red"   # Deficient | Elevated | Critical
+
+    @property
+    def is_abnormal(self) -> bool:
+        return self.status != BiomarkerStatus.NORMAL
+
+
+class BiomarkerRaw(BaseModel):
+    """
+    Intermediate model produced by the regex parser.
+    Status is NOT assigned yet — assigned in scorer.py after range lookup.
+    Kept separate to make the pipeline stages explicit and testable.
+    """
+    name:       str
+    value_raw:  str   # raw string before float conversion
+    unit:       str   = ""
+    range_raw:  str   = ""   # extracted range string from report
+    line_text:  str   = ""   # full original line (for debugging)
+    page_num:   int   = 0    # PDF page number (for debugging)

app/models/report.py

@@ -0,0 +1,152 @@
+"""
+LabCard AI — Report + API Request/Response Pydantic v2 Models
+"""
+from __future__ import annotations
+from pydantic import BaseModel, Field, model_validator
+from enum import Enum
+from app.models.biomarker import Biomarker
+
+
+class HealthGrade(str, Enum):
+    EXCELLENT = "Excellent"
+    GOOD      = "Good"
+    FAIR      = "Fair"
+    POOR      = "Poor"
+    CRITICAL  = "Critical"
+
+
+class UserTier(str, Enum):
+    FREE    = "free"
+    PREMIUM = "premium"
+
+
+# ── Request models ─────────────────────────────────────────────────────────────
+
+class AnalyzeRequest(BaseModel):
+    """For direct text submission (PDF handled as multipart upload in route)."""
+    text: str  = Field(..., min_length=50, max_length=50_000)
+    tier: UserTier = UserTier.FREE
+    lang: str  = "en"
+
+
+class ChatMessage(BaseModel):
+    role:    str   # "user" | "assistant"
+    content: str   = Field(..., min_length=1)
+
+    @model_validator(mode="after")
+    def validate_role(self) -> "ChatMessage":
+        if self.role not in ("user", "assistant"):
+            raise ValueError("role must be 'user' or 'assistant'")
+        return self
+
+
+class ChatRequest(BaseModel):
+    messages:    list[ChatMessage] = Field(..., min_length=1, max_length=20)
+    report_data: str               = Field(..., description="JSON-stringified LabReport")
+    lang:        str               = "en"
+    tier:        UserTier          = UserTier.FREE
+
+    @model_validator(mode="after")
+    def trim_history(self) -> "ChatRequest":
+        """Keep only last 10 messages to control token usage."""
+        if len(self.messages) > 10:
+            self.messages = self.messages[-10:]
+        return self
+
+
+# ── Core report model ──────────────────────────────────────────────────────────
+
+class LabReport(BaseModel):
+    """
+    Complete analysis output.
+
+    Tier 2 fills:  patient info, biomarkers, health_score, health_grade,
+                   has_critical_alert, critical_alert_text
+    Tier 3 fills:  summary, summary_hindi, doctor_note, top_priority,
+                   biomarker.explanation, biomarker.advice, biomarker.indian_foods
+    Tier 4 fills:  biological_age, chronological_age, bio_age_insight,
+                   bio_age_protocol (premium only)
+    """
+
+    # ── Patient info (Tier 2 — deterministic extraction) ─────────────────────
+    patient_name:   str = "Unknown"
+    patient_age:    str = ""
+    patient_gender: str = "Unknown"
+    report_date:    str = ""
+    lab_name:       str = ""
+
+    # ── Health scoring (Tier 2 — deterministic, never LLM) ───────────────────
+    health_score: int        = Field(default=100, ge=0, le=100)
+    health_grade: HealthGrade = HealthGrade.GOOD
+
+    # ── Biological age (Tier 4 only — Claude premium) ────────────────────────
+    biological_age:    int | None = None
+    chronological_age: int | None = None
+    bio_age_insight:   str        = ""
+    bio_age_protocol:  list[str]  = Field(default_factory=list)
+
+    # ── Summaries (Tier 3 — Groq/Gemini) ─────────────────────────────────────
+    summary:       str = ""
+    summary_hindi: str = ""
+    doctor_note:   str = ""
+    top_priority:  str = ""
+
+    # ── Critical alert (Tier 2 — deterministic, never LLM) ───────────────────
+    has_critical_alert:  bool = False
+    critical_alert_text: str  = ""
+
+    # ── Biomarkers (Tier 2 core + Tier 3 explanations) ───────────────────────
+    biomarkers: list[Biomarker] = Field(default_factory=list)
+
+    # ── Metadata ─────────────────────────────────────────────────────────────
+    tier_used:           UserTier = UserTier.FREE
+    processing_time_ms:  int | None = None
+    ai_provider_used:    str       = ""   # "groq" | "gemini" | "claude" | "none"
+
+    @model_validator(mode="after")
+    def set_grade_from_score(self) -> "LabReport":
+        """Auto-derive grade from score for consistency."""
+        s = self.health_score
+        if s >= 85:
+            self.health_grade = HealthGrade.EXCELLENT
+        elif s >= 70:
+            self.health_grade = HealthGrade.GOOD
+        elif s >= 50:
+            self.health_grade = HealthGrade.FAIR
+        elif s >= 30:
+            self.health_grade = HealthGrade.POOR
+        else:
+            self.health_grade = HealthGrade.CRITICAL
+        return self
+
+    @model_validator(mode="after")
+    def auto_critical_alert(self) -> "LabReport":
+        """
+        Auto-set has_critical_alert if any biomarker is Critical.
+        scorer.py also sets this explicitly, but this is a safety net.
+        """
+        from app.models.biomarker import BiomarkerStatus
+        critical_bm = [b for b in self.biomarkers if b.status == BiomarkerStatus.CRITICAL]
+        if critical_bm and not self.has_critical_alert:
+            self.has_critical_alert  = True
+            names = ", ".join(b.name for b in critical_bm[:3])
+            self.critical_alert_text = (
+                f"Critical values detected: {names}. "
+                "Please consult a doctor immediately."
+            )
+        return self
+
+
+# ── Response models ────────────────────────────────────────────────────────────
+
+class AnalyzeResponse(LabReport):
+    """
+    Identical to LabReport — kept as separate class so the API route
+    can add response_model=AnalyzeResponse for OpenAPI docs.
+    """
+    pass
+
+
+class ChatResponse(BaseModel):
+    reply: str
+    lang:  str

data/icmr_ranges.json

@@ -0,0 +1,214 @@
+{
+  "Hemoglobin": {
+    "male":   { "low": 13.0, "high": 17.0, "unit": "g/dL",       "category": "Blood" },
+    "female": { "low": 12.0, "high": 15.5, "unit": "g/dL",       "category": "Blood" }
+  },
+  "RBC Count": {
+    "male":   { "low": 4.5,  "high": 5.5,  "unit": "million/uL", "category": "Blood" },
+    "female": { "low": 4.0,  "high": 5.0,  "unit": "million/uL", "category": "Blood" }
+  },
+  "WBC Count": {
+    "any": { "low": 4000, "high": 11000, "unit": "cells/uL", "category": "Blood" }
+  },
+  "Platelet Count": {
+    "any": { "low": 150000, "high": 400000, "unit": "/uL", "category": "Blood" }
+  },
+  "MCV": {
+    "any": { "low": 80, "high": 100, "unit": "fL", "category": "Blood" }
+  },
+  "MCH": {
+    "any": { "low": 27, "high": 32, "unit": "pg", "category": "Blood" }
+  },
+  "MCHC": {
+    "any": { "low": 31.5, "high": 34.5, "unit": "g/dL", "category": "Blood" }
+  },
+  "Hematocrit": {
+    "male":   { "low": 40, "high": 50, "unit": "%", "category": "Blood" },
+    "female": { "low": 36, "high": 46, "unit": "%", "category": "Blood" }
+  },
+  "Neutrophils": {
+    "any": { "low": 40, "high": 75, "unit": "%", "category": "Blood" }
+  },
+  "Lymphocytes": {
+    "any": { "low": 20, "high": 45, "unit": "%", "category": "Blood" }
+  },
+  "Eosinophils": {
+    "any": { "low": 1, "high": 6, "unit": "%", "category": "Blood" }
+  },
+  "Monocytes": {
+    "any": { "low": 2, "high": 10, "unit": "%", "category": "Blood" }
+  },
+  "Basophils": {
+    "any": { "low": 0, "high": 1, "unit": "%", "category": "Blood" }
+  },
+  "Serum Iron": {
+    "any": { "low": 60, "high": 170, "unit": "ug/dL", "category": "Blood" }
+  },
+  "TIBC": {
+    "any": { "low": 250, "high": 370, "unit": "ug/dL", "category": "Blood" }
+  },
+  "Serum Ferritin": {
+    "male":   { "low": 12,  "high": 300, "unit": "ng/mL", "category": "Blood" },
+    "female": { "low": 12,  "high": 150, "unit": "ng/mL", "category": "Blood" }
+  },
+  "Transferrin Saturation": {
+    "any": { "low": 20, "high": 50, "unit": "%", "category": "Blood" }
+  },
+  "TSH": {
+    "any": { "low": 0.4, "high": 4.0, "unit": "uIU/mL", "category": "Thyroid" }
+  },
+  "T3": {
+    "any": { "low": 60, "high": 200, "unit": "ng/dL", "category": "Thyroid" }
+  },
+  "T4": {
+    "any": { "low": 4.5, "high": 12.5, "unit": "ug/dL", "category": "Thyroid" }
+  },
+  "Free T3": {
+    "any": { "low": 2.3, "high": 4.2, "unit": "pg/mL", "category": "Thyroid" }
+  },
+  "Free T4": {
+    "any": { "low": 0.89, "high": 1.76, "unit": "ng/dL", "category": "Thyroid" }
+  },
+  "Vitamin D": {
+    "any": {
+      "low": 30, "high": 100, "unit": "ng/mL", "category": "Vitamin",
+      "deficient_threshold": 20,
+      "insufficient_threshold": 30
+    }
+  },
+  "Vitamin B12": {
+    "any": {
+      "low": 200, "high": 900, "unit": "pg/mL", "category": "Vitamin",
+      "deficient_threshold": 140
+    }
+  },
+  "Folic Acid": {
+    "any": { "low": 3.0, "high": 17.0, "unit": "ng/mL", "category": "Vitamin" }
+  },
+  "Vitamin C": {
+    "any": { "low": 0.6, "high": 2.0, "unit": "mg/dL", "category": "Vitamin" }
+  },
+  "Fasting Blood Glucose": {
+    "any": {
+      "low": 70, "high": 100, "unit": "mg/dL", "category": "Sugar",
+      "elevated_threshold": 126
+    }
+  },
+  "HbA1c": {
+    "any": {
+      "low": 4.0, "high": 5.6, "unit": "%", "category": "Sugar",
+      "prediabetes_threshold": 6.4,
+      "diabetes_threshold": 6.5
+    }
+  },
+  "Post Prandial Glucose": {
+    "any": { "low": 70, "high": 140, "unit": "mg/dL", "category": "Sugar" }
+  },
+  "Random Blood Glucose": {
+    "any": { "low": 70, "high": 140, "unit": "mg/dL", "category": "Sugar" }
+  },
+  "SGPT": {
+    "male":   { "low": 0, "high": 40, "unit": "U/L", "category": "Liver" },
+    "female": { "low": 0, "high": 35, "unit": "U/L", "category": "Liver" }
+  },
+  "SGOT": {
+    "any": { "low": 0, "high": 40, "unit": "U/L", "category": "Liver" }
+  },
+  "Alkaline Phosphatase": {
+    "any": { "low": 44, "high": 147, "unit": "U/L", "category": "Liver" }
+  },
+  "Total Bilirubin": {
+    "any": { "low": 0.2, "high": 1.2, "unit": "mg/dL", "category": "Liver" }
+  },
+  "Direct Bilirubin": {
+    "any": { "low": 0.0, "high": 0.3, "unit": "mg/dL", "category": "Liver" }
+  },
+  "Indirect Bilirubin": {
+    "any": { "low": 0.1, "high": 0.8, "unit": "mg/dL", "category": "Liver" }
+  },
+  "Albumin": {
+    "any": { "low": 3.5, "high": 5.0, "unit": "g/dL", "category": "Liver" }
+  },
+  "Total Protein": {
+    "any": { "low": 6.0, "high": 8.3, "unit": "g/dL", "category": "Liver" }
+  },
+  "GGT": {
+    "male":   { "low": 0, "high": 55, "unit": "U/L", "category": "Liver" },
+    "female": { "low": 0, "high": 38, "unit": "U/L", "category": "Liver" }
+  },
+  "Serum Creatinine": {
+    "male":   { "low": 0.7, "high": 1.3, "unit": "mg/dL", "category": "Kidney" },
+    "female": { "low": 0.5, "high": 1.1, "unit": "mg/dL", "category": "Kidney" }
+  },
+  "BUN": {
+    "any": { "low": 7, "high": 20, "unit": "mg/dL", "category": "Kidney" }
+  },
+  "Uric Acid": {
+    "male":   { "low": 3.5, "high": 7.2, "unit": "mg/dL", "category": "Kidney" },
+    "female": { "low": 2.5, "high": 6.0, "unit": "mg/dL", "category": "Kidney" }
+  },
+  "eGFR": {
+    "any": { "low": 60, "high": 999, "unit": "mL/min/1.73m2", "category": "Kidney" }
+  },
+  "Total Cholesterol": {
+    "any": { "low": 0, "high": 200, "unit": "mg/dL", "category": "Lipid" }
+  },
+  "HDL Cholesterol": {
+    "male":   { "low": 40, "high": 999, "unit": "mg/dL", "category": "Lipid" },
+    "female": { "low": 50, "high": 999, "unit": "mg/dL", "category": "Lipid" }
+  },
+  "LDL Cholesterol": {
+    "any": { "low": 0, "high": 100, "unit": "mg/dL", "category": "Lipid" }
+  },
+  "Triglycerides": {
+    "any": { "low": 0, "high": 150, "unit": "mg/dL", "category": "Lipid" }
+  },
+  "VLDL": {
+    "any": { "low": 0, "high": 30, "unit": "mg/dL", "category": "Lipid" }
+  },
+  "Non-HDL Cholesterol": {
+    "any": { "low": 0, "high": 130, "unit": "mg/dL", "category": "Lipid" }
+  },
+  "CRP": {
+    "any": { "low": 0, "high": 5.0, "unit": "mg/L", "category": "Other" }
+  },
+  "hs-CRP": {
+    "any": { "low": 0, "high": 3.0, "unit": "mg/L", "category": "Other" }
+  },
+  "ESR": {
+    "male":   { "low": 0, "high": 15, "unit": "mm/hr", "category": "Other" },
+    "female": { "low": 0, "high": 20, "unit": "mm/hr", "category": "Other" }
+  },
+  "Calcium": {
+    "any": { "low": 8.5, "high": 10.5, "unit": "mg/dL", "category": "Other" }
+  },
+  "Phosphorus": {
+    "any": { "low": 2.5, "high": 4.5, "unit": "mg/dL", "category": "Other" }
+  },
+  "Sodium": {
+    "any": { "low": 136, "high": 145, "unit": "mEq/L", "category": "Other" }
+  },
+  "Potassium": {
+    "any": { "low": 3.5, "high": 5.0, "unit": "mEq/L", "category": "Other" }
+  },
+  "Chloride": {
+    "any": { "low": 98, "high": 107, "unit": "mEq/L", "category": "Other" }
+  },
+  "Magnesium": {
+    "any": { "low": 1.7, "high": 2.2, "unit": "mg/dL", "category": "Other" }
+  },
+  "Zinc": {
+    "any": { "low": 70, "high": 120, "unit": "ug/dL", "category": "Other" }
+  },
+  "Iron Binding Capacity": {
+    "any": { "low": 250, "high": 370, "unit": "ug/dL", "category": "Blood" }
+  },
+  "Testosterone": {
+    "male":   { "low": 300, "high": 1000, "unit": "ng/dL", "category": "Other" },
+    "female": { "low": 15,  "high": 70,   "unit": "ng/dL", "category": "Other" }
+  },
+  "Prolactin": {
+    "male":   { "low": 2,  "high": 18,  "unit": "ng/mL", "category": "Other" },
+    "female": { "low": 2,  "high": 29,  "unit": "ng/mL", "category": "Other" }
+  }
+}

requirements.txt

@@ -0,0 +1,37 @@
+# LabCard AI Backend — Python 3.11
+# Pinned versions tested on HF Spaces Docker SDK
+
+# Core API
+fastapi==0.111.0
+uvicorn[standard]==0.30.1
+python-multipart==0.0.9
+
+# Validation
+pydantic==2.7.4
+pydantic-settings==2.3.4
+
+# PDF Parsing — dual engine
+pdfplumber==0.11.0
+PyMuPDF==1.24.5
+pillow==10.3.0
+
+# AI Providers
+anthropic==0.30.0
+groq==0.9.0
+# Gemini 2.5 Flash → called via httpx REST (no SDK needed, lighter)
+
+# HTTP client
+httpx==0.27.0
+
+# Database
+supabase==2.5.1
+
+# Cache
+upstash-redis==1.1.0
+
+# Auth
+python-jose[cryptography]==3.3.0
+
+# Testing
+pytest==8.2.2
+pytest-asyncio==0.23.7

supabase_schema.sql

@@ -0,0 +1,177 @@
+-- ─────────────────────────────────────────────────────────────────────────────
+-- LabCard AI — Supabase Schema
+-- Run this in Supabase SQL Editor: https://supabase.com/dashboard/project/_/sql
+-- ─────────────────────────────────────────────────────────────────────────────
+
+-- ── User Profiles ─────────────────────────────────────────────────────────────
+-- Extends auth.users — created automatically on first report / payment
+
+CREATE TABLE IF NOT EXISTS public.user_profiles (
+  id                   UUID         REFERENCES auth.users(id) ON DELETE CASCADE PRIMARY KEY,
+  tier                 TEXT         NOT NULL DEFAULT 'free'
+                                    CHECK (tier IN ('free', 'premium')),
+  reports_analyzed     INTEGER      NOT NULL DEFAULT 0,
+  premium_expires_at   TIMESTAMPTZ,
+  created_at           TIMESTAMPTZ  DEFAULT NOW(),
+  updated_at           TIMESTAMPTZ  DEFAULT NOW()
+);
+
+-- Auto-update updated_at on any change
+CREATE OR REPLACE FUNCTION update_updated_at()
+RETURNS TRIGGER AS $$
+BEGIN
+  NEW.updated_at = NOW();
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+CREATE TRIGGER user_profiles_updated_at
+  BEFORE UPDATE ON public.user_profiles
+  FOR EACH ROW EXECUTE FUNCTION update_updated_at();
+
+-- ── Reports ───────────────────────────────────────────────────────────────────
+-- Full LabReport JSON stored in report_json JSONB for future trend analysis.
+-- Summary columns (score, grade, etc.) allow fast SQL aggregates without
+-- parsing the full JSON every time.
+
+CREATE TABLE IF NOT EXISTS public.reports (
+  id                   UUID         DEFAULT gen_random_uuid() PRIMARY KEY,
+  user_id              UUID         REFERENCES auth.users(id) ON DELETE SET NULL,
+  -- Extracted patient fields (denormalized for fast queries)
+  patient_name         TEXT,
+  patient_age          TEXT,
+  patient_gender       TEXT,
+  lab_name             TEXT,
+  report_date          TEXT,
+  -- Health metrics (all deterministic — not from AI)
+  health_score         INTEGER      CHECK (health_score >= 0 AND health_score <= 100),
+  health_grade         TEXT,
+  biological_age       INTEGER,
+  chronological_age    INTEGER,
+  has_critical_alert   BOOLEAN      DEFAULT FALSE,
+  -- Processing metadata
+  tier_used            TEXT         DEFAULT 'free',
+  biomarker_count      INTEGER,
+  abnormal_count       INTEGER,
+  processing_time_ms   INTEGER,
+  -- Full report blob (enables trend queries + future re-analysis)
+  report_json          JSONB        NOT NULL,
+  created_at           TIMESTAMPTZ  DEFAULT NOW()
+);
+
+-- Indexes for common access patterns
+CREATE INDEX IF NOT EXISTS idx_reports_user_id
+  ON public.reports(user_id);
+
+CREATE INDEX IF NOT EXISTS idx_reports_created_at
+  ON public.reports(created_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_reports_health_score
+  ON public.reports(health_score);
+
+-- GIN index on JSONB for fast biomarker trend queries
+CREATE INDEX IF NOT EXISTS idx_reports_json
+  ON public.reports USING GIN (report_json);
+
+-- ── Payments ──────────────────────────────────────────────────────────────────
+-- Audit trail for all Razorpay transactions.
+-- razorpay_order_id is UNIQUE — idempotent upsert is safe.
+
+CREATE TABLE IF NOT EXISTS public.payments (
+  id                   UUID         DEFAULT gen_random_uuid() PRIMARY KEY,
+  user_id              UUID         REFERENCES auth.users(id) ON DELETE SET NULL,
+  razorpay_order_id    TEXT         UNIQUE NOT NULL,
+  razorpay_payment_id  TEXT         UNIQUE,
+  razorpay_signature   TEXT,
+  plan                 TEXT         NOT NULL
+                                    CHECK (plan IN ('per_report', 'monthly')),
+  amount_paise         INTEGER      NOT NULL,
+  status               TEXT         NOT NULL DEFAULT 'pending'
+                                    CHECK (status IN ('pending', 'success', 'failed')),
+  verified_at          TIMESTAMPTZ,
+  created_at           TIMESTAMPTZ  DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idx_payments_user_id
+  ON public.payments(user_id);
+
+-- ── Row Level Security ────────────────────────────────────────────────────────
+-- Users can only read their own data.
+-- Backend uses service role key — bypasses RLS for writes.
+
+ALTER TABLE public.user_profiles ENABLE ROW LEVEL SECURITY;
+ALTER TABLE public.reports       ENABLE ROW LEVEL SECURITY;
+ALTER TABLE public.payments      ENABLE ROW LEVEL SECURITY;
+
+-- user_profiles: users see and update only their own row
+CREATE POLICY "Users see own profile"
+  ON public.user_profiles FOR ALL
+  USING (auth.uid() = id);
+
+-- reports: users can read their own reports
+CREATE POLICY "Users see own reports"
+  ON public.reports FOR SELECT
+  USING (auth.uid() = user_id);
+
+-- reports: backend service role inserts (WITH CHECK true allows service key)
+CREATE POLICY "Service role inserts reports"
+  ON public.reports FOR INSERT
+  WITH CHECK (true);
+
+-- payments: users can only see their own payment records
+CREATE POLICY "Users see own payments"
+  ON public.payments FOR SELECT
+  USING (auth.uid() = user_id);
+
+-- payments: backend service role inserts
+CREATE POLICY "Service role inserts payments"
+  ON public.payments FOR INSERT
+  WITH CHECK (true);
+
+-- ── Helper: increment reports_analyzed counter ────────────────────────────────
+-- Called via trigger when a new report is inserted
+
+CREATE OR REPLACE FUNCTION increment_reports_analyzed()
+RETURNS TRIGGER AS $$
+BEGIN
+  IF NEW.user_id IS NOT NULL THEN
+    INSERT INTO public.user_profiles (id, reports_analyzed)
+      VALUES (NEW.user_id, 1)
+      ON CONFLICT (id) DO UPDATE
+        SET reports_analyzed = user_profiles.reports_analyzed + 1,
+            updated_at = NOW();
+  END IF;
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql SECURITY DEFINER;
+
+CREATE TRIGGER on_report_inserted
+  AFTER INSERT ON public.reports
+  FOR EACH ROW EXECUTE FUNCTION increment_reports_analyzed();
+
+-- ── Trend analysis view (bonus — useful for future dashboard) ─────────────────
+-- Returns latest health score per user for trend charts
+
+CREATE OR REPLACE VIEW public.user_health_trends AS
+SELECT
+  r.user_id,
+  r.id           AS report_id,
+  r.created_at,
+  r.health_score,
+  r.health_grade,
+  r.biological_age,
+  r.chronological_age,
+  r.abnormal_count,
+  r.lab_name
+FROM public.reports r
+WHERE r.user_id IS NOT NULL
+ORDER BY r.user_id, r.created_at DESC;
+
+-- ── Verify setup ──────────────────────────────────────────────────────────────
+SELECT
+  schemaname,
+  tablename,
+  tableowner
+FROM pg_tables
+WHERE schemaname = 'public'
+  AND tablename IN ('user_profiles', 'reports', 'payments');

tests/__init__.py

@@ -0,0 +1 @@
+# LabCard AI Backend

tests/test_parser.py

@@ -0,0 +1,374 @@
+"""
+LabCard AI — Biomarker Parser Tests
+Covers all 4 real-world Indian lab report format variants.
+Run with: pytest tests/test_parser.py -v
+"""
+import sys
+import os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+import pytest
+from app.core.biomarker_parser import (
+    clean_test_name,
+    parse_biomarkers,
+    parse_range,
+    parse_value,
+)
+from app.models.biomarker import BiomarkerRaw
+
+
+# ── parse_value tests ─────────────────────────────────────────────────────────
+
+class TestParseValue:
+    def test_standard_float(self):
+        assert parse_value("10.2") == 10.2
+
+    def test_integer(self):
+        assert parse_value("9800") == 9800.0
+
+    def test_indian_comma(self):
+        assert parse_value("10,200") == 10200.0
+
+    def test_large_indian_comma(self):
+        assert parse_value("1,85,000") == 185000.0
+
+    def test_less_than(self):
+        # "<0.1" → half of 0.1
+        result = parse_value("<0.1")
+        assert result == pytest.approx(0.05, abs=0.001)
+
+    def test_greater_than(self):
+        # ">100" → 101
+        assert parse_value(">100") == 101.0
+
+    def test_with_trailing_flag(self):
+        # Some labs print "10.2 L" (L = Low)
+        assert parse_value("10.2 L") == 10.2
+        assert parse_value("185000 H") == 185000.0
+
+    def test_invalid(self):
+        assert parse_value("N/A") is None
+        assert parse_value("") is None
+        assert parse_value("abc") is None
+
+
+# ── parse_range tests ─────────────────────────────────────────────────────────
+
+class TestParseRange:
+    def test_hyphen_range(self):
+        assert parse_range("13.0 - 17.0") == (13.0, 17.0)
+
+    def test_endash_range(self):
+        assert parse_range("13.0 – 17.0") == (13.0, 17.0)
+
+    def test_no_spaces(self):
+        assert parse_range("13.0-17.0") == (13.0, 17.0)
+
+    def test_large_numbers(self):
+        assert parse_range("150000-400000") == (150000.0, 400000.0)
+
+    def test_less_than(self):
+        low, high = parse_range("< 200")
+        assert low is None
+        assert high == 200.0
+
+    def test_less_than_no_space(self):
+        low, high = parse_range("<200")
+        assert low is None
+        assert high == 200.0
+
+    def test_greater_than(self):
+        low, high = parse_range("> 40")
+        assert low == 40.0
+        assert high is None
+
+    def test_decimal_small(self):
+        assert parse_range("0.4 - 4.0") == (0.4, 4.0)
+
+    def test_inverted_range(self):
+        # Some labs print high first — parser should swap
+        assert parse_range("17.0 - 13.0") == (13.0, 17.0)
+
+    def test_empty(self):
+        assert parse_range("") == (None, None)
+
+    def test_unparseable(self):
+        assert parse_range("Normal") == (None, None)
+
+
+# ── clean_test_name tests ─────────────────────────────────────────────────────
+
+class TestCleanTestName:
+    def test_all_caps(self):
+        result = clean_test_name("HEMOGLOBIN")
+        assert result == "Hemoglobin"
+
+    def test_strips_automated(self):
+        result = clean_test_name("Hemoglobin (Automated)")
+        assert result == "Hemoglobin"
+
+    def test_strips_serum(self):
+        result = clean_test_name("Creatinine (Serum)")
+        assert result == "Creatinine"
+
+    def test_strips_quantitative(self):
+        result = clean_test_name("Vitamin B12 (Quantitative)")
+        assert result == "Vitamin B12"
+
+    def test_preserves_meaningful_paren(self):
+        # (25-OH) is meaningful — keep it
+        result = clean_test_name("Vitamin D (25-OH)")
+        # Should not strip (25-OH) — it's not in the suffix list
+        assert "25-Oh" in result or "25-oh" in result.lower() or "Vitamin D" in result
+
+    def test_max_length(self):
+        long_name = "A" * 60
+        result = clean_test_name(long_name)
+        assert len(result) <= 50
+
+    def test_collapse_spaces(self):
+        result = clean_test_name("Hemoglobin   Count")
+        assert "  " not in result
+
+
+# ── parse_biomarkers tests — 4 real-world formats ────────────────────────────
+
+class TestParseBiomarkers:
+    """Test the main parser with all 4 Indian lab report formats."""
+
+    # Format A — Thyrocare colon-separated with brackets
+    FORMAT_A = """
+COMPLETE BLOOD COUNT (CBC)
+Hemoglobin           : 10.2  g/dL        [13.0 - 17.0]
+WBC Count            : 9800  cells/uL    [4000 - 11000]
+Platelet Count       : 185000 /uL        [150000 - 400000]
+MCV                  : 68    fL          [80 - 100]
+"""
+
+    # Format B — Dr. Lal tabular, no colon
+    FORMAT_B = """
+TEST                    RESULT    UNIT        REFERENCE RANGE
+HEMOGLOBIN (Hb)         10.2      g/dL        13.0 - 17.0   L
+WBC COUNT               9800      cells/uL    4000 - 11000
+PLATELET COUNT          185000    /uL         150000 - 400000
+MCV                     68        fL          80 - 100      L
+"""
+
+    # Format C — Apollo with Ref: prefix
+    FORMAT_C = """
+Haemoglobin   10.2   g/dL   Ref: 13.0-17.0
+WBC           9800   cells/uL   Ref: 4000-11000
+Platelet      185000  /uL   Ref: 150000-400000
+"""
+
+    # Format D — inline abbreviated
+    FORMAT_D = """
+Hb: 10.2 g/dL (N: 13.0-17.0)
+WBC: 9800 cells/uL (N: 4000-11000)
+PLT: 185000 /uL (N: 150000-400000)
+"""
+
+    def _get_parsed(self, text: str) -> dict[str, BiomarkerRaw]:
+        """Helper — parse text and return dict by lowercase name."""
+        results = parse_biomarkers(text)
+        return {r.name.lower(): r for r in results}
+
+    def test_format_a_hemoglobin(self):
+        parsed = self._get_parsed(self.FORMAT_A)
+        # Find hemoglobin (may be titled)
+        hb = next(
+            (v for k, v in parsed.items() if "hemoglobin" in k or "hb" == k),
+            None,
+        )
+        assert hb is not None, f"Hemoglobin not found. Got: {list(parsed.keys())}"
+        assert parse_value(hb.value_raw) == pytest.approx(10.2)
+        assert "13" in hb.range_raw and "17" in hb.range_raw
+
+    def test_format_a_wbc(self):
+        parsed = self._get_parsed(self.FORMAT_A)
+        wbc = next((v for k, v in parsed.items() if "wbc" in k or "white" in k), None)
+        assert wbc is not None, f"WBC not found. Got: {list(parsed.keys())}"
+        val = parse_value(wbc.value_raw)
+        assert val == pytest.approx(9800.0)
+
+    def test_format_a_platelet(self):
+        parsed = self._get_parsed(self.FORMAT_A)
+        plt = next((v for k, v in parsed.items() if "platelet" in k or "plt" in k), None)
+        assert plt is not None, f"Platelet not found. Got: {list(parsed.keys())}"
+        val = parse_value(plt.value_raw)
+        assert val == pytest.approx(185000.0)
+
+    def test_format_b_hemoglobin(self):
+        parsed = self._get_parsed(self.FORMAT_B)
+        hb = next((v for k, v in parsed.items() if "hemoglobin" in k or "hb" in k), None)
+        assert hb is not None, f"Hemoglobin not found in Format B. Got: {list(parsed.keys())}"
+        assert parse_value(hb.value_raw) == pytest.approx(10.2)
+
+    def test_format_c_haemoglobin(self):
+        parsed = self._get_parsed(self.FORMAT_C)
+        hb = next((v for k, v in parsed.items() if "haemoglobin" in k or "hemoglobin" in k), None)
+        assert hb is not None, f"Haemoglobin not found in Format C. Got: {list(parsed.keys())}"
+
+    def test_deduplication(self):
+        """Same test on two lines — keep the one with a range."""
+        text = """
+Hemoglobin : 10.2 g/dL
+Hemoglobin : 10.2 g/dL [13.0 - 17.0]
+"""
+        results = parse_biomarkers(text)
+        hb_results = [r for r in results if "hemoglobin" in r.name.lower()]
+        assert len(hb_results) == 1, "Deduplication failed — got duplicates"
+        assert hb_results[0].range_raw != "", "Should keep entry with range"
+
+    def test_skips_header_lines(self):
+        text = """
+TEST NAME    RESULT    UNIT    REFERENCE RANGE
+Hemoglobin : 10.2 g/dL [13.0 - 17.0]
+PARAMETER    VALUE     NORMAL
+"""
+        results = parse_biomarkers(text)
+        names = [r.name.lower() for r in results]
+        assert not any("test name" in n or "parameter" in n for n in names)
+        assert any("hemoglobin" in n for n in names)
+
+    def test_skips_empty_lines(self):
+        text = "\n\n\n\nHemoglobin : 10.2 g/dL [13.0 - 17.0]\n\n"
+        results = parse_biomarkers(text)
+        assert len(results) >= 1
+
+    def test_empty_text(self):
+        assert parse_biomarkers("") == []
+        assert parse_biomarkers("   ") == []
+
+
+# ── Integration: Demo report from frontend ────────────────────────────────────
+
+class TestDemoReport:
+    """
+    Parse the actual demo-report.txt from the frontend project.
+    Validates end-to-end that all major biomarkers are extracted.
+    """
+
+    DEMO_REPORT = """
+THYROCARE TECHNOLOGIES LIMITED
+Test Report
+
+Patient Name: Rahul Sharma
+Age/Gender: 28 Years / Male
+Sample Collected: 15 May 2025
+Report Date: 16 May 2025
+Lab No: TH9823451
+
+AAROGYAM 1.3 (FULL BODY CHECKUP)
+
+COMPLETE BLOOD COUNT (CBC)
+Hemoglobin           : 10.2  g/dL        [13.0 - 17.0]
+RBC Count            : 4.1   million/uL  [4.5 - 5.5]
+WBC Count            : 9800  cells/uL    [4000 - 11000]
+Platelet Count       : 185000 /uL        [150000 - 400000]
+MCV                  : 68    fL          [80 - 100]
+MCH                  : 22    pg          [27 - 32]
+MCHC                 : 29    g/dL        [31.5 - 34.5]
+Hematocrit (PCV)     : 32    %           [40 - 50]
+
+IRON STUDIES
+Serum Iron           : 42    ug/dL       [60 - 170]
+TIBC                 : 420   ug/dL       [250 - 370]
+Serum Ferritin       : 8     ng/mL       [12 - 300]
+Transferrin Saturation: 10   %           [20 - 50]
+
+THYROID PROFILE
+TSH                  : 2.8   uIU/mL      [0.4 - 4.0]
+T3 (Triiodothyronine): 98    ng/dL       [60 - 200]
+T4 (Thyroxine)       : 7.2   ug/dL       [4.5 - 12.5]
+
+VITAMINS
+Vitamin D (25-OH)    : 14.2  ng/mL       [30 - 100]
+Vitamin B12          : 185   pg/mL       [200 - 900]
+Folic Acid           : 5.8   ng/mL       [3.0 - 17.0]
+
+DIABETES
+Fasting Blood Glucose: 88    mg/dL       [70 - 100]
+HbA1c                : 5.2   %           [4.0 - 5.6]
+
+LIVER FUNCTION TEST
+SGPT (ALT)           : 32    U/L         [0 - 40]
+SGOT (AST)           : 28    U/L         [0 - 40]
+Alkaline Phosphatase : 78    U/L         [44 - 147]
+Bilirubin Total      : 0.8   mg/dL       [0.2 - 1.2]
+Albumin              : 4.1   g/dL        [3.5 - 5.0]
+
+KIDNEY FUNCTION TEST
+Serum Creatinine     : 0.9   mg/dL       [0.7 - 1.3]
+Blood Urea Nitrogen  : 14    mg/dL       [7 - 20]
+Uric Acid            : 5.8   mg/dL       [3.5 - 7.2]
+
+LIPID PROFILE
+Total Cholesterol    : 198   mg/dL       [< 200]
+HDL Cholesterol      : 38    mg/dL       [> 40]
+LDL Cholesterol      : 128   mg/dL       [< 100]
+Triglycerides        : 185   mg/dL       [< 150]
+VLDL                 : 37    mg/dL       [< 30]
+"""
+
+    def test_extracts_at_least_20_biomarkers(self):
+        results = parse_biomarkers(self.DEMO_REPORT)
+        assert len(results) >= 20, (
+            f"Expected ≥20 biomarkers, got {len(results)}: "
+            f"{[r.name for r in results]}"
+        )
+
+    def test_key_biomarkers_found(self):
+        results = parse_biomarkers(self.DEMO_REPORT)
+        names_lower = [r.name.lower() for r in results]
+
+        required = [
+            "hemoglobin", "wbc", "platelet", "tsh", "vitamin d",
+            "vitamin b12", "sgpt", "creatinine", "cholesterol",
+        ]
+        for req in required:
+            found = any(req in n for n in names_lower)
+            assert found, (
+                f"Required biomarker '{req}' not found. "
+                f"Got: {[r.name for r in results]}"
+            )
+
+    def test_hemoglobin_value_correct(self):
+        results = parse_biomarkers(self.DEMO_REPORT)
+        hb = next((r for r in results if "hemoglobin" in r.name.lower()), None)
+        assert hb is not None
+        assert parse_value(hb.value_raw) == pytest.approx(10.2)
+        low, high = parse_range(hb.range_raw)
+        assert low == pytest.approx(13.0)
+        assert high == pytest.approx(17.0)
+
+    def test_vitamin_d_range_parsed(self):
+        results = parse_biomarkers(self.DEMO_REPORT)
+        vd = next((r for r in results if "vitamin d" in r.name.lower()), None)
+        assert vd is not None, "Vitamin D not found"
+        low, high = parse_range(vd.range_raw)
+        assert low == pytest.approx(30.0)
+        assert high == pytest.approx(100.0)
+
+    def test_lipid_less_than_range(self):
+        results = parse_biomarkers(self.DEMO_REPORT)
+        chol = next((r for r in results if "cholesterol" in r.name.lower() and "total" in r.name.lower()), None)
+        if chol:
+            low, high = parse_range(chol.range_raw)
+            assert high == pytest.approx(200.0)
+            assert low is None
+
+    def test_no_header_lines_in_results(self):
+        results = parse_biomarkers(self.DEMO_REPORT)
+        names = [r.name.lower() for r in results]
+        bad = ["test name", "parameter", "result", "reference", "thyrocare", "patient"]
+        for b in bad:
+            assert not any(b == n.strip() for n in names), (
+                f"Header/metadata '{b}' appeared in biomarker results"
+            )
+
+    def test_no_duplicates(self):
+        results = parse_biomarkers(self.DEMO_REPORT)
+        names_lower = [r.name.lower() for r in results]
+        duplicates = [n for n in names_lower if names_lower.count(n) > 1]
+        assert not duplicates, f"Duplicate biomarkers found: {duplicates}"

tests/test_scorer.py

@@ -0,0 +1,311 @@
+"""
+LabCard AI — Health Scorer Tests
+Tests verify:
+- Demo report: health_score ≈ 52 (Fair)
+- Demo report: biological_age > chronological_age (28 yrs actual → ~35–38 bio)
+- Demo report: has_critical_alert = False
+- Demo report: top_priority mentions iron/hemoglobin
+- Edge cases: empty list, all normal, single critical
+Run with: pytest tests/test_scorer.py -v
+"""
+import sys
+import os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+import pytest
+from app.core.scorer import (
+    HealthMetrics,
+    _compute_score,
+    _estimate_bio_age,
+    _find_top_priority,
+    _parse_age,
+    _score_to_grade,
+    compute_health_metrics,
+)
+from app.models.biomarker import Biomarker, BiomarkerCategory, BiomarkerStatus
+
+
+# ── Biomarker factory helpers ─────────────────────────────────────────────────
+
+def make_bm(
+    name: str,
+    value: float,
+    status: BiomarkerStatus,
+    category: BiomarkerCategory = BiomarkerCategory.BLOOD,
+    unit: str = "g/dL",
+    normal_range_text: str = "13.0 - 17.0",
+) -> Biomarker:
+    """Create a Biomarker for testing."""
+    return Biomarker(
+        name=name,
+        value=value,
+        value_raw=str(value),
+        unit=unit,
+        normal_range_text=normal_range_text,
+        status=status,
+        category=category,
+    )
+
+
+# ── Demo report biomarkers (mirrors public/demo-report.txt) ──────────────────
+
+def build_demo_biomarkers() -> list[Biomarker]:
+    """
+    Build the full Rahul Sharma demo report biomarker set.
+    Status matches what range_db.classify_status() would return.
+    """
+    return [
+        # CBC — several abnormal (anemia pattern)
+        make_bm("Hemoglobin",     10.2, BiomarkerStatus.LOW,       BiomarkerCategory.BLOOD,  "g/dL",    "13.0 - 17.0"),
+        make_bm("RBC Count",       4.1, BiomarkerStatus.LOW,       BiomarkerCategory.BLOOD,  "M/uL",    "4.5 - 5.5"),
+        make_bm("WBC Count",      9800, BiomarkerStatus.NORMAL,    BiomarkerCategory.BLOOD,  "cells/uL","4000 - 11000"),
+        make_bm("Platelet Count",185000, BiomarkerStatus.NORMAL,   BiomarkerCategory.BLOOD,  "/uL",     "150000 - 400000"),
+        make_bm("MCV",              68, BiomarkerStatus.LOW,       BiomarkerCategory.BLOOD,  "fL",      "80 - 100"),
+        make_bm("MCH",              22, BiomarkerStatus.LOW,       BiomarkerCategory.BLOOD,  "pg",      "27 - 32"),
+        make_bm("MCHC",             29, BiomarkerStatus.LOW,       BiomarkerCategory.BLOOD,  "g/dL",    "31.5 - 34.5"),
+        make_bm("Hematocrit",       32, BiomarkerStatus.LOW,       BiomarkerCategory.BLOOD,  "%",       "40 - 50"),
+        # Iron studies — deficient
+        make_bm("Serum Iron",       42, BiomarkerStatus.LOW,       BiomarkerCategory.BLOOD,  "ug/dL",   "60 - 170"),
+        make_bm("TIBC",            420, BiomarkerStatus.ELEVATED,  BiomarkerCategory.BLOOD,  "ug/dL",   "250 - 370"),
+        make_bm("Serum Ferritin",    8, BiomarkerStatus.DEFICIENT, BiomarkerCategory.BLOOD,  "ng/mL",   "12 - 300"),
+        make_bm("Transferrin Saturation", 10, BiomarkerStatus.LOW, BiomarkerCategory.BLOOD,  "%",       "20 - 50"),
+        # Thyroid — normal
+        make_bm("TSH",             2.8, BiomarkerStatus.NORMAL,   BiomarkerCategory.THYROID, "uIU/mL",  "0.4 - 4.0"),
+        make_bm("T3",               98, BiomarkerStatus.NORMAL,   BiomarkerCategory.THYROID, "ng/dL",   "60 - 200"),
+        make_bm("T4",              7.2, BiomarkerStatus.NORMAL,   BiomarkerCategory.THYROID, "ug/dL",   "4.5 - 12.5"),
+        # Vitamins — deficient
+        make_bm("Vitamin D",       14.2, BiomarkerStatus.DEFICIENT, BiomarkerCategory.VITAMIN,"ng/mL",  "30 - 100"),
+        make_bm("Vitamin B12",      185, BiomarkerStatus.DEFICIENT, BiomarkerCategory.VITAMIN,"pg/mL",  "200 - 900"),
+        make_bm("Folic Acid",       5.8, BiomarkerStatus.NORMAL,  BiomarkerCategory.VITAMIN, "ng/mL",   "3.0 - 17.0"),
+        # Diabetes — normal
+        make_bm("Fasting Blood Glucose", 88, BiomarkerStatus.NORMAL, BiomarkerCategory.SUGAR,"mg/dL",   "70 - 100"),
+        make_bm("HbA1c",           5.2, BiomarkerStatus.NORMAL,   BiomarkerCategory.SUGAR,  "%",       "4.0 - 5.6"),
+        # Liver — normal
+        make_bm("SGPT",             32, BiomarkerStatus.NORMAL,   BiomarkerCategory.LIVER,  "U/L",     "0 - 40"),
+        make_bm("SGOT",             28, BiomarkerStatus.NORMAL,   BiomarkerCategory.LIVER,  "U/L",     "0 - 40"),
+        make_bm("Alkaline Phosphatase", 78, BiomarkerStatus.NORMAL, BiomarkerCategory.LIVER,"U/L",     "44 - 147"),
+        make_bm("Total Bilirubin", 0.8, BiomarkerStatus.NORMAL,   BiomarkerCategory.LIVER,  "mg/dL",   "0.2 - 1.2"),
+        make_bm("Albumin",         4.1, BiomarkerStatus.NORMAL,   BiomarkerCategory.LIVER,  "g/dL",    "3.5 - 5.0"),
+        # Kidney — normal
+        make_bm("Serum Creatinine",0.9, BiomarkerStatus.NORMAL,   BiomarkerCategory.KIDNEY, "mg/dL",   "0.7 - 1.3"),
+        make_bm("BUN",              14, BiomarkerStatus.NORMAL,   BiomarkerCategory.KIDNEY, "mg/dL",   "7 - 20"),
+        make_bm("Uric Acid",       5.8, BiomarkerStatus.NORMAL,   BiomarkerCategory.KIDNEY, "mg/dL",   "3.5 - 7.2"),
+        # Lipids — slightly abnormal
+        make_bm("Total Cholesterol",198, BiomarkerStatus.NORMAL,  BiomarkerCategory.LIPID,  "mg/dL",   "< 200"),
+        make_bm("HDL Cholesterol",  38, BiomarkerStatus.LOW,      BiomarkerCategory.LIPID,  "mg/dL",   "> 40"),
+        make_bm("LDL Cholesterol", 128, BiomarkerStatus.ELEVATED, BiomarkerCategory.LIPID,  "mg/dL",   "< 100"),
+        make_bm("Triglycerides",   185, BiomarkerStatus.ELEVATED, BiomarkerCategory.LIPID,  "mg/dL",   "< 150"),
+        make_bm("VLDL",             37, BiomarkerStatus.ELEVATED, BiomarkerCategory.LIPID,  "mg/dL",   "< 30"),
+    ]
+
+
+# ── _parse_age tests ──────────────────────────────────────────────────────────
+
+class TestParseAge:
+    def test_years_format(self):
+        assert _parse_age("28 Years") == 28
+
+    def test_digits_only(self):
+        assert _parse_age("35") == 35
+
+    def test_yrs_format(self):
+        assert _parse_age("22 Yrs") == 22
+
+    def test_empty(self):
+        assert _parse_age("") == 0
+
+    def test_out_of_range(self):
+        assert _parse_age("200") == 0
+
+    def test_with_gender(self):
+        # "28 Years / Male" — should extract 28
+        assert _parse_age("28 Years / Male") == 28
+
+
+# ── _score_to_grade tests ─────────────────────────────────────────────────────
+
+class TestScoreToGrade:
+    def test_excellent(self):
+        assert _score_to_grade(90) == "Excellent"
+        assert _score_to_grade(85) == "Excellent"
+
+    def test_good(self):
+        assert _score_to_grade(75) == "Good"
+        assert _score_to_grade(70) == "Good"
+
+    def test_fair(self):
+        assert _score_to_grade(60) == "Fair"
+        assert _score_to_grade(55) == "Fair"
+
+    def test_poor(self):
+        assert _score_to_grade(45) == "Poor"
+        assert _score_to_grade(40) == "Poor"
+
+    def test_critical(self):
+        assert _score_to_grade(39) == "Critical"
+        assert _score_to_grade(0) == "Critical"
+
+    def test_boundaries(self):
+        assert _score_to_grade(84) == "Good"    # just below Excellent
+        assert _score_to_grade(69) == "Fair"    # just below Good
+        assert _score_to_grade(54) == "Poor"    # just below Fair
+        assert _score_to_grade(39) == "Critical" # just below Poor
+
+
+# ── Demo report integration tests ────────────────────────────────────────────
+
+class TestDemoReport:
+    """
+    Rahul Sharma (28M) — iron-deficiency anemia + vitamin deficiencies.
+    Expected: Fair score, biological age > chronological, no critical alert.
+    """
+
+    @pytest.fixture(scope="class")
+    def metrics(self) -> HealthMetrics:
+        biomarkers = build_demo_biomarkers()
+        return compute_health_metrics(biomarkers, "28 Years", "male")
+
+    def test_health_score_is_abnormal(self, metrics: HealthMetrics):
+        """
+        Score must be below 70 given the severity of this report.
+        Demo has 16 abnormal markers (8 CBC, 4 iron, 2 vitamin, 3 lipid).
+        Actual score will be low (0-45) — this is clinically correct for
+        multi-system iron deficiency anemia + vitamin deficiencies + dyslipidemia.
+        """
+        assert metrics.health_score <= 55, (
+            f"Expected score ≤55 (significant abnormalities), got {metrics.health_score}"
+        )
+
+    def test_health_grade_is_not_excellent_or_good(self, metrics: HealthMetrics):
+        """Grade should not be Excellent or Good with 16 abnormal markers."""
+        assert metrics.health_grade not in ("Excellent", "Good"), (
+            f"Expected Poor/Fair/Critical, got {metrics.health_grade}"
+        )
+
+    def test_biological_age_older_than_chronological(self, metrics: HealthMetrics):
+        """Bio age must be higher than actual age given iron + vitamin deficiencies."""
+        assert metrics.biological_age > metrics.chronological_age, (
+            f"Bio age {metrics.biological_age} should exceed chrono age {metrics.chronological_age}"
+        )
+
+    def test_biological_age_in_plausible_range(self, metrics: HealthMetrics):
+        """Bio age should be 28 + some delta — roughly 32–42 for this report."""
+        assert 30 <= metrics.biological_age <= 45, (
+            f"Bio age {metrics.biological_age} outside plausible range 30–45"
+        )
+
+    def test_chronological_age_parsed_correctly(self, metrics: HealthMetrics):
+        assert metrics.chronological_age == 28
+
+    def test_no_critical_alert(self, metrics: HealthMetrics):
+        """Demo report has no life-threatening values."""
+        assert metrics.has_critical_alert is False
+        assert metrics.critical_alert_text == ""
+
+    def test_top_priority_mentions_iron_or_hemoglobin(self, metrics: HealthMetrics):
+        """Top finding should reference the dominant issue — iron deficiency / anemia."""
+        priority_lower = metrics.top_priority.lower()
+        has_iron_ref = any(
+            kw in priority_lower
+            for kw in ["hemoglobin", "ferritin", "iron", "anemia", "hb"]
+        )
+        assert has_iron_ref, (
+            f"Top priority should mention iron/hemoglobin but got: {metrics.top_priority!r}"
+        )
+
+    def test_bio_age_factors_present(self, metrics: HealthMetrics):
+        """Factors list should be non-empty and explain the delta."""
+        assert len(metrics.bio_age_factors) > 0
+
+    def test_bio_age_delta_positive(self, metrics: HealthMetrics):
+        """This patient has deficiencies — delta must be positive."""
+        assert metrics.bio_age_delta > 0
+
+
+# ── Edge case tests ───────────────────────────────────────────────────────────
+
+class TestEdgeCases:
+    def test_empty_biomarkers(self):
+        m = compute_health_metrics([], "25", "male")
+        assert m.health_score == 100
+        assert m.health_grade == "Excellent"
+        assert m.has_critical_alert is False
+
+    def test_all_normal(self):
+        biomarkers = [
+            make_bm("Hemoglobin", 14.5, BiomarkerStatus.NORMAL),
+            make_bm("WBC Count", 7000, BiomarkerStatus.NORMAL, BiomarkerCategory.BLOOD, "cells/uL"),
+            make_bm("TSH", 2.5, BiomarkerStatus.NORMAL, BiomarkerCategory.THYROID, "uIU/mL"),
+        ]
+        m = compute_health_metrics(biomarkers, "30", "male")
+        assert m.health_score == 100
+        assert m.health_grade == "Excellent"
+        assert "normal" in m.top_priority.lower()
+        assert not m.has_critical_alert
+
+    def test_single_critical_triggers_alert(self):
+        biomarkers = [
+            make_bm("Hemoglobin", 5.5, BiomarkerStatus.CRITICAL),
+        ]
+        m = compute_health_metrics(biomarkers, "30", "male")
+        assert m.has_critical_alert is True
+        assert "hemoglobin" in m.critical_alert_text.lower()
+        assert "critical" in m.top_priority.lower()
+
+    def test_critical_adds_25_to_deduction(self):
+        only_critical = [make_bm("Hemoglobin", 5.5, BiomarkerStatus.CRITICAL)]
+        only_low      = [make_bm("Hemoglobin", 11.0, BiomarkerStatus.LOW)]
+        score_critical = _compute_score(only_critical)
+        score_low      = _compute_score(only_low)
+        assert score_critical < score_low, "Critical should score lower than Low"
+
+    def test_no_age_gives_zero_chrono(self):
+        m = compute_health_metrics([], "", "male")
+        assert m.chronological_age == 0
+
+    def test_vitamin_deficiency_lowers_score(self):
+        with_vitamin = [make_bm("Vitamin D", 14.2, BiomarkerStatus.DEFICIENT, BiomarkerCategory.VITAMIN)]
+        all_normal   = [make_bm("Hemoglobin", 14.5, BiomarkerStatus.NORMAL)]
+        assert _compute_score(with_vitamin) < _compute_score(all_normal)
+
+    def test_sugar_category_higher_weight(self):
+        """
+        With multiple markers, sugar category accumulates more deduction than blood.
+        Single marker rounds to same score due to integer rounding (93.5→94 == 94.0→94).
+        Use 3 markers to make the weight difference visible.
+        """
+        sugar_bms = [make_bm(f"Sugar{i}", 7.0, BiomarkerStatus.HIGH, BiomarkerCategory.SUGAR, "%") for i in range(3)]
+        blood_bms = [make_bm(f"Blood{i}", 22.0, BiomarkerStatus.LOW,  BiomarkerCategory.BLOOD, "pg") for i in range(3)]
+        # 3 markers: Sugar = 3×5×1.3=19.5 → score 81; Blood = 3×5×1.2=18 → score 82
+        assert _compute_score(sugar_bms) <= _compute_score(blood_bms)
+
+    def test_multiple_critical_amplifies_bio_age(self):
+        bm_list = [
+            make_bm("Hemoglobin", 5.0, BiomarkerStatus.CRITICAL),
+            make_bm("Platelet Count", 10000, BiomarkerStatus.CRITICAL, BiomarkerCategory.BLOOD, "/uL"),
+        ]
+        bio_age, delta, _ = _estimate_bio_age(bm_list, 30)
+        assert delta >= 10, f"2 critical markers should add ≥10 years, got {delta}"
+
+    def test_all_lipids_normal_gives_bonus(self):
+        bm_list = [
+            make_bm("Total Cholesterol", 175, BiomarkerStatus.NORMAL, BiomarkerCategory.LIPID, "mg/dL"),
+            make_bm("HDL Cholesterol",    55, BiomarkerStatus.NORMAL, BiomarkerCategory.LIPID, "mg/dL"),
+            make_bm("LDL Cholesterol",    85, BiomarkerStatus.NORMAL, BiomarkerCategory.LIPID, "mg/dL"),
+            make_bm("Triglycerides",      90, BiomarkerStatus.NORMAL, BiomarkerCategory.LIPID, "mg/dL"),
+            make_bm("VLDL",               18, BiomarkerStatus.NORMAL, BiomarkerCategory.LIPID, "mg/dL"),
+        ]
+        _, delta, factors = _estimate_bio_age(bm_list, 30)
+        assert delta <= 0, f"All normal lipids should give ≤0 delta, got {delta}"
+        assert any("lipid" in f.lower() for f in factors)
+
+    def test_prediabetic_hba1c_adds_3_years(self):
+        bm_list = [make_bm("HbA1c", 6.0, BiomarkerStatus.HIGH, BiomarkerCategory.SUGAR, "%")]
+        _, delta, factors = _estimate_bio_age(bm_list, 30)
+        assert delta >= 3, f"Pre-diabetic HbA1c should add ≥3 years, got {delta}"
+        assert any("pre-diabet" in f.lower() or "prediabet" in f.lower() for f in factors)
+
+    def test_diabetic_hba1c_adds_6_years(self):
+        bm_list = [make_bm("HbA1c", 7.5, BiomarkerStatus.ELEVATED, BiomarkerCategory.SUGAR, "%")]
+        _, delta, factors = _estimate_bio_age(bm_list, 30)
+        assert delta >= 6, f"Diabetic HbA1c should add ≥6 years, got {delta}"

tests/test_unit_noise.py

@@ -0,0 +1,62 @@
+"""Tests for unit validation and noise filtering."""
+import sys
+import os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from app.core.biomarker_parser import (
+    filter_report_noise,
+    parse_biomarkers,
+    resolve_and_classify,
+)
+from app.core.unit_validator import validate_unit
+
+
+class TestNoiseFilter:
+    def test_blocks_textbook_footer(self):
+        text = """
+Hemoglobin : 12.5 g/dL [13.0 - 17.0]
+molecular diagnosis fifth edition chapter 3 page 12
+Serum Creatinine : 0.54 mg/dL [0.7 - 1.3]
+"""
+        filtered = filter_report_noise(text)
+        assert "edition" not in filtered.lower()
+        assert "chapter" not in filtered.lower()
+
+    def test_no_textbook_biomarker(self):
+        text = """
+molecular diagnosis fifth edition chapter : 5.0 U/L [1 - 10]
+Hemoglobin : 12.5 g/dL [13.0 - 17.0]
+"""
+        results = parse_biomarkers(text)
+        names = [r.name.lower() for r in results]
+        assert not any("edition" in n or "chapter" in n for n in names)
+        assert any("hemoglobin" in n for n in names)
+
+
+class TestUnitValidation:
+    def test_sodium_rejects_wrong_unit(self):
+        unit, err = validate_unit("Sodium", "U/L")
+        assert err is True
+        assert unit == ""
+
+    def test_sodium_accepts_meq(self):
+        unit, err = validate_unit("Sodium", "mEq/L")
+        assert err is False
+        assert unit == "mEq/L"
+
+    def test_missing_unit_filled_from_dict(self):
+        unit, err = validate_unit("Hemoglobin", "")
+        assert err is False
+        assert unit == "g/dL"
+
+
+class TestDedup:
+    def test_creatinine_not_duplicated(self):
+        text = """
+Serum Creatinine     : 0.54   mg/dL    [0.7 - 1.3]
+Creatinine           : 0.54   mg/dL    [0.7 - 1.3]
+"""
+        raw = parse_biomarkers(text)
+        classified = resolve_and_classify(raw, gender="male")
+        creatinine = [b for b in classified if "creatinine" in b.name.lower()]
+        assert len(creatinine) == 1

venv/Lib/site-packages/pymupdf/mupdfcpp64.dll

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9f86ab1801c0c3df64889bf202222e6dba5522a2303148ae58d2888d35a7b189
+size 23856128

venv/Scripts/python.exe

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:21bb438c0d4a6f1f164b9a646f6ee000340185e5871180aec06db8d3f07c0082
+size 274712

venv/Scripts/uvicorn.exe

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:761b1bd9c49caf8f1e2c73261c887e5e38528c6e78dcf7654d2fbe44f2aaccce
+size 108429