lionagi 0.1.1__py3-none-any.whl → 0.2.0__py3-none-any.whl

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

@@ -0,0 +1,12 @@
+from .mail import Mail
+from .mail_manager import MailManager
+from .package import Package
+from .start_mail import StartMail
+
+
+__all__ = [
+    "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,
+        }

lionagi/core/mail/mail_manager.py

@@ -1,10 +1,14 @@
 from collections import deque
+from pydantic import Field
 from lionagi.libs import AsyncUtil
-from lionagi.core.generic import Node
-from lionagi.core.mail.schema import BaseMail, MailCategory
+from lionagi.core.collections.abc import Executable, Element
+from lionagi.core.collections import Exchange
+from lionagi.core.collections.util import to_list_type, get_lion_id
+from .mail import Mail, Package
+from lionagi.core.collections import Pile, pile
 
 
-class MailManager:
+class MailManager(Element, Executable):
     """
     Manages the sending, receiving, and storage of mail items between various sources.
 
@@ -15,85 +19,162 @@ class MailManager:
             sources (Dict[str, Any]): A dictionary mapping source identifiers to their attributes.
             mails (Dict[str, Dict[str, deque]]): A nested dictionary storing queued mail items, organized by recipient
                     and sender.
+            execute_stop (bool): A flag indicating whether to stop execution.
     """
 
+    sources: Pile[Element] = Field(
+        default_factory=lambda: pile(),
+        description="The pile of managed sources",
+    )
+
+    mails: dict[str, dict[str, deque]] = Field(
+        default_factory=dict,
+        description="The mails waiting to be sent",
+        examples=["{'recipient_id': {'sender_id': deque()}}"],
+    )
+
+    execute_stop: bool = Field(
+        False, description="A flag indicating whether to stop execution."
+    )
+
     def __init__(self, sources=None):
-        self.sources = {}
-        self.mails = {}
+        """
+        Initializes the MailManager with optional sources.
+
+        Args:
+            sources (Optional[list]): A list of sources to be managed by the MailManager.
+        """
+        super().__init__()
         if sources:
             self.add_sources(sources)
-        self.execute_stop = False
 
     def add_sources(self, sources):
-        if isinstance(sources, dict):
-            for _, v in sources.items():
-                if v.id_ not in self.sources:
-                    self.sources[v.id_] = v
-                    self.mails[v.id_] = {}
-        elif isinstance(sources, list):
-            for v in sources:
-                if v.id_ not in self.sources:
-                    self.sources[v.id_] = v
-                    self.mails[v.id_] = {}
-        else:
-            raise ValueError("Failed to add source, please input list or dict.")
+        """
+        Adds new sources to the MailManager.
+
+        Args:
+            sources (list): A list of sources to be added.
+
+        Raises:
+            ValueError: If failed to add sources.
+        """
+        try:
+            sources = to_list_type(sources)
+            self.sources.include(sources)
+            for item in sources:
+                self.mails[item.ln_id] = {}
+        except Exception as e:
+            raise ValueError(f"Failed to add source. Error {e}")
 
     @staticmethod
-    def create_mail(sender_id, recipient_id, category, package):
-        return BaseMail(sender_id, recipient_id, category, package)
+    def create_mail(sender, recipient, category, package):
+        """
+        Creates a mail item.
 
-    # def add_source(self, sources: list[Node]):
-    #     for source in sources:
-    #         if source.id_ in self.sources:
-    #             # raise ValueError(f"Source {source.id_} exists, please input a different name.")
-    #             continue
-    #         self.sources[source.id_] = source
-    #         self.mails[source.id_] = {}
+        Args:
+            sender (str): The sender of the mail.
+            recipient (str): The recipient of the mail.
+            category (str): The category of the mail.
+            package (Any): The content of the package.
+
+        Returns:
+            Mail: The created mail object.
+        """
+        pack = Package(category=category, package=package)
+        mail = Mail(
+            sender=sender,
+            recipient=recipient,
+            package=pack,
+        )
+        return mail
 
     def delete_source(self, source_id):
+        """
+        Deletes a source from the MailManager.
+
+        Args:
+            source_id (str): The ID of the source to be deleted.
+
+        Raises:
+            ValueError: If the source does not exist.
+        """
         if source_id not in self.sources:
             raise ValueError(f"Source {source_id} does not exist.")
-        # if self.mails[source_id]:
-        #     raise ValueError(f"None empty pending mails in source {source_id}")
         self.sources.pop(source_id)
         self.mails.pop(source_id)
 
