relationalai 0.12.4__py3-none-any.whl → 0.12.6__py3-none-any.whl

relationalai/semantics/reasoners/graph/core.py

@@ -21,7 +21,9 @@ from relationalai.semantics import (
 )
 from relationalai.docutils import include_in_docs
 from relationalai.semantics.internal import annotations
+from relationalai.semantics.internal import internal as builder_internal # For primitive graph algorithms.
 from relationalai.semantics.std.math import abs, isnan, isinf, maximum, natural_log, sqrt
+from relationalai.semantics.std.integers import int64
 
 Numeric = Union[int, float, Decimal]
 NumericType = Type[Union[Numeric, Number]]
@@ -1067,6 +1069,7 @@ class Graph():
     def _validate_domain_constraint_parameters(
             self,
             method_name: str,
+            symmetric: bool,
             full: Optional[bool],
             from_: Optional[Relationship],
             to: Optional[Relationship],
@@ -1076,13 +1079,15 @@ class Graph():
         Validate the domain constraint parameters for methods that accept
         `full`, `from_`, `to`, and `between` parameters.
 
-        This helper method performs common validation logic that applies
-        across multiple graph methods (e.g., common_neighbor, adamic_adar).
-
         Parameters
         ----------
         method_name : str
             The name of the method being validated (for error messages).
+        symmetric : bool
+            Whether the relationship is symmetric in its first two positions.
+            If True, enforces that 'to' can only be used with 'from_' (since
+            'to' alone would be redundant for symmetric relations).
+            If False, allows 'to' without 'from_' (for asymmetric relations).
         full : bool, optional
             The full parameter value.
         from_ : Relationship, optional
@@ -1127,8 +1132,9 @@ class Graph():
                 "or use 'from_'/'to' to constrain by position."
             )
 
