# Project export: AthenaCare

This document was generated by HackStack to give an AI agent context about a hackathon project. Sections are labeled with their provenance; content marked as truncated was cut to keep this document small.

## Project metadata

- Hackathon: TreeHacks 2026
- Tagline: Map insurance claim denial patterns across healthcare providers and regions - identify high-risk specialties, track trends, and optimize reimbursement strategies.
- Devpost: https://devpost.com/software/athenacare
- GitHub: https://github.com/amogyisabogy1/Athena-Care
- Video: https://www.youtube.com/embed/b1A58oCsZ48?enablejsapi=1&hl=en_US&rel=0&start=&version=3&wmode=transparent
- Team: 4 GitHub contributor(s) — ds9-code (10 commits), Radha (3 commits), Claude Sonnet 4.5 (1 commits), amogyisabogy1 (1 commits)

## Devpost submission (written by the team)

### Inspiration

Healthcare claim denials cost the US system billions annually and burden both providers and patients. We wanted to leverage publicly available NPPES data to predict which healthcare providers might face compliance issues that correlate with higher claim denial rates, helping administrators proactively identify and address risks.

### What it does

AthenaCare uses machine learning to predict healthcare provider risk levels based on deactivation history and data quality patterns. It analyzes 7+ million provider records from NPPES, extracting features like data completeness, taxonomy codes, license information, and geographic patterns to generate risk scores (High/Medium/Low) via an API endpoint.

### How we built it

ML Pipeline: XGBoost model trained on NPPES provider data (11GB dataset) Feature Engineering: Created 20+ features from data completeness scores, provider taxonomy, license info, deactivation history, and geographic patterns Class Imbalance: Used SMOTE oversampling and class weights to handle severe imbalance (0.35% deactivation rate) Experiment Tracking: Integrated Weights & Biases for metric logging and model versioning Deployment: Built REST API for real-time predictions

### Challenges we ran into

