New predictive templates: subscriber_retention + demand_forecasting

[cafzal]

Summary

Adds two net-new Predictive (GNN) templates, completing the reasoner-coverage gap left by PR #48. Both ran end-to-end against jqb21724 and have customer-ready READMEs with real captured output.

Two templates

subscriber_retention (Telecommunications)

Multi-reasoner per-subscriber churn-risk pipeline (Graph → Rules → Predictive).

• Concepts: Subscriber (graph node, denormalized plan attrs), Call (edge intermediary)
• Stage 1 — Graph: PageRank on directed Subscriber→Subscriber call graph → Subscriber.pagerank continuous feature
• Stage 2 — Rules: Subscriber.outgoing_calls / incoming_calls derivation properties → integer features
• Stage 3 — Predictive: regression GNN on CHURN_RISK_SCORE (continuous 0–1 risk score). 20 epochs CPU. Stratified 70/15/15 split by SEGMENT.
• Stage 4 — Reporting: top-5 highest-predicted-risk subscribers per segment, plus test-set RMSE.
• Verified output: Test-set RMSE = 0.1386, top-5 per segment captured. Predictions cluster around segment mean (~0.24) on the synthetic data — README documents this and explains real-data feature requirements.

demand_forecasting (Retail)

Per-(store, item, date) demand-regression GNN over a Store / Item / ItemFamily / Sale knowledge graph.

• Concepts: Store, Item, ItemFamily (graph nodes), Sale (prediction unit, identifies by sale_id)
• Heterogeneous graph: Sale → Store, Sale → Item, Item → ItemFamily
• Predictive: regression GNN on Sale.unit_sales. 20 epochs CPU. Temporal split: last 60 days = test, previous 60 = val, rest = train (split done in pandas).
• Reporting: weekly per-(city, item family) forecast with actual vs predicted side-by-side, plus per-Sale and per-(city, family, week) RMSE.
• Verified output: Per-Sale RMSE = 7.2792, per-(city,family,week) RMSE = 150.8997, weekly forecast table captured. GNN cleanly learns base demand + weekday/weekend rhythm; December holiday spike under-shot (see SDK note below).

Customer onboarding paths (each README, two-path framing)

Each template ships with both a bundled / light and a full / your-own option:

Template	Bundled (light) — ships in ZIP	Full / public-dataset link
subscriber_retention	data/telco_mini/ — 4 CSVs (~1.2K subs, 6K calls, 1.2K plans, 0.7K billing). Synthetic, derived from internal DEMO_TELCO.RAW with PII dropped.	No public call-graph telco dataset exists. IBM Telco Customer Churn is tabular only (no calls), so the GNN graph path needs real CDR data or a synthetic generator. README documents the Snowflake-loading pattern for own-data.
demand_forecasting	data/favorita_mini/ — 3 CSVs (3 stores × 25 items × 365 days = 27,375 rows). Synthetic, generated by data/generate_favorita_mini.py with seasonality / promotions / Poisson noise.	Kaggle: Corporación Favorita Grocery Sales Forecasting (~125M rows). README has a full Snowflake-load + GPU walkthrough including optional oil, holidays_events, transactions tables.

Schema-permission setup (one-time)

