lionagi 0.3.8__py3-none-any.whl → 0.5.0__py3-none-any.whl

lionagi/core/generic/graph.py

@@ -1,202 +1,284 @@
-import contextlib
-from collections import deque
-from typing import Any
-
-from lionagi.core.collections import Pile, pile
-from lionagi.core.collections.abc import (
-    Actionable,
-    Condition,
-    ItemNotFoundError,
-    LionIDable,
-    LionTypeError,
-)
-from lionagi.core.generic.edge import Edge
-from lionagi.core.generic.node import Node
-from lionagi.libs.ln_convert import to_list
-
+# Copyright (c) 2023 - 2024, HaiyangLi <quantocean.li at gmail dot com>
+#
+# SPDX-License-Identifier: Apache-2.0
 
-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,
-        )
+from collections import deque
 
-    def is_empty(self) -> bool:
-        """Check if the graph is empty (has no nodes)."""
-        return self.internal_nodes.is_empty()
+from lionagi.core.generic.pile import Pile
+from lionagi.core.typing import (
+    ID,
+    Any,
+    Field,
+    ItemExistsError,
+    Literal,
+    Note,
+    Relational,
+    RelationError,
+    field_serializer,
+)
 
-    def clear(self):
-        """Clear all nodes and edges from the graph."""
-        self.internal_nodes.clear()
+from .edge import Edge
+from .node import Node
 
-    def add_edge(
-        self,
-        head: Node,
-        tail: Node,
-        condition: Condition | None = None,
-        bundle=False,
-        label=None,
-        edge_class=Edge,
-        **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,
-            edge_class=edge_class,
-            **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."
+class Graph(Node):
+    """
+    Represents a graph structure containing nodes and edges.
+
+    This class models a graph with internal nodes and edges, providing
+    methods for graph manipulation and analysis.
+
+    Attributes:
+        internal_nodes (Pile): The internal nodes of the graph.
+        internal_edges (Pile): The internal edges of the graph.
+        node_edge_mapping (Note): The mapping of nodes to edges for
+                search purposes.
+    """
+
+    internal_nodes: Pile = Field(
+        default_factory=lambda: Pile({}, {Relational}),
+        description="The internal nodes of the graph.",
+    )
+    internal_edges: Pile = Field(
+        default_factory=lambda: Pile({}, {Edge}),
+        description="The internal edges of the graph.",
+    )
+    node_edge_mapping: Note = Field(
+        default_factory=Note,
+        description="The mapping for node and edges for search",
+        exclude=True,
+    )
+
+    @field_serializer("internal_nodes", "internal_edges")
+    def _serialize_internal_piles(self, value) -> Any:
+        """
+        Serialize the internal nodes and edges.
+
+        Args:
+            value: The Pile of internal nodes or edges to serialize.
+
+        Returns:
+            Serialized representation of the Pile.
+        """
+        value = value.to_dict()
+        value = value["pile_"]
+        return value
+
+    def add_node(self, node: Relational) -> None:
+        """
+        Add a node to the graph.
+
+        Args:
+            node (Node): The node to add.
+
+        Raises:
+            RelationError: If the node already exists in the graph or
+                if the node type is invalid.
+        """
+        try:
+            if not isinstance(node, Relational):
+                raise RelationError(
+                    "Failed to add node: Invalid node type: "
+                    "not a <Relational> entity."
                 )
-            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)
-                    ]
+            _id = ID.get_id(node)
+            self.internal_nodes.insert(len(self.internal_nodes), node)
+            self.node_edge_mapping.insert(_id, {"in": {}, "out": {}})
+        except ItemExistsError as e:
+            raise RelationError(f"Error adding node: {e}")
+
+    def add_edge(self, edge: Edge, /) -> None:
+        """
+        Add an edge to the graph.
+
+        Args:
+            edge (Edge): The edge to add.
+
+        Raises:
+            RelationError: If the edge already exists in the graph or
+                if either the head or tail node does not exist in the graph.
+        """
+        try:
+            if not isinstance(edge, Edge):
+                raise RelationError("Failed to add edge: Invalid edge type.")
+            if (
+                edge.head not in self.internal_nodes
+                or edge.tail not in self.internal_nodes
+            ):
+                raise RelationError(
+                    "Failed to add edge: Either edge head or tail node does"
+                    " not exist in the graph."
                 )
