Skip to content

hackfest-dev/HF26-10

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

25 Commits
frontend
frontend
 
 
rag
rag
 
 
server
server
 
 
readme.md
readme.md
 
 

Repository files navigation

🏥 Patient Zero: Autonomous Medical Billing Advocate

Patient Zero is an AI-powered, fully autonomous medical billing advocate. It protects patients from hospital overcharges, upcoding, unbundling, and fraudulent billing practices by automatically auditing medical bills against clinical notes and insurance policies, drafting legal dispute letters, and deploying digital agents to fight the hospital on the patient's behalf.

✨ Core Features

  • 📥 Autopilot Inbox Scanning: Integrates with the Gmail API to securely scan for incoming medical bills (PDFs) with strict, bulletproof domain verification to block spoofed/phishing emails.
  • 🕵️‍♂️ The Master Scribe (AI Audit Engine): Utilizes Google Gemini in a RAG (Retrieval-Augmented Generation) pipeline to extract line items, cross-reference clinical notes against the user's uploaded insurance policy, and detect billing discrepancies.
  • ⚔️ Automated Agent Deployment:
    • Primary (Web): Uses Playwright to autonomously log into the hospital's billing portal and submit the AI-generated dispute letter.
    • Fallback (Voice): Uses Twilio to initiate an automated Text-to-Speech phone call to the hospital's billing department if the web portal is inaccessible.
  • ⚡ Real-Time Dashboard: Built with React and Supabase Realtime. The UI updates instantly via WebSockets when the AI finishes drafting a dispute letter—no page refreshes required.
  • 🛡️ Dynamic Insurance Vault: A multi-step wizard to manage multiple health insurance policies, storing encrypted portal credentials securely.
  • 📁 Manual Override: A modern, floating drag-and-drop UI to manually upload PDF bills directly into the AI extraction pipeline using multer.

🛠️ Tech Stack

Frontend (Client)

  • React (Vite)
  • Tailwind CSS (Styling & Responsive UI)
  • Framer Motion (Fluid animations and micro-interactions)
  • Lucide React (Modern iconography)
  • React Router (Navigation)

Backend (Server)

  • Node.js & Express.js (API Routing & Middleware)
  • Multer (In-memory multipart/form-data handling for PDF uploads)
  • Googleapis (Gmail API integration)
  • Playwright (Headless browser automation for web disputes)
  • Twilio SDK (Telephony and automated voice calls)
  • Google Gemini API (Document extraction and Master Scribe RAG pipeline)

Database & Auth

  • Supabase (PostgreSQL, Row Level Security, Realtime WebSocket subscriptions)

🚀 Getting Started

Prerequisites

  • Node.js (v18 or higher)
  • A Supabase Project
  • Google Cloud Console Project (with Gmail API enabled and OAuth 2.0 credentials)
  • Twilio Account (Account SID, Auth Token, and a Twilio Phone Number)
  • Google Gemini API Key

Installation

  1. Clone the repository 
README.md generated successfully.

```bash
   git clone [https://github.com/yourusername/patient-zero.git](https://github.com/yourusername/patient-zero.git)
   cd patient-zero

  1. Install Backend Dependencies

    cd server
npm install

  2. Install Frontend Dependencies

    cd ../client
npm install

Environment Variables

Create a .env file in your server directory and add the following keys:

# Supabase Configuration
SUPABASE_URL=your_supabase_project_url
SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key

# Google / Gmail API Credentials
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
GOOGLE_CALLBACK_URL=http://localhost:3000/api/auth/google/callback

# AI Engine
GEMINI_API_KEY=your_gemini_api_key

# Twilio Fallback Configuration
TWILIO_SID=your_twilio_account_sid
TWILIO_AUTH_TOKEN=your_twilio_auth_token
TWILIO_PHONE_NUMBER=+1234567890
FALLBACK_PHONE=+0987654321  # Your personal phone number for testing the voice agent

Running the Application

1. Start the Backend Server

cd server
npm run dev
# Server runs on http://localhost:3000

2. Start the Frontend Client

cd client
npm run dev
# Client runs on http://localhost:5173

📂 Project Architecture & Key Files

  • server/src/api/bills.js: Express router handling manual PDF uploads (/upload), triggering the Gmail scanner (/scan), deploying agents (/:id/deploy), and fetching compiled arena data.
  • server/src/services/gmailService.js: The Autopilot scanner. Features strict sender domain verification to prevent processing spoofed emails.
  • server/src/services/agentService.js: Houses runDisputeAgent(). Attempts Playwright web automation first, and automatically falls back to a Twilio voice call if it fails.
  • server/rag/unifiedAudit.js: The brains of the operation. Fetches the bill, fetches the user's insurance policy from Supabase, and prompts Gemini to act as a Master Scribe to find discrepancies and draft the dispute letter. Includes graceful fallbacks for missing policy data.
  • client/src/views/ActionArena.jsx: The main dispute dashboard. Displays the itemized bill, the AI Detective Notes, the drafted letter, and the "Deploy AI Agent" trigger button.
  • client/src/components/dashboard/FloatingUploadBar.jsx: The modern, Gemini-style floating action bar for manual PDF uploads.

⚠️ Disclaimer

Patient Zero is a conceptual tool designed to assist with medical billing disputes. It does not provide certified legal advice. Users should review all AI-generated dispute letters before deploying the autonomous agents. """

with open("README.md", "w", encoding="utf-8") as f: f.write(readme_content)

print("README.md generated successfully.")

Your Markdown file is ready
[file-tag: code-generated-file-0-1776554008595075563]

Here is the complete, perfectly formatted `README.md` text for you to easily copy and paste into your project repository. 

```markdown
# 🏥 Patient Zero: Autonomous Medical Billing Advocate

