relationalai 0.13.5__py3-none-any.whl → 1.0.0a1__py3-none-any.whl

v0/relationalai/experimental/pathfinder/datalog.py

@@ -0,0 +1,214 @@
+from typing import Optional, Callable, NamedTuple, Tuple, Union, List, Dict
+from v0.relationalai.dsl import Graph, create_vars
+from v0.relationalai.std import rel
+from v0.relationalai.metamodel import Builtins
+from v0.relationalai.experimental.pathfinder.utils import get_lambda_str
+from v0.relationalai.experimental.pathfinder.filter import EdgeLabel
+
+# -----------------------------------------------------------------------------------------
+# Rules and Atoms
+# -----------------------------------------------------------------------------------------
+# Currently, the datalog programs that we generate consist of rules with essentially
+# positive conjunctive bodies. Multiple rules may use the same head, thus the rules are in
+# fact disjunctions of conjunctive queries. Furthermore, rules may be recursive.
+#
+# A rule has a n-ary relation head `R(x₁,...,xₙ)` and uses only the following kind of atoms
+# in its body:
+# - `A(x₁,...,xₖ)` -- a k-ary relation, where `A` is a derived or base relation
+#   name, and `x₁,...,xₖ` are variables.
+# - `f(i)` or `f(i, j) -- either unary or binary anonymous unary filter atom, where `f` is a
+#   unary or binary function that emits PyRel code to filter for the input variables
+# - `x = y` -- an equality atom of two variables
+# - `x = c` -- an equality atom of a variable and a constant (integer)
+#
+# For simplicity, in our representation we use consecutive integers 0, 1, ... to name
+# variables in rules. As it is custom, variables that are not present in the head are
+# (implicitly) existentially quantified.
+#
+# Examples:
+# The following rule
+# Rule:
+# * head = RelAtom('R', (0, 3))
+# * n = 4 # number of variables in the rule
+# * body = [
+#       RelAtom('S', (0, 1, 2)),
+#       VariableEqualityAtom((1, 3)),
+#       ConstantEqualityAtom((2, 105768493)),
+#       AnonymousFilterAtom(lambda x, y: x < y, (0, 1))
+#   ]
+# represent the following Rel/Datalog rule
+#
+# def R(x0, x3): exists((x1, x2) | S(x0, x1, x2) and x1 = x3 and x2 = 105768493 and x0 < x1)
+#
+# It could be argued that the anonymous filter atoms supplant equality atoms but we keep
+# them to make their use more explicit. Anonymous filter atoms will always originate from
+# the anonymous filter expressions in the RPQs.
+# -----------------------------------------------------------------------------------------
+
+class RelAtom(NamedTuple):
+    rel_name: str
+    vars: Tuple[int,...]
+
+    def __repr__(self):
+        return f"{self.rel_name}({', '.join([f'x{v}' for v in self.vars])})"
+
+    def to_dict(self):
+        return {
+            "type": "RelAtom",
+            "rel_name": self.rel_name,
+            "vars": list(self.vars)
+        }
+
+# FilterAtom(lambda x: x == 1, (0,)) -> {lambda x: x < 1}(x0) -> x0 < 1
+class AnonymousFilterAtom(NamedTuple):
+    function: Callable
+    vars: Union[Tuple[int], Tuple[int, int]]
+
+    def __repr__(self):
+        return '{' + get_lambda_str(self.function) + '}(' + ', '.join([f'x{v}' for v in self.vars]) + ')'
+
+    def to_dict(self):
+        return {
+            "type": "AnonymousFilterAtom",
+            "function": get_lambda_str(self.function),
+            "vars": list(self.vars)
+        }
+
+# VariableEqualityAtom((0, 1)) -> x0 = x1
+class VariableEqualityAtom(NamedTuple):
+    vars: Tuple[int, int]
+
+    def __repr__(self):
+        return f'x{self.vars[0]} = x{self.vars[1]}'
+
+    def to_dict(self):
+        return {
+            "type": "VariableEqualityAtom",
+            "vars": list(self.vars)
+        }
+
+# ConstantEqualityAtom((0, 1234)) -> x0 = 1234
+# NOTE: Currently, we only use equality atoms in product graph definition to indicate the
+# state of the automaton. Hence, logging the constant value is safe; User defined equality
+# tests are encapsulated in anonymous filter atoms, which are serialized in a way that
+# obscures any values (and logic) used in the filter.
+class ConstantEqualityAtom(NamedTuple):
+    vars: Tuple[int, int]
+
+    def __repr__(self):
+        return f'x{self.vars[0]} = {self.vars[1]}'
+
+    def to_dict(self):
+        return {
+            "type": "ConstantEqualityAtom",
+            "vars": list(self.vars)
+        }
+
+# Atoms used in the body of a rule
+Atom = Union[
+   RelAtom, AnonymousFilterAtom, VariableEqualityAtom, ConstantEqualityAtom
+]
+
+# Rule(RelAtom('R', (0, 2)), 3, [RelAtom('S', (0, 1)), VariableEqualityAtom((1, 2))])
+# -> R(x0, x2) :- ∃ x1. S(x0, x1), x1 = x2
+class Rule(NamedTuple):
+    head: RelAtom
+    n: int   # number of variables in the rule
+    body: List[Atom]
+
+    def __repr__(self):
+        return f"def {self.head}:\n    " + ' ∧\n    '.join([str(a) for a in self.body])
+
+    def to_dict(self):
+        return {
+            "type": "Rule",
+            "head": self.head.to_dict(),
+            "n": self.n,
+            "body": [a.to_dict() for a in self.body]
+        }
+
+# -----------------------------------------------------------------------------------------
+# Datalog Program
+# -----------------------------------------------------------------------------------------
+# The result of compiling a RPQ into a Datalog program, which includes:
+# - `root_rel` a dictionary mapping distinguished relations to their names.
+# - `rel_attrs` a dictionary mapping relation names to their attributes:
+#   a possibly empty subset of {'@inline', '@no_inline', '@pipeline'}
+# - `rules` a list of rules,
+# - `edge_label_map` a dictionary mapping hash values to the edge labels.
+# -----------------------------------------------------------------------------------------
+class DatalogProgram(NamedTuple):
+    root_rel: Dict[str, str]
+    rel_attrs: Dict[str, List[str]]
+    rules: List[Rule]
+    edge_label_map: Optional[Dict[int, EdgeLabel]]
+
+    def __repr__(self):
+        return '\n'.join([str(rule) for rule in self.rules])
+
+    def to_dict(self):
+        d = {
+            "type": "DatalogProgram",
+            "root_rel": self.root_rel,
+            "rel_attrs": self.rel_attrs,
+            "rules": [rule.to_dict() for rule in self.rules],
+        }
+        if self.edge_label_map:
+            d["edge_label_map"] = {k: v.to_dict() for k, v in self.edge_label_map.items()}
+        return d
+
+# -----------------------------------------------------------------------------------------
+# Installing the compiled RPQ
+# -----------------------------------------------------------------------------------------
+# An RPQ is compiled into a simple Datalog program, which needs to be installed in the
+# model. The program introduces a number of relations, some of which must be decorated with
+# specific attributes (such as `@inline` or `@pipeline`).
+# -----------------------------------------------------------------------------------------
+
+def install_program(model: Graph, program: DatalogProgram, options):
+    declare_relations(model, program)
+    emit_pyrel(model, program)
+
+def declare_relations(model: Graph, program: DatalogProgram):
+    rel_names = {rule.head.rel_name for rule in program.rules}
+    rel_names.update(program.rel_attrs.keys())
+    rel_names.update(program.root_rel.keys())
+    for rel_name in rel_names:
+        declare_relation(model, rel_name, program)
+
+def declare_relation(model, rel_name, program):
+    T = model.Type("_pathfinder_dummy_type_for_predicate_declarations")
+    getattr(T, rel_name).declare()
+    pred = getattr(rel, rel_name)
+    for kind in program.rel_attrs.get(rel_name, []):
+        if kind == '@no_inline':
+            pred._rel.parents.append(Builtins.NoInlineAnnotation)
+        elif kind == '@inline':
+            pred._rel.parents.append(Builtins.InlineAnnotation)
+        elif kind == '@pipeline':
+            pred._rel.parents.append(Builtins.PipelineAnnotation)
+        elif kind == '@track':
+            pred._rel.parents.append(Builtins.TrackConnAnnotation)
+        else:
+            raise ValueError(f"Invalid predicate kind {kind}")
+
+def emit_pyrel(model: Graph, program: DatalogProgram):
+    for rule in program.rules:
+        if len(rule.body) == 0:
+            continue
+        with model.rule(dynamic=True):
+            rule_vars = create_vars(rule.n)
+            for atom in rule.body:
+                if isinstance(atom, RelAtom):
+                    getattr(rel, atom.rel_name)(*[rule_vars[v] for v in atom.vars])
+                elif isinstance(atom, AnonymousFilterAtom):
+                    atom.function(*[rule_vars[v] for v in atom.vars])
+                elif isinstance(atom, VariableEqualityAtom):
+                      rule_vars[atom.vars[0]]._wrapped_op(
+                          Builtins.eq, rule_vars[atom.vars[0]], rule_vars[atom.vars[1]])
+                elif isinstance(atom, ConstantEqualityAtom):
+                    rule_vars[atom.vars[0]]._wrapped_op(
+                        Builtins.eq, rule_vars[atom.vars[0]], atom.vars[1])
+                else:
+                    raise ValueError(f"Invalid atom {atom}")
+            getattr(rel, rule.head.rel_name).add(*[rule_vars[v] for v in rule.head.vars])