-                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
+            self.internal_edges.insert(len(self.internal_edges), edge)
+            self.node_edge_mapping[edge.head, "out", edge.ln_id] = edge.tail
+            self.node_edge_mapping[edge.tail, "in", edge.ln_id] = edge.head
+        except ItemExistsError as e:
+            raise RelationError(f"Error adding node: {e}")
+
+    def remove_node(self, node: Relational | str, /) -> None:
+        """
+        Remove a node from the graph.
+
+        This method removes a node and all connected edges from the graph.
+
+        Args:
+            node (Node | str): The node or node ID to remove.
+
+        Raises:
+            RelationError: If the node does not exist in the graph.
+        """
+        _id = ID.get_id(node)
+        if _id not in self.internal_nodes:
+            raise RelationError(f"Node {node} not found in the graph nodes.")
+
+        in_edges: dict = self.node_edge_mapping[_id, "in"]
+        for edge_id, node_id in in_edges.items():
+            self.node_edge_mapping[node_id, "out"].pop(edge_id)
+            self.internal_edges.pop(edge_id)
+
+        out_edges = self.node_edge_mapping[_id, "out"]
+        for edge_id, node_id in out_edges.items():
+            self.node_edge_mapping[node_id, "in"].pop(edge_id)
+            self.internal_edges.pop(edge_id)
+
+        self.node_edge_mapping.pop(_id)
+        return self.internal_nodes.pop(_id)
+
+    def remove_edge(self, edge: Edge | str, /) -> None:
+        """
+        Remove an edge from the graph.
+
+        Args:
+            edge (Edge | str): The edge or edge ID to remove.
+
+        Raises:
+            RelationError: If the edge does not exist in the graph.
+        """
+        _id = ID.get_id(edge)
+        if _id not in self.internal_edges:
+            raise RelationError(f"Edge {edge} not found in the graph edges.")
+
+        edge = self.internal_edges[_id]
+        self.node_edge_mapping[edge.head, "out"].pop(_id)
+        self.node_edge_mapping[edge.tail, "in"].pop(_id)
+        return self.internal_edges.pop(_id)
+
+    def find_node_edge(
+        self,
+        node: Any,
+        /,
+        direction: Literal["both", "in", "out"] = "both",
+    ) -> Pile[Edge]:
+        """
+        Find edges connected to a node in a specific direction.
+
+        Args:
+            node (Any): The node to find edges for.
+            direction (Literal["both", "in", "out"], optional):
+                The direction to search ("in", "out", or "both").
+                Defaults to "both".
+
+        Returns:
+            Pile[Edge]: A Pile of edges connected to the node in the
+                specified direction.
+
+        Raises:
+            RelationError: If the node is not found in the graph.
+            ValueError: If the direction is not one of "both", "in", or "out".
+        """
+        if direction not in {"both", "in", "out"}:
+            raise ValueError("The direction should be 'both', 'in', or 'out'.")
+
+        _id = ID.get_id(node)
+        if _id not in self.internal_nodes:
+            raise RelationError(f"Node {node} not found in the graph nodes.")
+
+        result = []
+
+        if direction in {"in", "both"}:
+            for edge_id in self.node_edge_mapping[_id, "in"].keys():
+                result.append(self.internal_edges[edge_id])
+
+        if direction in {"out", "both"}:
+            for edge_id in self.node_edge_mapping[_id, "out"].keys():
+                result.append(self.internal_edges[edge_id])
+
+        return self.internal_nodes.__class__(items=result, item_type={Edge})
 
     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)
-            ]
-        )
+        """
+        Get all head nodes in the graph.
 
-    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
+        Head nodes are nodes with no incoming edges.
 
-        def visit(key):
-            if check_dict[key] == 2:
-                return True
-            elif check_dict[key] == 1:
-                return False
+        Returns:
+            Pile: A Pile containing all head nodes.
+        """
 
-            check_dict[key] = 1
+        result = []
+        for node_id in self.node_edge_mapping.keys():
+            if self.node_edge_mapping[node_id, "in"] == {}:
+                result.append(self.internal_nodes[node_id])
 