Both templates expose EXP_DATABASE / EXP_SCHEMA constants near the top of the script so customers can repoint to a database they own. Required one-time setup as ACCOUNTADMIN (DDL spelled out in each README's Prerequisites):

CREATE DATABASE IF NOT EXISTS <YOUR_DB>;
CREATE SCHEMA IF NOT EXISTS <YOUR_DB>.EXPERIMENTS;
GRANT USAGE ON DATABASE <YOUR_DB> TO APPLICATION RELATIONALAI;
GRANT ALL PRIVILEGES ON SCHEMA <YOUR_DB>.EXPERIMENTS TO APPLICATION RELATIONALAI;

Defaults: subscriber_retention → TELCO_ENRICHMENT.EXPERIMENTS; demand_forecasting → FAVORITA_MINI.EXPERIMENTS. Customers must change to a database they own and rerun the DDL.

SDK gotcha applied to demand_forecasting

PyRel 1.0.x has a server-side DateTime/VString signature mismatch when has_time_column=True is paired with a date column at scale (also documented in dev_temp/predictive_enrichment_archive/handoff_full_paysim_cpu.md for fraud-detection at full PaySim scale). Reproduced for demand_forecasting (~27K rows, daily date column) — workaround applied:

• has_time_column=False
• Date kept as a plain datetime feature in PropertyTransformer (not time_col)
• temporal_strategy removed
• Train/Val/Test relationships time-stripped (f"{Sale} has {Any:value}" instead of f"{Sale} at {Any:date} has {Any:value}")
• Temporal split is preserved at the pandas level — train still on the past, eval on the future

The README's "Customize this template" section spells out the steps to re-enable temporal indexing once the SDK fix lands.

Test plan

Step	Status
python -m py_compile on both scripts	✅ passes
ruff check v1/subscriber_retention v1/demand_forecasting	✅ clean
python scripts/generate_version_indexes.py	✅ index up to date
Synthetic data generator (generate_favorita_mini.py) runs end-to-end	✅ 27,375 rows generated
subscriber_retention.py end-to-end against Snowflake	✅ Test-set RMSE 0.1386
demand_forecasting.py end-to-end against Snowflake	✅ Per-Sale RMSE 7.28, per-(city,family,week) RMSE 151
READMEs filled in with real captured output	✅ both populated
Customer onboarding paths (bundled-light + full-public) documented	✅ both READMEs, with explicit dataset links
Troubleshooting blocks (schema-permissions, worker-not-ready, stale-experiment, has_time_column at scale)	✅ both READMEs

Configuration / SDK learnings (for rai-agent-skills)

Real-run gotchas captured during this session and proposed for the relevant skills (rai-setup, rai-health, rai-predictive-training, rai-predictive-modeling):

• L-1 experiment-schema setup DDL + grants
• L-2 worker-not-ready recovery via SUSPEND_REASONER + RESUME_REASONER_ASYNC
• L-3 SDK matches train jobs to existing experiments by Model("...") name; bump on re-run
• L-4 has_time_column=True workaround at scale
• L-5 CREATE_GNN_SERVICE() is legacy / not the right escalation for QUEUED predictive jobs
• L-6 RELATIONALAI.API.JOBS history rolls; SDK can poll forever on a vanished job

Branch predictive-config-learnings (in rai-agent-skills repo, based on PR #30's branch) carries the SKILL.md edits — pushed but no PR opened yet, awaiting review.

Portfolio impact (after both PRs land)

Reasoner	Pre-PR48	Post-PR48	Post-this-PR
Prescriptive (single)	17	17	17
Graph (single)	7	5	5
Rules (single)	1	2	2
Predictive (single)	0	0	1
Multi-reasoner	7	7	8
Scaffold / starter	1	1	1
Total active	33	32	34

demand_forecasting is the new single-reasoner Predictive entry. subscriber_retention is multi-reasoner (Graph + Predictive): PageRank on the call graph is a real Graph-reasoner usage, the GNN is the Predictive head.

🤖 Generated with Claude Code

[github-actions]

The docs preview for this pull request has been deployed to Vercel!

✅ Preview:	https://relationalai-docs-a3auhcyup-relationalai.vercel.app/build/templates
🔍 Inspect:	https://vercel.com/relationalai/relationalai-docs/AJ5mAnUvhvdwUh8BiHFNALRRVJg8

[ifountalis]

Strong PR overall — the SDK-workaround disclosure is honest, RMSE numbers are captured from real runs, and both templates ship customer-ready READMEs. A few small items worth tightening before merge.

HIGH — small doc-truthfulness edits

• v1/subscriber_retention/subscriber_retention.py:30 — module docstring says "top-15 highest-predicted-risk subscribers per segment" but TOP_N_PER_SEGMENT = 5 (line 53) and the README + actual print say "Top 5". Change to "top-N" or "top-5".

• v1/subscriber_retention/README.md:118 — the Expected output block shows

  ============================================================
  Stage 3: Predictive -- subscriber churn-risk regression GNN (CPU)
  ============================================================
  

  but the script (line 242) actually prints Predictive: subscriber churn-risk regression GNN (CPU) — the Stage 3: prefix is fabricated. Either drop it from the README or add a stage label to the print.

• v1/subscriber_retention/subscriber_retention.py:4–5 — top-of-module docstring claims "no Snowflake data loading", but the template needs Snowflake for EXP_DATABASE = "TELCO_ENRICHMENT" (the GNN writes experiment artifacts there, and the README's Prerequisites spells out the schema-permission DDL). Tighten to "no source-data Snowflake loading; the GNN reasoner still uses Snowflake for experiment artifacts (see README Prerequisites)."

• v1/demand_forecasting/demand_forecasting.py:13–14 — module docstring says "Train a regression GNN with a time column on Sale.date predicting unit_sales", but line 218 sets has_time_column=False and the inline NOTE (lines 128–135) explains the SDK workaround. The README is honest about this; the docstring should be too.

MEDIUM

• v1/subscriber_retention/subscriber_retention.py:159–164 — the PropertyTransformer.drop= list has sub_id and postal_code but not churn_risk_score (the regression target). The target isn't in any feature list either, so it shouldn't auto-include, but adding it to drop makes the no-leakage invariant explicit and protects future adapters:

  drop=[
      Subscriber.sub_id,
      Subscriber.postal_code,
      Subscriber.churn_risk_score,  # target — never a feature
  ],

• PR description ↔ front matter mismatch on reasoner taxonomy. The "Portfolio impact" table classifies both new templates as Predictive (single), but v1/subscriber_retention/README.md front matter declares reasoning_types: [Graph, Predictive] (multi-reasoner) — consistent with the README narrative "wires a call-graph signal into the model… Graph reasoner (PageRank)… Predictive reasoner trains a GNN regression head". Either fix the PR description's portfolio counts (1 single-reasoner predictive + 1 multi-reasoner) or change the front matter to [Predictive]. The README narrative argues for the front matter being right.

• Hardcoded model names (subscriber_retention.py:68, demand_forecasting.py:65). Both READMEs have a "Re-running with a stale experiment causes training job failed" troubleshooting block telling customers to bump the model name on re-run, but the defaults (subscriber_retention_local, demand_forecasting_local) are version-less. Adding a _v1 suffix would model the bump pattern visually so customers see the convention before they hit the failure.

• v1/subscriber_retention/README.md:147 — billing_events.csv is bundled (681 lines) and called out as "available for customization", but no concrete worked example exists in Customize this template. Either drop the CSV (keep the bundle lean) or add a 5-line example wiring late_payment_count as an integer feature.

On has_time_column=False — confirmed valid

Verified that no time/date column appears in any task table:

• TrainTable: [sale_id, unit_sales]
• ValTable: [sale_id, unit_sales]
• TestTable: [sale_id]

The relationships correspondingly omit at {Any:date} (lines 184–194), time_col= is unset in PropertyTransformer, and Sale.date flows through as a regular datetime feature on the Sale node. The four pieces — task-table columns, relationship signatures, PropertyTransformer fields, GNN parameter — form an internally consistent set, and the configuration matches the workaround already documented in v1/retail_planning/README.md:377–382. The trade-off (no GNN temporal aggregation; December holiday spike under-shot) is honestly disclosed, and the "Re-enable temporal indexing" recipe in Customize this template gives the four-step path back when the SDK fix lands.

Optional follow-up (not blocking): the SDK bug fires at this scale (~18K train rows), but retail_planning_local works fine at ~7.6K train rows with has_time_column=True. Shrinking the bundled demand_forecasting dataset below the SDK-bug threshold would let the bundled run demonstrate the "happy-path" with time column on, while the README's "Run on full Favorita" section explains when the workaround becomes necessary at scale. Worth raising as a separate discussion.

Strengths

• Honest SDK-workaround disclosure with the full four-step re-enable recipe in Customize this template.
• Real captured RMSE numbers from end-to-end runs (0.1386 / 7.28 / 151) — not placeholders.
• Stratified split (subscriber_retention, by SEGMENT) and temporal split (demand_forecasting, last 60 / previous 60 days) — both correct for their respective tasks; no leakage.
• Schema-permission DDL spelled out per template — saves a customer support ticket.
• Related templates cross-references between siblings.
• Front matter complete (title, description, experience_level, industry, reasoning_types, tags, featured) and alphabetic insertion in v1/README.md correct for both entries.
• Reproducibility: SEED=42 set in the script, the PropertyTransformer, and the data generator.

[somacdivad]

Looks good, thanks!

[somacdivad]

@cafzal I already approved, but please make the following changes before mergine.

[somacdivad]

Suggested change

	featured: false
	featured: false
	private: true

This will filter it from the public site