Metadata-Version: 2.4
Name: demandplan
Version: 0.2.0
Summary: Production-grade demand planning: classical forecasting, intermittent demand, hierarchical reconciliation, and probabilistic outputs.
Author: Cheng-I Wu
License: Apache-2.0
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"
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9; extra == "docs"
Dynamic: license-file

# 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

```bash
pip install -e ".[dev]"
```

```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 series
result.forecasts  # quantile forecasts from full-history refit
```

Full walkthrough in [docs/index.md](docs/index.md); design rationale in the
[spec](docs/superpowers/specs/2026-08-23-demand-planning-library-design.md),
[research report](research/report.md), and [ADR-0001](docs/adr/0001-segmentation-router-no-sbc-thresholds.md).

## 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 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
