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

v0/relationalai/experimental/pathfinder/options.py

@@ -1,265 +0,0 @@
-from v0.relationalai.experimental.pathfinder.diagnostics import PathfinderParameterWarning
-from v0.relationalai.debugging import warn, logger
-from typing import Callable
-from v0.relationalai.dsl import Instance, Type, Graph
-
-
-# ----------------------------------------------------------------------------------------
-# Options controlling the execution of the Pathfinder PyRel integration
-# ----------------------------------------------------------------------------------------
-#
-# The options used to control the execution of the Pathfinder PyRel integration are stored
-# in a simple dictionary mapping strings to values (typically string, ints, and Booleans).
-# For a streamline use, this dictionary will be a total mapping from the set of all
-# possible options, with `None` used if the given option is not applicable (e.g., the number
-# of paths to compute is only specified when the LIMIT selector is to be used).
-#
-# The options are:
-# ## Pathfinder Rel config values
-# * `graph_type` ∈ {'labeled', 'unlabeled'} (currently, only 'labeled' is supported).
-# * `semantics` ∈ {'shortest_paths', 'walks'}.
-# * `max_path_length`: Optional[int]; the maximum length of the paths when `semantics` is
-#   'walks'; otherwise None.
-# * `group` ∈ {'for_any' , 'for_each_source'}
-# * `selector` ∈ {'all', 'single', 'limit'}
-# * `path_count`: Optional[int]; the number of paths to return when `selector` is 'limit';
-#   otherwise None
-# * `search_strategy` ∈ {'from_source', 'from_target', 'from_both_sides'} graph exploration
-#   strategy (default is 'from_both_sides');
-# * `search_radius` ∈ {'unbounded', 'bounded'} toggle indicating whether graph exploration
-#   should span the whole graph or stop whenever a target node is found (default is
-#   'bounded');
-# ## Optional input arguments
-# * `source`: Optional[Type] or Optional[Callable]; optional specification of the source
-#   node relation; by default (projection of) the connectivity relation is used to identify
-#   potential sources.
-# * `target`: Optional[Type] or Optional[Callable]; optional specification of the target
-#   node relation; by default (projection of) the connectivity relation is used to identify
-#   potential targets.
-# * 'pathfinder_lib_version': str; the version of the Pathfinder library to use.
-#    (default "0.7.0")
-## Integration control options
-# * `force_transition_pruning`: bool; if True, the automaton transition pruning is forced;
-#   otherwise, pruning happens only if the size is not too big (<50).
-# * `suppress_groundedness_test`: bool; if True, we do not raise an error when the input
-#   automaton is ungrounded; default is False.
-# * `model`: Optional[Graph]; the model to use for emitting the rules. If None, the
-#   a default model is retrieved from the model stack (see utils.get_model).
-#
-
-DEFAULT_OPTIONS = {
-    'graph_type': 'labeled',
-    'semantics': 'shortest_paths',
-    'max_path_length': None,
-    'group': 'for_any',
-    'selector': 'all',
-    'path_count': None,
-    'search_strategy': 'from_both_sides',
-    'search_radius': 'bounded',
-    'source': None,
-    'target': None,
-    'pathfinder_lib_version': '0.7.0',
-    'force_transition_pruning': False,
-    'suppress_groundedness_test': False,
-    'model' : None
-}
-
-
-# -----------------------------------------------------------------------------------------
-# The user-facing PyRel pathfinder functions, `find_paths` and `conn`, accept the following
-# keyword _params_:
-# * `max_path_length`: Optional[int] (default: None); the maximum length of the paths to be
-#   computed. If max_path_length os None, the shortest paths are computed only.
-# * `limit`: Optional[int] (default: None); whether all paths should be returned (None) or
-#   only the first k paths.
-# * `from_source` and `from_target`: Optional[bool] (default: False); whether the search
-#   should be done from the source nodes or target nodes respectively. Only one of
-#   `from_source` and `from_target` can be set to True. If both are False, the search is
-#   done from both sides.
-# * `for_each_source`: Optional[bool] (default: False); whether the search should be done
-#   for each source node separately. If False, the search is done for any pair of source and
-#   target nodes. This option is only supported for the shortest path semantics; When walks
-#   semantics is selected (by using `max_path_length`), this option is ignored.
-# * `unbounded`: Optional[bool] (default: False); whether the search should be
-#   unbounded or bounded.
-# * `source`: Optional[Type] or Optional[Callable]; the source node relation specification.
-# * `target`: Optional[Type] or Optional[Callable]; the target node relation specification.
-# * `force_transition_pruning`: Optional[bool] (default: False); whether the FA transition
-#   pruning should be forced if the FA is too big (>50 states).
-# * `suppress_groundedness_test`: bool; if True, we will not raises an error when the input
-#   automaton is ungrounded; default is False.
-# * `pathfinder_lib_version`: str; the version of the Pathfinder library to use.
-#   (default "0.7.0")
-# ----------------------------------------------------------------------------------------
-
-PARAM_NAMES = [
-    'max_path_length',
-    'limit',
-    'from_source',
-    'from_target',
-    'for_each_source',
-    'unbounded',
-    'source',
-    'target',
-    'force_transition_pruning',
-    'suppress_groundedness_test',
-    'pathfinder_lib_version'
-]
-
-
-def normalized_options(params):
-
-    logger.info("Normalizing parameters...")
-    for k, v in params.items():
-        logger.info(f"  {k}: {v}")
-        if k not in PARAM_NAMES:
-            warn(PathfinderParameterWarning(
-                f"Unknown parameter '{k}' ignored."
-            ))
-
-    # pathfinder_lib_version (grab)
-    pathfinder_lib_version = params.get('pathfinder_lib_version',
-                                        DEFAULT_OPTIONS['pathfinder_lib_version'])
-    assert pathfinder_lib_version in ["0.7.0"], "`pathfinder_lib_version` parameter is an invalid library version"
-
-    # graph_type
-    graph_type = "labeled"
-
-    # max_path_length (grab)
-    max_path_length = None
-    if 'max_path_length' in params:
-        max_path_length = params['max_path_length']
-        if not isinstance(max_path_length, Instance):
-            assert type(max_path_length) is int and max_path_length >= 0, "`max_path_length` parameter must be a non-negative integer"
-
-
-    # semantics (grab)
-    if max_path_length is None:
-        semantics = 'shortest_paths'
-    else:
-        semantics = 'walks'
-
-    # path_count (grab)
-    path_count = None
-    if 'limit' in params:
-        path_count = params['limit']
-        if not isinstance(path_count, Instance):
-            assert type(path_count) is int and path_count > 0, "`limit` parameter must be a positive integer"
-
-
-    # selector (grab)
-    if path_count is None:
-        selector = 'all'
-    elif path_count == 1:
-        selector = 'single'
-    else:
-        selector = "limit"
-
-
-    # group (grab)
-    group = 'any_pair'
-    assert 'for_each_source' not in params or type(params['for_each_source']) is bool, "`for_each_source` parameter must be a boolean"
-    if 'for_each_source' in params and params['for_each_source']:
-        group = 'for_each_source'
-    # group (check)
-    if group == 'for_each_source' and semantics == 'walks':
-        warn(PathfinderParameterWarning(
-            "The option `for_each_source=True` is ignored when "
-            "the option `max_path_length` is used."
-        ))
-        group = 'any_pair'
-    if group == 'for_each_source' and selector in ['single', 'limit']:
-        warn(PathfinderParameterWarning(
-            "The option `for_each_source=True` is ignored when "
-            "the option `limit` is used."
-        ))
-        group = 'any_pair'
-
-
-    # search_strategy (grab)
-    search_strategy = 'from_both_sides'
-    assert 'from_source' not in params or type(params['from_source']) is bool, "`from_source` parameter must be a boolean"
-    assert 'from_target' not in params or type(params['from_target']) is bool, "`from_target` parameter must be a boolean"
-    if 'from_source' in params and params['from_source']:
-        search_strategy = 'from_source'
-    elif 'from_target' in params and params['from_target']:
-        search_strategy = 'from_target'
-    # search_strategy (check)
-    if group == 'for_each_source' and search_strategy != 'from_source':
-        warn(PathfinderParameterWarning(
-            "The parameter `for_each_source=True` forces the parameter `from_source=True`. "
-            "Parameters selecting other search strategy, like `from_target=True`, are ignored."
-        ))
-        search_strategy = 'from_source'
-    if (group == 'any_pair' and search_strategy == 'from_source' and
-        'from_target' in params and params['from_target']):
-        warn(PathfinderParameterWarning(
-            "The parameter `from_source=True` supersedes the parameter `from_target=True`. "
-            "The parameter `from_target=True` is ignored."
-        ))
-
-
-    # search_radius (grab)
-    search_radius = 'bounded'
-    assert 'unbounded' not in params or type(params['unbounded']) is bool, "`unbounded` parameter must be a boolean"
-    if 'unbounded' in params and params['unbounded']:
-        search_radius = 'unbounded'
-    # search_radius (check)
-    if search_radius == 'unbounded' and semantics == 'walks':
-        warn(PathfinderParameterWarning(
-            "The parameter `unbounded=True` is ignored when "
-            "the parameter `max_path_length` is used."
-        ))
-        search_radius = 'bounded'
-    if search_radius == 'unbounded' and search_strategy == 'from_both_sides':
-        warn(PathfinderParameterWarning(
-            "The parameter `unbounded=True` has effect only when used with one of the parameters "
-            "`from_source=True` or `from_target=True; The parameter `unbounded=True` is ignored."
-        ))
-        search_radius = 'bounded'
-
-
-    # source and target (grab)
-    source = params.get("source", None)
-    target = params.get("target", None)
-    # source and target (check)
-    if source is not None and not isinstance(source, (Type, Callable)):
-        warn(PathfinderParameterWarning(
-            "Ignoring parameter `source`: must be a Type or a function"
-        ))
-        source, target = None, None
-
-    if target is not None and not isinstance(target, (Type, Callable)):
-        warn(PathfinderParameterWarning(
-            "Ignoring parameter `source`: must be a Type or a lambda expression"
-        ))
-        source, target = None, None
-
-    # force_transition_pruning (grab)
-    force_transition_pruning = params.get("force_transition_pruning", False)
-    assert type(force_transition_pruning) is bool, "`force_transition_pruning` parameter must be a boolean"
-
-    # suppress_groundedness_test (grab)
-    suppress_groundedness_test = params.get("suppress_groundedness_test", False)
-    assert type(suppress_groundedness_test) is bool, "`suppress_groundedness_test` parameter must be a boolean"
-
-    # model (grab)
-    model = params.get("model", None)
-    assert model is None or isinstance(model, Graph), "`model` parameter must be a Graph instance"
-
-    return {
-        'graph_type': graph_type,
-        'semantics': semantics,
-        'group': group,
-        'selector': selector,
-        'search_strategy': search_strategy,
-        'search_radius': search_radius,
-        'source': source,
-        'target': target,
-        'max_path_length': max_path_length,
-        'path_count': path_count,
-        'pathfinder_lib_version': pathfinder_lib_version,
-        'force_transition_pruning': force_transition_pruning,
-        'suppress_groundedness_test': suppress_groundedness_test,
-        'model': model
-    }

v0/relationalai/experimental/pathfinder/rpq.py

@@ -1,344 +0,0 @@
-from abc import ABC, abstractmethod
-import typing
-from v0.relationalai.experimental.pathfinder.glushkov import Glushkov
-from v0.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
-        }