lionagi 0.0.312__py3-none-any.whl → 0.2.1__py3-none-any.whl

lionagi/core/generic/graph.py

@@ -0,0 +1,236 @@
+import contextlib
+from collections import deque
+from typing import Any
+
+from lionagi.libs.ln_convert import to_list
+from lionagi.core.collections.abc import (
+    Condition,
+    Actionable,
+    LionTypeError,
+    ItemNotFoundError,
+    LionIDable,
+)
+from lionagi.core.collections import pile, Pile
+
+from lionagi.core.generic.edge import Edge
+from lionagi.core.generic.node import Node
+
+
+class Graph(Node):
+    """Represents a graph structure with nodes and edges."""
+
+    internal_nodes: Pile = pile()
+
+    @property
+    def internal_edges(self) -> Pile[Edge]:
+        """Return a pile of all edges in the graph."""
+        return pile(
+            {edge.ln_id: edge for node in self.internal_nodes for edge in node.edges},
+            Edge,
+        )
+
+    def is_empty(self) -> bool:
+        """Check if the graph is empty (has no nodes)."""
+        return self.internal_nodes.is_empty()
+
+    def clear(self):
+        """Clear all nodes and edges from the graph."""
+        self.internal_nodes.clear()
+
+    def add_edge(
+        self,
+        head: Node,
+        tail: Node,
+        condition: Condition | None = None,
+        bundle=False,
+        label=None,
+        **kwargs,
+    ):
+        """Add an edge between two nodes in the graph."""
+        if isinstance(head, Actionable):
+            raise LionTypeError("Actionable nodes cannot be related as head.")
+        if isinstance(tail, Actionable):
+            bundle = True
+
+        self.internal_nodes.include(head)
+        self.internal_nodes.include(tail)
+
+        head.relate(
+            tail,
+            direction="out",
+            condition=condition,
+            label=label,
+            bundle=bundle,
+            **kwargs,
+        )
+
+    def remove_edge(self, edge: Any) -> bool:
+        """Remove an edge from the graph."""
+        edge = edge if isinstance(edge, list) else [edge]
+        for i in edge:
+            if i not in self.internal_edges:
+                raise ItemNotFoundError(f"Edge {i} does not exist in structure.")
+            with contextlib.suppress(ItemNotFoundError):
+                self._remove_edge(i)
+
+    def add_node(self, node: Any) -> None:
+        """Add a node to the graph."""
+        self.internal_nodes.update(node)
+
+    def get_node(self, item: LionIDable, default=...):
+        """Get a node from the graph by its identifier."""
+        return self.internal_nodes.get(item, default)
+
+    def get_node_edges(
+        self,
+        node: Node | str,
+        direction: str = "both",
+        label: list | str = None,
+    ) -> Pile[Edge] | None:
+        """Get the edges of a node in the specified direction and with the given label."""
+        node = self.internal_nodes[node]
+        edges = None
+        match direction:
+            case "both":
+                edges = node.edges
+            case "head" | "predecessor" | "outgoing" | "out" | "predecessors":
+                edges = node.relations["out"]
+            case "tail" | "successor" | "incoming" | "in" | "successors":
+                edges = node.relations["in"]
+
+        if label:
+            return (
+                pile(
+                    [
+                        edge
+                        for edge in edges
+                        if edge.label in to_list(label, dropna=True, flatten=True)
+                    ]
+                )
+                if edges
+                else None
+            )
+        return pile(edges) if edges else None
+
+    def pop_node(self, item, default=...):
+        """Remove and return a node from the graph by its identifier."""
+        return self.internal_nodes.pop(item, default)
+
+    def remove_node(self, item):
+        """Remove a node from the graph by its identifier."""
+        return self.internal_nodes.remove(item)
+
+    def _remove_edge(self, edge: Edge | str) -> bool:
+        """Remove a specific edge from the graph."""
+        if edge not in self.internal_edges:
+            raise ItemNotFoundError(f"Edge {edge} does not exist in structure.")
+
+        edge = self.internal_edges[edge]
+        head: Node = self.internal_nodes[edge.head]
+        tail: Node = self.internal_nodes[edge.tail]
+
+        head.unrelate(tail, edge=edge)
+        return True
+
+    def get_heads(self) -> Pile:
+        """Get all head nodes in the graph."""
+        return pile(
+            [
+                node
+                for node in self.internal_nodes
+                if node.relations["in"].is_empty() and not isinstance(node, Actionable)
+            ]
+        )
+
+    def is_acyclic(self) -> bool:
+        """Check if the graph is acyclic (contains no cycles)."""
+        node_ids = list(self.internal_nodes.keys())
+        check_deque = deque(node_ids)
+        check_dict = {key: 0 for key in node_ids}  # 0: not visited, 1: temp, 2: perm
+
+        def visit(key):
+            if check_dict[key] == 2:
+                return True
+            elif check_dict[key] == 1:
+                return False
+
+            check_dict[key] = 1
+
+            for edge in self.internal_nodes[key].relations["out"]:
+                check = visit(edge.tail)
+                if not check:
+                    return False
+
+            check_dict[key] = 2
+            return True
+
+        while check_deque:
+            key = check_deque.pop()
+            check = visit(key)
+            if not check:
+                return False
+        return True
+
+    def to_networkx(self, **kwargs) -> Any:
+        """Convert the graph to a NetworkX graph object."""
+        from lionagi.libs import SysUtil
+
+        SysUtil.check_import("networkx")
+
+        from networkx import DiGraph
+
+        g = DiGraph(**kwargs)
+        for node in self.internal_nodes:
+            node_info = node.to_dict()
+            node_info.pop("ln_id")
+            node_info.update({"class_name": node.class_name})
+            g.add_node(node.ln_id, **node_info)
+
+        for _edge in self.internal_edges:
+            edge_info = _edge.to_dict()
+            edge_info.pop("ln_id")
+            edge_info.update({"class_name": _edge.class_name})
+            source_node_id = edge_info.pop("head")
+            target_node_id = edge_info.pop("tail")
+            g.add_edge(source_node_id, target_node_id, **edge_info)
+
+        return g
+
+    def display(self, **kwargs):
+        """Display the graph using NetworkX and Matplotlib."""
+        from lionagi.libs import SysUtil
+
+        SysUtil.check_import("networkx")
+        SysUtil.check_import("matplotlib", "pyplot")
+
+        import networkx as nx
+        import matplotlib.pyplot as plt
+
+        g = self.to_networkx(**kwargs)
+        pos = nx.spring_layout(g)
+        nx.draw(
+            g,
+            pos,
+            edge_color="black",
+            width=1,
+            linewidths=1,
+            node_size=500,
+            node_color="orange",
+            alpha=0.9,
+            labels=nx.get_node_attributes(g, "class_name"),
+        )
+
+        labels = nx.get_edge_attributes(g, "label")
+        labels = {k: v for k, v in labels.items() if v}
+
+        if labels:
+            nx.draw_networkx_edge_labels(
+                g, pos, edge_labels=labels, font_color="purple"
+            )
+
+        plt.axis("off")
+        plt.show()
+
+    def size(self) -> int:
+        """Return the number of nodes in the graph."""
+        return len(self.internal_nodes)

