ML-forecasting/README.md

Demand Forecasting Case Study

Privacy-safe demonstration of a demand-forecasting delivery flow using only synthetic data, written as an executive-readable AI delivery case study.

What it demonstrates

• Monthly demand by synthetic SKU and region.
• A baseline forecast: the mean of the preceding eight observed months after removing one minimum and one maximum.
• One gradient-boosting model using lag and calendar features.
• Leakage-safe rolling-origin validation for a 12-month horizon.
• A manual trigger boundary that can later be connected to Airflow.
• Annotated charts and written observations connecting modeling choices to delivery governance.
• An optional, gated build-vs-buy comparison against a pretrained TimesFM foundation model (RUN_TIMESFM=1), evaluating operational cost alongside accuracy instead of switching models by default.

The notebook calculates evaluation metrics for model selection, but the published case-study narrative intentionally avoids numeric business claims.

The notebook is structured for an executive audience: it starts with the business question, explains why the baseline exists, visualizes the signal and validation trade-off, and closes with delivery implications for a lean AI task force.

Run

uv sync
uv run jupyter notebook notebooks/forecasting_case_study.ipynb

To execute the notebook non-interactively:

uv run jupyter execute notebooks/forecasting_case_study.ipynb --inplace

To also run the optional TimesFM foundation-model comparison (downloads ~500M-parameter weights from Hugging Face; needs torch/transformers and internet access):

RUN_TIMESFM=1 uv run --with torch --with transformers jupyter execute notebooks/forecasting_case_study.ipynb --inplace

Privacy boundary

This repository contains no company rows, identifiers, schemas, credentials, private URLs, or copied business values. Review docs/publication-checklist.md before publishing.

Artifacts

• notebooks/forecasting_case_study.ipynb — reproducible analysis.
• docs/forecasting-case-study-notebook.pdf — rendered notebook with charts and results for platforms that do not preview Jupyter notebooks.
• docs/architecture.mmd — editable architecture diagram.
• docs/architecture.svg — editable/exportable diagram asset used by the handout.
• docs/case-study-one-page.md — Markdown source for the interview handout.
• docs/case-study-one-page.html — print-ready handout source.
• docs/case-study-one-page.pdf — generated one-page interview handout.
• docs/linkedin-post.md — publication draft.