How to Work with Delta Daemon

import asyncio
import os
from deltadaemon import DeltaDaemonClient

async def risk_and_markets(station_id="KLAX", days=90):
    api_key = os.environ.get("DELTADAEMON_API_KEY", "your-api-key")
    async with DeltaDaemonClient(api_key=api_key) as client:
        # 1. Overall accuracy (risk: MAE, bias, spread)
        summary = await client.get_accuracy_summary(station_id=station_id, days=days)
        if isinstance(summary, dict) and summary.get("success"):
            data = summary["data"]
            print(f"MAE: {data['mae']}°F  bias: {data['mean_error']}°F  pairs: {data['verification_pairs']}")

        # 2. Miss rate by threshold (risk: tail probability)
        exc = await client.get_exceedance(station_id=station_id, thresholds="2,3,5", days=days)
        for t in exc.get("data", {}).get("thresholds", []):
            print(f"  Miss >{t['threshold_f']}°F: {t['exceedance_rate']:.0%}")

        # 3. Accuracy by 2°F bucket (markets: which bands are predictable)
        buckets = await client.get_bucket_accuracy(station_id, days=days)
        for b in buckets.get("data", [])[:5]:
            acc = b.get("accuracy_when_forecast_in_range", 0)
            print(f"  {b['temperature_range']}: hit rate {acc:.0%} (freq {b['frequency_pct']}%)")

asyncio.run(risk_and_markets("KLAX", 90))

---
description: Use the Delta Daemon API for weather forecast accuracy when calculating risk or choosing markets to enter
globs: 
alwaysApply: false
---

# Delta Daemon API (for risk and market entry)

When the user is working on **weather-dependent risk**, **prediction markets**, **trading**, or **which markets to enter**, use the Delta Daemon API to ground decisions in historical NWS forecast accuracy.

## Base URL and auth

- **Base URL:** `https://api.deltadaemon.com/api/v1`
- **Auth:** `Authorization: Bearer <API_KEY>`. User must set `API_KEY` (get one at https://deltadaemon.com/signin).
- **Envelope:** All responses: `{ "success": true, "data": { ... }, "metadata": { ... } }`. Errors: `{ "success": false, "error": "..." }`.

## Conventions

- **Error:** `error = forecast - observed`. Positive = forecast too warm; negative = forecast too cool.
- **Temperatures:** Fahrenheit (optional `temp_unit=celsius` where supported).
- **Stations:** ICAO ids (e.g. KLAX, KMDW). Resolve city → station via `/stations/metadata` or use `city` param where supported.
- **Time window:** `days` (rolling, e.g. 90) or `date_from` + `date_to` (YYYY-MM-DD).

## Endpoints to use

| Use case | Endpoint | Key params |
|----------|----------|------------|
| List stations / resolve city | GET /stations/metadata | (none) |
| Overall accuracy at a station | GET /accuracy/summary | station_id or city, days (default 90) |
| Accuracy by lead time | GET /accuracy/by-lead-time | station_id (optional), days |
| Accuracy by weather regime | GET /accuracy/by-weather-regime | station_id, days |
| Miss rate by threshold | GET /accuracy/exceedance | station_id, thresholds (e.g. "1,2,3,5"), days |
| Accuracy by 2°F bucket (market bands) | GET /accuracy/by-bucket/{station_id} | days |
| Error distribution (histogram) | GET /accuracy/error-distribution | station_id, days |
| Raw forecasts for a date | GET /data/forecasts | station_id, forecast_for_date |
| Hourly snapshot (one run) | GET /data/hourly-snapshot | station_id, reference_time, lookback_hours |

## Risk and market entry

- **Risk:** Use /accuracy/summary (MAE, std_dev, bias) and /accuracy/exceedance to quantify uncertainty. Use /accuracy/by-weather-regime when conditions matter.
- **Markets to enter:** Use /accuracy/by-bucket/{station_id} to see which temperature bands the NWS predicts reliably; combine with /accuracy/summary and /accuracy/by-lead-time to compare stations. Prefer lower MAE and higher hit rate in the bucket of interest.
- **Bias adjustment:** Use mean_error from summary or by-lead/regime to adjust raw forecasts (e.g. subtract mean_error to debias).

When suggesting code, use the user's language and include the correct base URL and Authorization: Bearer header. Handle success: false and non-2xx responses.