Add NWS client, Toto forecast wrapper, and Gradio app

- src/nws.py: two-step /points → forecastHourly fetcher; returns a
UTC-indexed DataFrame with columns aligned to Ecowitt (temp_f, humidity).
- src/forecast.py: Toto 2.0 (4M) wrapper. Lazy-imports torch/toto2 so the
module is importable without those installed; loads on first call.
- src/plotting.py: per-metric Plotly figure (history + Toto p10/p50/p90
band + NWS overlay + 'now' marker).
- app.py: Gradio Blocks app — three metric plots, 1h TTL cache, refresh
button.
- requirements.txt: pin torch>=2.4.0 and toto-2 from the DataDog/toto repo.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

app.py

@@ -0,0 +1,122 @@
+"""Toto weather forecasting demo — Gradio app for HuggingFace Spaces.
+
+Pulls live data from an Ecowitt GW3000B home weather station, runs Datadog's
+Toto 2.0 (smallest, 4M params) to forecast the next 24h of temperature,
+humidity, and pressure, and shows it next to the National Weather Service
+forecast for the same window.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from datetime import datetime, timedelta, timezone
+
+import gradio as gr
+import pandas as pd
+
+from src import ecowitt, nws
+from src.forecast import forecast_series
+from src.plotting import metric_figure
+
+CACHE_TTL_SECONDS = 60 * 60  # 1 hour
+HISTORY_DAYS = 7
+HORIZON_HOURS = 24
+
+# Three metrics to forecast. Maps Ecowitt history column → plot config.
+METRICS = [
+    {"col": "temp_f",        "title": "Outdoor temperature",  "y": "°F",  "nws_col": "temp_f"},
+    {"col": "humidity",      "title": "Outdoor humidity",      "y": "%",   "nws_col": "humidity"},
+    {"col": "pressure_inhg", "title": "Barometric pressure",   "y": "inHg", "nws_col": None},
+]
+
+
+# --- tiny TTL cache (Gradio has no @st.cache_data equivalent) -------------
+_cache: dict[tuple, tuple[float, object]] = {}
+
+
+def cached(ttl: int):
+    def deco(fn):
+        def wrapper(*args, **kwargs):
+            key = (fn.__name__, args, tuple(sorted(kwargs.items())))
+            now = time.time()
+            hit = _cache.get(key)
+            if hit and now - hit[0] < ttl:
+                return hit[1]
+            out = fn(*args, **kwargs)
+            _cache[key] = (now, out)
+            return out
+        return wrapper
+    return deco
+
+
+# --- data fetchers ---------------------------------------------------------
+@cached(CACHE_TTL_SECONDS)
+def fetch_history() -> pd.DataFrame:
+    cfg = ecowitt.EcowittConfig.from_env()
+    end = datetime.now(timezone.utc).replace(tzinfo=None)
+    start = end - timedelta(days=HISTORY_DAYS)
+    raw = ecowitt.fetch_history(cfg, start, end, cycle_type="30min", call_back="outdoor,pressure")
+    return ecowitt.history_to_dataframe(raw, resample="1h")
+
+
+@cached(CACHE_TTL_SECONDS)
+def fetch_nws() -> pd.DataFrame:
+    lat = float(os.environ["LAT"])
+    lon = float(os.environ["LON"])
+    return nws.hourly_forecast_df(lat, lon, hours=HORIZON_HOURS)
+
+
+# --- main refresh ---------------------------------------------------------
+def refresh():
+    history = fetch_history()
+    nws_df = fetch_nws()
+    now = pd.Timestamp.now(tz="UTC").floor("h")
+
+    figs = []
+    for m in METRICS:
+        series = history[m["col"]].dropna()
+        toto = forecast_series(series, horizon=HORIZON_HOURS)
+        nws_series = (
+            nws_df[m["nws_col"]] if (m["nws_col"] and m["nws_col"] in nws_df.columns) else None
+        )
+        figs.append(
+            metric_figure(
+                history=series.tail(HISTORY_DAYS * 24),
+                toto=toto,
+                nws=nws_series,
+                title=m["title"],
+                y_label=m["y"],
+                now=now,
+            )
+        )
+    return figs[0], figs[1], figs[2]
+
+
+# --- UI -------------------------------------------------------------------
+HOOK = (
+    "**Language models predict the next token. "
+    "What if you could predict the future with the same technology?**"
+)
+SUBTITLE = (
+    "Live readings from my Ecowitt GW3000B + a 24h forecast from "
+    "[Datadog's Toto 2.0 (4M)](https://huggingface.co/Datadog/Toto-2.0-4m), "
+    "compared against the [NWS hourly forecast](https://www.weather.gov/documentation/services-web-api)."
+)
+
+with gr.Blocks(title="Toto Weather Forecast") as demo:
+    gr.Markdown("# Toto on my home weather station")
+    gr.Markdown(HOOK)
+    gr.Markdown(SUBTITLE)
+    refresh_btn = gr.Button("Refresh forecast", variant="primary")
+    temp_plot = gr.Plot(label="Temperature")
+    humidity_plot = gr.Plot(label="Humidity")
+    pressure_plot = gr.Plot(label="Pressure")
+
+    outputs = [temp_plot, humidity_plot, pressure_plot]
+    demo.load(refresh, outputs=outputs)
+    refresh_btn.click(refresh, outputs=outputs)
+
+
+if __name__ == "__main__":
+    demo.launch()

requirements.txt

@@ -4,3 +4,8 @@ numpy
 plotly
 requests
 python-dotenv
+
+# Toto 2.0 inference. The package isn't on PyPI; install from the
+# DataDog/toto repo's toto2/ subdirectory.
+torch>=2.4.0
+toto-2 @ git+https://github.com/DataDog/toto.git#subdirectory=toto2

src/forecast.py

@@ -0,0 +1,121 @@
+"""Toto 2.0 inference wrapper.
+
+We use the smallest Toto 2.0 variant (4M params) for speed on CPU. The model
+is downloaded from the HuggingFace Hub on first use and cached.
+
+API confirmed against DataDog/toto's `toto2/notebooks/quick_start.ipynb`:
+
+    from toto2 import Toto2Model
+    model = Toto2Model.from_pretrained("Datadog/Toto-2.0-4m", map_location=device)
+    quantiles = model.forecast(
+        {"target": ..., "target_mask": ..., "series_ids": ...},
+        horizon=H,
+    )
+    # quantiles shape: (9, batch, n_var, horizon)
+    # quantile levels:  [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9]
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+import pandas as pd
+
+DEFAULT_MODEL_ID = "Datadog/Toto-2.0-4m"
+
+# Index into the 9-quantile output.
+Q10_IDX = 0
+Q50_IDX = 4
+Q90_IDX = 8
+
+
+@dataclass
+class TotoForecast:
+    """One metric's forecast.
+
+    `index` is a future-timestamp DatetimeIndex; `median`, `p10`, `p90` are
+    pandas Series aligned to it.
+    """
+    median: pd.Series
+    p10: pd.Series
+    p90: pd.Series
+
+
+_MODEL_CACHE: dict[str, object] = {}
+
+
+def load_model(model_id: str = DEFAULT_MODEL_ID, device: str = "cpu"):
+    """Lazy-load + cache the Toto model. Imports torch lazily so this module
+    is importable in environments without torch (local dev on Intel mac)."""
+    if model_id in _MODEL_CACHE:
+        return _MODEL_CACHE[model_id]
+
+    import torch  # noqa: PLC0415
+    from toto2 import Toto2Model  # noqa: PLC0415
+
+    actual_device = device if (device != "cuda" or torch.cuda.is_available()) else "cpu"
+    model = Toto2Model.from_pretrained(model_id, map_location=actual_device)
+    model = model.to(actual_device).eval()
+    _MODEL_CACHE[model_id] = model
+    return model
+
+
+def _series_freq(series: pd.Series) -> pd.Timedelta:
+    """Infer the spacing of a regular time series; default to 1 hour."""
+    if len(series.index) < 2:
+        return pd.Timedelta("1h")
+    diffs = pd.Series(series.index).diff().dropna()
+    if diffs.empty:
+        return pd.Timedelta("1h")
+    return diffs.median()
+
+
+def forecast_series(
+    series: pd.Series,
+    horizon: int = 24,
+    model_id: str = DEFAULT_MODEL_ID,
+    device: str = "cpu",
+) -> TotoForecast:
+    """Univariate forecast for one metric.
+
+    `series` must be regularly-spaced and have a DatetimeIndex (UTC). Returns
+    median, p10, p90 over `horizon` future steps at the same cadence.
+    """
+    import torch  # noqa: PLC0415
+
+    if series.empty:
+        raise ValueError("Cannot forecast an empty series")
+
+    clean = series.astype(float).interpolate(limit_direction="both")
+    arr = clean.to_numpy(dtype=np.float32)
+
+    target = torch.from_numpy(arr).unsqueeze(0).unsqueeze(0)  # (1, 1, T)
+    target_mask = torch.ones_like(target, dtype=torch.bool)
+    series_ids = torch.zeros(1, 1, dtype=torch.long)
+
+    model = load_model(model_id, device=device)
+    target = target.to(device)
+    target_mask = target_mask.to(device)
+    series_ids = series_ids.to(device)
+
+    with torch.no_grad():
+        quantiles = model.forecast(
+            {"target": target, "target_mask": target_mask, "series_ids": series_ids},
+            horizon=horizon,
+        )
+    # quantiles: (9, 1, 1, horizon) → grab three quantile slices
+    q = quantiles.detach().cpu().numpy()
+    p10 = q[Q10_IDX, 0, 0]
+    p50 = q[Q50_IDX, 0, 0]
+    p90 = q[Q90_IDX, 0, 0]
+
+    freq = _series_freq(clean)
+    last_ts = clean.index[-1]
+    future_idx = pd.date_range(start=last_ts + freq, periods=horizon, freq=freq, tz=last_ts.tz)
+
+    return TotoForecast(
+        median=pd.Series(p50, index=future_idx, name=f"{series.name}_median"),
+        p10=pd.Series(p10, index=future_idx, name=f"{series.name}_p10"),
+        p90=pd.Series(p90, index=future_idx, name=f"{series.name}_p90"),
+    )

