README.md

---
title: Phoebe Headache Predictor API v3
emoji: 🧠
colorFrom: purple
colorTo: blue
sdk: docker
pinned: true
license: mit
app_port: 7860
---

# 🧠 Phoebe Headache Predictor API v3.0

**Production ML headache risk forecasting** for the [Phoebe](https://empedoclabs.com) iOS app by **EmpedocLabs**.

## How It Works

Predicts headache probability for today + next 6 days using three real-time data streams from the user's iPhone:

| Source | Via | Features Used |
|---|---|---|
| **Weather** | Apple WeatherKit | Barometric pressure, 24h pressure Δ, humidity, temperature |
| **Health** | Apple HealthKit | Sleep (total/deep/REM), resting HR, HRV, workout min, menstrual flow |
| **Diary** | User Input in Phoebe | Yesterday's headache severity, duration, mood, symptoms, triggers |

### Leak-Free Architecture

The model predicts **day T** headache using **day T-1** health/diary data + **day T** weather forecast.
No same-day diary data is used — that would be leakage (you can't know today's headache to predict today's headache).

## API Endpoints

| Method | Path | Description |
|---|---|---|
| `GET` | `/` | API info + example request body |
| `GET` | `/health` | Health check + model metrics |
| `POST` | **`/forecast`** | **7-day headache forecast** (recommended) |
| `POST` | `/predict` | Single prediction (legacy raw features) |
| `POST` | `/predict/batch` | Batch predictions (legacy raw features) |
| `GET` | `/docs` | Interactive Swagger documentation |

## `/forecast` Request

```json
{
  "user_context": {
    "age_range": "30-40",
    "location_region": "Balkan Peninsula, Europe"
  },
  "daily_snapshots": [
    {
      "headache_log": {
        "severity": 3,
        "duration_hours": 4.5,
        "input_date": "2025-06-01",
        "mood": "bad",
        "symptoms": { "symptoms": ["nausea", "photophobia"] },
        "triggers": { "triggers": ["stress", "weather_change"] }
      },
      "health_kit_metrics": {
        "resting_heart_rate": 72,
        "sleep_analysis": {
          "total_duration_hours": 5.1,
          "deep_sleep_minutes": 45,
          "rem_sleep_minutes": 60
        },
        "hrv_summary": { "average_ms": 22 },
        "workout_minutes": 0,
        "had_menstrual_flow": true
      },
      "weather_data": {
        "barometric_pressure_mb": 1005.3,
        "pressure_change_24h_mb": -7.2,
        "humidity_percent": 88,
        "temperature_celsius": 28.5
      }
    }
  ]
}
```

## Response

```json
{
  "predictions": [
    {
      "day": 1,
      "date": "2025-06-01",
      "prediction": 1,
      "probability": 0.7234,
      "risk_level": "very_high",
      "top_risk_factors": ["barometric_pressure_drop", "poor_sleep", "menstrual_phase"]
    }
  ],
  "model_version": "3.0.0",
  "threshold": 0.294
}
```

## Model Details

| Property | Value |
|---|---|
| Algorithm | HistGradientBoosting + Isotonic Calibration |
| Features | 38 (leak-free) |
| Training data | 198,000 samples, 1,000 synthetic users × 200 days |
| User archetypes | chronic_migraine, episodic_tension, menstrual_migraine, weather_sensitive, mixed |
| Test ROC-AUC | 0.686 |
| Test F1 | 0.559 |
| Threshold | 0.294 (tuned on validation set) |

### Top Predictive Features

1. **Recent headache** (yesterday) — strongest predictor
2. **Barometric pressure change** — rapid drops trigger migraines
3. **Headache streak** — consecutive-day pattern detection
4. **HRV** — low heart rate variability = stress = risk
5. **Menstrual flow** — perimenstrual window is highest risk
6. **Humidity** — high humidity worsens symptoms
7. **Temperature** — extremes increase risk

## Deployment

Upload `model.pkl` to the model repo, then create an HF Space with this code.

```bash
# Set environment variables in HF Space settings:
HF_REPO_ID=emp-admin/headache-predictor-xgboost
HF_TOKEN=your_hf_token  # if repo is private
```