Patient Zero is an AI-powered, fully autonomous medical billing advocate. It protects patients from hospital overcharges, upcoding, unbundling, and fraudulent billing practices by automatically auditing medical bills against clinical notes and insurance policies, drafting legal dispute letters, and deploying digital agents to fight the hospital on the patient's behalf.

---

## ✨ Core Features

* **📥 Autopilot Inbox Scanning:** Integrates with the Gmail API to securely scan for incoming medical bills (PDFs) with strict, bulletproof domain verification to block spoofed/phishing emails.
* **🕵️‍♂️ The Master Scribe (AI Audit Engine):** Utilizes Google Gemini in a RAG (Retrieval-Augmented Generation) pipeline to extract line items, cross-reference clinical notes against the user's uploaded insurance policy, and detect billing discrepancies.
* **⚔️ Automated Agent Deployment:**
    * **Primary (Web):** Uses **Playwright** to autonomously log into the hospital's billing portal and submit the AI-generated dispute letter.
    * **Fallback (Voice):** Uses **Twilio** to initiate an automated Text-to-Speech phone call to the hospital's billing department if the web portal is inaccessible.
* **⚡ Real-Time Dashboard:** Built with React and Supabase Realtime. The UI updates instantly via WebSockets when the AI finishes drafting a dispute letter—no page refreshes required.
* **🛡️ Dynamic Insurance Vault:** A multi-step wizard to manage multiple health insurance policies, storing encrypted portal credentials securely.
* **📁 Manual Override:** A modern, floating drag-and-drop UI to manually upload PDF bills directly into the AI extraction pipeline using `multer`.

---

## 🛠️ Tech Stack

### Frontend (Client)
* **React** (Vite)
* **Tailwind CSS** (Styling & Responsive UI)
* **Framer Motion** (Fluid animations and micro-interactions)
* **Lucide React** (Modern iconography)
* **React Router** (Navigation)

### Backend (Server)
* **Node.js & Express.js** (API Routing & Middleware)
* **Multer** (In-memory `multipart/form-data` handling for PDF uploads)
* **Googleapis** (Gmail API integration)
* **Playwright** (Headless browser automation for web disputes)
* **Twilio SDK** (Telephony and automated voice calls)
* **Google Gemini API** (Document extraction and Master Scribe RAG pipeline)

### Database & Auth
* **Supabase** (PostgreSQL, Row Level Security, Realtime WebSocket subscriptions)

---

## 🚀 Getting Started

### Prerequisites
* **Node.js** (v18 or higher)
* A **Supabase** Project
* **Google Cloud Console** Project (with Gmail API enabled and OAuth 2.0 credentials)
* **Twilio** Account (Account SID, Auth Token, and a Twilio Phone Number)
* **Google Gemini** API Key

### Installation

1. **Clone the repository**
   ```bash
   git clone [https://github.com/yourusername/patient-zero.git](https://github.com/yourusername/patient-zero.git)
   cd patient-zero

  1. Install Backend Dependencies

    cd server
npm install

  2. Install Frontend Dependencies

    cd ../client
npm install

Environment Variables

Create a .env file in your server directory and add the following keys:

# Supabase Configuration
SUPABASE_URL=your_supabase_project_url
SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key

# Google / Gmail API Credentials
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
GOOGLE_CALLBACK_URL=http://localhost:3000/api/auth/google/callback

# AI Engine
GEMINI_API_KEY=your_gemini_api_key

# Twilio Fallback Configuration
TWILIO_SID=your_twilio_account_sid
TWILIO_AUTH_TOKEN=your_twilio_auth_token
TWILIO_PHONE_NUMBER=+1234567890
FALLBACK_PHONE=+0987654321  # Your personal phone number for testing the voice agent

Running the Application

1. Start the Backend Server

cd server
npm run dev
# Server runs on http://localhost:3000

2. Start the Frontend Client

cd client
npm run dev
# Client runs on http://localhost:5173

📂 Project Architecture & Key Files

  • server/src/api/bills.js: Express router handling manual PDF uploads (/upload), triggering the Gmail scanner (/scan), deploying agents (/:id/deploy), and fetching compiled arena data.
  • server/src/services/gmailService.js: The Autopilot scanner. Features strict sender domain verification to prevent processing spoofed emails.
  • server/src/services/agentService.js: Houses runDisputeAgent(). Attempts Playwright web automation first, and automatically falls back to a Twilio voice call if it fails.
  • server/rag/unifiedAudit.js: The brains of the operation. Fetches the bill, fetches the user's insurance policy from Supabase, and prompts Gemini to act as a Master Scribe to find discrepancies and draft the dispute letter. Includes graceful fallbacks for missing policy data.
  • client/src/views/ActionArena.jsx: The main dispute dashboard. Displays the itemized bill, the AI Detective Notes, the drafted letter, and the "Deploy AI Agent" trigger button.
  • client/src/components/dashboard/FloatingUploadBar.jsx: The modern, Gemini-style floating action bar for manual PDF uploads.

⚠️ Disclaimer

Patient Zero is a conceptual tool designed to assist with medical billing disputes. It does not provide certified legal advice. Users should review all AI-generated dispute letters before deploying the autonomous agents.

About

Hackfest26 repository for T10

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages