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

v0/relationalai/experimental/pathfinder/transition.py

@@ -0,0 +1,200 @@
+
+from typing import List, FrozenSet, Union, Iterable
+from v0.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]

v0/relationalai/experimental/pathfinder/utils.py

@@ -0,0 +1,26 @@
+from typing import Callable
+from v0.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()

v0/relationalai/experimental/paths/api.py

@@ -0,0 +1,143 @@
+import typing
+from .rpq.rpq import RPQ, Segment, _process_segment, Star
+from .rpq.rpq import Node, Edge, Concat, Optional, Plus, Union
+from .rpq.filter import AnonymousNodeFilter
+from .find_paths_via_automaton import find_paths_via_automaton
+from .product_graph import project_product_graph_paths_to_original_graph
+
+from v0.relationalai.semantics import Concept, Relationship, define
+
+#-----------------------------------------------------------------------------
+# User-facing RPQ constructors
+#-----------------------------------------------------------------------------
+
+# (filter)
+def node_filter(filter: typing.Callable) -> RPQ:
+    from .rpq import Node
+
+    return Node(label = None, filter = AnonymousNodeFilter(filter))
+
+
+# (node_lab {∧ filter})
+def node(node_lab: typing.Union[str,Concept],
+         filter: typing.Optional[typing.Callable] = None) -> RPQ:
+    from .rpq.filter import NodeLabel, parse_label
+
+    filter = AnonymousNodeFilter(filter) if filter is not None else None
+
+    if isinstance(node_lab, Concept):
+        label = NodeLabel(node_lab._name)
+    else:
+        label = parse_label(node_lab)
+    assert isinstance(label, NodeLabel), f"Expected a node label, got {label}"
+
+    return Node(label, filter)
+
+# -[edge_lab {∧ filter}]- or <-[edge_lab {∧ filter}]-
+def edge(edge_lab:str, filter: typing.Optional[typing.Callable] = None) -> RPQ:
+    from .rpq.filter import EdgeLabel, AnonymousEdgeFilter, parse_label
+
+    label = parse_label(edge_lab)
+    assert isinstance(label, EdgeLabel), f"Expected an edge label, either `-[...]->` or `<-[...]-`, got {label}"
+    filter = AnonymousEdgeFilter(filter) if filter is not None else None
+    return Edge(label, filter)
+
+
+# (expr₁ ⋅ ... ⋅ exprₙ)
+def path(segment: Segment, *segments: Segment) -> RPQ:
+
+    pattern = _process_segment(segment)
+    for seg in segments:
+        pattern = Concat(pattern, _process_segment(seg))
+
+    return pattern
+
+# (expr₁ ⋅ ... ⋅ exprₙ)?
+def optional(*segments: Segment) -> RPQ:
+
+    return Optional(path(*segments))
+
+# (expr₁ ⋅ ... ⋅ exprₙ)+
+def plus(segment: Segment, *segments: Segment) -> RPQ:
+
+    return Plus(path(segment, *segments))
+
+# (expr₁ ⋅ ... ⋅ exprₙ)*
+def star(segment: Segment, *segments: Segment) -> RPQ:
+
+    return Star(path(segment, *segments))
+
+# (expr₁ | ... | exprₙ)
+def union(segment: Segment, *segments: Segment) -> RPQ:
+
+    pattern = _process_segment(segment)
+    for seg in segments:
+        pattern = Union(pattern, _process_segment(seg))
+
+    return pattern
+
+#-----------------------------------------------------------------------------
+# UI for path finding
+#-----------------------------------------------------------------------------
+
+
+def match(graph, pattern, source=None, target=None,
+          num_paths=None, max_length=1000,
+          type="shortest"):
+    """
+    Find paths matching a given pattern in the graph from src to dst.
+
+    Args:
+        graph: The graph
+        pattern: RPQ pattern
+        src: Source node entity
+        dst: Destination node entity
+
+    Returns:
+        Projected paths in the original graph
+    """
+
+    model = graph.model
+    Node = graph.Node
+
+    # Convert the pattern to an automaton
+    g = pattern.glushkov()
+    automaton = g.automaton()
+    automaton.reduce()
+
+    # Print the automaton for debugging
+    # print(automaton)
+
+    # Find paths via the automaton
+
+    # allow a single source node; if so, wrap it in a relationship:
+    if source is None:
+        Source = Node
+    elif isinstance(source, Concept) or isinstance(source, Relationship):
+        Source = source
+    else:
+        Source = model.Relationship(f"source {{{Node}}}")
+        define(Source(source))
+
+    if target is None:
+        Target = Node
+    elif isinstance(target, Concept) or isinstance(target, Relationship):
+        Target = target
+    else:
+        Target = model.Relationship(f"target {{{Node}}}")
+        define(Target(target))
+
+    # Source.inspect()
+    # Target.inspect()
+
+    product_graph, product_graph_paths = find_paths_via_automaton(
+        graph, automaton, Source, Target,
+        num_paths=num_paths, max_length=max_length,
+        type=type)
+
+    # Project the paths back to the original graph
+    projected_paths = project_product_graph_paths_to_original_graph(product_graph, product_graph_paths, automaton)
+
+    return projected_paths
+
+

v0/relationalai/experimental/paths/benchmarks/grid_graph.py

@@ -0,0 +1,37 @@
+from v0.relationalai.semantics import Integer, define, std
+from ..graph import Graph
+
+def create_labeled_grid(model, side_length, directed = True, label = "A"):
+    """
+    Create a grid Graph instance from a Model. The number of edges in each side of the grid
+    is given by the parameter `side`.
+    """
+    Node = model.Concept("GridNode")
+    Edge = model.Relationship(f"edge1 {{{Node}}} {{{Node}}} {{String}}")
+
+    n, m = Integer.ref(), Integer.ref()
+    u, v = Node.ref(), Node.ref()
+
+    define(Node.new(row = n, col = m)).where(
+        n == std.range(1, side_length + 2, 1),  # n + 1 nodes so n edges in each side
+        m == std.range(1, side_length + 2, 1)
+    )
+
+    define(Edge(u, v, label)).where(
+        Node(u),
+        Node(v),
+        u.row == v.row,
+        v.col == u.col + 1
+    )
+
+    define(Edge(u, v, label)).where(
+        Node(u),
+        Node(v),
+        u.col == v.col,
+        v.row == u.row + 1
+    )
+
+    if not directed:
+        define(Edge(u, v, label)).where(Edge(v, u, label))
+
+    return Graph(model, Node, Edge)

v0/relationalai/experimental/paths/examples/basic_example.py

@@ -0,0 +1,40 @@
+from v0.relationalai.semantics import Model, Integer, select, String, define
+from v0.relationalai.experimental.paths.graph import Graph
+from v0.relationalai.experimental.paths.api import path, star, match
+
+# Create an automaton that matches paths with pattern: A(A*)B:
+pattern = path("A", star("A"), "B")
+edge_list = [(1, 2, "A"), (2, 3, "A"), (3, 4, "A"), (4, 5, "B"), (1, 5, "A")]
+
+sources = [1]
+targets = [5]
+
+model = Model("my_paths")
+
+# create the graph:
+graph = Graph.from_edge_list(model, edge_list)
+Node = graph.Node
+
+# create source and target sets:
+Source = model.Relationship("source3 {Node}")
+Target = model.Relationship("target3 {Node}")
+
+for src in sources:
+    define(Source(graph.Node.new(id=src)))
+
+for tgt in targets:
+    define(Target(graph.Node.new(id=tgt)))
+
+paths = match(graph, pattern, Source, Target)
+
+i, k = Integer.ref(), Integer.ref()
+graph_node = graph.Node.ref()
+label = String.ref()
+
+result = select(i, k, label, graph_node.id).where(
+    paths(i, k, label, graph_node)
+)
+
+result.inspect()
+
+# print(result)

v0/relationalai/experimental/paths/examples/minimal_engine_warmup.py

@@ -0,0 +1,3 @@
+from v0.relationalai.semantics import select
+
+select(1 + 1).inspect()

v0/relationalai/experimental/paths/examples/movie_example.py

@@ -0,0 +1,77 @@
+from v0.relationalai.semantics import Model, select, define, data, String
+import pandas as pd
+
+model = Model("movies", dry_run=False)
+Concept, Relationship = model.Concept, model.Relationship
+
+Movie = Concept("Movie")
+Person = Concept("Person")
+Directed = Concept("Directed")
+ActedIn = Concept("ActedIn")
+
+
+data(pd.read_csv("movies_data/movies.csv")).into(Movie, keys=["id"])
+data(pd.read_csv("movies_data/person.csv")).into(Person, keys=["id"])
+data(pd.read_csv("movies_data/directed.csv")).into(Directed, keys=["id"])
+data(pd.read_csv("movies_data/actedin.csv")).into(ActedIn, keys=["id"])
+# data(pd.read_csv("examples/builder/actors.csv")).into(Person, keys=["actor_id"])
+
+# select(Person.name, Movie.title).where(
+#     Directed.from_ == Person.id,
+#     Directed.to == Movie.id
+# ).inspect()
+
+edge = Relationship("edge3 {String} {String} {String}")
+
+define(edge(Person.name, Movie.title, "directed")).where(
+    Directed.from_ == Person.id,
+    Directed.to == Movie.id
+)
+
+define(edge(Person.name, Movie.title, "acted_in")).where(
+    ActedIn.from_ == Person.id,
+    ActedIn.to == Movie.id
+)
+
+a, b, label = String.ref(), String.ref(), String.ref()
+select(a, b, label).where(edge(a, b, label)).inspect()
+
+
+
+
+# # define author relationship by matching author_id
+# define(Book.author(Author)).where(Author.author_id == Book.author_id)
+
+# # get each book title with its author's name
+# select(Book.title, Book.author.author_name).inspect()
+
+# # get each pair of books published n the same year
+# b = Book
+# b1 = Book.ref()
+# b2 = Book.ref()
+# where(
+#     b.publication_year == b1.publication_year,
+#     b.title < b1.title
+# ).select(b.title, b1.title).inspect()
+
+# # get each triple of books published in the same year
+# where(
+#     b.publication_year == b1.publication_year,
+#     b1.publication_year == b2.publication_year,
+#     b.title < b1.title,
+#     b1.title < b2.title
+# ).select(b.title, b1.title, b2.title).inspect()
+
+# # create a relationship for the author's published genres
+# Author.genres = Relationship("{Author} has published {genres:str*}")
+# # the Book.genre isn't necessary in the when, but the current rel
+# # backend fails otherwise
+# define(Author.genres(Book.genre)).where(Book.author == Author, Book.genre)
+
+# select(Author.author_name, Author.genres).inspect()
+
+# # get each author that has published in the dystopian genre and another genre
+# select(Author.author_name).where(
+#     Author.genres == "Dystopian",
+#     Author.genres.ref() != "Dystopian"
+# ).inspect()

