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

relationalai/experimental/pathfinder/rpq.py

@@ -1,344 +0,0 @@
-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

@@ -1,200 +0,0 @@
-
-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

@@ -1,26 +0,0 @@
-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

@@ -1,107 +0,0 @@
-# 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)