src/nws.py

@@ -0,0 +1,121 @@
+"""National Weather Service forecast client.
+
+Two-step flow per https://www.weather.gov/documentation/services-web-api:
+
+  GET /points/{lat},{lon}             → properties.forecastHourly (URL)
+  GET <forecastHourly URL>            → properties.periods[]      (hourly forecast)
+
+A `User-Agent` header is required; NWS uses it as a contact string and may
+block requests without one. No auth, no API key.
+
+Run standalone:
+
+  python -m src.nws                   # uses LAT / LON from .env
+  python -m src.nws --hours 24
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from datetime import datetime
+from typing import Any
+
+import pandas as pd
+import requests
+
+from . import ecowitt  # for _load_dotenv_if_present
+
+# NWS asks for a contact string. Update if you fork.
+USER_AGENT = "toto-weather-demo/0.1 (https://huggingface.co/spaces; lettieri.christopher@gmail.com)"
+
+POINTS_URL = "https://api.weather.gov/points/{lat},{lon}"
+
+
+def _get(url: str, timeout: int = 30) -> dict[str, Any]:
+    r = requests.get(url, headers={"User-Agent": USER_AGENT, "Accept": "application/geo+json"}, timeout=timeout)
+    r.raise_for_status()
+    return r.json()
+
+
+def fetch_forecast_hourly_url(lat: float, lon: float) -> str:
+    """First leg: resolve the forecast grid for this lat/lon."""
+    body = _get(POINTS_URL.format(lat=lat, lon=lon))
+    url = body.get("properties", {}).get("forecastHourly")
+    if not url:
+        raise RuntimeError(f"No forecastHourly URL in /points response: {body}")
+    return url
+
+
+def fetch_hourly_periods(forecast_hourly_url: str) -> list[dict]:
+    body = _get(forecast_hourly_url)
+    return body.get("properties", {}).get("periods", []) or []
+
+
+def _f_from_period(p: dict) -> float | None:
+    """Return temperature in °F regardless of how NWS reports it."""
+    val = p.get("temperature")
+    if val is None:
+        return None
+    unit = (p.get("temperatureUnit") or "").upper()
+    if unit == "F":
+        return float(val)
+    if unit == "C":
+        return float(val) * 9.0 / 5.0 + 32.0
+    return float(val)
+
+
+def _quantity_value(node: dict | None) -> float | None:
+    """NWS quantity nodes look like {'unitCode': 'wmoUnit:percent', 'value': 65}."""
+    if not isinstance(node, dict):
+        return None
+    v = node.get("value")
+    return None if v is None else float(v)
+
+
+def hourly_forecast_df(lat: float, lon: float, hours: int = 48) -> pd.DataFrame:
+    """Return a UTC-indexed DataFrame with NWS forecast columns aligned to
+    Ecowitt's column names where possible (`temp_f`, `humidity`)."""
+    url = fetch_forecast_hourly_url(lat, lon)
+    periods = fetch_hourly_periods(url)
+    if not periods:
+        return pd.DataFrame()
+
+    rows = []
+    for p in periods[:hours]:
+        # startTime is ISO-8601 with offset, e.g. "2026-05-10T14:00:00-04:00"
+        ts = pd.to_datetime(p["startTime"], utc=True)
+        rows.append(
+            {
+                "ts": ts,
+                "temp_f": _f_from_period(p),
+                "humidity": _quantity_value(p.get("relativeHumidity")),
+                "dewpoint_c": _quantity_value(p.get("dewpoint")),
+                "precip_prob": _quantity_value(p.get("probabilityOfPrecipitation")),
+                "wind_speed": p.get("windSpeed"),
+                "wind_direction": p.get("windDirection"),
+                "short_forecast": p.get("shortForecast"),
+            }
+        )
+    df = pd.DataFrame(rows).set_index("ts").sort_index()
+    return df
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--hours", type=int, default=24)
+    args = parser.parse_args(argv)
+
+    ecowitt._load_dotenv_if_present()
+    lat = float(os.environ["LAT"])
+    lon = float(os.environ["LON"])
+
+    df = hourly_forecast_df(lat, lon, hours=args.hours)
+    print(df.to_string())
+    print(f"\nshape: {df.shape}, range: {df.index.min()} → {df.index.max()}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

src/plotting.py

@@ -0,0 +1,69 @@
+"""Plotly figure builders for the Toto weather demo."""
+
+from __future__ import annotations
+
+import pandas as pd
+import plotly.graph_objects as go
+
+from .forecast import TotoForecast
+
+
+def metric_figure(
+    history: pd.Series,
+    toto: TotoForecast,
+    nws: pd.Series | None,
+    title: str,
+    y_label: str,
+    now: pd.Timestamp | None = None,
+) -> go.Figure:
+    fig = go.Figure()
+
+    # Past actuals
+    fig.add_trace(
+        go.Scatter(
+            x=history.index, y=history.values,
+            name="Ecowitt (past)", mode="lines",
+            line=dict(color="#222", width=2),
+        )
+    )
+
+    # Toto p10–p90 band
+    fig.add_trace(
+        go.Scatter(
+            x=list(toto.p90.index) + list(toto.p10.index[::-1]),
+            y=list(toto.p90.values) + list(toto.p10.values[::-1]),
+            fill="toself", fillcolor="rgba(31,119,180,0.18)",
+            line=dict(width=0), hoverinfo="skip",
+            name="Toto 10–90% interval",
+        )
+    )
+    # Toto median
+    fig.add_trace(
+        go.Scatter(
+            x=toto.median.index, y=toto.median.values,
+            name="Toto median", mode="lines",
+            line=dict(color="#1f77b4", width=2, dash="dash"),
+        )
+    )
+
+    if nws is not None and not nws.empty:
+        fig.add_trace(
+            go.Scatter(
+                x=nws.index, y=nws.values,
+                name="NWS forecast", mode="lines",
+                line=dict(color="#d62728", width=2, dash="dot"),
+            )
+        )
+
+    if now is not None:
+        fig.add_vline(x=now, line=dict(color="#888", dash="dot", width=1))
+
+    fig.update_layout(
+        title=title,
+        xaxis_title="Time (UTC)",
+        yaxis_title=y_label,
+        hovermode="x unified",
+        margin=dict(l=40, r=20, t=50, b=40),
+        legend=dict(orientation="h", yanchor="bottom", y=1.02, xanchor="right", x=1),
+    )
+    return fig