-            for edge in self.internal_nodes[key].relations["out"]:
-                check = visit(edge.tail)
-                if not check:
-                    return False
+        return self.internal_nodes.__class__(
+            items=result, item_type={Relational}
+        )
 
-            check_dict[key] = 2
-            return True
+    def get_predecessors(self, node: Relational, /) -> Pile:
+        """
+        Get all predecessor nodes of a given node.
+
+        Predecessors are nodes that have outgoing edges to the given node.
+
+        Args:
+            node (Node): The node to find predecessors for.
+
+        Returns:
+            Pile: A Pile containing all predecessor nodes.
+        """
+        edges = self.find_node_edge(node, direction="in")
+        result = []
+        for edge in edges:
+            node_id = edge.head
+            result.append(self.internal_nodes[node_id])
+        return self.internal_nodes.__class__(
+            items=result, item_type={Relational}
+        )
 
-        while check_deque:
-            key = check_deque.pop()
-            check = visit(key)
-            if not check:
-                return False
-        return True
+    def get_successors(self, node: Relational, /) -> Pile:
+        """
+        Get all successor nodes of a given node.
+
+        Successors are nodes that have incoming edges from the given node.
+
+        Args:
+            node (Node): The node to find successors for.
+
+        Returns:
+            Pile: A Pile containing all successor nodes.
+        """
+        edges = self.find_node_edge(node, direction="out")
+        result = []
+        for edge in edges:
+            node_id = edge.tail
+            result.append(self.internal_nodes[node_id])
+        return self.internal_nodes.__class__(
+            items=result, item_type={Relational}
+        )
 
     def to_networkx(self, **kwargs) -> Any:
         """Convert the graph to a NetworkX graph object."""
-        from lionagi.libs import SysUtil
 
-        SysUtil.check_import("networkx")
+        from lionagi.libs.package.imports import check_import
 
+        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})
+            node_info.update({"class_name": node.class_name()})
             if hasattr(node, "name"):
                 node_info.update({"name": node.name})
             g.add_node(node.ln_id, **node_info)
@@ -204,7 +286,7 @@ class Graph(Node):
         for _edge in self.internal_edges:
             edge_info = _edge.to_dict()
             edge_info.pop("ln_id")
-            edge_info.update({"class_name": _edge.class_name})
+            edge_info.update({"class_name": _edge.class_name()})
             if hasattr(_edge, "name"):
                 edge_info.update({"name": _edge.name})
             source_node_id = edge_info.pop("head")
@@ -221,11 +303,11 @@ class Graph(Node):
         **kwargs,
     ):
         """Display the graph using NetworkX and Matplotlib."""
-        from lionagi.libs import SysUtil
 
-        SysUtil.check_import("networkx")
-        SysUtil.check_import("matplotlib", "pyplot")
+        from lionagi.libs.package.imports import check_import
 
+        check_import("matplotlib")
+        check_import("networkx")
         import matplotlib.pyplot as plt
         import networkx as nx
 
@@ -255,6 +337,41 @@ class Graph(Node):
         plt.axis("off")
         plt.show()
 
-    def size(self) -> int:
-        """Return the number of nodes in the graph."""
-        return len(self.internal_nodes)
+    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
+
+            # Use node_edge_mapping instead of relations
+            for edge_id in self.node_edge_mapping[key, "out"].keys():
+                edge = self.internal_edges[edge_id]
+                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 __contains__(self, item: object) -> bool:
+        return item in self.internal_nodes or item in self.internal_edges
+
+
+__all__ = ["Graph"]

lionagi/core/generic/log.py

@@ -0,0 +1,151 @@
+# Copyright (c) 2023 - 2024, HaiyangLi <quantocean.li at gmail dot com>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from lionagi.core.generic.element import Element
+from lionagi.core.typing import (
+    Any,
+    Field,
+    Note,
+    PrivateAttr,
+    Self,
+    field_serializer,
+)
+from lionagi.libs.parse import to_dict
+
+
+class Log(Element):
+    """A log entry in the Lion framework.
+
+    The Log class represents an immutable log entry with structured content
+    and metadata. Once created and loaded from storage, logs become immutable
+    to ensure data integrity.
+
+    Key Features:
+        - Structured content storage using Note objects
+        - Additional metadata through loginfo
+        - Immutability after loading from storage
+        - Serialization support
+        - Validation of content and metadata
+
+    Attributes:
+        content (Note): The main content of the log entry
+        loginfo (Note): Additional metadata about the log entry
+    """
+
+    content: Note = Field(
+        default_factory=Note,
+        title="Log Content",
+        description="The content of the log entry.",
+    )
+
+    loginfo: Note = Field(
+        default_factory=Note,
+        title="Log Info",
+        description="Metadata about the log entry.",
+    )
+
+    _immutable: bool = PrivateAttr(False)
+
+    def __init__(self, content: Note, loginfo: Note, **kwargs) -> None:
+        """Initialize a Log instance.
+
+        Args:
+            content: The main content of the log entry
+            loginfo: Additional metadata about the log entry
+            **kwargs: Additional arguments passed to Element
+        """
+        super().__init__(**kwargs)
+        self.content = self._validate_note(content)
+        self.loginfo = self._validate_note(loginfo)
+
+    @classmethod
+    def _validate_load_data(cls, data: dict, /) -> dict:
+        try:
+            # Validate required fields
+            if not isinstance(data.get("content"), (dict, Note)):
+                raise ValueError("Missing or invalid 'content' field")
+            if not isinstance(data.get("loginfo"), (dict, Note)):
+                raise ValueError("Missing or invalid 'loginfo' field")
+
+            # Convert log_* fields to standard fields
+            if "log_id" in data:
+                data["ln_id"] = data.pop("log_id")
+            if "log_timestamp" in data:
+                data["timestamp"] = data.pop("log_timestamp")
+            if "log_class" in data:
+                data["lion_class"] = data.pop("log_class")
+            return data
+        except Exception as e:
+            raise ValueError(
+                "Log can only be loaded from a previously saved log entries.",
+            ) from e
+
+    @classmethod
+    def from_dict(cls, data: dict, /) -> Self:
+        """Create a Log instance from a dictionary.
+
+        The created log will be immutable to ensure data integrity.
+
+        Args:
+            data: Dictionary containing log data
+
+        Returns:
+            New immutable Log instance
+        """
+        data = cls._validate_load_data(data)
+        # Convert content and loginfo to Note objects if they're dicts
+        if isinstance(data.get("content"), dict):
+            data["content"] = Note(**data["content"])
+        if isinstance(data.get("loginfo"), dict):
+            data["loginfo"] = Note(**data["loginfo"])
+        # Remove lion_class as it's handled by Element
+        data.pop("lion_class", None)
+        self = cls(**data)
+        self._immutable = True
+        return self
+
+    def __setattr__(self, name: str, value: Any, /) -> None:
+        if hasattr(self, "_immutable") and self._immutable:
+            raise AttributeError("Cannot modify immutable log entry.")
+        super().__setattr__(name, value)
+
+    def _validate_note(self, value: Any, /) -> Note:
+
+        if not value:
+            return Note()
+        if isinstance(value, Note):
+            return value
+        if isinstance(value, dict):
+            return Note(**value)
+        try:
+            return Note(**to_dict(value))
+        except Exception as e:
+            raise ValueError(f"Invalid note value: {value}") from e
+
+    @field_serializer("content", "loginfo")
+    def _serialize_note(self, value: Note) -> dict:
+        return value.to_dict()
+
+    def to_dict(self) -> dict:
+        """Convert Log to dictionary.
+
+        Converts standard field names to log_* format and handles recursive
+        serialization of nested structures.
+
+        Returns:
+            Dictionary representation of the log
+        """
+        dict_ = super().to_dict()
+        # Convert standard fields to log_* fields
+        dict_["log_id"] = dict_.pop("ln_id")
+        dict_["log_class"] = dict_.pop("lion_class")
+        dict_["log_timestamp"] = dict_.pop("timestamp")
+
+        dict_ = to_dict(
+            dict_,
+            recursive=True,
+            recursive_python_only=False,
+            max_recursive_depth=10,  # Increased depth for nested structures
+        )
+        return dict_