ClaimShield-AI

ClaimShield-AI is an open-source, production-grade medical bill auditing platform, hospital price transparency scraper, and automated insurance dispute engine.

Medical bills in the United States are notoriously riddled with billing anomalies, predatory markups, unbundled line items, and upcoded procedural intensity—often billed at 4x to 10x the actual Medicare allowable cost. ClaimShield-AI empowers patients and medical advocates to audit hospital statements against CMS Medicare benchmarks (150% fair market standard) and generate legally enforceable settlement letters citing federal statutes (No Surprises Act, 45 CFR Part 180, and Quantum Meruit doctrine).

---

💰 Practical Monetization & Personal Value

• 🏥 Personal & Family Savings: Audit your own emergency room, MRI, surgery, or outpatient bills to slash predatory balances by 40% to 80%.
• 💼 Turnkey Patient Advocacy Business: Medical billing advocates routinely charge 20%–30% contingency on total dollars saved for clients or a flat $30–$75 audit fee. ClaimShield-AI includes a built-in commission tracker for client case files.
• 🎓 Elite Portfolio Showpiece: Demonstrates practical intersection of Medicine, Health Economics, Legal Tech, Data Scraping, and Full-Stack Engineering.

---

🌟 Key Features

• 📊 CMS Medicare Physician Fee Schedule (MPFS) Scraper: Indexes national Medicare allowable rates, RVUs, and standard fair market benchmarks across common CPT/HCPCS codes.
• 🏥 Hospital Price Transparency Scraper: Integrates hospital machine-readable standard chargemaster files (cash discount rates vs. gross charges) under federal 45 CFR Part 180 rules.
• ⚖️ Automated Legal Dispute Engine: Auto-generates customized dispute & settlement letters citing the No Surprises Act (45 CFR § 149), hospital chargemaster non-disclosure rules, and common law Quantum Meruit fair-value doctrines.
• 🖥️ Interactive Glassmorphic Web App: Includes dynamic line-item bill builder, visual price comparison charts (Chart.js), violation tagging (GROSS_INFLATION, POTENTIAL_UPCODING, DUPLICATE_BILLING), and 1-click letter copying.
• ⚡ CLI & FastAPI REST Endpoints: Run batch audits from terminal (claimshield audit --cpt 73721:3800 99285:2900 --letter) or integrate with patient portal backends.

---

🏗️ System Architecture

flowchart TD
    A[Patient / Client Medical Bill] -->|CPT Codes & Billed Charges| B[ClaimShield Core Audit Engine]
    
    subgraph Data Sources & Scrapers
        C[CMS Medicare Fee Schedule] -->|Medicare Allowable Rates| B
        D[Hospital Chargemasters 45 CFR 180] -->|Cash & Commercial Rates| B
        E[NCCI Coding Edits] -->|Unbundling & Upcoding Rules| B
    end

    subgraph Algorithmic Audit & Legal Engine
        B --> F[Fair Benchmark Calculator (150% Medicare)]
        B --> G[Billing Anomaly Detector]
        B --> H[Advocate Contingency Calculator (25%)]
    end

    F --> I[Itemized Dispute Audit Report]
    G --> I
    H --> I

    I --> J[Glassmorphic Web Dashboard & Charts]
    I --> K[Formal Dispute & Settlement Letter]

Loading

---

🚀 Quickstart

1. Clone & Setup Virtual Environment

git clone https://github.com/AshishSara/ClaimShield-AI.git
cd ClaimShield-AI

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

2. Run Automated Unit Tests

pytest -v

3. Launch Web Dashboard

uvicorn claimshield.server:app --reload --port 8000

Open http://localhost:8000 in your browser.

---

💻 CLI Usage

Audit a medical bill directly from your terminal:

python3 -m claimshield.cli audit \
  --patient "Jane Doe" \
  --provider "Metropolitan Hospital" \
  --state "NY" \
  --cpt 73721:3850 99285:2950 88305:1100

Sample CLI Output:

=======================================================
          ClaimShield-AI Medical Bill Audit            
=======================================================
Audit ID         : AUD-9F2B4810
Patient          : Jane Doe
Provider         : Metropolitan Hospital (NY)
Timestamp        : 2026-08-15 03:38:00 UTC
-------------------------------------------------------
Total Billed     : $7,900.00
Fair Benchmark   : $833.20 (150% Medicare Rate)
POTENTIAL SAVINGS: $7,066.80 (89.5%)
Advocate Fee (25%): $1,766.70 (Your Earned Share)
-------------------------------------------------------
Itemized Line Discrepancies (3):
 • CPT 73721 (MRI Knee Joint): Billed $3,850.00 vs Fair $373.20 | Overcharge: $3,476.80 [GROSS_INFLATION]
 • CPT 99285 (Emergency Dept Visit): Billed $2,950.00 vs Fair $348.75 | Overcharge: $2,601.25 [GROSS_INFLATION]
 • CPT 88305 (Surgical Pathology): Billed $1,100.00 vs Fair $111.30 | Overcharge: $988.70 [GROSS_INFLATION]
=======================================================
💡 Run with --letter flag to print the ready-to-mail formal dispute letter.

To print the full formal legal dispute letter:

python3 -m claimshield.cli audit --cpt 73721:3850 99285:2950 --letter

---

🧪 REST API Reference

Endpoint	Method	Description
GET /api/v1/health	GET	Health check & service version
POST /api/v1/audit	POST	Audit a medical bill with itemized CPT codes & charges

---

📄 License & Author

Distributed under the MIT License. See LICENSE for details.

Author: Ashish Saragadam (Medicine, clinical research, and auditable AI).