README.md

metadata

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 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

{
  "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

{
  "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.

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