-    def collect(self, sender_id):
-        if sender_id not in self.sources:
-            raise ValueError(f"Sender source {sender_id} does not exist.")
-        while self.sources[sender_id].pending_outs:
-            mail_ = self.sources[sender_id].pending_outs.popleft()
-            if mail_.recipient_id not in self.sources:
-                raise ValueError(
-                    f"Recipient source {mail_.recipient_id} does not exist"
-                )
-            if mail_.sender_id not in self.mails[mail_.recipient_id]:
-                self.mails[mail_.recipient_id].update({mail_.sender_id: deque()})
-            self.mails[mail_.recipient_id][mail_.sender_id].append(mail_)
-
-    def send(self, recipient_id):
-        if recipient_id not in self.sources:
-            raise ValueError(f"Recipient source {recipient_id} does not exist.")
-        if not self.mails[recipient_id]:
+    def collect(self, sender):
+        """
+        Collects mails from a sender's outbox and queues them for the recipient.
+
+        Args:
+            sender (str): The ID of the sender.
+
+        Raises:
+            ValueError: If the sender or recipient source does not exist.
+        """
+        if sender not in self.sources:
+            raise ValueError(f"Sender source {sender} does not exist.")
+        mailbox = (
+            self.sources[sender]
+            if isinstance(self.sources[sender], Exchange)
+            else self.sources[sender].mailbox
+        )
+        while mailbox.pending_outs.size() > 0:
+            mail_id = mailbox.pending_outs.popleft()
+            mail = mailbox.pile.pop(mail_id)
+            if mail.recipient not in self.sources:
+                raise ValueError(f"Recipient source {mail.recipient} does not exist")
+            if mail.sender not in self.mails[mail.recipient]:
+                self.mails[mail.recipient].update({mail.sender: deque()})
+            self.mails[mail.recipient][mail.sender].append(mail)
+
+    def send(self, recipient):
+        """
+        Sends mails to a recipient's inbox.
+
+        Args:
+            recipient (str): The ID of the recipient.
+
+        Raises:
+            ValueError: If the recipient source does not exist.
+        """
+        if recipient not in self.sources:
+            raise ValueError(f"Recipient source {recipient} does not exist.")
+        if not self.mails[recipient]:
             return
-        for key in list(self.mails[recipient_id].keys()):
-            mails_deque = self.mails[recipient_id].pop(key)
-            if key not in self.sources[recipient_id].pending_ins:
-                self.sources[recipient_id].pending_ins[key] = mails_deque
-            else:
-                while mails_deque:
-                    mail_ = mails_deque.popleft()
-                    self.sources[recipient_id].pending_ins[key].append(mail_)
+        for key in list(self.mails[recipient].keys()):
+            pending_mails = self.mails[recipient].pop(key)
+            mailbox = (
+                self.sources[recipient]
+                if isinstance(self.sources[recipient], Exchange)
+                else self.sources[recipient].mailbox
+            )
+            while pending_mails:
+                mail = pending_mails.popleft()
+                mailbox.include(mail, "in")
 
     def collect_all(self):
-        for ids in self.sources:
-            self.collect(ids)
+        """
+        Collects mails from all sources.
+        """
+        for source in self.sources:
+            self.collect(get_lion_id(source))
 
     def send_all(self):
-        for ids in self.sources:
-            self.send(ids)
+        """
+        Sends mails to all sources.
+        """
+        for source in self.sources:
+            self.send(get_lion_id(source))
 
     async def execute(self, refresh_time=1):
+        """
+        Continuously collects and sends mails until execution is stopped.
+
+        Args:
+            refresh_time (int): The time in seconds to wait between each cycle. Defaults to 1.
+        """
         while not self.execute_stop:
             self.collect_all()
             self.send_all()

lionagi/core/mail/package.py

@@ -0,0 +1,45 @@
+from enum import Enum
+from typing import Any
+from pydantic import field_validator
+from lionagi.core.collections.abc import Element, Field
+
+
+class PackageCategory(str, Enum):
+    MESSAGE = "message"
+    TOOL = "tool"
+    IMODEL = "imodel"
+    NODE = "node"
+    NODE_LIST = "node_list"
+    NODE_ID = "node_id"
+    START = "start"
+    END = "end"
+    CONDITION = "condition"
+
+
+class Package(Element):
+
+    request_source: str | None = None
+
+    category: PackageCategory = Field(
+        None,
+        title="Category",
+        description="The category of the package.",
+    )
+
+    package: Any = Field(
+        None,
+        title="Package",
+        description="The package to be delivered.",
+    )
+
+    @field_validator("category", mode="before")
+    def validate_category(cls, value: Any):
+        if value is None:
+            raise ValueError("Package category cannot be None.")
+        if isinstance(value, PackageCategory):
+            return value
+        else:
+            try:
+                return PackageCategory(value)
+            except Exception as e:
+                raise ValueError(f"Invalid value for category: {value}.") from e

lionagi/core/mail/start_mail.py