Working with the NPPES dataset presented significant technical hurdles from the start. The raw data file was 11GB containing over 7 million healthcare provider records, which immediately caused memory overflow errors when we attempted to load it into pandas. We had to implement chunked reading strategies, processing the data in 100,000-row batches and using efficient data types (categorical for taxonomy codes, int32 instead of int64) to reduce memory footprint by nearly 60%. Even with these optimizations, feature engineering would crash on the full dataset, so we built our pipeline to save intermediate results to disk and implemented aggressive garbage collection between processing steps. The class imbalance problem was even more severe than typical ML projects - only 0.35% of providers had deactivation history, meaning our target variable had a 285:1 ratio of negative to positive cases. Initial model runs simply predicted "never deactivated" for every provider, achieving 99.65% accuracy but zero predictive value. We experimented with multiple balancing techniques including undersampling (which discarded too much data), class weights (which helped but wasn't enough), and ultimately settled on SMOTE oversampling combined with stratified train-test splits. This required careful tuning since over-aggressive SMOTE created synthetic samples that didn't represent real provider patterns, leading to models that performed well in training but poorly on real data. Memory constraints plagued us throughout model training as well. Given the hackathon's tight timeline, we specifically chose XGBoost over deep learning alternatives (neural networks, transformers) because it offers dramatically faster training times on tabular data - critical when we only had 24-36 hours to iterate on our approach. However, even XGBoost's default behavior loads the entire training matrix into RAM, which caused crashes when training on the full 7 million row dataset with our engineered feature set. We reduced the training sample to 500,000 providers initially, implemented early stopping to prevent unnecessary iterations, and used XGBoost's built-in checkpoint saving to avoid losing progress during long training runs. We also experimented with tree depth limits and reduced the number of boosting rounds, finding a sweet spot that balanced model performance with computational feasibility. The final model trains in about 15 minutes on the sampled dataset compared to the 3+ hours (and frequent crashes) we experienced initially, and this rapid iteration speed was essential for testing different feature engineering approaches and hyperparameter configurations within the hackathon timeframe.

### Accomplishments we're proud of

We successfully built a production-ready data pipeline that processes and engineers meaningful features from 7 million+ healthcare provider records, transforming raw NPPES registration data into a clean, structured dataset with over 20 predictive features. This pipeline doesn't just handle the current data—it's designed to scale and run incrementally as NPPES releases monthly updates, automatically detecting new providers and updating risk scores. The broader implication is significant: hospital networks and insurance companies can now leverage publicly available government data to flag potential compliance issues before they result in claim denials, potentially saving millions in denied claims and administrative overhead. Perhaps most importantly, we created a deployable REST API that accepts NPI numbers and returns risk predictions in milliseconds, making it trivial to integrate into existing healthcare workflows. This can plug directly into Epic Systems or Cerner EHR platforms that major hospital networks like Cleveland Clinic, Mayo Clinic, and Kaiser Permanente use - administrators could see risk flags right in the provider registration interface. Smaller community hospitals and rural health systems, which often lack sophisticated analytics teams, could particularly benefit since AthenaCare provides enterprise-level risk intelligence through a simple API call. The technology is needed because current provider credentialing and claims management systems are largely reactive - they detect problems only after denials occur. AthenaCare enables a proactive approach, identifying potential issues during provider onboarding or before claim submission, fundamentally shifting healthcare administration from firefighting to prevention.

### What we learned

We learned how to integrate a self-built ML model into a fully deployed website, implement feature engineering pipelines, tune hyperparameters through trial and error, and clean massive amounts of data efficiently. Technically, we got deep experience working with diverse and fragmented datasets, implementing chunked reading and streaming to process 10+ GB NPPES files without crashing our laptops, and optimizing memory usage through smarter data types. But the bigger revelation was discovering how much valuable healthcare data just sits unused. NPPES has detailed info on 7 million providers that almost nobody is leveraging for predictions or analytics. We realized that most healthcare inefficiency comes from clinicians and administrators only having local context, they see their own denial rates rising but have no way to benchmark against peers, spot broader patterns, or learn from what works elsewhere. This excessive fragmentation creates billions in preventable waste. Working on this problem got us genuinely excited about building in healthcare long-term. The combination of massive impact potential, hard technical problems, and obvious unmet needs made us realize we want to found companies in this space that bridge data gaps and give providers real intelligence instead of just local guesswork.

### What's next

we're planning to expand AthenaCare's capabilities to accept individual claim information as input before submission. This would involve taking in CPT procedure codes, ICD-10 diagnosis codes, patient demographics, and prior authorization status to predict denial risk for specific claims, not just providers. For example, a hospital could submit a proposed claim for a knee replacement surgery and receive a risk score indicating whether that specific combination of provider, procedure, diagnosis, and patient characteristics is likely to be denied. We want to expand the input types to include unstructured data as well. Medical billing notes, prior authorization denial letters, and appeal documentation contain rich contextual information that our current structured-feature approach misses. Using natural language processing, we could extract denial reasons, identify documentation gaps, and learn which appeal strategies are most effective. For example, if a provider's appeal letters frequently mention "medical necessity not established," the system could flag that as a training gap and recommend specific documentation improvements.

## README (from the GitHub repository)

# AthenaCare

Healthcare provider risk prediction using machine learning on NPPES data.

## Inspiration

Healthcare claim denials cost the US system billions annually and burden both providers and patients. We wanted to leverage publicly available NPPES data to predict which healthcare providers might face compliance issues that correlate with higher claim denial rates, helping administrators proactively identify and address risks.

## What it does

AthenaCare uses machine learning to predict healthcare provider risk levels based on deactivation history and data quality patterns. It analyzes 7+ million provider records from NPPES, extracting features like data completeness, taxonomy codes, license information, and geographic patterns to generate risk scores (High/Medium/Low) via an API endpoint.

## How we built it

- **ML Pipeline**: XGBoost model trained on NPPES provider data (11GB dataset)
- **Feature Engineering**: Created 20+ features from data completeness scores, provider taxonomy, license info, deactivation history, and geographic patterns
- **Class Imbalance**: Used SMOTE oversampling and class weights to handle severe imbalance (0.35% deactivation rate)
- **Experiment Tracking**: Integrated Weights & Biases for metric logging and model versioning
- **Deployment**: Built REST API for real-time predictions

## Challenges we ran into

Working with the NPPES dataset presented significant technical hurdles from the start. The raw data file was 11GB containing over 7 million healthcare provider records, which immediately caused memory overflow errors when we attempted to load it into pandas. We had to implement chunked reading strategies, processing the data in 100,000-row batches and using efficient data types (categorical for taxonomy codes, int32 instead of int64) to reduce memory footprint by nearly 60%. Even with these optimizations, feature engineering would crash on the full dataset, so we built our pipeline to save intermediate results to disk and implemented aggressive garbage collection between processing steps.

The class imbalance problem was even more severe than typical ML projects—only 0.35% of providers had deactivation history, meaning our target variable had a 285:1 ratio of negative to positive cases. Initial model runs simply predicted "never deactivated" for every provider, achieving 99.65% accuracy but zero predictive value. We experimented with multiple balancing techniques including undersampling (which discarded too much data), class weights (which helped but wasn't enough), and ultimately settled on SMOTE oversampling combined with stratified train-test splits. This required careful tuning since over-aggressive SMOTE created synthetic samples that didn't represent real provider patterns, leading to models that performed well in training but poorly on real data.

Memory constraints plagued us throughout model training as well. Given the hackathon's tight timeline, we specifically chose XGBoost over deep learning alternatives (neural networks, transformers) because it offers dramatically faster training times on tabular data—critical when we only had 24-36 hours to iterate on our approach. However, even XGBoost's default behavior loads the entire training matrix into RAM, which caused crashes when training on the full 7 million row dataset with our engineered feature set. We reduced the training sample to 500,000 providers initially, implemented early stopping to prevent unnecessary iterations, and used XGBoost's built-in checkpoint saving to avoid losing progress during long training runs. We also experimented with tree depth limits and reduced the number of boosting rounds, finding a sweet spot that balanced model performance with computational feasibility. The final model trains in about 15 minutes on the sampled dataset compared to the 3+ hours (and frequent crashes) we experienced initially, and this rapid iteration speed was essential for testing different feature engineering approaches and hyperparameter configurations within the hackathon timeframe.

## Accomplishments that we're proud of

We successfully built a production-ready data pipeline that processes and engineers meaningful features from 7 million+ healthcare provider records, transforming raw NPPES registration data into a clean, structured dataset with over 20 predictive features. This pipeline doesn't just handle the current data—it's designed to scale and run incrementally as NPPES releases monthly updates, automatically detecting new providers and updating risk scores. The broader implication is significant: hospital networks and insurance companies can now leverage publicly available government data to flag potential compliance issues before they result in claim denials, potentially saving millions in denied claims and administrative overhead.

Perhaps most importantly, we created a deployable REST API that accepts NPI numbers and returns risk predictions in milliseconds, making it trivial to integrate into existing healthcare workflows. This can plug directly into Epic Systems or Cerner EHR platforms that major hospital networks like Cleveland Clinic, Mayo Clinic, and Kaiser Permanente use—administrators could see risk flags right in the provider registration interface. Smaller community hospitals and rural health systems, which often lack sophisticated analytics teams, could particularly benefit since AthenaCare provides enterprise-level risk intelligence through a simple API call. The technology is needed because current provider credentialing and claims management systems are largely reactive—they detect problems only after denials occur. AthenaCare enables a proactive approach, identifying potential issues during provider onboarding or before claim submission, fundamentally shifting healthcare administration from firefighting to prevention.

## What we learned

We learned how to integrate a self-built ML model into a fully deployed website, implement feature engineering pipelines, tune hyperparameters through trial and error, and clean massive amounts of data efficiently. Technically, we got deep experience working with diverse and fragmented datasets, implementing chunked reading and streaming to process 10+ GB NPPES files without crashing our laptops, and optimizing memory usage through smarter data types. But the bigger revelation was discovering how much valuable healthcare data just sits unused. NPPES has detailed info on 7 million providers that almost nobody is leveraging for predictions or analytics. We realized that most healthcare inefficiency comes from clinicians and administrators only having local context—they see their own denial rates rising but have no way to benchmark against peers, spot broader patterns, or learn from what works elsewhere. This excessive fragmentation creates billions in preventable waste. Working on this problem got us genuinely excited about building in healthcare long-term. The combination of massive impact potential, hard technical problems, and obvious unmet needs made us realize we want to found companies in this space that bridge data gaps and give providers real intelligence instead of just local guesswork.

## What's next for AthenaCare

We're planning to expand AthenaCare's capabilities to accept individual claim information as input before submission. This would involve taking in CPT procedure codes, ICD-10 diagnosis codes, patient demographics, and prior authorization status to predict denial risk for specific claims, not just providers. For example, a hospital could submit a proposed claim for a knee replacement surgery and receive a risk score indicating whether that specific combination of provider, procedure, diagnosis, and patient characteristics is likely to be denied.

We want to expand the input types to include unstructured data as well. Medical billing notes, prior authorization denial letters, and appeal documentation contain rich contextual information that our current structured-fea

[README truncated for size]

## Detected evidence (automated analysis)

Indexed codebase: 38 recognized source files, 233 KB.
- CSS (language) — detected in the code
- FastAPI (technology) — detected in the code
- Flask (technology) — detected in the code
- HTML (language) — detected in the code
- Python (language) — detected in the code
- TypeScript (language) — detected in the code
- React (technology) — claimed on Devpost, not found in the code
- AI coding agent: Claude Code — evidence: commit authorship or trailers

## Codebase structure (from repository index)

### Files (51 of 51)

```
.dockerignore
.gitignore
.railwayignore
backend/.env
backend/app/__init__.py
backend/app/main.py
backend/app/models.py
backend/app/schemas.py
backend/ReadME.md
backend/requirements.txt
dashboard.ts
Dockerfile
docs/CLAIMS_DATA_GUIDE.md
docs/CLASS_IMBALANCE_FIX.md
docs/DOWNLOADING_UHC_DATA.md
docs/PREDICTION_USE_CASES.md
docs/UHC_TIC_INTEGRATION.md
docs/WHAT_CAN_WE_PREDICT.md
frontend/index.html
frontend/src/App.tsx
frontend/src/components/ui/badge.tsx
frontend/src/components/ui/button.tsx
frontend/src/components/ui/card.tsx
frontend/src/components/ui/dropdown-menu.tsx
frontend/src/components/ui/input.tsx
frontend/src/components/ui/separator.tsx
frontend/src/components/ui/table.tsx
frontend/src/components/ui/tabs.tsx
frontend/src/components/ui/utils.ts
frontend/src/dashboard.tsx
frontend/src/main.tsx
frontend/src/styles.css
frontend/vite.config.ts
models/checkpoints/best_model.json
NPPES_Data_Dissemination_February_2026/endpoint_pfile_20050523-20260208_fileheader.csv
NPPES_Data_Dissemination_February_2026/npidata_pfile_20050523-20260208_fileheader.csv
NPPES_Data_Dissemination_February_2026/pl_pfile_20050523-20260208_fileheader.csv
Procfile
README.md
requirements.txt
run_pipeline.py
runtime.txt
src/api.py
src/data_processing.py
src/feature_engineering.py
src/load_claims_data.py
src/load_uhc_tic_data.py
src/model.py
src/predict_provider_risk.py
src/utils.py
UI_INTEGRATION.md
```

### Dependencies

- backend/requirements.txt: fastapi@==0.115.8, numpy@==2.0.2, pydantic@==2.9.2, python-dotenv@==1.0.1, uvicorn[standard]@==0.30.6, xgboost@==2.1.1
- requirements.txt: beautifulsoup4@>=4.12.0, flask@>=2.3.0, flask-cors@>=4.0.0, imbalanced-learn@>=0.11.0, jupyter@>=1.0.0, lxml@>=4.9.0, matplotlib@>=3.7.0, numpy@>=1.24.0, pandas@>=2.0.0, requests@>=2.31.0, scikit-learn@>=1.3.0, seaborn@>=0.12.0, tqdm@>=4.65.0, wandb@>=0.15.0, xgboost@>=2.0.0

### Recent commits (newest first)

- Refine installation and pipeline instructions
- Update README with comprehensive hackathon submission details
- Delete notebooks/01_data_exploration.ipynb
- c'est la vie
- backend
- Integrate XGBoost model for denial risk prediction
- Merge branch 'main' of github.com:amogyisabogy1/Athena-Care
- Add model checkpoint file to repository
- Add model checkpoint to repository
- Update README to remove real claims data instructions
- Merge branch 'main' of github.com:amogyisabogy1/Athena-Care
- Initial commit: Hospital risk prediction model with XGBoost
- Add HealthScore AI main dashboard implementation
- Add files via upload

## Key source files (fetched from GitHub, selected and truncated for size)

### UI_INTEGRATION.md

```markdown
# UI Integration Guide

## For Your Friend: How to Use the Model in Your UI

Your friend doesn't need the model files directly! They just need to **call the API** that serves the model.

## Option 1: Use Deployed API (Recommended - Easiest)

If you deploy the API to Railway/Heroku/etc., your friend just needs the **API URL**.

### Example API Call:

```javascript
// Replace with your deployed API URL
const API_URL = 'https://your-app-name.up.railway.app';

// Make a prediction
async function predictRisk(npi) {
  const response = await fetch(`${API_URL}/predict`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ npi: npi })
  });
  
  const data = await response.json();
  return data.predictions[0];
}

