PulseCheck — AI-Powered Medical Bill Auditor

PulseCheck is a multi-agent AI system that forensically audits medical bills against insurance policy documents. It detects overcharges, coding errors, and coverage violations — then generates an appeal letter ready for submission.

Architecture

┌─────────────┐     ┌──────────────┐     ┌───────────────┐
│  Ingestor   │────▶│  Researcher  │────▶│  Supervisor   │
│ (Vision OCR)│     │ (Web Search) │     │ (Policy Audit)│
└─────────────┘     └──────────────┘     └───────┬───────┘
                                                 │
                                        ┌────────▼────────┐
                                        │    Advocate      │
                                        │ (Appeal Letter)  │
                                        └─────────────────┘

Agent	Model	Role
Ingestor	Gemini 2.0 Flash	OCR extraction of bill line items
Researcher	Gemini 2.0 Flash	Web-grounded CPT/HCPCS code verification
Supervisor	Gemini 2.5 Pro	Policy-aware audit with reasoning trace
Advocate	Gemini 2.5 Flash	Appeal letter generation

Quick Start — Local Development

Prerequisites

• Python 3.11+
• Node.js 20+
• A Gemini API key

1. Backend

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

Create a .env file:

GEMINI_API_KEY=your-key-here
OPIK_API_KEY=your-opik-key        # optional — observability
OPIK_WORKSPACE=your-workspace     # optional
OPIK_PROJECT_NAME=PulseCheck      # optional

Start the API server:

uvicorn api:app --reload --port 8000

2. Frontend

cd ui
npm install
npm run dev

Open http://localhost:5173 — the Vite dev server proxies /api requests to the backend on port 8000.

Docker — Production Build

docker build -t pulsecheck .
docker run --rm -p 8080:8080 \
  -e GEMINI_API_KEY=your-key-here \
  pulsecheck

Open http://localhost:8080 — FastAPI serves both the API and the pre-built React UI.

Deploy to GCP Cloud Run

Option A: Source Deploy (simplest)

gcloud run deploy pulsecheck \
  --source . \
  --region us-central1 \
  --allow-unauthenticated \
  --port 8080 \
  --memory 2Gi \
  --timeout 300 \
  --set-env-vars "GEMINI_API_KEY=your-key-here"

Option B: Pre-built Image

# Build and push
gcloud builds submit --tag gcr.io/YOUR_PROJECT/pulsecheck
# Deploy
gcloud run deploy pulsecheck \
  --image gcr.io/YOUR_PROJECT/pulsecheck \
  --region us-central1 \
  --allow-unauthenticated \
  --port 8080 \
  --memory 2Gi \
  --timeout 300 \
  --set-env-vars "GEMINI_API_KEY=your-key-here"

Environment Variables

Variable	Required	Description
GEMINI_API_KEY	Yes	Google Gemini API key
PORT	No	Server port (default: 8080 in Docker, 8000 locally)
OPIK_API_KEY	No	Opik observability API key
OPIK_WORKSPACE	No	Opik workspace name
OPIK_PROJECT_NAME	No	Opik project name

Project Structure

├── api.py              # FastAPI server (API + static UI serving)
├── core.py             # Multi-agent orchestration engine
├── models.py           # Pydantic schemas (MedicalBill, AuditReport)
├── config.py           # Model configuration and generation settings
├── prompts.py          # Agent system prompts
├── observability.py    # Opik tracing setup
├── run_audit.py        # CLI for single audit runs
├── requirements.txt    # Python dependencies
├── Dockerfile          # Multi-stage production build
├── sample_inputs/      # Demo bill images and policy PDFs
└── ui/                 # React frontend (Vite + Tailwind)
    ├── src/
    │   ├── App.jsx     # Main app with audit flow state management
    │   ├── views/      # Landing, Processing, Results views
    │   └── components/ # AgentTimeline, FindingsGrid, AppealLetter, etc.
    └── dist/           # Production build output

CLI Usage

Run a standalone audit from the command line:

python run_audit.py \
  --image /path/to/bill.png \
  --policy /path/to/policy.pdf \
  --output audit_report.json \
  --verbose --show-thoughts