inventoryAI

Optimizing inventory management through the integration of Global Demand Forecasting and Reinforcement Learning.

This repository contains the end-to-end pipeline developed by the AI che dolor team. The project addresses the complexity of modern supply chains by combining ensemble machine learning for demand prediction with Reinforcement Learning (RL) for stochastic inventory control.

---

Technical Overview

The system operates as a two-stage optimization engine:

1. Global Forecasting Ensemble: A multi-model framework utilizing LightGBM and XGBoost to learn shared demand patterns across diverse Stock Keeping Units (SKUs) and locations. A Ridge-based meta-model stacks these predictions to provide a robust demand baseline.
2. RL Residual Controller: A Deep Reinforcement Learning agent that treats the forecast as a baseline and learns to "nudge" order quantities. This stage optimizes for real-world business constraints, such as the asymmetry between holding costs and stockout penalties.

---

Core Files

Demand Forecasting Engine

• data_loader.py: Manages the ingestion of historical demand signals and entity metadata from Parquet files.
• preprocessor.py: Implements the feature engineering pipeline, including dynamic lag generation (leakage-protected), temporal feature extraction, and linear interpolation for data cleaning.
• model_lgbm.py: Defines LightGBM configurations with specialized presets such as Tweedie for intermittent demand and MAE-optimization for outlier robustness.
• Model_XGboost.py: Implements a complementary XGBoost forecaster focused on capturing demand volatility and intermittency through Huber loss and custom rolling statistics.
• combined_model.py: Provides the stacking logic to train a final meta-model on base-model predictions using Time Series Cross-Validation.
• forecasting_arima.py: A benchmarking tool that provides automated SARIMA modeling for comparative performance analysis.

Reinforcement Learning and Environment

• rl_from_data.py: The primary training script for the RL agent. It integrates historical demand, generated forecasts, and product metadata to train a residual policy.
• conv_reinforce_trainer.py: Implements the REINFORCE algorithm tailored for convolutional architectures, managing state buffers and policy updates.
• conv_models.py: Defines the neural network architectures, including a CNN-based policy that fuses temporal demand sequences with static product features.
• utils.py: Contains environment utility functions, including episode generators for demand data and a solver for comparing the RL agent against an optimal Gurobi-based inventory policy.
• data_utils.py: Provides data-loading utilities for various experimental setups and policy evaluations.

Evaluation and Orchestration

• evaluator.py: A comprehensive suite of supply chain metrics, including Mean Absolute Error (MAE), Root Mean Squared Error (RMSE), and Weighted Mean Absolute Percentage Error (WMAPE).
• main.ipynb: The central execution environment for data integration, feature engineering, global model training, and performance benchmarking.

---

Replication Procedure

1. Ensemble Forecast Generation

Execute the training and inference pipeline to establish the demand baseline.

• Action: Run forecasting/main.ipynb.
• Output: This step generates the consolidated predictions utilized by the inventory environment.

2. RL Residual Policy Training

Train the convolutional agent to refine order quantities based on the forecasting residuals.

• Action: Execute rl_from_data.py.
• Output: The best-performing agent is serialized to rl/trained/demand_residual_from_data.pth.

3. Verification and Testing

Analyze the final policy performance against raw forecasts and myopic order strategies.

• Metrics: WMAPE (Weighted Mean Absolute Percentage Error) and total holding vs. missed sale costs are used as the primary KPIs for validation.

---

Team AI che dolor | Stochastic Optimization and Meta-Learning for Supply Chain Excellence.