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

lionagi/core/mail/mail_manager.py

@@ -1,10 +1,14 @@
 from collections import deque
+from pydantic import Field
 from lionagi.libs import AsyncUtil
-from ..schema import BaseNode
-from .schema import BaseMail
+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,82 +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.
     """
 
-    def __init__(self, sources):
-        self.sources = {}
-        self.mails = {}
-        self.add_sources(sources)
-        self.execute_stop = False
+    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):
+        """
+        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)
 
     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_] = {}
+        """
+        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[BaseNode]):
-        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] = {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}")

lionagi/core/message/action_response.py

@@ -0,0 +1,135 @@
+"""
+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.
+"""
+
+from typing import Any
+from pydantic import Field
+from .message import RoledMessage, MessageRole
+from .action_request import ActionRequest
+
+
+# action response must correlates to a specific action request
+class ActionResponse(RoledMessage):
+    """
+    Represents a response to a specific action request.
+
+    Inherits from `RoledMessage` and provides attributes specific to action responses.
+
+    Attributes:
+        action_request (str): The ID of the action request that this response corresponds to.
+        function (str): The name of the function called.
+        arguments (dict): The keyword arguments provided.
+        func_outputs (Any): The output of the function call.
+    """
+
+    action_request: str | None = Field(
+        None,
+        description="The id of the action request that this response corresponds to",
+    )
+
+    function: str | None = Field(None, description="The name of the function called")
+    arguments: dict | None = Field(None, description="The keyword arguments provided")
+    func_outputs: Any | None = Field(
+        None, description="The output of the function call"
+    )
+
+    def __init__(
+        self,
+        action_request: ActionRequest,
+        sender: str | None = None,  # the sender of action request
+        func_outputs=None,
+        **kwargs,
+    ):
+        """
+        Initializes the ActionResponse.
+
+        Args:
+            action_request (ActionRequest): The action request that this response corresponds to.
+            sender (str, optional): The sender of the action request.
+            func_outputs (Any, optional): The output of the function call.
+
+        Raises:
+            ValueError: If the action request has already been responded to.
+        """
+        if action_request.is_responded():
+            raise ValueError("Action request has already been responded to")
+
+        super().__init__(
+            role=MessageRole.ASSISTANT,
+            sender=sender or "N/A",  # sender is the actionable component
+            recipient=action_request.sender,  # recipient is the assistant who made the request
+            content={
+                "action_response": {
+                    "function": action_request.function,
+                    "arguments": action_request.arguments,
+                    "output": func_outputs,
+                }
+            },
+            **kwargs,
+        )
+        self.update_request(action_request)
+        self.func_outputs = func_outputs
+
+    def update_request(self, action_request: ActionRequest):
+        """
+        Updates the action request details in the action response.
+
+        Args:
+            action_request (ActionRequest): The action request to update from.
+        """
+        self.function = action_request.function
+        self.arguments = action_request.arguments
+        self.action_request = action_request.ln_id
+        action_request.action_response = self.ln_id
+
+    def _to_dict(self):
+        """
+        Converts the action response to a dictionary.
+
+        Returns:
+            dict: A dictionary representation of the action response.
+        """
+        return {
+            "function": self.function,
+            "arguments": self.arguments,
+            "output": self.func_outputs,
+        }
+
+    def clone(self, **kwargs):
+        """
+        Creates a copy of the current object with optional additional arguments.
+
+        This method clones the current object, preserving its function and arguments.
+        It also retains the original `action_request`, `func_outputs`, 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:
+            ActionResponse: A new instance of the object with the same function, arguments,
+            and additional keyword arguments.
+        """
+        import json
+
+        arguments = json.dumps(self.arguments)
+        action_request = ActionRequest(
+            function=self.function, arguments=json.loads(arguments)
+        )
+        action_response_copy = ActionResponse(action_request=action_request, **kwargs)
+        action_response_copy.action_request = self.action_request
+        action_response_copy.func_outputs = self.func_outputs
+        action_response_copy.metadata["origin_ln_id"] = self.ln_id
+        return action_response_copy