docs(mission): add weather and holiday context
release-please / release-please (push) Failing after 3s
release-please / release-please (push) Failing after 3s
This commit is contained in:
1 parent
8afb767585
commit
1ff3bc8290
8 files changed
+109
-25
No files matched your search
+31
-6
@@ -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. |
|
||||
|
||||
Reference in new issue
Block a user