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

relationalai/experimental/pathfinder/glushkov.py

@@ -0,0 +1,439 @@
+from typing import Dict, Set, Optional
+
+from relationalai.experimental.pathfinder.transition import (
+    NodeTransition, NodeFilter, EdgeTransition, EdgeFilter, EdgeLabel
+)
+from relationalai.experimental.pathfinder.automaton import Automaton
+
+# =========================================================================================
+# Glushkov Construction
+# =========================================================================================
+#
+# The Glushkov construction [1] allows to construct an automaton from a given regular
+# expression in a manner such that every (non-initial) state of the automaton corresponds to
+# a position of a specific edge label in the input expression.  This is an important
+# property, maintained throughout the whole integration, because it allows to provide
+# actionable diagnostic information to the user composing their queries.
+#
+# Strictly speaking, the construction does not construct a finite automata but its analogue
+# that we refer to as an _outline_.  The main difference is the lack of an initial state.
+# Outlines are, however, closed under the standard operations of regular expressions, such
+# as union, concatenation, and Kleene closure.  They allow to construct the final outline by
+# traversing the input regular expression in a bottom-up fashion.  The final outline is then
+# equipped with a single initial state.  The Glushkov construction is commonly used to
+# identify the class of Deterministic Regular Expressions, that yield a Deterministic Finite
+# Automata [2, 3].  We use it to check the determinism of the automaton representing the
+# input RPQ, which is essential for the correctness of Pathfinder execution.  More
+# importantly, the correspondence between the automaton states and positions of the Regular
+# Path Query shall allows to provide actionable diagnostic messages to the user composing
+# their queries [4].
+#
+# A Glushkov outline consist of a set of _positions_, each corresponding to a specific
+# occurrence of an edge label in the regular path query.  The transitions between the two
+# positions are encoded with edge transitions stored in the _follow_ relation.  An outline
+# does not have initial states: their role is played by the set of _first_ positions with
+# incoming edge transitions.  The essential property is  that an edge transition arriving in
+# a position has the same edge label as the position.  The final states are represented with
+# sets of _last_ positions with outgoing node transition that verifies any additional
+# conditions on the last node in a path that must be satisfied.  Finally, for completeness
+# an outline also has an _epsilon_ set of node transitions that allow to recognize empty
+# paths, consisting of a single node, which do not advance on any edge transition.
+#
+# -----------------------------------------------------------------------------------------
+# Glushkov automaton outline
+# -----------------------------------------------------------------------------------------
+# A Glushkov outline consists of:
+# - epsilon: {NodeTransition} -- epsilon transitions that allow to accept empty paths
+# - pos: {int} -- set of positions of the original regular path expression
+# - label: pos -> EdgeLabel -- edge labels of positions (edge labels of incoming transitions)
+# - first: pos -> {EdgeTransition} -- first positions with incoming edge-transitions
+# - follow: pos -> pos -> {EdgeTransition} -- follow transitions between positions
+# - last: pos -> {NodeTransition} -- last positions with outgoing ε-transitions
+#
+# In our constructions, we represent above functions with dicts. For simplicity, we
+# manipulate on _complete_ Glushkov outlines i.e., having all dicts total, possibly mapping
+# to a (vacuous) empty sets of transitions. These are removed in the final stage of
+# trimming.
+#
+# -----------------------------------------------------------------------------------------
+# Example
+# -----------------------------------------------------------------------------------------
+# We present an example of the Glushkov automaton outline for the following pattern
+#
+# path(Odd, star('-[A]->', Even)) | path('<-[B]-', N)
+#
+# which is parsed into the following RPQ (with 2 positions)
+#
+# ╷ Union
+# ├──┐ Concat
+# │  ├──╴ Node(Odd)
+# │  └──┐ Star
+# │     └──┐ Concat
+# │        ├──╴ Edge(-⟨A⟩→) pos=1
+# │        └──╴ Node(Even)
+# └──┐ Concat
+#    ├──╴ Edge(←⟨B⟩-) pos=2
+#    └──╴ Node(N)
+#
+# The Glushkov automaton outline follows (vacuous elements omitted):
+#  * epsilon:
+#    ⋅ ⊨⸨Odd⸩⇒
+#  * positions (label):
+#      1 -⟨A⟩→
+#      2 ←⟨B⟩-
+#  * first:
+#      → 1:
+#        ⋅ ⊨⸨Odd⸩=⟦-⟨A⟩→⟧=⸨⸩⇒
+#      → 2:
+#        ⋅ ⊨⸨⸩=⟦←⟨B⟩-⟧=⸨⸩⇒
+#  * follows:
+#     - 1
+#       → 1:
+#         ⋅ ⊨⸨Even⸩=⟦-⟨A⟩→⟧=⸨⸩⇒
+#  * last:
+#     - 1:
+#       ⋅ ⊨⸨Even⸩⇒
+#     - 2:
+#       ⋅ ⊨⸨N⸩⇒
+# -----------------------------------------------------------------------------------------
+#
+# References:
+# [1] Glushkov Automaton: https://en.wikipedia.org/wiki/Glushkov%27s_construction_algorithm
+# [2] Finite Automata: https://en.wikipedia.org/wiki/Nondeterministic_finite_automaton
+# [3] Deterministic FA: https://en.wikipedia.org/wiki/Deterministic_finite_automaton
+# [4] RPQs in Rel: https://docs.google.com/document/d/1GW71mJTCkCo8wPvOjGIKalUApPOZzKV-L7xHoD8Cel8
+# =========================================================================================
+
+
+class Glushkov:
+    def __init__(self,
+                 epsilon:  Set[NodeTransition],
+                 position: Set[int],
+                 label:    Dict[int, EdgeLabel],
+                 first:    Dict[int, Set[EdgeTransition]],
+                 follow:   Dict[int, Dict[int, Set[EdgeTransition]]],
+                 last:     Dict[int, Set[NodeTransition]]):
+
+        self.epsilon = epsilon
+        self.position = position
+        self.label = label
+        self.first = first
+        self.follow = follow
+        self.last = last
+
+        self.check_consistency()
+        self.check_completeness()
+
+    def check_consistency(self):
+        for pos in self.position:
+            assert pos in self.label, f"Position {pos} is missing a label"
+
+        for pos in self.label:
+            assert pos in self.position, f"Illegal position {pos} in label with {self.label[pos]}"
+
+        for pos in self.first:
+            assert pos in self.position, f"Illegal first position {pos}"
+        for pos in self.first:
+            for t in self.first[pos]:
+                fl = self.label[pos]
+                assert fl in t._edge_filters, f"Missing edge label filter {fl} in the transition {t} to the first position {pos}"
+                for f in t._edge_filters:
+                    if isinstance(f, EdgeLabel):
+                        assert f == fl, f"Edge label filter {f} of the transition {t} does not match the label {fl} of first postion {pos}"
+
+        for pos in self.follow:
+            assert pos in self.position, f"Illegal follow position {pos}"
+            for next_pos in self.follow[pos]:
+                assert next_pos in self.position, f"Illegal position {next_pos} following {pos}"
+                tl = self.label[next_pos]
+                for t in self.follow[pos][next_pos]:
+                    assert tl in t._edge_filters, f"Missing edge label filter {tl} in the transition {t} from {pos} to {next_pos}"
+                    for f in t._edge_filters:
+                        if isinstance(f, EdgeLabel):
+                            assert f == tl, f"Edge label {f} of the transition {t} from {pos} to {next_pos} does not match the label {tl}"
+        for pos in self.last:
+            assert pos in self.position, f"Illegal last position {pos} "
+
+    def check_completeness(self):
+        for pos in self.position:
+            assert pos in self.first, f"Missing first position {pos}"
+            assert pos in self.last, f"Missing last position {pos}"
+            assert pos in self.follow, f"Missing follow position {pos}"
+            for next_pos in self.position:
+                assert next_pos in self.follow[pos], f"Missing follow transition from {pos} to {next_pos}"
+
+    # Output a human-readable representation of the Glushkov outline.  Because Glushkov
+    # outlines uses complete dicts, we omit any empty elements that would otherwise create
+    # noise in the output.
+    def __repr__(self) -> str:
+        s = "Glushkov"
+        s += ":\n"
+
+        s += " * epsilon:\n"
+        for t in self.epsilon:
+            s += f"   ⋅ {t}\n"
+
+        s += " * positions (label): \n"
+        for pos in sorted(self.position):
+            s += f"     {pos} {self.label[pos]}\n"
+
+        s += " * first:\n"
+        for pos in sorted(self.first):
+            if len(self.first[pos]) == 0:
+                continue
+            s += f"     → {pos}: \n"
+            for t in self.first[pos]:
+                s += f"       ⋅ {t}\n"
+
+        s += " * follows: \n"
+        for pos in sorted(self.follow):
+            pos_printed = False
+            for next_pos in sorted(self.follow[pos]):
+                if len(self.follow[pos][next_pos]) == 0:
+                    continue
+                if not pos_printed:
+                    s += f"    - {pos}\n"
+                    pos_printed = True
+
+                s += f"      → {next_pos}:\n"
+                for t in self.follow[pos][next_pos]:
+                    s += f"        ⋅ {t}\n"
+
+        s += " * last: \n"
+        for pos in sorted(self.last):
+            if len(self.last[pos]) == 0:
+                continue
+            s += f"    - {pos}: \n"
+            for t in self.last[pos]:
+                s += f"      ⋅ {t}\n"
+
+        return s
+
+    def to_dict(self) -> dict:
+        return {
+            "type": "Glushkov",
+            "epsilon": [t.to_dict() for t in self.epsilon],
+            "position": list(sorted(self.position)),
+            "label": {pos: self.label[pos].to_dict() for pos in self.label},
+            "first": {pos: [t.to_dict() for t in self.first[pos]]
+                           for pos in self.first if len(self.first[pos]) > 0},
+            "follow": {pos: {next_pos: [t.to_dict() for t in self.follow[pos][next_pos]
+                                                    if len(self.follow[pos][next_pos]) > 0]
+                                       for next_pos in self.follow[pos]
+                                       if len(self.follow[pos][next_pos]) > 0}
+                            for pos in self.follow
+                            if any(len(self.follow[pos][next_pos]) > 0
+                                   for next_pos in self.follow[pos])},
+            "last": {pos: [t.to_dict() for t in self.last[pos]]
+                          for pos in self.last
+                          if len(self.last[pos]) > 0}
+        }
+
+    # Copy of the Glushkov outline up to transition sets (which are assumed immutable).
+    def copy(self) -> 'Glushkov':
+        epsilon = self.epsilon.copy()
+        position = self.position.copy()
+        label = self.label.copy()
+        first = {pos: self.first[pos].copy() for pos in self.first}
+        follow = {pos: {next_pos: self.follow[pos][next_pos].copy() for next_pos in self.follow[pos]} for pos in self.follow}
+        last = {pos: self.last[pos].copy() for pos in self.last}
+
+        return Glushkov(epsilon, position, label, first, follow, last)
+
+    # Constructs the Automaton from the Glushkov outline.
+    def automaton(self) -> Automaton:
+        states = self.position | {0}
+        init = {0}
+        delta = self.follow | {0: {p : self.first[p] for p in self.first}}
+        final = self.last
+        if len(self.epsilon) > 0:
+            final[0] = self.epsilon
+        return Automaton(states, init, delta, final)
+
+
+    # ------------------------------------------------------------------------
+    # Mutable operations used to build a new Glushkov automaton outline
+    # ------------------------------------------------------------------------
+
+    # adds a single epsilon transition
+    def _add_epsilon_transition(self, t: NodeTransition) -> None:
+        self.epsilon.add(t)
+
+    # adds all epsilon transitions from another Glushkov automaton outline
+    def _add_all_epsilon_transitions(self, other: 'Glushkov') -> None:
+        for t in other.epsilon:
+            self._add_epsilon_transition(t)
+
+    # adds a single position
+    def _add_position(self, pos: int, label: EdgeLabel) -> None:
+        assert pos not in self.position, f"Position {pos} already exists"
+        self.position.add(pos)
+        self.label[pos] = label
+        self.first[pos] = set()
+        self.follow[pos] = {next_pos: set() for next_pos in self.position}
+        for p in self.position:
+            if pos not in self.follow[p]:
+                self.follow[p][pos] = set()
+        self.last[pos] = set()
+
+    # add all positions from another Glushkov automaton
+    def _add_all_positions(self, other: 'Glushkov') -> None:
+        for pos in other.position:
+            self._add_position(pos, other.label[pos])
+
+    # adds a single first transition
+    def _add_first_transition(self, pos: int, t: EdgeTransition) -> None:
+        assert pos in self.position, f"Position {pos} missing"
+        assert self.label[pos] in t._edge_filters, f"Missing edge label filter {self.label[pos]} in the transition {t} to the first position {pos}"
+        self.first[pos].add(t)
+
+    # adds all first transitions from another Glushkov automaton outline
+    def _add_all_first_transitions(self, other: 'Glushkov') -> None:
+        for pos in other.first:
+            for t in other.first[pos]:
+                self._add_first_transition(pos, t)
+
+    # mutable operation
+    def _add_follow_transition(self, pos: int, next_pos: int, t: EdgeTransition) -> None:
+        assert pos in self.position, f"Source position {pos} missing"
+        assert next_pos in self.position, f"Target position {next_pos} missing"
+        assert self.label[next_pos] in t._edge_filters, f"Missing edge label filter {self.label[next_pos]} in the transition {t} from {pos} to {next_pos}"
+        self.follow[pos][next_pos].add(t)
+
+    # adds all follow transitions from another Glushkov automaton outline
+    def _add_all_follow_transitions(self, other: 'Glushkov') -> None:
+        for pos in other.follow:
+            for next_pos in other.follow[pos]:
+                for t in other.follow[pos][next_pos]:
+                    self._add_follow_transition(pos, next_pos, t)
+
+    # adds a single last transition
+    def _add_last_transition(self, pos: int, t: NodeTransition) -> None:
+        assert pos in self.position, f"Position {pos} missing"
+        self.last[pos].add(t)
+
+    # adds all last transitions from another Glushkov automaton outline
+    def _add_all_last_transitions(self, other: 'Glushkov') -> None:
+        for pos in other.last:
+            for t in other.last[pos]:
+                self._add_last_transition(pos, t)
+
+    # -------------------------------------------------------------------------------------
+    # Operations to build a Glushkov automata using base cases and RegEx operators.
+    # -------------------------------------------------------------------------------------
+
+    # The void language, empty set, `L(∅)`.
+    @staticmethod
+    def void() -> 'Glushkov':
+        return Glushkov(
+            epsilon = set(),
+            position = set(),
+            label = dict(),
+            first = dict(),
+            follow = dict(),
+            last = dict()
+        )
+
+    # The set of empty paths with single node satisfying given filters, L(ε(filter)),
+    @staticmethod
+    def node_transition(*filters: NodeFilter) -> 'Glushkov':
+        g = Glushkov.void()
+        g._add_epsilon_transition(NodeTransition(set(filters)))
+
+        return g
+
+    # The set of paths with a single edge satisfying given filters, L({()-[R(filter)]->()})
+    @staticmethod
+    def edge_transition(pos: int, edge_label: EdgeLabel, edge_filter: Optional[EdgeFilter]=None) -> 'Glushkov':
+        filters: Set[EdgeFilter] = {edge_label}
+        if edge_filter is not None:
+            filters.add(edge_filter)
+
+        g = Glushkov.void()
+        g._add_position(pos, edge_label)
+        g._add_first_transition(pos, EdgeTransition(set(), filters, set()))
+        g._add_last_transition(pos, NodeTransition())
+
+        return g
+
+    # `A |= B` recognizes the union `L(A|B) = L(A) ∪ L(B)`.
+    def __ior__(self, other):
+        self._add_all_epsilon_transitions(other)
+        self._add_all_positions(other)
+        self._add_all_first_transitions(other)
+        self._add_all_follow_transitions(other)
+        self._add_all_last_transitions(other)
+
+        return self
+
+    # `A *= B` recognizes the concatenation `L(A⋅B) = L(A)⋅L(B)`.
+    def __mul__(self, other: 'Glushkov') -> 'Glushkov':
+        # epsilon transitions are obtained by composing the epsilon transitions of A and B
+        _epsilon = self.epsilon.copy()
+        _last = self.last.copy()
+        self.epsilon.clear()
+        self.last = {pos: set() for pos in self.position}
+
+        # epsilon transitions
+        for e1 in _epsilon:
+            for e2 in other.epsilon:
+                self._add_epsilon_transition(e1 * e2)
+
+        # positions
+        self._add_all_positions(other)
+
+        # first transitions
+        # combine epsilon transitions of A with the first transitions of B
+        for last_pos in other.first:
+            for t in other.first[last_pos]:
+                for e in _epsilon:
+                    self._add_first_transition(last_pos, e * t)
+
+        # follow transitions
+        self._add_all_follow_transitions(other)
+        # combine last transitions of A with first transitions of B
+        for last_pos in _last:
+            for e in _last[last_pos]:
+                for first_pos in other.first:
+                    for t in other.first[first_pos]:
+                        self._add_follow_transition(last_pos, first_pos, e * t) # type: ignore
+
+        # last transitions
+        self._add_all_last_transitions(other)
+        # combine last transitions of A with epsilon transitions of B
+        for last_pos in _last:
+            for t in _last[last_pos]:
+                for e in other.epsilon:
+                    self._add_last_transition(last_pos, t * e)
+
+        return self
+
+    # `A.optional()` recognizes `L(A)? = L(A) ∪ L(ε)`.
+    def optional(self) -> 'Glushkov':
+        self._add_epsilon_transition(NodeTransition())
+
+        return self
+
+    # `A.plus()` recognizes Kleene's plus `L(A)+ = L(A) ∪ L(A)⋅L(A) ∪ L(A)⋅L(A)⋅L(A) ∪ …`.
+    def plus(self) -> 'Glushkov':
+        # combine last transitions with first transitions
+        for last_pos in self.last:
+            for first_pos in self.first:
+                for last_t in self.last[last_pos]:
+                    for first_t in self.first[first_pos]:
+                        self._add_follow_transition(last_pos, first_pos, last_t * first_t)
+
+        # Is seems unnecessary to combine first and lasts with epsilons.
+        #
+        # Thm. For any set of paths L and any set of empty paths E the following holds:
+        # >     (L ∪ Ε)+ = L+ ∪ E
+        #
+        # Proof:
+        # * the ⊇ direction is trivial
+        # * the ⊆ direction is easily proven by removing of E from the path derivation. □
+
+        return self
+
+    # `A.star()` recognizes Kleene's star `L(A)* = L(A)+ ∪ {ε}`.
+    def star(self) -> 'Glushkov':
+        return self.plus().optional()