From ac0d8984bb2a20337edf2285c37a85d688a55b87 Mon Sep 17 00:00:00 2001 From: Noel Sabia Date: Sat, 14 Nov 2026 09:12:29 +0100 Subject: [PATCH] docs: correct reproduction and cache claims The small-model page said make small reproduced every number, but the threshold table and several derived values only appear in the JSON payload. Say what the commands actually print, fix the stale weather-cache docstring, and lead the e2e evidence page with what it checks. --- docs/small-model.md | 5 +++-- docs/train-e2e.md | 11 ++++++----- scripts/train_small.py | 6 +++--- src/pulsecast/weather.py | 2 +- 4 files changed, 13 insertions(+), 11 deletions(-) diff --git a/docs/small-model.md b/docs/small-model.md index cb0e0f8..878c117 100644 --- a/docs/small-model.md +++ b/docs/small-model.md @@ -6,7 +6,8 @@ forecast: six cheap features, a time-based split, and under a second to fit. Every number below comes from the baked artifact `artifacts/small_metrics.json` (version `logit-20261114-052723`, trained -2026-11-14T05:27:23Z) and can be reproduced with `make small`. +2026-11-14T05:27:23Z). `make small` prints the headline metrics and per-sensor +table; `scripts/train_small.py --json` prints the full payload. ## Target @@ -132,7 +133,7 @@ it is not evidence of a strong signal there. ## Reproduce ```bash -# Full challenge CSV, prints every number above. +# Full challenge CSV, prints the metrics and per-sensor table above. make small # Explicit CSV, all rows, save the baked artifact. diff --git a/docs/train-e2e.md b/docs/train-e2e.md index eb9b198..3ef079e 100644 --- a/docs/train-e2e.md +++ b/docs/train-e2e.md @@ -1,16 +1,17 @@ # Training end-to-end evidence +The script starts a real `uvicorn pulsecast.server:app` process with +`CONTROL_TOKEN`, waits for startup, and drives the HTTP API only. It checks the +snapshot, every prediction/scenario path, auth and error paths, one job at a +time, and both training jobs; it exits non-zero on the first failed check. +Unit/contract tests (`make check`) are separate. + Reproduce with: ```bash uv run python scripts/e2e_train.py --port 18000 --report /tmp/e2e.json ``` -The script starts a real `uvicorn pulsecast.server:app` process with -`CONTROL_TOKEN`, waits for startup, and drives the HTTP API only. It exits -non-zero on the first failed check. Unit/contract tests (`make check`) are -separate. - ## Run | Field | Value | diff --git a/scripts/train_small.py b/scripts/train_small.py index 9add34e..9cb6c0e 100644 --- a/scripts/train_small.py +++ b/scripts/train_small.py @@ -2,9 +2,9 @@ """Train and evaluate the small "busy hour" classifier from a CSV. This is the repeatable artifact behind ``make small`` and the runtime -``model=small`` training job. It prints every number reported in -``docs/small-model.md``; ``--save`` bakes the bundle and metrics into -``artifacts/`` exactly like ``make train`` does. +``model=small`` training job. It prints the headline metrics and per-sensor +table used in ``docs/small-model.md``; ``--save`` bakes the bundle and metrics +into ``artifacts/`` exactly like ``make train`` does. Examples: uv run python scripts/train_small.py diff --git a/src/pulsecast/weather.py b/src/pulsecast/weather.py index 8c8f280..30181e3 100644 --- a/src/pulsecast/weather.py +++ b/src/pulsecast/weather.py @@ -128,7 +128,7 @@ def ensure_weather( *, refresh: bool = False, ) -> tuple[pd.DataFrame, pd.DataFrame, dict]: - """Load cached weather, fetching only when missing, stale, or refresh=True.""" + """Load cached weather, fetching only when the cache is missing or refresh=True.""" cache = config.cache_dir() cache.mkdir(parents=True, exist_ok=True) archive_path = cache / ARCHIVE_FILE