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

+2
View File
@@ -13,6 +13,7 @@ Most teams will ship a footfall dashboard. **We ship a staffing copilot**: a sto
Why this bet: Why this bet:
- **The data supports it.** 8 sensors, 5 months of multi-sensor data, 15-minute intervals, clear daily and weekly peaks. See [data.md](data.md). - **The data supports it.** 8 sensors, 5 months of multi-sensor data, 15-minute intervals, clear daily and weekly peaks. See [data.md](data.md).
- **The context makes it credible.** The dashboard shows the latest Heilbronn weather and German/Baden-Württemberg holidays; the Python ML service uses the same context as features. Weather is the main accuracy driver.
- **The challenge supports it.** "Dynamic Staffing" is one of the three named use cases; predictions are the explicit stretch goal. - **The challenge supports it.** "Dynamic Staffing" is one of the three named use cases; predictions are the explicit stretch goal.
- **The judging supports it.** Originality is a stated criterion and "generic dashboard" is the thing to avoid. A decision workflow is distinctive. - **The judging supports it.** Originality is a stated criterion and "generic dashboard" is the thing to avoid. A decision workflow is distinctive.
- **The demo supports it.** One scenario change visibly changes a recommendation on every phone. - **The demo supports it.** One scenario change visibly changes a recommendation on every phone.
@@ -39,6 +40,7 @@ Why this bet:
- Deployed on SKE, public HTTPS URL, health checks, README. - Deployed on SKE, public HTTPS URL, health checks, README.
- 8-sensor map with measured points (no fake city-wide heatmap). - 8-sensor map with measured points (no fake city-wide heatmap).
- 7-day hourly forecast per sensor, weather-aware, validated against a baseline. - 7-day hourly forecast per sensor, weather-aware, validated against a baseline.
- Latest weather and German/Baden-Württemberg holiday context in the dashboard, used by the ML service.
- Staffing recommendation view with transparent assumptions. - Staffing recommendation view with transparent assumptions.
- Live scenario broadcast (SSE) to stage + phones. - Live scenario broadcast (SSE) to stage + phones.
- Mobile-responsive; works on a phone without installing anything. - Mobile-responsive; works on a phone without installing anything.
+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). - **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. - **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. - **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. - **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. - **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/meta -> data/model versions, coverage, metrics
GET /api/sensors -> [{id,name,lat,lon,mean,p95,battery}] GET /api/sensors -> [{id,name,lat,lon,mean,p95,battery}]
GET /api/series?sensor=&from=&to= -> [{t,v}] 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/forecast?sensor=&horizon=15m|1h|48h|7d&scenario= -> [{t,v,lo,hi}]
GET /api/staffing?sensor=&scenario=&standard= -> {hours:[...],summary:{...}} GET /api/staffing?sensor=&scenario=&standard= -> {hours:[...],summary:{...}}
POST /api/scenario -> 202 {version, scenario} 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`. - `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. - 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`. - 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`. - **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 ```text
GET /healthz -> 200 GET /healthz -> 200
GET /readyz -> 200 if model loaded GET /readyz -> 200 if model loaded
GET /meta -> model version, metrics, training window GET /meta -> model version, metrics, training window, context version
POST /predict -> {sensor, horizon, scenario, weather} -> forecast POST /predict -> {sensor, horizon, scenario, weather, is_holiday} -> forecast
POST /simulate -> {scenario} -> forecasts for all sensors/horizons 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." - 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. - 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 semantics
| Horizon | Use | Data reality | | 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. | | 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. | | 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." | | 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. | | 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 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. | | No NetworkPolicy permission | Cannot fix a default-deny | Test early; escalate to the platform. |
+48 -4
View File
@@ -50,7 +50,51 @@ Across the multi-sensor period the weighted mean is ~14.4. Over the full file th
- The inner city peaks **18:00–21:00 local**, with the top at 19:00. Morning is quiet. - The inner city peaks **18:00–21:00 local**, with the top at 19:00. Morning is quiet.
- **Saturday is the busiest day** (mean 19.1), then Friday (16.3). Sunday is quieter (11.4) than Monday (11.9). - **Saturday is the busiest day** (mean 19.1), then Friday (16.3). Sunday is quieter (11.4) than Monday (11.9).
- The three busiest locations are **Stadtgalerie, Neckarufer and Hagenbuchersee-02**. That is a retail/leisure cluster, which fits the staffing story. - The three busiest locations are **Stadtgalerie, Neckarufer and Hagenbuchersee-02**. That is a retail/leisure cluster, which fits the staffing story.
- Weather is a real signal: the quick model below improves by ~20% when temperature/rain/cloud/wind are added. - Weather is a real signal: the quick model below improves by ~20% when temperature/rain are added.
## Context features: latest weather + German holidays
The dashboard is not just footfall. It also shows the latest Heilbronn weather and the German/Baden-Württemberg public holidays from the past, and the ML microservice uses the same context as features. This is the "why" layer: it explains spikes and makes the forecast feel less like a black box.
### Weather
- **Source:** Open-Meteo, no API key.
- **Historical:** `archive-api.open-meteo.com` for the training/validation window.
- **Current/forecast:** `api.open-meteo.com/v1/forecast` for the dashboard and what-if scenarios.
- **Fields:** `temperature_2m`, `precipitation`, `cloud_cover`, `wind_speed_10m`, `relative_humidity_2m`.
- **Timezone:** `Europe/Berlin`; handle DST explicitly.
- **Dashboard:** current conditions, a 7-day weather strip, and a "weather context" card on the forecast/plan screens.
- **Model:** temperature + rain are the useful features; cloud/wind did not improve the short test. Keep them in the payload for display, but do not claim they improve accuracy.
### German holidays (Baden-Württemberg)
Public holidays in the training window and around the demo:
| Year | Dates |
|---|---|
| 2025 | Jan 1, Jan 6, Apr 18, Apr 21, May 1, May 29, Jun 9, Jun 19, Oct 3, Nov 1, Dec 25, Dec 26 |
| 2026 | Jan 1, Jan 6, Apr 3, Apr 6, May 1, May 14, May 25, Jun 4, Oct 3, Nov 1, Dec 25, Dec 26 |
- **Feature:** `is_holiday` binary + `holiday_name` for display.
- **Dashboard:** holiday badges on the time-series and plan; a tooltip explains "public holiday in Baden-Württemberg."
- **Honest effect:** in the quick 28-day test, the holiday feature alone added little (MAE 4.15 vs 4.20 without weather; 3.44 vs 3.36 with weather). Weather is the main driver. Keep holidays as context and a feature, but do not claim a large accuracy lift.
- **Not included:** school holidays, local events, bridge days. Those are future work.
### How it flows
```text
Open-Meteo historical ──► features ──► training/validation
Open-Meteo current/7d ──► dashboard cards + scenario inputs
BW holiday calendar ──► is_holiday feature + timeline badges
│
▼
FastAPI /predict + /simulate
│
▼
Go API cache ──► Nuxt SSR dashboard
```
The dashboard can show the latest weather without the ML service being available: Go caches the last context payload. The ML service uses weather/holiday inputs when it is healthy; if it is down, the cached forecast still renders.
## What the data does **not** support ## What the data does **not** support
@@ -80,10 +124,10 @@ A deliberately small, reproducible baseline — not a tuned model. Hourly target
2. Merge `density-01` device IDs into one logical sensor. 2. Merge `density-01` device IDs into one logical sensor.
3. Exclude `maker-fair`, `niklas-01`, `hn-bollwerksturm-01`. 3. Exclude `maker-fair`, `niklas-01`, `hn-bollwerksturm-01`.
4. Aggregate to hourly means per sensor; keep 15-minute data for the drill-down view. 4. Aggregate to hourly means per sensor; keep 15-minute data for the drill-down view.
5. Join historical/forecast weather from Open-Meteo; join Baden-Württemberg holidays. 5. Join historical/forecast weather from Open-Meteo; join Baden-Württemberg holidays; export a `context.json` for the dashboard.
6. Train the global model; validate on a time-based holdout; export `forecasts.json`, `metrics.json`, `sensors.json`. 6. Train the global model; validate on a time-based holdout; export `forecasts.json`, `metrics.json`, `sensors.json`.
7. Bake the JSON into the Go binary (or serve from a volume). No runtime Python dependency. 7. Bake the model into the FastAPI image and the fallback JSON into Go. No runtime data fetch is required for the demo.
8. Show data coverage and model metrics in the app's "About the data" panel. 8. Show data coverage, weather/holiday context and model metrics in the app's "About the data" panel.
## Open data questions for the mentors ## Open data questions for the mentors
+8 -3
View File
@@ -22,8 +22,8 @@ Rehearse the 5-minute version first. The 8-minute version is the same story with
|---:|---|---| |---:|---|---|
| 0:00–0:30 | Hook | "It's Friday. A store manager on Kaiserstraße has 12 staff and a sunny Saturday forecast. Should she schedule 8 people or 14? Today she guesses. We built the answer." | | 0:00–0:30 | Hook | "It's Friday. A store manager on Kaiserstraße has 12 staff and a sunny Saturday forecast. Should she schedule 8 people or 14? Today she guesses. We built the answer." |
| 0:30–1:15 | Problem | Raw counts are not decisions. Weather, events, and time of day change the crowd. A generic dashboard shows history; it does not tell her what to do. | | 0:30–1:15 | Problem | Raw counts are not decisions. Weather, events, and time of day change the crowd. A generic dashboard shows history; it does not tell her what to do. |
| 1:15–4:15 | **Demo** | Phone: pick Stadtgalerie. Week view: Saturday peak. Staffing plan: recommended shifts, coverage, cost. Change scenario: sunny Saturday + Christmas market. Forecast rises; plan changes. The jury's phones update. | | 1:15–4:15 | **Demo** | Phone: pick Stadtgalerie. The dashboard shows the latest Heilbronn weather and German holiday badges. Week view: Saturday peak. Staffing plan: recommended shifts, coverage, cost. Change scenario: sunny Saturday + Christmas market. Forecast rises; plan changes. The jury's phones update. |
| 4:15–5:15 | How it works | 8 sensors, 15-minute data, 5 months. Weather fusion. Global model; time-based validation; MAE 3.36 vs 5.40 seasonal naive; WAPE 27.8%. Go + Nuxt + Onyx on SKE. No PII. | | 4:15–5:15 | How it works | 8 sensors, 15-minute data, 5 months. Weather + holiday context. Global model; time-based validation; MAE 3.36 vs 5.40 seasonal naive; WAPE 27.8%. Go + Nuxt + Onyx on SKE. No PII. |
| 5:15–6:00 | Honest limits | 8 sensors, 580 m, 5 months, devices not people, observed weather not forecast, no event log. What we would do with more data. | | 5:15–6:00 | Honest limits | 8 sensors, 580 m, 5 months, devices not people, observed weather not forecast, no event log. What we would do with more data. |
| 6:00–7:30 | Vision | Add POS data, event calendars, forecast weather, more sensors. Multi-store staffing API. City operations view. Start with one store, one decision. | | 6:00–7:30 | Vision | Add POS data, event calendars, forecast weather, more sensors. Multi-store staffing API. City operations view. Start with one store, one decision. |
| 7:30–8:00 | Close | "PulseCast: from footfall to shifts. The demo is live at `<URL>` — open it now." | | 7:30–8:00 | Close | "PulseCast: from footfall to shifts. The demo is live at `<URL>` — open it now." |
@@ -86,7 +86,10 @@ Never debug on stage. If the app is down, switch to the video and keep the story
> Time-based holdout: train June–October, test the last 28 days. Day-ahead MAE 3.36 with weather vs 4.20 without vs 5.40 seasonal naive. WAPE 27.8% vs 44.7%. We show the baseline and the limitations in the app. > Time-based holdout: train June–October, test the last 28 days. Day-ahead MAE 3.36 with weather vs 4.20 without vs 5.40 seasonal naive. WAPE 27.8% vs 44.7%. We show the baseline and the limitations in the app.
**"Is the weather real or synthetic?"** **"Is the weather real or synthetic?"**
> Historical observed weather for training and validation. The what-if scenarios are counterfactual inputs to the model, clearly labeled as scenarios. In production we would use the forecast API and show a confidence band. > Historical observed weather from Open-Meteo for training and validation. The dashboard shows the latest Heilbronn weather and a 7-day forecast; the what-if scenarios are counterfactual inputs to the model, clearly labeled as scenarios. The forecast still renders if Open-Meteo is down because Go caches the last context payload.
**"What about holidays?"**
> The dashboard shows German/Baden-Württemberg public holidays from the past and uses an `is_holiday` feature. Weather is the main accuracy driver; the holiday feature added little in our 28-day test, so we present it as context, not a miracle. That honesty is part of the product.
**"Why Nuxt + Go + Onyx?"** **"Why Nuxt + Go + Onyx?"**
> Vue and Go are the Digits stack; Onyx is the design system. Nuxt gives us a fast, typed frontend build; Go gives us one small binary with SSE and static serving. One deployable, fewer failure modes. The Onyx Nuxt module is official. > Vue and Go are the Digits stack; Onyx is the design system. Nuxt gives us a fast, typed frontend build; Go gives us one small binary with SSE and static serving. One deployable, fewer failure modes. The Onyx Nuxt module is official.
@@ -114,6 +117,8 @@ Never debug on stage. If the app is down, switch to the video and keep the story
- "Production-grade" without the caveat. - "Production-grade" without the caveat.
- "AI" as a feature. The model is a means to a decision. - "AI" as a feature. The model is a means to a decision.
- "We built a platform." You built a product for one decision. - "We built a platform." You built a product for one decision.
- "Holidays improve accuracy a lot." They are context; weather is the main driver.
- "Live weather data." It is the latest forecast/current conditions plus historical weather, not a live sensor feed.
## Slides (max 8) ## Slides (max 8)
+6 -4
View File
@@ -54,14 +54,16 @@ The technical stack is not the differentiator. Nuxt SSR, Go, FastAPI, SSE and SK
## The MVP in five screens ## The MVP in five screens
1. **Now** — pulse map of the 8 sensors, current/replay reading, weather, last update. This is the "Pulse of the City" context. 1. **Now** — pulse map of the 8 sensors, current/replay reading, **latest Heilbronn weather**, **German/Baden-Württemberg holiday badge**, last update. This is the "Pulse of the City" context.
2. **Forecast** — 48-hour and 7-day forecast per location, with uncertainty band, weather context and baseline comparison. 2. **Forecast** — 48-hour and 7-day forecast per location, with uncertainty band, **weather strip**, **holiday markers** and baseline comparison.
3. **Plan** — the hero screen: recommended staff per hour, shift blocks, coverage score, over/understaffed hours, estimated labor cost, comparison to a flat schedule. 3. **Plan** — the hero screen: recommended staff per hour, shift blocks, coverage score, over/understaffed hours, estimated labor cost, comparison to a flat schedule, and a **"why this plan" context card** that names the weather/holiday driver.
4. **Simulate** — presenter changes weather / event / service standard; forecast and plan update; all phones stay in sync via SSE. 4. **Simulate** — presenter changes weather / event / service standard; forecast and plan update; all phones stay in sync via SSE.
5. **About** — data coverage, model metrics, assumptions, privacy, limitations. 5. **About** — data coverage, weather/holiday sources, model metrics, assumptions, privacy, limitations.
The hero screen is **Plan**. Everything else supports it. The hero screen is **Plan**. Everything else supports it.
**Context layer:** the dashboard shows the latest weather and historical German holidays, and the Python ML microservice uses the same context as features. This is not decoration: weather is the main accuracy driver, and holidays explain spikes. It makes the product feel like it understands the city, not just the sensor.
**Plan generation requirement:** one click on "Generate next week" returns a shift plan in **under 2 seconds**. The plan is a table of 2–4 hour shift blocks per day, staff counts per hour, coverage score, cost, and a comparison to a flat schedule. The manager can edit the assumptions and regenerate. Export as CSV/print view. Not a drag-and-drop optimizer; a usable plan, fast. **Plan generation requirement:** one click on "Generate next week" returns a shift plan in **under 2 seconds**. The plan is a table of 2–4 hour shift blocks per day, staff counts per hour, coverage score, cost, and a comparison to a flat schedule. The manager can edit the assumptions and regenerate. Export as CSV/print view. Not a drag-and-drop optimizer; a usable plan, fast.
## The decision logic — transparent, not magic ## The decision logic — transparent, not magic
+10 -6
View File
@@ -21,10 +21,10 @@ If those six are clear, it is halfway good. Novelty is a bonus, not a requiremen
|---|---:|---| |---|---:|---|
| Abstract | 150–200 words | Problem, data, method, headline result, deployment. | | Abstract | 150–200 words | Problem, data, method, headline result, deployment. |
| 1. Introduction | 0.5 page | The decision gap; why a dashboard is not enough; three contributions. | | 1. Introduction | 0.5 page | The decision gap; why a dashboard is not enough; three contributions. |
| 2. Data | 0.75 page | PAX counters, 8 sensors, 5 months, 15 min, 580 m, coverage/gaps, device-penetration bias, privacy. | | 2. Data | 0.75 page | PAX counters, 8 sensors, 5 months, 15 min, 580 m, coverage/gaps, device-penetration bias, privacy, Open-Meteo weather, Baden-Württemberg holidays. |
| 3. Method | 1 page | Preprocessing, features, global HistGB, weather fusion, horizons, time-based split, staffing heuristic. | | 3. Method | 1 page | Preprocessing, features (time, lags, weather, holiday), global HistGB, horizons, time-based split, staffing heuristic. |
| 4. System | 0.75 page | Nuxt SSR, Go API/SSE, FastAPI, Cloudflare Tunnel, SKE namespace-only, build-time batch, cached fallback. | | 4. System | 0.75 page | Nuxt SSR, Go API/SSE, FastAPI, Cloudflare Tunnel, SKE namespace-only, build-time batch, cached fallback. |
| 5. Evaluation | 1 page | Baseline comparison, weather ablation, per-sensor errors, plan latency, 120-client load test. | | 5. Evaluation | 1 page | Baseline comparison, weather ablation, holiday effect, per-sensor errors, plan latency, 120-client load test. |
| 6. Discussion & limitations | 0.5 page | 8 sensors, 5 months, observed weather, no POS/labor data, single replica, no auth. | | 6. Discussion & limitations | 0.5 page | 8 sensors, 5 months, observed weather, no POS/labor data, single replica, no auth. |
| 7. Related work | 0.25 page | PAX counters/privacy, pedestrian forecasting, gradient boosting, smart-city dashboards. | | 7. Related work | 0.25 page | PAX counters/privacy, pedestrian forecasting, gradient boosting, smart-city dashboards. |
| 8. Conclusion & future work | 0.25 page | More sensors, POS/event data, multi-store, city operations. | | 8. Conclusion & future work | 0.25 page | More sensors, POS/event data, multi-store, city operations. |
@@ -36,7 +36,7 @@ If those six are clear, it is halfway good. Novelty is a bonus, not a requiremen
1. Sensor map of the 580 m cluster (8 points; label the sensor names). 1. Sensor map of the 580 m cluster (8 points; label the sensor names).
2. Hourly and weekday footfall profile (the "pulse"). 2. Hourly and weekday footfall profile (the "pulse").
3. Forecast vs actual for one sensor over the 28-day test (with uncertainty band). 3. Forecast vs actual for one sensor over the 28-day test (with uncertainty band), with weather/holiday context markers.
4. Architecture diagram (three services + Cloudflare Tunnel + SKE). 4. Architecture diagram (three services + Cloudflare Tunnel + SKE).
5. The staffing plan screen (or a table if the screenshot is weak). 5. The staffing plan screen (or a table if the screenshot is weak).
@@ -44,7 +44,7 @@ If those six are clear, it is halfway good. Novelty is a bonus, not a requiremen
1. Data coverage per sensor: readings, mean, p95, max, max gap. 1. Data coverage per sensor: readings, mean, p95, max, max gap.
2. Model comparison: seasonal naive vs no-weather vs weather, MAE/WAPE/R². 2. Model comparison: seasonal naive vs no-weather vs weather, MAE/WAPE/R².
3. Ablation: weather on/off; per-sensor MAE. 3. Ablation: weather on/off, holiday on/off; per-sensor MAE.
4. System metrics: plan generation latency, 120 SSE clients, image sizes, deployment time. 4. System metrics: plan generation latency, 120 SSE clients, image sizes, deployment time.
## Facts and numbers to use (do not invent) ## Facts and numbers to use (do not invent)
@@ -61,6 +61,8 @@ If those six are clear, it is halfway good. Novelty is a bonus, not a requiremen
- **With temperature/rain:** MAE **3.36**, WAPE **27.8%**, R² **0.779**. - **With temperature/rain:** MAE **3.36**, WAPE **27.8%**, R² **0.779**.
- **7-day:** MAE 4.37, WAPE 36.2%, R² 0.672. - **7-day:** MAE 4.37, WAPE 36.2%, R² 0.672.
- **Caveat:** weather is observed, not forecast; no event data; 4-week test; values are device estimates, not people. - **Caveat:** weather is observed, not forecast; no event data; 4-week test; values are device estimates, not people.
- **Weather:** Open-Meteo historical archive for training; forecast API for the dashboard. Temp/rain are the useful features; cloud/wind did not improve the short test.
- **Holidays:** German/Baden-Württemberg public holidays 2025–2026; `is_holiday` feature + dashboard badges. The holiday-only feature added little in the 28-day test (4.15 vs 4.20 without weather; 3.44 vs 3.36 with weather). Report honestly.
- **System:** 3 Deployments + `cloudflared`; no Ingress, no cert-manager, no Jobs; build-time batch; Cloudflare Tunnel; SSE + polling fallback; Go cache; plan < 2 s. - **System:** 3 Deployments + `cloudflared`; no Ingress, no cert-manager, no Jobs; build-time batch; Cloudflare Tunnel; SSE + polling fallback; Go cache; plan < 2 s.
- **Load test:** fill in after k6; do not claim a number you did not measure. - **Load test:** fill in after k6; do not claim a number you did not measure.
@@ -82,6 +84,7 @@ Facts:
- 8-sensor window 2026-06-12 to 2026-11-07; ~15-min cadence; 580 m cluster. - 8-sensor window 2026-06-12 to 2026-11-07; ~15-min cadence; 580 m cluster.
- Values are estimated devices, not people; device penetration unknown. - Values are estimated devices, not people; device penetration unknown.
- Peak 18:00–21:00 local; Saturday busiest. - Peak 18:00–21:00 local; Saturday busiest.
- Weather from Open-Meteo; German/Baden-Württemberg holidays as context features.
- Global HistGradientBoostingRegressor; time-based holdout of 28 days. - Global HistGradientBoostingRegressor; time-based holdout of 28 days.
- Seasonal naive: MAE 5.40, WAPE 44.7%, R2 0.462. - Seasonal naive: MAE 5.40, WAPE 44.7%, R2 0.462.
- No weather: MAE 4.20, WAPE 34.8%, R2 0.678. - No weather: MAE 4.20, WAPE 34.8%, R2 0.678.
@@ -106,7 +109,8 @@ real sources you are confident exist; otherwise write "[CITATION TODO]".
- [ ] Every number matches `mission/data.md` or a measured result. - [ ] Every number matches `mission/data.md` or a measured result.
- [ ] The baseline table is present; the model is compared to seasonal naive, not only to itself. - [ ] The baseline table is present; the model is compared to seasonal naive, not only to itself.
- [ ] Weather is described as observed, not forecast. - [ ] Weather is described as observed for training, forecast/current for the dashboard.
- [ ] Holidays are described as context/feature, not as a large accuracy lift.
- [ ] The 8-sensor/5-month/580 m limitation is explicit. - [ ] The 8-sensor/5-month/580 m limitation is explicit.
- [ ] "Devices, not people" appears at least once. - [ ] "Devices, not people" appears at least once.
- [ ] No claim of live sensor data; replay/nowcast is labeled. - [ ] No claim of live sensor data; replay/nowcast is labeled.
+2 -2
View File
@@ -72,7 +72,7 @@ The human owns decisions, integration, deployment, and the demo. Agents own code
### 2. Data/ML agent — `ml/` ### 2. Data/ML agent — `ml/`
- Owns `ml/`, `data/` (git-ignored raw), generated JSON, the FastAPI service. - Owns `ml/`, `data/` (git-ignored raw), generated JSON, the FastAPI service.
- Delivers: batch pipeline (`make data`), `sensors.json`, `series.json`, `forecasts.json`, `metrics.json`, `model_card.md`, FastAPI `/predict` and `/simulate` with `/healthz` and `/readyz`. - Delivers: batch pipeline (`make data`), `sensors.json`, `series.json`, `forecasts.json`, `metrics.json`, `context.json` (Open-Meteo weather + BW holidays), `model_card.md`, FastAPI `/predict` and `/simulate` with `/healthz` and `/readyz`.
- Must not touch `web/` or `api/` code. - Must not touch `web/` or `api/` code.
- Definition of done: reproducible batch run; time-based validation; baseline comparison; no leakage; FastAPI starts with the baked model; JSON schema matches the contract; Go cache fallback tested. - Definition of done: reproducible batch run; time-based validation; baseline comparison; no leakage; FastAPI starts with the baked model; JSON schema matches the contract; Go cache fallback tested.
- Prompt: *"Read mission/README.md, mission/data.md and mission/architecture.md. Build the batch pipeline and FastAPI service. Do not tune for more than 2 hours. Report MAE/WAPE vs seasonal naive and the exact JSON/API schema."* - Prompt: *"Read mission/README.md, mission/data.md and mission/architecture.md. Build the batch pipeline and FastAPI service. Do not tune for more than 2 hours. Report MAE/WAPE vs seasonal naive and the exact JSON/API schema."*
@@ -88,7 +88,7 @@ The human owns decisions, integration, deployment, and the demo. Agents own code
### 4. Nuxt agent — `web/` ### 4. Nuxt agent — `web/`
- Owns `web/`. - Owns `web/`.
- Delivers: app shell, pulse map, time-series chart, forecast + staffing view, scenario controls, `/live` mobile view, `/stage` big-screen view, `/control` token page, empty/error states. - Delivers: app shell, pulse map, time-series chart, forecast + staffing view, weather card, holiday badges, scenario controls, `/live` mobile view, `/stage` big-screen view, `/control` token page, empty/error states.
- Must not touch `api/` or `ml/`. - Must not touch `api/` or `ml/`.
- Definition of done: builds with `nuxt build` (SSR); works with mock JSON before the API exists; responsive at 390 px and 1440 px; no console errors; browser-only map/chart wrappers; Onyx components where sensible. - Definition of done: builds with `nuxt build` (SSR); works with mock JSON before the API exists; responsive at 390 px and 1440 px; no console errors; browser-only map/chart wrappers; Onyx components where sensible.
- Prompt: *"Read mission/README.md and mission/architecture.md. Build the screens against the mock data in `web/mock/`. Use `@sit-onyx/nuxt` with SSR. Wrap MapLibre and SSE in client-only components. Keep the map dependency replaceable with a static image."* - Prompt: *"Read mission/README.md and mission/architecture.md. Build the screens against the mock data in `web/mock/`. Use `@sit-onyx/nuxt` with SSR. Wrap MapLibre and SSE in client-only components. Keep the map dependency replaceable with a static image."*
+2
View File
@@ -58,6 +58,8 @@ Answer these in chat; I will update the docs. Each has a recommended answer and
- **Batch path:** build-time, not a Kubernetes Job/CronJob. - **Batch path:** build-time, not a Kubernetes Job/CronJob.
- **Security:** the kubeconfig is a secret, now git-ignored and chmod 600. Rotate the token after the event; it was shared in chat. - **Security:** the kubeconfig is a secret, now git-ignored and chmod 600. Rotate the token after the event; it was shared in chat.
**Weather/holiday scope — resolved:** use Open-Meteo (historical archive for training; current/7-day forecast for the dashboard) and German/Baden-Württemberg public holidays 2025–2026. The ML service uses the same context as features. The earlier "only what is available" is read as "no invented data"; public context is in. See [data.md](data.md).
--- ---
## Q1 — Hero use case ## Q1 — Hero use case