---
library_name: lightgbm
tags:
- lightgbm
- retail
- demand-forecasting
- quantile-regression
- inventory
---

# RestockIQ Demand v1

Frozen LightGBM artifact used by the RestockIQ semifinal product for stockout-censored demand reconstruction and direct cumulative quantile forecasting.

## Artifact identity

- Version: `restockiq-demand-v1-a067286b7c1e`
- Production Git SHA evaluated: `06ae958730f87cc44b3a5dbb7094fb8a3c88f7a3`
- Training dataset ID: `demo-retail-v1`
- Training cutoff: `2024-05-31`
- Training data hash: `a067286b7c1e966de43f3db9e1d24a7f8a440d236d94c24365c6d717ca44399c`
- Seed: `20260723`
- Artifact files covered by the supplied checksum manifest: 11
- Oracle fields used as model features: none

## Components

The artifact contains:

1. One causal stockout-censor reconstruction model trained with uncensored observed sales as its label.
2. Nine direct cumulative quantile models: H1, H7, and H14 × Q10, Q50, and Q90.
3. Frozen feature medians and split-conformal interval adjustments in `manifest.json`.
4. Inference-time clipping and quantile-order repair in the RestockIQ application code.

The cumulative target contract is demand from `t+1` through `t+H`; the decision-origin day is not part of its own label.

## Controlled synthetic evaluation

The supplied `evaluation/` directory was produced by the standalone evaluator against the pinned production Git SHA and frozen workbook. The evaluator imports the production snapshot builder, feature engineering, artifact loader, and inference path. Predictions are generated before the synthetic Oracle label is joined.

Evaluation window: June 2024. Label: synthetic latent demand `units_demanded_est`, used for evaluation only. The benchmark contains 10,540 store–SKU–origin–horizon prediction rows.

| Horizon | Q50 MAE | Q50 RMSE | Q50 WMAPE | Best tested baseline WMAPE | Relative result vs best baseline | Q10–Q90 coverage |
|---:|---:|---:|---:|---:|---:|---:|
| H1 | 2.384 | 3.590 | 31.33% | 32.68% (Croston) | +4.14% | 78.64% |
| H7 | 9.563 | 14.722 | 18.19% | 17.48% (28-day moving average) | −4.10% | 81.07% |
| H14 | 14.259 | 20.992 | 13.49% | 14.42% (28-day moving average) | +6.46% | 83.15% |

There were zero quantile-crossing rows after the production inference repair. The frozen Q50 model beats the strongest tested causal baseline at H1 and H14, while the 28-day moving-average baseline remains stronger at H7. This mixed result is retained intentionally.

## Intended use

- Frozen controlled RestockIQ demo inference.
- Reproduction of the supplied June 2024 synthetic evaluation.
- Inspection of the model and Oracle-safe feature contract.

The artifact is not a general pretrained retail model and does not perform live retraining.

## Out-of-scope use and claims

Do not use this artifact or its evaluation to claim:

- proven generalization to real merchants or arbitrary POS systems;
- realized stockout reduction;
- inventory-cost reduction;
- service-level improvement;
- savings, revenue uplift, or ROI;
- causal promotional effects.

Supplier risk, LMAR, WCAR, and the exact sparse-DP allocator are downstream RestockIQ components. They are not outputs or submodels of these LightGBM files.

## Oracle and leakage boundary

The frozen manifest declares these fields as forbidden model features:

- `units_demanded_est`
- `demand_profile`
- `avg_daily_demand_per_store`
- `cash_locked_in_stock_rp`

Realized future supplier outcomes are likewise excluded from decision-time inputs. Oracle data is permitted only after prediction for controlled evaluation and value decomposition.

## Files

- `manifest.json`
- `SHA256SUMS`
- `reconstruction_censor_no_inventory.txt`
- `forecast_h1_q10.txt`, `forecast_h1_q50.txt`, `forecast_h1_q90.txt`
- `forecast_h7_q10.txt`, `forecast_h7_q50.txt`, `forecast_h7_q90.txt`
- `forecast_h14_q10.txt`, `forecast_h14_q50.txt`, `forecast_h14_q90.txt`
- `evaluation/`: predictions, point metrics, quantile diagnostics, baseline comparison, run manifest, summary, and checksums

## Verification

From the model repository root:

```bash
sha256sum -c SHA256SUMS
cd evaluation && sha256sum -c SHA256SUMS
```

The evaluation manifest records the exact Git SHA, workbook checksum, training cutoff, model version, target timing, baseline definitions, and claim limitations.

No license is asserted in this card because the project team has not frozen a licensing decision.