relationalai 0.13.0.dev0__py3-none-any.whl → 0.13.1__py3-none-any.whl

relationalai/experimental/pathfinder/rpq.py

@@ -0,0 +1,344 @@
+from abc import ABC, abstractmethod
+import typing
+from relationalai.experimental.pathfinder.glushkov import Glushkov
+from relationalai.experimental.pathfinder.filter import (
+    NodeFilter, NodeLabel, AnonymousNodeFilter, EdgeLabel, AnonymousEdgeFilter
+)
+
+# =========================================================================================
+# Regular Path Queries (RPQs) with local filters
+# =========================================================================================
+#
+# Regular Path Queries with local filters are represented as ASTs defined with this grammar.
+#
+# expr ::= Node([NodeLabel], [AnonymousNodeFilter])
+#        | Edge(EdgeLabel, [AnonymousEdgeFilter])
+#        | Concat(expr₁, expr₂)
+#        | Union(expr₁, expr₂)
+#        | Star(expr)
+#        | Plus(expr)
+#        | Optional(expr)
+#        | Void
+#
+# Every Edge leaf of an RPQ is automatically assigned a unique position `pos` value i.e.,
+# the `Edge` constructor uses a class variable `_id_counter` to generate a fresh value for
+# each new instance of `Edge`. The positions are used to provide the user with clear
+# feedback (error and warnings) that refers to specific places in the input RPQ.
+#
+# An important requirement is that an RPQ does not use two Edge leaves with the same
+# position.  With a natural use of the RPQ constructors, this requirement is not violated
+# unless a subexpression is reused. Consequently, the `clone` method is provided to create a
+# copy of an RPQ subexpression with fresh edge positions. For further safety, we ensure that
+# no two Edges with the same position are present, by constructing the set of positions of
+# an expression. If during the construction of a complex RPQ (`Concat` or `Union`) we find
+# repeating positions, we clone one of the expressions to ensure that the positions are
+# unique in the whole RPQ.
+# =========================================================================================
+
+#------------------------------------------------------------------------------------------
+# Auxiliary function for repeating `expr{n:m}` used to implement slicing operator of RPQ
+#------------------------------------------------------------------------------------------
+def _repeat(pattern: 'RPQ', n:typing.Union[int,None], m:typing.Union[int,None]) -> 'RPQ':
+        n = n if n is not None else 0
+        assert n >= 0, f"Negative start range [{n}:{m}]"
+        assert (m is None or m >= n), f"Invalid repeat range [{n}:{m}]"
+        if m is None:
+            if n == 0:
+                return Star(pattern)
+            elif n == 1:
+                return Plus(pattern)
+            else:
+                result = pattern.clone()
+                for _ in range(n-2):
+                    result = Concat(result, pattern.clone())
+                return Concat(result, Plus(pattern))
+        else:
+            if n == 0:
+                if m == 0:
+                    return Node()
+                else:
+                    result = Optional(pattern)
+                    for _ in range(m-1):
+                        result = Concat(result, Optional(pattern.clone()))
+                    return result
+            else:
+                result = pattern
+                for _ in range(n-1):
+                    result = Concat(result, pattern.clone())
+                for _ in range(m-n):
+                    result = Concat(result, Optional(pattern.clone()))
+                return result
+
+class RPQ(ABC):
+    _id_counter = 0
+
+    @classmethod
+    def next_id(cls) -> int:
+        cls._id_counter += 1
+        return cls._id_counter
+
+    def __init__(self, positions: typing.FrozenSet[int] = frozenset()):
+        self._positions = positions
+
+    @property
+    def positions(self) -> typing.FrozenSet[int]:
+        return self._positions
+
+    @abstractmethod
+    def clone(self) -> 'RPQ':
+        pass
+
+    @abstractmethod
+    def glushkov(self) -> Glushkov:
+        pass
+
+    @abstractmethod
+    def pprint(self, ind) -> str:
+        pass
+
+    def __str__(self):
+        return self.pprint("")
+
+    @abstractmethod
+    def to_dict(self) -> dict:
+        pass
+
+    def __len__(self) -> int:
+        return len(self.positions)
+
+    # expr[n:m]
+    def __getitem__(self, key):
+        if isinstance(key, int):
+            return _repeat(self, key, key)
+        elif isinstance(key, slice):
+            return _repeat(self, key.start, key.stop)
+        else:
+            return NotImplemented
+
+    # expr₁ | expr₂
+    def __or__(self, other):
+        if isinstance(self, Void):
+            return other
+        elif isinstance(other, Void):
+            return self
+        else:
+            return Union(self, other)
+
+    # expr₁ ⋅ expr₂
+    def __mul__(self, other):
+        return Concat(self, other)
+
+# ∅
+class Void(RPQ):
+    def __init__(self):
+        super().__init__()
+
+    def clone(self):
+        return Void()
+
+    def glushkov(self):
+        return Glushkov.void()
+
+    def pprint(self, ind):
+        return ind + "⋅ ∅"
+
+    def to_dict(self):
+        return {"type": "Void"}
+
+# ε(label {filter})
+class Node(RPQ):
+    def __init__(self,
+                 label: typing.Optional[NodeLabel]=None,
+                 filter: typing.Optional[AnonymousNodeFilter]=None):
+        super().__init__()
+        self.label = label
+        self.filter = filter
+
+    def clone(self):
+        return Node(self.label, self.filter)
+
+    def glushkov(self):
+        filters: typing.List[NodeFilter] = []
+        if self.label is not None:
+            filters.append(self.label)
+        if self.filter is not None:
+            filters.append(self.filter)
+        return Glushkov.node_transition(*filters)
+
+    def pprint(self, ind):
+        res = ind + "⋅ Node("
+        if self.label is not None:
+            res += f"{self.label}"
+        if self.filter is not None:
+            res += " {" if self.label is not None else "{"
+            res += f"{self.filter}"
+            res += "}"
+        res += ")"
+        return res
+
+    def to_dict(self) -> dict:
+        d = {"type": "Node"}
+        if self.label is not None:
+            d["label"] = self.label.to_dict() # type: ignore
+        if self.filter is not None:
+            d["filter"] = self.filter.to_dict() # type: ignore
+        return d
+
+# -[label {filter}]->
+class Edge(RPQ):
+    def __init__(self,
+                 label: EdgeLabel,
+                 filter: typing.Optional[AnonymousEdgeFilter] = None):
+        self.pos = self.next_id()
+        super().__init__(frozenset([self.pos]))
+        self.label = label
+        self.filter = filter
+
+    def clone(self):
+        return Edge(self.label, self.filter)
+
+    def glushkov(self):
+        return Glushkov.edge_transition(self.pos, self.label, self.filter)
+
+    # we avoid using `[...]` which can be mistaken for control sequence by rich-text loggers
+    def pprint(self, ind):
+        res = ind + "⋅ "
+        filter_str = ""
+        if self.filter is not None:
+            filter_str += f" {{ {self.filter} }}"
+        if self.label.direction == "forward":
+            res += f"-⟨{self.label.label}{filter_str}⟩→"
+        else:
+            res += f"←⟨{self.label.label}{filter_str}⟩-"
+        res += f" pos={self.pos} "
+        return res
+
+    def to_dict(self) -> dict:
+        return {
+            "type": "Edge",
+            "pos": self.pos,
+            "label": self.label.to_dict() # type: ignore
+        }
+
+# expr₁ ⋅ expr₂
+class Concat(RPQ):
+    def __init__(self, expr1:RPQ, expr2:RPQ):
+        if not expr1.positions.isdisjoint(expr2.positions):
+            expr2 = expr2.clone()
+        super().__init__(expr1.positions | expr2.positions)
+        self.expr1 = expr1
+        self.expr2 = expr2
+
+    def clone(self):
+        return Concat(self.expr1.clone(), self.expr2.clone())
+
+    def glushkov(self):
+        g = self.expr1.glushkov()
+        g *= self.expr2.glushkov()
+        return g
+
+    def pprint(self, ind):
+        res = ind + "⋅ Concat\n"
+        res += self.expr1.pprint(ind + "   ") + "\n"
+        res += self.expr2.pprint(ind + "   ")
+        return res
+
+    def to_dict(self) -> dict:
+        return {
+            "type": "Concat",
+            "expr1": self.expr1.to_dict(), # type: ignore
+            "expr2": self.expr2.to_dict()  # type: ignore
+        }
+
+# expr ₁ | expr₂
+class Union(RPQ):
+    def __init__(self, expr1:RPQ, expr2:RPQ):
+        if not expr1.positions.isdisjoint(expr2.positions):
+            expr2 = expr2.clone()
+        super().__init__(expr1.positions | expr2.positions)
+        self.expr1 = expr1
+        self.expr2 = expr2
+
+    def clone(self):
+        return Union(self.expr1.clone(), self.expr2.clone())
+
+    def glushkov(self):
+        g = self.expr1.glushkov()
+        g |= self.expr2.glushkov()
+        return g
+
+    def pprint(self, ind):
+        res = ind + "⋅ Union\n"
+        res += self.expr1.pprint(ind + "   ") + "\n"
+        res += self.expr2.pprint(ind + "   ")
+        return res
+
+    def to_dict(self) -> dict:
+        return {
+            "type": "Union",
+            "expr1": self.expr1.to_dict(), # type: ignore
+            "expr2": self.expr2.to_dict()  # type: ignore
+        }
+
+# expr*
+class Star(RPQ):
+    def __init__(self, expr:RPQ):
+        super().__init__(expr.positions)
+        self.expr = expr
+
+    def clone(self):
+        return Star(self.expr.clone())
+
+    def glushkov(self):
+        return self.expr.glushkov().star()
+
+    def pprint(self, ind):
+        return ind + "⋅ Star\n" + self.expr.pprint(ind + '   ')
+
+    def to_dict(self) -> dict:
+        return {
+            "type": "Star",
+            "expr": self.expr.to_dict() # type: ignore
+        }
+
+# expr+
+class Plus(RPQ):
+    def __init__(self, expr:RPQ):
+        super().__init__(expr.positions)
+        self.expr = expr
+
+    def clone(self):
+        return Plus(self.expr.clone())
+
+    def glushkov(self):
+        return self.expr.glushkov().plus()
+
+    def pprint(self, ind):
+        return ind + "⋅ Plus\n" + self.expr.pprint(ind + '   ')
+
+    def to_dict(self) -> dict:
+        return {
+            "type": "Plus",
+            "expr": self.expr.to_dict() # type: ignore
+        }
+
+# expr?
+class Optional(RPQ):
+    def __init__(self, expr:RPQ):
+        super().__init__(expr.positions)
+        self.expr = expr
+
+    def clone(self):
+        return Optional(self.expr.clone())
+
+    def glushkov(self):
+        return self.expr.glushkov().optional()
+
+    def pprint(self, ind):
+        return ind + "⋅ Optional\n" + self.expr.pprint(ind + '   ')
+
+    def to_dict(self) -> dict:
+        return {
+            "type": "Optional",
+            "expr": self.expr.to_dict() # type: ignore
+        }