lionagi/core/generic/hyperedge.py

@@ -0,0 +1 @@
+# TODO

lionagi/core/generic/node.py

@@ -0,0 +1,220 @@
+"""
+This module defines the Node class, representing a node in a graph-like
+structure within LionAGI. Nodes can form relationships with other nodes
+through directed edges, enabling construction and manipulation of complex
+relational networks.
+
+Includes functionality for managing relationships, such as adding,
+modifying, and removing edges, and querying related nodes and connections.
+"""
+
+from pydantic import Field
+from pandas import Series
+
+from lionagi.libs.ln_convert import to_list
+
+from lionagi.core.collections.abc import (
+    Component,
+    Condition,
+    Relatable,
+    RelationError,
+    get_lion_id,
+)
+from lionagi.core.collections import pile, Pile
+from lionagi.core.generic.edge import Edge
+
+
+class Node(Component, Relatable):
+    """
+    Node in a graph structure, can connect to other nodes via edges.
+
+    Extends `Component` by incorporating relational capabilities, allowing
+    nodes to connect through 'in' and 'out' directed edges, representing
+    incoming and outgoing relationships.
+
+    Attributes:
+        relations (dict[str, Pile]): Dictionary holding 'Pile' instances
+            for incoming ('in') and outgoing ('out') edges.
+    """
+
+    relations: dict[str, Pile] = Field(
+        default_factory=lambda: {"in": pile(), "out": pile()},
+        description="The relations of the node.",
+    )
+
+    @property
+    def edges(self) -> Pile[Edge]:
+        """
+        Get unified view of all incoming and outgoing edges.
+
+        Returns:
+            Combined pile of all edges connected to this node.
+        """
+        return self.relations["in"] + self.relations["out"]
+
+    @property
+    def related_nodes(self) -> list[str]:
+        """
+        Get list of all unique node IDs directly related to this node.
+
+        Returns:
+            List of node IDs related to this node.
+        """
+        all_nodes = set(
+            to_list([[i.head, i.tail] for i in self.edges], flatten=True, dropna=True)
+        )
+        all_nodes.discard(self.ln_id)
+        return list(all_nodes)
+
+    @property
+    def node_relations(self) -> dict:
+        """
+        Get categorized view of direct relationships into groups.
+
+        Returns:
+            Dict with keys 'in' and 'out', each containing a mapping of
+            related node IDs to lists of edges representing relationships.
+        """
+        out_node_edges = {}
+        if not self.relations["out"].is_empty():
+            for edge in self.relations["out"]:
+                for node_id in self.related_nodes:
+                    if edge.tail == node_id:
+                        out_node_edges.setdefault(node_id, []).append(edge)
+
+        in_node_edges = {}
+        if not self.relations["in"].is_empty():
+            for edge in self.relations["in"]:
+                for node_id in self.related_nodes:
+                    if edge.head == node_id:
+                        in_node_edges.setdefault(node_id, []).append(edge)
+
+        return {"out": out_node_edges, "in": in_node_edges}
+
+    @property
+    def predecessors(self) -> list[str]:
+        """
+        Get list of IDs of nodes with direct incoming relation to this.
+
+        Returns:
+            List of node IDs that precede this node.
+        """
+        return [
+            node_id for node_id, edges in self.node_relations["in"].items() if edges
+        ]
+
+    @property
+    def successors(self) -> list[str]:
+        """
+        Get list of IDs of nodes with direct outgoing relation from this.
+
+        Returns:
+            List of node IDs that succeed this node.
+        """
+        return [
+            node_id for node_id, edges in self.node_relations["out"].items() if edges
+        ]
+
+    def relate(
+        self,
+        node: "Node",
+        direction: str = "out",
+        condition: Condition | None = None,
+        label: str | None = None,
+        bundle: bool = False,
+    ) -> None:
+        """
+        Establish directed relationship from this node to another.
+
+        Args:
+            node: Target node to relate to.
+            direction: Direction of edge ('in' or 'out'). Default 'out'.
+            condition: Optional condition to associate with edge.
+            label: Optional label for edge.
+            bundle: Whether to bundle edge with others. Default False.
+
+        Raises:
+            ValueError: If direction is neither 'in' nor 'out'.
+        """
+        if direction not in ["in", "out"]:
+            raise ValueError(
+                f"Invalid value for direction: {direction}, " "must be 'in' or 'out'"
+            )
+
+        edge = Edge(
+            head=self if direction == "out" else node,
+            tail=node if direction == "out" else self,
+            condition=condition,
+            bundle=bundle,
+            label=label,
+        )
+
+        self.relations[direction].include(edge)
+        node.relations["in" if direction == "out" else "out"].include(edge)
+
+    def remove_edge(self, node: "Node", edge: Edge | str) -> bool:
+        """
+        Remove specified edge or all edges between this and another node.
+
+        Args:
+            node: Other node involved in edge.
+            edge: Specific edge to remove or 'all' to remove all edges.
+
+        Returns:
+            True if edge(s) successfully removed, False otherwise.
+
+        Raises:
+            RelationError: If removal fails or edge does not exist.
+        """
+        edge_piles = [
+            self.relations["in"],
+            self.relations["out"],
+            node.relations["in"],
+            node.relations["out"],
+        ]
+
+        if not all(pile.exclude(edge) for pile in edge_piles):
+            raise RelationError(f"Failed to remove edge between nodes.")
+        return True
+
+    def unrelate(self, node: "Node", edge: Edge | str = "all") -> bool:
+        """
+        Remove all or specific relationships between this and another node.
+
+        Args:
+            node: Other node to unrelate from.
+            edge: Specific edge to remove or 'all' for all. Default 'all'.
+
+        Returns:
+            True if relationships successfully removed, False otherwise.
+
+        Raises:
+            RelationError: If operation fails to unrelate nodes.
+        """
+        if edge == "all":
+            edges = self.node_relations["out"].get(
+                node.ln_id, []
+            ) + self.node_relations["in"].get(node.ln_id, [])
+        else:
+            edges = [get_lion_id(edge)]
+
+        if not edges:
+            raise RelationError(f"Node is not related to {node.ln_id}.")
+
+        try:
+            for edge_id in edges:
+                self.remove_edge(node, edge_id)
+            return True
+        except RelationError as e:
+            raise e
+
+    def __str__(self):
+        _dict = self.to_dict()
+        _dict["relations"] = [
+            len(self.relations["in"]),
+            len(self.relations["out"]),
+        ]
+        return Series(_dict).__str__()
+
+    def __repr__(self):
+        return self.__str__()

