End-to-end demand forecasting platform for retail supply chains (M5): pipelines, feature engineering, MLflow, and batch/real-time inference.
An end-to-end demand forecasting platform for multi-SKU retail/CPG scenarios, designed as a production-like system: data ingestion, feature store, model training, model registry, batch + real-time inference, monitoring, and measurable business impact.
Forecasting is a core driver of supply chain performance (service level, inventory, working capital, and cost). This project demonstrates:
- Data Engineering: robust pipelines and data quality controls
- Data Science: feature engineering and forecasting experimentation
- AI/ML: modern models (GBM, deep learning) and ensembles
- MLOps: reproducibility, tracking, model registry, monitoring, retraining
- Supply Chain Impact: metrics tied to inventory and lost sales
Given daily sales history for multiple products (SKUs), forecast demand at different horizons (e.g., 7/14/28 days) while handling:
- seasonality, holidays, promotions
- cold start (new items)
- outliers and stockouts
- multiple locations (optional extension)
- Forecasts by SKU and horizon (P50 + optional prediction intervals)
- Model performance reports by SKU segment
- Monitoring dashboard (data drift + forecast error drift)
- A simple financial impact simulation (inventory vs lost sales tradeoff)
Data Engineering
- Python, Pandas/Polars
- DuckDB (local) / Postgres (optional)
- Prefect or Airflow (or simple CLI pipelines to start)
MLOps
- MLflow (tracking + model registry)
- DVC (optional) for data versioning
Modeling
- Baseline: Seasonal Naive
- Statistical: Prophet (optional)
- ML: LightGBM/XGBoost
- Deep Learning: LSTM or Temporal Fusion Transformer (optional phase)
Serving
- FastAPI (real-time inference endpoint)
- Batch inference job (daily)
flowchart TD
A[M5 Raw CSV Data] --> B[Data Ingestion Pipeline]
B --> C[Clean Dataset Parquet]
C --> D[Feature Engineering Pipeline]
D --> E[Training Dataset]
E --> F[Model Training LightGBM]
F --> G[Trained Model Artifact .pkl]
G --> H[Batch Inference Pipeline]
H --> I[Forecast Output]
G --> J[FastAPI Prediction Service]
J --> K[Real-time Forecast API]
I --> L[Business Impact Evaluation]
L --> M[Operational Cost Reduction Analysis]
This project supports two options:
Use M5 Forecasting (Walmart sales) or similar multi-SKU datasets.
- Daily unit sales by item/store, calendar events, and prices.
- Great for multi-horizon forecasting and feature engineering.
A synthetic data generator is included to create realistic patterns (seasonality, promotions, shocks) for quick iteration.
- Seasonal Naive (weekly seasonality)
- Moving Average Goal: establish a strong baseline and sanity check.
- LightGBM/XGBoost using engineered features:
- lags (1,7,14,28)
- rolling mean/std
- day-of-week, month, holidays
- promo/price features (if available)
- stockout flags
- LSTM / TFT for SKUs with complex patterns
- Compare against ML models for incremental gain
- Weighted blend of top models by SKU segment
- WAPE (preferred for business)
- RMSE
- MAPE (careful with zeros)
- Bias (systematic over/under forecasting)
A lightweight simulation links forecast quality to operations:
- Lost Sales (proxy):
max(demand - inventory, 0) - Holding Cost:
inventory * holding_cost_rate - Service Level (Fill Rate)
Outputs:
- Cost/service curves by model
- Recommended policy sensitivity (simple reorder point approximation)
- Time-based split (no random split)
- Missing dates filled per SKU
- Outlier handling strategy documented
- Stockouts treated as censored demand (flag + imputation strategy)
- Leakage prevention: features built using only past data
- MLflow experiment tracking for every run:
- dataset version
- features configuration
- model hyperparameters
- metrics by SKU and global
- Model registry stages:
Staging → Production - Retraining trigger examples:
- WAPE drift above threshold
- data drift in key features
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
1) Run the pipeline (example)
python -m pipelines.ingestion.run
python -m pipelines.preprocessing.run
python -m pipelines.feature_engineering.run
python -m pipelines.training.run --model lgbm
python -m pipelines.inference.run --mode batch
2) Start the API (optional)
uvicorn src.serving.app:app --reload
Phase 1 — MVP
- dataset ingestion + clean time series
- baseline models + evaluation
- reproducible training runs
Phase 2 — Production-like
- feature store concept (simple feature tables)
- MLflow tracking + model registry
- batch inference + output contracts
Phase 3 — Advanced
- drift monitoring + retraining triggers
- probabilistic forecasts / intervals
- cost-impact simulation and model selection by business KPI
Results (to be filled)
- Top model performance (WAPE, Bias)
- Model ranking by SKU segment (fast/slow movers)
- Financial impact simulation summary
Most forecasting repos are notebooks. This is a platform:
- pipelines, quality, reproducibility
- model registry and monitoring
- business impact alignment (inventory & service level)
| Model | WAPE | RMSE |
|---|---|---|
| Seasonal Naive Baseline | 0.8750 | 3.4031 |
| LightGBM | 0.6737 | 2.4564 |
The LightGBM model significantly improves forecast accuracy compared to the naive seasonal baseline.
Key observations:
- WAPE improvement: ~23%
- RMSE improvement: ~27%
- The model still shows a mild underforecast bias.
Using simple supply chain cost proxies:
- Stockout cost per unit: 5
- Holding cost per unit: 1
The LightGBM forecast reduces estimated operational cost by:
~20.7% vs baseline
This improvement can translate to:
- lower stockout risk
- reduced excess inventory
- improved replenishment decisions
- more stable supply chain planning
Example comparison between actual demand and model forecast for a sample SKU.
End-to-end machine learning system designed for scalable demand forecasting, from raw data ingestion to real-time API predictions and business impact evaluation.
python pipelines/ingestion/load_m5.py
python pipelines/features/build_training_features.py
python pipelines/training/train_lightgbm.py
python pipelines/inference/run_inference.py
python pipelines/evaluation/business_impact.py
uvicorn src.serving.app:app --reload
MIT
Victor Vergara
Procurement and operations professional with 15+ years of experience in supply chain, analytics, and process improvement. Focused on applying AI/ML, forecasting, and digital transformation to real-world operational challenges.
- Email: victorgvc@gmail.com
- Portfolio: https://github.com/victorgvc-hes?tab=repositories