Metadata-Version: 2.4
Name: demandplan
Version: 0.4.0
Summary: Production-grade demand planning: classical forecasting, intermittent demand, hierarchical reconciliation, and probabilistic outputs.
Author: Cheng-I Wu
License: Apache-2.0
Project-URL: Homepage, https://github.com/trikieu293/demandplan
Project-URL: Repository, https://github.com/trikieu293/demandplan
Project-URL: Issues, https://github.com/trikieu293/demandplan/issues
Keywords: demand-planning,forecasting,supply-chain,intermittent-demand,reconciliation
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: statsmodels>=0.14
Requires-Dist: statsforecast>=1.7
Requires-Dist: hierarchicalforecast>=0.4
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: hypothesis>=6; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: pandas-stubs; extra == "dev"
Requires-Dist: types-setuptools; extra == "dev"
Requires-Dist: lightgbm>=4; extra == "dev"
Requires-Dist: mlforecast>=0.13; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9; extra == "docs"
Provides-Extra: ml
Requires-Dist: lightgbm>=4; extra == "ml"
Requires-Dist: mlforecast>=0.13; extra == "ml"
Provides-Extra: fm
Requires-Dist: chronos-forecasting>=2; extra == "fm"
Dynamic: license-file

# demandplan

[![PyPI](https://img.shields.io/pypi/v/demandplan)](https://pypi.org/project/demandplan/)
[![Python](https://img.shields.io/pypi/pyversions/demandplan)](https://pypi.org/project/demandplan/)
[![License](https://img.shields.io/pypi/l/demandplan)](LICENSE)
[![CI](https://github.com/trikieu293/demandplan/actions/workflows/ci.yml/badge.svg)](https://github.com/trikieu293/demandplan/actions/workflows/ci.yml)

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.

![28-day probabilistic forecast on a real Walmart SKU](docs/assets/fig_fan.png)

## 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](docs/adr/0001-segmentation-router-no-sbc-thresholds.md)).
- **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](docs/case_study.md).

## Validation stack

| Evidence | Result |
|---|---|
| Real M5 Walmart data (270 SKUs, full hierarchy) | +30% FVA vs naive · coherence error 5e-13 across 283 nodes |
| Ground-truth client simulation | safety stock hits **95.3% realized service vs 95% target** |
| Scale benchmark | 25 000-series champion–challenger in ~250 s, single machine |
| Correctness anchors | golden refs vs `hierarchicalforecast`/scipy · property tests · **183 tests**, ≥90 % coverage |
| Cross-platform | Windows + Linux (WSL) full-suite green |

Reports: [`benchmarks/`](benchmarks/) · Research base: [`research/`](research/)

## Install

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

## Quickstart

```python
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](docs/tutorials/user_storyline.md) — every
step, input, and genuine outcome on real Walmart data. Runnable version:
[`examples/walkthrough.ipynb`](examples/walkthrough.ipynb).

## Scope

| Shipped | Later versions |
|---|---|
| naive/seasonal-naive, ETS, ARIMA/SARIMA · Croston/SBA/TSB (+NB heads) · **global LightGBM (cross-learning + covariates)** | temporal reconciliation |
| MinT-shrink / WLS / BU-TD-MO reconciliation with coherence guarantees | probabilistic reconciliation (BUIS) |
| rolling-origin backtesting, FVA, stateful `refit=False`, **covariate-aware backtesting** | Chronos fine-tuning, second dataset |
| newsvendor order-up-to from any quantile grid · calibration diagnostics | demand-sensing utilities |

## Development

```bash
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](docs/adr/) and the audited research base; engineering
war stories in the [case study](docs/case_study.md).

## License

Apache-2.0