// Usage
const result = await predictRisk('1234567890');
console.log(result.risk_level); // "High", "Medium", or "Low"
console.log(result.predicted_risk); // 0.75 (probability)
```

### API Endpoints:

- `GET /health` - Check if API is running
- `POST /predict` - Get prediction for one or more NPIs
- `GET /providers/search?q=NAME_OR_NPI` - Search for providers
- `GET /model/info` - Get model information

### Example Response:

```json
{
  "predictions": [
    {
      "npi": "1234567890",
      "predicted_risk": 0.75,
      "predicted_class": 1,
      "risk_level": "High",
      "interpretation": "High risk provider. Probability of issues: 75.0%"
    }
  ],
  "count": 1
}
```

## Option 2: Run API Locally

If you want to run the API on your own machine:

### Step 1: Clone the Repository

```bash
git clone https://github.com/amogyisabogy1/Athena-Care.git
cd Athena-Care
```

### Step 2: Install Dependencies

```bash
pip install -r requirements.txt
```

### Step 3: Train the Model (First Time Only)

The model files are not in GitHub (they're too large). You need to train it first:

```bash
# Process the data
python run_pipeline.py

# Or step by step:
python src/data_processing.py
python src/feature_engineering.py
python src/model.py --no-wandb
```

**Note:** You'll need the NPPES data files. Update the path in `src/data_processing.py` to point to your data location.

### Step 4: Start the API Server

```bash
python src/api.py
```

The API will run on `http://localhost:5000`

