docs(mission): add weather and holiday context
release-please / release-please (push) Failing after 3s

This commit is contained in:
Noel Sabia committed 2026-11-13 20:27:06 +01:00
1 parent 8afb767585
commit 1ff3bc8290
8 files changed
+109 -25

No files matched your search

+31 -6
View File
@@ -77,7 +77,7 @@ CSV ──► Python batch (pandas, sklearn) ──► model + JSON forecasts
- **Frontend:** Nuxt 4.6.4, `ssr: true`, `@sit-onyx/nuxt` 1.2.0, `sit-onyx` 1.22.0, `@sit-onyx/chartjs-plugin` 1.0.1, Chart.js, MapLibre GL JS (static basemap fallback).
- **Backend:** Go 1.27+, `net/http`; `chi` optional. SSE hub, scenario state, cache, health/ready.
- **ML:** Python 3.12, pandas, scikit-learn (`HistGradientBoostingRegressor`), FastAPI/Uvicorn. Horizons: 15 min, 1 h, 48 h, 7 d.
- **ML:** Python 3.12, pandas, scikit-learn (`HistGradientBoostingRegressor`), FastAPI/Uvicorn. Horizons: 15 min, 1 h, 48 h, 7 d. Weather from Open-Meteo; German/Baden-Württemberg public holidays as a feature and dashboard context.
- **Registry:** Gitea at `git.noelsabia.dev`, Docker Registry v2, Let's Encrypt certificate. `imagePullSecret` in the namespace. Public Docker Hub pull also works, so `cloudflare/cloudflared` can be used directly.
- **K8s:** three Deployments + `cloudflared`, four Services, ConfigMaps/Secrets, no PVC, no CRDs, no cluster-scoped resources.
- **TLS/DNS:** Cloudflare Tunnel public hostnames. No cert-manager, no external-dns, no Ingress.
@@ -133,6 +133,7 @@ GET /api/readyz -> 200 if data loaded
GET /api/meta -> data/model versions, coverage, metrics
GET /api/sensors -> [{id,name,lat,lon,mean,p95,battery}]
GET /api/series?sensor=&from=&to= -> [{t,v}]
GET /api/context -> {weather:{now,forecast[]}, holidays:[], updated_at}
GET /api/forecast?sensor=&horizon=15m|1h|48h|7d&scenario= -> [{t,v,lo,hi}]
GET /api/staffing?sensor=&scenario=&standard= -> {hours:[...],summary:{...}}
POST /api/scenario -> 202 {version, scenario}
@@ -141,7 +142,7 @@ GET /api/stream -> text/event-stream; events: scenario, pulse
- `scenario` enum: `base`, `sunny-saturday-market`, `rainy-saturday`, `weekday-event`; `standard`: `relaxed|standard|premium`.
- Go never computes the model. It calls FastAPI or serves the cached JSON.
- Every response carries `data_version` and `model_version`.
- Every response carries `data_version`, `model_version` and `context_version`; the UI shows "last updated" for each.
- SSE: `event: scenario\ndata: {...}\n\n`, heartbeat 15 s, `retry: 3000`.
- **Plan generation:** `GET /api/staffing` returns a complete next-week plan in under 2 seconds; the heuristic is deterministic and cached by `sensor|scenario|standard`.
@@ -150,15 +151,38 @@ GET /api/stream -> text/event-stream; events: scenario, pulse
```text
GET /healthz -> 200
GET /readyz -> 200 if model loaded
GET /meta -> model version, metrics, training window
POST /predict -> {sensor, horizon, scenario, weather} -> forecast
POST /simulate -> {scenario} -> forecasts for all sensors/horizons
GET /meta -> model version, metrics, training window, context version
POST /predict -> {sensor, horizon, scenario, weather, is_holiday} -> forecast
POST /simulate -> {scenario, weather, is_holiday} -> forecasts for all sensors/horizons
```
- Go calls `/simulate` on a scenario change; caches by `scenario|standard`.
- Go calls `/simulate` on a scenario change; caches by `scenario|standard|weather|holiday`.
- If FastAPI times out (> 1.5 s) or is unhealthy, Go serves the cached JSON and marks the UI "cached forecast."
- The batch job is build-time; there is no Job/CronJob permission. A production path can use a CronJob in a less restricted namespace; document it, do not depend on it.
## Context features: weather and holidays
The dashboard shows the latest Heilbronn weather and the German/Baden-Württemberg public holidays from the past. The ML service uses the same context as features, and the what-if scenarios can change the weather.
```text
Open-Meteo historical ──► training/validation features
Open-Meteo current/7d ──► /api/context + dashboard cards + scenario input
BW holiday calendar ──► is_holiday feature + timeline badges
│
▼
FastAPI /predict + /simulate
│
▼
Go cache ──► Nuxt SSR dashboard
```
- **Weather source:** Open-Meteo archive for training; forecast API for the dashboard. No API key.
- **Weather fields:** temperature, precipitation, cloud cover, wind, humidity. Show all; use temperature/rain as model features (cloud/wind did not improve the short test).
- **Holidays:** 2025–2026 Baden-Württemberg public holidays; `is_holiday` feature plus `holiday_name` for display.
- **Dashboard:** current conditions, 7-day weather strip, holiday badges on the timeline, and a "context" card that explains spikes.
- **Reliability:** Go caches the last `/api/context` payload. If Open-Meteo is unreachable, the dashboard shows "last updated" and the forecast still renders. No runtime weather call is required for the demo. If the context is newer than the forecast, the UI labels it "context updated; forecast cached."
- **Honesty:** weather is the main driver; holidays are context and a small feature. Do not claim a large holiday accuracy lift.
## Horizon semantics
| Horizon | Use | Data reality |
@@ -179,6 +203,7 @@ The CSV is static. Without a live feed, 15 min/1 h are replay/nowcast features,
| Cloudflare Tunnel down | URL 502 / no tunnel | Restart `cloudflared`; use a temporary `kubectl port-forward` for the demo? No — use a backup tunnel or local fallback. |
| SSE buffered | No events on phone | Poll `/api/scenario` every 5 s; keep UI. |
| FastAPI down | `/readyz` fails | Go serves cached JSON; banner "cached forecast." |
| Open-Meteo down | `/api/context` stale | Go serves cached context; show "last updated"; forecast unaffected. |
| Nuxt SSR down | 502 on `/` | Restart pod; local fallback; recorded video. |
| No Jobs/CronJobs | Batch cannot run in-cluster | Build-time pipeline; document production path. |
| No NetworkPolicy permission | Cannot fix a default-deny | Test early; escalate to the platform. |