v0/relationalai/experimental/paths/examples/paths_benchmark.py

@@ -0,0 +1,115 @@
+"""
+Example usage of automaton-based pathfinding.
+"""
+
+import time
+from v0.relationalai.semantics import Model, Integer, select, String, define
+from v0.relationalai.experimental.paths.graph import Graph
+from v0.relationalai.experimental.paths.api import node, path, match
+
+import argparse
+
+
+# def print_paths(path_node, path_label):
+#     # Print nodes and labels in a readable format
+#     l2 = String.ref()
+#     k = Integer.ref()
+#     m = Integer.ref()
+#     print("\nNodes and labels in the path on the original graph:")
+#     select(k, m, l2).where(
+#         path_node(k, m),
+#         path_label(k, label := String.ref()),
+#         l2 == strings.concat("-[", label, "]->")
+#     ).inspect()
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Pathfinder example script.")
+    parser.add_argument("--num_paths", type=int, default=None, help="Number of paths to find.")
+    args = parser.parse_args()
+
+    print("Number of paths to find:", args.num_paths)
+
+    # Create an automaton that matches paths with pattern: A(A*)B:
+    # pattern = path("-[A]->", star("-[A]->"), "-[B]->")
+    # edge_list = [(1, 2, "A"), (2, 3, "A"), (3, 4, "A"), (4, 5, "B"), (1, 5, "A")]
+
+    # 2 paths matching AB:
+    # pattern = path("-[A]->", "-[B]->")
+    # edge_list = [(1, 2, "A"), (2, 3, "B"), (1, 4, "A"), (4, 3, "B")]
+
+    
+
+    # pattern = path("-[A]->")
+    # edge_list = [(1, 3, "A"), (2, 3, "A")]
+
+    pattern = path("A")
+    # edge_list = [(1, 3, "A"), (2, 3, "A"), (1, 4, "A"), (2, 4, "A")]
+    edge_list = [(1, 2, "A")]
+
+
+    sources = []
+    targets = []
+
+    sources = [1]
+    targets = [2]
+
+    # pattern = path("-[A]->")
+    # edge_list = [(1, 3, "A"), (2, 3, "A"), (1, 4, "A"), (2, 4, "A")]
+
+    # sources = [1, 2]
+    # targets = [3, 4]
+    # 2 paths from 2 different source nodes:
+    # pattern = path("-[A]->")
+    # edge_list = [(1, 3, "A"), (2, 3, "A")]
+
+    # pattern = path("-[A]->")
+    # edge_list = [(1, 3, "A"), (2, 3, "A"), (1, 4, "A"), (2, 4, "A")]
+
+
+    print("\nEdge list:\n", edge_list)
+
+    # Initialize the RelationalAI model
+    model = Model("paths", use_lqp=True) # , use_lqp=True)  # strict=True  # dry_run=False  # use_direct_access=True
+    # use_lqp=True  # strict=True  # dry_run=False  # use_direct_access=True
+
+    # model.define(
+    #     RawSource("rel", "@span_no_threshold")
+    # )
+
+    graph = Graph.from_edge_list(model, edge_list)
+    Node = graph.Node
+
+    # Call the function to find the path
+
+    Source = model.Relationship(f"source5 {{{Node}}}")
+    Target = model.Relationship(f"target5 {{{Node}}}")
+
+    for src in sources:
+        define(Source(Node.new(id=src)))
+
+    for tgt in targets:
+        define(Target(Node.new(id=tgt)))
+
+    src, tgt = Node.ref(), Node.ref()
+
+    # select(graph.Node).inspect()
+
+    graph.Edge.inspect()
+    select(src).where(Source(src)).inspect()
+    select(tgt).where(Target(tgt)).inspect()
+
+    # print(f"\nFinding paths matching the automaton pattern from {src} to {dst}..."
+    # projected_paths = match(graph, pattern, Source, Target, num_paths=args.num_paths)
+
+    start = time.time()
+    projected_paths = match(graph, pattern, Source, Target)
+
+    i, k = Integer.ref(), Integer.ref()
+    node = graph.Node.ref()
+    label = String.ref()
+
+    result = select(i, k, label, node.id).where(projected_paths(i, k, label, node)).inspect()
+    end = time.time()
+
+    print(f"Time taken to find paths: {end - start} seconds")