relationalai/experimental/pathfinder/transition.py

@@ -0,0 +1,200 @@
+
+from typing import List, FrozenSet, Union, Iterable
+from relationalai.experimental.pathfinder.filter import (
+    NodeFilter, EdgeFilter, EdgeLabel, AnonymousEdgeFilter
+)
+
+# =========================================================================================
+# Transitions
+# =========================================================================================
+#
+# Transitions are the building blocks of automata for paths in a labeled knowledge graph.
+# There are two types of transitions: node transitions and edge transitions.
+#
+# * a _node transition_ `-(ψ₁ ∧ … ∧ ψ ₖ)->` does not advance on the path but only asserts
+#   the node filters ψ₁,..., ψ ₖ on the current node.
+#
+# * an _edge transition_ `-(ψ₁ ∧ … ∧ ψₖ)-[φ₁ ∧ … ∧ φₙ]-(ρ₁ ∧ … ρₘ)->` that asserts the
+#   source node filters ψ₁, ..., ψₖ on the current node, traverses an edge satisfying the
+#   edge filters φ₁, ..., φₙ, and asserts the node filters ρ₁, ..., ρₘ on the arriving node.
+#   NOTE: We only use edge transitions that have at least one edge label.
+#
+# A transition `t` is _trivial_ if it has no filters. A transition is _grounded_ if it
+# contains a grounded filter (a label). Note that an edge transition is always grounded
+# since it contains at least one edge label filter (that is grounded).
+#
+# Two transitions t₁ and t₂ can be _composed_ `t₁ * t₂` with the multiplication operator:
+# 1. two node transitions can be composed by taking the union of their filters.
+# 2. an node transition can be composed with and edge transition on the left or right by
+#    adding its filters to the source or destination node filters of the edge transition.
+# 3. Two edge-transitions CANNOT be composed!
+#
+# To ensure rudimentary equality and hashing, the collection of filters are stored as
+# immutable frozen sets; A transition once created must not have its filters modified in any
+# way.
+#
+# For the purposes of automata simplification, we define a simulation relation between
+# transitions: `t₁ simulates t₂` if any path fragment that matches t₂ also matches t₁.
+# =========================================================================================
+
+class NodeTransition:
+    def __init__(self, filters: Iterable[NodeFilter] = set()):
+        self._filters: FrozenSet = frozenset(filters)
+
+    @property
+    def filters(self) -> FrozenSet[NodeFilter]:
+        return self._filters
+
+    def is_trivial(self):
+        return len(self._filters) == 0
+
+    def is_grounded(self):
+        return any(f.is_grounded() for f in self._filters)
+
+    def __repr__(self):
+        return f"⊨⸨{' ∧ '.join(map(str, self._filters))}⸩⇒"
+
+    def to_dict(self) -> dict:
+        d = {"type": "NodeTransition"}
+        if self._filters:
+            d["filters"] = [f.to_dict() for f in self._filters] # type: ignore
+        return d
+
+    def __eq__(self, other):
+        if isinstance(other, NodeTransition):
+            return self._filters == other._filters
+        else:
+            return NotImplemented
+
+    def __hash__(self):
+        return hash(self._filters)
+
+    def __mul__(self, other: 'NodeTransition') -> 'NodeTransition':
+        if isinstance(other, NodeTransition):
+            return NodeTransition(self._filters | other._filters)
+        else:
+            return NotImplemented
+
+    # if `t₁ simulates t₂`, then any node on a path that matches t₂ also matches t₁
+    def simulates(self, other: 'NodeTransition') -> bool:
+        if isinstance(other, NodeTransition):
+            return self._filters <= other._filters
+        else:
+            return NotImplemented
+
+class EdgeTransition:
+    def __init__(self,
+                 src_filters: Iterable[NodeFilter],
+                 edge_filters: Iterable[EdgeFilter],
+                 trg_filters: Iterable[NodeFilter]):
+        assert any(isinstance(f, EdgeLabel) for f in edge_filters), "An edge transition must have at least one edge label"
+        self._src_filters: FrozenSet[NodeFilter] = frozenset(src_filters)
+        self._edge_filters: FrozenSet[EdgeFilter] = frozenset(edge_filters)
+        self._trg_filters: FrozenSet[NodeFilter] = frozenset(trg_filters)
+
+    @property
+    def src_filters(self) -> FrozenSet[NodeFilter]:
+        return self._src_filters
+
+    @property
+    def edge_filters(self) -> FrozenSet[EdgeFilter]:
+        return self._edge_filters
+
+    @property
+    def trg_filters(self) -> FrozenSet[NodeFilter]:
+        return self._trg_filters
+
+    def __repr__(self):
+        res = f"⊨⸨{' ∧ '.join(map(str, self._src_filters))}⸩"
+        res += f"═⟦{' ∧ '.join(map(str, self._edge_filters))}⟧═"
+        res += f"⸨{' ∧ '.join(map(str, self._trg_filters))}⸩⇒"
+        return res
+
+    def to_dict(self):
+        d = {"type": "EdgeTransition"}
+        if self._src_filters:
+            d["src_filters"] = [f.to_dict() for f in self._src_filters] # type: ignore
+        d["edge_filters"] = [f.to_dict() for f in self._edge_filters]   # type: ignore
+        if self._trg_filters:
+            d["trg_filters"] = [f.to_dict() for f in self._trg_filters] # type: ignore
+        return d
+
+    def has_src_filters(self):
+        return len(self._src_filters) > 0
+
+    def has_trg_filters(self):
+        return len(self._trg_filters) > 0
+
+    def has_grounded_trg_filters(self):
+        return any(f.is_grounded() for f in self._trg_filters)
+
+    def has_grounded_src_filters(self):
+        return any(f.is_grounded() for f in self._src_filters)
+
+    def has_anon_edge_filters(self):
+        return any(not f.is_grounded() for f in self._edge_filters)
+
+    def get_label(self) -> EdgeLabel:
+        for f in self._edge_filters:
+            if isinstance(f, EdgeLabel):
+                return f
+        raise ValueError("No edge label filter in the transition")
+
+    def get_anon_edge_filters(self) -> List[AnonymousEdgeFilter]:
+        return [f for f in self._edge_filters if isinstance(f, AnonymousEdgeFilter)]
+
+    def __eq__(self, other):
+        if isinstance(other, EdgeTransition):
+            return (self._src_filters == other._src_filters and
+                    self._edge_filters == other._edge_filters and
+                    self._trg_filters == other._trg_filters)
+        else:
+            return NotImplemented
+
+    # If `t₁ simulates t₂`, then then any edge on a path that matches t₂ also matches t₁.
+    def simulates(self, other: 'EdgeTransition') -> bool:
+        if isinstance(other, EdgeTransition):
+            return (self._src_filters <= other._src_filters and
+                    self._edge_filters <= other._edge_filters and
+                    self._trg_filters <= other._trg_filters)
+        else:
+            return NotImplemented
+
+    def __hash__(self):
+        return hash((hash(self._src_filters),
+                     hash(self._edge_filters),
+                     hash(self._trg_filters)))
+
+    def __mul__(self, other: 'NodeTransition') -> 'EdgeTransition':
+        if isinstance(other, NodeTransition):
+            return EdgeTransition(
+                self._src_filters,
+                self._edge_filters,
+                self._trg_filters | other._filters
+            )
+        else:
+            return NotImplemented
+
+    def __rmul__(self, other: 'NodeTransition') -> 'EdgeTransition':
+        if isinstance(other, NodeTransition):
+            return EdgeTransition(
+                self._src_filters | other._filters,
+                self._edge_filters,
+                self._trg_filters
+            )
+        else:
+            return NotImplemented
+
+# -----------------------------------------------------------------------------------------
+# Function on sets of transitions
+# -----------------------------------------------------------------------------------------
+
+# T₁ _simulate_ T₂, if for any t₂ in T₂ there is t₁ in T₁ such that t₁ simulates t₂.
+# When T₁ _simulate_ T₂ a path fragment that matches all of T₂ also matches all of T₁.
+def simulate(T1: Union[Iterable[EdgeTransition], Iterable[NodeTransition]],
+             T2: Union[Iterable[EdgeTransition], Iterable[NodeTransition]]) -> bool:
+    return all(any(t1.simulates(t2) for t1 in T1) for t2 in T2) # type: ignore
+
+# Gets the list of all labels from a collection of edge transitions (with repetitions)
+def labels(T: Iterable[EdgeTransition]) -> List[EdgeLabel]:
+    return [t.get_label() for t in T]