@@ -0,0 +1,36 @@
+from collections import deque
+from pydantic import Field
+from lionagi.core.generic.node import Node
+from lionagi.core.mail.mail import Mail, Package
+from lionagi.core.collections import Exchange
+
+
+class StartMail(Node):
+    """
+    Represents a start mail node that triggers the initiation of a process.
+
+    Attributes:
+        mailbox (Exchange): The exchange object that holds pending start mails.
+    """
+
+    mailbox: Exchange = Field(
+        default_factory=Exchange[Mail], description="The pending start mail"
+    )
+
+    def trigger(self, context, structure_id, executable_id):
+        """
+        Triggers the start mail by including it in the mailbox.
+
+        Args:
+            context (Any): The context to be included in the start mail.
+            structure_id (str): The ID of the structure to be initiated.
+            executable_id (str): The ID of the executable to receive the start mail.
+        """
+        start_mail_content = {"context": context, "structure_id": structure_id}
+        pack = Package(category="start", package=start_mail_content)
+        start_mail = Mail(
+            sender=self.ln_id,
+            recipient=executable_id,
+            package=pack,
+        )
+        self.mailbox.include(start_mail, "out")

lionagi/core/message/__init__.py

@@ -0,0 +1,19 @@
+from .message import RoledMessage, MessageRole
+from .system import System
+from .instruction import Instruction
+from .assistant_response import AssistantResponse
+from .action_request import ActionRequest
+from .action_response import ActionResponse
+from .util import create_message
+
+
+__all__ = [
+    "RoledMessage",
+    "MessageRole",
+    "System",
+    "Instruction",
+    "AssistantResponse",
+    "ActionRequest",
+    "ActionResponse",
+    "create_message",
+]

lionagi/core/message/action_request.py

@@ -0,0 +1,133 @@
+"""
+Copyright 2024 HaiyangLi
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+
+import inspect
+from pydantic import Field
+from lionagi.libs import convert, ParseUtil
+from .message import RoledMessage, MessageRole
+
+
+class ActionRequest(RoledMessage):
+    """
+    Represents a request for an action with function and arguments.
+
+    Inherits from `RoledMessage` and provides attributes specific to action requests.
+
+    Attributes:
+        function (str): The name of the function to be called.
+        arguments (dict): The keyword arguments to be passed to the function.
+        action_response (str): The ID of the action response that this request corresponds to.
+    """
+
+    function: str | None = Field(
+        None, description="The name of the function to be called"
+    )
+
+    arguments: dict | None = Field(
+        None, description="The keyword arguments to be passed to the function"
+    )
+
+    action_response: str | None = Field(
+        None,
+        description="The id of the action response that this request corresponds to",
+    )
+
+    def __init__(
+        self,
+        function=None,
+        arguments=None,
+        sender=None,  # sender is the assistant who made the request
+        recipient=None,  # recipient is the actionable component
+        **kwargs,
+    ):
+        """
+        Initializes the ActionRequest.
+
+        Args:
+            function (str or function, optional): The function to be called.
+            arguments (dict, optional): The keyword arguments for the function.
+            sender (str, optional): The sender of the request.
+            recipient (str, optional): The recipient of the request.
+        """
+        function = function.__name__ if inspect.isfunction(function) else function
+        arguments = _prepare_arguments(arguments)
+
+        super().__init__(
+            role=MessageRole.ASSISTANT,
+            sender=sender,
+            recipient=recipient,
+            content={"action_request": {"function": function, "arguments": arguments}},
+            **kwargs,
+        )
+        self.function = function
+        self.arguments = arguments
+
+    def is_responded(self):
+        """
+        Checks if the action request has been responded to.
+
+        Returns:
+            bool: True if the action request has a response, otherwise False.
+        """
+        return self.action_response is not None
+
+    def clone(self, **kwargs):
+        """
+        Creates a copy of the current ActionRequest object with optional additional arguments.
+
+        This method clones the current object, preserving its function and arguments.
+        It also retains the original `action_response` and metadata, while allowing
+        for the addition of new attributes through keyword arguments.
+
+        Args:
+            **kwargs: Optional keyword arguments to be included in the cloned object.
+
+        Returns:
+            ActionRequest: A new instance of the object with the same function, arguments,
+            and additional keyword arguments.
+        """
+        import json
+
+        arguments = json.dumps(self.arguments)
+        request_copy = ActionRequest(
+            function=self.function, arguments=json.loads(arguments), **kwargs
+        )
+        request_copy.action_response = self.action_response
+        request_copy.metadata["origin_ln_id"] = self.ln_id
+        return request_copy
+
+
+def _prepare_arguments(arguments):
+    """
+    Prepares the arguments for the action request.
+
+    Args:
+        arguments (Any): The arguments to be prepared.
+
+    Returns:
+        dict: The prepared arguments.
+
+    Raises:
+        ValueError: If the arguments are invalid.
+    """
+    if not isinstance(arguments, dict):
+        try:
+            arguments = ParseUtil.fuzzy_parse_json(convert.to_str(arguments))
+        except Exception as e:
+            raise ValueError(f"Invalid arguments: {e}") from e
+    if isinstance(arguments, dict):
+        return arguments
+    raise ValueError(f"Invalid arguments: {arguments}")