demandplan

Production-grade demand planning library: classical forecasting, intermittent demand methods, hierarchical reconciliation, and probabilistic outputs designed to feed inventory decisions.

Scope

Shipped in v0.1:

• Classical forecasting core — naive / seasonal-naive baselines, ETS, ARIMA/SARIMA behind one probabilistic protocol
• Intermittent demand — Croston, SBA, TSB (vectorized, portfolio-scale)
• Hierarchical reconciliation — bottom-up / top-down / middle-out, OLS / WLSv / MinT-shrink with coherence guarantees
• Probabilistic forecasting — quantile outputs everywhere, calibration diagnostics, newsvendor order-up-to solver
• Evaluation — rolling-origin backtesting with leakage guards; WAPE/MASE/RMSSE/WQL/bias; Forecast Value Add tables
• Selection — champion-challenger per series from backtested performance (no hardcoded segmentation rules)
• Knowledge base — method guides, evaluation handbook, selection framework, tiered industry notes (docs/)

Planned for later versions: ML/DL model families, foundation-model adapters, causal/driver-based methods, temporal reconciliation, demand sensing utilities.

Quickstart

pip install -e ".[dev]"

from demandplan.pipeline import champion_challenger

result = champion_challenger(df, horizon=13)  # df: unique_id, ds, y
result.champion  # winning model + backtested WAPE per series
result.forecasts  # quantile forecasts from full-history refit

Full walkthrough in docs/index.md; design rationale in the spec, research report, and ADR-0001.

Development

python -m pytest          # test suite (coverage gate ≥90% enforced)
python -m mypy            # strict typing
python -m ruff check .    # lint + format checks
mkdocs serve              # knowledge base site
python examples/run_battle_tests.py     # bundled real series + 25k-series scale test
python examples/client_simulation.py    # ground-truth decision validation
python examples/real_m5_validation.py   # real Walmart M5 end-to-end (auto-downloads)

Validated on Windows and Linux (Python 3.12); distribution artefacts pass twine check. Reproducibility locks: constraints/. Real-data evidence: benchmarks/.

License

Apache-2.0