README.md

---
title: Phoebe Bioweather API v2
emoji: 🌤️
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
license: mit
app_port: 7860
---

# 🌤️ Phoebe Bioweather API v2.0

**Weather-driven headache risk scoring** for the [Phoebe](https://empedoclabs.com) iOS app by **EmpedocLabs**.

## What It Does

Takes 7 weather parameters → returns a 0-100 risk score, one of 15 biometeo conditions, and personalized actionable advice with 3 severity tiers.

## Endpoints

| Method | Path | Description |
|---|---|---|
| `GET` | `/` | Status |
| `GET` | `/health` | Model health |
| `POST` | `/predict` | Risk score + condition + actions |

## Request

```json
{
  "temp_c": 28.5,
  "pressure_hpa": 1005.3,
  "humidity": 88,
  "wind_kph": 12,
  "uv_index": 7,
  "pressure_drop": -7.2,
  "temp_change": 3.5
}
```

## Response

```json
{
  "risk_score": 72,
  "risk_level": "High",
  "condition": {
    "id": 1,
    "title": "Rapid Pressure Drop",
    "emoji": "📉",
    "text": "A sharp pressure drop is one of today's main headache drivers...",
    "actions": [
      "Reduce stimulation for the next few hours...",
      "Lower sensory load: dim lights, shorter screen blocks...",
      "Keep hydration steady and avoid skipped meals."
    ]
  }
}
```

## 15 Biometeo Conditions

| ID | Condition | Primary Trigger |
|---|---|---|
| 0 | Clear Skies | No weather trigger |
| 1 | Rapid Pressure Drop | Barometric drop > 5 hPa |
| 2 | Pressure Squeeze | Barometric rise > 5 hPa |
| 3 | Sauna Effect | Heat + humidity |
| 4 | High Wind | Wind > 35 km/h |
| 5 | High UV Glare | UV index ≥ 7 |
| 6 | Bitter Cold | Temperature < 0°C |
| 7 | Drastic Temp Drop | 24h temp change < -7°C |
| 8 | Heat Shock | 24h temp change > +7°C |
| 9 | Heavy Dampness | Humidity > 88% + calm |
| 10 | Mild Barometric Dip | Pressure drop 2-5 hPa |
| 11 | Mild Pressure Squeeze | Pressure rise 2-5 hPa |
| 12 | Breezy Pollen Risk | Moderate wind + warm |
| 13 | Dry Air Warning | Humidity < 30% |
| 14 | Stagnant & Gloomy | Low UV + high humidity + calm |

## Model Details

- Risk regressor: HistGradientBoosting, MAE=2.52, R²=0.977
- Advice classifier: HistGradientBoosting, Accuracy=98.6%, F1=0.971
- Rule-based coherence layer ensures physically-impossible outputs never reach the user