docs/plan.md

Toto Weather Forecasting Demo — Plan

A public Hugging Face Space that pulls live data from a personal Ecowitt GW3000 weather station, runs Datadog's Toto 2.0 (smallest variant) to forecast the next 24h of temperature/humidity/pressure, and shows it next to the National Weather Service forecast.

Hook: "Language models predict the next token. What if you could predict the future with the same technology?"

Architecture (one file, one process)

Ecowitt Cloud API v3  ──┐
                        ├──►  app.py (Gradio Blocks)  ──►  HF Space (CPU basic)
NWS API /forecastHourly ┘            │
                                     ├─ Toto 2.0 small (HF Hub, ~4M params, CPU)
                                     ├─ Plotly figs (gr.Plot × 3)
                                     └─ TTL cache (1h) on fetches + inference

Repo layout

time-series-ai-weather-forecast/
├── app.py                     # Gradio entry point
├── requirements.txt
├── README.md                  # HF Space frontmatter + description
├── .env.example
├── .gitignore
├── docs/
│   └── plan.md                # this file
└── src/
    ├── ecowitt.py             # Ecowitt API client
    ├── nws.py                 # NWS forecast client
    ├── forecast.py            # Toto load + inference
    ├── plotting.py            # Plotly figure builders
    └── cache.py               # TTL cache decorator

Single app.py is also fine; splitting into src/ keeps each concern testable.

Build order

1. Ecowitt client (current focus) — fetch real-time + last 7 days history, return a clean hourly pandas.DataFrame with columns temp_f, humidity, pressure_inhg, indexed by UTC timestamp.
2. NWS client — /points/{lat},{lon} → forecastHourly URL → 24h hourly forecast aligned to Ecowitt's cadence.
3. Toto inference — load smallest Toto 2.0 from HF Hub, univariate forecast per metric, return median + p10 + p90 over a 24h horizon.
4. Plotting — one Plotly figure per metric: past actuals (solid), Toto median (dashed) + p10–p90 band (shaded), NWS forecast (dashed, distinct color), vertical "now" marker.
5. Gradio app — gr.Blocks, title + hook, "Refresh" button, three gr.Plot outputs. demo.load runs once on visit; cache prevents repeat inference.
6. Local smoke test — python app.py, verify all three plots render with real data.
7. Push to HF — set secrets in Space settings, watch build, verify public URL.

Ecowitt API v3 reference (verified URLs)

Base: https://api.ecowitt.net/api/v3

• GET /device/real_time — current snapshot. Params: application_key, api_key, mac, call_back=all.
• GET /device/history — historical data. Params: application_key, api_key, mac, start_date, end_date, cycle_type, call_back. Cycle types per Ecowitt's storage tiers: 5min (last 90 days), 30min (last year), 240min (last 2 years), auto. Date format and exact call_back values to be confirmed against the live API on first call.
• GET /device/info — sanity check that creds + MAC are valid.

For the demo we want hourly cadence over the last 7 days, so cycle_type=30min and we resample to 1h locally. (5min would also work; 30min is lighter.)

Secrets / config

Local .env (gitignored):

ECOWITT_APPLICATION_KEY=...
ECOWITT_API_KEY=...
ECOWITT_DEVICE_MAC=...
LAT=...
LON=...

On HF Space → Settings → Variables and Secrets:

• Secrets: ECOWITT_APPLICATION_KEY, ECOWITT_API_KEY
• Variables: ECOWITT_DEVICE_MAC, LAT, LON

Out of scope

• Multivariate Toto inference
• Fine-tuning
• Auth, rate limiting, monitoring
• Metrics beyond temp/humidity/pressure