v0/relationalai/experimental/pathfinder/diagnostics.py

@@ -0,0 +1,56 @@
+from v0.relationalai.errors import RAIWarning, RAIException
+
+# -----------------------------------------------------------------------------------------
+# All User-facing diagnostic messages: Warnings and Errors
+# -----------------------------------------------------------------------------------------
+
+class PathfinderParameterWarning(RAIWarning):
+    def __init__(self, message: str):
+        super().__init__(message)
+
+class PathfinderSizeWarning(RAIWarning):
+    def __init__(self, pattern, prune_states_only: bool):
+        from v0.relationalai.experimental.pathfinder.rpq import RPQ
+        assert isinstance(pattern, RPQ)
+
+        message = f"WARNING: RPQ pattern is prohibitively large {len(pattern)} >= 50"
+        if prune_states_only:
+            message += "\nSkipping transitions pruning"
+            message += "\nUse 'force_transition_pruning=True' to force transition pruning"
+        super().__init__(message)
+
+class PathfinderNonDeterminismWarning(RAIWarning):
+    def __init__(self, pattern, a, prune_states_only: bool):
+        from v0.relationalai.experimental.pathfinder.rpq import RPQ
+        from v0.relationalai.experimental.pathfinder.automaton import Automaton
+        assert isinstance(pattern, RPQ)
+        assert isinstance(a, Automaton)
+
+        message = "WARNING: RPQ pattern is non-deterministic\n"
+        if prune_states_only:
+            message += "Using 'force_transition_pruning=True' may solve this issue\n"
+        message += str(pattern)
+        message += "\n"
+        for reason in a.determinism_report():
+            message += " *" + reason + '\n'
+        message += "Pathfinder may return duplicate results"
+        super().__init__(message)
+
+class PathfinderUngroundedPatternError(RAIException):
+    def __init__(self, pattern):
+        from v0.relationalai.experimental.pathfinder.rpq import RPQ
+        assert isinstance(pattern, RPQ)
+
+        message = "ERROR: Input RPQ pattern is ungrounded\n"
+        message += "Pattern potentially admits an infinite number of single-node paths\n"
+        message += str(pattern)
+        super().__init__(message)
+
+class PathfinderVoidPatternError(RAIException):
+    def __init__(self, pattern):
+        from v0.relationalai.experimental.pathfinder.rpq import RPQ
+        assert isinstance(pattern, RPQ)
+
+        message = "ERROR: Input RPQ pattern is void (admits no paths)\n"
+        message += str(pattern)
+        super().__init__(message)