### Step 5: Use in Your UI

```javascript
const API_URL = 'http://localhost:5000';

// Same API calls as above
```

## Option 3: Direct Model Integration (Advanced)

If your friend wants to use the model directly in their UI (without API), they would need:

1. **Model files** from `models/` directory:
   - `xgb_model_*.pkl` - The trained XGBoost model
   - `label_encoders_*.pkl` - Label encoders for categorical features
   - `model_metadata_*.json` - Model metadata

2. **Feature data** from `data/processed/hospitals_features.csv`

3. **Python dependencies** to load and run the model

This is more complex and not recommended. Using the API is much easier!

## Quick Test

Test the API is working:

```bash
# Health check
cu
[truncated — 386 more characters]
```

### docs/DOWNLOADING_UHC_DATA.md

```markdown
# Downloading UHC Transparency in Coverage Data

## Automated Download

I've created a script to automatically download UHC MRF files:

```bash
# Install required packages
pip install requests beautifulsoup4 lxml

# Download MRF files (limits to 10 files by default)
python src/download_uhc_tic_data.py

# Download all MRF files
python src/download_uhc_tic_data.py --download-all

# Download specific number of files
python src/download_uhc_tic_data.py --max-files 5
```

The script will:
1. Search the UHC transparency website for MRF file links
2. Download MRF index files
3. Extract individual file URLs from index
4. Download all MRF files to `data/raw/`

## Manual Download (If Automated Fails)

If the automated script doesn't work (website structure may vary), you can download manually:

### Step 1: Visit UHC Transparency Site
1. Go to: https://transparency-in-coverage.uhc.com/
2. Navigate to "Machine Readable Files" section
3. Look for download links or API endpoints

### Step 2: Download MRF Index File
- Usually named `index.json` or similar
- Contains list of all MRF files
- May be in a subdirectory like `/mrf/` or `/files/`

### Step 3: Download Individual MRF Files
- Files are typically JSON format
- Can be very large (GBs)
- May need to download in chunks

### Step 4: Place Files in Project
```bash
# Create raw data directory
mkdir -p data/raw

