A demand forecasting platform that turns M5 data into inventory scenarios, explanations and recommendations for human decisions.
Key metric
0.771
Mean bottom-level RMSSE · 28-day validation
Mean RMSSE · lower is better
LightGBM0.771
Naive last0.952
Seasonal 70.976
Seasonal 281.006
Same validation window · 2,744,100 training rows · not the official M5 WRMSSE
Architecture
RetailOps AI
Components, data flows and trust boundaries of the system.
Scroll the diagram →
Technologies
BigQuery
dbt
Cloud Storage
LightGBM
SHAP
FastAPI
Cloud Run
Vertex AI
LangGraph
Gemini
React
PostgreSQL
Docker
GitHub Actions
Terraform
Design decisions
01
The recursive forecast runs inside Cloud Run: each horizon feeds the next one’s lags, which a per-horizon endpoint would handle poorly. Vertex AI keeps model registry and promotion.
02
The LLM never writes SQL: it picks typed, parameterized BigQuery templates, each with a billed-bytes ceiling.
03
The agent is read-only; any proposed business action goes through a LangGraph interrupt and human approval, with state persisted in Cloud SQL.
04
FastAPI services are private (Google ID tokens), the console sits behind IAP, and deployment uses Workload Identity Federation with no service-account keys.
The problem
A forecast alone does not determine the right action. This project connects a recursive 28-day forecast with explicit business scenarios and a copilot using bounded tools.
What I built
RAW/STAGING/SILVER/GOLD layers, leakage-safe temporal contracts, a LightGBM Poisson model, private FastAPI serving, TreeSHAP explanations, counterfactual inventory scenarios, a LangGraph agent and a React console. Training validated on Cloud Run Jobs and a GCP delivery pipeline.
Result and trade-off
On the same validation window (2,744,100 training rows), LightGBM reaches a mean RMSSE of 0.771 versus 0.952 for the best naive baseline. This is not the official hierarchical M5 WRMSSE.
Scope and limitations
Inventory and lead times are user-provided scenario assumptions: M5 does not contain them. Demand bands are stress scenarios without calibrated coverage guarantees. Vertex AI Custom Training is not validated; V7 additions require separate cloud validation.