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:
1 parent
9c7f77f66b
commit
070ecd2a78
13 files changed
+81
-75
No files matched your search
@@ -1,11 +1,10 @@
|
||||
# PulseCast ML
|
||||
|
||||
Footfall pipeline, weather-aware 7-day forecast, scenario engine, and FastAPI
|
||||
service for the PulseCast staffing copilot.
|
||||
|
||||
The reusable asset is the pipeline: raw 15-minute PAX counters → clean hourly
|
||||
series → observed weather + Baden-Württemberg holidays → global model →
|
||||
honest holdout metrics → JSON artifacts → decision-ready API.
|
||||
service for the PulseCast staffing copilot. It turns raw 15-minute PAX counter
|
||||
rows into hourly series, joins weather and Baden-Württemberg holidays, trains
|
||||
one global model, evaluates it on a 28-day time-based holdout, and serves the
|
||||
resulting JSON artifacts.
|
||||
|
||||
## Results
|
||||
|
||||
@@ -24,9 +23,10 @@ honest holdout metrics → JSON artifacts → decision-ready API.
|
||||
The seasonal-naive row reproduces the mission reference exactly
|
||||
(5.40 / 44.7% / 0.462), and the day-ahead weather row matches 3.36 / 27.8%.
|
||||
Weather cuts error by ~19% versus the no-weather 7-day model and ~38% versus
|
||||
seasonal naive. The production model is slightly better than the reference
|
||||
because its seasonal feature uses the previous *observed* same weekday/hour
|
||||
across sensor gaps; the baseline uses the exact 168-row lag.
|
||||
seasonal naive. The production 7-day model edges the reference day-ahead
|
||||
weather row (3.32 vs 3.36 MAE). The two use different features; `lag_week` uses
|
||||
the previous *observed* same weekday/hour across sensor gaps, while the
|
||||
seasonal-naive baseline uses the exact 168-row lag.
|
||||
|
||||
Small busy-hour classifier (baked for the "train new data" demo):
|
||||
|
||||
@@ -37,34 +37,35 @@ Small busy-hour classifier (baked for the "train new data" demo):
|
||||
The classifier predicts `busy` = hourly footfall above the sensor's p75 using
|
||||
hour, weekday, weekend, temperature, rain, and holiday. It trains in under a
|
||||
second on the challenge CSV and is retrained from an uploaded CSV through
|
||||
`POST /train`. Full definition, confusion matrix, per-sensor table, and honest
|
||||
limits: [`docs/small-model.md`](docs/small-model.md). Paper tables and figures:
|
||||
`POST /train`. Full definition, confusion matrix, per-sensor table, and limits:
|
||||
[`docs/small-model.md`](docs/small-model.md). Paper tables and figures:
|
||||
[`docs/metrics.md`](docs/metrics.md).
|
||||
|
||||
## Quick start
|
||||
|
||||
Requirements: Python 3.12 and `uv` (the repo also works with a plain venv).
|
||||
Requires Python 3.12 and `uv`.
|
||||
|
||||
```bash
|
||||
uv sync
|
||||
make data # needs the raw CSV, first run also fetches Open-Meteo weather
|
||||
make serve # uses the committed artifacts; http://localhost:8000
|
||||
make check # same gate as CI: sync --frozen, ruff, compileall, pytest
|
||||
```
|
||||
|
||||
To rebuild the artifacts from raw data:
|
||||
|
||||
```bash
|
||||
make data # needs the raw CSV; first run also fetches Open-Meteo weather
|
||||
make train # writes artifacts/model.joblib, metrics.json, forecasts.json
|
||||
make small # prints the busy-hour classifier metrics + confusion matrix
|
||||
make figures # regenerates docs/figures/*.svg from metrics.json
|
||||
make test
|
||||
make check # CI gate: sync --frozen, ruff, compileall, pytest
|
||||
make serve # http://localhost:8000
|
||||
```
|
||||
|
||||
The raw challenge CSV is **never committed**. Put it at:
|
||||
|
||||
```text
|
||||
/home/noel/Documents/Hackathon_2026/data/raw/schwarz-pax.csv
|
||||
```
|
||||
|
||||
or point `PULSECAST_RAW_CSV` at it. `data/raw/` and `data/cache/` are git-ignored.
|
||||
The generated `artifacts/` (JSON + joblib + compact weather frames) are
|
||||
committed so the API and Docker image work without the raw file or network.
|
||||
The raw challenge CSV is **never committed**. The default path is
|
||||
`/home/noel/Documents/Hackathon_2026/data/raw/schwarz-pax.csv`; set
|
||||
`PULSECAST_RAW_CSV` to use another file. `data/raw/` and `data/cache/` are
|
||||
git-ignored. The committed `artifacts/` (JSON + joblib + compact weather frames)
|
||||
let the API and Docker image run without the raw file or network.
|
||||
|
||||
## Artifacts
|
||||
|
||||
@@ -76,14 +77,15 @@ committed so the API and Docker image work without the raw file or network.
|
||||
| `artifacts/metrics.json` | Versions, coverage, headline metrics, ablation, per-sensor, small summary, limits |
|
||||
| `artifacts/small_metrics.json` | Busy classifier: metrics, confusion matrix, per-sensor, thresholds |
|
||||
| `artifacts/context.json` | Current + 7-day weather, BW holidays |
|
||||
| `artifacts/data_audit.json` | Row/sensor checks against `mission/data.md` |
|
||||
| `artifacts/data_audit.json` | Row/device checks for the raw CSV |
|
||||
| `artifacts/model.joblib` | Baked HistGB forecast bundle |
|
||||
| `artifacts/small_model.joblib` | Baked busy classifier |
|
||||
| `artifacts/weather_*.parquet` | Baked weather frames for retraining/inference |
|
||||
|
||||
## API
|
||||
|
||||
Shapes follow `CONTRACT.md`. The service is internal; Go exposes it publicly.
|
||||
Response shapes match the Go service contract. The service is internal; Go
|
||||
exposes it publicly.
|
||||
|
||||
| Method | Path | Notes |
|
||||
|---|---|---|
|
||||
@@ -160,9 +162,11 @@ artifacts baked in, writable paths only under `/tmp`.
|
||||
|
||||
| Variable | Default | Use |
|
||||
|---|---|---|
|
||||
| `PULSECAST_ROOT` | first parent with `pyproject.toml` | Project root |
|
||||
| `PULSECAST_RAW_CSV` | challenge path | Raw CSV location |
|
||||
| `PULSECAST_ARTIFACTS` | `./artifacts` | Baked JSON/model output |
|
||||
| `PULSECAST_CACHE` | `./data/cache` | Parquet/weather cache |
|
||||
| `PULSECAST_WEATHER` | `PULSECAST_ARTIFACTS` | Baked weather frame location |
|
||||
| `PULSECAST_MODELS` | `/tmp/pulsecast/models` | Retrained model persistence |
|
||||
| `PULSECAST_UPLOADS` | `/tmp/pulsecast/uploads` | Multipart upload landing |
|
||||
| `CONTROL_TOKEN` | unset | Required by `/train`; service returns 503 if unset |
|
||||
@@ -182,7 +186,7 @@ src/pulsecast/
|
||||
retrain.py runtime forecast retraining from upload
|
||||
server.py FastAPI app and training job manager
|
||||
scripts/ train_small.py, plot_metrics.py, e2e_train.py
|
||||
docs/ metrics.md, small-model.md, generated figures
|
||||
docs/ metrics.md, small-model.md, train-e2e.md, generated figures
|
||||
tests/ schema, bootstrap, health, prediction, small-training job
|
||||
model_card.md features, split, baseline, ablation, limits, leakage
|
||||
```
|
||||
|
||||
Reference in new issue
Block a user