demandplan

Production-grade demand planning library: probabilistic forecasting, intermittent demand methods, hierarchical reconciliation, and inventory decisions — built end-to-end from literature research through adversarial audit to a published, continuously-validated PyPI package.

Why this exists

Most forecasting libraries answer "how do I run model X?" — this one answers "which method wins on my data, how uncertain is it, and what do I reorder because of it?"

• Measured selection, not rules. Champion–challenger backtests pick a method per SKU; no hardcoded segmentation thresholds (ADR-0001).
• Quantiles are the contract. Every forecaster returns predictive distributions, because inventory decisions consume tails (newsvendor), not points.
• Claims are validated adversarially. Golden-reference tests against vetted implementations, ground-truth simulations, real Walmart M5 data — details in the case study.

Validation stack

Reports: benchmarks/ · Research base: research/

Install

pip install demandplan                    # core
pip install "demandplan[ml]"              # global LightGBM (covariate-aware)
pip install "demandplan[fm]"              # Chronos-Bolt foundation models

Quickstart

from demandplan.pipeline import champion_challenger

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

New here? Follow A user's walkthrough — every step, input, and genuine outcome on real Walmart data. Runnable version: examples/walkthrough.ipynb.

Scope

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 series + 25k 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)
python examples/make_figures.py         # regenerate docs/assets figures

Design history lives in ADRs and the audited research base; engineering war stories in the case study.

License

Apache-2.0