v0/relationalai/experimental/pathfinder/filter.py

@@ -0,0 +1,236 @@
+import re
+from abc import ABC, abstractmethod
+from v0.relationalai.experimental.pathfinder.utils import get_lambda_str
+
+# =========================================================================================
+# Filters, and Labels
+# =========================================================================================
+#
+# Filters are building blocks of Regular Path Queries, in a analogous way to characters used
+# in a regular expression.  They specify constraints on nodes and edges on a path.
+# Consequently, they are also used in the transitions of automata that correspond to the
+# regular path patterns.
+#
+# Filter expressions are functions that filter nodes and edges of paths:
+#
+# _Node filter_ `ψ(x)` is a unary function `lambda x: test(x)` that takes a variable bounded
+# to a node and expresses assertions about the node.
+#
+# _Edge filter_ `φ(x, y)` is a binary function `lambda x, y: test(x,y)` that takes two
+# variables bound to endpoints of an edge, and expresses assertions about the nodes at the
+# endpoints.
+#
+# Their principal role of filters is to represent PyRel/Rel conditions that capture the
+# semantics of the filter. We distinguish two types of filters:
+#
+# * _Labels_ that specify a label (of a node or edge), and hence can ensure that the
+#   corresponding Rel filtering predicate is grounded. Consequently, they are also
+#   considered as _grounded filters_.
+# * _Anonymous filters_ that are anonymous lambda functions. Even though they may ground the
+#   corresponding Rel filtering predicate, it is impossible to verify this statically, and
+#   consequently they are not considered as grounded filters.
+#
+# We work with sets of filters and to avoid duplicates, we introduce rudimentary equality
+# and hashing functions. They are precise for labels, but for anonymous filters, they only
+# check for pointer equality. Also, we take rudimentary precautions to endure that the data
+# structures used to represent filters are treated as immutable.
+# =========================================================================================
+
+
+# -----------------------------------------------------------------------------------------
+# Abstract classes for Node and Edge filters
+# -----------------------------------------------------------------------------------------
+class NodeFilter(ABC):
+    @abstractmethod
+    def __repr__(self) -> str:
+        pass
+
+    @abstractmethod
+    def to_dict(self) -> dict:
+        pass
+
+    @abstractmethod
+    def is_grounded(self) -> bool:
+        pass
+
+class EdgeFilter(ABC):
+    @abstractmethod
+    def __repr__(self) -> str:
+        pass
+
+    @abstractmethod
+    def to_dict(self) -> dict:
+        pass
+
+    @abstractmethod
+    def is_grounded(self) -> bool:
+        pass
+
+# -----------------------------------------------------------------------------------------
+# Edge and Node labels
+# -----------------------------------------------------------------------------------------
+class NodeLabel(NodeFilter):
+    def __init__(self, label: str):
+        self._label = label
+
+    @property
+    def label(self):
+        return self._label
+
+    def __repr__(self) -> str:
+        return f'{self.label}'
+
+    def to_dict(self) -> dict:
+        return {
+            "type": "NodeLabel",
+            "label": self.label
+        }
+
+    def __eq__(self, other):
+        return isinstance(other, NodeLabel) and self.label == other.label
+
+    def __hash__(self):
+        return hash(self.label)
+
+    def is_grounded(self) -> bool:
+        return True
+
+class EdgeLabel(EdgeFilter):
+    def __init__(self, label: str, direction: str):
+        self._label = label
+        assert direction in ["forward", "backward"], f"Invalid direction: {direction}"
+        self._direction = direction
+
+    @property
+    def label(self) -> str:
+        return self._label
+
+    @property
+    def direction(self) -> str:
+        return self._direction
+
+    # when printing edge labels we avoid using `[...]` which tend to be interpreted as
+    # a control sequence when printing warnings by PyRel
+    def __str__(self) -> str:
+        if self.direction == "forward":
+            return f"-⟨{self.label}⟩→"
+        else:
+            return f"←⟨{self.label}⟩-"
+
+    def __repr__(self) -> str:
+        if self.direction == "forward":
+            return f"-[{self.label}]→"
+        else:
+            return f"←[{self.label}]-"
+
+    def to_dict(self) -> dict:
+        return {
+            "type": "EdgeLabel",
+            "label": self.label,
+            "direction": self.direction
+        }
+
+    def is_grounded(self) -> bool:
+        return True
+
+    def __eq__(self, other):
+        if isinstance(other, EdgeLabel):
+            return self.label == other.label and self.direction == other.direction
+        else:
+            return NotImplemented
+
+    def __hash__(self):
+        return hash((self.label, self.direction))
+
+REGEX_FORWARD_EDGE = re.compile(r'^-\[([a-zA-Z_][a-zA-Z0-9_]*?)\]->$')
+REGEX_BACKWARD_EDGE = re.compile(r'^<-\[([a-zA-Z_][a-zA-Z0-9_]*?)\]-$')
+REGEX_NODE = re.compile(r'^([a-zA-Z_][a-zA-Z0-9_]*?)$')
+
+#
+# Parses a string specification of a node or edge label:
+#
+# parse_label('N') = NodeLabel('N')
+# parse_label('-[R]->') = EdgeLabel('R', 'forward')
+# parse_label('<-[R]-') = EdgeLabel('R', 'backward')
+#
+def parse_label(lab: str):
+    from v0.relationalai.experimental.pathfinder.filter import NodeLabel, EdgeLabel
+    match_forward = REGEX_FORWARD_EDGE.search(lab)
+    if match_forward:
+        return EdgeLabel(match_forward.group(1), 'forward')
+
+    match_backward = REGEX_BACKWARD_EDGE.search(lab)
+    if match_backward:
+        return EdgeLabel(match_backward.group(1), 'backward')
+
+
+    match_node = REGEX_NODE.search(lab)
+    if match_node:
+        return NodeLabel(match_node.group(1))
+
+    raise Exception(f"Couldn't parse label '{lab}'")
+
+
+# -----------------------------------------------------------------------------------------
+# Anonymous node and edge filters
+# -----------------------------------------------------------------------------------------
+class AnonymousNodeFilter(NodeFilter):
+    def __init__(self, unary_function):
+        self._unary_function = unary_function
+
+    @property
+    def unary_function(self):
+        return self._unary_function
+
+    def __call__(self, x):
+        return self._unary_function(x)
+
+    def __eq__(self, other):
+        if isinstance(other, AnonymousNodeFilter):
+            return self._unary_function == other._unary_function
+        else:
+            return NotImplemented
+
+    def __hash__(self):
+        return hash(self._unary_function)
+
+    def __repr__(self) -> str:
+        return get_lambda_str(self._unary_function)
+
+    def to_dict(self) -> dict:
+        return {
+            "type": "AnonymousNodeFilter",
+            "function": get_lambda_str(self._unary_function)
+        }
+
+    def is_grounded(self) -> bool:
+        return False
+
+class AnonymousEdgeFilter(EdgeFilter):
+    def __init__(self, binary_function):
+        self._binary_function = binary_function
+
+    @property
+    def binary_function(self):
+        return self._binary_function
+
+    def __call__(self, x, y):
+        return self._binary_function(x, y)
+
+    def __eq__(self, other):
+        return isinstance(other, AnonymousEdgeFilter) and self._binary_function == other._binary_function
+
+    def __hash__(self):
+        return hash(self._binary_function)
+
+    def __repr__(self) -> str:
+        return get_lambda_str(self._binary_function)
+
+    def to_dict(self) -> dict:
+        return {
+            "type": "AnonymousEdgeFilter",
+            "function": get_lambda_str(self._binary_function)
+        }
+
+    def is_grounded(self) -> bool:
+        return False