# Move downloaded files
mv ~/Downloads/uhc_mrf_*.json data/raw/
```

## Using Downloaded Files

Once you have the MRF files:

```bash
# Load and integrate with NPPES data
python src/load_uhc_tic_data.py data/raw/uhc_mrf_index.json

# Or use a specific MRF file
python src/load_uhc_tic_data.py data/raw/in-network-rates.json
```

## Troubleshooting

### Script Can't Find Files
- Website structure may have changed
- May require authentication
- Try manual download instead

### Files Are Too Large
- MRF files can be several GBs
- Download may timeout
- Consider downloading in smaller chunks
- Use `wget` or `curl` for resumable downloads

### Rate Limiting
- Script includes delays between downloads
- If you get blocked, increase delay time
- Or download manually

## Alternative: Use Payerset

If UHC's site is difficult to access, consider using [Payerset](https://docs.payerset.com/) which provides:
- Pre-processed MRF data
- Multiple payer data sources
- Easier API access
- Data normalization

## File Structure

UHC MRF files typically contain:
- `reporting_structure`: Array of reporting entities
- `in_network_files`: List of in-network rate files
- `allowed_amount_files`: List of allowed amount files
- Each file entry has:
  - `location`: URL to the file
  - `description`: File description
  - `file_size_bytes`: File size

```

