ci: fix Gitea runner setup and tighten docs
ci / check (push) Successful in 1m12s

Replace setup-python with setup-uv: the self-hosted Gitea runner lacks the
toolcache and lsb_release dependency, so the job failed before any project
step. uv installs its own Python 3.12; the checks are unchanged.

Align the README and docs with the committed artifacts: quick start serves
from baked artifacts, rebuild steps are separate, and the reference-model
comparison no longer overstates the result. Drop stale external-doc
references and comments that restated the code.
This commit is contained in:
Noel Sabia committed 2026-11-14 09:10:47 +01:00
1 parent 9c7f77f66b
commit 070ecd2a78
13 files changed
+81 -75

No files matched your search

+5 -6
View File
@@ -1,4 +1,4 @@
"""Configuration: paths, sensors, holidays, scenarios, contract versions.
"""Configuration: paths, sensors, holidays, features, scenarios.
All timestamps are UTC internally; Europe/Berlin is used only for calendar
features and display-oriented payloads.
@@ -65,8 +65,8 @@ def control_token() -> str:
# --------------------------------------------------------------------------- data
# Multi-sensor window documented in mission/data.md. density-01 has older
# history but the other seven locations start on 2026-06-12.
# Multi-sensor window of the published dataset. density-01 has older history,
# but the other seven locations start on 2026-06-12.
MULTI_SENSOR_START = "2026-06-12T00:00:00Z"
# 28-day time-based holdout, measured back from the last observed hour.
@@ -134,8 +134,8 @@ WEATHER_COLUMNS = {
"relative_humidity_2m": "humidity_pct",
}
# Baden-Württemberg public holidays, 2025-2026 (mission/data.md). Kept explicit
# so the build is deterministic and needs no holiday library.
# Baden-Württemberg public holidays, 2025-2026. Kept explicit so the build is
# deterministic and needs no holiday library.
HOLIDAYS: dict[str, str] = {
"2025-01-01": "Neujahr",
"2025-01-06": "Heilige Drei Könige",
@@ -185,7 +185,6 @@ FEATURE_WEATHER = ["temp_c", "precip_mm"]
FEATURE_DAY_NO_HOLIDAY = FEATURE_CALENDAR_NO_HOLIDAY + FEATURE_DAY[6:]
FEATURE_DAY_NO_WEATHER = FEATURE_DAY
FEATURE_DAY_WEATHER = FEATURE_DAY + FEATURE_WEATHER
FEATURE_DAY_HOLIDAY = FEATURE_DAY + ["is_holiday"] # is_holiday already present; kept for clarity
FEATURE_WEEK_NO_WEATHER = FEATURE_WEEK
FEATURE_WEEK_WEATHER = FEATURE_WEEK + FEATURE_WEATHER
+2 -2
View File
@@ -16,7 +16,7 @@ from . import config
from .features import SENSOR_CODES, future_calendar
# Fixed, deliberately small model. No tuning beyond a short sanity pass: the
# 28-day holdout is the honest signal, not the training loss.
# 28-day holdout decides, not the training loss.
HISTGB_PARAMS = {
"loss": "squared_error",
"learning_rate": 0.06,
@@ -58,7 +58,7 @@ def metrics(y_true, y_pred) -> dict:
def residual_quantiles(eval_frame: pd.DataFrame, pred: np.ndarray) -> dict:
"""80% prediction band offsets from the honest holdout residuals."""
"""80% prediction band offsets from the holdout residuals."""
residual = np.asarray(eval_frame["y"], dtype=float) - np.asarray(pred, dtype=float)
return {
"p10": round(float(np.quantile(residual, 0.10)), 4),
+4 -3
View File
@@ -1,8 +1,9 @@
"""Parse and clean the raw PAX CSV.
Verifies the claims in mission/data.md: 192,464 rows, 12 device IDs, 8 usable
logical locations, three excluded test devices, and the density-01 merge.
The raw file is never written to git; a cached parquet copy lives in data/cache/.
The audit checks the counts the pipeline depends on: 192,464 rows, 12 device
IDs, 8 usable logical locations, three excluded test devices, and the
density-01 merge. The raw file is never written to git; a cached parquet copy
lives in data/cache/.
"""
from __future__ import annotations
+7 -6
View File
@@ -1,7 +1,7 @@
"""FastAPI ML service: /healthz, /readyz, /meta, /bootstrap, /predict, /simulate, /train.
Shapes follow CONTRACT.md. The service is internal: only Go exposes it publicly,
and the training routes require a bearer control token.
The service is internal: only Go exposes it publicly, and the training routes
require a bearer control token.
"""
from __future__ import annotations
@@ -79,10 +79,9 @@ def _load_runtime(runtime: Runtime) -> None:
json.loads(meta_path.read_text()) if meta_path.exists() else None
)
# Baked snapshot artifacts served by GET /bootstrap. Go caches this once at
# startup, so loading them at boot keeps the endpoint a pure in-memory read.
# Project to the contract fields; artifacts carry extra audit fields
# (last_seen) that Go does not need.
# Go caches /bootstrap once at startup, so load it at boot and keep the
# endpoint a pure in-memory read. Project to contract fields because the
# artifacts carry extra audit fields (last_seen).
sensors_path = artifacts / "sensors.json"
if sensors_path.exists():
sensors = json.loads(sensors_path.read_text())
@@ -653,6 +652,8 @@ def create_app() -> FastAPI:
state = runtime()
model, path = await _parse_train_request(request)
# Serialize check-and-start so two requests cannot both pass the
# "no active job" check.
with state.schedule_lock:
with state.jobs_lock:
if any(job["status"] in ACTIVE_STATUSES for job in state.jobs.values()):
+2 -2
View File
@@ -93,8 +93,8 @@ def _attach_weather(hourly: pd.DataFrame, archive: pd.DataFrame | None) -> pd.Da
frame[column] = frame[column].where(frame[column].notna(), frame[archive_column])
frame = frame.drop(columns=[archive_column])
# Honest fallback: no weather available for the uploaded window. Constant
# values keep the other features useful; the job metrics show the effect.
# No weather for the uploaded window: constant values keep the other
# features usable, and the job metrics show the effect.
frame["temp_c"] = frame["temp_c"].fillna(14.0)
frame["precip_mm"] = frame["precip_mm"].fillna(0.0)
return frame
+1 -1
View File
@@ -170,7 +170,7 @@ def train_bundle(
}
)
# Production model: refit on all observed rows after the honest holdout.
# Production model: refit on all observed rows after the holdout is scored.
production = fit(features, config.FEATURE_WEEK_WEATHER)
residual = residual_quantiles(eval_frame, preds["week_weather"])
sensor_mean = hourly.groupby("sensor", observed=True)["v"].mean().round(4).to_dict()
+3 -3
View File
@@ -1,8 +1,8 @@
"""Open-Meteo weather: historical archive for training, forecast for scenarios.
No API key. Responses are cached under data/cache/ so `make train` and the
Docker image need no network. The raw CSV and cache stay out of git; the final
context.json is committed.
No API key. Responses are cached under data/cache/ so `make train` needs no
network after the first fetch. The raw CSV and cache stay out of git; compact
frames and context.json are committed under artifacts/.
"""
from __future__ import annotations