diff --git a/README.md b/README.md index 2bd9d025..9f60fc37 100644 --- a/README.md +++ b/README.md @@ -17,11 +17,10 @@ The index below covers the current templates. Expand an industry to see its temp
-Cross-Industry (4) +Cross-Industry (3) | Template | Reasoners | Description | | --- | --- | --- | -| [rai-agent-scaffold](rai-agent-scaffold/) | Graph | Scaffold for packaging a RelationalAI semantic model as a Snowflake Cortex agent and exposing it through Snowflake Intelligence. | | [shift_assignment](shift_assignment/) | Prescriptive | Assign workers to shifts based on availability to meet coverage requirements. | | [simple-start](simple-start/) | Graph | A minimal notebook to connect to Snowflake, model a small graph, and compute betweenness centrality with RelationalAI. | | [wildlife-conservation-network](wildlife-conservation-network/) | Graph | Identify collaboration clusters among wildlife-conservation organizations with Louvain community detection and degree centrality, surfacing key coordination hubs for resource sharing. | diff --git a/ad_spend_allocation/README.md b/ad_spend_allocation/README.md index 1c447877..f91eb00a 100644 --- a/ad_spend_allocation/README.md +++ b/ad_spend_allocation/README.md @@ -55,7 +55,7 @@ This template also answers the follow-up question every planner asks: if we had ### Tools - Python >= 3.10. -- RelationalAI Python SDK (`relationalai == 1.0.14`). +- RelationalAI Python SDK (`relationalai == 2.1.1`). ## Quickstart diff --git a/ad_spend_allocation/pyproject.toml b/ad_spend_allocation/pyproject.toml index 939609aa..079f84df 100644 --- a/ad_spend_allocation/pyproject.toml +++ b/ad_spend_allocation/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: ad_spend_allocation (PyRel v1)" readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai==1.0.14", + "relationalai==2.1.1", "pandas", ] diff --git a/bom-reachability/README.md b/bom-reachability/README.md index 68f1faa2..e1b8c934 100644 --- a/bom-reachability/README.md +++ b/bom-reachability/README.md @@ -184,7 +184,7 @@ Focus on the first changes most users will make. ### Tune parameters -- **Assembly-path depth** — `MAX_ASSEMBLY_HOPS` (the `repeat(1, MAX_ASSEMBLY_HOPS)` bound) caps how many tiers `all_paths()` enumerates. Raise it if your BOM is deeper than the bundled three tiers; lower it to keep path counts manageable on wide structures. +- **Assembly-path depth** — `MAX_ASSEMBLY_HOPS` (the `repeat(1, MAX_ASSEMBLY_HOPS)` bound) caps how many tiers `.all().paths()` enumerates. Raise it if your BOM is deeper than the bundled three tiers; lower it to keep path counts manageable on wide structures. ### Extend the model diff --git a/bom-reachability/bom_reachability.py b/bom-reachability/bom_reachability.py index b31d0d64..70afafba 100644 --- a/bom-reachability/bom_reachability.py +++ b/bom-reachability/bom_reachability.py @@ -13,7 +13,7 @@ Assembly path enumeration (PREVIEW, requires relationalai>=1.15): enumerate the bottom-up assembly chains that build each finished good. Derives a binary SKU->SKU "feeds into" edge from the BillOfMaterials intermediary (input feeds - output), enumerates every assembly path with model.path(...).all_paths(), + output), enumerates every assembly path with model.path(...).all().paths(), filters to the maximal (longest non-extendable) chains so sub-paths are suppressed, and persists each finished good's longest assembly depth back onto the SKU ontology. @@ -201,12 +201,12 @@ ).define(sku_in.feeds(sku_out)) # Enumerate every assembly chain. The BOM is a DAG (raw materials -> components -# -> finished goods, never back), so .all_paths() already yields simple paths -- +# -> finished goods, never back), so .all().paths() already yields simple paths -- # there is no cycle risk, and the repeat bound only needs to cover the BOM depth. # Deepest chain here is raw_material -> component -> finished_good (2 hops); we # allow extra headroom so deeper BOMs enumerate fully. MAX_ASSEMBLY_HOPS = 4 -p = model.path(SKU.feeds.repeat(1, MAX_ASSEMBLY_HOPS)).all_paths() +p = model.path(SKU.feeds.repeat(1, MAX_ASSEMBLY_HOPS)).all().paths() assembly_df = ( model.where(p) .select( diff --git a/bom-reachability/pyproject.toml b/bom-reachability/pyproject.toml index 13e64c95..1e29ee54 100644 --- a/bom-reachability/pyproject.toml +++ b/bom-reachability/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: bill of materials dependency tracing with readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai==1.15.0", + "relationalai==2.1.1", "pandas>=2.0.0", ] diff --git a/bom-reachability/runbook.md b/bom-reachability/runbook.md index e1ef9d48..ba164800 100644 --- a/bom-reachability/runbook.md +++ b/bom-reachability/runbook.md @@ -45,7 +45,7 @@ Each prompt is pasted into a fresh agent session loaded with the named `/rai-*` **Prompt:** /rai-graph-analysis Reachability gives dependency pairs, but we want the actual build sequences. Enumerate every bottom-up assembly chain — each ordered route from a raw material up through its components to a finished good. Treat an input that feeds an output as a step in the chain. -**Response:** Where reachability returns pairs, path enumeration returns the ordered build routes. Deriving a SKU→SKU "feeds into" edge from the `BillOfMaterials` intermediary (input feeds output — the reverse of "depends on") and enumerating it with `.all_paths()` yields 18 assembly paths (up to 4 hops). Because the BOM is acyclic, every enumerated path is already a simple chain — no cycle risk. They range from 1-hop direct feeds (e.g. Mobile Processor A15 → ProPhone X1) to 2-hop chains like NAND Flash Memory Die → Mobile Processor A15 → ProPhone X1. +**Response:** Where reachability returns pairs, path enumeration returns the ordered build routes. Deriving a SKU→SKU "feeds into" edge from the `BillOfMaterials` intermediary (input feeds output — the reverse of "depends on") and enumerating it with `.all().paths()` yields 18 assembly paths (up to 4 hops). Because the BOM is acyclic, every enumerated path is already a simple chain — no cycle risk. They range from 1-hop direct feeds (e.g. Mobile Processor A15 → ProPhone X1) to 2-hop chains like NAND Flash Memory Die → Mobile Processor A15 → ProPhone X1. ## 6. Maximal chains and assembly depth diff --git a/book_slate_recommendation/README.md b/book_slate_recommendation/README.md index df895340..1071f584 100644 --- a/book_slate_recommendation/README.md +++ b/book_slate_recommendation/README.md @@ -57,7 +57,7 @@ This template composes the slate as a single optimization decision rather than a ### Tools - Python 3.10 or newer. -- RelationalAI Python SDK (`relationalai == 1.1.0`). +- RelationalAI Python SDK (`relationalai == 2.1.1`). ## Quickstart @@ -170,7 +170,7 @@ For the full concept and property definitions, see `book_slate_recommendation.py The pipeline runs in three stages over the shared ontology. Its architectural centerpiece is the bounded knowledge-graph walk: without the paths library there are no candidates and no optimization variables. -**Stage 1 — Knowledge-graph path walks (candidate generation).** The path walker traverses `Item.connected_to` (the symmetric union of `read`, `written_by`, `about`, and `similar_to`) from each user up to `MAX_HOPS = 2` hops. With a `Book` endpoint, the candidate set is the union of length-1 walks (`User -> read_Book`, later excluded because already read) and length-2 walks (`User -> read_Book -> similar_Book`). Each reachable `(user, book)` becomes a `Candidate`. The per-`(user, candidate)` typed counts — shared-author and shared-subject joins against the user's read history, plus the count of walker-enumerated paths — feed the explanation floor, the cold-start cap, and the objective. Each count is defined for every candidate so a candidate with no matches still gets a value, and `path_count_total` sums the three. +**Stage 1 — Knowledge-graph path walks (candidate generation).** The path pattern `model.path(user, Item.connected_to.repeat(1, MAX_HOPS), book)` walks `Item.connected_to` (the symmetric union of `read`, `written_by`, `about`, and `similar_to`) from each user up to `MAX_HOPS = 2` hops. The matched walks are the union of length-1 walks (`User -> read_Book`, later excluded because already read) and length-2 walks (`User -> read_Book -> similar_Book`). Each `(user, book)` pair the pattern connects (`.exists()`) becomes a `Candidate`. The per-`(user, candidate)` typed counts — shared-author and shared-subject joins against the user's read history, plus the number of walks between the pair (`.all().count()`) — feed the explanation floor, the cold-start cap, and the objective. Each count is defined for every candidate so a candidate with no matches still gets a value, and `path_count_total` sums the three. **Stage 2 — Graph analysis (hero-slot embeddedness).** A `Graph` is built from `Book.similar_to`, and triangle count returns the per-book count of similarity triangles each book participates in, stored as `Book.triangle_count`. Triangle count is graph-derived: it depends on the topology of the similarity graph, not on a per-book scalar that could be supplied externally. Stage 3 uses it to pin the hero slot to a densely embedded book. @@ -266,7 +266,7 @@ The fetcher caches every API response under `data/_cache/` keyed by URL, so subs ### Reasoner reference -- [Paths library](https://docs.relational.ai/) — bounded knowledge-graph walks with `.repeat(...)` and `all_paths()`. +- [Paths library](https://docs.relational.ai/) — bounded knowledge-graph walks with `.repeat(...)`, `.exists()`, and `.all().count()`. - [Graph reasoner](https://docs.relational.ai/) — building a `Graph`, node-concept binding, and structural metrics such as triangle count. - [Prescriptive reasoner](https://docs.relational.ai/) — the `Problem` API, integer decisions, constraints, and objectives on MiniZinc and HiGHS. diff --git a/book_slate_recommendation/book_slate_recommendation.py b/book_slate_recommendation/book_slate_recommendation.py index 32553595..c02034ca 100644 --- a/book_slate_recommendation/book_slate_recommendation.py +++ b/book_slate_recommendation/book_slate_recommendation.py @@ -4,8 +4,8 @@ them by slate position. Slot 1 is hero (top of row); position-decay engagement is the canonical recsys model, so the order matters as much as the selection. The architectural centerpiece is bounded -heterogeneous-KG walks via the PyRel paths library -(``relationalai.semantics.std.paths``): the walks generate the +heterogeneous-KG walks via the PyRel path library +(``relationalai.semantics.std.path``): the walks generate the Candidate concept and the per-(user, candidate) explanation evidence that feeds the Prescriptive reasoner. The Graph reasoner separately contributes per-Book ``triangle_count`` @@ -13,15 +13,16 @@ 1 so the highest-engagement position carries graph-derived structural quality: -- Bounded KG walks (paths library, central): - ``Item.connected_to.repeat(1, 2).all_paths()`` walks enumerate - ``User -> read_Book`` (length 1; pruned downstream by the +- Bounded KG walks (path library, central): + ``model.path(user, Item.connected_to.repeat(1, 2), book)`` matches + ``User -> read_Book`` walks (length 1; pruned downstream by the already-read exclusion) and ``User -> read_Book -> similar_Book`` - (length 2). Each walker-reachable (user, book) becomes a - ``Candidate``. The per-(user, candidate) typed counts - (``path_count_via_author``, ``_via_subject``, ``_via_kg_walk``) - feed the engagement-weighted explanation floor and objective, and - surface as the per-pick explanation block. + walks (length 2). Each user and book joined by a walk + (``.exists()``) becomes a ``Candidate``. The per-(user, candidate) + typed counts (``path_count_via_author``, ``_via_subject``, + ``_via_kg_walk``, the last from ``.all().count()``) feed the + engagement-weighted explanation floor and objective, and surface + as the per-pick explanation block. - Graph reasoner (hero pin): triangle count over ``Book.similar_to`` per Book. Drives ``hero_pin_ic`` -- slot 1 (top of row) must come from the densely-embedded subset, so the most-impressed position @@ -63,7 +64,6 @@ ) from relationalai.semantics.reasoners.graph import Graph from relationalai.semantics.reasoners.prescriptive import Problem -from relationalai.semantics.std.paths import PathTraversal # -------------------------------------------------- # Configure inputs @@ -374,37 +374,36 @@ def _assert_in_set(df, col, allowed, source): # -------------------------------------------------- # Walk the unified ``Item.connected_to`` edge from each User up to -# MAX_HOPS hops. The path-walker bounds enumeration to MAX_HOPS, so -# the candidate set is the bounded reachable set under the KG. -kg_paths = model.path( +# MAX_HOPS hops. The path pattern bounds the walk to MAX_HOPS, so the +# candidate set is the bounded reachable set under the KG. Naming the +# endpoints as a User and a Book lets the same pattern answer both +# "is this book reachable from this user" (``exists``, no +# enumeration) and "how many walks reach it" (``count``). +walk_user, walk_book = User.ref(), Book.ref() +kg_walks = model.path( + walk_user, Item.connected_to.repeat(1, MAX_HOPS), -).all_paths() - -# Candidate set: any (user, book) reached by a User-anchored bounded -# KG walk ending at a Book node. The already-read exclusion lands as -# a ``slot == K+1`` IC (``exclude_read_ic`` below) rather than as a -# pre-pruning filter on this rule -- which keeps the candidate- -# derivation rule a pure positive join over the path walker, at the -# minor CSP cost of a few wasted integer variables forced to K+1. + walk_book, +) + +# Candidate set: any (user, book) joined by a bounded KG walk. Books the +# user already read stay candidates; the already-read exclusion below +# forces them to the unpicked slot K+1. Candidate = model.Concept( "Candidate", identify_by={"user_id": Integer, "book_id": Integer}, ) -u_cand, b_cand = User.ref(), Book.ref() -p_cand = PathTraversal.ref() -model.define(Candidate.new(user_id=u_cand.id, book_id=b_cand.id)).where( - kg_paths(p_cand), - p_cand.nodes(0, u_cand), - p_cand.nodes(p_cand.length, b_cand), +model.define(Candidate.new(user_id=walk_user.id, book_id=walk_book.id)).where( + kg_walks.exists(), ) # Per-(user, candidate) explanation features: counts of distinct # typed connections between the candidate and the user's read # history. # -# Each ``count`` expression is followed by ``| 0`` so the property is -# defined for *every* Candidate (not only those with at least one -# match). PyRel aggregates over an empty group produce no row, and +# The author and subject ``count`` expressions are followed by ``| 0`` +# so the property is defined for *every* Candidate (not only those +# with at least one match). PyRel aggregates over an empty group produce no row, and # the position-weighted explanation IC would silently drop Candidates # whose property is undefined. # @@ -467,21 +466,13 @@ def _assert_in_set(df, col, allowed, source): # via-walk: number of bounded heterogeneous KG paths from this user # to the candidate (the actual paths-walk count -- the headline -# explanation-strength signal). -p_s = PathTraversal.ref() +# explanation-strength signal). Every Candidate has at least one walk, +# so this count is always defined. model.define(Candidate.path_count_via_kg_walk(c, n)).where( Candidate(c), - n - == count(p_s) - .per(c) - .where( - kg_paths(p_s), - c.user_id == u_c.id, - c.book_id == b_c.id, - p_s.nodes(0, u_c), - p_s.nodes(p_s.length, b_c), - ) - | 0, + c.user_id == walk_user.id, + c.book_id == walk_book.id, + n == kg_walks.all().count().per(walk_user, walk_book), ) # Total: sum across types as a single integer feature for cold-start @@ -563,8 +554,11 @@ def _assert_in_set(df, col, allowed, source): # ``Candidate.slot <= SLATE_SIZE_K`` lives inside ``count``'s second # argument, not the outer ``where`` -- PyRel rejects decision- # variable-dependent expressions in top-level ``where`` clauses -# because those iterate over data rows. -slate_size_ic = model.require( +# because those iterate over data rows. Every per-group IC below names +# its group keys (``Candidate.user_id``, plus ``Slot``, ``Author`` or +# ``Subject``) in the ``where`` clause: that clause is what gives the +# constraint one instance per group. +slate_size_ic = model.where(Candidate.user_id).require( count(Candidate, Candidate.slot <= SLATE_SIZE_K).per(Candidate.user_id) == SLATE_SIZE_K ) problem.satisfy(slate_size_ic) @@ -576,7 +570,7 @@ def _assert_in_set(df, col, allowed, source): # positions 1..K. Per-pair count cap is the CSP-native shape for # all-different over decision variables once you also pin the # total-pick count. -slot_uniqueness_ic = model.require( +slot_uniqueness_ic = model.where(Candidate.user_id, Slot).require( count(Candidate, Candidate.slot == Slot.pos).per(Candidate.user_id, Slot) <= 1 ) problem.satisfy(slot_uniqueness_ic) @@ -608,6 +602,7 @@ def _assert_in_set(df, col, allowed, source): author_uniqueness_ic = model.where( Book.id == Candidate.book_id, Book.written_by(Book, Author), + Candidate.user_id, ).require(count(Candidate, Candidate.slot <= SLATE_SIZE_K).per(Candidate.user_id, Author) <= 1) problem.satisfy(author_uniqueness_ic) @@ -620,6 +615,7 @@ def _assert_in_set(df, col, allowed, source): subject_span_ic = model.where( Book.id == Candidate.book_id, Book.about(Book, Subject), + Candidate.user_id, ).require( count(Candidate, Candidate.slot <= SLATE_SIZE_K).per(Candidate.user_id, Subject) <= MAX_PER_SUBJECT @@ -631,6 +627,7 @@ def _assert_in_set(df, col, allowed, source): freshness_ic = model.where( Book.id == Candidate.book_id, Book.age_days <= FRESH_WINDOW_DAYS, + Candidate.user_id, ).require( count(Candidate, Candidate.slot <= SLATE_SIZE_K).per(Candidate.user_id) >= FRESHNESS_FLOOR ) @@ -640,6 +637,7 @@ def _assert_in_set(df, col, allowed, source): originals_ic = model.where( Book.id == Candidate.book_id, Book.in_house == 1, + Candidate.user_id, ).require( count(Candidate, Candidate.slot <= SLATE_SIZE_K).per(Candidate.user_id) >= ORIGINALS_FLOOR ) @@ -648,6 +646,7 @@ def _assert_in_set(df, col, allowed, source): # Cold-start cap: at most COLD_START_CAP weakly-explained picks. cold_start_ic = model.where( Candidate.path_count_total < WEAK_EXPLANATION_THRESHOLD, + Candidate.user_id, ).require(count(Candidate, Candidate.slot <= SLATE_SIZE_K).per(Candidate.user_id) <= COLD_START_CAP) problem.satisfy(cold_start_ic) @@ -661,6 +660,7 @@ def _assert_in_set(df, col, allowed, source): hero_pin_ic = model.where( Book.id == Candidate.book_id, Book.triangle_count >= HERO_EMBEDDEDNESS_THRESHOLD, + Candidate.user_id, ).require(count(Candidate, Candidate.slot == 1).per(Candidate.user_id) >= 1) problem.satisfy(hero_pin_ic) @@ -671,7 +671,7 @@ def _assert_in_set(df, col, allowed, source): # picked items without needing an indicator multiplier. Top picks # count more, matching the engagement-decay model the objective # also encodes. -explanation_ic = model.require( +explanation_ic = model.where(Candidate.user_id).require( sum((SLATE_SIZE_K + 1 - Candidate.slot) * Candidate.path_count_total).per(Candidate.user_id) >= EXPLANATION_FLOOR ) diff --git a/book_slate_recommendation/pyproject.toml b/book_slate_recommendation/pyproject.toml index d717eb7b..6f926585 100644 --- a/book_slate_recommendation/pyproject.toml +++ b/book_slate_recommendation/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: book_slate_recommendation (PyRel v1)" readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai==1.1.0", + "relationalai==2.1.1", "pandas>=2.0", ] diff --git a/campaign_roi/README.md b/campaign_roi/README.md index 486615ee..8ae4bbad 100644 --- a/campaign_roi/README.md +++ b/campaign_roi/README.md @@ -52,7 +52,7 @@ Every marketing team eventually faces the same question: the portfolio of campai ### Tools - Python >= 3.10. -- RelationalAI Python SDK (`relationalai == 1.0.14`). +- RelationalAI Python SDK (`relationalai == 2.1.1`). ## Quickstart diff --git a/campaign_roi/pyproject.toml b/campaign_roi/pyproject.toml index db1b6398..717ff2d9 100644 --- a/campaign_roi/pyproject.toml +++ b/campaign_roi/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: campaign_roi (PyRel v1)" readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai==1.0.14", + "relationalai==2.1.1", "pandas", ] diff --git a/cell_tower_coverage/README.md b/cell_tower_coverage/README.md index f57953ed..ee309257 100644 --- a/cell_tower_coverage/README.md +++ b/cell_tower_coverage/README.md @@ -54,7 +54,7 @@ Telecommunications and infrastructure teams routinely have to decide where to bu ### Tools - Python >= 3.10. -- RelationalAI Python SDK (`relationalai == 1.0.14`). +- RelationalAI Python SDK (`relationalai == 2.1.1`). ## Quickstart diff --git a/cell_tower_coverage/pyproject.toml b/cell_tower_coverage/pyproject.toml index e04282a1..ca26100f 100644 --- a/cell_tower_coverage/pyproject.toml +++ b/cell_tower_coverage/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: cell_tower_coverage (PyRel v1)" readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai==1.0.14", + "relationalai==2.1.1", "pandas>=2.0", ] diff --git a/cicd_runner_allocation/README.md b/cicd_runner_allocation/README.md index dc734dcc..8f4cb449 100644 --- a/cicd_runner_allocation/README.md +++ b/cicd_runner_allocation/README.md @@ -53,7 +53,7 @@ Every merge kicks off a pipeline of build, test, and deploy jobs, and each job c ### Tools - Python >= 3.10. -- RelationalAI Python SDK (`relationalai == 1.11.0`). +- RelationalAI Python SDK (`relationalai == 2.1.1`). ## Quickstart @@ -217,7 +217,7 @@ Focus on the first changes most users will make. - Replace the `data/` CSV bundle with queries against your CI/CD platform's API or data warehouse. - The model scales to whatever fits the prescriptive engine's solve budget; raise `time_limit_sec` and the concurrency caps together as the fleet grows. -- Pin dependencies (the template pins `relationalai == 1.11.0`) for reproducible runs across environments. +- Pin dependencies (the template pins `relationalai == 2.1.1`) for reproducible runs across environments. ## Troubleshooting diff --git a/cicd_runner_allocation/pyproject.toml b/cicd_runner_allocation/pyproject.toml index cc0fa9d6..32e0e460 100644 --- a/cicd_runner_allocation/pyproject.toml +++ b/cicd_runner_allocation/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: cicd_runner_allocation (PyRel v1)" readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai==1.11.0", + "relationalai==2.1.1", "pandas>=2.0", ] diff --git a/commercial_underwriting/README.md b/commercial_underwriting/README.md index 3c660dc3..87751f75 100644 --- a/commercial_underwriting/README.md +++ b/commercial_underwriting/README.md @@ -55,7 +55,7 @@ This template shows how to express that rulebook as declarative logic on a four- ### Tools - Python >= 3.10 -- RelationalAI Python SDK (`relationalai`) == 1.11.0 +- RelationalAI Python SDK (`relationalai`) == 2.1.1 ## Quickstart diff --git a/commercial_underwriting/commercial_underwriting.py b/commercial_underwriting/commercial_underwriting.py index 11c7e050..9cb6b4de 100644 --- a/commercial_underwriting/commercial_underwriting.py +++ b/commercial_underwriting/commercial_underwriting.py @@ -31,7 +31,7 @@ from pathlib import Path from pandas import read_csv -from relationalai.semantics import Float, Integer, Model, String +from relationalai.semantics import Float, Integer, Model, String, sum # -------------------------------------------------- # Configure inputs @@ -317,9 +317,8 @@ model.where( model.not_(InsuredEntity.has_decline_factor()), model.not_(InsuredEntity.has_marginal_factor()), + model.not_(RiskTier_Preferred(InsuredEntity)), ).define(RiskTier_Standard(InsuredEntity)) -# Standard is then narrowed by NOT being Preferred. We express this by -# subtracting Preferred from Standard at query time below. # -------------------------------------------------- # Reporting @@ -421,13 +420,8 @@ def query_flag(rel, label): preferred_ids = set( model.where(RiskTier_Preferred(InsuredEntity)).select(InsuredEntity.id.alias("id")).to_df()["id"] ) -# Standard is the rule-defined Standard set MINUS Preferred (Preferred is a -# tightened subset of "no decline, no marginal"). -standard_ids = ( - set( - model.where(RiskTier_Standard(InsuredEntity)).select(InsuredEntity.id.alias("id")).to_df()["id"] - ) - - preferred_ids +standard_ids = set( + model.where(RiskTier_Standard(InsuredEntity)).select(InsuredEntity.id.alias("id")).to_df()["id"] ) @@ -463,8 +457,10 @@ def classify(entity_id): print(f"\nWARNING: {len(overlap)} entities classified into multiple tiers: {sorted(overlap)}") # Aggregate premium by tier — the underwriting business view. -tier_df["premium"] = tier_df["id"].apply( - lambda i: float(policy_csv.loc[policy_csv["insured_entity_id"] == i, "total_premium"].iloc[0]) -) +premium_df = model.where(Policy.insured_entity(InsuredEntity)).select( + InsuredEntity.id.alias("id"), + sum(Policy, Policy.total_premium).per(InsuredEntity).alias("premium"), +).to_df() +tier_df = tier_df.merge(premium_df, on="id") print("\nPremium by tier:") print(tier_df.groupby("tier")["premium"].agg(["count", "sum", "mean"]).to_string()) diff --git a/commercial_underwriting/pyproject.toml b/commercial_underwriting/pyproject.toml index c763dede..7c0f7d37 100644 --- a/commercial_underwriting/pyproject.toml +++ b/commercial_underwriting/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: commercial_underwriting (PyRel v1)" readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai==1.11.0", + "relationalai==2.1.1", "pandas", ] diff --git a/cybersecurity-attack-paths/README.md b/cybersecurity-attack-paths/README.md index a2bd8149..34086951 100644 --- a/cybersecurity-attack-paths/README.md +++ b/cybersecurity-attack-paths/README.md @@ -53,7 +53,7 @@ This template enumerates multi-step attack paths across an enterprise asset grap ### Tools - Python >= 3.10. -- `relationalai` SDK >= 1.21 (path enumeration with multi-edge patterns is a preview capability) and the `rai` CLI, both installed by the Quickstart steps below. +- `relationalai` SDK 2.1.1, the version pinned in `pyproject.toml` (path enumeration with multi-edge patterns is a preview capability) and the `rai` CLI, both installed by the Quickstart steps below. - OS notes: works on macOS, Linux, and Windows; the Quickstart's virtual-environment activation command assumes macOS or Linux. ## Quickstart diff --git a/cybersecurity-attack-paths/cybersecurity_attack_paths.py b/cybersecurity-attack-paths/cybersecurity_attack_paths.py index 793d307d..b1eeb353 100644 --- a/cybersecurity-attack-paths/cybersecurity_attack_paths.py +++ b/cybersecurity-attack-paths/cybersecurity_attack_paths.py @@ -121,7 +121,7 @@ def load_csv(filename): print("=== Cybersecurity Attack Paths: kill-chain into crown jewels ===") a, b, c, dst = Asset.ref(), Asset.ref(), Asset.ref(), Asset.ref() -kill = model.path(a.exploit_to, b.cred_to, c.pivot_to.repeat(1, MAX_PIVOTS), dst).all_paths() +kill = model.path(a.exploit_to, b.cred_to, c.pivot_to.repeat(1, MAX_PIVOTS), dst).all().paths() kill_df = ( model.where( kill, @@ -179,11 +179,11 @@ def load_csv(filename): # -------------------------------------------------- # Pin both endpoints by id and enumerate all simple routes between them over the # technique-agnostic can_reach edge (any technique, 1..MAX_ROUTE_HOPS). This is the -# >=1.15-era native point query (still current) -- src/dst unified to specific assets inside all_paths(). +# >=1.15-era native point query (still current) -- src/dst unified to specific assets inside .all().paths(). src_pt, dst_pt = Asset.ref(), Asset.ref() -route = model.path(src_pt.can_reach.repeat(1, MAX_ROUTE_HOPS), dst_pt).all_paths() -# Keep only SIMPLE routes (no asset revisited). all_paths() has WALK semantics and +route = model.path(src_pt.can_reach.repeat(1, MAX_ROUTE_HOPS), dst_pt).all().paths() +# Keep only SIMPLE routes (no asset revisited). .all().paths() has WALK semantics and # no native simple-path mode, so drop node-repeating walks with a negated existential # over positions -- expressed natively in the route's where() (no pandas). i, j = Integer.ref(), Integer.ref() diff --git a/cybersecurity-attack-paths/pyproject.toml b/cybersecurity-attack-paths/pyproject.toml index 36a16b1f..d3117adc 100644 --- a/cybersecurity-attack-paths/pyproject.toml +++ b/cybersecurity-attack-paths/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: enumerate multi-step cyber attack chains a readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai==1.21.1", + "relationalai==2.1.1", "pandas>=2.0.0", ] diff --git a/datacenter_compute_allocation/README.md b/datacenter_compute_allocation/README.md index 7ecc6d6a..4f3ff3b4 100644 --- a/datacenter_compute_allocation/README.md +++ b/datacenter_compute_allocation/README.md @@ -49,7 +49,7 @@ This template models that allocation as a scenario sweep across three axes (powe - Reverse-PageRank scoring on a workload dependency DAG (4-5 deep chains rooted at frontier pretrains) - Declarative hardware-compatibility rules + lex-emulating priority weights (P0=100, P1=10, P2=1) - Two headline Pareto frontiers (margin × revenue and diversity × revenue) at the 100% envelope, with the 85% envelope drawn as an overlay sensitivity band -- Per-cell results queryable directly from the ontology — realized revenue, energy + depreciation cost, anchor share, per-workload-type counts, binding-constraint signal (OPTIMAL vs INFEASIBLE) +- Per-cell results queryable directly from the ontology — realized revenue, energy + depreciation cost, anchor share, per-workload-type counts, binding-constraint signal (OPTIMAL vs INFEASIBLE, or FEASIBLE vs UNSOLVED when the solve stops at its time limit) ## What's included @@ -142,13 +142,13 @@ Set `EXP_DATABASE` at the top of `datacenter_compute_allocation.py` to that data ```text STAGE 4: PRESCRIPTIVE -- compute allocation MIP (24-cell sweep) - Termination status: OPTIMAL - Per-cell summary (24 cells: 16 optimal, 8 infeasible) + Termination status: TIME_LIMIT + Per-cell summary (24 cells: 16 feasible, 8 unsolved) AllocationPlan singleton (100pct / unconstrained / none): 110 workloads assigned, $25.28M revenue, 83% margin, 95% anchor share ``` - Full stage-by-stage log (GNN distribution, PageRank scores, both Pareto frontiers, the demand-scenario overlay, and expected per-cell behavior) is in `runbook.md`. GNN probabilities depend on seed and predictive engine; the `--no-gnn` fallback values are deterministic. Stage 4 reaches `OPTIMAL` in seconds with Gurobi; the open-source HiGHS default returns a feasible solution at the `time_limit_sec=240` wall and may surface `TIME_LIMIT` (signal, not failure, per `rai-prescriptive-results`). Set `SOLVER` in `datacenter_compute_allocation.py` to switch. + Full stage-by-stage log (GNN distribution, PageRank scores, both Pareto frontiers, the demand-scenario overlay, and expected per-cell behavior) is in `runbook.md`. GNN probabilities depend on seed and predictive engine; the `--no-gnn` fallback values are deterministic. The output above is from the open-source HiGHS default, which returns a feasible solution at the `time_limit_sec=240` wall and reports `TIME_LIMIT` (signal, not failure, per `rai-prescriptive-results`), so cells are labelled FEASIBLE or UNSOLVED. With Gurobi, Stage 4 reaches `OPTIMAL` in seconds and the cells are labelled OPTIMAL or INFEASIBLE. Set `SOLVER` in `datacenter_compute_allocation.py` to switch. ## Template structure diff --git a/datacenter_compute_allocation/datacenter_compute_allocation.py b/datacenter_compute_allocation/datacenter_compute_allocation.py index 1a423c00..77d0e8f5 100644 --- a/datacenter_compute_allocation/datacenter_compute_allocation.py +++ b/datacenter_compute_allocation/datacenter_compute_allocation.py @@ -39,7 +39,8 @@ utilization probabilities (top / bottom 5 + n>=0.5 count), Compatibility table size and P0/P1/P2 priority counts with under-provisioning penalties, top-10 gating workloads by downstream reach, MIP termination status, - per-cell summary table (with INFEASIBLE cells as designed diagnostic signal), two Pareto frontiers + per-cell summary table (INFEASIBLE cells are designed diagnostic signal; + UNSOLVED when the solve stops at its time limit), two Pareto frontiers (margin x revenue and diversity x revenue at the 100pct envelope), and a DemandScenario overlay replaying the chosen plan under risk scenarios (expected / diffusion_slowdown / scaling_break / frontier_loss) with @@ -83,7 +84,7 @@ # Stage 4 solver. HiGHS is the open-source default that ships with the # prescriptive engine; switch to "gurobi" if your engine has a Gurobi # license (faster convergence, tighter MIP gaps on the 24-cell sweep). -SOLVER = "gurobi" +SOLVER = "highs" SOLVER_TIME_LIMIT_SEC = 240 WORKLOAD_TYPES = ("pretrain", "finetune", "inference", "eval") @@ -1036,19 +1037,21 @@ def _pos_prob(v): cells_df = cells_df.merge(df_pt, on=["envelope", "margin", "diversity"], how="left") cells_df[f"n_{pt}"] = pd.to_numeric(cells_df[f"n_{pt}"], errors="coerce").fillna(0).astype(int) - # Per-cell status: cells with assignments are OPTIMAL; cells with none - # are INFEASIBLE when the global solve proved optimality, or UNSOLVED when - # the wall-clock ran out before the solver could explore that cell. - _empty_label = "INFEASIBLE" if si.termination_status == "OPTIMAL" else "UNSOLVED" + # Per-cell status: when the global solve proved optimality, cells with + # assignments are OPTIMAL and cells with none are INFEASIBLE. When the + # wall-clock ran out first, they are FEASIBLE and UNSOLVED. + _proved = si.termination_status == "OPTIMAL" + _filled_label = "OPTIMAL" if _proved else "FEASIBLE" + _empty_label = "INFEASIBLE" if _proved else "UNSOLVED" cells_df["status"] = cells_df["n_assigned"].apply( - lambda n: "OPTIMAL" if n > 0 else _empty_label + lambda n: _filled_label if n > 0 else _empty_label ) cells_df = cells_df.sort_values(["envelope", "margin", "diversity"]) n_cells_total = len(cells_df) - n_feasible = (cells_df["status"] == "OPTIMAL").sum() - n_empty = n_cells_total - n_feasible - print(f"\n Per-cell summary ({n_cells_total} cells: {n_feasible} optimal, {n_empty} {_empty_label.lower()}):") + n_filled = (cells_df["status"] == _filled_label).sum() + n_empty = n_cells_total - n_filled + print(f"\n Per-cell summary ({n_cells_total} cells: {n_filled} {_filled_label.lower()}, {n_empty} {_empty_label.lower()}):") display_cols = ["envelope", "margin", "diversity", "status", "n_assigned", "revenue_usd", "total_cost_usd", @@ -1098,8 +1101,8 @@ def _pos_prob(v): else: _r = chosen_row.iloc[0] _status = _r["status"] - if _status == "INFEASIBLE": - _binding_axis = "infeasible" + if _status == _empty_label: + _binding_axis = _empty_label.lower() else: _binding_axis = "power_envelope" diff --git a/datacenter_compute_allocation/pyproject.toml b/datacenter_compute_allocation/pyproject.toml index cac449da..09c7d0df 100644 --- a/datacenter_compute_allocation/pyproject.toml +++ b/datacenter_compute_allocation/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: datacenter_compute_allocation (PyRel v1)" readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai[gnn]==1.27.1", + "relationalai[gnn]==2.1.1", "pandas>=2.0", ] diff --git a/datacenter_compute_allocation/runbook.md b/datacenter_compute_allocation/runbook.md index c9e8cbd6..04367778 100644 --- a/datacenter_compute_allocation/runbook.md +++ b/datacenter_compute_allocation/runbook.md @@ -32,7 +32,8 @@ as ontology so the plan survives the chain run. ───────────────────────────────────────────────────────────────── STAGE 4 Prescriptive ──► Assignment.x_assign(env, mar, div) (MIP) 24 cells: 16 OPTIMAL, 8 INFEASIBLE. - OPTIMAL in 6 s with Gurobi. + OPTIMAL in 6 s with Gurobi. HiGHS (default) + stops at 240 s: 16 FEASIBLE, 8 UNSOLVED. Baseline (100pct / unconstrained / none): 110 assigned · $25.28M revenue · 83% margin · 95% anchor · binding axis: power envelope. @@ -144,7 +145,7 @@ Frontier labs (Anthropic, OpenAI, xAI Internal) carry the 15 P0 pretrains (256 **Response** -Single MIP across 24 cells: `Assignment.x_assign(PowerEnvelopeLevel, MarginFloor, DiversityCap)` written back per cell — 16 OPTIMAL, 8 INFEASIBLE (designed signal at the strictest anchor-cap + type-floor combinations). OPTIMAL in ~6 s with Gurobi. Baseline (100pct / unconstrained / none): 110 workloads, $25.28M revenue, 83% margin, 95% anchor. +Single MIP across 24 cells: `Assignment.x_assign(PowerEnvelopeLevel, MarginFloor, DiversityCap)` written back per cell — 16 OPTIMAL, 8 INFEASIBLE (designed signal at the strictest anchor-cap + type-floor combinations). OPTIMAL in ~6 s with Gurobi; HiGHS, the default, stops at its 240 s limit with 16 FEASIBLE and 8 UNSOLVED. Baseline (100pct / unconstrained / none): 110 workloads, $25.28M revenue, 83% margin, 95% anchor. ### 9. Read the frontiers and the demand-risk overlay @@ -168,7 +169,7 @@ Baseline: 110 workloads, $25.28M revenue, $4.18M cost, 83% margin, 95% anchor, b **Response** -Ontology gains a singleton `AllocationPlan(id="DCCA_BASELINE")` with `revenue_usd` ≈ $25.28M, `total_cost_usd` ≈ $4.18M, `realized_margin` ≈ 0.83, `anchor_share` ≈ 0.95, `n_assigned` = 110, `status` = `OPTIMAL`, `binding_axis` = `power_envelope`; plus `Assignment.is_chosen` (110 rows), `DemandScenario` (4 rows), and `DemandScenarioOutlook` (per-scenario realized + stranded revenue). All queryable as ontology, not stdout. +Ontology gains a singleton `AllocationPlan(id="DCCA_BASELINE")` with `revenue_usd` ≈ $25.28M, `total_cost_usd` ≈ $4.18M, `realized_margin` ≈ 0.83, `anchor_share` ≈ 0.95, `n_assigned` = 110, `status` = `OPTIMAL` (`FEASIBLE` when HiGHS stops at its time limit), `binding_axis` = `power_envelope`; plus `Assignment.is_chosen` (110 rows), `DemandScenario` (4 rows), and `DemandScenarioOutlook` (per-scenario realized + stranded revenue). All queryable as ontology, not stdout. ## Data diff --git a/defect_root_cause/pyproject.toml b/defect_root_cause/pyproject.toml index 6c60d8a3..74bd506d 100644 --- a/defect_root_cause/pyproject.toml +++ b/defect_root_cause/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: defect_root_cause (PyRel v1)" readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai==1.13.0", + "relationalai==2.1.1", "pandas>=2.0", ] diff --git a/demand_forecasting/README.md b/demand_forecasting/README.md index d0384508..313150e7 100644 --- a/demand_forecasting/README.md +++ b/demand_forecasting/README.md @@ -64,7 +64,7 @@ GRANT CREATE MODEL ON SCHEMA FAVORITA_MINI.EXPERIMENTS TO APPLICATION RELATIONAL ### Tools - Python >= 3.10 -- RelationalAI Python SDK (`relationalai[gnn] == 1.27.1`) +- RelationalAI Python SDK (`relationalai[gnn] == 2.1.1`) ## Quickstart diff --git a/demand_forecasting/pyproject.toml b/demand_forecasting/pyproject.toml index 669c671f..a8ab6e7e 100644 --- a/demand_forecasting/pyproject.toml +++ b/demand_forecasting/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: demand_forecasting (PyRel v1)" readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai[gnn]==1.27.1", + "relationalai[gnn]==2.1.1", "pandas", "numpy", ] diff --git a/demand_planning_temporal/README.md b/demand_planning_temporal/README.md index e6897444..00104917 100644 --- a/demand_planning_temporal/README.md +++ b/demand_planning_temporal/README.md @@ -34,7 +34,7 @@ Prescriptive reasoning makes this practical because the solver simultaneously ba - A service-level guarantee (a 95% minimum-fulfillment constraint) plus an unmet-demand report showing whether any demand went unserved. - A three-scenario what-if sweep that shows how total cost changes as the planning horizon extends, all sharing one model. -Built using **prescriptive reasoning**: continuous decision variables for production, inventory, and unmet demand; a multi-period flow-conservation constraint; and a total-cost objective assembled with `model.union()`. +Built using **prescriptive reasoning**: continuous decision variables for production, inventory, and unmet demand; a multi-period flow-conservation constraint; and a total-cost objective that adds separately summed cost terms. ## What's included @@ -51,7 +51,7 @@ Built using **prescriptive reasoning**: continuous decision variables for produc ### Tools - Python >= 3.10 -- RelationalAI Python SDK (`relationalai`) >= 1.0.14 +- RelationalAI Python SDK (`relationalai`) == 2.1.1 ## Quickstart @@ -157,7 +157,7 @@ For the full concept and property definitions — including the time-indexed `x_ **Enforce flow conservation.** The core multi-period constraint ties adjacent weeks together: inventory at the end of week `t` equals inventory at the end of week `t-1` plus production in week `t` minus demand in week `t`. A `WeeklyDemand` concept pre-aggregates orders into weekly buckets — including zero-demand weeks — so the constraint covers every period. -**Minimize total cost.** The objective combines production cost, holding cost, and an unmet-demand penalty from different concepts using `model.union()`, and the solver minimizes their sum subject to the flow-conservation and service-level constraints. +**Minimize total cost.** The objective adds production cost, holding cost, and an unmet-demand penalty, each summed over its own concept, and the solver minimizes the total subject to the flow-conservation and service-level constraints. The script also includes a commented-out Pattern B for data that carries Unix epoch-second timestamps instead of date strings: convert the horizon boundaries to epochs and filter identically. @@ -178,7 +178,7 @@ See `demand_planning_temporal.py` for the implementation and `runbook.md` to rep ### Extend the model -- Add new cost components (for example a per-site fixed operating cost) as additional terms in the `model.union()` objective, following the `prod_cost` / `hold_cost` / `unmet_cost` pattern. +- Add new cost components (for example a per-site fixed operating cost) as another summed term in the objective, following the `prod_cost` / `hold_cost` / `unmet_cost` pattern. - Add new constraints (for example a per-site total-capacity cap across SKUs) with additional `problem.satisfy(...)` calls alongside the flow-conservation constraint. ### Scale up / productionize @@ -226,7 +226,7 @@ Ensure your Snowflake account has the RAI Native App installed and your user has ### Reasoner reference -- [Prescriptive reasoner](https://docs.relational.ai/) — `Problem`, `solve_for` decision variables, `satisfy` constraints, `minimize` objectives, and `model.union()`. +- [Prescriptive reasoner](https://docs.relational.ai/) — `Problem`, `solve_for` decision variables, `satisfy` constraints, and `minimize` objectives. - [Solver management](https://docs.relational.ai/) — configuring the HiGHS solve and `time_limit_sec`. ## Support diff --git a/demand_planning_temporal/demand_planning_temporal.py b/demand_planning_temporal/demand_planning_temporal.py index 22f3b46b..39fe7bb5 100644 --- a/demand_planning_temporal/demand_planning_temporal.py +++ b/demand_planning_temporal/demand_planning_temporal.py @@ -168,9 +168,6 @@ x_inv_prev = Float.ref() x_inv_curr = Float.ref() -# Static constraint expression: demand fulfillment bound (no scenario param dependency) -demand_bound = model.require(DemandOrder.x_unmet <= DemandOrder.quantity) - # Static constraint expression: global service level (no scenario param dependency) service_level_constraint = model.require( sum(DemandOrder.x_unmet) <= (1 - min_service_level) * sum(DemandOrder.quantity) @@ -322,9 +319,6 @@ ).require(x_inv_curr == x_inv_prev + production_ref - WeeklyDemand.wk_quantity) ) - # Static constraint: demand fulfillment bound - problem.satisfy(demand_bound) - # Static constraint: global service level problem.satisfy(service_level_constraint) @@ -346,15 +340,16 @@ ).require(inventory_ref >= avg_weekly_demand * safety_stock_weeks) ) - # Parameterized objective: minimize total cost (depends on week ranges via production/inventory refs) - prod_cost = ProdCapacity.production_cost * sum(production_ref).per( - ProdCapacity + # Objective: minimize total cost, each term summed over its own rows. + prod_cost = sum( + ProdCapacity, week_ref, ProdCapacity.production_cost * production_ref ).where(ProdCapacity.x_production(week_ref, production_ref)) - hold_cost = ProdCapacity.holding_cost_per_week * sum(inventory_ref).per( - ProdCapacity + hold_cost = sum( + ProdCapacity, week_ref, ProdCapacity.holding_cost_per_week * inventory_ref ).where(ProdCapacity.x_inventory(week_ref, inventory_ref), week_ref >= 1) - unmet_cost = unmet_penalty * DemandOrder.x_unmet - problem.minimize(sum(model.union(prod_cost, hold_cost, unmet_cost))) + unmet_cost = sum(DemandOrder, unmet_penalty * DemandOrder.x_unmet) + # With no orders in the horizon the unmet sum is empty; `| 0.0` makes it zero. + problem.minimize(prod_cost + hold_cost + (unmet_cost | 0.0)) problem.display() problem.solve("highs", time_limit_sec=60) diff --git a/demand_planning_temporal/pyproject.toml b/demand_planning_temporal/pyproject.toml index b5e167e1..63ffee51 100644 --- a/demand_planning_temporal/pyproject.toml +++ b/demand_planning_temporal/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: demand_planning_temporal (PyRel v1)" readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai==1.0.14", + "relationalai==2.1.1", "pandas", ] diff --git a/diet/pyproject.toml b/diet/pyproject.toml index bd378db7..97ee4f6e 100644 --- a/diet/pyproject.toml +++ b/diet/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: diet (PyRel v1)" readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai==1.0.14", + "relationalai==2.1.1", "pandas", ] diff --git a/disease-outbreak-prevention/README.md b/disease-outbreak-prevention/README.md index 3cd90db5..503d927d 100644 --- a/disease-outbreak-prevention/README.md +++ b/disease-outbreak-prevention/README.md @@ -54,7 +54,7 @@ Built using **graph analysis** (a directed, weighted graph with `Facility` as th ### Tools - Python >= 3.10 -- RelationalAI Python SDK (`relationalai == 1.11.0`). +- RelationalAI Python SDK (`relationalai == 2.1.1`). - Optional: `streamlit`, `plotly`, `numpy` for the interactive app (installed via the `visualization` extra). ## Quickstart @@ -206,7 +206,7 @@ Focus on the first changes most users will make. ### Scale up / productionize - Replace the CSV bundle with CDC ingestion from your health-network systems; the graph shape is independent of the load pipeline. -- Pin `relationalai` (this template targets `1.11.0`) and schedule the run as a pipeline step for reproducible re-runs. +- Pin `relationalai` (this template targets `2.1.1`) and schedule the run as a pipeline step for reproducible re-runs. ## Troubleshooting diff --git a/disease-outbreak-prevention/pyproject.toml b/disease-outbreak-prevention/pyproject.toml index 6924e37d..1a2cec69 100644 --- a/disease-outbreak-prevention/pyproject.toml +++ b/disease-outbreak-prevention/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: disease outbreak prevention network with d readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai==1.11.0", + "relationalai==2.1.1", "pandas>=2.0.0", ] diff --git a/energy_grid_planning/README.md b/energy_grid_planning/README.md index 787ab25c..f1f9991a 100644 --- a/energy_grid_planning/README.md +++ b/energy_grid_planning/README.md @@ -75,7 +75,7 @@ Texas is now the fastest-growing market for AI data center development. Hypersca ### Tools - Python >= 3.10 -- RelationalAI Python SDK (`relationalai[gnn]`) == 1.27.1 +- RelationalAI Python SDK (`relationalai[gnn]`) == 2.1.1 ## Quickstart @@ -120,10 +120,10 @@ Texas is now the fastest-growing market for AI data center development. Hypersca ```text STAGE 5: OPTIMIZE -- Joint Interconnection + Upgrade - Status: OPTIMAL | Objective: 1,579,200,000 + Status: OPTIMAL + Objective: 1,562,600,000.00 - KNEE POINT: $300M -- 5 DCs, 1,500 MW, $264M net value - xAI Colossus ($105M/yr) unlocks at $300M -- highest-revenue single request + KNEE POINT: $300M -- $300M budget, $252,450,000 net value, 6 DCs, 1,530 MW PIPELINE COMPLETE: 5 stages executed on shared Energy Grid ontology ``` @@ -225,7 +225,7 @@ Three declarative rules consume upstream outputs, then a composite flag combines An `InvestmentLevel` Scenario Concept holds 5 budget levels ($200M-$600M), each parameterizing one MIP solve into a Pareto frontier. Binary variables `x_approve` (per DC request) and `x_upgrade` (per substation upgrade) are indexed by investment level; substation-capacity constraints use `predicted_load` from Stage 1 so the optimizer sees the same forecasted headroom as the rules engine, and budget constraints are scoped `.per(InvestmentLevel)`. Revenue reflects annual interconnection capacity revenue ($145K-$210K per MW/yr), not energy revenue. -One solve produces the entire frontier. The knee point at $300M (5 DCs, 1,500 MW, $264M net value) shows the highest marginal return, unlocking xAI Colossus ($105M/yr). At $200M, 4 DCs are approved (Microsoft, CoreWeave, Crusoe, Oracle); each additional $100M adds one more DC with diminishing returns ($995K/$M at the knee vs $400K/$M at $600M). Google Metroplex DC (400 MW) and Lambda Labs DFW (200 MW) are never approved at any budget — DFW capacity is fully consumed. Per-level results (approvals, upgrades, MW) are all queried from the ontology via `model.select()` rather than parsed from solver output. +One solve produces the entire frontier. The knee point at $300M (6 DCs, 1,530 MW, $252M net value) shows the highest marginal return: both DFW upgrades fit the budget, and Google Metroplex DC and Lambda Labs DFW join. At $200M, 4 DCs are approved (Microsoft, Amazon SA, Crusoe, Oracle); beyond the knee each additional $100M adds one more DC with diminishing returns ($1,013K/$M into the knee vs $439K/$M from $400M to $500M). Revenue is the objective, so where several upgrade sets earn the same revenue (as at $500M), the net value depends on which set the solver returns. xAI Colossus (500 MW) is never approved at any budget — DFW headroom goes to Google and Lambda. Per-level results (approvals, upgrades, MW) are all queried from the ontology via `model.select()` rather than parsed from solver output. See `energy_grid_planning.py` for the implementation of all five stages and `runbook.md` for the skill-driven reproduction. @@ -256,7 +256,7 @@ Focus on the first changes most users will make. - Replace the `data/` CSV bundle with CDC ingestion from your grid systems; the ontology shape is independent of the load pipeline. - The synthetic grid is sized at 12 substations / 18 lines; the chain scales to whatever fits the prescriptive engine's solve budget. Size the engine up for larger grids or finer investment grids, since the MIP grows with substations × investment levels. -- Pin `relationalai` (this template targets `1.15.0`) and schedule the run as a pipeline step for reproducible, deterministic re-runs. +- Pin `relationalai` (this template targets `2.1.1`) and schedule the run as a pipeline step for reproducible, deterministic re-runs. ## Troubleshooting @@ -264,7 +264,7 @@ Focus on the first changes most users will make. Stage 2 graph queries work but Stage 5 fails with UnsupportedRecursionError - SDK versions before 1.0.13 could hit this when recursive graph rules and - prescriptive result queries shared one model. Upgrade to >= 1.0.13. + prescriptive result queries shared one model. Upgrade to `relationalai` 2.1.1, the version pinned in `pyproject.toml`.
@@ -288,11 +288,11 @@ Focus on the first changes most users will make.
-Google and Lambda Labs are never approved at any budget level +xAI Colossus is never approved at any budget level -- Both target the Dallas-Fort Worth substation, which is already the only substation predicted to breach capacity (54.6% growth). -- Even with upgrades, DFW capacity is fully consumed by higher-revenue requests (xAI Colossus at 500 MW, $105M/yr). -- The optimizer correctly prioritizes revenue-maximizing allocations at the constrained substation. +- It targets the Dallas-Fort Worth substation, the only substation predicted to breach capacity (54.6% growth). Even with both DFW upgrades, DFW has 699.8 MW of headroom. +- That fits Google Metroplex DC and Lambda Labs DFW together (600 MW, $108M/yr) or xAI alone (500 MW, $105M/yr); xAI with Lambda would need 700 MW. +- The optimizer correctly prioritizes the revenue-maximizing allocation at the constrained substation.
diff --git a/energy_grid_planning/energy_grid_planning.py b/energy_grid_planning/energy_grid_planning.py index f1edcf3c..68e14e2a 100644 --- a/energy_grid_planning/energy_grid_planning.py +++ b/energy_grid_planning/energy_grid_planning.py @@ -712,9 +712,13 @@ def load_csv(filename): # Enumerate generator-sub -> DC-sub corridors (finite repeat; the grid is meshed/cyclic). MAX_CORRIDOR_HOPS = 6 corridor_src, corridor_dst = GeneratorSubstation.ref(), DCSubstation.ref() -corridor = model.path( - corridor_src, Substation.connects_to.repeat(1, MAX_CORRIDOR_HOPS), corridor_dst -).all_paths() +corridor = ( + model.path( + corridor_src, Substation.connects_to.repeat(1, MAX_CORRIDOR_HOPS), corridor_dst + ) + .all() + .paths() +) # Score each corridor IN PyRel by Stage 2's betweenness summed ALONG its hops, and # roll the most-fragile (max-load) corridor up per DC substation -- all native paths. @@ -722,7 +726,7 @@ def load_csv(filename): # Three operations move into PyRel: # 1. Per-corridor score: aggs.sum(Substation(p.nodes).betweenness).per(p) sums the # per-node betweenness over each corridor's node sequence (the core paths-only op). -# 2. Simple-path filter: the grid is cyclic, so walk-semantics all_paths() revisits +# 2. Simple-path filter: the grid is cyclic, so walk-semantics .all().paths() revisits # nodes; not_(where(i < j, p.nodes(i) == p.nodes(j))) drops any node-repeating walk # via a negated existential over positions. It sits in the SAME where() as the sum, # so the sum only sees simple corridors -- on a simple corridor the position-sum @@ -1010,18 +1014,32 @@ def _query_flag(relationship, flag_name): x_u_c = Float.ref("xu_c") effective_load = Substation.predicted_load | Substation.current_load_mw -problem.satisfy(model.where( - DataCenterRequest.x_approve(InvestmentLevel, x_a_c), - SubstationUpgrade.x_upgrade(InvestmentLevel, x_u_c), - DataCenterRequest.substation(Substation), - SubstationUpgrade.substation(Substation), -).require( - Substation.max_capacity_mw - effective_load - + sum(x_u_c * UpgRef.capacity_increase_mw).where( - UpgRef.substation == Substation).per(Substation, InvestmentLevel) - >= sum(x_a_c * DCRef.requested_mw).where( - DCRef.substation == Substation).per(Substation, InvestmentLevel) -)) +# Each upgrade's capacity and each request's MW is weighted by its own variable. +# A substation with no upgrade options adds no capacity (`| 0.0`). +problem.satisfy( + model.where( + InvestmentLevel, + DataCenterRequest.substation(Substation), + ).require( + Substation.max_capacity_mw + - effective_load + + ( + sum(UpgRef, x_u_c * UpgRef.capacity_increase_mw) + .where( + UpgRef.substation == Substation, + UpgRef.x_upgrade(InvestmentLevel, x_u_c), + ) + .per(Substation, InvestmentLevel) + | 0.0 + ) + >= sum(DCRef, x_a_c * DCRef.requested_mw) + .where( + DCRef.substation == Substation, + DCRef.x_approve(InvestmentLevel, x_a_c), + ) + .per(Substation, InvestmentLevel) + ) +) # C2: Budget per investment level problem.satisfy(model.where( @@ -1032,7 +1050,7 @@ def _query_flag(relationship, flag_name): # Objective: maximize total DC revenue across all levels problem.maximize( - sum(x_a * DataCenterRequest.annual_revenue_per_mw * DataCenterRequest.requested_mw).where( + sum(InvestmentLevel, x_a * DataCenterRequest.annual_revenue_per_mw * DataCenterRequest.requested_mw).where( DataCenterRequest.x_approve(InvestmentLevel, x_a) ) ) diff --git a/energy_grid_planning/pyproject.toml b/energy_grid_planning/pyproject.toml index 2a1a1ae1..c51ae329 100644 --- a/energy_grid_planning/pyproject.toml +++ b/energy_grid_planning/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: energy_grid_planning (PyRel v1)" readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai[gnn]==1.27.1", + "relationalai[gnn]==2.1.1", "pandas>=2.0", ] diff --git a/energy_grid_planning/runbook.md b/energy_grid_planning/runbook.md index b9382c4c..18e67b01 100644 --- a/energy_grid_planning/runbook.md +++ b/energy_grid_planning/runbook.md @@ -8,7 +8,7 @@ ERCOT processes 10 hyperscaler interconnection requests (2,930 MW) against a 12- ERCOT has 10 hyperscaler interconnection requests totalling 2,930 MW on a 12-substation grid where DFW is the binding capacity bottleneck. The chain produces a Pareto frontier across 5 budget levels — the knee at -$300M unlocks 5 DCs (1,500 MW, $264M net value) including xAI Colossus. +$300M unlocks 6 DCs (1,530 MW, $252M net value) including Google and Lambda at DFW. ───────────────────────────────────────────────────────────────── STAGE 1 Predictive ──► Substation.predicted_load (12) @@ -37,8 +37,8 @@ $300M unlocks 5 DCs (1,500 MW, $264M net value) including xAI Colossus. STAGE 5 Prescriptive ──► DataCenterRequest.x_approve (per InvestmentLevel) SubstationUpgrade.x_upgrade (per InvestmentLevel) OPTIMAL across 5 budget levels in one solve. - Knee $300M · 5 DCs · 1,500 MW · $264M net. - Google + Lambda never approved — DFW full. + Knee $300M · 6 DCs · 1,530 MW · $252M net. + xAI never approved — DFW headroom fits Google + Lambda. ───────────────────────────────────────────────────────────────── ``` @@ -152,7 +152,7 @@ OPTIMAL MIP across 5 `InvestmentLevel` values in one solve; `x_approve` and `x_u **Response** -Pareto frontier with knee at $300M (5 DCs, 1,500 MW, $264M net); marginal $995K/$M at knee, declining to $400K/$M by $600M; Google + Lambda never approved (DFW full). +Pareto frontier with knee at $300M (6 DCs, 1,530 MW, $252M net); marginal $1,013K/$M into the knee, declining to $439K/$M by $500M; xAI Colossus never approved (DFW headroom goes to Google + Lambda). ### 10. Persist solution concepts into the ontology @@ -164,7 +164,7 @@ Pareto frontier with knee at $300M (5 DCs, 1,500 MW, $264M net); marginal $995K/ **Response** -Ontology gains an `InvestmentPortfolio(InvestmentLevel)` Concept (5 rows, one per budget) with `dc_count`, `total_mw`, `annual_revenue`, `upgrade_cost`, `net_value`, `marginal_per_m_to_next_level`, `is_knee_point`. All five frontier rows — $200M ($165M net) → $300M ($264M net, knee) → $600M ($395M net) — are queryable as ontology rather than stdout. +Ontology gains an `InvestmentPortfolio(InvestmentLevel)` Concept (5 rows, one per budget) with `dc_count`, `total_mw`, `annual_revenue`, `upgrade_cost`, `net_value`, `marginal_per_m_to_next_level`, `is_knee_point`. All five frontier rows — $200M ($151M net) → $300M ($252M net, knee) → $600M ($398M net) — are queryable as ontology rather than stdout. ## Data diff --git a/entity_resolution/README.md b/entity_resolution/README.md index b620b60d..b3369271 100644 --- a/entity_resolution/README.md +++ b/entity_resolution/README.md @@ -36,7 +36,7 @@ Before you start, install Python 3.10 or later and get access to a Snowflake account with the RAI Native App. Graph and Prescriptive reasoning are in Public Preview; ask your RelationalAI support representative to enable Prescriptive reasoning. Preview features are for evaluation and testing, not production -applications. The template pins `relationalai==1.13.0` in `pyproject.toml` and +applications. The template pins `relationalai==2.1.1` in `pyproject.toml` and uses HiGHS without a separate solver license. Use this sequence to run the bundled example: diff --git a/entity_resolution/pyproject.toml b/entity_resolution/pyproject.toml index 4b52d026..01d472ee 100644 --- a/entity_resolution/pyproject.toml +++ b/entity_resolution/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: entity_resolution" readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai==1.13.0", + "relationalai==2.1.1", "pandas>=2.0.0", ] diff --git a/factory_production/README.md b/factory_production/README.md index 98555b1c..3cd4ea55 100644 --- a/factory_production/README.md +++ b/factory_production/README.md @@ -55,7 +55,7 @@ Manufacturing operations must decide how much of each product to make at each fa ### Tools - Python >= 3.10 -- RelationalAI Python SDK (`relationalai`) == 1.11.0 +- RelationalAI Python SDK (`relationalai`) == 2.1.1 ## Quickstart diff --git a/factory_production/pyproject.toml b/factory_production/pyproject.toml index af921e4a..b969ff36 100644 --- a/factory_production/pyproject.toml +++ b/factory_production/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: factory_production (PyRel v1)" readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai==1.11.0", + "relationalai==2.1.1", "pandas", ] diff --git a/financial_index_replication/README.md b/financial_index_replication/README.md index 989bc8ef..314912ac 100644 --- a/financial_index_replication/README.md +++ b/financial_index_replication/README.md @@ -37,7 +37,7 @@ Before you start, install Python 3.10 or later and get access to a Snowflake account with the RAI Native App. Prescriptive reasoning is in Public Preview; ask your RelationalAI support representative to enable it. Preview features are for evaluation and testing, not production applications. The template pins -`relationalai==1.0.14` in `pyproject.toml`. +`relationalai==2.1.1` in `pyproject.toml`. Use this sequence to run the bundled example: diff --git a/financial_index_replication/financial_index_replication.py b/financial_index_replication/financial_index_replication.py index 3a21ef97..cf703e52 100644 --- a/financial_index_replication/financial_index_replication.py +++ b/financial_index_replication/financial_index_replication.py @@ -202,7 +202,7 @@ # Uncomment to print the formulated problem for debugging. # problem.display() -problem.solve("highs", time_limit_sec=240) +problem.solve("highs", time_limit_sec=300) si = problem.solve_info() si.display() assert si.termination_status == "OPTIMAL" or si.termination_status == "TIME_LIMIT", "Solver did not find an optimal solution." diff --git a/financial_index_replication/pyproject.toml b/financial_index_replication/pyproject.toml index a86c232e..4dd72624 100644 --- a/financial_index_replication/pyproject.toml +++ b/financial_index_replication/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: financial_index_replication (PyRel v1)" readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai==1.0.14", + "relationalai==2.1.1", "pandas>=2.0", ] diff --git a/financial_index_replication/runbook.md b/financial_index_replication/runbook.md index 7b5155e1..16b54528 100644 --- a/financial_index_replication/runbook.md +++ b/financial_index_replication/runbook.md @@ -11,7 +11,7 @@ A portfolio manager wants to track a broad benchmark without holding all of its • constraints: exactly 20 names; weights sum to 1; ≤ 10% per name; sectors within ±4% of benchmark; trading-capacity (ADV) limit; residual = benchmark − basket return each month • objective: minimize total absolute monthly tracking error (L1) - • HiGHS mixed-integer program (240s cap) -> feasible basket, ~0.4% annualized tracking error + • HiGHS mixed-integer program (300s cap) -> feasible basket, ~0.4% annualized tracking error │ ▼ /rai-prescriptive-results diff --git a/financial_index_replication/template-docs.yaml b/financial_index_replication/template-docs.yaml index 28d5ddf1..05bbb737 100644 --- a/financial_index_replication/template-docs.yaml +++ b/financial_index_replication/template-docs.yaml @@ -295,13 +295,13 @@ guided_walkthrough: focus: file: financial_index_replication.py anchors: - - start: problem.solve("highs", time_limit_sec=240) + - start: problem.solve("highs", time_limit_sec=300) end: return monthly_rms * sqrt(MONTHS_PER_YEAR) references: problem.solve(...): anchor: - start: problem.solve("highs", time_limit_sec=240) - end: problem.solve("highs", time_limit_sec=240) + start: problem.solve("highs", time_limit_sec=300) + end: problem.solve("highs", time_limit_sec=300) model.select(...): anchor: start: model.select( diff --git a/fraud-detection/README.md b/fraud-detection/README.md index b4658bd4..fc89947c 100644 --- a/fraud-detection/README.md +++ b/fraud-detection/README.md @@ -39,7 +39,7 @@ are in Public Preview; ask your RelationalAI support representative to enable Prescriptive reasoning. Preview features are for evaluation and testing, not production applications. The local demo uses bundled CSVs and runs on CPU without an external dataset or GPU. The template pins -`relationalai[gnn]==1.27.1` in `pyproject.toml`. +`relationalai[gnn]==2.1.1` in `pyproject.toml`. Ask an administrator to run this SQL before you start. It creates the writable experiment schema used by `fraud_detection_local.py` and grants the RAI Native diff --git a/fraud-detection/fraud_detection_rules.ipynb b/fraud-detection/fraud_detection_rules.ipynb index dc392a8a..b410bdba 100644 --- a/fraud-detection/fraud_detection_rules.ipynb +++ b/fraud-detection/fraud_detection_rules.ipynb @@ -37,7 +37,7 @@ "metadata": {}, "outputs": [], "source": [ - "%pip install -U \"relationalai==1.0.14\"" + "%pip install -U \"relationalai==2.1.1\"" ] }, { @@ -105,12 +105,16 @@ "Address.city = m.Property(f\"{Address} is in city {String:city}\")\n", "Address.state = m.Property(f\"{Address} is in state {String:state}\")\n", "\n", + "CreditCard = m.Concept(\"CreditCard\", identify_by={\"number\": String})\n", + "Phone = m.Concept(\"Phone\", identify_by={\"number\": String})\n", + "Email = m.Concept(\"Email\", identify_by={\"address\": String})\n", + "\n", "User = m.Concept(\"User\", identify_by={\"id\": Integer})\n", "User.fullname = m.Property(f\"{User} is named {String:fullname}\")\n", - "User.phone_number = m.Property(f\"{User} has phone number {String:phone_number}\")\n", - "User.email = m.Property(f\"{User} has email {String:email}\")\n", - "User.credit_card_number = m.Property(f\"{User} has credit card number {String:credit_card_number}\")\n", - "User.address = m.Relationship(f\"{User} lives at {Address:address}\")" + "User.has_address = m.Relationship(f\"{User} lives at {Address:address}\")\n", + "User.has_credit_card = m.Relationship(f\"{User} has {CreditCard:credit_card}\")\n", + "User.has_phone = m.Relationship(f\"{User} has {Phone:phone}\")\n", + "User.has_email = m.Relationship(f\"{User} has {Email:email}\")" ] }, { @@ -118,7 +122,7 @@ "id": "f5fd6aed", "metadata": {}, "source": [ - "`Address` and `User` are *entity types* that are identified by an `id` property." + "`User` and `Address` are *entity types* that are identified by an `id` property. `CreditCard`, `Phone`, and `Email` are identified by their value, so users who share a phone number or an email are linked to the same `Phone` or `Email`." ] }, { @@ -144,8 +148,11 @@ "m.define(Address.new(addresses.to_schema()))\n", "m.define(\n", " User.new(\n", - " users.to_schema(exclude=[\"address_id\"]),\n", - " address=Address.filter_by(id=users.address_id),\n", + " users.to_schema(exclude=[\"address_id\", \"credit_card_number\", \"phone_number\", \"email\"]),\n", + " has_address=Address.lookup(id=users.address_id),\n", + " has_credit_card=CreditCard.new(number=users.credit_card_number),\n", + " has_phone=Phone.new(number=users.phone_number),\n", + " has_email=Email.new(address=users.email),\n", " )\n", ")" ] @@ -168,7 +175,7 @@ "\n", "Let's query users and their linked entities.\n", "\n", - "Each `User` now links to an `Address`." + "Each `User` now links to an `Address`, a `CreditCard`, a `Phone`, and an `Email`." ] }, { @@ -180,10 +187,10 @@ "source": [ "m.select(\n", " User.fullname,\n", - " User.address.street_address,\n", - " User.credit_card,\n", - " User.email,\n", - " User.phone,\n", + " User.has_address.street_address,\n", + " User.has_credit_card.number.alias(\"credit_card_number\"),\n", + " User.has_email.address.alias(\"email\"),\n", + " User.has_phone.number.alias(\"phone_number\"),\n", ").to_df()" ] }, @@ -215,7 +222,11 @@ " g.Edge.new(src=User, dst=User.has_email),\n", ")\n", "\n", - "User.community = g.weakly_connected_component(of=User)" + "wcc = g.weakly_connected_component()\n", + "community = g.Node.ref(\"community\")\n", + "\n", + "User.community = m.Property(f\"{User} is in community {g.Node:community}\")\n", + "m.define(User.community(User, community)).where(wcc(User, community))" ] }, { @@ -324,7 +335,7 @@ "outputs": [], "source": [ "m.define(SuspiciousUser(User)).where(\n", - " User.address == SuspiciousUser.address,\n", + " User.has_address == SuspiciousUser.has_address,\n", ")" ] }, diff --git a/fraud-detection/pyproject.toml b/fraud-detection/pyproject.toml index a942bbaa..89962d2f 100644 --- a/fraud-detection/pyproject.toml +++ b/fraud-detection/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: fraud_detection (PyRel v1)" readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai[gnn]==1.27.1", + "relationalai[gnn]==2.1.1", "pandas>=2.0", "numpy", "jupyter", diff --git a/hospital_staffing/README.md b/hospital_staffing/README.md index b5d43198..0a091122 100644 --- a/hospital_staffing/README.md +++ b/hospital_staffing/README.md @@ -52,7 +52,7 @@ The result is a Pareto frontier that reveals exactly how much overtime cost each ### Tools - Python >= 3.10 -- RelationalAI Python SDK (`relationalai`) >= 1.0.14 +- RelationalAI Python SDK (`relationalai`) == 2.1.1 ## Quickstart diff --git a/hospital_staffing/pyproject.toml b/hospital_staffing/pyproject.toml index 2e046b4e..2b922a9d 100644 --- a/hospital_staffing/pyproject.toml +++ b/hospital_staffing/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: hospital_staffing (PyRel v1)" readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai==1.0.14", + "relationalai==2.1.1", "pandas", ] diff --git a/humanitarian-aid-supply-chain/README.md b/humanitarian-aid-supply-chain/README.md index 6434766a..ef3edcb9 100644 --- a/humanitarian-aid-supply-chain/README.md +++ b/humanitarian-aid-supply-chain/README.md @@ -58,7 +58,7 @@ Built using **graph analysis** — PageRank (an iterative random-walk algorithm) ### Tools - Python >= 3.10 -- RelationalAI Python SDK (`relationalai == 1.11.0`) +- RelationalAI Python SDK (`relationalai == 2.1.1`) - For the interactive app only: the `visualization` extra (`python -m pip install .[visualization]`) ## Quickstart diff --git a/humanitarian-aid-supply-chain/pyproject.toml b/humanitarian-aid-supply-chain/pyproject.toml index a0197b50..e253dc8e 100644 --- a/humanitarian-aid-supply-chain/pyproject.toml +++ b/humanitarian-aid-supply-chain/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: humanitarian aid supply chain with PageRan readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai==1.11.0", + "relationalai==2.1.1", "pandas>=2.0.0", ] diff --git a/it-dependency-mapping/README.md b/it-dependency-mapping/README.md index ff76dce2..1c7ad8f5 100644 --- a/it-dependency-mapping/README.md +++ b/it-dependency-mapping/README.md @@ -23,7 +23,7 @@ Modern software estates are webs of dependencies: raw data sources feed ingestio This template demonstrates **Graph** reasoning -- specifically variable-length path traversal -- over a dependency directed acyclic graph (DAG): -1. **Path enumeration** (`model.path(Feature.contributes_to.repeat(1, N)).all_paths()`) -- Walk every downstream dependency path of every length. Because the estate is acyclic, each enumerated path is a simple chain. +1. **Path enumeration** (`model.path(Feature.contributes_to.repeat(1, N)).all().paths()`) -- Walk every downstream dependency path of every length. Because the estate is acyclic, each enumerated path is a simple chain. 2. **Maximal-chain reduction** -- Collapse the full path set down to the longest non-extendable chains, dropping the shorter sub-chains contained inside them, so the end-to-end propagation paths stand out. ## Who this is for @@ -40,7 +40,7 @@ This template demonstrates **Graph** reasoning -- specifically variable-length p - `Feature.max_downstream_depth` persisted back to the ontology, so downstream queries can rank features by reach without re-enumerating paths. - The owners along the single longest chain -- the worst-case change/incident blast radius. -Built using RelationalAI's **variable-length path enumeration** (`model.path(...).all_paths()`) over an acyclic dependency graph. +Built using RelationalAI's **variable-length path enumeration** (`model.path(...).all().paths()`) over an acyclic dependency graph. ## What's included @@ -58,7 +58,7 @@ Built using RelationalAI's **variable-length path enumeration** (`model.path(... ### Tools - Python >= 3.10 -- `relationalai >= 1.15` -- the path-traversal API is a preview capability. +- `relationalai` 2.1.1, the version pinned in `pyproject.toml` -- the path-traversal API is a preview capability. - The `rai` CLI (ships with the `relationalai` SDK) for configuring your connection. ## Quickstart @@ -163,7 +163,7 @@ CSV files --> Define Feature + contributes_to --> Enumerate downstream paths --> **Load the ontology.** A `Feature` is any node in the estate -- a raw source, pipeline, feature job, service, or dashboard -- with `id`, `name`, `owner`, and `deploy_tier` loaded from `data/features.csv`. The `contributes_to` self-relationship records that an upstream feature feeds a downstream one, forming the dependency DAG from `data/dependencies.csv`. -**Enumerate downstream paths.** A variable-length traversal of 1 to `MAX_DEPTH` `contributes_to` edges, enumerated with `.all_paths()`, walks every downstream dependency path. Each path arrives as one row per visited node; grouping by path reassembles the ordered chain, and the hop count comes from the maximum node index. (Selecting the path length alongside the nodes would fan the rows out, so the code derives hops from the index and dedupes before reassembly.) +**Enumerate downstream paths.** A variable-length traversal of 1 to `MAX_DEPTH` `contributes_to` edges, enumerated with `.all().paths()`, walks every downstream dependency path. Each path arrives as one row per visited node; grouping by path reassembles the ordered chain, and the hop count comes from the maximum node index. (Selecting the path length alongside the nodes would fan the rows out, so the code derives hops from the index and dedupes before reassembly.) **Persist longest downstream depth.** The longest path starting at each feature is its downstream depth. RelationalAI computes it in PyRel — a max over path length per source endpoint — and defines it straight onto the feature as a first-class `max_downstream_depth` property, with no DataFrame round-trip, so later queries can rank features by reach without re-enumerating paths. @@ -231,7 +231,7 @@ The deepest chain runs five hops from a raw source all the way to a downstream d
Why does path enumeration hang or return far more paths than expected? -- `all_paths()` enumerates walks. On an acyclic estate every walk is a simple chain, but if you add an edge that introduces a cycle the enumeration can explode. Keep `contributes_to` acyclic, and use `MAX_DEPTH` to bound traversal. +- `.all().paths()` enumerates walks. On an acyclic estate every walk is a simple chain, but if you add an edge that introduces a cycle the enumeration can explode. Keep `contributes_to` acyclic, and use `MAX_DEPTH` to bound traversal.
diff --git a/it-dependency-mapping/it_dependency_mapping.py b/it-dependency-mapping/it_dependency_mapping.py index db1897c1..5008e4d5 100644 --- a/it-dependency-mapping/it_dependency_mapping.py +++ b/it-dependency-mapping/it_dependency_mapping.py @@ -6,7 +6,7 @@ - Loads Feature nodes (services, pipelines, jobs, dashboards) and a contributes_to self-relationship (feeds / contributes to) from CSV. - Enumerates every downstream dependency path with - ``model.path(Feature.contributes_to.repeat(1, N)).all_paths()`` -- because the + ``model.path(Feature.contributes_to.repeat(1, N)).all().paths()`` -- because the estate is acyclic, every enumerated path is simple. - Reduces the full path set to its maximal chains (longest non-extendable dependency chains, with shorter sub-chains dropped). @@ -85,7 +85,7 @@ def load_csv(path): # -------------------------------------------------- # model.path(src, Feature.contributes_to.repeat(1, MAX_DEPTH)) describes a # variable-length traversal of 1..MAX_DEPTH contributes_to edges starting from a -# typed source endpoint `src`. all_paths() enumerates every such path; because +# typed source endpoint `src`. .all().paths() enumerates every such path; because # contributes_to is acyclic, each path is simple. The result is one PathTraversal # per path -- p.length is its hop count, p.nodes is the ordered sequence of # Feature nodes it visits, and src is auto-unified with p.nodes(0) (the start). @@ -93,7 +93,7 @@ def load_csv(path): print("=== IT Dependency Mapping: downstream paths ===") src = Feature.ref() -p = model.path(src, Feature.contributes_to.repeat(1, MAX_DEPTH)).all_paths() +p = model.path(src, Feature.contributes_to.repeat(1, MAX_DEPTH)).all().paths() # Project the node sequence of each path (for display-side reassembly). Keep this # its own query: selecting p.length or a path aggregate alongside p.nodes fans the diff --git a/it-dependency-mapping/pyproject.toml b/it-dependency-mapping/pyproject.toml index a6cb4125..22dedcbc 100644 --- a/it-dependency-mapping/pyproject.toml +++ b/it-dependency-mapping/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: map downstream software / data-pipeline de readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai==1.15.0", + "relationalai==2.1.1", "pandas>=2.0.0", ] diff --git a/it-dependency-mapping/runbook.md b/it-dependency-mapping/runbook.md index ef5ce63a..1eb6a827 100644 --- a/it-dependency-mapping/runbook.md +++ b/it-dependency-mapping/runbook.md @@ -7,7 +7,7 @@ Dependency DAG (14 features: sources -> pipelines -> jobs -> services -> dashbo │ ▼ /rai-graph-analysis — Variable-length path enumeration (paths: relationalai>=1.15) - • every downstream dependency path (1-8 hops, all_paths) -> 46 paths + • every downstream dependency path (1-8 hops, all().paths()) -> 46 paths • per-feature reach + persist Feature.max_downstream_depth -> Clickstream Ingest: 7 paths / depth 5 • maximal end-to-end chains (sub-chains dropped) -> 6 of 46 • longest chain = worst-case blast radius + owners along it -> 5 hops, 6 features / 5 owners @@ -33,7 +33,7 @@ Each prompt is pasted into a fresh agent session loaded with the named `/rai-*` **Prompt:** /rai-graph-analysis For every feature, how far does its blast radius reach downstream? Enumerate all downstream dependency paths of any length, count how many start at each feature, and record each feature's longest downstream depth so we can rank features by reach. -**Response:** Variable-length path enumeration (`.all_paths()` over 1–8 `contributes_to` hops) finds 46 downstream paths in total; because the estate is acyclic, every path is a simple chain. Transaction CDC Stream spawns the most downstream paths (9, reaching depth 4), while Clickstream Ingest reaches the deepest (7 paths, depth 5) — "most paths" and "furthest reach" are different questions with different answers. The two leaf dashboards start none. Each feature's longest depth is persisted as `Feature.max_downstream_depth` so a later query can rank by reach without re-enumerating. +**Response:** Variable-length path enumeration (`.all().paths()` over 1–8 `contributes_to` hops) finds 46 downstream paths in total; because the estate is acyclic, every path is a simple chain. Transaction CDC Stream spawns the most downstream paths (9, reaching depth 4), while Clickstream Ingest reaches the deepest (7 paths, depth 5) — "most paths" and "furthest reach" are different questions with different answers. The two leaf dashboards start none. Each feature's longest depth is persisted as `Feature.max_downstream_depth` so a later query can rank by reach without re-enumerating. ## 4. Maximal end-to-end chains diff --git a/memory_supply_allocation/README.md b/memory_supply_allocation/README.md index 7f687713..cee443c6 100644 --- a/memory_supply_allocation/README.md +++ b/memory_supply_allocation/README.md @@ -59,7 +59,7 @@ This template shows how RelationalAI answers that question on a single shared mo ### Tools - Python >= 3.10 -- RelationalAI Python SDK (`relationalai[gnn]==1.27.1`) +- RelationalAI Python SDK (`relationalai[gnn]==2.1.1`) ### One-time Snowflake setup (predictive GNN) @@ -195,7 +195,7 @@ effective_capacity = Σ_suppliers (nominal × capability_pct) × Π_inputs (1 Each solve is constrained by capacity, a yield-aware demand cap, and the base and elevated service floors. A per-customer plan-diff against the previous solve is the headline: hyperscalers absorb the disruption while equipment-maker customers stay pinned at their elevated floors. -**Stage 4 (Graph)** enumerates variable-length dependency chains with `model.path(Customer.depends_on.repeat(1, 3)).all_paths()` for root-cause analysis, then runs two what-if branches that reuse Stage 3's capacity helper so impact stays consistent with the optimization: one takes each supplier offline, the other drops each input to 30% availability, ranking the widest blast radius. +**Stage 4 (Graph)** enumerates variable-length dependency chains with `model.path(Customer.depends_on.repeat(1, 3)).all().paths()` for root-cause analysis, then runs two what-if branches that reuse Stage 3's capacity helper so impact stays consistent with the optimization: one takes each supplier offline, the other drops each input to 30% availability, ranking the widest blast radius. ## Customize this template @@ -203,7 +203,7 @@ Each solve is constrained by capacity, a yield-aware demand cap, and the base an - Replace the CSVs in `data/` with your own, keeping the headers documented in [Sample data](#sample-data). - Add suppliers or inputs by appending rows to `suppliers.csv` + `supplier_product_capacity.csv`, or `inputs.csv` + `input_usage.csv`; the LP picks up new entities automatically. -- Extend the dependency graph by adding rows to `dependencies.csv`. For chains longer than 3 hops, raise the `repeat(1, 3)` bound in Stage 4. Avoid cycles — `.all_paths()` returns walks, which can blow up enumeration. +- Extend the dependency graph by adding rows to `dependencies.csv`. For chains longer than 3 hops, raise the `repeat(1, 3)` bound in Stage 4. Avoid cycles — `.all().paths()` returns walks, which can blow up enumeration. ### Tune parameters @@ -221,7 +221,7 @@ Each solve is constrained by capacity, a yield-aware demand cap, and the base an ### Scale up / productionize - **Engine sizing**: the GNN path needs a GPU-sized predictive reasoner (`GPU_NV_S`); the LP solves on the default `highs` solver. -- **Reproducibility**: pin `relationalai[gnn]==1.27.1`, set `GNN_SEED`, and prefer `USE_PRECOMPUTED_FORECAST = True` for deterministic, offline reruns. +- **Reproducibility**: pin `relationalai[gnn]==2.1.1`, set `GNN_SEED`, and prefer `USE_PRECOMPUTED_FORECAST = True` for deterministic, offline reruns. - **Scheduling**: the script is a single entrypoint, so it drops into any scheduler or pipeline that can run `python memory_supply_allocation.py`. ## Troubleshooting @@ -284,7 +284,7 @@ Ensure your Snowflake account has the RAI Native App installed and your user has - [Predictive reasoner (GNN)](https://docs.relational.ai/) — heterogeneous-graph regression, PropertyTransformer, and edge patterns (Stage 2). - [Prescriptive reasoner](https://docs.relational.ai/) — the `Problem` API, decision variables, constraints, and objectives (Stage 3). -- [Graph reasoner / paths](https://docs.relational.ai/) — variable-length path traversal with `.repeat(...).all_paths()` (Stage 4). +- [Graph reasoner / paths](https://docs.relational.ai/) — variable-length path traversal with `.repeat(...).all().paths()` (Stage 4). ## Support diff --git a/memory_supply_allocation/memory_supply_allocation.py b/memory_supply_allocation/memory_supply_allocation.py index 2e6db3ae..d12210aa 100644 --- a/memory_supply_allocation/memory_supply_allocation.py +++ b/memory_supply_allocation/memory_supply_allocation.py @@ -17,7 +17,7 @@ remaining horizon. Effective capacity per (product, period) = sum over suppliers of nominal x predicted capability, scaled by input availability. - Stage 4 (Graph / PATHS): enumerate variable-length dependency chains via - `model.path(Customer.depends_on.repeat(1, 3)).all_paths()` for root cause + `model.path(Customer.depends_on.repeat(1, 3)).all().paths()` for root cause on the customer-customer graph. Two what-if branches: (1) supplier goes offline, (2) raw-material input shortage. Each surfaces affected (product, period) cells without re-solving the LP. @@ -695,7 +695,7 @@ def compute_effective_capacity(forecast_df_state, input_avail_state): p_pattern = model.path(Customer.depends_on.repeat(1, 3)) paths_df = model.where( - p := p_pattern.all_paths(), + p := p_pattern.all().paths(), ).select( p.alias("path_id"), p.length.alias("hops"), diff --git a/memory_supply_allocation/pyproject.toml b/memory_supply_allocation/pyproject.toml index 56e4fd9f..e3f4f1ae 100644 --- a/memory_supply_allocation/pyproject.toml +++ b/memory_supply_allocation/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: memory_supply_allocation (PyRel v1)" readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai[gnn]==1.27.1", + "relationalai[gnn]==2.1.1", "pandas", ] diff --git a/memory_supply_allocation/runbook.md b/memory_supply_allocation/runbook.md index f2459b4d..dca360a9 100644 --- a/memory_supply_allocation/runbook.md +++ b/memory_supply_allocation/runbook.md @@ -159,7 +159,7 @@ Cast `PathTraversal.length` to int before pandas comparisons (the paths library **Response** -9 total paths via `model.path(Customer.depends_on.repeat(1, 3)).all_paths()`: 7 one-hop and 2 two-hop. Multi-hop chains: `Hyperion → Photonic → Apex` and `Aether → Photonic → Apex`. Photonic Lithography has 2 paths terminating, Vertex and Crystal each have 2, and Apex has 3 (1 direct + 2 indirect through Photonic). Despite Apex's higher terminating-path count, it is still the lone dependency SPOF — `model.where(Customer.is_dependency_spof()).select(Customer.name).to_df()` returns Apex Photonic Components as the only row. The indirect paths through Photonic protect Apex only as long as the direct Photonic → Apex edge stands; removing that edge drops Apex's effective floor from 0.90 back to its 0.70 base. +9 total paths via `model.path(Customer.depends_on.repeat(1, 3)).all().paths()`: 7 one-hop and 2 two-hop. Multi-hop chains: `Hyperion → Photonic → Apex` and `Aether → Photonic → Apex`. Photonic Lithography has 2 paths terminating, Vertex and Crystal each have 2, and Apex has 3 (1 direct + 2 indirect through Photonic). Despite Apex's higher terminating-path count, it is still the lone dependency SPOF — `model.where(Customer.is_dependency_spof()).select(Customer.name).to_df()` returns Apex Photonic Components as the only row. The indirect paths through Photonic protect Apex only as long as the direct Photonic → Apex edge stands; removing that edge drops Apex's effective floor from 0.90 back to its 0.70 base. ### 9. What-if: supplier offline and input shortage @@ -196,5 +196,5 @@ This runbook was paste-tested against fresh `/rai-*` skill sessions on 2026-05-2 - **Margin totals are invariant across runs and across Stage-2 paths.** HiGHS produces the same LP objective bit-exactly. The bundled `supplier_capability_forecast.csv` is a snapshot of the GNN's output, so `USE_PRECOMPUTED_FORECAST=True` and `USE_PRECOMPUTED_FORECAST=False` produce identical $45,488,032,436 / $40,523,678,803 / $28,972,506,958 margins on the three iterations, plus identical Stage 9 cascade rankings (Orion 72 cells / 60.0% drop, Helium 180 cells). The CSV is refreshed via `dev_temp/snapshot_gnn_forecast.py` whenever supplier features or historical observations change. - **Per-customer service-level splits are LP-degenerate** — multiple optimal allocations with identical total margin exist on the feasible face. Step 6's documented hyperscaler service levels are representative ranges; the exact per-customer split may drift a few percentage points run-to-run while structural facts (equipment makers pinned at elevated floor, hyperscalers below 100%) hold. - **Input disruption semantics**: the script applies input disruptions (helium shortage) persistently from the reveal period through end-of-horizon, not just within the `start_period`–`end_period` window in `disruption_reveal.csv` (suppliers DO respect the window). The runbook's iter 2 margin reflects this. A future revision could symmetrize the semantics. -- **Step 8 (paths library)** is the only step that needed an explicit Setup note to reproduce, because the `model.path(...).all_paths()` API is new and not yet documented in `rai-graph-analysis`. Both the relationship signature (role short_names) AND the entity-binding population pattern (via two `Customer.ref()`, not via FK-Property navigation) are required — paste-testing surfaced both gaps. The underlying API is documented at `relationalai/semantics/std/paths/README.md`; full integration into the graph-analysis skill is a planned follow-up that will obviate the Setup note. +- **Step 8 (paths library)** is the only step that needed an explicit Setup note to reproduce, because the `model.path(...).all().paths()` API is new and not yet documented in `rai-graph-analysis`. Both the relationship signature (role short_names) AND the entity-binding population pattern (via two `Customer.ref()`, not via FK-Property navigation) are required — paste-testing surfaced both gaps. The underlying API is documented at `relationalai/semantics/std/path/README.md`; full integration into the graph-analysis skill is a planned follow-up that will obviate the Setup note. - **Sparse derived properties**: a derived property bound only to customers with an incoming or outgoing dependency (e.g., 5 out of 11 rows) silently fails to ground downstream solver constraints — symptom is alloc grossly exceeding demand, not an obvious INFEASIBLE. Always coalesce with `| 0.0` or `| base_value` so every entity has a value. diff --git a/money_laundering_motif_detection/pyproject.toml b/money_laundering_motif_detection/pyproject.toml index 225606d9..5955fa2a 100644 --- a/money_laundering_motif_detection/pyproject.toml +++ b/money_laundering_motif_detection/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: money_laundering_motif_detection (PyRel v1 readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai==1.1.0", + "relationalai==2.1.1", "pandas", ] diff --git a/network_flow_planning/README.md b/network_flow_planning/README.md index 2ac24448..7dd71367 100644 --- a/network_flow_planning/README.md +++ b/network_flow_planning/README.md @@ -66,7 +66,7 @@ The objective minimizes transport cost plus fixed-cost FC opening cost. ### Tools - Python >= 3.10 -- RelationalAI Python SDK (`relationalai`) == 1.11.0 +- RelationalAI Python SDK (`relationalai`) == 2.1.1 ## Quickstart @@ -178,7 +178,7 @@ The model runs as a single MILP that decides flow on every lane and which fulfil **Constraints.** Each site type contributes the constraint that matches its role. Warehouses cap total outflow at their inventory. Transit hubs and fulfillment centers conserve flow — inflow equals outflow. A fulfillment center's inflow is bounded by `capacity × x_open`, so an unopened FC (open = 0) can carry no flow and the fixed cost is only incurred when it is opened. Customers require inflow to meet their aggregate demand. -**Objective.** Minimize transport cost (per-unit lane cost times flow, summed over lanes) plus the fixed cost of every opened fulfillment center. The two cost terms live on different concepts (`Lane` and `Site`), so they are combined into one per-entity sum that the objective minimizes. +**Objective.** Minimize transport cost (per-unit lane cost times flow, summed over lanes) plus the fixed cost of every opened fulfillment center. The two cost terms live on different concepts (`Lane` and `Site`), so the objective adds one sum per concept. For the exact PyRel formulation, see `network_flow_planning.py`; `runbook.md` reproduces the model step by step with the RAI skills. @@ -236,16 +236,16 @@ Replace the three CSVs in `data/` with your own:
- Why is model.union needed in the objective? + Why does the objective add two sums? - PyRel disallows `+` between aggregated terms of different concepts. `model.union` lets the outer `sum` aggregate per-Lane and per-Site cost terms in a single objective. Each branch must be a per-entity expression, not a fully-aggregated scalar. + The transport cost lives on `Lane` and the fixed cost on `Site`, so each is summed over its own concept and the two totals are added. A single `sum` over `model.union(...)` of both terms is refused: a union keeps one copy of equal values, while the solver needs every lane's and every site's term.
## Learn more ### Core concepts -- [PyRel v1 query language](https://docs.relational.ai/) — `model.where(...)`, `sum(...).per(...)`, and `model.union` for multi-concept objectives. +- [PyRel v1 query language](https://docs.relational.ai/) — `model.where(...)` and `sum(...).per(...)`. - [Prescriptive reasoner](https://docs.relational.ai/) — the `Problem` API: decision variables (`solve_for`), constraints (`satisfy`), and objectives (`minimize` / `maximize`). ### Language / modeling reference diff --git a/network_flow_planning/network_flow_planning.py b/network_flow_planning/network_flow_planning.py index d30edea5..cc22ef41 100644 --- a/network_flow_planning/network_flow_planning.py +++ b/network_flow_planning/network_flow_planning.py @@ -176,12 +176,10 @@ )) # Objective: minimize transport cost + fixed cost of opened fulfillment centers. -# Each branch of model.union must be a per-entity expression (per Lane and per -# Site here), aggregated by the outer sum. -problem.minimize(sum(model.union( - Lane.cost_per_unit * Lane.x_flow, - Site.fixed_cost * Site.x_open, -))) +# With no site that has a fixed cost the second sum is empty; `| 0.0` makes it zero. +problem.minimize( + sum(Lane.cost_per_unit * Lane.x_flow) + (sum(Site.fixed_cost * Site.x_open) | 0.0) +) # -------------------------------------------------- # Solve and check solution diff --git a/network_flow_planning/pyproject.toml b/network_flow_planning/pyproject.toml index b5942387..4f229363 100644 --- a/network_flow_planning/pyproject.toml +++ b/network_flow_planning/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: network_flow_planning (PyRel v1)" readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai==1.11.0", + "relationalai==2.1.1", "pandas", ] diff --git a/patient_cohort_recruitment/README.md b/patient_cohort_recruitment/README.md index 9eda2246..da9eee6f 100644 --- a/patient_cohort_recruitment/README.md +++ b/patient_cohort_recruitment/README.md @@ -66,7 +66,7 @@ The bundled CSVs are illustrative, fully synthetic demo data (e.g. patient names ### Tools - Python >= 3.10 -- RelationalAI Python SDK (`relationalai == 1.1.0`) +- RelationalAI Python SDK (`relationalai == 2.1.1`) ## Quickstart diff --git a/patient_cohort_recruitment/pyproject.toml b/patient_cohort_recruitment/pyproject.toml index aa89aa03..5aa7459c 100644 --- a/patient_cohort_recruitment/pyproject.toml +++ b/patient_cohort_recruitment/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: patient_cohort_recruitment (PyRel v1)" readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai==1.1.0", + "relationalai==2.1.1", "pandas>=2.0", ] diff --git a/planogram_optimization/README.md b/planogram_optimization/README.md index fce08be2..caf6275c 100644 --- a/planogram_optimization/README.md +++ b/planogram_optimization/README.md @@ -60,7 +60,7 @@ The same pattern applies to any predict-then-optimize problem where the predicti ### Tools - Python >= 3.10 -- RelationalAI Python SDK (`relationalai == 1.1.0`) +- RelationalAI Python SDK (`relationalai == 2.1.1`) ## Quickstart @@ -241,8 +241,8 @@ For the exact PyRel formulation, see `planogram_optimization.py`; `runbook.md` r Import error or AttributeError on relationalai - Confirm your virtual environment is active: `which python` should point to `.venv`. -- Reinstall dependencies: `python -m pip install .`. The pinned version (`relationalai==1.1.0`) ships the `solve_info()`, `verify()`, and `where().require()` APIs this template uses; older versions lack them and produce attribute errors. -- If you share a venv across templates, run `python -m pip install --upgrade --force-reinstall relationalai==1.1.0`. +- Reinstall dependencies: `python -m pip install .`. The pinned version (`relationalai==2.1.1`) ships the `solve_info()`, `verify()`, and `where().require()` APIs this template uses; older versions lack them and produce attribute errors. +- If you share a venv across templates, run `python -m pip install --upgrade --force-reinstall relationalai==2.1.1`. diff --git a/planogram_optimization/pyproject.toml b/planogram_optimization/pyproject.toml index a9cdd505..a9640894 100644 --- a/planogram_optimization/pyproject.toml +++ b/planogram_optimization/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: planogram_optimization (PyRel v1)" readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai==1.1.0", + "relationalai==2.1.1", "pandas>=2.0", ] diff --git a/pod_placement/README.md b/pod_placement/README.md index 838b0daf..d9cfc7c3 100644 --- a/pod_placement/README.md +++ b/pod_placement/README.md @@ -71,7 +71,7 @@ The bundled CSVs are illustrative demo data tuned so multiple ICs bind at the op ### Tools - Python >= 3.10 -- RelationalAI Python SDK (`relationalai == 1.1.0`) +- RelationalAI Python SDK (`relationalai == 2.1.1`) ## Quickstart @@ -256,7 +256,7 @@ For the exact PyRel formulation, see `pod_placement.py`; `runbook.md` reproduces Import error or AttributeError on relationalai - Confirm your virtual environment is active: `which python` should point to `.venv`. -- Reinstall dependencies: `python -m pip install .`. The pinned version (`relationalai==1.1.0`) ships the `solve_info()`, `verify()`, and `where().require()` APIs this template uses; older versions lack them and produce attribute errors. +- Reinstall dependencies: `python -m pip install .`. The pinned version (`relationalai==2.1.1`) ships the `solve_info()`, `verify()`, and `where().require()` APIs this template uses; older versions lack them and produce attribute errors. diff --git a/pod_placement/pyproject.toml b/pod_placement/pyproject.toml index ff9eb8d1..3dd3a7bb 100644 --- a/pod_placement/pyproject.toml +++ b/pod_placement/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: pod_placement (PyRel v1)" readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai==1.1.0", + "relationalai==2.1.1", "pandas>=2.0", ] diff --git a/portfolio_balancing/README.md b/portfolio_balancing/README.md index 49081ac2..d0a514ce 100644 --- a/portfolio_balancing/README.md +++ b/portfolio_balancing/README.md @@ -34,7 +34,7 @@ Before you start, install Python 3.10 or later and get access to a Snowflake account with the RAI Native App. Graph and Prescriptive reasoning are in Public Preview; ask your RelationalAI support representative to enable Prescriptive reasoning. Preview features are for evaluation and testing, not production -applications. The template pins `relationalai==1.9.0` in `pyproject.toml`. +applications. The template pins `relationalai==2.1.1` in `pyproject.toml`. Use this sequence to run the bundled example: diff --git a/portfolio_balancing/pyproject.toml b/portfolio_balancing/pyproject.toml index 78fdae48..bb242c83 100644 --- a/portfolio_balancing/pyproject.toml +++ b/portfolio_balancing/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: portfolio_balancing (PyRel v1)" readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai==1.9.0", + "relationalai==2.1.1", "pandas>=2.0", ] diff --git a/product_configurator/README.md b/product_configurator/README.md index 7b25f7dc..10ce43bd 100644 --- a/product_configurator/README.md +++ b/product_configurator/README.md @@ -58,7 +58,7 @@ The configurator scenario here is automotive trim, drawn from the public Renault ### Tools - Python >= 3.10 -- RelationalAI Python SDK (`relationalai`) >= 1.1.0 +- RelationalAI Python SDK (`relationalai`) == 2.1.1 ## Quickstart diff --git a/product_configurator/pyproject.toml b/product_configurator/pyproject.toml index fa3f9161..6cf19687 100644 --- a/product_configurator/pyproject.toml +++ b/product_configurator/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: product_configurator (PyRel v1)" readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai==1.1.0", + "relationalai==2.1.1", "pandas>=2.0", ] diff --git a/production_planning/pyproject.toml b/production_planning/pyproject.toml index b1dcca17..33675a0e 100644 --- a/production_planning/pyproject.toml +++ b/production_planning/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: production_planning (PyRel v1)" readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai==1.0.14", + "relationalai==2.1.1", "pandas", ] diff --git a/rai-agent-scaffold/.gitignore b/rai-agent-scaffold/.gitignore deleted file mode 100644 index e26261ac..00000000 --- a/rai-agent-scaffold/.gitignore +++ /dev/null @@ -1,22 +0,0 @@ -# Your filled-in implementation files — gitignored so credentials and -# proprietary model logic stay local. -rai-agent-config.yaml -raiconfig.yaml -ontology.py -queries.py -test_queries.py - -# Allow the checked-in example files despite the rules above. -!example/ontology.py -!example/queries.py -!example/test_queries.py - -# Python cache -__pycache__/ -*.pyc - -# Build/runtime artifacts -build/ -spans.jsonl -debug.jsonl -metadata.json diff --git a/rai-agent-scaffold/README.md b/rai-agent-scaffold/README.md deleted file mode 100644 index d9689325..00000000 --- a/rai-agent-scaffold/README.md +++ /dev/null @@ -1,308 +0,0 @@ ---- -title: "Snowflake Intelligence Agent — RelationalAI Knowledge Graph" -description: "Scaffold for packaging a RelationalAI semantic model as a Snowflake Cortex agent and exposing it through Snowflake Intelligence." -experience_level: intermediate -industry: "Cross-Industry" -reasoning_types: - - Graph -tags: - - cortex-agent - - snowflake-intelligence - - knowledge-graph - - natural-language - - semantic-layer ---- - -## What this template is for - -This template uses **Graph** reasoning over a RelationalAI semantic layer to power natural-language Q&A. RelationalAI lets you map Snowflake tables into a semantic layer — concepts, properties, and relationships — that executes directly inside Snowflake. This template wires that semantic layer into a Snowflake Cortex agent so users can ask natural-language questions about their data from anywhere in Snowflake Intelligence. - -The scaffold provides the full lifecycle tooling: define your model, test queries locally, deploy stored procedures and the agent, push updates, and tear everything down — all from a single CLI script. - -## Who this is for - -- Engineers and data modelers who have a Snowflake table they want to expose conversationally -- Teams building or evaluating RAI-powered Snowflake Intelligence integrations -- Assumed knowledge: basic Python, familiarity with Snowflake, some exposure to PyRel concepts (concepts, properties, model.define) - -## What you'll build - -- A PyRel semantic model (ontology) that maps your source table to typed concepts and properties -- A set of curated analytical queries the agent can execute on demand -- A deployed Snowflake Cortex agent with stored procedures backed by the model -- A Snowflake Intelligence integration that lets users ask natural-language questions against your data - -## What's included - -- **Model** (`ontology.example.py`): Example concept and property definitions with a parent/child hierarchy and label tagging pattern -- **Queries** (`queries.example.py`): Two example queries — category breakdown and label traceability — plus the `ToolRegistry` wiring -- **Runner** (`si_agent.py`): CLI for deploy / update / status / chat / teardown -- **Config template** (`rai-agent-config.example.yaml`): All instance-specific values in one place -- **Local smoke test** (`test_queries.example.py`): Runs both queries directly against Snowflake before deploying -- **Working example** (`example/`): End-to-end employee directory implementation you can run immediately with the included sample data — useful as a reference before building your own model - -## Prerequisites - -### Access - -- RelationalAI native app installed in your Snowflake account -- `ACCOUNTADMIN` role (or equivalent) with `CREATE PROCEDURE`, `CREATE STAGE`, and `CREATE AGENT` on the target schema -- The target schema must exist before deploying -- Change tracking enabled on the source table: - ```sql - ALTER TABLE .. SET CHANGE_TRACKING = TRUE; - ``` - -### Tools - -- Python 3.10+ -- `relationalai>=1.0.14`, `httpx`, `pyyaml` (see `pyproject.toml`) - -## Quickstart - -> **New to this scaffold?** The `example/` directory contains a fully-wired employee -> directory implementation with sample data you can deploy immediately. Follow the -> [example README](example/README.md) to get your first agent running, then come back -> here to build your own model. - -1. **Install dependencies** - - ```bash - python -m venv .venv - source .venv/bin/activate - pip install -e . - ``` - -2. **Copy and fill in config files** - - ```bash - cp rai-agent-config.example.yaml rai-agent-config.yaml - cp ontology.example.py ontology.py - cp queries.example.py queries.py - cp test_queries.example.py test_queries.py - ``` - - Edit `rai-agent-config.yaml` with your agent name, database, schema, warehouse, model name, and source table. - - Create `raiconfig.yaml` with your Snowflake credentials (see Configuration below). - -3. **Define your model** - - Edit `ontology.py` — replace the `Node`/`Edge` example with concepts and properties that match your source table. - -4. **Define your queries** - - Edit `queries.py` — replace or extend the example query functions. Each function's docstring is what the LLM sees to decide when to call it. - -5. **Test locally** - - ```bash - RAI_CONFIG_FILE_PATH=raiconfig.yaml python test_queries.py - ``` - -6. **Deploy** - - ```bash - python si_agent.py deploy - python si_agent.py status - ``` - -7. **Test a question** - - ```bash - python si_agent.py chat "what can I ask about?" - ``` - -8. **Expected output** - - ```text - Deploying 'MY_AGENT_NAME' to MY_DATABASE.MY_SCHEMA ... - Agent MY_AGENT_NAME: ACTIVE (2 tools registered) - ``` - -## Template structure - -```text -. -├── README.md # this file -├── pyproject.toml # dependencies -├── si_agent.py # deployment CLI — start here -├── rai-agent-config.example.yaml # config template → copy to rai-agent-config.yaml -├── ontology.example.py # model template → copy to ontology.py -├── queries.example.py # query template → copy to queries.py -├── test_queries.example.py # local smoke test → copy to test_queries.py -└── example/ # working employee directory example — try this first - ├── README.md # quickstart for the example - ├── data/employees.csv # 12-row sample dataset - ├── ontology.py # Employee + ReportsTo concepts - ├── queries.py # headcount_by_department + direct_reports - ├── test_queries.py # local smoke test - └── rai-agent-config.example.yaml -``` - -**Start here**: `python si_agent.py deploy` - -## Configuration - -### rai-agent-config.yaml - -Single source of truth for all instance-specific values. - -```yaml -agent: - name: MY_AGENT_NAME # Name shown in Snowflake Cortex Agents UI - database: MY_DATABASE # Snowflake database to deploy into - schema: MY_SCHEMA # Schema to deploy into (must already exist) - warehouse: MY_WAREHOUSE # Warehouse for sproc execution - model_name: MY_MODEL_NAME # RAI Model name used internally in each sproc - -model: - source_table: MY_DB.MY_SCHEMA.MY_TABLE # Fully-qualified source table -``` - -### raiconfig.yaml (gitignored) - -Snowflake connection credentials used locally and during deployment. - -```yaml -connections: - sf: - account: # Snowflake account identifier - user: # Your Snowflake username - password: # Your password - warehouse: # Warehouse for query execution - role: # Must have CREATE PROCEDURE, CREATE STAGE, CREATE AGENT - rai_app_name: # Name of the RelationalAI native app (usually RELATIONALAI) -``` - -## Model overview - -The example ontology models a hierarchical dataset (e.g. a bill-of-materials or org structure) sourced from a single Snowflake table. - -- **Key entities**: `Node` (a record in the source table), `Edge` (a parent→child link between nodes) -- **Primary identifiers**: `Node` is identified by `id` (string); `Edge` by `(parent_id, child_id)` -- **Important invariants**: null `id` rows are silently dropped by null propagation — do not coalesce nulls to a sentinel - -### Concepts - -**Node** — Represents a record in the source table, deduplicated by `id`. - -| Property | Type | Identifying? | Notes | -|---|---|---|---| -| `id` | string | Yes | Loaded from `parent_id` and `child_id` columns | -| `category` | string | No | Required for `per()`-based aggregation queries | -| `label` | string | No | Optional classification tag; used by `label_trace` query | - -**Edge** — Represents a directed parent→child link between two nodes. - -| Property | Type | Identifying? | Notes | -|---|---|---|---| -| `parent_id` | string | Yes | FK to `Node.id` | -| `child_id` | string | Yes | FK to `Node.id` | - -## How it works - -1. `ontology.py` maps source table rows into `Node` and `Edge` concepts via `model.define()` -2. `queries.py` defines query functions that return `rai.Fragment` objects; each function's docstring is verbalized to the LLM -3. `si_agent.py deploy` packages `ontology.py` and `queries.py` as Snowflake stored procedures and registers a Cortex agent -4. Snowflake Intelligence routes natural-language questions to the agent, which selects and executes the appropriate query -5. Results are verbalized and returned as a natural-language response - -```text -Snowflake table → ontology.py → RAI model → queries.py → stored procs → Cortex agent → Snowflake Intelligence -``` - -## Customize this template - -### Use your own data - -- Set `model.source_table` in `rai-agent-config.yaml` to your fully-qualified table name -- In `ontology.py`, replace `Node`/`Edge` with concepts that match your domain -- Column names in `model.define()` must match your actual table columns - -### Add a new query - -1. Write a function in `queries.py` returning a `rai.Fragment` with a clear docstring -2. Bind and register it in `build_tool_registry` → `QueryCatalog` -3. Test locally: `python test_queries.py` -4. Push to Snowflake: `python si_agent.py update` - -### Seed labels - -In `ontology.py` inside `initialize()`: - -```python -node = Node.ref() -model.define(node.label("MY_LABEL")).where(node.id == "some-identifier") -``` - -Then run `python si_agent.py update`. - -### Scale up / productionize - -- Pin `relationalai` to a specific version in `pyproject.toml` for reproducible deploys -- Run `si_agent.py update` in CI after merging changes to `ontology.py` or `queries.py` -- Use a dedicated warehouse sized for your query volume - -## Troubleshooting - -
- Why did deployment fail with a permissions error? - - - Confirm your Snowflake role has `CREATE PROCEDURE`, `CREATE STAGE`, and `CREATE AGENT` on the target schema. - - Verify the target schema already exists — the deploy step does not create it automatically. -
- -
- Why is my source table not found? - - - Check that `model.source_table` in `rai-agent-config.yaml` is fully qualified (`DB.SCHEMA.TABLE`). - - Confirm change tracking is enabled: `ALTER TABLE ... SET CHANGE_TRACKING = TRUE`. -
- -
- Why do local test queries return duplicate rows? - - - This is a known local-execution quirk: `.to_df()` may return one row per `(node, category)` because `node` stays a free variable. Add `.drop_duplicates()` as shown in `test_queries.example.py`. The deployed sproc returns correctly aggregated results. -
- -
- Why did the sproc fail with an httpx import error? - - - `httpx` is not auto-installed as a transitive dep in Snowflake sprocs. It is explicitly added via `_EXTRA_PACKAGES` in `si_agent.py` — ensure you have not removed it. -
- -
- Why does the agent appear inactive after deploy? - - - Run `python si_agent.py status` to see the full deployment state. - - If the agent shows as pending, wait a few seconds and re-check — Cortex agent registration is asynchronous. -
- -## Known workarounds - -| Issue | Workaround applied | -|---|---| -| `snowflake-telemetry-python` conflicts with `relationalai>=1.0.x` opentelemetry dependency | Remove `snowflake-telemetry-python` from the sproc package list in the installed library (`relationalai/agent/cortex/cortex_tool_resources.py` ~line 278). Re-apply after upgrading `relationalai`. | -| `httpx` not auto-installed as a transitive dep in Snowflake sprocs | Added `"httpx"` to `_EXTRA_PACKAGES` in `si_agent.py`. | -| Local `.to_df()` returns one row per node for count queries | Added `.drop_duplicates()` in `test_queries.example.py`. | - -## Learn more - -### Core concepts - -- [Build a semantic model](https://docs.relational.ai/build/guides/modeling/]) — How `model.Concept`, `model.Property`, and `model.define()` work -- [Cortex Agents overview](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents) — Snowflake's agent framework - -### Language / modeling reference - -- [PyRel documentation](https://docs.relational.ai/build) — Tutorials and guides -- [PyRel API documentation](https://docs.relational.ai/api/python/latest/) — Full language reference for `relationalaiai` - -### Deeper dives - -- [Snowflake Intelligence](https://docs.snowflake.com/en/user-guide/snowflake-intelligence) — How to promote a Cortex agent to Snowflake Intelligence - -## Support - -- [https://support.relational.ai](https://support.relational.ai) diff --git a/rai-agent-scaffold/example/README.md b/rai-agent-scaffold/example/README.md deleted file mode 100644 index 0e5edc8b..00000000 --- a/rai-agent-scaffold/example/README.md +++ /dev/null @@ -1,117 +0,0 @@ -# Employee Directory Example - -A concrete, runnable example for the `rai-agent-scaffold` template. It models a -small company org chart and exposes it as a Snowflake Intelligence agent so users -can ask natural-language questions like: - -- *"How many people are in each department?"* -- *"Who does Alice Smith report to?"* -- *"Show me all direct reports for the engineering lead."* - -## What's in this folder - -| File | Purpose | -|---|---| -| `data/employees.csv` | 12-row sample dataset — upload this to Snowflake as your source table | -| `ontology.py` | Semantic model: `Employee` and `ReportsTo` concepts | -| `queries.py` | Two queries: `headcount_by_department` and `direct_reports` | -| `test_queries.py` | Local smoke test — run before deploying | -| `rai-agent-config.example.yaml` | Pre-filled config template | - -## Quickstart - -**1. Upload sample data to Snowflake** - -Create a table from `data/employees.csv`. The table must have these columns: -`EMPLOYEE_ID`, `NAME`, `DEPARTMENT`, `TITLE`, `MANAGER_ID`. - -Enable change tracking on the table: - -```sql -ALTER TABLE MY_DB.MY_SCHEMA.EMPLOYEES SET CHANGE_TRACKING = TRUE; -``` - -**2. Copy files to the parent scaffold directory** - -```bash -cd rai-agent-scaffold - -cp example/ontology.py ontology.py -cp example/queries.py queries.py -cp example/test_queries.py test_queries.py -cp example/rai-agent-config.example.yaml rai-agent-config.yaml -``` - -**3. Fill in config** - -Edit `rai-agent-config.yaml` — set your `database`, `schema`, `warehouse`, -and `source_table` (the fully-qualified EMPLOYEES table you just created). - -**4. Test locally** - -```bash -RAI_CONFIG_FILE_PATH=raiconfig.yaml python test_queries.py -``` - -Expected output: - -```text -QUERY 1: headcount_by_department - department headcount - Engineering 4 - Product 3 - Design 3 - -QUERY 2: direct_reports - manager_name manager_title department report_name report_title - Sarah Chen VP of Engineering Engineering Alice Smith Senior Engineer - Alice Smith Senior Engineer Engineering Bob Jones Engineer - Alice Smith Senior Engineer Engineering Rachel Kim Engineer - ... -``` - -**5. Deploy and test the agent** - -```bash -python si_agent.py deploy -python si_agent.py status -python si_agent.py chat "how many people are in each department?" -``` - -## Ontology at a glance - -The source table has one row per employee. The model derives two concepts: - -- **Employee** — identified by `EMPLOYEE_ID`. Has `name`, `department`, and `title`. -- **ReportsTo** — identified by `(MANAGER_ID, EMPLOYEE_ID)`. Represents a direct - reporting relationship. Employees with a null `MANAGER_ID` (department heads) - have no `ReportsTo` edge and are treated as root nodes. - -```text -EMPLOYEES table - EMPLOYEE_ID NAME DEPARTMENT TITLE MANAGER_ID - E001 Sarah Chen Engineering VP of Engineering (null) - E002 Alice Smith Engineering Senior Engineer E001 - E003 Bob Jones Engineering Engineer E002 - ... - │ - ▼ - Employee(id=E001, name="Sarah Chen", department="Engineering", ...) - Employee(id=E002, name="Alice Smith", ...) - ReportsTo(manager_id=E001, employee_id=E002) - ReportsTo(manager_id=E002, employee_id=E003) - ... -``` - -## Adapting to your own data - -This example uses a flat table where each employee row carries both the -employee's own attributes and a reference to their manager. To use your own -employee table: - -1. Ensure the table has at minimum: an employee ID column, a department column, - and a manager ID column (nullable for top-level employees). -2. Update the column references in `ontology.py` (`src.EMPLOYEE_ID`, `src.MANAGER_ID`, - etc.) to match your actual column names. -3. Update `source_table` in `rai-agent-config.yaml`. -4. Re-run `test_queries.py` to validate before deploying. diff --git a/rai-agent-scaffold/example/data/employees.csv b/rai-agent-scaffold/example/data/employees.csv deleted file mode 100644 index ff0d785b..00000000 --- a/rai-agent-scaffold/example/data/employees.csv +++ /dev/null @@ -1,13 +0,0 @@ -EMPLOYEE_ID,NAME,DEPARTMENT,TITLE,MANAGER_ID -E001,Sarah Chen,Engineering,VP of Engineering, -E002,Alice Smith,Engineering,Senior Engineer,E001 -E003,Bob Jones,Engineering,Engineer,E002 -E004,Dana Lee,Product,VP of Product, -E005,Carlos Rivera,Product,Product Manager,E004 -E006,Priya Patel,Product,Product Analyst,E005 -E007,James Wright,Design,Head of Design, -E008,Mia Nguyen,Design,UX Designer,E007 -E009,Tom Baker,Design,UI Designer,E007 -E010,Rachel Kim,Engineering,Engineer,E002 -E011,Omar Hassan,Product,Product Manager,E004 -E012,Lily Zhang,Engineering,Staff Engineer,E001 diff --git a/rai-agent-scaffold/example/ontology.py b/rai-agent-scaffold/example/ontology.py deleted file mode 100644 index 208c2957..00000000 --- a/rai-agent-scaffold/example/ontology.py +++ /dev/null @@ -1,89 +0,0 @@ -""" -Employee directory ontology definition. - -Defines the RAI model for an employee org-chart sourced from a single -Snowflake table where each row represents one employee with a reference -to their manager. - -Import `initialize` into any script that needs to build or query the model. -""" -import os as _os - -import relationalai.semantics as rai -from relationalai.semantics import String - - -def _read_source_table() -> str: - _config_path = _os.path.join(_os.path.dirname(_os.path.abspath(__file__)), "rai-agent-config.yaml") - try: - import yaml as _yaml - with open(_config_path) as _f: - return _yaml.safe_load(_f)["model"]["source_table"] - except (FileNotFoundError, KeyError, ImportError): - return "MY_DB.MY_SCHEMA.EMPLOYEES" # fallback — update to match your config - - -SOURCE_TABLE = _read_source_table() - - -def initialize(model: rai.Model): - """ - Employee org-chart model sourced from the EMPLOYEES table. - - Each row in the source table represents one employee. The model - derives two concepts: - - - Employee: one instance per unique EMPLOYEE_ID. Has a department - (e.g. Engineering, Product, Design) and a title (e.g. Senior Engineer). - - ReportsTo: one instance per (manager, direct-report) pair, derived - from the MANAGER_ID foreign key. Rows with a null MANAGER_ID (e.g. - department heads) have no ReportsTo edge and are treated as root nodes. - - Use this model to answer questions about team size, reporting structure, - and org hierarchy. - """ - src = model.Table(SOURCE_TABLE) - - # ------------------------------------------------------------------------- - # Concepts - # ------------------------------------------------------------------------- - Employee = model.Concept("Employee", identify_by={"id": String}) - - # One edge per (manager, report) pair — null MANAGER_ID rows are silently - # skipped by null propagation, so department heads have no ReportsTo entry. - ReportsTo = model.Concept( - "ReportsTo", - identify_by={"manager_id": String, "employee_id": String}, - ) - - # ------------------------------------------------------------------------- - # Properties - # ------------------------------------------------------------------------- - Employee.department = model.Property(f"{Employee} works in {String:department}") - Employee.title = model.Property(f"{Employee} has title {String:title}") - Employee.name = model.Property(f"{Employee} has name {String:name}") - - # ------------------------------------------------------------------------- - # Seed employees from source table - # ------------------------------------------------------------------------- - # Each row contributes the employee themselves … - model.define( - emp := Employee.new(id=src.EMPLOYEE_ID), - emp.department(src.DEPARTMENT), - emp.title(src.TITLE), - emp.name(src.NAME), - ) - # … and, when MANAGER_ID is non-null, their manager as well. - model.define( - Employee.new(id=src.MANAGER_ID), - ) - - # ------------------------------------------------------------------------- - # Seed reporting edges - # ------------------------------------------------------------------------- - # Null MANAGER_ID rows are dropped automatically — no sentinel needed. - model.define( - ReportsTo.new(manager_id=src.MANAGER_ID, employee_id=src.EMPLOYEE_ID) - ) - - return Employee, ReportsTo diff --git a/rai-agent-scaffold/example/queries.py b/rai-agent-scaffold/example/queries.py deleted file mode 100644 index 94bdc7b1..00000000 --- a/rai-agent-scaffold/example/queries.py +++ /dev/null @@ -1,84 +0,0 @@ -""" -Pre-defined queries and ToolRegistry for the employee directory Cortex agent. - -Each query function must: - - Return a rai.Fragment (a model.select(...) expression) - - Have a clear docstring — shown to the LLM to decide when to call the query - - Have a __name__ attribute — preserved by functools.wraps -""" -import functools - -import relationalai.semantics as rai -from ontology import initialize -from relationalai.agent.cortex import ( - QueryCatalog, - SourceCodeVerbalizer, - ToolRegistry, -) -from relationalai.semantics import Model - - -def headcount_by_department(model: Model, Employee, ReportsTo) -> rai.Fragment: - """ - Number of employees in each department. - Use this to answer questions like 'how many people are in each team', - 'what is the headcount breakdown', or 'which department is largest'. - Returns one row per department with an employee count. - """ - emp = Employee.ref() - g = rai.per(emp.department) - return model.select( - emp.department.alias("department"), - g.count(emp).alias("headcount"), - ) - - -def direct_reports(model: Model, Employee, ReportsTo) -> rai.Fragment: - """ - Every employee and their direct manager — including both names, titles, - and departments. - Use this to answer questions like 'who does Alice report to', 'show me - the reporting structure', or 'list all direct reports for a given manager'. - Returns one row per (manager, direct-report) pair. Employees with no - manager (e.g. department heads) are not included. - """ - edge = ReportsTo.ref() - report = Employee.ref() - manager = Employee.ref() - return model.select( - manager.name.alias("manager_name"), - manager.title.alias("manager_title"), - manager.department.alias("department"), - report.name.alias("report_name"), - report.title.alias("report_title"), - ).where( - report.id == edge.employee_id, - manager.id == edge.manager_id, - ) - - -def build_tool_registry(model: Model) -> ToolRegistry: - """Build the ToolRegistry for the Cortex agent sproc.""" - Employee, ReportsTo = initialize(model) - - def _bind(fn, *args): - @functools.wraps(fn) - def wrapper(): - return fn(*args) - return wrapper - - return ToolRegistry().add( - model=model, - description=( - "Employee directory and org chart for the company. " - "Contains all employees with their name, title, department, and " - "reporting relationships. Use this model to answer questions about " - "team size, headcount by department, reporting structure, and " - "who reports to whom." - ), - verbalizer=SourceCodeVerbalizer(model, initialize), - queries=QueryCatalog( - _bind(headcount_by_department, model, Employee, ReportsTo), - _bind(direct_reports, model, Employee, ReportsTo), - ), - ) diff --git a/rai-agent-scaffold/example/rai-agent-config.example.yaml b/rai-agent-scaffold/example/rai-agent-config.example.yaml deleted file mode 100644 index 22f400ea..00000000 --- a/rai-agent-scaffold/example/rai-agent-config.example.yaml +++ /dev/null @@ -1,12 +0,0 @@ -# Copy this file to the parent directory as rai-agent-config.yaml and fill in your values. -# rai-agent-config.yaml is gitignored — this file is the checked-in template. - -agent: - name: EMPLOYEE_DIRECTORY_AGENT # Name shown in Snowflake Cortex Agents UI - database: MY_DATABASE # Snowflake database to deploy into - schema: MY_SCHEMA # Schema to deploy into (must already exist) - warehouse: MY_WAREHOUSE # Warehouse for sproc execution - model_name: EMPLOYEE_DIRECTORY # RAI Model name used internally in each sproc - -model: - source_table: MY_DB.MY_SCHEMA.EMPLOYEES # Fully-qualified EMPLOYEES table diff --git a/rai-agent-scaffold/example/test_queries.py b/rai-agent-scaffold/example/test_queries.py deleted file mode 100644 index 371b7f00..00000000 --- a/rai-agent-scaffold/example/test_queries.py +++ /dev/null @@ -1,54 +0,0 @@ -""" -Quick smoke test: run both agent queries locally against the EMPLOYEES table. - -Copy this file to the parent directory (alongside si_agent.py) and run: - RAI_CONFIG_FILE_PATH=raiconfig.yaml python test_queries.py -""" -import relationalai.semantics as rai -from ontology import initialize -from relationalai.config import SnowflakeConnection, create_config - -print("Connecting to Snowflake...") -session = create_config().get_session(SnowflakeConnection) -print(f"Connected: {session.get_current_account()} / {session.get_current_role()}\n") - -model = rai.Model("EMPLOYEE_DIRECTORY_TEST") -Employee, ReportsTo = initialize(model) - -# ---- Query 1: headcount by department -------------------------------------- -print("=" * 60) -print("QUERY 1: headcount_by_department") -print("=" * 60) -emp = Employee.ref() -g = rai.per(emp.department) -# Note: local .to_df() may return one row per (emp, department) because `emp` -# remains a free variable. .drop_duplicates() gives the correct per-department -# summary. The deployed sproc returns correctly aggregated results. -df1 = model.select( - emp.department.alias("department"), - g.count(emp).alias("headcount"), -).to_df().drop_duplicates() -print(df1.to_string(index=False)) -print() - -# ---- Query 2: direct reports ----------------------------------------------- -print("=" * 60) -print("QUERY 2: direct_reports") -print("=" * 60) -edge = ReportsTo.ref() -report = Employee.ref() -manager = Employee.ref() - -df2 = model.select( - manager.name.alias("manager_name"), - manager.title.alias("manager_title"), - manager.department.alias("department"), - report.name.alias("report_name"), - report.title.alias("report_title"), -).where( - report.id == edge.employee_id, - manager.id == edge.manager_id, -).to_df() -print(df2.to_string(index=False)) -print() -print("Done.") diff --git a/rai-agent-scaffold/ontology.example.py b/rai-agent-scaffold/ontology.example.py deleted file mode 100644 index 4f551d38..00000000 --- a/rai-agent-scaffold/ontology.example.py +++ /dev/null @@ -1,105 +0,0 @@ -""" - ontology definition. - -Defines the RAI model for data. -Copy this file to ontology.py and customize it for your dataset. - -Import `initialize` into any script that needs to build or query the model. -""" -import os as _os - -import relationalai.semantics as rai -from relationalai.semantics import String - - -def _read_source_table() -> str: - """Read source_table from rai-agent-config.yaml; fall back to inline constant. - - The YAML is present when running locally or in test_queries.py. - It is not packaged into the Snowflake sproc, so the fallback fires there — - which is fine because the value was correct when the sproc was last deployed. - """ - _config_path = _os.path.join(_os.path.dirname(_os.path.abspath(__file__)), "rai-agent-config.yaml") - try: - import yaml as _yaml - with open(_config_path) as _f: - return _yaml.safe_load(_f)["model"]["source_table"] - except (FileNotFoundError, KeyError, ImportError): - return "MY_DB.MY_SCHEMA.MY_TABLE" # fallback — update to match your config - - -SOURCE_TABLE = _read_source_table() - - -def initialize(model: rai.Model): - """ - - - This docstring is exposed to the agent via SourceCodeVerbalizer — write it - as a concise summary of what the model represents, what concepts exist, and - any important design decisions a user asking questions should know about. - - Example: - Nodes are assembly parts connected in a parent/child BOM hierarchy sourced - from MY_DB.MY_SCHEMA.MY_TABLE. Each node has a category (TYPE_A, TYPE_B, - etc.) and an optional label (e.g. FLAGGED, REVIEWED). - """ - src = model.Table(SOURCE_TABLE) - - # ------------------------------------------------------------------------- - # Concepts - # ------------------------------------------------------------------------- - # Primary entity: identified by one or more string keys from the source table. - # Use identify_by to deduplicate rows so each unique (key1, key2) becomes one - # concept instance. - Node = model.Concept("Node", identify_by={"id": String}) - - # Edge table: one row = one parent→child link. - # Only needed if your data has a hierarchy — remove otherwise. - Edge = model.Concept( - "Edge", - identify_by={"parent_id": String, "child_id": String}, - ) - - # ------------------------------------------------------------------------- - # Properties - # ------------------------------------------------------------------------- - # Use model.Property for 1:1 (functional) attributes — required for - # rai.per() groupby in queries. Each node must have at most one value. - Node.category = model.Property(f"{Node} has category {String:category}") - - # Optional: label property for classified/flagged records. - Node.label = model.Property(f"{Node} has label {String:label}") - - # ------------------------------------------------------------------------- - # Seed nodes from source table - # ------------------------------------------------------------------------- - # Rows where the id column is null are skipped by null propagation. - # Do NOT coalesce null ids to a sentinel — that causes FD violations on - # Properties when multiple null rows get merged into the same node. - model.define( - p := Node.new(id=src.parent_id), - p.category(src.parent_category), - ) - model.define( - c := Node.new(id=src.child_id), - c.category(src.child_category), - ) - - # ------------------------------------------------------------------------- - # Seed edge table - # ------------------------------------------------------------------------- - model.define( - Edge.new(parent_id=src.parent_id, child_id=src.child_id) - ) - - # ------------------------------------------------------------------------- - # Seed known labels (optional) - # ------------------------------------------------------------------------- - # Tag specific records with a classification label. - # Add one .where() block per labelled record. - # - # node = Node.ref() - # model.define(node.label("MY_LABEL")).where(node.id == "some-identifier") - - return Node, Edge diff --git a/rai-agent-scaffold/pyproject.toml b/rai-agent-scaffold/pyproject.toml deleted file mode 100644 index 51e9222d..00000000 --- a/rai-agent-scaffold/pyproject.toml +++ /dev/null @@ -1,19 +0,0 @@ -[build-system] -requires = ["setuptools>=64", "wheel"] -build-backend = "setuptools.build_meta" - -[project] -name = "rai-template-rai-agent-scaffold" -version = "0.0.0" -description = "RelationalAI template: rai-agent-scaffold (PyRel v1)" -readme = "README.md" -requires-python = ">=3.10" -dependencies = [ - "relationalai==1.0.14", - "httpx", - "pyyaml", - "snowflake-snowpark-python", -] - -[tool.setuptools] -packages = [] diff --git a/rai-agent-scaffold/queries.example.py b/rai-agent-scaffold/queries.example.py deleted file mode 100644 index e25722b9..00000000 --- a/rai-agent-scaffold/queries.example.py +++ /dev/null @@ -1,85 +0,0 @@ -""" -Pre-defined queries and ToolRegistry for the Cortex agent. - -Copy this file to queries.py and customize the query functions for your dataset. - -Each query function must: - - Return a rai.Fragment (a model.select(...) expression) - - Have a clear docstring — shown to the LLM to decide when to call the query - - Have a __name__ attribute — used as the query identifier (preserved by functools.wraps) -""" -import functools - -import relationalai.semantics as rai -from ontology import initialize -from relationalai.agent.cortex import ( - QueryCatalog, - SourceCodeVerbalizer, - ToolRegistry, -) -from relationalai.semantics import Model - - -def count_by_category(model: Model, Node, Edge) -> rai.Fragment: - """ - Count of records grouped by category. - Use this to answer questions like 'how many records of each type exist' - or 'what is the breakdown by category'. - Returns one row per category with the count of distinct records. - """ - node = Node.ref() - g = rai.per(node.category) - return model.select( - node.category.alias("category"), - g.count(node).alias("count"), - ) - - -def label_trace(model: Model, Node, Edge) -> rai.Fragment: - """ - Traceability: every record tagged with a label and its immediate parent - in the hierarchy — including the parent's category and identifier. - Use this to answer questions like 'show me all flagged records and their - parents' or 'which records are affected by a given label'. - """ - n = Node.ref() # the labelled child node - edge = Edge.ref() # the edge connecting child to parent - parent = Node.ref() # the immediate parent node - return model.select( - n.label.alias("label"), - n.category.alias("child_category"), - n.id.alias("child_id"), - parent.category.alias("parent_category"), - parent.id.alias("parent_id"), - ).where( - n.label, - n.id == edge.child_id, - parent.id == edge.parent_id, - ) - - -def build_tool_registry(model: Model) -> ToolRegistry: - """Build the ToolRegistry for the Cortex agent sproc.""" - Node, Edge = initialize(model) - - # Bind model/Node/Edge into each query so QueryCatalog gets zero-arg callables - # while __name__ and __doc__ (used by the agent) are preserved via functools.wraps. - def _bind(fn, *args): - @functools.wraps(fn) - def wrapper(): - return fn(*args) - return wrapper - - return ToolRegistry().add( - model=model, - description=( - "Replace this with a description of your domain model. " - "The agent uses this text to decide when to query this model — " - "describe what data it contains and what kinds of questions it can answer." - ), - verbalizer=SourceCodeVerbalizer(model, initialize), - queries=QueryCatalog( - _bind(count_by_category, model, Node, Edge), - _bind(label_trace, model, Node, Edge), - ), - ) diff --git a/rai-agent-scaffold/rai-agent-config.example.yaml b/rai-agent-scaffold/rai-agent-config.example.yaml deleted file mode 100644 index aa56860d..00000000 --- a/rai-agent-scaffold/rai-agent-config.example.yaml +++ /dev/null @@ -1,12 +0,0 @@ -# Copy this file to rai-agent-config.yaml and fill in your values. -# rai-agent-config.yaml is gitignored — this file is the public template. - -agent: - name: MY_AGENT_NAME # Name shown in Snowflake Cortex Agents UI - database: MY_DATABASE # Snowflake database to deploy into - schema: MY_SCHEMA # Schema to deploy into (must already exist) - warehouse: MY_WAREHOUSE # Warehouse for sproc execution - model_name: MY_MODEL_NAME # RAI Model name used internally in each sproc - -model: - source_table: MY_DB.MY_SCHEMA.MY_TABLE # Fully-qualified source table diff --git a/rai-agent-scaffold/si_agent.py b/rai-agent-scaffold/si_agent.py deleted file mode 100644 index 7a542633..00000000 --- a/rai-agent-scaffold/si_agent.py +++ /dev/null @@ -1,145 +0,0 @@ -""" -Deployment script for a RelationalAI Cortex agent. - -Usage: - python si_agent.py deploy - python si_agent.py update - python si_agent.py status - python si_agent.py chat "" - python si_agent.py teardown -""" -import argparse -import os - -import yaml -from relationalai.agent.cortex import ( - CortexAgentManager, - DeploymentConfig, - ToolRegistry, -) -from relationalai.config import SnowflakeConnection, create_config -from relationalai.semantics import Model -from snowflake import snowpark - -_AGENT_DIR = os.path.dirname(os.path.abspath(__file__)) -_CONFIG_PATH = os.path.join(_AGENT_DIR, "rai-agent-config.yaml") - -# --------------------------------------------------------------------------- -# Configuration — loaded from rai-agent-config.yaml -# --------------------------------------------------------------------------- -def _load_config() -> dict: - with open(_CONFIG_PATH) as f: - return yaml.safe_load(f) - -_cfg = _load_config() - -AGENT_NAME = _cfg["agent"]["name"] -DATABASE = _cfg["agent"]["database"] -SCHEMA = _cfg["agent"]["schema"] -WAREHOUSE = _cfg["agent"]["warehouse"] -MODEL_NAME = _cfg["agent"]["model_name"] - -# Packages used by relationalai.agent.cortex not auto-installed as transitive deps. -_EXTRA_PACKAGES = ["httpx"] - - -def _build_manager() -> CortexAgentManager: - session: snowpark.Session = create_config().get_session(SnowflakeConnection) - return CortexAgentManager( - session=session, - config=DeploymentConfig( - agent_name=AGENT_NAME, - database=DATABASE, - schema=SCHEMA, - warehouse=WAREHOUSE, - model_name=MODEL_NAME, - allow_preview=True, - ), - ) - - -# --------------------------------------------------------------------------- -# init_tools — executed inside each stored procedure with a fresh Model. -# Must be self-contained: no sessions, DataFrames, or other runtime state. -# --------------------------------------------------------------------------- -def init_tools(model: Model) -> ToolRegistry: - # Workaround for v1.0.x: redirect schema cache to /tmp (UDF sandbox restriction) - from pathlib import Path - - import relationalai.util.schema as _schema_mod - _schema_mod.CACHE_PATH = Path("/tmp/rai_cache/schemas.json") - - from queries import build_tool_registry - return build_tool_registry(model) - - -# --------------------------------------------------------------------------- -# CLI commands -# --------------------------------------------------------------------------- -def _imports(): - return [ - os.path.join(_AGENT_DIR, "ontology.py"), - os.path.join(_AGENT_DIR, "queries.py"), - ] - - -def cmd_deploy(manager: CortexAgentManager) -> None: - print(f"Deploying '{AGENT_NAME}' to {DATABASE}.{SCHEMA} ...") - manager.deploy(init_tools=init_tools, imports=_imports(), extra_packages=_EXTRA_PACKAGES) - print(manager.status()) - - -def cmd_update(manager: CortexAgentManager) -> None: - print(f"Updating stored procedures for '{AGENT_NAME}' ...") - manager.update(init_tools=init_tools, imports=_imports(), extra_packages=_EXTRA_PACKAGES) - print(manager.status()) - - -def cmd_status(manager: CortexAgentManager) -> None: - print(manager.status()) - - -def cmd_chat(manager: CortexAgentManager, message: str) -> None: - response = manager.chat().send(message) - print(response.full_text()) - - -def cmd_teardown(manager: CortexAgentManager) -> None: - print(f"Tearing down '{AGENT_NAME}' from {DATABASE}.{SCHEMA} ...") - print("WARNING: permanently deletes all SI conversation history for this agent.") - manager.cleanup() - print(manager.status()) - - -# --------------------------------------------------------------------------- -# Argument parser -# --------------------------------------------------------------------------- -def main() -> None: - parser = argparse.ArgumentParser( - description="Manage the Cortex agent lifecycle.") - sub = parser.add_subparsers(dest="command") - sub.required = True - - sub.add_parser("deploy", help="Create schema, stage, sprocs, and agent") - sub.add_parser("update", help="Update sprocs without re-registering the agent") - sub.add_parser("status", help="Print deployment status") - sub.add_parser("teardown", help="Remove all agent resources") - - chat_p = sub.add_parser("chat", help="Send a message to the deployed agent") - chat_p.add_argument("message", help="Message to send") - - args = parser.parse_args() - manager = _build_manager() - - commands = { - "deploy": lambda: cmd_deploy(manager), - "update": lambda: cmd_update(manager), - "status": lambda: cmd_status(manager), - "chat": lambda: cmd_chat(manager, args.message), - "teardown": lambda: cmd_teardown(manager), - } - commands[args.command]() - - -if __name__ == "__main__": - main() diff --git a/rai-agent-scaffold/test_queries.example.py b/rai-agent-scaffold/test_queries.example.py deleted file mode 100644 index 5d5ace32..00000000 --- a/rai-agent-scaffold/test_queries.example.py +++ /dev/null @@ -1,57 +0,0 @@ -""" -Quick smoke test: run both agent queries locally against the source table. - -Copy this file to test_queries.py, update it to match your ontology.py and -queries.py, then run: - RAI_CONFIG_FILE_PATH=raiconfig.yaml python test_queries.py -""" -import relationalai.semantics as rai -from ontology import initialize -from relationalai.config import SnowflakeConnection, create_config - -print("Connecting to Snowflake...") -session = create_config().get_session(SnowflakeConnection) -print(f"Connected: {session.get_current_account()} / {session.get_current_role()}\n") - -model = rai.Model("MY_MODEL_TEST") -Node, Edge = initialize(model) - -# ---- Query 1: count by category -------------------------------------------- -print("=" * 60) -print("QUERY 1: count_by_category") -print("=" * 60) -node = Node.ref() -cat = node.category -g = rai.per(cat) -# Note: local .to_df() may return one row per (node, category) because `node` -# remains a free variable. .drop_duplicates() gives the correct per-category -# summary. The deployed sproc returns correctly aggregated results. -df1 = model.select( - cat.alias("category"), - g.count(node).alias("count"), -).to_df().drop_duplicates() -print(df1.to_string(index=False)) -print() - -# ---- Query 2: label trace -------------------------------------------------- -print("=" * 60) -print("QUERY 2: label_trace") -print("=" * 60) -n = Node.ref() -edge = Edge.ref() -parent = Node.ref() - -df2 = model.select( - n.label.alias("label"), - n.category.alias("child_category"), - n.id.alias("child_id"), - parent.category.alias("parent_category"), - parent.id.alias("parent_id"), -).where( - n.label, - n.id == edge.child_id, - parent.id == edge.parent_id, -).to_df() -print(df2.to_string(index=False)) -print() -print("Done.") diff --git a/retail_markdown/pyproject.toml b/retail_markdown/pyproject.toml index 15ba8665..80604640 100644 --- a/retail_markdown/pyproject.toml +++ b/retail_markdown/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: retail_markdown (PyRel v1)" readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai==1.0.14", + "relationalai==2.1.1", "pandas", ] diff --git a/retail_planning/README.md b/retail_planning/README.md index 9198d5e5..d522653e 100644 --- a/retail_planning/README.md +++ b/retail_planning/README.md @@ -76,7 +76,7 @@ you'll additionally need: ### Tools - Python >= 3.10 -- RelationalAI Python SDK (`relationalai[gnn] == 1.27.1`) +- RelationalAI Python SDK (`relationalai[gnn] == 2.1.1`) ## Quickstart diff --git a/retail_planning/pyproject.toml b/retail_planning/pyproject.toml index 8ab95756..32e46e55 100644 --- a/retail_planning/pyproject.toml +++ b/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.27.1", + "relationalai[gnn]==2.1.1", "pandas>=2.0", ] diff --git a/retail_planning/retail_planning.py b/retail_planning/retail_planning.py index 571f979a..5940eaec 100644 --- a/retail_planning/retail_planning.py +++ b/retail_planning/retail_planning.py @@ -566,12 +566,14 @@ def _report(gnn, label): # Objective: maximize revenue from sales + salvage value of remaining inventory revenue = sum( - OptArticle.initial_price * (1 - Discount_ref.discount_pct / 100) * sales_ref + OptArticle, Week_ref, Discount_ref, + OptArticle.initial_price * (1 - Discount_ref.discount_pct / 100) * sales_ref, ).where(OptArticle.x_sales(Week_ref, Discount_ref, sales_ref)) salvage = sum( + OptArticle, Week_ref, OptArticle.initial_price * OptArticle.salvage_rate - * (OptArticle.initial_inventory - cumulative_ref) + * (OptArticle.initial_inventory - cumulative_ref), ).where( OptArticle.x_cuml_sales(Week_ref, cumulative_ref), Week_ref.num == num_weeks, @@ -726,18 +728,21 @@ def _report(gnn, label): # Objective: minimize production cost + holding cost + unmet demand penalty prod_cost_total = sum( - ProdCapacity.production_cost * production_ref + ProdCapacity, dp_week_ref, + ProdCapacity.production_cost * production_ref, ).where(ProdCapacity.x_production(dp_week_ref, production_ref)) hold_cost_total = sum( - ProdCapacity.holding_cost_per_week * inventory_ref + ProdCapacity, inv_week_ref, + ProdCapacity.holding_cost_per_week * inventory_ref, ).where( ProdCapacity.x_inventory(inv_week_ref, inventory_ref), inv_week_ref >= 1, ) unmet_cost_total = sum( - UNMET_PENALTY * unmet_ref + ProdCapacity, dp_week_ref, + UNMET_PENALTY * unmet_ref, ).where(ProdCapacity.x_unmet(dp_week_ref, unmet_ref)) dp.minimize(prod_cost_total + hold_cost_total + unmet_cost_total) diff --git a/retail_planning/retail_planning_local.py b/retail_planning/retail_planning_local.py index 7b1711fb..2f570cff 100644 --- a/retail_planning/retail_planning_local.py +++ b/retail_planning/retail_planning_local.py @@ -300,12 +300,14 @@ )) revenue = sum( - OptArticle.initial_price * (1 - Discount_ref.discount_pct / 100) * sales_ref + OptArticle, Week_ref, Discount_ref, + OptArticle.initial_price * (1 - Discount_ref.discount_pct / 100) * sales_ref, ).where(OptArticle.x_sales(Week_ref, Discount_ref, sales_ref)) salvage = sum( + OptArticle, Week_ref, OptArticle.initial_price * OptArticle.salvage_rate - * (OptArticle.initial_inventory - cumulative_ref) + * (OptArticle.initial_inventory - cumulative_ref), ).where( OptArticle.x_cuml_sales(Week_ref, cumulative_ref), Week_ref.num == num_weeks, @@ -425,18 +427,21 @@ )) prod_cost_total = sum( - ProdCapacity.production_cost * production_ref + ProdCapacity, dp_week_ref, + ProdCapacity.production_cost * production_ref, ).where(ProdCapacity.x_production(dp_week_ref, production_ref)) hold_cost_total = sum( - ProdCapacity.holding_cost_per_week * inventory_ref + ProdCapacity, inv_week_ref, + ProdCapacity.holding_cost_per_week * inventory_ref, ).where( ProdCapacity.x_inventory(inv_week_ref, inventory_ref), inv_week_ref >= 1, ) unmet_cost_total = sum( - UNMET_PENALTY * unmet_ref + ProdCapacity, dp_week_ref, + UNMET_PENALTY * unmet_ref, ).where(ProdCapacity.x_unmet(dp_week_ref, unmet_ref)) dp.minimize(prod_cost_total + hold_cost_total + unmet_cost_total) diff --git a/sample-template/model/schema.py b/sample-template/model/schema.py index f15316cc..8b1298c3 100644 --- a/sample-template/model/schema.py +++ b/sample-template/model/schema.py @@ -2,7 +2,7 @@ from relationalai.semantics import Integer, Model, String -model = Model("Template", use_lqp=False) +model = Model("Template") Item = model.Concept("Item", identify_by={"id": Integer}) Item.name = model.Property(f"{Item} has {String:name}") diff --git a/sample-template/pyproject.toml b/sample-template/pyproject.toml index 19bea2ab..330cfa59 100644 --- a/sample-template/pyproject.toml +++ b/sample-template/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: template" readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai==0.13.3", + "relationalai==2.1.1", ] [tool.setuptools] diff --git a/shift_assignment/README.md b/shift_assignment/README.md index 1497d4bf..87bd7810 100644 --- a/shift_assignment/README.md +++ b/shift_assignment/README.md @@ -51,7 +51,7 @@ The template also demonstrates scenario analysis by sweeping over different mini ### Tools - Python >= 3.10 -- RelationalAI Python SDK (`relationalai == 1.0.14`) +- RelationalAI Python SDK (`relationalai == 2.1.1`) ## Quickstart diff --git a/shift_assignment/pyproject.toml b/shift_assignment/pyproject.toml index 605c5c41..5d341a8f 100644 --- a/shift_assignment/pyproject.toml +++ b/shift_assignment/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: shift_assignment (PyRel v1)" readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai==1.0.14", + "relationalai==2.1.1", "pandas", ] diff --git a/shipment_compliance/README.md b/shipment_compliance/README.md index 6698fe66..c467054a 100644 --- a/shipment_compliance/README.md +++ b/shipment_compliance/README.md @@ -60,7 +60,7 @@ The four rules demonstrate different rule patterns: ### Tools - Python >= 3.10 -- RelationalAI Python SDK (`relationalai == 1.13.0`) +- RelationalAI Python SDK (`relationalai == 2.1.1`) ## Quickstart diff --git a/shipment_compliance/pyproject.toml b/shipment_compliance/pyproject.toml index 1be96347..e4a0aa5e 100644 --- a/shipment_compliance/pyproject.toml +++ b/shipment_compliance/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: shipment_compliance (PyRel v1)" readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai==1.13.0", + "relationalai==2.1.1", "pandas", ] diff --git a/simple-start/README.md b/simple-start/README.md index 898d0848..43a197fa 100644 --- a/simple-start/README.md +++ b/simple-start/README.md @@ -115,7 +115,7 @@ At a high level, the notebook: 1. Creates and populates the `CONNECTIONS` table in Snowflake. 2. Defines `Station` and `Connection` concepts and loads them from the Snowflake source table. -3. Builds an undirected graph from the station connectivity relation. +3. Builds an undirected graph with `Station` as the node concept and the station connectivity relation as its edges. 4. Lists the resulting edges as a table. 5. Computes betweenness centrality and queries the scores into a pandas DataFrame. diff --git a/simple-start/pyproject.toml b/simple-start/pyproject.toml index ce97080a..7741aeb8 100644 --- a/simple-start/pyproject.toml +++ b/simple-start/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: simple_start (PyRel v1)" readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai==1.0.14", + "relationalai==2.1.1", "jupyter" ] diff --git a/simple-start/simple-start.ipynb b/simple-start/simple-start.ipynb index b6249289..f98e897b 100644 --- a/simple-start/simple-start.ipynb +++ b/simple-start/simple-start.ipynb @@ -70,15 +70,6 @@ "session = cfg.get_session()" ] }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "The edge table shows which stations connect to which, but it doesn’t give an at-a-glance way to compare stations.\n", - "\n", - "**Betweenness centrality** is a common graph metric that assigns each station a score based on its position in the network. It’s available as a method on the `Graph` object:" - ] - }, { "cell_type": "markdown", "metadata": {}, @@ -99,7 +90,7 @@ " create or replace table RAI_DEMO.SIMPLE_START.CONNECTIONS (\n", " station_1 int,\n", " station_2 int\n", - " );\n", + " ) change_tracking = true;\n", "\n", " insert into RAI_DEMO.SIMPLE_START.CONNECTIONS (station_1, station_2) values\n", " (1, 2),\n", @@ -183,8 +174,8 @@ "# Define connection entities from rows in the source table.\n", "model.define(\n", " Connection.new(\n", - " src=Station.filter_by(id=connections.station_1),\n", - " dst=Station.ref().filter_by(id=connections.station_2),\n", + " src=Station.lookup(id=connections.station_1),\n", + " dst=Station.lookup(id=connections.station_2),\n", " )\n", ")" ] @@ -270,7 +261,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "The power stations and connections between them form a graph. We can model a graph in RelationalAI by wrapping the model in a `Graph` object and associating data with its `Node` and `Edge` properties." + "The power stations and connections between them form a graph. We can model a graph in RelationalAI by wrapping the model in a `Graph` object. Passing `node_concept=Station` makes `Station` the graph's `Node` concept, and we then define the graph's edges through its `Edge` concept." ] }, { @@ -279,7 +270,7 @@ "metadata": {}, "outputs": [], "source": [ - "graph = Graph(model, directed=False, weighted=False)\n", + "graph = Graph(model, directed=False, weighted=False, node_concept=Station)\n", "model.define(graph.Edge.new(src=Station, dst=Station.connections))" ] }, diff --git a/smoker_status_prediction/README.md b/smoker_status_prediction/README.md index ed6c803f..4dc72428 100644 --- a/smoker_status_prediction/README.md +++ b/smoker_status_prediction/README.md @@ -54,7 +54,7 @@ Assumes familiarity with Python and basic ML concepts (binary classification, tr ### Tools - Python >= 3.10 -- RelationalAI Python SDK (`relationalai[gnn] == 1.27.1`) +- RelationalAI Python SDK (`relationalai[gnn] == 2.1.1`) ## Quickstart diff --git a/smoker_status_prediction/pyproject.toml b/smoker_status_prediction/pyproject.toml index 78c24bc9..dac6a16a 100644 --- a/smoker_status_prediction/pyproject.toml +++ b/smoker_status_prediction/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: smoker_status_prediction (PyRel v1)" readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai[gnn]==1.27.1", + "relationalai[gnn]==2.1.1", "pandas>=2.0", ] diff --git a/sprint_scheduling/README.md b/sprint_scheduling/README.md index 8198a001..7aaa2554 100644 --- a/sprint_scheduling/README.md +++ b/sprint_scheduling/README.md @@ -53,7 +53,7 @@ Built using **prescriptive reasoning** (mixed-integer programming solved with Hi ### Tools - Python >= 3.10 -- RelationalAI Python SDK (`relationalai`) >= 1.0.14 +- RelationalAI Python SDK (`relationalai`) == 2.1.1 ## Quickstart diff --git a/sprint_scheduling/pyproject.toml b/sprint_scheduling/pyproject.toml index 024fba7b..c2d19b42 100644 --- a/sprint_scheduling/pyproject.toml +++ b/sprint_scheduling/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: sprint_scheduling (PyRel v1)" readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai==1.0.14", + "relationalai==2.1.1", "pandas", ] diff --git a/subscriber_retention/README.md b/subscriber_retention/README.md index d1f43a57..fed71e8d 100644 --- a/subscriber_retention/README.md +++ b/subscriber_retention/README.md @@ -72,7 +72,7 @@ GRANT CREATE MODEL ON SCHEMA TELCO_ENRICHMENT.EXPERIMENTS TO APPLICATION RELATIO ### Tools - Python >= 3.10 -- RelationalAI Python SDK (`relationalai[gnn] == 1.27.1`) +- RelationalAI Python SDK (`relationalai[gnn] == 2.1.1`) ## Quickstart diff --git a/subscriber_retention/pyproject.toml b/subscriber_retention/pyproject.toml index e63ddc8b..2faea94a 100644 --- a/subscriber_retention/pyproject.toml +++ b/subscriber_retention/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: subscriber_retention (PyRel v1)" readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai[gnn]==1.27.1", + "relationalai[gnn]==2.1.1", "pandas", "numpy", ] diff --git a/supplier_reliability/README.md b/supplier_reliability/README.md index 796e4ad4..b8f75ad8 100644 --- a/supplier_reliability/README.md +++ b/supplier_reliability/README.md @@ -51,7 +51,7 @@ This template answers all of those in one place: it finds the cost-minimizing so ### Tools - Python >= 3.10 -- RelationalAI Python SDK (`relationalai`) == 1.11.0 +- RelationalAI Python SDK (`relationalai`) == 2.1.1 ## Quickstart diff --git a/supplier_reliability/pyproject.toml b/supplier_reliability/pyproject.toml index ccedd7e0..54576c70 100644 --- a/supplier_reliability/pyproject.toml +++ b/supplier_reliability/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: supplier_reliability (PyRel v1)" readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai==1.11.0", + "relationalai==2.1.1", "pandas", ] diff --git a/supply_chain_resilience/README.md b/supply_chain_resilience/README.md index a0cd7e22..dcb69f6c 100644 --- a/supply_chain_resilience/README.md +++ b/supply_chain_resilience/README.md @@ -59,7 +59,7 @@ Supply chain networks route goods from suppliers through factories and distribut ### Tools - Python >= 3.10 -- RelationalAI Python SDK (`relationalai`) == 1.11.0 +- RelationalAI Python SDK (`relationalai`) == 2.1.1 ## Quickstart diff --git a/supply_chain_resilience/pyproject.toml b/supply_chain_resilience/pyproject.toml index 8bb703c8..b57065c5 100644 --- a/supply_chain_resilience/pyproject.toml +++ b/supply_chain_resilience/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: supply_chain_resilience (PyRel v1)" readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai==1.11.0", + "relationalai==2.1.1", "pandas>=2.0", ] diff --git a/supply_chain_resilience/supply_chain_resilience.py b/supply_chain_resilience/supply_chain_resilience.py index 864c827a..77147521 100644 --- a/supply_chain_resilience/supply_chain_resilience.py +++ b/supply_chain_resilience/supply_chain_resilience.py @@ -640,8 +640,11 @@ def solve_flow(label, exclude_site_id=None, block_business_ids=None, use_avoid_r unmet_cost = UNMET_PENALTY * sum(Demand.x_unmet) + # The risk sum is empty with no watch-level supplier, and the centrality sum + # with no operation into a scored site (stores and offices are unscored); + # `| 0.0` makes an empty sum zero. problem.minimize( - sum(model.union(transport_cost, risk_cost, centrality_cost, unmet_cost)) + transport_cost + (risk_cost | 0.0) + (centrality_cost | 0.0) + unmet_cost ) problem.solve("highs", time_limit_sec=120) diff --git a/supply_chain_transport/README.md b/supply_chain_transport/README.md index d18b1be7..35afc880 100644 --- a/supply_chain_transport/README.md +++ b/supply_chain_transport/README.md @@ -51,7 +51,7 @@ The model demonstrates several advanced techniques: multi-period inventory flow ### Tools - Python >= 3.10 -- RelationalAI Python SDK (`relationalai` == 1.0.14) +- RelationalAI Python SDK (`relationalai` == 2.1.1) ## Quickstart diff --git a/supply_chain_transport/pyproject.toml b/supply_chain_transport/pyproject.toml index 704960d2..1af0d2fa 100644 --- a/supply_chain_transport/pyproject.toml +++ b/supply_chain_transport/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: supply_chain_transport (PyRel v1)" readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai==1.0.14", + "relationalai==2.1.1", "pandas", ] diff --git a/supply_chain_transport/supply_chain_transport.py b/supply_chain_transport/supply_chain_transport.py index 9deb0bb2..f70fabbb 100644 --- a/supply_chain_transport/supply_chain_transport.py +++ b/supply_chain_transport/supply_chain_transport.py @@ -166,7 +166,7 @@ FreightGroup.x_inv(time_period_ref + 1, x_inv_next), TransportType.x_qty_tra(FreightGroup, time_period_ref, x_qty_tra), ).require( - x_inv_current == x_inv_next + sum(x_qty_tra).per(FreightGroup, time_period_ref) + x_inv_current == x_inv_next + sum(TransportType, x_qty_tra).per(FreightGroup, time_period_ref) )) # Constraint: initial inventory equals starting position; final inventory is zero @@ -192,7 +192,7 @@ # Constraint: weight[type,t] = sum of quantities shipped by that type on day t problem.satisfy(model.require( - x_weight == sum(x_qty_tra).per(TransportType, time_period_ref) + x_weight == sum(FreightGroup, x_qty_tra).per(TransportType, time_period_ref) ).where( TransportType.x_weight(time_period_ref, x_weight), TransportType.x_qty_tra(FreightGroup, time_period_ref, x_qty_tra), @@ -209,7 +209,7 @@ # Constraint: piecewise LTL cost — exactly one segment active, remainder within limit problem.satisfy(model.require( - sum(y_bin_ltl).per(time_period_ref) == 1, + sum(LTLSegment, y_bin_ltl).per(time_period_ref) == 1, x_rem_ltl <= LTLSegment.limit * y_bin_ltl, ).where( LTLSegment.x_rem_ltl(time_period_ref, x_rem_ltl), @@ -220,34 +220,32 @@ LTLSegment_outer = LTLSegment.ref() LTLSegment_inner = LTLSegment.ref() problem.satisfy(model.where( - LTLSegment_outer := LTLSegment.ref(), - LTLSegment_inner := LTLSegment.ref(), TransportType.name("ltl"), TransportType.x_weight(time_period_ref, x_weight), ).require( x_weight == - sum(x_rem_ltl).where(LTLSegment.x_rem_ltl(time_period_ref, x_rem_ltl)).per(time_period_ref) + - sum(LTLSegment_outer.limit * y_bin_ltl).where( + sum(LTLSegment, x_rem_ltl).where(LTLSegment.x_rem_ltl(time_period_ref, x_rem_ltl)).per(time_period_ref) + + sum(LTLSegment_inner, LTLSegment_outer.limit * y_bin_ltl).where( LTLSegment_inner.y_bin_ltl(time_period_ref, y_bin_ltl), LTLSegment_outer.seg == LTLSegment_inner.seg - 1, ).per(time_period_ref) )) # Objective: minimize total cost (inventory holding + TL fixed + LTL variable) -total_inv_cost = inv_cost * sum(x_inv).where( +total_inv_cost = inv_cost * sum(FreightGroup, time_period_ref, x_inv).where( FreightGroup.x_inv(time_period_ref, x_inv), time_period_ref > FreightGroup.inv_start_t ) -total_tl_cost = tl_tra_cost * sum(y_bin_tl).where(bin_tl(Integer.ref(), y_bin_tl)) -total_ltl_rem_cost = LTLSegment.cost * sum(x_rem_ltl).per(LTLSegment).where( - LTLSegment.x_rem_ltl(Integer.ref(), x_rem_ltl) +total_tl_cost = tl_tra_cost * sum(time_period_ref, y_bin_tl).where(bin_tl(time_period_ref, y_bin_tl)) +total_ltl_rem_cost = sum(LTLSegment, time_period_ref, LTLSegment.cost * x_rem_ltl).where( + LTLSegment.x_rem_ltl(time_period_ref, x_rem_ltl) ) -LTLSegment_outer = LTLSegment.ref() -LTLSegment_inner = LTLSegment.ref() -total_ltl_bin_cost = (LTLSegment_outer.cost * LTLSegment_outer.limit) * sum(y_bin_ltl).per(LTLSegment_outer).where( - LTLSegment_inner.y_bin_ltl(Integer.ref(), y_bin_ltl), +total_ltl_bin_cost = sum( + LTLSegment_inner, time_period_ref, LTLSegment_outer.cost * LTLSegment_outer.limit * y_bin_ltl +).where( + LTLSegment_inner.y_bin_ltl(time_period_ref, y_bin_ltl), LTLSegment_outer.seg == LTLSegment_inner.seg - 1, ) -total_cost = sum(model.union(total_inv_cost, total_tl_cost, total_ltl_rem_cost, total_ltl_bin_cost)) +total_cost = total_inv_cost + total_tl_cost + total_ltl_rem_cost + total_ltl_bin_cost problem.minimize(total_cost) # -------------------------------------------------- diff --git a/synthetic_eligibility_records/pyproject.toml b/synthetic_eligibility_records/pyproject.toml index 32d01011..ae720ae0 100644 --- a/synthetic_eligibility_records/pyproject.toml +++ b/synthetic_eligibility_records/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: synthetic_eligibility_records (PyRel v1)" readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai==1.1.0", + "relationalai==2.1.1", "pandas>=2.0", ] diff --git a/synthetic_order_lifecycle/README.md b/synthetic_order_lifecycle/README.md index c14f7df8..f62aa885 100644 --- a/synthetic_order_lifecycle/README.md +++ b/synthetic_order_lifecycle/README.md @@ -60,7 +60,7 @@ The same pattern applies to any test-data-generation problem where rows have to ### Tools - Python >= 3.10 -- RelationalAI Python SDK (`relationalai == 1.13.0`) +- RelationalAI Python SDK (`relationalai == 2.1.1`) ## Quickstart @@ -254,8 +254,8 @@ model.require(problem.termination_status() == "OPTIMAL") Import error or AttributeError on relationalai - Confirm your virtual environment is active: `which python` should point to `.venv`. -- Reinstall dependencies: `python -m pip install .`. The pinned version (`relationalai==1.13.0`) ships enum members as constants across the DSL and prescriptive reasoning (alongside the `solve_info()`, `verify()`, and chained-`where().require()` APIs); older versions reject the enum-indexed decision variable and produce type or attribute errors. -- If you share a venv across templates, run `python -m pip install --upgrade --force-reinstall relationalai==1.13.0`. +- Reinstall dependencies: `python -m pip install .`. The pinned version (`relationalai==2.1.1`) ships enum members as constants across the DSL and prescriptive reasoning (alongside the `solve_info()`, `verify()`, and chained-`where().require()` APIs); older versions reject the enum-indexed decision variable and produce type or attribute errors. +- If you share a venv across templates, run `python -m pip install --upgrade --force-reinstall relationalai==2.1.1`. diff --git a/synthetic_order_lifecycle/pyproject.toml b/synthetic_order_lifecycle/pyproject.toml index 796287b8..13c89f06 100644 --- a/synthetic_order_lifecycle/pyproject.toml +++ b/synthetic_order_lifecycle/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: synthetic_order_lifecycle (PyRel v1)" readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai==1.13.0", + "relationalai==2.1.1", "pandas>=2.0", ] diff --git a/telco_network_recovery/README.md b/telco_network_recovery/README.md index 8affe4e2..aee54ed1 100644 --- a/telco_network_recovery/README.md +++ b/telco_network_recovery/README.md @@ -61,7 +61,7 @@ Built using **predictive reasoning** (GNN on a heterogeneous graph), **rules-bas ### Tools - Python >= 3.10. -- RelationalAI Python SDK (`relationalai[gnn] == 1.27.1`). +- RelationalAI Python SDK (`relationalai[gnn] == 2.1.1`). ### One-time Snowflake setup for GNN experiment artifacts diff --git a/telco_network_recovery/pyproject.toml b/telco_network_recovery/pyproject.toml index 08d02a8a..e7f36b8a 100644 --- a/telco_network_recovery/pyproject.toml +++ b/telco_network_recovery/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: telco_network_recovery (PyRel v1)" readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai[gnn]==1.27.1", + "relationalai[gnn]==2.1.1", "pandas>=2.0", ] diff --git a/telco_network_recovery/telco_network_recovery.py b/telco_network_recovery/telco_network_recovery.py index 823ac461..3f6f2a1f 100644 --- a/telco_network_recovery/telco_network_recovery.py +++ b/telco_network_recovery/telco_network_recovery.py @@ -894,7 +894,7 @@ class SubscriberStatus(model.Enum): i, j = Integer.ref(), Integer.ref() p = model.path( seed, Subscriber.calls_via.repeat(1, PATH_MAX_HOPS) - ).all_paths() + ).all().paths() score_df = model.where( seed.id == hub_id, p, @@ -921,7 +921,7 @@ class SubscriberStatus(model.Enum): seed_n.id == hub_id, pn := model.path( seed_n, Subscriber.calls_via.repeat(1, PATH_MAX_HOPS) - ).all_paths(), + ).all().paths(), ).select( pn.alias("path_id"), pn.nodes["index"].alias("step"), @@ -937,7 +937,7 @@ class SubscriberStatus(model.Enum): seed_h.id == hub_id, ph := model.path( seed_h, Subscriber.calls_via.repeat(1, PATH_MAX_HOPS) - ).all_paths(), + ).all().paths(), ).select( ph.alias("path_id"), ph.relationship_fields["index"].alias("hop"), diff --git a/test_data_generation/pyproject.toml b/test_data_generation/pyproject.toml index 3b321767..33c7f234 100644 --- a/test_data_generation/pyproject.toml +++ b/test_data_generation/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: test_data_generation (PyRel v1)" readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai==1.0.14", + "relationalai==2.1.1", "pandas", ] diff --git a/tests/test_generate_template_index.py b/tests/test_generate_template_index.py index c7a8fa7a..fb75aeb0 100644 --- a/tests/test_generate_template_index.py +++ b/tests/test_generate_template_index.py @@ -15,7 +15,7 @@ def test_collects_only_root_template_directories(self) -> None: entries = collect_templates(REPO_ROOT) names = {entry.name for entry in entries} - self.assertEqual(len(entries), 53) + self.assertEqual(len(entries), 52) self.assertIn("simple-start", names) self.assertNotIn("sample-template", names) self.assertNotIn("scripts", names) diff --git a/transaction_screening_local/README.md b/transaction_screening_local/README.md index b140a0c0..fc575ea3 100644 --- a/transaction_screening_local/README.md +++ b/transaction_screening_local/README.md @@ -52,7 +52,7 @@ The value of the template is that you can try this entire workflow with nothing ### Tools - Python 3.10 or later. -- `relationalai` version 1.13.0 or later. DuckDB is included with the package, and 1.13 is the minimum version for the local path. +- `relationalai` 2.1.1, the version pinned in `pyproject.toml`. DuckDB is included with the package. Local DuckDB execution relies on deploy mode, which the package currently flags as experimental. @@ -145,7 +145,7 @@ For the full concept and property definitions, see `transaction_screening_local. ## How it works -The script starts by configuring a local DuckDB connection with automatic deployment, so the model materializes and runs on your machine with no Snowflake connection. It then loads the transfer ledger from CSV and derives an `Account` for every party seen at either end of a transfer. +The script starts by configuring a local DuckDB connection with a `deployment` section, so the model materializes and runs on your machine with no Snowflake connection. The section sets `public_schema` (`main`, where the model's views are published), `identity.internal_schema` (`main_internal`, where RelationalAI keeps the model's internal objects), and `auto_deploy`, which deploys the model before each query. It then loads the transfer ledger from CSV and derives an `Account` for every party seen at either end of a transfer. Next it builds the `transfers_to` relationship, linking each sender to its receiver, one row per transfer. The classification rules follow as declarative derived relationships: an account is flagged as structuring when it sends a transfer just under the reporting threshold, and as a large sender when it sends a transfer over the large-transfer limit. An account is a suspect if either flag holds — expressed as two rules that together read as a logical OR. @@ -186,13 +186,13 @@ DuckDB tables need a three-part name. Reference them as `memory..
A query falls back to a Snowflake path, or reads an empty model relation -Make sure the configuration includes a `deployment` section with `auto_deploy` set to true, so that the model is routed to the DuckDB executor and materialized before queries run. +Make sure the configuration includes a `deployment` section with `public_schema`, `identity.internal_schema`, and `auto_deploy` set to true, so that the model is routed to the DuckDB executor and materialized before queries run.
Existing object ... is of type Table, trying to replace with type View -DuckDB is case-insensitive, so a source table named like a concept collides with the installed view. Keep source tables in a schema named `raw`, separate from the model install schema named `main`. +DuckDB is case-insensitive, so a source table named like a concept collides with the installed view. Keep source tables in a schema named `raw`, separate from the model's public schema `main`.
## Learn more diff --git a/transaction_screening_local/pyproject.toml b/transaction_screening_local/pyproject.toml index 9a3dcab2..1c4f3c7a 100644 --- a/transaction_screening_local/pyproject.toml +++ b/transaction_screening_local/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: transaction_screening_local (PyRel v1, loc readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai==1.13.0", + "relationalai==2.1.1", ] [tool.setuptools] diff --git a/transaction_screening_local/runbook.md b/transaction_screening_local/runbook.md index 72a89310..cbcd34b3 100644 --- a/transaction_screening_local/runbook.md +++ b/transaction_screening_local/runbook.md @@ -21,7 +21,7 @@ transactions.csv — 75 transfers, 54 accounts (in-memory DuckDB, no Snowflake) **These prompts are designed to run in order, in a single session** — each builds on the ontology state created by the ones before it. -Requires `relationalai >= 1.13`. Local DuckDB execution uses deploy mode (flagged experimental in the package). +Requires `relationalai` 2.1.1. Local DuckDB execution uses deploy mode (flagged experimental in the package). --- @@ -31,7 +31,7 @@ Requires `relationalai >= 1.13`. Local DuckDB execution uses deploy mode (flagge > Set up a RelationalAI model on local DuckDB (no Snowflake) over `data/transactions.csv` (columns: `id, src, dst, amount`). Create an `Account` concept identified by `id`, drawn from both the `src` and `dst` of every transfer, and a self-referential `transfers_to` relationship linking each transfer's sender to its receiver. -**Response.** A model on an in-memory DuckDB database, configured with a `deployment` section (`schema` and `auto_deploy`). `Account` has 54 instances; `transfers_to` has 75 directed links, one per transfer. (To count the links, count the transfers — `aggs.count()`. Counting a single account ref instead collapses to distinct senders, not arcs.) +**Response.** A model on an in-memory DuckDB database, configured with a `deployment` section (`public_schema`, `identity.internal_schema`, and `auto_deploy`). `Account` has 54 instances; `transfers_to` has 75 directed links, one per transfer. (To count the links, count the transfers — `aggs.count()`. Counting a single account ref instead collapses to distinct senders, not arcs.) ### Examine the ontology diff --git a/transaction_screening_local/transaction_screening_local.py b/transaction_screening_local/transaction_screening_local.py index eae39ea0..e795479c 100644 --- a/transaction_screening_local/transaction_screening_local.py +++ b/transaction_screening_local/transaction_screening_local.py @@ -39,19 +39,25 @@ LARGE_TRANSFER = 50000.0 # Local DuckDB config (no Snowflake): a duckdb connection plus a `deployment` -# section (schema and auto_deploy) routes the model to the local DuckDB executor -# and materializes derived relations before queries. +# section routes the model to the local DuckDB executor and materializes derived +# relations before queries. The section names the schema for the model's +# published views (`public_schema`), the schema for its internal objects +# (`identity.internal_schema`), and turns on `auto_deploy`. config = create_config( connections={"local": DuckDBConnection(path=":memory:")}, # or a file path, e.g. "./dev.duckdb" default_connection="local", - deployment={"schema": "main", "auto_deploy": True}, + deployment={ + "public_schema": "main", + "identity": {"internal_schema": "main_internal"}, + "auto_deploy": True, + }, ) # -------------------------------------------------- # Define semantic model & load data # -------------------------------------------------- # Load the ledger straight into DuckDB. Keep source data in a schema (`raw`) -# separate from the model install schema (`main`) — DuckDB is case-insensitive, +# separate from the model's public schema (`main`) — DuckDB is case-insensitive, # so a source table named like a concept would collide with the installed view. session = config.get_connection(DuckDBConnection).get_session() session.execute("CREATE SCHEMA IF NOT EXISTS raw") diff --git a/traveling_salesman/README.md b/traveling_salesman/README.md index 416915a5..a4b6b6e8 100644 --- a/traveling_salesman/README.md +++ b/traveling_salesman/README.md @@ -52,7 +52,7 @@ Built using **prescriptive reasoning** (mixed-integer programming with the HiGHS ### Tools - Python >= 3.10 -- RelationalAI Python SDK (`relationalai == 1.0.14`) +- RelationalAI Python SDK (`relationalai == 2.1.1`) ## Quickstart diff --git a/traveling_salesman/pyproject.toml b/traveling_salesman/pyproject.toml index 6d646a2d..1169ddf6 100644 --- a/traveling_salesman/pyproject.toml +++ b/traveling_salesman/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: traveling_salesman (PyRel v1)" readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai==1.0.14", + "relationalai==2.1.1", "pandas", ] diff --git a/underwriting_audit/README.md b/underwriting_audit/README.md index 804568af..b8316697 100644 --- a/underwriting_audit/README.md +++ b/underwriting_audit/README.md @@ -55,7 +55,7 @@ Built using **prescriptive reasoning** (constraint satisfaction with multi-solut ### Tools - Python >= 3.10 -- RelationalAI Python SDK (`relationalai == 1.1.0`) +- RelationalAI Python SDK (`relationalai == 2.1.1`) ## Quickstart diff --git a/underwriting_audit/pyproject.toml b/underwriting_audit/pyproject.toml index e07af2a3..83fbbd55 100644 --- a/underwriting_audit/pyproject.toml +++ b/underwriting_audit/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: underwriting_audit (PyRel v1)" readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai==1.1.0", + "relationalai==2.1.1", "pandas", ] diff --git a/warehouse_allocation/README.md b/warehouse_allocation/README.md index 719050a1..479e4d36 100644 --- a/warehouse_allocation/README.md +++ b/warehouse_allocation/README.md @@ -54,7 +54,7 @@ Built using **graph analysis** (eigenvector centrality, weakly connected compone ### Tools - Python >= 3.10. -- RelationalAI Python SDK (`relationalai == 1.11.0`). +- RelationalAI Python SDK (`relationalai == 2.1.1`). ## Quickstart diff --git a/warehouse_allocation/pyproject.toml b/warehouse_allocation/pyproject.toml index 10227c89..ce570013 100644 --- a/warehouse_allocation/pyproject.toml +++ b/warehouse_allocation/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: warehouse_allocation (PyRel v1)" readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai==1.11.0", + "relationalai==2.1.1", "pandas", ] diff --git a/water_allocation/README.md b/water_allocation/README.md index 422be002..f7145cdb 100644 --- a/water_allocation/README.md +++ b/water_allocation/README.md @@ -51,7 +51,7 @@ Built using **prescriptive reasoning** (nonlinear program over continuous flow v ### Tools - Python >= 3.10. -- RelationalAI Python SDK (`relationalai == 1.0.14`). +- RelationalAI Python SDK (`relationalai == 2.1.1`). ## Quickstart diff --git a/water_allocation/pyproject.toml b/water_allocation/pyproject.toml index 64fa9d20..c5eb4925 100644 --- a/water_allocation/pyproject.toml +++ b/water_allocation/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: water_allocation (PyRel v1)" readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai==1.0.14", + "relationalai==2.1.1", "pandas", ] diff --git a/wildlife-conservation-network/README.md b/wildlife-conservation-network/README.md index d8ae7167..36967831 100644 --- a/wildlife-conservation-network/README.md +++ b/wildlife-conservation-network/README.md @@ -52,7 +52,7 @@ Built using **graph analysis** (Louvain community detection and degree centralit ### Tools - Python >= 3.10. -- RelationalAI Python SDK (`relationalai == 1.11.0`). +- RelationalAI Python SDK (`relationalai == 2.1.1`). - Streamlit (installed via the optional `.[visualization]` extra) for the interactive app. ## Quickstart diff --git a/wildlife-conservation-network/pyproject.toml b/wildlife-conservation-network/pyproject.toml index e65de287..cc0fbfc6 100644 --- a/wildlife-conservation-network/pyproject.toml +++ b/wildlife-conservation-network/pyproject.toml @@ -9,7 +9,7 @@ description = "RelationalAI template: wildlife conservation network with Louvain readme = "README.md" requires-python = ">=3.10" dependencies = [ - "relationalai==1.11.0", + "relationalai==2.1.1", "pandas>=2.0.0", ]