### requirements.txt

```
pandas>=2.0.0
numpy>=1.24.0
xgboost>=2.0.0
scikit-learn>=1.3.0
matplotlib>=3.7.0
seaborn>=0.12.0
jupyter>=1.0.0
tqdm>=4.65.0
wandb>=0.15.0
imbalanced-learn>=0.11.0
requests>=2.31.0
beautifulsoup4>=4.12.0
lxml>=4.9.0
flask>=2.3.0
flask-cors>=4.0.0

```

### Dockerfile

```
FROM python:3.9-slim

WORKDIR /app

# Copy requirements
COPY requirements.txt .

# Install dependencies
RUN pip install --no-cache-dir -r requirements.txt

# Copy application code
COPY src/ ./src/
COPY models/ ./models/
COPY data/processed/ ./data/processed/

# Expose port
EXPOSE 5000

# Run API server
CMD ["python", "src/api.py"]

```

### backend/requirements.txt

```
fastapi==0.115.8
uvicorn[standard]==0.30.6
pydantic==2.9.2
xgboost==2.1.1
numpy==2.0.2
python-dotenv==1.0.1

```

### frontend/src/App.tsx

```typescript
import HealthScoreAIDashboard from "./dashboard";

export default function App() {
  return <HealthScoreAIDashboard />;
}

```

