From 34d5d51b69d98092cd3f0c3350565a6f5c85e6e8 Mon Sep 17 00:00:00 2001 From: pkouki Date: Fri, 15 May 2026 11:48:47 +0300 Subject: [PATCH 1/6] Update retail_planning README for predictive reasoner setup - Bump minimum relationalai SDK version to 1.3.1 (required for predictive reasoner) - Replace `rai init` quickstart step with instructions to edit raiconfig.yaml directly, since the SDK now prioritizes .yaml over the .toml that rai init produces - Add quickstart step with SQL commands to create the experiment database/schema in Snowflake and grant required permissions to the RAI Native App - Remove inapplicable has_time_column=True troubleshooting entry Co-Authored-By: Claude Sonnet 4.6 --- v1/retail_planning/README.md | 38 ++++++++++++++++++++---------------- 1 file changed, 21 insertions(+), 17 deletions(-) diff --git a/v1/retail_planning/README.md b/v1/retail_planning/README.md index 9480cdfe..92f0b792 100644 --- a/v1/retail_planning/README.md +++ b/v1/retail_planning/README.md @@ -19,7 +19,7 @@ tags: ## What this template is for -Retailers face interconnected decisions: which items will sell, which customers are at risk of leaving, what discounts to offer, and how much inventory to stock. Traditionally these are solved in isolation -- demand forecasting in one silo, pricing optimization in another, supply planning in a third. This template shows how to unify them in a single **predict-then-optimize** pipeline using RelationalAI. +Retailers face interconnected decisions: which items will sell, which customers are at risk of leaving, what discounts to offer, and how much inventory to stock. Traditionally these are solved in isolation -- demand forecasting in one silo, pricing optimization in another, supply planning is a third. This template shows how to unify them in a single **predict-then-optimize** pipeline using RelationalAI. **Start with `retail_planning_local.py`** -- it trains a real sales-regression GNN on a bundled H&M subset (CPU, no external data), aggregates predictions per article, and runs both optimizers. A few minutes end-to-end. It's the quickest way to see the whole pattern working. @@ -27,7 +27,7 @@ Retailers face interconnected decisions: which items will sell, which customers > [!IMPORTANT] > The RelationalAI **predictive reasoner (GNN)** used in this template is in -> early access. The API surface (`GNN`, `PropertyTransformer`, task +> private preview. The API surface (`GNN`, `PropertyTransformer`, task > relationships) may still change between releases; check the > `rai-predictive-modeling` and `rai-predictive-training` skills for the > current guidance before adapting to production data. @@ -54,7 +54,7 @@ Assumes familiarity with Python, basic ML concepts (classification, regression, - **Runners**: - `retail_planning_local.py` -- **primary, runnable out of the box.** Trains a sales-regression GNN on the bundled HM_MINI subset and solves both optimizers. - `retail_planning.py` -- **reference pattern** for adapting the same pipeline to your own Snowflake data. Trains three GNNs (sales, churn, purchase) against a full H&M dataset in Snowflake. -- **Model**: Three GNN tasks on the H&M knowledge graph (Customer, Article, Transaction), two prescriptive problems consuming their output +- **Model**: Three GNN tasks on the H&M knowledge graph (Customer, Article, Transaction), two prescriptive problems consuming their output. - **Sample data**: - `data/hm_mini/` -- bundled H&M subset (~10K customers / 5K articles / 9.6K transactions) with sales task splits. This is what the local runner trains on. - `data/*.csv` -- optimizer parameters: discounts, weeks, article inventory, production capacity. @@ -83,7 +83,7 @@ you'll additionally need: ### Tools - Python >= 3.10 -- RelationalAI Python SDK (`relationalai`) >= 1.0.14 +- RelationalAI Python SDK (`relationalai`) >= 1.3.1 ## Quickstart @@ -109,11 +109,25 @@ you'll additionally need: ``` 4. Configure: - ```bash - rai init + Open `raiconfig.yaml` and fill in your Snowflake credentials (`account`, `user`, `password`, `warehouse`, `rai_app_name`). The file is pre-populated with placeholder values — replace them with your actual account details. + +5. Set up the experiment schema in Snowflake: + + Before running, create the database and schema used to store GNN experiments, and grant the required permissions to the RAI Native App. Run the following in a Snowflake worksheet: + + ```sql + CREATE DATABASE IF NOT EXISTS HM_MINI; + CREATE SCHEMA IF NOT EXISTS HM_MINI.EXPERIMENTS; + GRANT USAGE ON DATABASE HM_MINI TO APPLICATION RELATIONALAI; + GRANT USAGE ON SCHEMA HM_MINI.EXPERIMENTS TO APPLICATION RELATIONALAI; + GRANT CREATE EXPERIMENT ON SCHEMA HM_MINI.EXPERIMENTS TO APPLICATION RELATIONALAI; + GRANT CREATE MODEL ON SCHEMA HM_MINI.EXPERIMENTS TO APPLICATION RELATIONALAI; ``` -5. Run the local demo on the bundled H&M subset (CPU, a few minutes): + > [!NOTE] + > Replace `RELATIONALAI` with the `rai_app_name` you set in `raiconfig.yaml` if it differs. + +6. Run the local demo on the bundled H&M subset (CPU, a few minutes): ```bash python retail_planning_local.py ``` @@ -381,16 +395,6 @@ dp.minimize(prod_cost_total + hold_cost_total + unmet_cost_total) collapsed to the mean — revisit the PropertyTransformer and task setup. -
-has_time_column=True fails validation - -Known limitation flagged in the rai-predictive-training skill: when the concept -carrying `time_col` (here, `Transaction`) is used only as an edge intermediary, -validation can fail with "no time column defined in data tables." Workaround: -set `has_time_column=False` on the affected GNN and remove the `"at"` clause -from its Relationship templates until the GNN team resolves this. -
-
Sales regression R² is low or negative From 63989552a5788e2c976d4c335c90097c2c8d0055 Mon Sep 17 00:00:00 2001 From: pkouki Date: Fri, 15 May 2026 16:14:24 +0300 Subject: [PATCH 2/6] Bump minimum relationalai version to 1.4.1 The predictive reasoner requires relationalai >= 1.4.1. Updates both the pyproject.toml dependency and the README prerequisites line. Co-Authored-By: Claude Sonnet 4.6 --- v1/retail_planning/README.md | 2 +- v1/retail_planning/pyproject.toml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/v1/retail_planning/README.md b/v1/retail_planning/README.md index 92f0b792..db26926d 100644 --- a/v1/retail_planning/README.md +++ b/v1/retail_planning/README.md @@ -83,7 +83,7 @@ you'll additionally need: ### Tools - Python >= 3.10 -- RelationalAI Python SDK (`relationalai`) >= 1.3.1 +- RelationalAI Python SDK (`relationalai`) >= 1.4.1 ## Quickstart diff --git a/v1/retail_planning/pyproject.toml b/v1/retail_planning/pyproject.toml index f05c851d..c21ecac4 100644 --- a/v1/retail_planning/pyproject.toml +++ b/v1/retail_planning/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: retail_planning (PyRel v1)" readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai==1.0.14", + "relationalai>=1.4.1", "pandas>=2.0", ] From 17c2c1690f4c53065c99ce7f73c985c6bd29eebb Mon Sep 17 00:00:00 2001 From: pkouki Date: Fri, 15 May 2026 16:28:53 +0300 Subject: [PATCH 3/6] Install relationalai with [gnn] extra The predictive reasoner requires GNN dependencies, which are pulled in via the [gnn] extra. Co-Authored-By: Claude Sonnet 4.6 --- v1/retail_planning/pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/v1/retail_planning/pyproject.toml b/v1/retail_planning/pyproject.toml index c21ecac4..4c6c6142 100644 --- a/v1/retail_planning/pyproject.toml +++ b/v1/retail_planning/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: retail_planning (PyRel v1)" readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai>=1.4.1", + "relationalai[gnn]>=1.4.1", "pandas>=2.0", ] From 0d6465d2bd5a9371298efab0bd6e289d78f78e9a Mon Sep 17 00:00:00 2001 From: pkouki Date: Thu, 21 May 2026 12:17:22 +0300 Subject: [PATCH 4/6] Pin relationalai to ==1.4.1 and revert configure step to rai init - pyproject.toml and README now pin relationalai[gnn]==1.4.1 (exact) - Quickstart step 4 reverted to `rai init` Co-Authored-By: Claude Sonnet 4.6 --- v1/retail_planning/README.md | 6 ++++-- v1/retail_planning/pyproject.toml | 2 +- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/v1/retail_planning/README.md b/v1/retail_planning/README.md index db26926d..641054c3 100644 --- a/v1/retail_planning/README.md +++ b/v1/retail_planning/README.md @@ -83,7 +83,7 @@ you'll additionally need: ### Tools - Python >= 3.10 -- RelationalAI Python SDK (`relationalai`) >= 1.4.1 +- RelationalAI Python SDK (`relationalai`) == 1.4.1 ## Quickstart @@ -109,7 +109,9 @@ you'll additionally need: ``` 4. Configure: - Open `raiconfig.yaml` and fill in your Snowflake credentials (`account`, `user`, `password`, `warehouse`, `rai_app_name`). The file is pre-populated with placeholder values — replace them with your actual account details. + ```bash + rai init + ``` 5. Set up the experiment schema in Snowflake: diff --git a/v1/retail_planning/pyproject.toml b/v1/retail_planning/pyproject.toml index 4c6c6142..2d33c10b 100644 --- a/v1/retail_planning/pyproject.toml +++ b/v1/retail_planning/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: retail_planning (PyRel v1)" readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai[gnn]>=1.4.1", + "relationalai[gnn]==1.4.1", "pandas>=2.0", ] From 28547a595ed90ed2625b65ddd3936c5e9dcd3003 Mon Sep 17 00:00:00 2001 From: nikolaoszygouras-rai Date: Thu, 21 May 2026 12:48:03 +0300 Subject: [PATCH 5/6] Merge pull request #73 from RelationalAI/fix/retail-planning-explicit-opt-article-relationship Fix: explicit opt_article relationship declaration in retail_planning_local.py --- v1/retail_planning/retail_planning_local.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/v1/retail_planning/retail_planning_local.py b/v1/retail_planning/retail_planning_local.py index 96097ffa..fda4fec9 100644 --- a/v1/retail_planning/retail_planning_local.py +++ b/v1/retail_planning/retail_planning_local.py @@ -358,6 +358,8 @@ pc.pc_initial_inventory(prod_data.initial_inventory), ) +ProdCapacity.opt_article = model.Relationship( + f"{ProdCapacity} has {OptArticle:opt_article}") model.define(ProdCapacity.opt_article(OptArticle)).where( ProdCapacity.pc_article_id == OptArticle.opt_article_id) From 192b987b32d0201698e7b526ae73eaf80fcc64b5 Mon Sep 17 00:00:00 2001 From: pkouki Date: Thu, 21 May 2026 13:49:32 +0300 Subject: [PATCH 6/6] Add ensure_change_tracking note after rai init step Tell users to add `data.ensure_change_tracking: true` to raiconfig.yaml after rai init generates it. Co-Authored-By: Claude Sonnet 4.6 --- v1/retail_planning/README.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/v1/retail_planning/README.md b/v1/retail_planning/README.md index 641054c3..18bd603a 100644 --- a/v1/retail_planning/README.md +++ b/v1/retail_planning/README.md @@ -113,6 +113,13 @@ you'll additionally need: rai init ``` + After `rai init` generates the config file, add the following to your `raiconfig.yaml`: + + ```yaml + data: + ensure_change_tracking: true + ``` + 5. Set up the experiment schema in Snowflake: Before running, create the database and schema used to store GNN experiments, and grant the required permissions to the RAI Native App. Run the following in a Snowflake worksheet: