SibangiS/hf-inventory-demand-forecaster
7-day retail demand forecasting and reorder calculator
2 min readupdated
A hybrid stacking ensemble (combining multiple algorithms under a meta-model) that predicts total 7-day demand for a specific product at a given store. It takes historical CSV sales data and outputs a demand forecast alongside recommended reorder quantities adjusted for safety stock. Under the hood, tuned LightGBM and XGBoost gradient boosting models are blended by a HuberRegressor meta-model — the author dropped the LSTM model in this release after the two-booster combo achieved lower error. Useful for data analysts and inventory management developers looking for a ready-to-run pipeline or a tabular forecasting baseline.
Key features
- Uses 49 leak-free features: sales lags, 7-, 14-, and 28-day rolling averages and standard deviations, competitor prices, discounts, seasonality, and weather.
- The HuberRegressor meta-model (weighted 0.5785 for LightGBM and 0.3456 for XGBoost) is trained strictly on out-of-fold validation and beats individual models on MAE and RMSE.
- Automatically calculates safety stock (at the 90th percentile of errors — 181.75 units), lifting the test service level to 91.14%.
- Bundles the entire pipeline and preprocessor into a single
hybrid_ensemble.pklfile, while keeping earlier versions and training scripts in the repo for comparison.
What you can do
- Run the ready-made
predict.pyscript on historical sales tables (at least 28 rows per store–product pair) to generate demand forecasts and reorder quantities. - Use the feature engineering and ensemble architecture as a starting point for custom retail forecasting tasks by fine-tuning on real-world data.
- Compare classic gradient boosting against LSTM on tabular time series using the pre-computed benchmarks in
leaderboard.csv.
Example
pip install -r requirements.txt
python predict.py --history sample_input.csvRead more
DetailsTest metrics (8,400 rows): MAE — 105.30 (vs. 141.86 for the seasonal baseline and 106.61 for v1 Ridge), RMSE — 138.13, WMAPE — 0.1460.
Training: 64,200 rows from a synthetic Kaggle dataset (5 stores, 20 products, 2022–2024).
Limitations: trained on synthetic data, does not account for product shelf life, and is intended for research rather than direct production use without validation on real sales.










Comments