retail_planning: align to predictive skills PR #21 + add registry split - #45
Merged
Conversation
…t workflow Aligns retail_planning.py to the predictive skills from rai-agent-skills PR #21 (rai-predictive-modeling + rai-predictive-training): - rename pt=pt to property_transformer=pt (SDK alignment) - drop deprecated database=/schema= args from GNN constructor - add stream_logs=False (default) to avoid non-TTY spinner flood - add seed for reproducible training - bump sales n_epochs from 5 to 20 per regression-tuning guidance; add target-distribution profile (min/max/mean/stddev) before training - add temporal_strategy="last" to sales and churn GNNs - add _report(gnn) helper for gnn.dataset.print_data_config() and gnn.visualize_dataset(), gated by VERBOSE_DATASET - explicit drop=[] for PK/FK columns in PropertyTransformer - add graph-derived features (Article.popularity_count, Customer.activity_count) demonstrating the cross-skill pattern from rai-graph-analysis; surfaced via integer=[] in PropertyTransformer Adds a split workflow for train-once/optimize-many iteration: - _retail_setup.py: shared model/graph/PT used by train and optimize - retail_train.py: trains and registers 3 GNNs to the Snowflake registry - retail_optimize.py: loads registered GNNs, runs markdown + demand planning - README: documents both workflows; expands troubleshooting with regression under-fitting, has_time_column edge-intermediary limitation, non-TTY spinner, and registry access grants retail_planning.py remains the all-in-one single-script entrypoint for users who don't need the split.
|
The docs preview for this pull request has been deployed to Vercel!
|
Makes the template runnable without Snowflake or a GPU engine. The new script runs only the prescriptive phases (markdown MILP + demand planning LP) using pre-computed predictions from data/predictions_sample.csv. Verified end-to-end against the sandbox raiconfig.yaml -- Demand Planning converged to OPTIMAL. The full predict-then-optimize pipeline (with GNN training on H&M) remains retail_planning.py. The local runner is for quick tours and for regression- testing the prescriptive logic after changes. - new: retail_planning_local.py (CSV-only optimizer runner) - new: data/predictions_sample.csv (stub per-article GNN outputs) - README: adds local run path to quickstart and template structure
…I CSVs Goal: users should have two real, working paths through the template. 1. **Lightweight template GNN example with CSV data** -- `retail_planning_local.py` loads a small HM_MINI subset (~10K customers / 5K articles / 9.6K transactions) from bundled CSVs via `model.data()`, trains a transaction-level sales-regression GNN on CPU (~5-10 min), aggregates predictions to per-article demand, and runs both prescriptive optimizers. No H&M Snowflake data loading and no GPU required. Verified end-to-end against a RAI engine -- Markdown MILP OPTIMAL at $62,096.89, Demand Planning LP OPTIMAL at $8,985.53. 2. **Full Snowflake-based workflow** -- `retail_planning.py` (+ the `retail_train.py` / `retail_optimize.py` split) trains all three GNNs (sales, churn, purchase) on the full Kaggle H&M + RelBench task splits with GPU. README now names Kaggle as the dataset source explicitly. Changes: - `retail_planning_local.py`: rewritten. Previous version was optimizer-only with stub predictions (`predictions_sample.csv`); now trains a real GNN on HM_MINI CSVs following the rai-predictive-modeling + training skills. - `data/hm_mini/` (new): customers, articles, transactions, train/val/test sales splits (from HM_MINI), plus 12-article articles_inventory and production_capacity CSVs keyed by real HM_MINI article IDs. - `data/predictions_sample.csv` removed (no longer needed). - README: Prerequisites section distinguishes local (no external data) vs full (Kaggle H&M + RelBench + GPU). Quickstart leads with the local runner. Template-structure section documents the new data/hm_mini/ subtree.
…entrypoints The rai-predictive-training skill already ships register_and_load.py as a focused example of the registry pattern. Reimplementing it here as a third entrypoint (retail_train.py + retail_optimize.py + _retail_setup.py) duplicated ~700 lines of setup code for no additional pedagogical value. Keep the two non-duplicative paths: - retail_planning_local.py (zero-setup CPU demo on HM_MINI CSVs) - retail_planning.py (full Snowflake pipeline on Kaggle H&M + RelBench) README also: - Surfaces the Option A / Option B split in Quickstart. - Flags that step 5 (Snowflake settings) applies to Option B only. - Updates "What's included" to name the HM_MINI subset. - Refreshes the "How it works" GNN snippet to the aligned API (property_transformer=pt, exp_database/exp_schema, stream_logs, seed, temporal_strategy, 20 epochs). - Rewrites the Pipeline Stages block to reflect that the local runner only trains the sales GNN.
…adaptation reference The Snowflake + GPU path is unlikely to be what most users exercise first. Reshape the README so: - "What this template is for" names retail_planning_local.py as the starting point and retail_planning.py as the reference pattern for adapting to the user's own Snowflake data. - "What's included" surfaces the primary vs reference split. - Prerequisites frames Snowflake + GPU as adaptation requirements, not template requirements. - Quickstart ends at "python retail_planning_local.py". Adapting to your own Snowflake data is a separate follow-on section. - Expected output now reflects the local run's actual numbers ($62,096.89 markdown revenue, $8,985.53 demand planning cost). - Template structure annotates local as primary, full as reference.
…ort sort - README: remove bullets/blocks recommending specific n_epochs / lr / train_batch_size / head_layers values; keep descriptive code samples only. - retail_planning_local.py: merge duplicate relationalai.semantics import line (ruff I001). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
somacdivad
approved these changes
Apr 24, 2026
| 53892,Jade HW Skinny Denim TRS,32.60,13.00,400,0.18 | ||
| 57700,Pour It Up Push Bra,12.92,5.20,600,0.12 | ||
| 64286,Maggie high support,47.40,19.00,250,0.20 | ||
| 66518,Rose thong 7-pack,20.53,8.20,500,0.12 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Goal: give users a runnable, adaptable predict-then-optimize example they can actually exercise the predictive reasoners on. Before this PR,
retail_planning.pyrequired the full H&M dataset loaded in Snowflake + a GPU engine just to see the pipeline run — most users would never get past setup. This PR adds a zero-external-data local path, aligns both paths torai-agent-skillsPR #21, and reframes the README so users start locally and treat the Snowflake version as the reference for adapting to their own data.Two non-duplicative entrypoints:
retail_planning_local.py(primary, CPU, no external data). Trains a real sales-regression GNN on a bundled HM_MINI subset (~10K customers / 5K articles / 9.6K transactions), aggregates predictions per article, and runs both optimizers. End-to-end in ~5 min.retail_planning.py(reference pattern, GPU, full H&M). Trains all three GNNs (sales, churn, purchase) on Kaggle H&M + RelBench task splits. Not intended to be run as-is by most users — it's the worked example for adapting this pipeline to their own Snowflake data.Changes
Skill alignment (applied to
retail_planning.py)pt=pt→property_transformer=pt; drop deprecateddatabase=/schema=args.n_epochs5 → 20; print target distribution and baseline-mean RMSE before training.temporal_strategy="last"on sales/churn (previously only on purchase)._report(gnn)helper printsgnn.dataset.print_data_config()+ optionalvisualize_dataset(), gated byVERBOSE_DATASET.stream_logs=Falsedefault avoids non-TTY spinner flood;seed=42for reproducibility.drop=[]for PKs/FKs;integer=[]for new graph-derived features.Article.popularity_count/Customer.activity_countderived features demonstrating therai-graph-analysis→rai-predictive-*cross-skill pattern.has_time_columnedge-intermediary limitation, non-TTY spinner.Local entrypoint
retail_planning_local.py— real sales-regression GNN on bundled HM_MINI CSVs (CPU) + both optimizers. Self-contained.Data
data/hm_mini/(new) — HM_MINI customers/articles/transactions + sales task splits, plus 12-articlearticles_inventory/production_capacitykeyed to real HM_MINI IDs.README (reframed local-first)
python retail_planning_local.py; adapting to your own Snowflake data is a separate follow-on section.Test plan
python retail_planning_local.pyon bundled HM_MINI CSVs. Ran end-to-end: GNN trained (CPU) in ~1 min, predicted in ~2 min. Markdown MILP → OPTIMAL at $62,096.89. Demand Planning LP → OPTIMAL at $8,985.53. Process exited cleanly.python retail_planning.pyon the full Kaggle H&M dataset + GPU engine — not executed in this PR (compute cost). Aligned in code andpy_compilepasses; meant as an adaptation reference rather than a regression-test target.VERBOSE_DATASET=Truerun — verifyprint_data_config()surfaces expected feature types.Related