zerosuum/restockiq-demand-v1

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:

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.