Description

This notebook is a production-grade tutorial demonstrating KumoRFM (Kumo Relational Foundation Model) for demand forecasting on multi-table retail data.

What it does (forecast-only)

• Builds a relational graph: sales(sku_id, week, qty) → skus → {products/hierarchy, stores/attributes}
• Handles censorship: Omits out-of-stock weeks from events (availability-aware)
• Prevents time leakage: Explicit as-of date truncation (only past events inform predictions)
• Uses Predictive Query Language (PQL): Single batched query to forecast 21-day demand per SKU
• Validates with mini backtest: Sliding-origin MAE/MAPE on 2 prior cutoffs
• Outputs: rfm_21d_predictions.csv + metadata JSON (reproducibility)

Key innovations

• Multi-hop reasoning: KumoRFM automatically learns from product/store hierarchies via relational structure
• Zero training: Foundation model generalizes from graph structure + timestamps
• Batched PQL: PREDICT SUM(sales.qty, 0, 21, days) FOR skus.sku_id IN (...) scores all SKUs efficiently
• Time-aware: Temporal splits handled natively; no manual feature engineering

What it does NOT include

• No inventory policies, cost optimization, or safety stock calculations
• No order quantity computation or submission generation
• No hyperparameter tuning or cross-validation

Forecasts ≠ Orders. The 21-day demand predictions can be inputs to downstream decision models.

Results (mini backtest)

• MAE: ~3.3 units per SKU over 21 days
• MAPE: 43-49% (high due to sparse/low-volume SKUs typical in retail)
• Runtime: ~60 seconds for 599 SKUs (batch prediction)

Technical details

• Graph structure: 4 tables with explicit FK→PK links
• Semantic types: Numerical targets, categorical hierarchy, ID keys
• Time column: Explicit time_column='week' on sales events
• Censorship: OOS weeks dropped from event table (no row = no event)
• API: Env-based authentication (no hardcoded secrets)

Attribution

• KumoRFM: kumo.ai | GitHub
• Dataset: VN2 Inventory Optimization Challenge
• Style: Follows KumoRFM handbook best practices for multi-table temporal regression

Competition relevance: Demonstrates zero-shot foundation model approach for retail demand forecasting, complementing traditional baselines (EDA, RL, Hierarchical Bayes) already shared publicly.