lionagi/core/generic/tree.py

@@ -0,0 +1,48 @@
+"""This module provides tree structure."""
+
+from pydantic import Field
+from lionagi.core.collections.abc import Condition
+from lionagi.core.collections.util import to_list_type
+from lionagi.core.generic.tree_node import TreeNode
+from lionagi.core.generic.graph import Graph
+
+
+class Tree(Graph):
+    """
+    Represents a tree structure, extending the graph with tree-specific functionalities.
+
+    Manages parent-child relationships within the tree.
+
+    Attributes:
+        root (TreeNode | None): The root node of the tree. Defaults to None.
+    """
+
+    root: TreeNode | None = Field(
+        default=None, description="The root node of the tree graph."
+    )
+
+    def relate_parent_child(
+        self,
+        parent: TreeNode,
+        children,
+        condition: Condition | None = None,
+        bundle: bool = False,
+    ) -> None:
+        """
+        Establishes parent-child relationships between the given parent and child node(s).
+
+        Args:
+            parent (TreeNode): The parent node.
+            children (list[TreeNode]): A list of child nodes.
+            condition (Condition | None): The condition associated with the relationships, if any.
+            bundle (bool): Indicates whether to bundle the relations into a single
+                           transaction. Defaults to False.
+        """
+
+        for i in to_list_type(children):
+            i.relate_parent(parent, condition=condition, bundle=bundle)
+
+        if self.root is None:
+            self.root = parent
+
+        self.add_node([parent, *children])

