Supply Chain Demand Forecasting — Documentation

Overview

The Supply Chain Demand Forecasting pipeline generates SKU-level forecasts using a hybrid modelling approach. It combines seasonal decomposition with machine learning demand signals to provide operationally actionable demand plans.

Architecture

The system is broken into modular components that can be deployed independently:

forecast_pipeline/
├── ingestion/
│   ├── connector.py          # CSV / ERP / API adapters
│   ├── clean.py              # missing value imputation + business rules
│   └── calendar.py           # holiday and event feature builder
├── features/
│   ├── demand.py             # SKU-level demand drivers
│   ├── external.py           # promotions, weather, and campaigns
│   └── pipeline.py           # sklearn pipeline wrapper
├── models/
│   ├── prophet_model.py      # seasonality baseline
│   ├── lightgbm_model.py     # residual learning
│   └── ensemble.py           # final blended forecast
├── scoring/
│   ├── batch_score.py        # nightly forecast generation
│   └── realtime_api.py       # dashboard refresh endpoint
└── monitoring/
    ├── bias.py               # forecast bias checks
    └── quality.py            # error and coverage reporting

Data Schema

Required input columns for the forecasting engine:

date                date      Forecast date
sku_id              str       SKU identifier
location_id         str       Warehouse / region code
historical_qty      float     Units sold in previous period
promo_flag          int       Promotion active (0/1)
price_index         float     Normalised price signal
weather_index       float     External demand driver
on_hand_qty         float     Inventory on hand
lead_time_days      int       Supplier lead time estimate
event_flag          int       Special event / campaign indicator

Installation

git clone https://github.com/chirchirp/demand-forecasting-pipeline.git
cd demand-forecasting-pipeline

python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

pip install -r requirements.txt

cp .env.example .env
# Update environment variables for data sources and monitoring

Usage

Train the hybrid forecast

from forecast_pipeline.models.ensemble import ForecastEnsemble
from forecast_pipeline.ingestion.connector import DataConnector

connector = DataConnector(source="data/historical_demand.csv")
data = connector.load()

ensemble = ForecastEnsemble()
forecast = ensemble.fit_predict(data)
print(forecast.tail())

Generate daily batch forecasts

from forecast_pipeline.scoring.batch_score import BatchScorer

scorer = BatchScorer(model_version="production")
scorer.run(
    input_path="data/forecast_input.csv",
    output_path="outputs/forecast_output.csv"
)

API Reference

POST /forecast — Returns next-period demand for a single SKU.

POST /forecast/batch — Submits a batch of SKUs and returns predicted demand with confidence bounds.

GET /status — Returns current pipeline health and model freshness.

Performance

Deployment

The pipeline is containerised for deployment to cloud platforms or on-premise Kubernetes clusters.

docker build -t demand-forecasting:latest .
docker run -p 8080:8080 --env-file .env demand-forecasting:latest

# Deploy on Azure Container Apps
az containerapp up --name demand-forecasting \
  --resource-group rg-analytics \
  --image chirchirp/demand-forecasting:latest \
  --ingress external --target-port 8080