rai-graph-analysis

name

rai-graph-analysis

description

Graph algorithm selection and execution on PyRel v1 models — construction from ontology patterns, parameter tuning, and result extraction. Use for questions about a network's structure — centrality and importance, community detection, connectivity and components, reachability and dependencies, shortest paths and distance, node similarity, and variable-length path enumeration (where the route itself is the answer).

Graph Analysis

• Summary
• Quick Reference
• Graph Analysis Workflow
• Graph Construction from Ontology
• Parameter Guidance
• Domain Constraints
• Result Extraction and Binding
• Downstream Use
• Common Pitfalls
• Examples
• Reference Files

Summary

What: Graph algorithm selection and execution — building Graph instances from PyRel ontology patterns and running the right algorithm to answer structural questions about the data.

When to use:

• Building a Graph instance from an existing PyRel model (choosing node concept, edge construction, directed/weighted)
• Selecting which graph algorithm answers a given question (centrality, community, reachability, etc.)
• Configuring algorithm parameters (direction, weights, aggregator)
• Extracting and binding graph results to model properties
• Feeding graph outputs into downstream reasoning (optimization, rules, predictions)

When NOT to use:

• Discovering whether graph analysis is appropriate for a dataset — see rai-discovery
• PyRel syntax reference (imports, types, model patterns) — see rai-pyrel
• Ontology design decisions (concept modeling, data mapping) — see rai-ontology
• Optimization formulation (variables, constraints, objectives) — see rai-prescriptive-problem
• Business rule authoring (validation, classification, alerting) — see rai-pyrel
• GNN graph construction for predictive pipelines — see rai-predictive-modeling

Overview (process steps):

1. Study the existing model — understand base definitions, coding conventions, and what's already wired
2. Start from the question — identify which concepts and relationships are relevant, and what kinds of analysis best speak to the question
3. Determine which relevant concepts should constitute nodes in the graph
4. Determine what edges would best capture the information relevant to the question and the planned analysis
5. Figure out how to derive those edges from the relevant relationships (sometimes a pass-through, often involving filters or more substantial logic)
6. Choose which Graph constructor pattern fits given the node/edge decisions
7. Select the specific algorithm(s) best suited to the question
8. Execute, extract results, and blend back into the model for downstream use

---

Quick Reference

# Imports
from relationalai.semantics import Model, Float, Integer, String, where, define, data
from relationalai.semantics.reasoners.graph import Graph
from relationalai.semantics.std import aggregates, floats

model = Model("my_model")

Note: where, define, and data are available as standalone imports and as model.where(), model.define(), model.data() methods. Both are equivalent for single-model scripts. Use the model.* form when multiple Models exist — standalone functions fail with "Multiple Models have been defined.". See rai-pyrel for data loading patterns with model.data().

Graph constructor — three patterns

Pattern 1: No existing node or edge concepts — the most common pattern. Use when nodes are drawn from multiple concepts, or when not all instances of a concept should be nodes. Edges are defined manually with Edge.new().

graph = Graph(
    model,
    directed=True|False,          # Edge directionality
    weighted=True|False,          # Whether edges carry weights
)
Node, Edge = graph.Node, graph.Edge
# Define nodes and edges manually with Edge.new(src=..., dst=...)

Pattern 2: Existing node concept, manual edges — use when a single concept covers all desired nodes and you want all instances as nodes (including isolated nodes with no edges). Isolated nodes can also be added explicitly via model.define(Node(my_instance)).

graph = Graph(
    model,
    directed=True|False,
    weighted=True|False,
    node_concept=MyConcept,       # All instances of MyConcept become nodes; graph.Node is bound to MyConcept
)
Node, Edge = graph.Node, graph.Edge
# graph.Node IS MyConcept — properties assigned to graph.Node are directly available on MyConcept
# Define edges manually with Edge.new(src=..., dst=...)

Pattern 3: Existing node concept + edge concept — use when each interaction is already modeled as its own concept with source/destination relationships. Rather than deriving new nodes and edges, graph.Node, graph.Edge, graph.EdgeSrc, graph.EdgeDst, and graph.EdgeWeight bind directly to the provided concepts and relationships — avoiding extra computation, which matters for large graphs.

graph = Graph(
    model,
    directed=True,
    weighted=True,
    node_concept=Account,
    edge_concept=Transaction,                      # Each Transaction instance becomes an edge
    edge_src_relationship=Transaction.payer,        # Source endpoint
    edge_dst_relationship=Transaction.payee,        # Destination endpoint
    edge_weight_relationship=Transaction.amount,    # Edge weight (required when weighted=True)
)

Important:

• When using edge_concept, you must also pass node_concept, edge_src_relationship, and edge_dst_relationship. Add edge_weight_relationship when the graph is weighted.
• Weights must be floats. Use floats.float() to cast from other numeric types: weight=floats.float(Transaction.amount).
• Note: edge_src_relationship, edge_dst_relationship, and edge_weight_relationship accept only a Relationship or Chain — not a Property, not an Expression. If your ontology models the link as a Property (e.g., f"{Edge} from {Node:source}"), or if you need to cast (floats.float(...)), use Pattern 1 or 2 with manual Edge.new(src=..., dst=..., weight=...) instead. Pattern 3 will fail silently with a model warning and produce 0 edges.

Graph constructor aggregator parameter guidance

aggregator defaults to None; multi-edges (parallel edges between the same node pair) emit warnings when present. aggregator="sum" (the only supported alternative) collapses multi-edges by summing weights — works on unweighted too.

Use it only when multi-edges are expected (co-occurrence with multiple shared attributes, or intermediary concepts where multiple operations connect the same pair). Omit otherwise — silencing unexpected multi-edges masks bugs in edge-derivation logic.

Algorithm cheat sheet

Compatibility constraints in this section are non-exhaustive. For any algorithm you plan to call, load algorithm-selection.md and confirm its compatibility row before writing the Graph(...) constructor. The Pre-flight table in Step 7 summarizes the most common gotchas, but is also non-exhaustive.

Family	Methods	Output Shape	Typical Use
Basic Stats	num_nodes(), num_edges(), num_triangles()	relation; use .inspect() to print	Graph validation, sanity checks
Neighbors	neighbor(), inneighbor(), outneighbor(), common_neighbor()	(node, node) or (node, node, node)	Neighborhood exploration
Degree	degree(), indegree(), outdegree(), weighted_degree(), weighted_indegree(), weighted_outdegree()	(node, value)	Connection counts
Centrality	eigenvector_centrality(), betweenness_centrality(), degree_centrality(), pagerank()	(node, score)	Importance, influence, bottlenecks
Community	louvain(), infomap(), label_propagation()	(node, label)	Natural groupings, clusters
Components	weakly_connected_component(), is_connected()	(node, component_id) or scalar	Fragmentation, isolation
Reachability	reachable()	(source, target) pairs	Dependency tracing, impact analysis
Distance	distance(), diameter_range()	(start, end, length)	Shortest paths, network diameter
Similarity	jaccard_similarity(), cosine_similarity(), adamic_adar(), preferential_attachment()	(node1, node2, score)	Entity comparison, link prediction
Clustering	local_clustering_coefficient(), average_clustering_coefficient(), triangle_count(), triangle(), unique_triangle()	(node, value) or (n1, n2, n3)	Local density, tightness

Bridge edges (edge-side single points of failure) have no named primitive — don't loop a WCC per candidate edge; collapse to one layered WCC. See Collapsing per-scenario connectivity checks.

For compatibility constraints (directed/weighted limits per algorithm), see Step 7.

---

Graph Analysis Workflow

Step 1: Study the Existing Model

Before writing any graph or enrichment code, read the existing model file to understand:

1. How to include base definitions — graph scripts that extend an existing model must import it (e.g., from my_model import model, Site, Operation) so that all base define() rules are in scope. Creating a standalone Model("same name") reference without the base definitions will produce an empty graph because concept instances won't exist.
2. Coding conventions — check how the existing model references table columns (casing, naming patterns) and follow the same style. The model file is the source of truth for conventions, not external metadata tools.
3. What's already wired — identify which relationships and properties exist vs. what needs enrichment. Only enrich what's missing.

Steps 2–5: From Question to Nodes and Edges

Start from the question, not the ontology. The question determines which concepts become nodes, what edges you need, and how to derive them.

Step 2 — Scope the question:

• State the question clearly — what property of the data's network structure are you trying to understand?
• Identify which concepts and relationships in the ontology are relevant to the question
• In broad strokes, what kinds of graph analysis over those concepts and relationships best speak to the question?

Step 3 — Identify the nodes:

• Which of the relevant concepts should constitute nodes — the actors or objects you want to rank, group, or trace?

Step 4 — Determine the edges:

• What edges would best capture the information relevant to the question and the planned analysis?
• Does direction matter? Direction often matters for flow, dependency, or causality. Undirected is often appropriate for co-membership or symmetric relationships. Consider whether directionality is semantically meaningful for your question.
• Note: The edges you need are informed both by the question and by the algorithm you plan to apply.

Step 5 — Derive edges from relationships:

• Sometimes an existing relationship maps directly to edges (the rules are essentially pass-through).
• Often, edges must be derived from one or more relationships less directly — involving filters, joins, or more substantial logic.
• Scan the ontology for the structural signals below to find how to build the edges you need.

Key principle: A single ontology can support multiple graph constructions. Different questions about the same data lead to different node/edge choices. The question always comes first — the ontology is the source of available structure, not the driver.

Recognizing edge sources in the ontology:

Once you know what nodes and edges you need, scan the ontology for these structural signals to find them:

Ontology Signal	What to Look For	How It Becomes Edges
Direct relationship	Concept A has a relationship to Concept B (or to itself)	The relationship itself is an edge — use Edge.new(src=a, dst=b)
Intermediary concept	A concept C with two relationships pointing to the same node type (e.g., source and destination both referencing Concept A)	Each instance of C becomes an edge between the two endpoints — use Edge.new() or edge_concept (edge_concept only when the src/dst are Relationships)
Shared attribute	Two instances of Concept A both relate to the same instance of Concept B (e.g., two users sharing an address, two customers ordering the same product)	Co-occurrence — entities sharing an attribute are connected. Requires id < guard to prevent duplicates
Self-referencing	A concept with a relationship back to itself (e.g., parent, reports_to, depends_on, subcomponent, follows)	Instance-to-instance edges within one concept — may be acyclic (hierarchies, DAGs) or contain cycles
Multi-concept co-occurrence	Multiple distinct attributes shared between entities (e.g., shared address OR shared phone OR shared email)	Each shared attribute type creates edges — combine in a single graph for richer connectivity

Tip: When the ontology has an interaction concept with source/destination relationships and edge-relevant properties (volume, weight, intensity), prefer edge_concept over manual Edge.new() — it's more concise and ensures every instance is included.

Step 6: Choose Construction Pattern

Map the ontology signal you identified in Steps 2–5 to a construction pattern and decide how to implement it:

Ontology Signal (from Steps 2–5)	Construction Pattern	Edge Method	Example
Direct relationship	Entity-level	Edge.new(src=a, dst=b)	Graph Construction from Ontology
Intermediary concept	Infrastructure-level	Edge.new() from intermediary, or edge_concept if concept has src/dst/weight	centrality_weighted_undirected.py, edge_concept_multi_algorithm.py
Shared attribute	Co-occurrence	Edge.new() with id < guard	community_to_derived_concept.py
Multi-concept co-occurrence	Multi-attribute co-occurrence	Multiple Edge.new() calls (one per shared attribute)	chained_graph_rules.py
Self-referencing	Hierarchy, recursive, or cyclic	Edge.new(src=parent, dst=child)	graph-construction.md

Then decide the remaining axes:

1. Directed or undirected? — Directed for flow/dependency, undirected for structural analysis
2. Weighted or unweighted? — Weighted when edge properties (cost, volume, distance) matter for the question
3. Edge.new() or edge_concept? — Prefer edge_concept when the interaction is already modeled as a concept with src/dst relationships

See graph-construction.md for detailed patterns including filtered edges, multi-graph, and weight construction.

Step 7: Select Algorithm

Start from the question, not the algorithm name. First check whether the question reduces to an aggregation — per-entity counts and one-hop group-bys ("how many sources per target?", "which targets have only one predecessor?") run as aggs.count(distinct(...)).per(target) with no Graph constructor needed. Reserve graph reasoners for multi-hop traversal, partitioning, and centrality.

Question Type	Algorithm Family	Default Choice
"Who/what is most important?" (directed graph)	Centrality	pagerank() (inbound flow)
"Who/what is most important?" (undirected graph)	Centrality	eigenvector_centrality() (mutual importance)
"Which nodes are bottlenecks?"	Centrality	betweenness_centrality() (bridge nodes)
"What natural groups exist?"	Community	louvain() (undirected) or infomap() (directed)
"Is the network fragmented?"	Components	weakly_connected_component()
"Which edges are single points of failure (bridges)?"	Components	No named primitive — a single layered WCC (one node per (node, excluded-edge)), not a per-edge WCC loop. See algorithm-selection.md
"What are all transitive dependencies?"	Reachability	reachable()
"What depends on X? / What does X affect?"	Reachability	reachable()
"How far apart are X and Y?"	Distance	distance() — supports weighted (non-negative)
"Which entities are most similar?"	Similarity	jaccard_similarity()
"How tightly connected locally?"	Clustering	local_clustering_coefficient() — requires undirected

Within the Centrality family, pick the variant by the structural test:

• Eigenvector — undirected mutual importance: a node ranks high when its undirected neighbors do. Requires directed=False. Use for structural-importance / centrality questions (symmetric, co-occurrence, similarity graphs). See eigenvector vs. PageRank.
• Betweenness — bottleneck identification: nodes that sit on many shortest paths. Best for: "which nodes are critical connectors / single points of failure?" Requires weighted=False.
• PageRank — directed inbound flow: importance accumulates along incoming edges. Default for any directed graph where the question explicitly turns on which nodes receive the most flow or attention.
• Degree — local connectivity: count of direct connections. Best for: "which nodes have the most direct relationships?"

One algorithm per question. Pick the single algorithm that matches the structural test above. Don't combine multiple centrality measures into a "composite criticality score" — the resulting ranking has no clean interpretation, depends on arbitrary normalization choices, and typically reorders results vs. any one of its inputs. If the question genuinely requires multiple lenses, run them as separate columns in the output, but rank by one and explain why.

Pre-flight compatibility check. Before Step 8, confirm the chosen algorithm fits the graph's directed/weighted settings:

Algorithm	Cannot use with
betweenness_centrality()	weighted=True
eigenvector_centrality()	directed=True (use pagerank() for directed)
louvain()	directed=True (use infomap() for directed)
local_clustering_coefficient()	directed=True (requires undirected)
diameter_range()	directed=True or weighted=True (requires undirected, unweighted)

• pagerank() / reachable() work on undirected but are most meaningful on directed.
• louvain(), infomap(), label_propagation() are non-deterministic — report ranges or structural assertions, not exact values.

For per-algorithm deep dives (parameters, output shapes, interpretation, compatibility matrix), see algorithm-selection.md and confirm the row for any algorithm you call.

Step 8: Configure, Execute, and Bind Results

Canonical assign → bind → query skeleton:

graph = Graph(model, directed=False, weighted=True, node_concept=MyConcept, aggregator="sum")  # match flags to the algorithm (Step 7 pre-flight): eigenvector needs directed=False
model.define(graph.Edge.new(src=..., dst=..., weight=...))                  # define edges
graph.Node.score = graph.eigenvector_centrality()                           # execute — substitute any algorithm
model.where(graph.Node == MyConcept).define(MyConcept.score(graph.Node.score))  # bind back
model.select(MyConcept.id, MyConcept.score).to_df()                         # query

For the directed / weighted / aggregator decisions, see Parameter Guidance. Expensive algorithms (reachable, jaccard_similarity, distance, triangle, …) require explicit domain constraints (of=/from_=/to=/between=/full=True) to run — see Domain Constraints. For the full assign → bind → query walkthrough and per-algorithm extraction, see Result Extraction and Binding and result-extraction.md.

---

Graph Construction from Ontology

The question determines which construction to use — the same ontology can yield multiple valid graphs.

Pattern	Nodes	Edges	Typical Use
Entity-level directed	Business entities	Direct relationships (ships_to)	PageRank, reachability
Infrastructure undirected weighted	Locations/sites	Intermediary concepts (Operation)	Centrality, WCC, bridges
Co-occurrence / shared-attribute	Entities	Shared membership/purchases	Community detection
Self-referencing	Single concept	Instance-to-instance refs (parent-child, depends_on, etc.)	Reachability, tree traversal, BOM, dependency graphs
edge_concept	Any	Existing interaction concept	When edges are already modeled

Two main edge definition approaches (Patterns 1–2 vs Pattern 3)

Manual edges with Edge.new() — most common:

# Entity-level: direct relationship between concepts
graph = Graph(model, directed=True, weighted=False, node_concept=Business)
b1, b2 = Business.ref(), Business.ref()
model.where(b1.ships_to(b2)).define(graph.Edge.new(src=b1, dst=b2))

# Infrastructure-level: edges from intermediary concept
graph = Graph(model, directed=False, weighted=True, node_concept=Site, aggregator="sum")
op = Operation.ref()
model.where(
    op.source_site(site1 := Site.ref()),
    op.output_site(site2 := Site.ref()),
).define(graph.Edge.new(src=site1, dst=site2, weight=op.shipment_count))

# Co-occurrence: shared attribute (id < guard prevents duplicates)
graph = Graph(model, directed=False, weighted=True, node_concept=Customer, aggregator="sum")
left_order, right_order = Order.ref(), Order.ref()
model.where(
    left_order.product == right_order.product,
    left_order.customer.id < right_order.customer.id,
).define(graph.Edge.new(src=left_order.customer, dst=right_order.customer, weight=1.0))

Concept-based edges with edge_concept — when each interaction is already a concept, pass it via edge_concept= + the three required relationships (edge_src_relationship, edge_dst_relationship, and edge_weight_relationship when weighted). See Quick Reference Pattern 3 for the full constructor signature.

Filtered edges: restrict via .where(t.amount >= 100.0).define(graph.Edge.new(src=t.payer, dst=t.payee)).

For detailed patterns (multi-intermediary, hierarchy, self-referencing, multi-graph, weight construction, validation), see graph-construction.md. Graph algorithms and prescriptive optimization coexist on the same Model — use domain concepts directly as node_concept (no mirror concepts or separate models needed).

---

Parameter Guidance

Defaults: directed=False, weighted=False. Only deviate when the question's structure justifies it. Flipping either flag changes algorithm outputs significantly — Louvain communities partition differently, PageRank scores invert, eigenvector is undefined on directed graphs. Add direction or weight only when the question explicitly demands it (see "When to use" below).

Parameter	Values	When to use
directed	True	Promote to directed only when the question is about flow, dependency, or causality — i.e., the edge's direction has semantic meaning the answer depends on.
	False	Default. Symmetric relationships, co-occurrence, infrastructure connectivity, similarity.
weighted	True	Promote to weighted only when an edge-property quantity is explicitly named in the question. Don't add weights speculatively because a numeric column on the edge "looks relevant" — for community detection in particular, weighting changes the partition. Weights must be floats — cast with floats.float().
	False	Default. Only connection existence matters.
aggregator	"sum"	Only supported alternative to the default None. Collapses multi-edges by summing weights. Only use when multi-edges are expected — see Aggregator guidance.
node_concept	Concept	Which concept forms nodes. Required with edge_concept. Optional otherwise (inferred from edges).

---

Domain Constraints

Domain constraints control which subset of an output relationship gets materialized. Some algorithms (e.g., preferential_attachment, common_neighbor, jaccard_similarity, reachable, triangle, distance) are expensive to materialize in full and require explicit domain constraints via of=, from_=, to=, between=, or full=True to proceed.

Keyword	Meaning
of=R	Constrain to nodes in relationship R (binary relationships: degree, neighbor, etc.)
from_=R	Source / first-argument nodes (paths, reachability)
to=R	Destination / second-argument nodes
from_=R1, to=R2	Separately constrain both axes
between=R	Jointly constrain to specific node pairs (binary Relationship of pairs)
full=True	Override guard and compute full relationship

For detailed guidance — which relationships support which keywords, the full=True guard rationale, and a worked constrained-similarity example — see domain-constraints.md.

---

Result Extraction and Binding

Core pattern: assign → bind → query

# 1. Run algorithm — result lives on graph.Node
graph.Node.centrality_score = graph.eigenvector_centrality()

# 2. Bind to original concept (makes it available for rules, optimization, queries)
Site.centrality_score = model.Property(f"{Site} has {Float:centrality_score}")
model.where(graph.Node == Site).define(Site.centrality_score(graph.Node.centrality_score))

# 3. Query as DataFrame
df = model.select(Site.id, Site.centrality_score).to_df().sort_values("centrality_score", ascending=False)

Shorthand: assign to graph.Node with node_concept

When node_concept is set (e.g., node_concept=User), graph.Node IS the concept — assigning to graph.Node directly creates the property on the concept without a separate binding step:

# graph.Node IS User when node_concept=User — property is automatically available on User
graph.Node.community = graph.weakly_connected_component()

# Query directly via User — no explicit binding needed
df = model.select(User.name, User.community).to_df()

Community labels → concept entities

graph.Node.community_label = graph.louvain()
Segment = model.Concept("Segment", identify_by={"id": Integer})
model.define(Segment.new(id=graph.Node.community_label))
Customer.segment = model.Property(f"{Customer} belongs to {Segment:segment}")
model.where(graph.Node == Customer).define(
    Customer.segment(Segment.lookup(id=graph.Node.community_label))
)

Type handling

Critical: Any integer-valued graph result column (community IDs, unweighted distance() lengths, degree counts) arrives in pandas as Int128Array — reductions raise, and equality filters against Python ints silently match nothing (df[df.hops == 6] returns empty even when df.hops.max() is 6). Cast with .astype(int) before pandas comparisons, groupby, or model.data(). WCC is different: its output is a Node, so the shorthand produces string hashes (.astype(str)) while the direct-query pattern using graph.Node.ref() exposes the node identifier type directly. See result-extraction.md for full casting guidance including both WCC access modes.

Validation

graph.num_nodes().inspect()  # 0 = edge definitions don't match data
graph.num_edges().inspect()  # 0 = relationship/join path is wrong

# .inspect() prints and returns None — for an assertion or any Python-side
# check, fetch the scalar through a query:
n_edges = int(model.select(graph.num_edges().alias("n")).to_df()["n"].iloc[0])
assert n_edges > 0

For per-algorithm query patterns (binary, ternary, reachability, similarity filtering, aggregation), see result-extraction.md.

---

Downstream Use

Graph outputs become model properties that other reasoning consumes:

• Optimization: Centrality scores as objective weights, community labels for per-group constraints
• Rules: Threshold-based alerting on graph metrics (e.g., centrality < 0.1 → at-risk flag)
• Predictions: Community membership and centrality as predictive features
• Multi-graph: Run multiple Graph() instances on the same model for complementary perspectives (e.g., directed flow graph + undirected connectivity graph)

# Graph metric feeds optimization
problem.maximize(aggregates.sum(x * Site.centrality_score))

# Graph metric feeds rule
Site.is_at_risk = model.Relationship(f"{Site} is at risk")
model.where(Site.centrality_score < 0.1).define(Site.is_at_risk())

---

Common Pitfalls

Mistake	Cause	Fix
louvain() fails on directed graph	Louvain requires undirected	Set directed=False or use infomap() for directed
Empty graph (no edges)	Edge definition doesn't match data — wrong relationship or join path	Verify edge source/destination properties exist and have data; query edge count before running algorithms
0 edges from a multi-argument relationship	Endpoints bound from a relationship packing several positional fields, with the slots in the wrong order — the binding matches no rows	Confirm the field order with inspect.fields(rel) before binding, and check graph.num_edges().inspect() immediately after defining edges. Binding endpoints from raw source columns (node.id == table.col) is a reliable fallback when the field order is ambiguous
Int128Array errors in pandas or model.data()	Community detection IDs (Louvain, Infomap) are always Int128 — incompatible with pandas ops and model.data() type inference	Cast: df["col"] = df["col"].astype(int) before pandas operations and before passing to model.data(). WCC is different — its output is a Node, not an integer: via shorthand the column arrives as string hashes (.astype(str)), via direct-query comp_ref.id it inherits the node's identifier type — Int128 when identify_by={"id": Integer} (cast with .astype(int)), a plain string column otherwise. See result-extraction.md
Duplicate/self-loop edges	Missing guard in co-occurrence pattern	Add left.id < right.id to .where() clause
aggregator missing	Weighted graph with multi-edges requires aggregator for parallel edges	Add aggregator="sum" — but only when multi-edges are expected (see Aggregator guidance)
Parallel edges mask bridges	Two edges between the same node pair mean removing one doesn't disconnect the pair — neither is a true bridge	Before reporting bridges, check whether the underlying data has parallel edges between the same endpoints. Do not collapse with aggregator="sum" before bridge detection — that merges parallel edges into one, making the single result appear to be a bridge when physically it isn't. For the recipe, see Collapsing per-scenario checks
Reaching for an external Python graph library when the algorithm isn't in the cheat sheet	Common reflex when the named primitive doesn't exist (e.g., bridge edges, edge betweenness) — but switching to NetworkX/igraph loses the concept binding that lets results feed downstream rules and optimization on the same model, and forces a pandas round-trip back into the model	First check whether the question can be expressed compositionally with the existing primitives — for example, bridge edges fall out of a single layered WCC. If the reflex is driven by scale (a per-scenario loop is slow), collapse the scenarios into one layered graph + one WCC rather than leave the reasoner — see Collapsing per-scenario connectivity checks
Weight type error	Weights must be floats, but property is Integer/Number	Cast with floats.float(property) in Edge.new weight parameter
ValueError: edge_weight_relationship must have type Float, is Number(38,0)	Weight property is Integer (count, duration in seconds, etc.), but graph weights must be Float	Cast inline with weight=floats.float(Entity.int_prop) in Edge.new(), or define a Float-typed derived property on the node concept
Centrality all equal / graph too dense	Two causes: (1) co-occurrence edges built on shared attribute values rather than shared specific entities produce near-complete graphs; (2) even with correct edges, all nodes have identical connectivity	(1) Build edges from shared specific entities (same FK value), not shared attribute categories; (2) add weighted edges to differentiate. If centrality is still uniform after both fixes, the underlying data may lack structural bottlenecks
Similarity produces too many results	O(n^2) output for n nodes	Use domain constraints to limit computation: e.g. graph.jaccard_similarity(from_=seed_nodes). If you need the full relationship, filter by minimum threshold or limit to top-k per node after full=True.
Reachability on undirected connected graph gives trivial results	On undirected connected graphs, all nodes are reachable from all others — results aren't useful	Set directed=True for meaningful reachability/impact analysis. (On disconnected undirected graphs, reachable can still be useful for discovering components for specific nodes.)
Wrong node concept	Using intermediary concept as nodes instead of entity concept	Intermediary concepts form edges, not nodes — e.g., Operation is an edge between Site nodes
Graph results not visible on original concept	Results bound to graph.Node but not to the source concept	Add explicit binding: model.where(graph.Node == MyConcept).define(...)
TypeError with large local models	In local execution mode, models with many (200+) Relationships in scope alongside a Graph can exceed type inference limits, producing a TypeError	First try: isolate the Graph in a separate script/model that imports only the concepts the Graph needs, reducing the type inference scope. Fallback: keep large datasets as pandas DataFrames for Python-side analysis. This limitation is specific to local execution; Snowflake-backed models handle larger schemas.
Empty graph when extending existing model	Script creates Model("name") without importing base model definitions — concepts exist but have no instances	Import the base model module (e.g., from my_model import model, Site) so base define() rules are in scope
ValidationError: Unused variable when using rank() with graph properties	Using rank(desc(graph.Node.betweenness)) alongside other graph properties in select() triggers the unused variable validator	Sort in pandas instead: .to_df().sort_values("betweenness", ascending=False).reset_index(drop=True) — avoid rank() in graph queries
DataFrame column name doesn't match the property name you assigned	Column names follow the algorithm's default output binding (often centrality, score, community) or the variable name used in .select() — they don't inherit the attribute name from graph.Node.my_name = graph.algorithm()	Always set names explicitly with .alias("my_name") in select(...). Don't rely on assignment-name propagation: model.select(Site.id, score.alias("centrality")).to_df()
RAIException: Ungrounded variables when mixing chained derived properties + Graph + boolean rules	Defining chained derived properties (e.g., peak_forecast → future_headroom) alongside Graph construction and boolean Relationship rules in the same model causes ungrounded variable errors	Query raw data via simple selects and compute derived values / rules in pandas. Root cause is related to the type inference limit noted above — chained derivations compound the issue

---

Examples

Each example targets a distinct combination of edge construction, topology, algorithm, and result pattern.

Primary Pattern	Construction	Topology	Algorithms	Result Pattern	File
Infrastructure Edge.new()	Intermediary concept (Operation) creates edges	Undirected, weighted	Eigenvector centrality	Simple property binding	centrality_weighted_undirected.py
Co-occurrence Edge.new()	Shared-attribute edges with id < guard	Undirected, unweighted	WCC + betweenness	Hybrid risk: graph metric + domain attribute	co_occurrence_wcc_bottleneck.py
edge_concept + computed weight	Interaction concept as edges, multi-factor weight	Directed, weighted	PageRank + degree centrality	Multi-algorithm classification	edge_concept_multi_algorithm.py
Directed reachability	edge_concept for dependency chain	Directed, unweighted	Reachability (4 modes) + betweenness	Graph + ontology enrichment	reachability_four_modes.py
Louvain → derived concept	Co-occurrence edges, community labels become entities	Undirected, weighted	Louvain + degree centrality	Community → concept + hub-per-community	community_to_derived_concept.py
Graph + rules combo	Multi-concept co-occurrence (shared address/phone/email)	Undirected, unweighted	WCC	Layered Relationship flags on graph results	chained_graph_rules.py
Identity graph self-join	Self-join edges from shared identifiers (phone, email)	Undirected, unweighted	WCC	Identity cluster detection	self_join_wcc_subtypes.py
Multiple graphs, same model	Multiple Graph instances on same node concept	Weighted + unweighted	Eigenvector + betweenness	Parallel graph views, separate Edge defs	multi_graph_same_model.py
Jaccard similarity	Co-occurrence edges via shared attribute	Undirected, unweighted	Jaccard similarity	Top-k similar pairs extraction	similarity_jaccard.py
Shortest path distances	edge_concept with cost weight	Directed, weighted	Distance	All-pairs shortest paths, filter by source/target	shortest_path_distance.py
Path enumeration (PREVIEW)	Self-referencing relationship	Cyclic	path(rel.repeat(min,max)).all_paths()	Node-sequence projection + simple-path filter	paths_variable_length_enumeration.py
Path scoring along route (PREVIEW)	Binary edge from intermediary	Typed endpoints	all_paths() + aggregates.sum(...).per(p) + p.nodes(idx) / nested-segment filters	Rank routes by a per-node value aggregated along the path; per-node and only-through filters	paths_scored_routes.py
Multi-relationship sequence (PREVIEW)	Two distinct relationships in series	Directed	path(a.rel1, b.rel2).all_paths()	Route alternating edge types; p.relationships reads the per-hop label	paths_multi_relationship_sequence.py

---

Reference Files

Reference	Description	File
Graph construction	Detailed construction patterns from ontology — entity-level, infrastructure, hierarchy, bridge, self-referencing, filtered, multi-graph	graph-construction.md
Algorithm selection	Per-algorithm deep dive — when to use, parameters, output shape, complexity, decision guidance	algorithm-selection.md
Domain constraints	Why they matter, which relationships support which keywords, full=True guard rationale, worked constrained-similarity example	domain-constraints.md
Result extraction	Query patterns for each algorithm output shape, model binding, DataFrame extraction, type handling	result-extraction.md
Path enumeration (PREVIEW)	When the answer is the route itself — variable-length traversal, intermediary→edge, multi-relationship sequences, typed endpoints, point queries, per-path filters, aggregate-a-value-along-route, walk-vs-simple-path. Load for any path-shaped question (relationalai>=1.15)	paths.md