relationalai/experimental/pathfinder/utils.py

@@ -0,0 +1,26 @@
+from typing import Callable
+from relationalai.dsl import get_graph, Graph
+# -----------------------------------------------------------------------------------------
+# Utility functions
+# -----------------------------------------------------------------------------------------
+
+#
+# Get the string representation of a lambda function (with moderate effort).
+#
+def get_lambda_str(f: Callable) -> str:
+    try:
+        if f.__name__ == '<lambda>':
+            return f"λ{','.join(f.__code__.co_varnames)}:... @{hex(id(f))}"
+        else:
+            return f"{f.__name__}({','.join(f.__code__.co_varnames)}):... @{hex(id(f))}"
+    except Exception as _:
+        return str(f)
+
+#
+# Returns the model to use for emitting the logic defining paths and calling the Pathfinder.
+#
+def get_model(options) -> Graph:
+    if options['model'] is not None:
+        return options['model']
+    else:
+        return get_graph()

relationalai/experimental/paths/README.md

@@ -0,0 +1,107 @@
+# RelationalAI `paths` library
+
+The RelationalAI `paths` library provides functionality for finding paths in a labeled
+property graph that **match** a certain **pattern**, specified by a so-called
+**regular path query** (RPQ).
+
+## Basic usage: Example
+
+The following is a minimal working example:
+
+```py
+from relationalai.semantics import Model, Integer, select, String, where, define
+from relationalai.semantics.std import strings
+
+from relationalai.experimental.paths.graph import Graph
+from relationalai.experimental.paths.api import node, edge, path, star, match
+
+model = Model("my_paths")
+
+# create a labeled graph from an edge list:
+edge_list = [(1, 2, "A"), (2, 3, "A"), (3, 4, "A"), (4, 5, "B"), (1, 5, "A")]
+graph = Graph.from_edge_list(model, edge_list)
+
+# specify a path pattern to match in terms of string labels:
+pattern = path("A", star("A"), "B")
+
+# specify source and target sets (optional):
+sources = [1]
+targets = [5]
+
+Node = graph.Node
+
+Source = model.Relationship("{Node} is a source node")
+Target = model.Relationship("{Node} is a target node")
+
+for src in sources:
+    define(Source(Node.new(id=src)))
+
+for tgt in targets:
+    define(Target(Node.new(id=tgt)))
+
+# specify setup for the path-finding algorithm:
+paths = match(graph, pattern, Source, Target)
+
+# convert path representation to use node IDs instead of opaque hashes:
+i, k = Integer.ref(), Integer.ref()
+node = graph.Node.ref()
+label = String.ref()
+
+result = select(i, k, label, node.id).where(
+    paths(i, k, label, node)
+)
+
+# run the computation and display the result:
+result.inspect()
+```
+
+## API
+
+### Specifying a path pattern
+
+A path is specified by a regular expression on edge labels, built using the following components:
+- `path`: A concatenation of its arguments (separated by commas)
+- `star`: Zero or more repetitions of its argument
+- `plus`: One or more repetitions of its argument
+- `union`: Allows any of its arguments (a single time)
+
+### Matching a pattern
+The API for matching a pattern is as follows:
+```
+match(graph, pattern, [Source], [Target], **kw)
+```
+The `Source` and `Target` sets should be `Concept`s or unary `Relationship`s containing
+sets of source / target nodes, respectively. If they are not specified then all nodes are used.
+
+The allowed keyword arguments are as follows:
+- `type`
+    - The type (semantics) of paths
+    - Possible values:
+        - `shortest`: Shortest paths
+        - `walks`: Walks (all paths)
+    - Default value is `shortest`
+
+- `num_paths`
+    - Specifies the maximum number of paths to return.
+    - Default value is `None`, corresponding to all paths.
+
+- `max_length`
+    - Maximum length of path to return
+    - Default value is 1000
+
+## Implementation sketch
+
+- The user's input `pattern` is converted into a finite automaton.
+- We create the **product graph**, consisting of nodes of the form `(state, orig_node)`,
+where `state` is a state of the automaton and `orig_node` is a node in the original graph.
+- We find paths in the product graph between nodes having the automaton's initial and 
+final state.
+- These paths are projected back down to the user's graph.
+
+## Notes
+- Currently we use our own `Graph` `class`. This will soon be replaced by the one from the
+ `graphs` library.
+
+ ## Not yet implemented
+- Reverse edges
+- Group-by operations over source and target sets (e.g. "find shortest paths from *each* node in this source set to this target node)