-        # Confirm that 'to' is only used with 'from_'.
-        if to is not None and from_ is None:
+        # Confirm that 'to' is only used with 'from_' for symmetric relations.
+        # For asymmetric relations, 'to' without 'from_' is meaningful.
+        if symmetric and to is not None and from_ is None:
             raise ValueError(
                 "The 'to' parameter can only be used together with the 'from_' parameter. "
                 f"The 'from_' parameter constrains the first position in {method_name} tuples, "
@@ -1142,6 +1148,7 @@ class Graph():
         if (
             full is None and
             from_ is None and
+            to is None and
             between is None
         ):
             raise ValueError(
@@ -2171,9 +2178,10 @@ class Graph():
         1   2    4    3
 
         """
-        # Validate domain constraint parameters.
+        # Validate domain constraint parameters (common_neighbor is symmetric).
+        symmetric = True
         self._validate_domain_constraint_parameters(
-            'common_neighbor', full, from_, to, between
+            'common_neighbor', symmetric, full, from_, to, between
         )
 
         # At this point, exactly one of `full`, `from_`, or `between`
@@ -4941,6 +4949,11 @@ class Graph():
     def reachable_from(self):
         """Returns a binary relationship of all pairs of nodes (u, v) where v is reachable from u.
 
+        .. deprecated::
+            The ``reachable_from`` method is deprecated and will be removed in a
+            future release. Please use :meth:`reachable` instead, which provides
+            the same functionality with additional domain constraint options.
+
         A node `v` is considered reachable from a node `u` if there is a path
         of edges from `u` to `v`.
 
@@ -5043,35 +5056,370 @@ class Graph():
         7   3    2
         8   3    3
 
+        See Also
+        --------
+        reachable
 
         """
         warnings.warn(
-            (
-                "`reachable_from` presently always computes the full transitive closure "
-                "of the graph. To provide better control over the computed subset, "
-                "`reachable_from`'s interface will soon need to change."
-            ),
-            FutureWarning,
+            "The 'reachable_from' method is deprecated and will be removed in a future release. "
+            "Please use 'reachable' instead.",
+            DeprecationWarning,
             stacklevel=2
         )
-        return self._reachable_from
+        return self.reachable(full=True)
+
+
+    @include_in_docs
+    def reachable(
+        self,
+        *,
+        full: Optional[bool] = None,
+        from_: Optional[Relationship] = None,
+        to: Optional[Relationship] = None,
+        between: Optional[Relationship] = None,
+    ):
+        """Returns a binary relationship of pairs of nodes (u, v) where v is reachable from u.
+
+        A node `v` is considered reachable from a node `u` if there is a path
+        of edges from `u` to `v`.
+
+        Parameters
+        ----------
+        full : bool, optional
+            If ``True``, computes reachability for all pairs of nodes in the graph.
+            This computation can be expensive for large graphs. Must be set to
+            ``True`` to compute the full reachable relationship. Cannot be used
+            with other parameters.
+        from_ : Relationship, optional
+            A unary relationship containing a subset of the graph's nodes. When
+            provided, constrains the first position of the reachable
+            computation: only reachability from nodes in this relationship are
+            returned. Cannot be used with other parameters.
+        to : Relationship, optional
+            A unary relationship containing a subset of the graph's nodes. When
+            provided, constrains the second position of the reachable
+            computation: only reachability to nodes in this relationship are
+            returned. Cannot be used with other parameters.
+        between : Relationship, optional
+            Not yet supported for reachable. If provided, raises an error. If you
+            need this capability, please reach out.
+
+        Returns
+        -------
+        Relationship
+            A binary relationship where each tuple represents a node and a
+            node that is reachable from it.
+
+        Relationship Schema
+        -------------------
+        ``reachable(from_node, to_node)``
+
+        * **from_node** (*Node*): The node from which the path originates.
+        * **to_node** (*Node*): The node that is reachable from the first node.
+
+        Supported Graph Types
+        ---------------------
+        | Graph Type | Supported | Notes                |
+        | :--------- | :-------- | :------------------- |
+        | Undirected | Yes       |                      |
+        | Directed   | Yes       |                      |
+        | Weighted   | Yes       | Weights are ignored. |
+
+        Notes
+        -----
+        The ``reachable(full=True)`` method computes and caches the full
+        reachable relationship, providing efficient reuse across multiple calls. In
+        contrast, ``reachable(from_=subset)`` or ``reachable(to=subset)``
+        compute constrained relationships specific to the passed-in subset and call
+        site. When a significant fraction of the reachable relation is needed,
+        ``reachable(full=True)`` is typically more efficient. Use constrained
+        variants only when small subsets are needed.
+
+        In directed graphs, the ``reachable`` relationship is asymmetric: node B
+        may be reachable from node A without node A being reachable from node B. This
+        asymmetry means that ``from_`` and ``to`` parameters have distinct,
+        non-interchangeable meanings.
+
+        **Important:** Simultaneous use of ``from_`` and ``to`` parameters is not
+        yet supported. The ``between`` parameter is also not yet supported. If
+        you need these capabilities, please reach out.
+
+        There is a slight difference between `transitive closure` and
+        `reachable`. The transitive closure of a binary relation E is the
+        smallest relation that contains E and is transitive. When E is the
+        edge set of a graph, the transitive closure of E does not include
+        (u, u) if u is isolated. `reachable` is a different binary
+        relation in which any node u is always reachable from u. In
+        particular, `transitive closure` is a more general concept than
+        `reachable`.
+
+        Examples
+        --------
+        **Directed Graph Example**
+
+        >>> from relationalai.semantics import Model, define, select
+        >>> from relationalai.semantics.reasoners.graph import Graph
+        >>>
+        >>> # 1. Set up a directed graph
+        >>> model = Model("test_model")
+        >>> graph = Graph(model, directed=True, weighted=False)
+        >>> Node, Edge = graph.Node, graph.Edge
+        >>>
+        >>> # 2. Define nodes and edges
+        >>> n1, n2, n3 = [Node.new(id=i) for i in range(1, 4)]
+        >>> define(n1, n2, n3)
+        >>> define(
+        ...     Edge.new(src=n1, dst=n2),
+        ...     Edge.new(src=n3, dst=n2),
+        ... )
+        >>>
+        >>> # 3. Select all reachable pairs and inspect
+        >>> from_node, to_node = Node.ref("start"), Node.ref("end")
+        >>> reachable = graph.reachable(full=True)
+        >>> select(from_node.id, to_node.id).where(reachable(from_node, to_node)).inspect()
+        ▰▰▰▰ Setup complete
+           id  id2
+        0   1    1
+        1   1    2
+        2   2    2
+        3   3    2
+        4   3    3
+
+        >>> # 4. Use 'from_' parameter to get reachability from specific nodes
+        >>> # Define a subset containing nodes 1 and 3
+        >>> from relationalai.semantics import union, where
+        >>> subset = model.Relationship(f"{{node:{Node}}} is in from subset")
+        >>> node = Node.ref()
+        >>> where(union(node.id == 1, node.id == 3)).define(subset(node))
+        >>>
+        >>> # Get reachability from nodes in the subset to all other nodes
+        >>> reachable_from = graph.reachable(from_=subset)
+        >>> select(from_node.id, to_node.id).where(
+        ...     reachable_from(from_node, to_node)
+        ... ).inspect()
+        ▰▰▰▰ Setup complete
+           id  id2
+        0   1    1
+        1   1    2
+        2   3    2
+        3   3    3
+
+        >>> # 5. Use 'to' parameter to get reachability to specific nodes
+        >>> # Define a different subset containing node 2
+        >>> to_subset = model.Relationship(f"{{node:{Node}}} is in to subset")
+        >>> node = Node.ref()
+        >>> where(node.id == 2).define(to_subset(node))
+        >>>
+        >>> # Get reachability from all nodes to node 2
+        >>> reachable_to = graph.reachable(to=to_subset)
+        >>> select(from_node.id, to_node.id).where(
+        ...     reachable_to(from_node, to_node)
+        ... ).inspect()
+        ▰▰▰▰ Setup complete
+           id  id2
+        0   1    2
+        1   2    2
+        2   3    2
+
+
+        **Undirected Graph Example**
+
+        >>> from relationalai.semantics import Model, define, select
+        >>> from relationalai.semantics.reasoners.graph import Graph
+        >>>
+        >>> # 1. Set up an undirected graph
+        >>> model = Model("test_model")
+        >>> graph = Graph(model, directed=False, weighted=False)
+        >>> Node, Edge = graph.Node, graph.Edge
+        >>>
+        >>> # 2. Define the same nodes and edges
+        >>> n1, n2, n3 = [Node.new(id=i) for i in range(1, 4)]
+        >>> define(n1, n2, n3)
+        >>> define(
+        ...     Edge.new(src=n1, dst=n2),
+        ...     Edge.new(src=n3, dst=n2),
+        ... )
+        >>>
+        >>> # 3. Select all reachable pairs and inspect
+        >>> from_node, to_node = Node.ref("start"), Node.ref("end")
+        >>> reachable = graph.reachable(full=True)
+        >>> select(from_node.id, to_node.id).where(reachable(from_node, to_node)).inspect()
+        ▰▰▰▰ Setup complete
+           id  id2
+        0   1    1
+        1   1    2
+        2   1    3
+        3   2    1
+        4   2    2
+        5   2    3
+        6   3    1
+        7   3    2
+        8   3    3
+
+        """
+        # Validate domain constraint parameters (reachable is asymmetric).
+        symmetric = False
+        self._validate_domain_constraint_parameters(
+            'reachable', symmetric, full, from_, to, between
+        )
+
+        # Reachable-specific validation: between is not yet supported.
+        if between is not None:
+            raise ValueError(
+                "The 'between' parameter is not yet supported for reachable. "
+                "Use 'full=True' for all-pairs reachability, or 'from_'/'to' to "
+                "constrain by position. If you need 'between' support for reachable, "
+                "please reach out."
+            )
+
+        # Reachable-specific validation: from_+to combination is not yet supported.
+        if from_ is not None and to is not None:
+            raise ValueError(
+                "Simultaneous use of 'from_' and 'to' is not yet supported for reachable. "
+                "Use 'from_=subset' to constrain start nodes, 'to=subset' to constrain "
+                "end nodes, or 'full=True' for all pairs. If you need the 'from_' and 'to' "
+                "combination for reachable, please reach out."
+            )
+
+        # At this point, exactly one of `full`, `from_`, or `to` has been provided.
+
+        if full is not None:
+            return self._reachable
+
+        if from_ is not None:
+            self._validate_node_subset_parameter('from_', from_)
+            return self._reachable_from(from_)
+
+        if to is not None:
+            self._validate_node_subset_parameter('to', to)
+            return self._reachable_to(to)
 
     @cached_property
-    def _reachable_from(self):
-        """Lazily define and cache the self._reachable_from relationship."""
-        _reachable_from_rel = self._model.Relationship(f"{{node_a:{self._NodeConceptStr}}} reaches {{node_b:{self._NodeConceptStr}}}")
-        _reachable_from_rel.annotate(annotations.track("graphs", "reachable_from"))
+    def _reachable(self):
+        """Lazily define and cache the self._reachable relationship."""
+        _reachable_rel = self._create_reachable_relationship()
+        _reachable_rel.annotate(annotations.track("graphs", "reachable"))
+        return _reachable_rel
+
+    def _reachable_from(self, node_subset_from: Relationship):
+        """
+        Create a reachable relationship with the first position constrained to
+        nodes in `node_subset_from`. This computes reachability from nodes in
+        the subset to all other nodes. Note this relationship
+        is not cached; it is specific to the callsite.
+        """
+        _reachable_rel = self._create_reachable_relationship(
+            node_subset_from=node_subset_from,
+        )
+        _reachable_rel.annotate(annotations.track("graphs", "reachable_from"))
+        return _reachable_rel
 
+    def _reachable_to(self, node_subset_to: Relationship):
+        """
+        Create a reachable relationship with the second position constrained to
+        nodes in `node_subset_to`. This computes reachability from all nodes to
+        nodes in the subset. Note this relationship
+        is not cached; it is specific to the callsite.
+        """
+        _reachable_rel = self._create_reachable_relationship(
+            node_subset_to=node_subset_to
+        )
+        _reachable_rel.annotate(annotations.track("graphs", "reachable_to"))
+        return _reachable_rel
+
+    def _create_reachable_relationship(
+        self,
+        *,
+        node_subset_from: Optional[Relationship] = None,
+        node_subset_to: Optional[Relationship] = None,
+    ):
+        """
+        Create a reachable relationship, optionally constrained to node subsets.
+
+        Parameters
+        ----------
+        node_subset_from : Relationship or None
+            If provided, constrains the first position to this subset.
+        node_subset_to : Relationship or None
+            If provided, constrains the second position to this subset.
+
+        Returns
+        -------
+        Relationship
+            A binary relationship mapping (from_node, to_node).
+        """
+        # NOTE: In the constrained cases, we must compute over the full reach
+        #   {from xor to}, depending on the constraint, the nodes in the provided subset,
+        #   and _only_ over that reach.
+
+        # A reach relation over the reach {from xor to} the nodes in the subset.
+        _reachable_rel = self._model.Relationship(
+            f"{{node_a:{self._NodeConceptStr}}} reaches {{node_b:{self._NodeConceptStr}}}"
+        )
+
+        # The logic below computes the reach by repeatedly extending
+        # known reachability to neighbors; this snippet drives that,
+        # with propagation direction depending on the constraint mode.
         node_a, node_b, node_c = self.Node.ref(), self.Node.ref(), self.Node.ref()
-        define(_reachable_from_rel(node_a, node_a))
-        define(_reachable_from_rel(node_a, node_c)).where(_reachable_from_rel(node_a, node_b), self._edge(node_b, node_c))
+        if node_subset_to is None:
+            # Either of `full` or `from_` modes; propagate reach forward for both.
+            # (`full` mode uses forward propagation as it may be slightly more efficient,
+            # though backward propagation also works in principle.)
+            extension_rule = where(
+                _reachable_rel(node_a, node_b),
+                self._edge(node_b, node_c),
+            ).select(node_a, node_c)
+        else:
+            # `to` mode; propagate reach backward.
+            extension_rule = where(
+                _reachable_rel(node_b, node_c),
+                self._edge(node_a, node_b),
+            ).select(node_a, node_c)
+            # NOTE: The optimizer may generate an index on _edge for the above;
+            #   it may be best to use a cached reversed edge relationship instead,
+            #   given it's useful elsewhere and that may yield reuse (and more reliably
+            #   good query plans, possibly).
+
+        # The set of nodes from which to propagate reach.
+        node = self.Node.ref() # node is used (coupled) below.
+        # Binding origin_nodes_constraint unconditionally for
+        # the unconstrained case and then overriding if necessary
+        # appeases the type checker, which otherwise thinks
+        # it may be unbound below.
+        origin_nodes_constraint = node
+        if node_subset_from is not None:
+            origin_nodes_constraint = node_subset_from(node)
+        elif node_subset_to is not None:
+            origin_nodes_constraint = node_subset_to(node)
+
+        # Generate union of reach implications between node_x and node_y:
+        node_x, node_y = union(
+            # A node is always reachable from itself.
+            where(origin_nodes_constraint).select(node, node),
+            # Reachability can be extended to neighbors.
+            # (Note that this part of the rule also drives the reach.)
+            extension_rule,
+        )
+        # Define the reach relation recursively.
+        define(
+            _reachable_rel(node_x, node_y)
+        )
 
-        return _reachable_from_rel
+        return _reachable_rel
 
 
     @include_in_docs
-    def distance(self):
-        """Returns a ternary relationship containing the shortest path length between all pairs of nodes.
+    def distance(
+        self,
+        *,
+        full: Optional[bool] = None,
+        from_: Optional[Relationship] = None,
+        to: Optional[Relationship] = None,
+        between: Optional[Relationship] = None,
+    ):
+        """Returns a ternary relationship containing
+        the shortest path length between pairs of nodes.
 
         This method computes the shortest path length between all pairs of
         reachable nodes. The calculation depends on whether the graph is
@@ -5082,6 +5430,27 @@ class Graph():
         * For **weighted** graphs, the length is the sum of edge weights
             along the shortest path. Edge weights are assumed to be non-negative.
 
+        Parameters
+        ----------
+        full : bool, optional
+            If ``True``, computes distances for all pairs of nodes in the graph.
+            This computation can be expensive for large graphs. Must be set to
+            ``True`` to compute the full distance relationship. Cannot be used
+            with other parameters.
+        from_ : Relationship, optional
+            A unary relationship containing a subset of the graph's nodes. When
+            provided, constrains the first position (start_node) of the distance
+            computation: only distances from nodes in this relationship are
+            returned. Cannot be used with other parameters.
+        to : Relationship, optional
+            A unary relationship containing a subset of the graph's nodes. When
+            provided, constrains the second position (end_node) of the distance
+            computation: only distances to nodes in this relationship are
+            returned. Cannot be used with other parameters.
+        between : Relationship, optional
+            Not yet supported for distance. If provided, raises an error. If you
+            need this capability, please reach out.
+
         Returns
         -------
         Relationship
@@ -5105,11 +5474,30 @@ class Graph():
         | Directed   | Yes       |                                            |
         | Weighted   | Yes       | The calculation uses edge weights.         |
 
+        Notes
+        -----
+        The ``distance(full=True)`` method computes and caches the full distance
+        relationship, providing efficient reuse across multiple calls. In contrast,
+        ``distance(from_=subset)`` or ``distance(to=subset)`` compute constrained
+        relationships specific to the passed-in subset and call site. When a
+        significant fraction of the distance relation is needed, ``distance(full=True)``
+        is typically more efficient. Use constrained variants only when small
+        subsets are needed.
+
+        In directed graphs, the ``distance`` relationship is asymmetric: the
+        distance from node A to node B may differ from the distance from node B
+        to node A. This asymmetry means that ``from_`` and ``to`` parameters
+        have distinct, non-interchangeable meanings.
+
+        **Important:** Simultaneous use of ``from_`` and ``to`` parameters is not
+        yet supported. The ``between`` parameter is also not yet supported. If
+        you need these capabilities, please reach out.
+
         Examples
         --------
         **Unweighted Graph Example**
 
-        >>> from relationalai.semantics import Model, define, select, Integer
+        >>> from relationalai.semantics import Model, define, select, union, where, Integer
         >>> from relationalai.semantics.reasoners.graph import Graph
         >>>
         >>> # 1. Set up an unweighted, undirected graph
@@ -5130,8 +5518,8 @@ class Graph():
         >>> # 3. Select the shortest path length between all pairs of nodes
         >>> start, end = Node.ref("start"), Node.ref("end")
         >>> length = Integer.ref("length")
-        >>> distance = graph.distance()
-        >>> select(start.id, end.id, length).where(distance(start, end, length)).inspect()
+        >>> dist = graph.distance(full=True)
+        >>> select(start.id, end.id, length).where(dist(start, end, length)).inspect()
         ▰▰▰▰ Setup complete
             id  id2  length
         0    1    1       0
@@ -5151,6 +5539,46 @@ class Graph():
         14   4    3       2
         15   4    4       0
 
+        >>> # 4. Use 'from_' parameter to get distances from specific nodes
+        >>> # Define a subset containing nodes 1 and 3
+        >>> subset = model.Relationship(f"{{node:{Node}}} is in from subset")
+        >>> node = Node.ref()
+        >>> where(union(node.id == 1, node.id == 3)).define(subset(node))
+        >>>
+        >>> # Get distances from nodes in the subset to all other nodes
+        >>> dist_from = graph.distance(from_=subset)
+        >>> select(start.id, end.id, length).where(
+        ...     dist_from(start, end, length)
+        ... ).inspect()
+        ▰▰▰▰ Setup complete
+            id  id2  length
+        0    1    1       0
+        1    1    2       1
+        2    1    3       2
+        3    1    4       2
+        4    3    1       2
+        5    3    2       1
+        6    3    3       0
+        7    3    4       2
+
+        >>> # 5. Use 'to' parameter to get distances to specific nodes
+        >>> # Define a different subset containing node 4
+        >>> to_subset = model.Relationship(f"{{node:{Node}}} is in to subset")
+        >>> node = Node.ref()
+        >>> where(node.id == 4).define(to_subset(node))
+        >>>
+        >>> # Get distances from all nodes to node 4
+        >>> dist_to = graph.distance(to=to_subset)
+        >>> select(start.id, end.id, length).where(
+        ...     dist_to(start, end, length)
+        ... ).inspect()
+        ▰▰▰▰ Setup complete
+            id  id2  length
+        0    1    4       2
+        1    2    4       1
+        2    3    4       2
+        3    4    4       0
+
 
         **Weighted Graph Example**
 
@@ -5174,8 +5602,8 @@ class Graph():
         >>> # 3. Select the shortest path length between all pairs of nodes
         >>> start, end = Node.ref("start"), Node.ref("end")
         >>> length = Float.ref("length")
-        >>> distance = graph.distance()
-        >>> select(start.id, end.id, length).where(distance(start, end, length)).inspect()
+        >>> dist = graph.distance(full=True)
+        >>> select(start.id, end.id, length).where(dist(start, end, length)).inspect()
         ▰▰▰▰ Setup complete
            id  id2  length
         0   1    1     0.0
@@ -5187,75 +5615,190 @@ class Graph():
         6   3    3     0.0
 
         """
-        warnings.warn(
-            (
-                "`distance` presently always computes all-to-all distances "
-                "of the graph. To provide better control over the computed subset, "
-                "`distance`'s interface will soon need to change."
-            ),
-            FutureWarning,
-            stacklevel=2
+        # Validate domain constraint parameters (distance is asymmetric).
+        symmetric = False
+        self._validate_domain_constraint_parameters(
+            'distance', symmetric, full, from_, to, between
         )
 
-        return self._distance
+        # Distance-specific validation: between is not yet supported.
+        if between is not None:
+            raise ValueError(
+                "The 'between' parameter is not yet supported for distance. "
+                "Use 'full=True' for all-pairs distances, or 'from_'/'to' to "
+                "constrain by position. If you need 'between' support for distance, "
+                "please reach out."
+            )
+
+        # Distance-specific validation: from_+to combination is not yet supported.
+        if from_ is not None and to is not None:
+            raise ValueError(
+                "Simultaneous use of 'from_' and 'to' is not yet supported for distance. "
+                "Use 'from_=subset' to constrain start nodes, 'to=subset' to constrain "
+                "end nodes, or 'full=True' for all pairs. If you need the 'from_' and 'to' "
+                "combination for distance, please reach out."
+            )
+
+        # At this point, exactly one of `full`, `from_`, or `to` has been provided.
+
+        if full is not None:
+            return self._distance
+
+        if from_ is not None:
+            self._validate_node_subset_parameter('from_', from_)
+            return self._distance_from(from_)
+
+        if to is not None:
+            self._validate_node_subset_parameter('to', to)
+            return self._distance_to(to)
 
     @cached_property
     def _distance(self):
         """Lazily define and cache the self._distance relationship."""
-        if not self.weighted:
-            _distance_rel = self._distance_non_weighted
-        else:
-            _distance_rel = self._distance_weighted
-
+        _distance_rel = self._create_distance_relationship()
         _distance_rel.annotate(annotations.track("graphs", "distance"))
         return _distance_rel
 
-    @cached_property
-    def _distance_weighted(self):
-        """Lazily define and cache the self._distance_weighted relationship, a non-public helper."""
-        _distance_weighted_rel = self._model.Relationship(f"{{node_u:{self._NodeConceptStr}}} and {{node_v:{self._NodeConceptStr}}} have a distance of {{d:Float}}")
-        node_u, node_v, node_n, w, d1 = self.Node.ref(), self.Node.ref(),\
-            self.Node.ref(), Float.ref(), Float.ref()
-        node_u, node_v, d = union(
-            where(node_u == node_v, d1 == 0.0).select(node_u, node_v, d1), # Base case.
-            where(self._weight(node_n, node_v, w), d2 := _distance_weighted_rel(node_u, node_n, Float) + abs(w))\
-            .select(node_u, node_v, d2) # Recursive case.
+    def _distance_from(self, node_subset_from: Relationship):
+        """
+        Create a distance relationship with the first position constrained to
+        nodes in `node_subset_from`. This computes distances from nodes in
+        the subset to all other nodes. Note this relationship
+        is not cached; it is specific to the callsite.
+        """
+        _distance_rel = self._create_distance_relationship(
+            node_subset_from=node_subset_from,
         )
-        define(_distance_weighted_rel(node_u, node_v, min(d).per(node_u, node_v)))
-
-        return _distance_weighted_rel
+        _distance_rel.annotate(annotations.track("graphs", "distance_from"))
+        return _distance_rel
 
-    @cached_property
-    def _distance_non_weighted(self):
-        """Lazily define and cache the self._distance_non_weighted relationship, a non-public helper."""
-        _distance_non_weighted_rel = self._model.Relationship(f"{{node_u:{self._NodeConceptStr}}} and {{node_v:{self._NodeConceptStr}}} have a distance of {{d:Integer}}")
-        node_u, node_v, node_n, d1 = self.Node.ref(), self.Node.ref(), self.Node.ref(), Integer.ref()
-        node_u, node_v, d = union(
-            where(node_u == node_v, d1 == 0).select(node_u, node_v, d1), # Base case.
-            where(self._edge(node_n, node_v),
-                  d2 := _distance_non_weighted_rel(node_u, node_n, Integer) + 1).select(node_u, node_v, d2) # Recursive case.
+    def _distance_to(self, node_subset_to: Relationship):
+        """
+        Create a distance relationship with the second position constrained to
+        nodes in `node_subset_to`. This computes distances from all nodes to
+        nodes in the subset. Note this relationship
+        is not cached; it is specific to the callsite.
+        """
+        _distance_rel = self._create_distance_relationship(
+            node_subset_to=node_subset_to
         )
-        define(_distance_non_weighted_rel(node_u, node_v, min(d).per(node_u, node_v)))
+        _distance_rel.annotate(annotations.track("graphs", "distance_to"))
+        return _distance_rel
 
-        return _distance_non_weighted_rel
+    def _create_distance_relationship(
+        self,
+        *,
+        node_subset_from: Optional[Relationship] = None,
+        node_subset_to: Optional[Relationship] = None,
+        weighted: Optional[bool] = None,
+    ):
+        """
+        Create a distance relationship, weighted or unweighted per the graph,
+        and optionally constrained to node subsets.
 
-    @cached_property
-    def _distance_reversed_non_weighted(self):
-        """Lazily define and cache the self._distance_reversed_non_weighted relationship, a non-public helper."""
-        _distance_reversed_non_weighted_rel = self._model.Relationship(f"{{node_u:{self._NodeConceptStr}}} and {{node_v:{self._NodeConceptStr}}} have a reversed distance of {{d:Integer}}")
-        node_u, node_v, node_n, d1 = self.Node.ref(), self.Node.ref(), self.Node.ref(), Integer.ref()
-        node_u, node_v, d = union(
-            where(node_u == node_v, d1 == 0).select(node_u, node_v, d1), # Base case.
-            where(self._edge(node_v, node_n),
-                  d2 := _distance_reversed_non_weighted_rel(node_u, node_n, Integer) + 1).select(node_u, node_v, d2) # Recursive case.
+        Parameters
+        ----------
+        node_subset_from : Relationship or None
+            If provided, constrains the first position to this subset.
+        node_subset_to : Relationship or None
+            If provided, constrains the second position to this subset.
+
+        Returns
+        -------
+        Relationship
+            A ternary relationship mapping (from_node, to_node, distance).
+        """
+        # NOTE: In the constrained cases, we must compute over the full reach
+        #   from xor to (depending on the constraint) the nodes in the provided subset,
+        #   and _only_ over that reach. To do so, the logic below simultaneously
+        #   computes the appropriate reach of the nodes in the provided subset
+        #   (in `_distance_reach_rel`) while computing distances.
+
+        if weighted is None:
+            weighted = self.weighted
+
+        dist_type = Float if weighted else Integer
+
+        # A distance relation over the appropriate reach of the nodes in the subset.
+        _distance_reach_rel = self._model.Relationship(
+            f"{{node_u:{self._NodeConceptStr}}} and {{node_v:{self._NodeConceptStr}}} have a distance of {{d:{dist_type}}}"
         )
-        define(_distance_reversed_non_weighted_rel(node_u, node_v, min(d).per(node_u, node_v)))
 
-        return _distance_reversed_non_weighted_rel
+        # The logic below computes the reach and distances by repeatedly extending
+        # known distances to neighbors; this snippet drives that, with propagation
+        # direction depending on the constraint mode.
+        node_u, node_v, neighbor = self.Node.ref(), self.Node.ref(), self.Node.ref()
+        uv_dist, step_dist, neighbor_dist = dist_type.ref(), dist_type.ref(), dist_type.ref()
+        if node_subset_to is None:
+            # Either of `full` or `from` modes; propagate reach forward for both.
+            # (`full` mode uses forward propagation as it may be slightly more efficient,
+            # though backward propagation also works in principle.)
+            extension_rule = where(
+                _distance_reach_rel(node_u, node_v, uv_dist),
+                *(
+                    (
+                        self._weight(node_v, neighbor, step_dist),
+                        neighbor_dist == uv_dist + abs(step_dist),
+                    )
+                    if weighted else
+                    (
+                        self._edge(node_v, neighbor),
+                        neighbor_dist == uv_dist + 1,
+                    )
+                ),
+            ).select(node_u, neighbor, neighbor_dist)
+        else:
+            # `to` mode; propagate reach backward.
+            extension_rule = where(
+                _distance_reach_rel(node_u, node_v, uv_dist),
+                *(
+                    (
+                        self._weight(neighbor, node_u, step_dist),
+                        neighbor_dist == uv_dist + abs(step_dist),
+                    )
+                    if weighted else
+                    (
+                        self._edge(neighbor, node_u),
+                        neighbor_dist == uv_dist + 1,
+                    )
+                ),
+            ).select(neighbor, node_v, neighbor_dist)
+            # NOTE: The optimizer may generate an index on _edge for the above;
+            #   it may be best to use a cached reversed edge/weight relationship instead,
+            #   given it's useful elsewhere and that may yield reuse (and more reliably
+            #   good query plans, possibly).
+
+        # The set of nodes from which to propagate reach and distances.
+        node = self.Node.ref() # node is used (coupled) below.
+        # Binding origin_nodes_constraint unconditionally for
+        # the unconstrained case and then overriding if necessary
+        # appeases the type checker, which otherwise thinks
+        # it may be unbound below.
+        origin_nodes_constraint = node
+        if node_subset_from is not None:
+            origin_nodes_constraint = node_subset_from(node)
+        elif node_subset_to is not None:
+            origin_nodes_constraint = node_subset_to(node)
+
+        # Generate union of possible distances between node_a and node_b:
+        node_a, node_b, ab_dist = union(
+            # The distance from a node to itself is zero.
+            where(origin_nodes_constraint).select(node, node, 0),
+            # The distance from one node to another can be extended to its neighbors.
+            # (Note that this part of the rule also drives the reach.)
+            extension_rule,
+        )
+        # From the union of possible distances between node_a and node_b,
+        # select the minimum as the distance.
+        define(
+            _distance_reach_rel(node_a, node_b, min(ab_dist).per(node_a, node_b))
+        )
+
+        return _distance_reach_rel
 
 
     @include_in_docs
-    def weakly_connected_component(self):
+    def weakly_connected_component(self, *, of: Optional[Relationship] = None):
         """Returns a binary relationship that maps each node to its weakly connected component.
 
         A weakly connected component is a subgraph where for every pair of
@@ -5263,6 +5806,14 @@ class Graph():
         For undirected graphs, this is equivalent to finding the connected
         components.
 
+        Parameters
+        ----------
+        of : Relationship, optional
+            A unary relationship containing a subset of the graph's nodes. When
+            provided, constrains the domain of the weakly connected component
+            computation: only component memberships of nodes in this relationship
+            are returned.
+
         Returns
         -------
         Relationship
@@ -5289,9 +5840,26 @@ class Graph():
         The ``component_id`` is the node with the minimum ID within each
         component.
 
+        The ``weakly_connected_component()`` method, called with no parameters,
+        computes and caches the full weakly connected component relationship,
+        providing efficient reuse across multiple calls to
+        ``weakly_connected_component()``.
+
+        In contrast, ``weakly_connected_component(of=subset)`` computes a constrained
+        relationship specific to the passed-in ``subset`` and that call site.
+
+        Note that the constrained computation requires working over all nodes
+        in the components containing the nodes in ``subset``. When that set
+        of nodes constitutes an appreciable fraction of the graph, the constrained
+        computation may be less efficient than computing the full relationship.
+        Use ``weakly_connected_component(of=subset)`` only when small subsets of
+        the weakly connected component relationship are needed collectively
+        across the program, and the associated components cover only a small
+        part of the graph.
+
         Examples
         --------
-        >>> from relationalai.semantics import Model, define, select
+        >>> from relationalai.semantics import Model, define, select, union, where
         >>> from relationalai.semantics.reasoners.graph import Graph
         >>>
         >>> # 1. Set up a directed graph
@@ -5317,36 +5885,141 @@ class Graph():
         1   2    1
         2   3    1
 
-        """
-        warnings.warn(
-            (
-                "`weakly_connected_component` presently always computes the component "
-                "for every node of the graph. To provide better control over the computed subset, "
-                "`weakly_connected_component`'s interface will soon need to change."
-            ),
-            FutureWarning,
-            stacklevel=2
-        )
+        >>> # 4. Use 'of' parameter to constrain computation to subset of nodes
+        >>> # Define a subset containing only nodes 1 and 3
+        >>> subset = model.Relationship(f"{{node:{Node}}} is in subset")
+        >>> node = Node.ref()
+        >>> where(union(node.id == 1, node.id == 3)).define(subset(node))
+        >>>
+        >>> # Get component membership only for nodes in the subset
+        >>> constrained_wcc = graph.weakly_connected_component(of=subset)
+        >>> select(node.id, component_id.id).where(
+        ...     constrained_wcc(node, component_id)
+        ... ).inspect()
+        ▰▰▰▰ Setup complete
+           id  id2
+        0   1    1
+        1   3    1
 
-        return self._weakly_connected_component
+        """
+        if of is None:
+            return self._weakly_connected_component
+        else:
+            # Validate the 'of' parameter
+            self._validate_node_subset_parameter('of', of)
+            return self._weakly_connected_component_of(of)
 
     @cached_property
     def _weakly_connected_component(self):
         """Lazily define and cache the self._weakly_connected_component relationship."""
-        _weakly_connected_component_rel = self._model.Relationship(f"{{node:{self._NodeConceptStr}}} is in the connected component {{id:{self._NodeConceptStr}}}")
+        _weakly_connected_component_rel = self._create_weakly_connected_component_relationship(
+            node_subset=None
+        )
         _weakly_connected_component_rel.annotate(annotations.track("graphs", "weakly_connected_component"))
+        return _weakly_connected_component_rel
 
-        node, node_v, component = self.Node.ref(), self.Node.ref(), self.Node.ref()
-        node, component = union(
-            # A node starts with itself as the component id.
-            where(node == component).select(node, component),
-            # Recursive case.
-            where(_weakly_connected_component_rel(node, component), self._neighbor(node, node_v)).select(node_v, component)
+    def _weakly_connected_component_of(self, node_subset: Relationship):
+        """
+        Create a weakly_connected_component relationship constrained to the
+        subset of nodes in `node_subset`. Note this relationship is not cached;
+        it is specific to the callsite.
+        """
+        _weakly_connected_component_rel = self._create_weakly_connected_component_relationship(
+            node_subset=node_subset
         )
-        define(_weakly_connected_component_rel(node, min(component).per(node)))
-
+        _weakly_connected_component_rel.annotate(annotations.track("graphs", "weakly_connected_component_of"))
         return _weakly_connected_component_rel
 
+    def _create_weakly_connected_component_relationship(
+            self, *, node_subset: Optional[Relationship]
+        ):
+        """
+        Create a weakly_connected_component relationship, optionally constrained
+        to a subset of nodes.
+
+        Parameters
+        ----------
+        node_subset : Relationship or None
+            If provided, a unary relationship defining the subset of nodes to
+            compute component membership for. If None, compute for all nodes.
+
+        Returns
+        -------
+        Relationship
+            A binary relationship mapping nodes to their weakly connected component IDs.
+        """
+        # NOTE: In the constrained case, we must compute over the full of
+        #   the weakly connected components containing the nodes in the
+        #   provided subset, and _only_ over those weakly connected components.
+        #   To do so, the logic below simultaneously computes the (weak) reach from
+        #   the nodes in the provided subset (in `_weakly_connected_component_reach_rel``)
+        #   while computing component membership.
+
+        # A weakly connected component relation over
+        # those components reachable from the nodes in the subset.
+        _weakly_connected_component_reach_rel = self._model.Relationship(
+            f"{{node:{self._NodeConceptStr}}} is in the connected component {{id:{self._NodeConceptStr}}}"
+        )
+
+        node, neighbor, component, dummy = \
+            self.Node.ref(), self.Node.ref(), self.Node.ref(), self.Node.ref()
+
+        # `discovered_nodes` reflects the (weak) reach from the nodes in the provided
+        # subset known at a given point in the recursion. In the unconstrained
+        # case, the subset is implicitly the set of all nodes, and starting with
+        # all such nodes "discovered" accelerates the computation.
+        if node_subset is None:
+            discovered_nodes = node
+        else:
+            discovered_nodes = union(
+                node_subset(node),
+                _weakly_connected_component_reach_rel(node, dummy)
+            )
+
+        where(
+            # Generate union of possible component identifiers for a given node:
+            union(
+                # A node's component identifier may be itself.
+                where(discovered_nodes, component == node),
+                # A node's component identifier may be those of its neighbors.
+                # (Note that this part of the rule also drives the (weak) reach.)
+                where(
+                    self._neighbor(neighbor, node),
+                    _weakly_connected_component_reach_rel(neighbor, component)
+                )
+            )
+        ).define(
+            # From the union of possible component identifiers for a given node,
+            # select the minimum as the component identifier.
+            _weakly_connected_component_reach_rel(node, min(component).per(node))
+        )
+        # NOTE: This logic, including in the constrained case, consumes
+        #   the (unconstrained, cached) self._neighbor relation, which is
+        #   ~O(nodes) to compute. Note that this seems to be about the best we can do:
+        #   To compute the (weak) reach, we either need: a) the edge relation, and
+        #   O(nodes) scans over the edge relation; b) the edge relation and
+        #   reverse edge relation, forming which is O(nodes); or c) the neighbor
+        #   relation over all nodes in the (weak) reach, computing which requires
+        #   one of (a) or (b) above. Given that, for simplicity here we use (c),
+        #   as there's a reasonable likelihood of re-/shared-use.
+
+        if node_subset is None:
+            # The reach relation from all nodes is the full relation.
+            return _weakly_connected_component_reach_rel
+        else:
+            # A weakly connected component relation constrained to
+            # nodes in the subset (filtered from the reach relation above).
+            _weakly_connected_component_constrained_rel = self._model.Relationship(
+                f"{{node:{self._NodeConceptStr}}} is in the connected component {{id:{self._NodeConceptStr}}}"
+            )
+
+            where(
+                node_subset(node),
+                _weakly_connected_component_reach_rel(node, component)
+            ).define(_weakly_connected_component_constrained_rel(node, component))
+
+            return _weakly_connected_component_constrained_rel
+
 
     @include_in_docs
     def diameter_range(self):
@@ -5517,6 +6190,28 @@ class Graph():
 
         return _reachable_from_min_node_rel
 
+    @cached_property
+    def _distance_non_weighted(self):
+        """Lazily define and cache the self._distance relationship."""
+        if not self.weighted:
+            return self._distance
+        else:
+            return self._create_distance_relationship(weighted=False)
+
+    @cached_property
+    def _distance_reversed_non_weighted(self):
+        """Lazily define and cache the self._distance_reversed_non_weighted relationship, a non-public helper."""
+        _distance_reversed_non_weighted_rel = self._model.Relationship(f"{{node_u:{self._NodeConceptStr}}} and {{node_v:{self._NodeConceptStr}}} have a reversed distance of {{d:Integer}}")
+        node_u, node_v, node_n, d1 = self.Node.ref(), self.Node.ref(), self.Node.ref(), Integer.ref()
+        node_u, node_v, d = union(
+            where(node_u == node_v, d1 == 0).select(node_u, node_v, d1), # Base case.
+            where(self._edge(node_v, node_n),
+                  d2 := _distance_reversed_non_weighted_rel(node_u, node_n, Integer) + 1).select(node_u, node_v, d2) # Recursive case.
+        )
+        define(_distance_reversed_non_weighted_rel(node_u, node_v, min(d).per(node_u, node_v)))
+
+        return _distance_reversed_non_weighted_rel
+
 
     @include_in_docs
     def is_connected(self):
@@ -5901,9 +6596,10 @@ class Graph():
         doi: 10.1162/netn_a_00199. PMID: 34746624; PMCID: PMC8567827.
 
         """
-        # Validate domain constraint parameters.
+        # Validate domain constraint parameters (jaccard_similarity is symmetric).
+        symmetric = True
         self._validate_domain_constraint_parameters(
-            'jaccard_similarity', full, from_, to, between
+            'jaccard_similarity', symmetric, full, from_, to, between
         )
 
         # At this point, exactly one of `full`, `from_`, or `between`
@@ -6476,9 +7172,10 @@ class Graph():
         1   3    4  0.707107
 
         """
-        # Validate domain constraint parameters.
+        # Validate domain constraint parameters (cosine_similarity is symmetric).
+        symmetric = True
         self._validate_domain_constraint_parameters(
-            'cosine_similarity', full, from_, to, between
+            'cosine_similarity', symmetric, full, from_, to, between
         )
 
         # At this point, exactly one of `full`, `from_`, or `between`
@@ -6869,9 +7566,10 @@ class Graph():
         1   2    3  1.442695
 
         """
-        # Validate domain constraint parameters.
+        # Validate domain constraint parameters (adamic_adar is symmetric).
+        symmetric = True
         self._validate_domain_constraint_parameters(
-            'adamic_adar', full, from_, to, between
+            'adamic_adar', symmetric, full, from_, to, between
         )
 
         # At this point, exactly one of `full`, `from_`, or `between`
@@ -7216,9 +7914,10 @@ class Graph():
         1   2    4      6
 
         """
-        # Validate domain constraint parameters.
+        # Validate domain constraint parameters (preferential_attachment is symmetric).
+        symmetric = True
         self._validate_domain_constraint_parameters(
-            'preferential_attachment', full, from_, to, between
+            'preferential_attachment', symmetric, full, from_, to, between
         )
 
         # At this point, exactly one of `full`, `from_`, or `between`
@@ -7472,6 +8171,197 @@ class Graph():
         return _isolated_node_rel
 
 
+    @cached_property
+    def _non_isolated_node(self):
+        """Lazily define and cache the self._non_isolated_node relationship."""
+        # Primarily a helper for the primitive graph algorithms at this time.
+        _non_isolated_node_rel = self._model.Relationship(f"{{node:{self._NodeConceptStr}}} is not isolated")
+
+        node, neighbor = self.Node.ref(), self.Node.ref()
+        where(node, self._neighbor(node, neighbor)).define(_non_isolated_node_rel(node))
+
+        return _non_isolated_node_rel
+
+
+    @cached_property
+    def _primitive_node_to_index_rel(self):
+        """
+        The graph primitives operate over node indices, contiguous from one;
+        compute a map from the identifier for each non-isolated node to such an index.
+        Lazily define and cache that relationship for shared use across primitive algorithms.
+        """
+        _node_to_index_rel = self._model.Relationship(f"{{node:{self._NodeConceptStr}}} has {{index:Integer}}")
+
+        node = self.Node.ref()
+        where(
+            self._non_isolated_node(node),
+            index := rank(node)
+        ).define(
+            _node_to_index_rel(node, index)
+        )
+
+        return _node_to_index_rel
+
+    @cached_property
+    def _primitive_weight_list(self):
+        """
+        The graph primitives operate over a normalized weight list, where
+        the nodes are represented by their contiguous indices as Int64s.
+        Lazily define and cache that normalized weight list for shared use
+        across primitive algorithms.
+        """
+        _normalized_weight_list = self._model.Relationship("{u:Int64} {v:Int64} {w:Float}")
+
+        src_node, dst_node, weight = self.Node.ref(), self.Node.ref(), Float.ref()
+        src_index, dst_index = Integer.ref(), Integer.ref()
+        where(
+            self._weight(src_node, dst_node, weight),
+            self._primitive_node_to_index_rel(src_node, src_index),
+            self._primitive_node_to_index_rel(dst_node, dst_index)
+        ).define(
+            _normalized_weight_list(int64(src_index), int64(dst_index), weight)
+        )
+
+        return _normalized_weight_list
+
+    @cached_property
+    def _primitive_node_count(self):
+        """
+        The graph primitives operate only over non-isolated nodes;
+        compute the number of non-isolated nodes as an Int64.
+        Lazily define and cache that count for shared use across primitive algorithms.
+        """
+        _normalized_node_count = self._model.Relationship("{node_count:Int64}")
+
+        define(_normalized_node_count(
+            int64(count(self.Node).where(self._non_isolated_node(self.Node)))
+        ))
+
+        return _normalized_node_count
+
+    @cached_property
+    def _primitive_edge_count(self):
+        """
+        The graph primitives operate over a normalized weight list;
+        compute the number of normalized edges as an Int64.
+        Lazily define and cache that count for shared use across primitive algorithms.
+
+        (Note that the count of normalized edges does not in general match
+        graph.num_edges(); it should match for directed graphs, but not for
+        undirected graphs, where num_edges computes the number of
+        undirected rather than directed edges.)
+        """
+        _normalized_edge_count = self._model.Relationship("{edge_count:Int64}")
+
+        u_index, v_index = builder_internal.Int64.ref(), builder_internal.Int64.ref()
+        define(_normalized_edge_count(
+            int64(count(u_index, v_index).where(self._primitive_weight_list(u_index, v_index, Float)))
+        ))
+
+        return _normalized_edge_count
+
+    def _create_primitive_algorithm_relationship(
+        self,
+        primitive_name: str,
+        primitive_params: list,
+    ):
+        """
+        Helper method for infomap, louvain, and label propagation,
+        i.e. the graph algorithsm that exercise graph primitives.
+
+        Create community assignment and diagnostic information relationships
+        exercising the specified primitive algorithm with the provided parameters.
+        """
+        # Create relationship in which to store the final community assignments.
+        _community_assignments_rel = self._model.Relationship(
+            f"{{node:{self._NodeConceptStr}}} belongs to {{community:Integer}}")
+
+        # The graph primitives operate over a normalized form of the graph.
+        # Most of the logic below transforms from the graph, to that normalized
+        # form, and back again.
+
+        # The graph primitives operate over node indices, contiguous from one;
+        # compute a map from the identifier for each non-isolated node to such an index.
+        _primitive_node_to_index_rel = self._primitive_node_to_index_rel
+
+        # The graph primitives operate over a normalized weight list, where
+        # the nodes are represented by their contiguous indices as Int64s.
+        _primitive_weight_list = self._primitive_weight_list
+
+        # Compute the number of non-isolated nodes and normalized edges, as int64s.
+        # (Note that the count of normalized edges does not in general match
+        # graph.num_edges(); it should match for directed graphs, but not for
+        # undirected graphs, where num_edges computes the number of
+        # undirected rather than directed edges.)
+        _primitive_node_count = self._primitive_node_count
+        _primitive_edge_count = self._primitive_edge_count
+
+        # Invoke the graph primitive over the normalized data.
+        primitive_expr = builder_internal.Expression(
+            builder_internal.Relationship.builtins[primitive_name],
+            builder_internal.TypeRef(_primitive_weight_list),
+            builder_internal.TypeRef(_primitive_node_count),
+            builder_internal.TypeRef(_primitive_edge_count),
+            *primitive_params,
+            builder_internal.String.ref("diagnostic_info"),
+            builder_internal.Int64.ref("node_index"),
+            builder_internal.Int64.ref("community")
+        )
+
+        last_input_arg_offset = 3 + len(primitive_params) - 1
+        prim_diagnostic_info = primitive_expr._arg_ref(last_input_arg_offset + 1)
+        prim_node_index = primitive_expr._arg_ref(last_input_arg_offset + 2)
+        prim_community = primitive_expr._arg_ref(last_input_arg_offset + 3)
+
+        # Extract the primitive's community assignments for
+        # non-isolated nodes into a relation, mapping from
+        # Int64s to Integers for smoother consumption downstream.
+        _primitive_assignments_rel = self._model.Relationship("{node_index:Integer} has {community:Integer}")
+        define(_primitive_assignments_rel(prim_node_index, prim_community))
+        # TODO: May be possible to remove this intermediate relationship,
+        #    by directly mapping into `_infomap_result_rel` below.
+        #    But if so, need to take care not to introduce recursion in rules below.
+
+        # Transform the primitive's community assignments, which map
+        # node indices to communities, to a map from nodes to communities.
+        # Note that this covers only non-isolated nodes; isolated handled later.
+        node = self.Node.ref()
+        node_index = Integer.ref()
+        community = Integer.ref()
+        where(
+            _primitive_node_to_index_rel(node, node_index),
+            _primitive_assignments_rel(node_index, community),
+        ).define(
+            _community_assignments_rel(node, community)
+        )
+
+        # Each isolated node must be assigned to its own unique community.
+        # The primitive's community assignments are contiguous integers from one,
+        # so we can assign isolated nodes to communities by offsetting their
+        # enumeration index by the maximum community assigned by the primitive.
+        isolated_node = self.Node.ref()
+        nonisolated_index = Integer.ref()
+        nonisolated_comm = Integer.ref()
+        where(
+            self._isolated_node(isolated_node),
+            isolated_node_rank := rank(isolated_node),
+            max_nonisolated_comm := (
+                max(nonisolated_index, nonisolated_comm).where(
+                    _primitive_assignments_rel(nonisolated_index, nonisolated_comm)
+                ) | 0
+            ),
+            isolated_comm := isolated_node_rank + max_nonisolated_comm
+        ).define(_community_assignments_rel(isolated_node, isolated_comm))
+
+        # Extract diagnostic information from the primitive.
+        _diagnostic_info_rel = self._model.Relationship("{diagnostic_info:String}")
+        define(_diagnostic_info_rel(prim_diagnostic_info))
+
+        # Return both the community assignments and diagnostic information.
+        return _community_assignments_rel, _diagnostic_info_rel
+
+
+    @include_in_docs
     def infomap(
             self,
             max_levels: int = 1,
@@ -7481,6 +8371,7 @@ class Graph():
             teleportation_rate: float = 0.15,
             visit_rate_tolerance: float = 1e-15,
             randomization_seed: int = 8675309,
+            diagnostic_info: bool = False,
     ):
         """Partitions nodes into communities using a variant of the Infomap algorithm.
 
@@ -7510,20 +8401,42 @@ class Graph():
         randomization_seed : int, optional
             The random number generator seed for the run. Must be a non-negative
             integer. Default is 8675309.
+        diagnostic_info : bool, optional
+            If ``True``, returns diagnostic information alongside
+            community assignments. If ``False`` (default), returns only community
+            assignments.
 
         Returns
         -------
-        Relationship
-            A binary relationship where each tuple represents a node and its
-            community assignment.
+        Relationship or tuple of Relationships
+            If ``diagnostic_info`` is ``False`` (default), returns a binary
+            relationship where each tuple represents a node and its community
+            assignment.
+
+            If ``diagnostic_info`` is ``True``, returns a tuple of
+            ``(community_assignments, diagnostic_info)`` where:
+
+            - ``community_assignments`` is the binary relationship described above
+            - ``diagnostic_info`` is a unary relationship containing a diagnostic
+              string describing the algorithm's convergence and termination behavior
 
         Relationship Schema
         -------------------
+        When ``diagnostic_info=False`` (default):
+
         ``infomap(node, community_label)``
 
         * **node** (*Node*): The node.
         * **community_label** (*Integer*): The label of the community the node
-        belongs to.
+          belongs to.
+
+        When ``diagnostic_info=True``, returns two relationships:
+
+        - ``infomap(node, community_label)`` as described above; and
+        - ``diagnostic_info(diagnostic_string)``
+
+        * **diagnostic_string** (*String*): A diagnostic string describing the
+          algorithm's convergence and termination behavior.
 
         Supported Graph Types
         ---------------------
@@ -7650,8 +8563,37 @@ class Graph():
         _assert_type("infomap:randomization_seed", randomization_seed, int)
         _assert_exclusive_lower_bound("infomap:randomization_seed", randomization_seed, 0)
 
-        raise NotImplementedError("`infomap` is not yet implemented.")
+        # Collect parameters to rel_primitive_infomap,
+        # appropriately typed and ordered for the primitive.
+        infomap_parameters = [
+            float(teleportation_rate),
+            float(visit_rate_tolerance),
+            float(level_tolerance),
+            float(sweep_tolerance),
+            int(max_levels),
+            int(max_sweeps),
+            int(randomization_seed),
+        ]
+
+        # Create infomap community assignment and, if requested,
+        # diagnostic information relationships.
+        _infomap_assignments_rel, _infomap_diagnostic_rel = \
+            self._create_primitive_algorithm_relationship(
+                "infomap", infomap_parameters
+            )
+
+        # Attach tracking information to the community assignment relationship.
+        _infomap_assignments_rel.annotate(annotations.track("graphs", "infomap"))
+
+        # Return either just the community assignments, or both
+        # the community assignments and diagnostic information, per request.
+        if diagnostic_info:
+            return _infomap_assignments_rel, _infomap_diagnostic_rel
+        else:
+            return _infomap_assignments_rel
+
 
+    @include_in_docs
     def louvain(
             self,
             max_levels: int = 1,
@@ -7659,6 +8601,7 @@ class Graph():
             level_tolerance: float = 0.01,
             sweep_tolerance: float = 0.0001,
             randomization_seed: int = 8675309,
+            diagnostic_info: bool = False,
     ):
         """Partitions nodes into communities using the Louvain algorithm.
 
@@ -7682,12 +8625,23 @@ class Graph():
         randomization_seed : int, optional
             The random number generator seed for the run. Must be a
             non-negative integer. Default is 8675309.
+        diagnostic_info : bool, optional
+            If ``True``, returns diagnostic information alongside community
+            assignments. If ``False`` (default), returns only community assignments.
 
         Returns
         -------
-        Relationship
-            A binary relationship where each tuple represents a node and its
-            community assignment.
+        Relationship or tuple of Relationships
+            If ``diagnostic_info`` is ``False`` (default), returns a binary
+            relationship where each tuple represents a node and its community
+            assignment.
+
+            If ``diagnostic_info`` is ``True``, returns a tuple of
+            ``(community_assignments, diagnostic_info)`` where:
+
+            - ``community_assignments`` is the binary relationship described above
+            - ``diagnostic_info`` is a unary relationship containing a diagnostic
+              string describing the algorithm's termination behavior.
 
         Raises
         ------
@@ -7696,11 +8650,21 @@ class Graph():
 
         Relationship Schema
         -------------------
+        When ``diagnostic_info=False`` (default):
+
         ``louvain(node, community_label)``
 
         * **node** (*Node*): The node.
         * **community_label** (*Integer*): The label of the community the node
-        belongs to.
+          belongs to.
+
+        When ``diagnostic_info=True``, returns two relationships:
+
+        - ``louvain(node, community_lable)`` as described above; and
+        - ``diagnostic_info(diagnostic_string)``
+
+        * **diagnostic_string** (*String*): A diagnostic string describing the
+          algorithm's convergence and termination behavior.
 
         Supported Graph Types
         ---------------------
@@ -7821,12 +8785,39 @@ class Graph():
         _assert_type("louvain:randomization_seed", randomization_seed, int)
         _assert_exclusive_lower_bound("louvain:randomization_seed", randomization_seed, 0)
 
-        raise NotImplementedError("`louvain` is not yet implemented.")
+        # Collect parameters to rel_primitive_louvain,
+        # appropriately typed and ordered for the primitive.
+        louvain_parameters = [
+            float(level_tolerance),
+            float(sweep_tolerance),
+            int(max_levels),
+            int(max_sweeps),
+            int(randomization_seed),
+        ]
+
+        # Create louvain community assignment and, if requested,
+        # diagnostic information relationships.
+        _louvain_assignments_rel, _louvain_diagnostic_rel = \
+            self._create_primitive_algorithm_relationship(
+                "louvain", louvain_parameters
+            )
+
+        # Attach tracking information to the community assignment relationship.
+        _louvain_assignments_rel.annotate(annotations.track("graphs", "louvain"))
+
+        # Return either just the community assignments, or both
+        # the community assignments and diagnostic information, per request.
+        if diagnostic_info:
+            return _louvain_assignments_rel, _louvain_diagnostic_rel
+        else:
+            return _louvain_assignments_rel
 
+    @include_in_docs
     def label_propagation(
             self,
             max_sweeps: int = 20,
             randomization_seed: int = 8675309,
+            diagnostic_info: bool = False,
     ):
         """Partitions nodes into communities using the Label Propagation algorithm.
 
@@ -7841,20 +8832,42 @@ class Graph():
         randomization_seed : int, optional
             The random number generator seed for the run. Must be a positive
             integer. Default is 8675309.
+        diagnostic_info : bool, optional
+            If ``True``, returns diagnostic information alongside
+            community assignments. If ``False`` (default), returns only community
+            assignments.
 
         Returns
         -------
-        Relationship
-            A binary relationship where each tuple represents a node and its
-            community assignment.
+        Relationship or tuple of Relationships
+            If ``diagnostic_info`` is ``False`` (default), returns a binary
+            relationship where each tuple represents a node and its community
+            assignment.
+
+            If ``diagnostic_info`` is ``True``, returns a tuple of
+            ``(community_assignments, diagnostic_info)`` where:
+
+            - ``community_assignments`` is the binary relationship described above
+            - ``diagnostic_info`` is a unary relationship containing a diagnostic
+              string describing the algorithm's termination behavior.
 
         Relationship Schema
         -------------------
+        When ``diagnostic_info=False`` (default):
+
         ``label_propagation(node, community_label)``
 
         * **node** (*Node*): The node.
         * **community_label** (*Integer*): The label of the community the node
-        belongs to.
+          belongs to.
+
+        When ``diagnostic_info=True``, returns two relationships:
+
+        - ``community_assignments(node, community_label)`` as described above; and
+        - ``diagnostic_info(diganostic_string)``
+
+        * **diagnostic_string** (*String*): A diagnostic string describing the
+          algorithm's convergence and termination behavior.
 
         Supported Graph Types
         ---------------------
@@ -7966,4 +8979,23 @@ class Graph():
         _assert_type("label_propagation:randomization_seed", randomization_seed, int)
         _assert_exclusive_lower_bound("label_propagation:randomization_seed", randomization_seed, 0)
 
-        raise NotImplementedError("`label_propagation` is not yet implemented.")
+        # Collect parameters to rel_primitive_async_label_propagation,
+        # appropriately typed and ordered for the primitive.
+        label_propagation_parameters = [
+            int(max_sweeps),
+            int(randomization_seed),
+        ]
+
+        # Invoke the helper method that handles normalization,
+        # primitive invocation, and result transformation.
+        _label_propagation_assignments_rel, _label_propagation_diagnostic_rel = \
+            self._create_primitive_algorithm_relationship("label_propagation", label_propagation_parameters)
+
+        # Add tracking annotation.
+        _label_propagation_assignments_rel.annotate(annotations.track("graphs", "label_propagation"))
+
+        # Return based on whether diagnostic information was requested.
+        if diagnostic_info:
+            return _label_propagation_assignments_rel, _label_propagation_diagnostic_rel
+        else:
+            return _label_propagation_assignments_rel