### frontend/src/main.tsx

```typescript
import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";
import "./styles.css";

ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

```

### backend/app/main.py

```python
import os
from dotenv import load_dotenv

load_dotenv()

MODEL_PATH = os.getenv("MODEL_PATH", "./models/xgb_model.json")
print("MODEL_PATH =", os.path.abspath(MODEL_PATH))  # ✅ AFTER definition

from fastapi import FastAPI, HTTPException
from fastapi.middleware.cors import CORSMiddleware
from dotenv import load_dotenv

from .schemas import PredictRequest, PredictResponse, TopFactor
from .models import init_model, predict_denial_probability

load_dotenv()

MODEL_PATH = os.getenv("MODEL_PATH", "./models/xgb_model.json")

app = FastAPI(title="HealthScore AI Model API", version="0.1.0")

# If you call this directly from the frontend in dev, enable CORS.
# If you proxy through Next.js (/api/predict), you can tighten/disable.
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],  # set to your frontend origin(s) in prod
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

@app.on_event("startup")
def startup():
    # If you want strict feature ordering, pass the exact list here.
    init_model(MODEL_PATH)

@app.get("/health")
def health():
    return {"ok": True}

@app.post("/predict", response_model=PredictResponse)
def predict(req: PredictRequest):
    try:
        proba, top = predict_denial_probability(req.features, topk=5)
        return PredictResponse(
            provider_key=req.provider_key,
            denial_probability=proba,
            top_factors=[TopFactor(feature=f, impact=float(v)) for f, v in top],
        )
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

```

### run_pipeline.py

```python
#!/usr/bin/env python3
"""
Main pipeline script to run the complete hospital claims denial prediction pipeline
"""

import sys
from pathlib import Path

# Add src to path
sys.path.insert(0, str(Path(__file__).parent / "src"))

def main():
    """Run the complete pipeline"""
    print("=" * 60)
    print("Hospital Claims Denial Prediction Pipeline")
    print("=" * 60)
    
    # Step 1: Data Processing
    print("\n[Step 1/3] Processing NPPES data...")
    from data_processing import main as process_data
    hospitals_df = process_data()
    
    # Step 2: Feature Engineering
    print("\n[Step 2/3] Engineering features...")
    from feature_engineering import main as engineer_features
    features_df = engineer_features()
    
    # Step 3: Model Training
    print("\n[Step 3/3] Training XGBoost model...")
    from model import main as train_model
    model, metrics = train_model()
    
    print("\n" + "=" * 60)
    print("Pipeline Complete!")
    print("=" * 60)
    print("\nNext steps:")
    print("1. Review model results in the 'results/' directory")
    print("2. Check saved model in the 'models/' directory")
    print("3. Explore data in the 'notebooks/' directory")
    print("\nTo use with real claims data:")
    print("- Replace synthetic target in feature_engineering.py")
    print("- Join NPPES data with actual claims denial data using NPI")
    print("- Retrain the model")

if __name__ == "__main__":
    main()

```

### frontend/vite.config.ts

```typescript
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";

export default defineConfig({
  plugins: [react()],
  server: {
    port: 5173,
    proxy: {
      "/api": {
        target: "http://localhost:8000",
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api/, "")
      }
    }
  }
});

```

[27 more indexed source files omitted to keep this export small. The full file list is in the Codebase structure section above.]