A rule-based, deterministic medical billing verification engine built on FastAPI. BillCheck programmatically audits inpatient and outpatient hospital bills by cross-referencing line-item charges against the CMS Medicare Physician Fee Schedule (queried live via the data.cms.gov public API), NCCI Correct Coding Initiative bundling edits, ICD-10-to-CPT clinical plausibility mappings, and FDA-sourced maximum daily drug dosage thresholds. The system produces structured, dollar-quantified discrepancy reports with zero reliance on large language models for the verification logic itself, ensuring full auditability and reproducibility of every flag raised.

                   ┌─────────────────┐
                   │   FastAPI App    │
                   │   (main.py)      │
                   └────────┬────────┘
                            │
              ┌─────────────┼─────────────┐
              │             │             │
     ┌────────▼──────┐ ┌───▼────┐ ┌──────▼───────┐
     │  OAuth 2.0    │ │ Static │ │  REST API    │
     │  (auth.py)    │ │   UI   │ │  Endpoints   │
     └───────────────┘ └────────┘ └──────┬───────┘
                                         │
                              ┌──────────▼──────────┐
                              │  Verification        │
                              │  Pipeline            │
                              │  (pipeline/)         │
                              ├──────────────────────┤
                              │  extractor.py        │
                              │  comparator.py       │
                              │  cms_api.py          │
                              │  scorer.py           │
                              └──────────┬───────────┘
                                         │
                       ┌─────────────────┼─────────────────┐
                       │                 │                 │
              ┌────────▼──────┐ ┌────────▼──────┐ ┌───────▼───────┐
              │ CMS Fee       │ │ NCCI Edit     │ │ Drug Dosage   │
              │ Schedule API  │ │ Lookup Table  │ │ Limits Table  │
              │ + Fallback    │ │               │ │               │
              └───────────────┘ └───────────────┘ └───────────────┘

The comparator module executes 7 independent, composable verification engines in sequence. Each engine operates on the structured PatientBill model and emits zero or more VerificationIssue objects with typed severity levels, CPT/HCPCS code references, and dollar-denominated overcharge estimates.

The scorer module consumes the list of VerificationIssue objects and produces a VerificationReport containing:

• Safety Score: Integer 0-100 computed by deducting 5 points per critical issue, 3 per warning, and 1 per informational finding. Clamped to [0, 100].
• Letter Grade: A (>=90), B (>=75), C (>=60), D (>=40), F (<40).
• Total Flagged Amount: De-duplicated sum of potential_overcharge values, grouped by line_item_index (max overcharge per line) to prevent double-counting across engines.
• Dispute Letter: Auto-generated formal letter addressed to the facility billing department, itemizing each finding with CPT codes and dollar amounts.
• Phone Script: Structured call script for verbal dispute with the billing department.

For uploaded bill images (PNG, JPEG, WebP, GIF, PDF), the extractor module sends the document to the Anthropic Claude Vision API with a specialized medical billing prompt. The model extracts structured line items (CPT/HCPCS codes, charges, dates, quantities) into the PatientBill schema, which then flows through the same deterministic verification pipeline. The LLM is used exclusively for OCR/extraction, never for verification logic.

BillCheckApp/
  main.py                  FastAPI application, middleware stack, API route handlers
  auth.py                  Google OAuth 2.0 flow (login/callback/logout/session)
  models.py                Pydantic schemas: PatientBill, BillLineItem, VerificationIssue, VerificationReport
  reference_data.py        Static reference: CMS fee schedule fallback, NCCI edits, ICD-10 mappings, drug dosage limits
  run.py                   Uvicorn entry point (localhost:8000, reload enabled)
  requirements.txt         Python dependencies
  pipeline/
    comparator.py          7 deterministic verification engines (core business logic)
    cms_api.py             CMS data.cms.gov API client with disk-based caching (7-day TTL)
    extractor.py           Bill-to-text formatter and Claude Vision extraction pipeline
    scorer.py              Safety scoring algorithm, report builder, dispute letter/phone script generator
  data/
    synthetic_bills.py     3 synthetic patient bills with 16+ seeded billing errors across all 7 engine types
  static/
    index.html             Single-page frontend

• Python 3.11+

git clone https://github.com/sreeram0407/BillCheckApp.git
cd BillCheckApp
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Create a .env file in the project root:

# Required for image/PDF bill extraction via Claude Vision (optional for synthetic data)
ANTHROPIC_API_KEY=your_anthropic_api_key

# Required for Google OAuth 2.0 (omit for unauthenticated dev mode)
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
APP_SECRET_KEY=a_cryptographically_random_secret
OAUTH_REDIRECT_URI=http://localhost:8000/auth/callback

When OAuth credentials are absent, the application operates in dev mode: all protected endpoints pass through without authentication, returning a synthetic dev user context.

python run.py

The server binds to http://localhost:8000 with hot reload enabled.

Three synthetic patient bills are loaded at startup, each seeded with intentional billing errors spanning all 7 engine categories:

The cms_api module queries the CMS Medicare Physician & Other Practitioners by Geography and Service dataset (dataset ID 6fea9d79-0129-4e4c-b1b8-23cd86a4f435) at data.cms.gov. It retrieves national-level average Medicare allowed amounts per HCPCS/CPT code, caches responses to disk with a 7-day TTL to minimize API calls, and falls back to the static CMS_FEE_SCHEDULE_FALLBACK dictionary in reference_data.py for any codes not returned by the API or when the service is unreachable.