Upload 9 files

Dockerfile

@@ -0,0 +1,12 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+EXPOSE 7860
+
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,11 +1,131 @@
 ---
-title: Headache Predictor Xgboost
-emoji: 👁
-colorFrom: blue
+title: Phoebe Headache Predictor API v3
+emoji: 🧠
+colorFrom: purple
 colorTo: blue
 sdk: docker
-pinned: false
+pinned: true
 license: mit
+app_port: 7860
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🧠 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
+```

app.py

@@ -0,0 +1,288 @@
+"""
+═══════════════════════════════════════════════════════════════════════
+  Phoebe Headache Predictor API v3.0
+  EmpedocLabs © 2025
+═══════════════════════════════════════════════════════════════════════
+
+Endpoints:
+  GET  /              → API info & usage examples
+  GET  /health        → Health + model status
+  POST /forecast      → 7-day headache forecast (DailySnapshotDTO)
+  POST /predict       → Single-day legacy (raw feature vector)
+  POST /predict/batch → Batch legacy (raw feature vectors)
+"""
+
+import logging
+import numpy as np
+import pickle
+import os
+from typing import List
+
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel
+from huggingface_hub import hf_hub_download
+
+from models import (
+    DailySnapshotDTO, UserContextDTO, WeatherDataDTO,
+    PredictionRequest, PredictionResponse, DayPrediction,
+    SinglePredictionRequest, SinglePredictionResponse,
+)
+from feature_engineering import (
+    extract_features_for_day, extract_forecast_features,
+    get_risk_factors, FEATURE_NAMES, NUM_FEATURES,
+)
+
+# ── Logging ──────────────────────────────────────────────────────────
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s | %(levelname)s | %(message)s")
+logger = logging.getLogger("phoebe")
+
+# ── App ──────────────────────────────────────────────────────────────
+
+app = FastAPI(
+    title="Phoebe Headache Predictor API",
+    version="3.0.0",
+    description="ML-powered headache risk forecasting for the Phoebe iOS app by EmpedocLabs.",
+    docs_url="/docs",
+    redoc_url="/redoc",
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# ── Globals ──────────────────────────────────────────────────────────
+
+clf = None
+threshold = 0.5
+model_version = "3.0.0"
+feature_importances = {}
+
+
+# ── Startup ──────────────────────────────────────────────────────────
+
+@app.on_event("startup")
+async def load_model():
+    global clf, threshold, model_version, feature_importances
+
+    try:
+        cache_dir = "/tmp/hf_cache"
+        os.makedirs(cache_dir, exist_ok=True)
+
+        hf_token = os.environ.get("HF_TOKEN")
+        repo_id = os.environ.get("HF_REPO_ID", "emp-admin/headache-predictor-xgboost")
+
+        logger.info(f"Loading model from {repo_id}...")
+
+        model_path = hf_hub_download(
+            repo_id=repo_id, filename="model.pkl",
+            cache_dir=cache_dir, token=hf_token,
+        )
+
+        with open(model_path, "rb") as f:
+            data = pickle.load(f)
+
+        if isinstance(data, dict):
+            clf = data["model"]
+            threshold = float(data.get("optimal_threshold", 0.5))
+            model_version = data.get("model_version", "3.0.0")
+            feature_importances = data.get("feature_importances", {})
+            metrics = data.get("test_metrics", {})
+            logger.info(
+                f"✅ Model v{model_version} loaded | "
+                f"threshold={threshold:.3f} | "
+                f"AUC={metrics.get('roc_auc', '?')} | "
+                f"F1={metrics.get('f1', '?')} | "
+                f"features={data.get('num_features', '?')}"
+            )
+        else:
+            clf = data
+            threshold = 0.5
+            logger.info("✅ Model loaded (legacy format)")
+
+    except Exception as e:
+        logger.error(f"❌ Model load failed: {e}")
+        import traceback
+        traceback.print_exc()
+
+
+# ── Helpers ──────────────────────────────────────────────────────────
+
+def _risk_level(prob: float) -> str:
+    if prob < 0.20: return "low"
+    if prob < 0.40: return "moderate"
+    if prob < 0.65: return "high"
+    return "very_high"
+
+
+# ── Root ─────────────────────────────────────────────────────────────
+
+@app.get("/")
+def root():
+    return {
+        "service": "Phoebe Headache Predictor API",
+        "version": model_version,
+        "by": "EmpedocLabs",
+        "status": "running" if clf is not None else "model_not_loaded",
+        "endpoints": {
+            "/health": "GET — model status & metrics",
+            "/forecast": "POST — 7-day headache risk forecast",
+            "/predict": "POST — single prediction (legacy)",
+            "/predict/batch": "POST — batch prediction (legacy)",
+            "/docs": "GET — Swagger UI",
+        },
+        "example_forecast_body": {
+            "user_context": {"age_range": "30-40", "location_region": "Balkan Peninsula, Europe"},
+            "daily_snapshots": [
+                {
+                    "headache_log": {"severity": 0, "duration_hours": 0, "input_date": "2025-06-01", "mood": "good"},
+                    "health_kit_metrics": {
+                        "resting_heart_rate": 62,
+                        "sleep_analysis": {"total_duration_hours": 7.2, "deep_sleep_minutes": 85, "rem_sleep_minutes": 95},
+                        "hrv_summary": {"average_ms": 42},
+                        "workout_minutes": 30,
+                        "had_menstrual_flow": False,
+                    },
+                    "weather_data": {
+                        "barometric_pressure_mb": 1015.2, "pressure_change_24h_mb": -2.1,
+                        "humidity_percent": 65, "temperature_celsius": 22.5,
+                    },
+                },
+            ],
+        },
+    }
+
+
+@app.get("/health")
+def health():
+    return {
+        "status": "healthy" if clf is not None else "degraded",
+        "model_loaded": clf is not None,
+        "model_version": model_version,
+        "threshold": threshold,
+        "num_features": NUM_FEATURES,
+        "top_features": list(feature_importances.keys())[:5],
+    }
+
+
+# ── /forecast — Main endpoint ───────────────────────────────────────
+
+@app.post("/forecast", response_model=PredictionResponse)
+def forecast(request: PredictionRequest):
+    """
+    7-day headache risk forecast.
+
+    Send daily_snapshots[0] = today (full HealthKit + diary + weather),
+    daily_snapshots[1..6] = future days (weather forecast only).
+
+    Returns probability, risk level, and top risk factors per day.
+    """
+    if clf is None:
+        raise HTTPException(status_code=503, detail="Model not loaded. Please retry shortly.")
+
+    if not request.daily_snapshots:
+        raise HTTPException(status_code=400, detail="daily_snapshots cannot be empty.")
+
+    if len(request.daily_snapshots) > 14:
+        raise HTTPException(status_code=400, detail="Maximum 14 days supported.")
+
+    try:
+        ctx = request.user_context
+        snaps = request.daily_snapshots
+
+        X = extract_forecast_features(snaps, ctx)
+        predictions = []
+
+        for i in range(len(snaps)):
+            prob_arr = clf.predict_proba(X[i:i + 1])[0]
+            prob = float(prob_arr[1])
+            pred = 1 if prob >= threshold else 0
+
+            date_str = None
+            if snaps[i].headache_log and snaps[i].headache_log.input_date:
+                date_str = snaps[i].headache_log.input_date
+
+            risks = get_risk_factors(X[i], feature_importances, top_k=3)
+
+            predictions.append(DayPrediction(
+                day=i + 1,
+                date=date_str,
+                prediction=pred,
+                probability=round(prob, 4),
+                risk_level=_risk_level(prob),
+                top_risk_factors=risks,
+            ))
+
+        logger.info(
+            f"Forecast: {len(snaps)} days | "
+            f"probs={[p.probability for p in predictions]}"
+        )
+
+        return PredictionResponse(
+            predictions=predictions,
+            model_version=model_version,
+            threshold=round(threshold, 4),
+        )
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Forecast error: {e}", exc_info=True)
+        raise HTTPException(status_code=400, detail=f"Forecast error: {str(e)}")
+
+
+# ── Legacy endpoints ─────────────────────────────────────────────────
+
+class BatchRequest(BaseModel):
+    instances: List[List[float]]
+
+class BatchDayPred(BaseModel):
+    day: int
+    prediction: int
+    probability: float
+
+class BatchResponse(BaseModel):
+    predictions: List[BatchDayPred]
+
+
+@app.post("/predict", response_model=SinglePredictionResponse)
+def predict_single(request: SinglePredictionRequest):
+    """Legacy: raw feature vector → single prediction."""
+    if clf is None:
+        raise HTTPException(status_code=503, detail="Model not loaded")
+    try:
+        X = np.array(request.features, dtype=np.float32).reshape(1, -1)
+        if X.shape[1] != NUM_FEATURES:
+            raise ValueError(f"Expected {NUM_FEATURES} features, got {X.shape[1]}")
+        prob = float(clf.predict_proba(X)[0][1])
+        return SinglePredictionResponse(prediction=1 if prob >= threshold else 0, probability=round(prob, 4))
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@app.post("/predict/batch", response_model=BatchResponse)
+def predict_batch(request: BatchRequest):
+    """Legacy: batch raw feature vectors."""
+    if clf is None:
+        raise HTTPException(status_code=503, detail="Model not loaded")
+    try:
+        X = np.array(request.instances, dtype=np.float32)
+        if X.ndim != 2 or X.shape[1] != NUM_FEATURES:
+            raise ValueError(f"Expected shape (n, {NUM_FEATURES}), got {X.shape}")
+        probas = clf.predict_proba(X)[:, 1]
+        preds = (probas >= threshold).astype(int)
+        return BatchResponse(predictions=[
+            BatchDayPred(day=i + 1, prediction=int(preds[i]), probability=round(float(probas[i]), 4))
+            for i in range(len(probas))
+        ])
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=400, detail=str(e))

feature_engineering.py

@@ -0,0 +1,237 @@
+"""
+Feature engineering v3.0 — Leak-free extraction from DailySnapshotDTO.
+
+Predicts day T headache using:
+  - Day T weather forecast (WeatherKit)
+  - Day T-1 HealthKit + diary (lag)
+  - Day T-2 headache history
+  - Temporal + user context + interactions
+
+Total: 38 features.
+"""
+
+from __future__ import annotations
+import math
+import numpy as np
+from datetime import datetime
+from typing import List, Optional
+
+from models import (
+    DailySnapshotDTO, UserContextDTO,
+    HeadacheLogSnapshotDTO, HealthKitMetricsDTO, WeatherDataDTO,
+    SleepAnalysisDTO, HRVSummaryDTO,
+)
+
+MOOD_MAP = {"great": 5, "good": 4, "okay": 3, "bad": 2, "terrible": 1}
+
+FEATURE_NAMES = [
+    "pressure_mb", "pressure_change_24h", "pressure_volatility",
+    "humidity_pct", "temperature_c", "is_pressure_drop",
+    "sleep_total_hours", "deep_sleep_min", "rem_sleep_min",
+    "resting_hr", "hrv_avg_ms", "workout_min", "menstrual_flow_flag",
+    "had_headache_1d", "severity_1d", "duration_1d",
+    "mood_1d", "symptom_count_1d", "trigger_count_1d",
+    "had_headache_2d", "severity_2d", "duration_2d",
+    "dow_sin", "dow_cos", "month_sin", "month_cos",
+    "doy_sin", "doy_cos", "is_weekend",
+    "age_midpoint", "is_europe", "is_tropical",
+    "sleep_x_pressure", "low_hrv_flag", "sleep_deficit",
+    "high_humidity_flag", "headache_streak_2d", "consecutive_headache_days",
+]
+NUM_FEATURES = len(FEATURE_NAMES)  # 38
+
+# Human-readable risk factor labels for the API response
+RISK_LABELS = {
+    "had_headache_1d": "recent_headache",
+    "pressure_change_24h": "barometric_pressure_drop",
+    "consecutive_headache_days": "headache_streak",
+    "hrv_avg_ms": "low_hrv_stress",
+    "headache_streak_2d": "multi_day_pattern",
+    "humidity_pct": "high_humidity",
+    "menstrual_flow_flag": "menstrual_phase",
+    "temperature_c": "temperature_extreme",
+    "sleep_total_hours": "poor_sleep",
+    "is_weekend": "weekend_pattern",
+    "sleep_deficit": "sleep_deficit",
+    "low_hrv_flag": "stress_indicator",
+    "is_pressure_drop": "pressure_front",
+}
+
+
+def _safe(val, default=0.0) -> float:
+    return float(val) if val is not None else default
+
+def _cyclic(value: float, period: float):
+    a = 2 * math.pi * value / period
+    return math.sin(a), math.cos(a)
+
+def _parse_age_range(age_range: Optional[str]) -> float:
+    if not age_range:
+        return 35.0
+    try:
+        parts = age_range.replace(" ", "").split("-")
+        return (float(parts[0]) + float(parts[1])) / 2.0
+    except Exception:
+        return 35.0
+
+
+def extract_features_for_day(
+    target_weather: WeatherDataDTO,
+    target_date: str,
+    yesterday_snapshot: Optional[DailySnapshotDTO],
+    two_days_ago_snapshot: Optional[DailySnapshotDTO],
+    user_ctx: Optional[UserContextDTO] = None,
+    consecutive_headache_days: int = 0,
+) -> np.ndarray:
+    """Build 38-feature vector for predicting headache on target_date."""
+    f: List[float] = []
+
+    w = target_weather or WeatherDataDTO()
+    yest = yesterday_snapshot or DailySnapshotDTO()
+    twod = two_days_ago_snapshot or DailySnapshotDTO()
+    ctx = user_ctx or UserContextDTO()
+
+    yest_hk = yest.health_kit_metrics or HealthKitMetricsDTO()
+    yest_sl = yest_hk.sleep_analysis or SleepAnalysisDTO()
+    yest_hrv = yest_hk.hrv_summary or HRVSummaryDTO()
+    yest_log = yest.headache_log or HeadacheLogSnapshotDTO()
+    twod_log = twod.headache_log or HeadacheLogSnapshotDTO()
+
+    # Weather target (6)
+    pc = _safe(w.pressure_change_24h_mb, 0.0)
+    hum = _safe(w.humidity_percent, 50.0)
+    f.append(_safe(w.barometric_pressure_mb, 1013.25))
+    f.append(pc)
+    f.append(abs(pc))
+    f.append(hum)
+    f.append(_safe(w.temperature_celsius, 15.0))
+    f.append(1.0 if pc < -5 else 0.0)
+
+    # HealthKit yesterday (7)
+    slp = _safe(yest_sl.total_duration_hours, 7.0)
+    hrv = _safe(yest_hrv.average_ms, 40.0)
+    f.append(slp)
+    f.append(_safe(yest_sl.deep_sleep_minutes, 80.0))
+    f.append(_safe(yest_sl.rem_sleep_minutes, 90.0))
+    f.append(_safe(yest_hk.resting_heart_rate, 65.0))
+    f.append(hrv)
+    f.append(_safe(yest_hk.workout_minutes, 0))
+    f.append(1.0 if yest_hk.had_menstrual_flow else 0.0)
+
+    # Headache yesterday (6)
+    yh = 1.0 if yest_log.severity > 0 else 0.0
+    f.append(yh)
+    f.append(float(yest_log.severity))
+    f.append(float(yest_log.duration_hours))
+    f.append(float(MOOD_MAP.get(str(yest_log.mood).lower(), 3)))
+    f.append(float(len(yest_log.symptoms.symptoms)))
+    f.append(float(len(yest_log.triggers.triggers)))
+
+    # Headache 2d ago (3)
+    th = 1.0 if twod_log.severity > 0 else 0.0
+    f.append(th)
+    f.append(float(twod_log.severity))
+    f.append(float(twod_log.duration_hours))
+
+    # Temporal (7)
+    try:
+        dt = datetime.strptime(target_date, "%Y-%m-%d")
+    except (ValueError, TypeError):
+        dt = datetime.now()
+    dw_s, dw_c = _cyclic(dt.weekday(), 7)
+    mn_s, mn_c = _cyclic(dt.month - 1, 12)
+    dy_s, dy_c = _cyclic(dt.timetuple().tm_yday, 365)
+    f.extend([dw_s, dw_c, mn_s, mn_c, dy_s, dy_c])
+    f.append(1.0 if dt.weekday() >= 5 else 0.0)
+
+    # User context (3)
+    f.append(_parse_age_range(ctx.age_range))
+    reg = str(ctx.location_region or "").lower()
+    f.append(1.0 if "europe" in reg else 0.0)
+    f.append(1.0 if "tropic" in reg else 0.0)
+
+    # Interactions (6)
+    f.append(slp * abs(pc))
+    f.append(1.0 if hrv < 25 else 0.0)
+    f.append(max(0.0, 6.0 - slp))
+    f.append(1.0 if hum > 80 else 0.0)
+    f.append(yh + th)
+    f.append(float(min(consecutive_headache_days, 7)))
+
+    return np.array(f, dtype=np.float32)
+
+
+def extract_forecast_features(
+    snapshots: List[DailySnapshotDTO],
+    user_ctx: Optional[UserContextDTO] = None,
+) -> np.ndarray:
+    """
+    Build feature matrix for 7-day forecast.
+    snapshots[0] = today (full data), [1..6] = future (weather only).
+    """
+    rows = []
+    for i in range(len(snapshots)):
+        snap = snapshots[i]
+        tw = snap.weather_data or WeatherDataDTO()
+        td = ""
+        if snap.headache_log and snap.headache_log.input_date:
+            td = snap.headache_log.input_date
+
+        yest = snapshots[i - 1] if i > 0 else None
+        twod = snapshots[i - 2] if i > 1 else None
+
+        consec = 0
+        for j in range(i - 1, -1, -1):
+            lj = snapshots[j].headache_log
+            if lj and lj.severity > 0:
+                consec += 1
+            else:
+                break
+
+        rows.append(extract_features_for_day(tw, td, yest, twod, user_ctx, consec))
+    return np.vstack(rows)
+
+
+def get_risk_factors(
+    features: np.ndarray,
+    feature_importances: dict,
+    top_k: int = 3,
+) -> List[str]:
+    """Identify top risk factors from feature values + learned importances."""
+    risks = []
+
+    # Check each important feature for concerning values
+    checks = [
+        ("had_headache_1d", lambda v: v > 0),
+        ("pressure_change_24h", lambda v: v < -3),
+        ("consecutive_headache_days", lambda v: v >= 2),
+        ("hrv_avg_ms", lambda v: v < 30),
+        ("headache_streak_2d", lambda v: v >= 1),
+        ("humidity_pct", lambda v: v > 75),
+        ("menstrual_flow_flag", lambda v: v > 0),
+        ("temperature_c", lambda v: v > 30 or v < -5),
+        ("sleep_total_hours", lambda v: v < 6),
+        ("sleep_deficit", lambda v: v > 0),
+        ("low_hrv_flag", lambda v: v > 0),
+        ("is_pressure_drop", lambda v: v > 0),
+        ("is_weekend", lambda v: v > 0),
+    ]
+
+    # Sort by feature importance
+    sorted_checks = sorted(
+        checks,
+        key=lambda x: feature_importances.get(x[0], 0),
+        reverse=True,
+    )
+
+    for fname, condition in sorted_checks:
+        if fname in FEATURE_NAMES:
+            idx = FEATURE_NAMES.index(fname)
+            if condition(features[idx]):
+                label = RISK_LABELS.get(fname, fname)
+                if label not in risks:
+                    risks.append(label)
+        if len(risks) >= top_k:
+            break
+
+    return risks

metadata.json

@@ -0,0 +1,69 @@
+{
+  "optimal_threshold": 0.293748559646689,
+  "feature_names": [
+    "pressure_mb",
+    "pressure_change_24h",
+    "pressure_volatility",
+    "humidity_pct",
+    "temperature_c",
+    "is_pressure_drop",
+    "sleep_total_hours",
+    "deep_sleep_min",
+    "rem_sleep_min",
+    "resting_hr",
+    "hrv_avg_ms",
+    "workout_min",
+    "menstrual_flow_flag",
+    "had_headache_1d",
+    "severity_1d",
+    "duration_1d",
+    "mood_1d",
+    "symptom_count_1d",
+    "trigger_count_1d",
+    "had_headache_2d",
+    "severity_2d",
+    "duration_2d",
+    "dow_sin",
+    "dow_cos",
+    "month_sin",
+    "month_cos",
+    "doy_sin",
+    "doy_cos",
+    "is_weekend",
+    "age_midpoint",
+    "is_europe",
+    "is_tropical",
+    "sleep_x_pressure",
+    "low_hrv_flag",
+    "sleep_deficit",
+    "high_humidity_flag",
+    "headache_streak_2d",
+    "consecutive_headache_days"
+  ],
+  "num_features": 38,
+  "model_version": "3.0.0",
+  "trained_at": "2026-03-12T10:47:40.844379",
+  "test_metrics": {
+    "roc_auc": 0.6859,
+    "pr_auc": 0.5669,
+    "f1": 0.5593
+  },
+  "training_rows": 150480,
+  "feature_importances": {
+    "had_headache_1d": 0.039352,
+    "pressure_change_24h": 0.008701,
+    "consecutive_headache_days": 0.007257,
+    "hrv_avg_ms": 0.004118,
+    "headache_streak_2d": 0.003967,
+    "duration_2d": 0.003535,
+    "duration_1d": 0.002007,
+    "humidity_pct": 0.001802,
+    "menstrual_flow_flag": 0.001657,
+    "temperature_c": 0.001522,
+    "resting_hr": 0.000438,
+    "had_headache_2d": 0.000436,
+    "rem_sleep_min": 0.000399,
+    "pressure_mb": 0.000374,
+    "pressure_volatility": 0.000369
+  }
+}

model.pkl

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e7d510635513fbf1390206d5631523655d18c49c127bd9c91a893c0eddf29a3d
+size 10437799

models.py

@@ -0,0 +1,133 @@
+"""
+Pydantic models — exact mirrors of Phoebe iOS Swift DTOs.
+
+Field names = snake_case matching CodingKeys from:
+  - APIModels.swift (HeadacheLogSnapshotDTO, DailySnapshotDTO)
+  - InsightPayloadDTO.swift (HealthKitMetricsDTO, WeatherDataDTO, UserContextDTO)
+"""
+
+from __future__ import annotations
+from pydantic import BaseModel, Field
+from typing import List, Optional
+from enum import Enum
+
+
+# ── Enums ────────────────────────────────────────────────────────────
+
+class MedicationResponseEnum(str, Enum):
+    horrible = "horrible"
+    worse = "worse"
+    same = "same"
+    better = "better"
+    excellent = "excellent"
+
+
+# ── Diary sub-payloads ───────────────────────────────────────────────
+
+class SymptomsPayload(BaseModel):
+    symptoms: List[str] = []
+
+class TriggersPayload(BaseModel):
+    triggers: List[str] = []
+
+class MedicationPayload(BaseModel):
+    medication_taken: List[str] = []
+
+class TherapeuticPayload(BaseModel):
+    therapeutic_activities: List[str] = []
+
+
+# ── HealthKit (from InsightPayloadDTO.swift) ─────────────────────────
+
+class SleepAnalysisDTO(BaseModel):
+    total_duration_hours: Optional[float] = None
+    deep_sleep_minutes: Optional[float] = None
+    rem_sleep_minutes: Optional[float] = None
+
+class HRVSummaryDTO(BaseModel):
+    average_ms: Optional[float] = None
+
+class HealthKitMetricsDTO(BaseModel):
+    resting_heart_rate: Optional[float] = None
+    sleep_analysis: Optional[SleepAnalysisDTO] = None
+    hrv_summary: Optional[HRVSummaryDTO] = None
+    workout_minutes: Optional[int] = None
+    had_menstrual_flow: Optional[bool] = None
+
+
+# ── Weather (from InsightPayloadDTO.swift) ───────────────────────────
+
+class WeatherDataDTO(BaseModel):
+    barometric_pressure_mb: float = 1013.25
+    pressure_change_24h_mb: float = 0.0
+    humidity_percent: float = 50.0
+    temperature_celsius: float = 15.0
+
+
+# ── Headache log (from APIModels.swift) ──────────────────────────────
+
+class HeadacheLogSnapshotDTO(BaseModel):
+    severity: int = 0
+    duration_hours: float = 0.0
+    symptoms: SymptomsPayload = Field(default_factory=SymptomsPayload)
+    triggers: TriggersPayload = Field(default_factory=TriggersPayload)
+    notes: Optional[str] = None
+    input_date: str = ""
+    input_time: Optional[str] = None
+    end_date: Optional[str] = None
+    end_time: Optional[str] = None
+    pain_frontal: bool = False
+    pain_temporal_left: bool = False
+    pain_temporal_right: bool = False
+    pain_occipital: bool = False
+    pain_parietal: bool = False
+    pain_ocular_left: bool = False
+    pain_ocular_right: bool = False
+    pain_sinus: bool = False
+    mood: Optional[str] = None
+    medication_taken: Optional[MedicationPayload] = None
+    medication_response: Optional[MedicationResponseEnum] = None
+    therapeutic_activities: Optional[TherapeuticPayload] = None
+
+
+# ── DailySnapshotDTO (top-level) ────────────────────────────────────
+
+class DailySnapshotDTO(BaseModel):
+    headache_log: Optional[HeadacheLogSnapshotDTO] = None
+    health_kit_metrics: Optional[HealthKitMetricsDTO] = None
+    weather_data: Optional[WeatherDataDTO] = None
+
+
+# ── UserContextDTO ──────────────────────────────────────────────────
+
+class UserContextDTO(BaseModel):
+    age_range: Optional[str] = None
+    location_region: Optional[str] = None
+
+
+# ── API request / response ──────────────────────────────────────────
+
+class PredictionRequest(BaseModel):
+    user_context: Optional[UserContextDTO] = None
+    daily_snapshots: List[DailySnapshotDTO]
+
+class DayPrediction(BaseModel):
+    day: int
+    date: Optional[str] = None
+    prediction: int
+    probability: float
+    risk_level: str
+    top_risk_factors: List[str] = []
+
+class PredictionResponse(BaseModel):
+    predictions: List[DayPrediction]
+    model_version: str
+    threshold: float
+
+# Legacy
+class SinglePredictionRequest(BaseModel):
+    features: List[float]
+
+class SinglePredictionResponse(BaseModel):
+    prediction: int
+    probability: float

requirements.txt

@@ -0,0 +1,6 @@
+fastapi>=0.104.0
+uvicorn[standard]>=0.24.0
+pydantic>=2.5.0
+numpy>=1.24.0
+scikit-learn>=1.3.0
+huggingface_hub>=0.19.0

run_training.py

@@ -0,0 +1,624 @@
+"""
+═══════════════════════════════════════════════════════════════════════════
+  PHOEBE HEADACHE PREDICTOR v3.0 — Production Training Pipeline
+  EmpedocLabs © 2025
+═══════════════════════════════════════════════════════════════════════════
+
+Clinical-grade synthetic data with user archetypes:
+  - Chronic migraineur (high baseline, medication dependent)
+  - Episodic tension-type (stress/sleep driven)
+  - Menstrual migraine (hormonal cycle dominant)
+  - Weather-sensitive (barometric pressure dominant)
+  - Mixed/general (moderate baseline)
+
+Leak-free: predicts day T headache using day T weather + day T-1 health/diary.
+
+38 features matching the iOS DailySnapshotDTO:
+  WeatherKit forecast  (6)  — pressure, Δp, |Δp|, humidity, temp, drop flag
+  HealthKit yesterday  (7)  — sleep h/deep/rem, rhr, hrv, workout, menstrual
+  Diary yesterday      (6)  — headache, severity, duration, mood, #symptoms, #triggers
+  Diary 2-days-ago     (3)  — headache, severity, duration
+  Temporal             (7)  — dow sin/cos, month sin/cos, doy sin/cos, weekend
+  User context         (3)  — age, is_europe, is_tropical
+  Interactions         (6)  — sleep×pressure, low_hrv, sleep_deficit,
+                               high_humidity, streak_2d, consecutive_days
+"""
+
+import os, sys, math, random, pickle, json, warnings
+import numpy as np
+import pandas as pd
+from datetime import datetime, timedelta
+from sklearn.model_selection import GroupShuffleSplit
+from sklearn.ensemble import HistGradientBoostingClassifier
+from sklearn.calibration import CalibratedClassifierCV
+from sklearn.metrics import (
+    classification_report, roc_auc_score, f1_score,
+    precision_recall_curve, average_precision_score, confusion_matrix,
+)
+
+warnings.filterwarnings("ignore")
+
+# ═══════════════════════════════════════════════════════════════════════
+# FEATURE SCHEMA
+# ═══════════════════════════════════════════════════════════════════════
+
+FEATURE_NAMES = [
+    "pressure_mb", "pressure_change_24h", "pressure_volatility",
+    "humidity_pct", "temperature_c", "is_pressure_drop",
+    "sleep_total_hours", "deep_sleep_min", "rem_sleep_min",
+    "resting_hr", "hrv_avg_ms", "workout_min", "menstrual_flow_flag",
+    "had_headache_1d", "severity_1d", "duration_1d",
+    "mood_1d", "symptom_count_1d", "trigger_count_1d",
+    "had_headache_2d", "severity_2d", "duration_2d",
+    "dow_sin", "dow_cos", "month_sin", "month_cos",
+    "doy_sin", "doy_cos", "is_weekend",
+    "age_midpoint", "is_europe", "is_tropical",
+    "sleep_x_pressure", "low_hrv_flag", "sleep_deficit",
+    "high_humidity_flag", "headache_streak_2d", "consecutive_headache_days",
+]
+NUM_FEATURES = len(FEATURE_NAMES)  # 38
+
+# ═══════════════════════════════════════════════════════════════════════
+# USER ARCHETYPES (based on migraine clinical literature)
+# ═══════════════════════════════════════════════════════════════════════
+
+ARCHETYPES = {
+    "chronic_migraine": {
+        "weight": 0.20,
+        "base_rate": 0.40,     # ~12 headache days/month
+        "sensitivity": 0.3,
+        "pressure_coeff": 0.5,
+        "sleep_coeff": 0.6,
+        "hrv_coeff": 0.3,
+        "menstrual_coeff": 0.4,
+        "humidity_coeff": 0.2,
+        "rebound_coeff": 0.7,  # strong rebound/cluster effect
+        "weekend_coeff": 0.1,
+        "temp_coeff": 0.15,
+    },
+    "episodic_tension": {
+        "weight": 0.25,
+        "base_rate": 0.12,
+        "sensitivity": 0.0,
+        "pressure_coeff": 0.2,
+        "sleep_coeff": 0.9,    # very sleep-dependent
+        "hrv_coeff": 0.7,      # very stress-dependent
+        "menstrual_coeff": 0.1,
+        "humidity_coeff": 0.1,
+        "rebound_coeff": 0.2,
+        "weekend_coeff": 0.25,  # "weekend headache" pattern
+        "temp_coeff": 0.1,
+    },
+    "menstrual_migraine": {
+        "weight": 0.20,
+        "base_rate": 0.15,
+        "sensitivity": 0.1,
+        "pressure_coeff": 0.3,
+        "sleep_coeff": 0.4,
+        "hrv_coeff": 0.3,
+        "menstrual_coeff": 1.2,  # dominant factor
+        "humidity_coeff": 0.15,
+        "rebound_coeff": 0.4,
+        "weekend_coeff": 0.05,
+        "temp_coeff": 0.1,
+    },
+    "weather_sensitive": {
+        "weight": 0.15,
+        "base_rate": 0.15,
+        "sensitivity": 0.1,
+        "pressure_coeff": 1.0,  # dominant factor
+        "sleep_coeff": 0.3,
+        "hrv_coeff": 0.2,
+        "menstrual_coeff": 0.2,
+        "humidity_coeff": 0.6,  # also weather
+        "rebound_coeff": 0.3,
+        "weekend_coeff": 0.05,
+        "temp_coeff": 0.4,     # temperature sensitive too
+    },
+    "mixed_general": {
+        "weight": 0.20,
+        "base_rate": 0.18,
+        "sensitivity": 0.0,
+        "pressure_coeff": 0.4,
+        "sleep_coeff": 0.5,
+        "hrv_coeff": 0.4,
+        "menstrual_coeff": 0.3,
+        "humidity_coeff": 0.2,
+        "rebound_coeff": 0.35,
+        "weekend_coeff": 0.12,
+        "temp_coeff": 0.15,
+    },
+}
+
+
+def _logistic(x):
+    return 1.0 / (1.0 + math.exp(-max(-20, min(20, x))))
+
+
+def _cyclic(val, period):
+    a = 2 * math.pi * val / period
+    return math.sin(a), math.cos(a)
+
+
+# ═══════════════════════════════════════════════════════════════════════
+# USER CLASS
+# ═══════════════════════════════════════════════════════════════════════
+
+class User:
+    def __init__(self, uid):
+        self.uid = uid
+
+        # Pick archetype by weights
+        names = list(ARCHETYPES.keys())
+        weights = [ARCHETYPES[n]["weight"] for n in names]
+        self.archetype_name = random.choices(names, weights=weights)[0]
+        self.arch = ARCHETYPES[self.archetype_name]
+
+        age_lo = random.choice([18, 20, 25, 30, 35, 40, 45, 50, 55, 60])
+        self.age_mid = age_lo + 4.5
+        self.region = random.choices(
+            ["europe", "americas", "asia", "tropical"],
+            weights=[40, 30, 20, 10],
+        )[0]
+
+        # Menstrual migraine archetype → always female
+        if self.archetype_name == "menstrual_migraine":
+            self.is_female = True
+        else:
+            self.is_female = random.random() < 0.65
+
+        # Personal baselines with variance
+        self.base_hr = random.gauss(65, 8)
+        self.base_hrv = random.gauss(45, 15)
+        self.base_sleep = random.gauss(7.0, 0.8)
+        self.personal_noise = random.gauss(0, 0.2)
+
+        # Cycle params
+        self.cycle_len = random.randint(26, 32) if self.is_female else 0
+        self.cycle_off = random.randint(0, 30)
+
+
+# ═══════════════════════════════════════════════════════════════════════
+# DATA GENERATION — per user
+# ═══════════════════════════════════════════════════════════════════════
+
+def generate_user(user: User, n_days: int, start: datetime):
+    """Generate n_days of raw data, return leak-free (features, labels)."""
+    a = user.arch
+
+    # Weather random walk
+    pressure = random.gauss(1013.25, 8)
+    temp = random.gauss(15, 10)
+    humidity = random.gauss(60, 15)
+
+    raw = []
+
+    for d in range(n_days):
+        dt = start + timedelta(days=d)
+        month = dt.month
+
+        # ── Weather with realistic autocorrelation ───────────────────
+        seasonal_t = 15 + 14 * math.sin(2 * math.pi * (month - 4) / 12)
+        seasonal_h = 55 + 20 * math.sin(2 * math.pi * (month - 7) / 12)
+
+        # Pressure: occasional fronts (sudden drops)
+        if random.random() < 0.08:  # ~3x/month cold front
+            p_change = random.gauss(-8, 3)
+        elif random.random() < 0.05:  # occasional rapid rise
+            p_change = random.gauss(6, 2)
+        else:
+            p_change = random.gauss(0, 2.5) + 0.12 * (1013.25 - pressure)
+        pressure += p_change
+        pressure = max(970, min(1050, pressure))
+
+        temp += random.gauss(0, 1.8) + 0.15 * (seasonal_t - temp)
+        humidity += random.gauss(0, 4) + 0.08 * (seasonal_h - humidity)
+        humidity = max(15, min(98, humidity))
+
+        # ── HealthKit ────────────────────────────────────────────────
+        # Sleep varies: weekends slightly longer, bad days shorter
+        base_s = user.base_sleep + (0.5 if dt.weekday() >= 5 else 0)
+        sleep_h = max(2.5, random.gauss(base_s, 1.0))
+
+        # If had headache yesterday → worse sleep tonight
+        if d > 0 and raw[d-1]["headache"]:
+            sleep_h = max(2.5, sleep_h - random.gauss(0.8, 0.5))
+
+        deep = max(0, random.gauss(75 + sleep_h * 3, 18))
+        rem = max(0, random.gauss(80 + sleep_h * 5, 22))
+
+        rhr = max(45, random.gauss(user.base_hr, 4))
+        # HRV: stress lowers it, good sleep raises it
+        hrv_base = user.base_hrv + (sleep_h - 7) * 3
+        hrv = max(8, random.gauss(hrv_base, 8))
+
+        workout = max(0, int(random.gauss(25, 18)))
+        # Less workout on headache days
+        if d > 0 and raw[d-1]["headache"]:
+            workout = max(0, workout - 15)
+
+        cycle_day = 0
+        menstrual = False
+        if user.is_female and user.cycle_len > 0:
+            cycle_day = ((d + user.cycle_off) % user.cycle_len) + 1
+            menstrual = cycle_day <= 4
+
+        # ── Headache probability ─────────────────────────────────────
+        base_rate = a["base_rate"]
+        lo = math.log(base_rate / (1 - base_rate))
+        lo += user.personal_noise
+
+        # Barometric pressure: graded response
+        if p_change < -8:
+            lo += a["pressure_coeff"] * 1.2
+        elif p_change < -5:
+            lo += a["pressure_coeff"] * 0.8
+        elif p_change < -3:
+            lo += a["pressure_coeff"] * 0.4
+        elif p_change > 8:
+            lo += a["pressure_coeff"] * 0.5  # rapid rise also triggers
+
+        # Sleep: graded response
+        if sleep_h < 4:
+            lo += a["sleep_coeff"] * 1.2
+        elif sleep_h < 5:
+            lo += a["sleep_coeff"] * 0.8
+        elif sleep_h < 6:
+            lo += a["sleep_coeff"] * 0.4
+        elif sleep_h > 9:
+            lo += a["sleep_coeff"] * 0.3  # oversleep trigger
+
+        # HRV (stress proxy): graded
+        if hrv < 20:
+            lo += a["hrv_coeff"] * 1.0
+        elif hrv < 30:
+            lo += a["hrv_coeff"] * 0.6
+        elif hrv < 35:
+            lo += a["hrv_coeff"] * 0.2
+
+        # Menstrual: perimenstrual window (days 1-3, 26-28)
+        if user.is_female and user.cycle_len > 0:
+            if cycle_day <= 3:
+                lo += a["menstrual_coeff"] * 1.0
+            elif cycle_day <= 5:
+                lo += a["menstrual_coeff"] * 0.4
+            elif cycle_day >= user.cycle_len - 2:
+                lo += a["menstrual_coeff"] * 0.7  # premenstrual
+
+        # Humidity
+        if humidity > 85:
+            lo += a["humidity_coeff"] * 0.8
+        elif humidity > 75:
+            lo += a["humidity_coeff"] * 0.3
+
+        # Temperature extremes
+        if temp > 32 or temp < -8:
+            lo += a["temp_coeff"] * 0.8
+        elif temp > 28 or temp < -3:
+            lo += a["temp_coeff"] * 0.3
+
+        # Rebound / cluster effect
+        if d > 0 and raw[d-1]["headache"]:
+            lo += a["rebound_coeff"] * 0.6
+            if d > 1 and raw[d-2]["headache"]:
+                lo += a["rebound_coeff"] * 0.3  # 2-day streak
+
+        # Weekend "let-down" headache
+        if dt.weekday() == 5:  # Saturday
+            lo += a["weekend_coeff"]
+        elif dt.weekday() == 6:
+            lo += a["weekend_coeff"] * 0.6
+
+        # Small random noise (less than before — let signal dominate)
+        lo += random.gauss(0, 0.15)
+
+        prob = _logistic(lo)
+        headache = random.random() < prob
+
+        # ── Diary details ────────────────────────────────────────────
+        if headache:
+            severity = random.choices([1,2,3,4,5], weights=[8,22,38,22,10])[0]
+            duration = round(max(0.5, random.gauss(2.5 + severity * 1.0, 1.5)), 1)
+            n_symp = random.randint(1, min(5, 1 + severity))
+            n_trig = random.randint(0, min(4, severity))
+            mood = random.choices([1,2,3,4,5], weights=[30,35,25,8,2])[0]
+        else:
+            severity, duration, n_symp, n_trig = 0, 0.0, 0, 0
+            mood = random.choices([1,2,3,4,5], weights=[3,8,25,38,26])[0]
+
+        raw.append({
+            "dt": dt, "pressure": pressure, "p_change": p_change,
+            "humidity": humidity, "temp": temp,
+            "sleep_h": round(sleep_h, 1), "deep": round(deep, 0),
+            "rem": round(rem, 0), "rhr": round(rhr, 0),
+            "hrv": round(hrv, 1), "workout": workout,
+            "menstrual": menstrual,
+            "headache": headache, "severity": severity,
+            "duration": duration, "mood": mood,
+            "n_symp": n_symp, "n_trig": n_trig,
+        })
+
+    # ── Build feature vectors (leak-free) ────────────────────────────
+    rows, labels = [], []
+    consec = 0
+
+    for i in range(2, n_days):
+        t = raw[i]       # target day
+        y = raw[i - 1]   # yesterday
+        p = raw[i - 2]   # 2 days ago
+        dt = t["dt"]
+        f = []
+
+        # Weather target (6)
+        f.append(t["pressure"])
+        f.append(t["p_change"])
+        f.append(abs(t["p_change"]))
+        f.append(t["humidity"])
+        f.append(t["temp"])
+        f.append(1.0 if t["p_change"] < -5 else 0.0)
+
+        # HealthKit yesterday (7)
+        f.append(y["sleep_h"])
+        f.append(y["deep"])
+        f.append(y["rem"])
+        f.append(y["rhr"])
+        f.append(y["hrv"])
+        f.append(float(y["workout"]))
+        f.append(1.0 if y["menstrual"] else 0.0)
+
+        # Diary yesterday (6)
+        f.append(1.0 if y["headache"] else 0.0)
+        f.append(float(y["severity"]))
+        f.append(float(y["duration"]))
+        f.append(float(y["mood"]))
+        f.append(float(y["n_symp"]))
+        f.append(float(y["n_trig"]))
+
+        # Diary 2d ago (3)
+        f.append(1.0 if p["headache"] else 0.0)
+        f.append(float(p["severity"]))
+        f.append(float(p["duration"]))
+
+        # Temporal (7)
+        dw_s, dw_c = _cyclic(dt.weekday(), 7)
+        mn_s, mn_c = _cyclic(dt.month - 1, 12)
+        dy_s, dy_c = _cyclic(dt.timetuple().tm_yday, 365)
+        f.extend([dw_s, dw_c, mn_s, mn_c, dy_s, dy_c])
+        f.append(1.0 if dt.weekday() >= 5 else 0.0)
+
+        # User context (3)
+        f.append(user.age_mid)
+        f.append(1.0 if "europe" in user.region else 0.0)
+        f.append(1.0 if "tropical" in user.region else 0.0)
+
+        # Interactions (6)
+        f.append(y["sleep_h"] * abs(t["p_change"]))
+        f.append(1.0 if y["hrv"] < 25 else 0.0)
+        f.append(max(0.0, 6.0 - y["sleep_h"]))
+        f.append(1.0 if t["humidity"] > 80 else 0.0)
+        streak = (1.0 if y["headache"] else 0.0) + (1.0 if p["headache"] else 0.0)
+        f.append(streak)
+        consec = (consec + 1) if y["headache"] else 0
+        f.append(float(min(consec, 7)))
+
+        rows.append(f)
+        labels.append(1 if t["headache"] else 0)
+
+    return np.array(rows, dtype=np.float32), np.array(labels, dtype=np.int32)
+
+
+# ═══════════════════════════════════════════════════════════════════════
+# DATASET ASSEMBLY
+# ═══════════════════════════════════════════════════════════════════════
+
+def generate_dataset(n_users=2000, days=365, seed=42):
+    random.seed(seed)
+    np.random.seed(seed)
+
+    all_X, all_y, all_uid, all_arch = [], [], [], []
+    start = datetime(2023, 6, 1)
+
+    arch_counts = {}
+
+    for uid in range(n_users):
+        user = User(uid)
+        arch_counts[user.archetype_name] = arch_counts.get(user.archetype_name, 0) + 1
+        X_u, y_u = generate_user(user, days, start)
+        all_X.append(X_u)
+        all_y.append(y_u)
+        all_uid.extend([uid] * len(y_u))
+        all_arch.extend([user.archetype_name] * len(y_u))
+        if (uid + 1) % 200 == 0:
+            print(f"  {uid + 1}/{n_users} users generated")
+
+    X = np.vstack(all_X)
+    y = np.concatenate(all_y)
+
+    df = pd.DataFrame(X, columns=FEATURE_NAMES)
+    df["headache"] = y
+    df["user_id"] = all_uid
+    df["archetype"] = all_arch
+
+    print(f"\n✅ Dataset: {df.shape[0]:,} rows × {NUM_FEATURES} features")
+    print(f"   Headache rate: {y.mean():.1%}")
+    print(f"   Archetypes: {arch_counts}")
+    return df
+
+
+# ═══════════════════════════════════════════════════════════════════════
+# TRAINING
+# ═══════════════════════════════════════════════════════════════════════
+
+def group_split(df, test_f=0.12, val_f=0.12, seed=42):
+    gss = GroupShuffleSplit(n_splits=1, test_size=test_f, random_state=seed)
+    i_tv, i_te = next(gss.split(df, groups=df["user_id"]))
+    df_tv, df_test = df.iloc[i_tv], df.iloc[i_te]
+    rel_val = val_f / (1 - test_f)
+    gss2 = GroupShuffleSplit(n_splits=1, test_size=rel_val, random_state=seed)
+    i_tr, i_v = next(gss2.split(df_tv, groups=df_tv["user_id"]))
+    return df_tv.iloc[i_tr], df_tv.iloc[i_v], df_test
+
+
+def tune_threshold(y_true, y_prob):
+    prec, rec, thr = precision_recall_curve(y_true, y_prob)
+    f1 = 2 * prec * rec / (prec + rec + 1e-8)
+    best = np.argmax(f1)
+    return float(thr[min(best, len(thr)-1)]), float(f1[best])
+
+
+def evaluate(y_true, y_prob, thr, label):
+    y_pred = (y_prob >= thr).astype(int)
+    print(f"\n{'═'*60}")
+    print(f"  {label}  (threshold={thr:.3f})")
+    print(f"{'═'*60}")
+    print(classification_report(y_true, y_pred,
+          target_names=["No headache", "Headache"], zero_division=0))
+    auc = roc_auc_score(y_true, y_prob)
+    ap = average_precision_score(y_true, y_prob)
+    f1 = f1_score(y_true, y_pred, zero_division=0)
+    cm = confusion_matrix(y_true, y_pred)
+    print(f"  ROC-AUC : {auc:.4f}")
+    print(f"  PR-AUC  : {ap:.4f}")
+    print(f"  F1      : {f1:.4f}")
+    print(f"  Confusion:\n{cm}")
+    return {"roc_auc": round(auc,4), "pr_auc": round(ap,4), "f1": round(f1,4)}
+
+
+def main():
+    print("=" * 62)
+    print("  PHOEBE HEADACHE PREDICTOR v3.0 — Production Training")
+    print("  EmpedocLabs | Beta Release Build")
+    print("=" * 62)
+
+    # ── Generate ─────────────────────────────────────────────────────
+    print("\n📊 Generating clinical-grade synthetic data (2000 users × 365 days)...")
+    df = generate_dataset(n_users=2000, days=365, seed=42)
+
+    # ── Split ────────────────────────────────────────────────────────
+    df_train, df_val, df_test = group_split(df)
+    print(f"\n📂 Split: Train={len(df_train):,}  Val={len(df_val):,}  Test={len(df_test):,}")
+
+    X_tr = df_train[FEATURE_NAMES].values.astype(np.float32)
+    y_tr = df_train["headache"].values.astype(np.int32)
+    X_va = df_val[FEATURE_NAMES].values.astype(np.float32)
+    y_va = df_val["headache"].values.astype(np.int32)
+    X_te = df_test[FEATURE_NAMES].values.astype(np.float32)
+    y_te = df_test["headache"].values.astype(np.int32)
+
+    neg, pos = np.bincount(y_tr)
+    print(f"   Class: neg={neg:,}  pos={pos:,}  ratio={neg/pos:.2f}")
+
+    # ── Train ────────────────────────────────────────────────────────
+    print("\n🚀 Training HistGradientBoosting (production config)...")
+    model = HistGradientBoostingClassifier(
+        max_iter=800,
+        max_depth=6,
+        learning_rate=0.03,
+        min_samples_leaf=25,
+        max_leaf_nodes=48,
+        l2_regularization=0.8,
+        max_features=0.85,
+        early_stopping=True,
+        validation_fraction=0.08,
+        n_iter_no_change=50,
+        scoring="loss",
+        class_weight="balanced",
+        random_state=42,
+    )
+    model.fit(X_tr, y_tr)
+    print(f"   Iterations: {model.n_iter_}")
+
+    # ── Calibrate ────────────────────────────────────────────────────
+    print("\n📐 Probability calibration (isotonic, 5-fold)...")
+    calibrated = CalibratedClassifierCV(model, method="isotonic", cv=5)
+    calibrated.fit(X_tr, y_tr)
+
+    # ── Threshold ────────────────────────────────────────────────────
+    vp = calibrated.predict_proba(X_va)[:, 1]
+    opt_thr, vf1 = tune_threshold(y_va, vp)
+    print(f"\n🎯 Optimal threshold: {opt_thr:.3f}  (val F1={vf1:.4f})")
+
+    # ── Evaluate ─────────────────────────────────────────────────────
+    val_m = evaluate(y_va, vp, opt_thr, "VALIDATION")
+    tp = calibrated.predict_proba(X_te)[:, 1]
+    test_m = evaluate(y_te, tp, opt_thr, "TEST")
+
+    # ── Per-archetype eval ───────────────────────────────────────────
+    print(f"\n📊 Per-archetype performance:")
+    for arch in ARCHETYPES:
+        mask = df_test["archetype"] == arch
+        if mask.sum() < 50:
+            continue
+        a_y = y_te[mask.values]
+        a_p = tp[mask.values]
+        try:
+            a_auc = roc_auc_score(a_y, a_p)
+            a_f1 = f1_score(a_y, (a_p >= opt_thr).astype(int), zero_division=0)
+            rate = a_y.mean()
+            print(f"   {arch:25s}  n={mask.sum():6,}  rate={rate:.1%}  AUC={a_auc:.3f}  F1={a_f1:.3f}")
+        except:
+            pass
+
+    # ── Feature importance ───────────────────────────────────────────
+    print(f"\n📊 Permutation feature importance...")
+    base_auc = roc_auc_score(y_te, tp)
+    imps = np.zeros(NUM_FEATURES)
+    rng = np.random.RandomState(42)
+    for fi in range(NUM_FEATURES):
+        Xp = X_te.copy()
+        Xp[:, fi] = rng.permutation(Xp[:, fi])
+        pp = calibrated.predict_proba(Xp)[:, 1]
+        imps[fi] = base_auc - roc_auc_score(y_te, pp)
+
+    top_idx = np.argsort(imps)[-15:][::-1]
+    print(f"\n   Top features:")
+    mx = max(imps.max(), 1e-6)
+    for r, i in enumerate(top_idx, 1):
+        bar = "█" * max(1, int(imps[i] / mx * 35)) if imps[i] > 0 else "·"
+        print(f"   {r:2d}. {FEATURE_NAMES[i]:30s} ΔAUC={imps[i]:+.4f}  {bar}")
+
+    # ── Save ─────────────────────────────────────────────────────────
+    os.makedirs("model", exist_ok=True)
+
+    model_data = {
+        "model": calibrated,
+        "raw_model": model,
+        "optimal_threshold": opt_thr,
+        "feature_names": FEATURE_NAMES,
+        "num_features": NUM_FEATURES,
+        "model_version": "3.0.0",
+        "trained_at": datetime.now().isoformat(),
+        "test_metrics": test_m,
+        "val_metrics": val_m,
+        "training_rows": len(df_train),
+        "total_users": 2000,
+        "feature_importances": {
+            FEATURE_NAMES[i]: round(float(imps[i]), 6)
+            for i in top_idx if imps[i] > 0
+        },
+    }
+
+    with open("model/model.pkl", "wb") as f:
+        pickle.dump(model_data, f)
+    sz = os.path.getsize("model/model.pkl") / 1024
+    print(f"\n💾 model/model.pkl  ({sz:.0f} KB)")
+
+    meta = {k: v for k, v in model_data.items() if k not in ("model", "raw_model")}
+    with open("model/metadata.json", "w") as f:
+        json.dump(meta, f, indent=2, default=str)
+    print(f"📋 model/metadata.json")
+
+    os.makedirs("data", exist_ok=True)
+    df.to_parquet("data/training_data.parquet", index=False)
+    print(f"📁 data/training_data.parquet")
+
+    print(f"\n{'═'*62}")
+    print(f"  ✅ PRODUCTION MODEL READY — v3.0.0")
+    print(f"  Test ROC-AUC: {test_m['roc_auc']}")
+    print(f"  Test F1:      {test_m['f1']}")
+    print(f"  Threshold:    {opt_thr:.3f}")
+    print(f"{'═'*62}")
+
+
+if __name__ == "__main__":
+    main()