lionagi/core/generic/tree_node.py

@@ -0,0 +1,79 @@
+from enum import Enum
+from pydantic import Field
+from lionagi.core.collections.abc import Condition
+from lionagi.core.collections.util import to_list_type
+from lionagi.core.generic.node import Node
+
+
+class TreeLabel(str, Enum):
+    """Enumeration representing tree relationships."""
+
+    PARENT = "parent"
+    CHILD = "child"
+
+
+class TreeNode(Node):
+    """Represents a node in a tree structure."""
+
+    parent: Node | None = Field(
+        default=None,
+        description="The parent node, as an instance of Node.",
+    )
+
+    @property
+    def children(self) -> list[str]:
+        """Return a list of child node ids."""
+        if not self.parent:
+            return list(self.related_nodes)
+        else:
+            return [node for node in self.related_nodes if node != self.parent.ln_id]
+
+    def relate_child(
+        self,
+        node: Node | list[Node],
+        condition: Condition | None = None,
+        bundle: bool = False,
+    ) -> None:
+        """Establish a parent-child relationship with the given node(s)."""
+        children = to_list_type(node)
+        for _child in children:
+            self.relate(
+                _child,
+                direction="out",
+                # label=TreeLabel.PARENT,
+                condition=condition,
+                bundle=bundle,
+            )
+            if isinstance(_child, TreeNode):
+                _child.parent = self
+
+    def relate_parent(
+        self,
+        node: Node,
+        condition: Condition | None = None,
+        bundle: bool = False,
+    ) -> None:
+        """Establish a parent-child relationship with the given parent node."""
+        if self.parent:
+            self.unrelate(self.parent)
+        self.relate(
+            node,
+            direction="in",
+            # label=TreeLabel.PARENT,
+            condition=condition,
+            bundle=bundle,
+        )
+        self.parent = node
+
+    def unrelate_parent(self):
+        """Remove the parent-child relationship with the parent node."""
+        self.unrelate(self.parent)
+        self.parent = None
+
+    def unrelate_child(self, child: Node | list[Node]):
+        """Remove the parent-child relationship with the given child node(s)."""
+        children: list[Node] = [child] if isinstance(child, Node) else child
+        for _child in children:
+            self.unrelate(_child)
+            if isinstance(_child, TreeNode):
+                _child.parent = None

lionagi/core/mail/__init__.py

@@ -1,8 +1,12 @@
-from .schema import BaseMail, StartMail
+from .mail import Mail
 from .mail_manager import MailManager
+from .package import Package
+from .start_mail import StartMail
+
 
 __all__ = [
-    "BaseMail",
-    "StartMail",
+    "Mail",
     "MailManager",
+    "Package",
+    "StartMail",
 ]

lionagi/core/mail/mail.py

@@ -0,0 +1,25 @@
+from lionagi.core.collections.abc import Element, Field, Sendable
+from .package import PackageCategory, Package
+
+
+class Mail(Element, Sendable):
+    """Represents a mail component with sender and recipient information."""
+
+    package: Package | None = Field(
+        None,
+        title="Package",
+        description="The package to be delivered.",
+    )
+
+    @property
+    def category(self) -> PackageCategory:
+        """Return the category of the package."""
+        return self.package.category
+
+    def to_dict(self):
+        return {
+            "ln_id": self.ln_id,
+            "created": self.timestamp,
+            "package_category": self.package.category,
+            "package_id": self.package.ln_id,
+        }