lionagi 0.5.5__py3-none-any.whl → 0.6.0__py3-none-any.whl

lionagi/protocols/mail/manager.py

@@ -0,0 +1,168 @@
+# Copyright (c) 2023 - 2024, HaiyangLi <quantocean.li at gmail dot com>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import asyncio
+from collections import deque
+from typing import Any
+
+from lionagi._errors import ItemNotFoundError
+
+from .._concepts import Manager, Observable
+from ..generic.element import ID, IDType
+from ..generic.pile import Pile, to_list_type
+from .exchange import Exchange
+from .mail import Mail, Package, PackageCategory
+
+
+class MailManager(Manager):
+    """
+    Manages mail operations for multiple sources in the Lion framework.
+
+    This class handles the collection, distribution, and management of mail
+    between different sources within the system.
+    """
+
+    def __init__(self, sources: ID.Item | ID.ItemSeq = None) -> None:
+        """
+        Initialize a MailManager instance.
+
+        Args:
+            sources (List[Any], optional): Initial list of mail sources to
+                manage.
+        """
+        self.sources: Pile[Observable] = Pile()
+        self.mails: dict[str, dict[str, deque]] = {}
+        self.execute_stop: bool = False
+
+        if sources:
+            self.add_sources(sources)
+
+    def add_sources(self, sources: ID.Item | ID.ItemSeq, /) -> None:
+        """
+        Add new sources to the MailManager.
+
+        Args:
+            sources (Any): The sources to add. Can be a single source or
+                a list of sources.
+
+        Raises:
+            LionValueError: If adding the source(s) fails.
+        """
+        try:
+            sources = to_list_type(sources)
+            self.sources.include(sources)
+            for item in sources:
+                self.mails[item.id] = {}
+        except Exception as e:
+            raise ValueError("Failed to add source.") from e
+
+    @staticmethod
+    def create_mail(
+        sender: ID.Ref,
+        recipient: ID.Ref,
+        category: PackageCategory | str,
+        package: Any,
+        request_source: Any = None,
+    ) -> Mail:
+        """
+        Create a new Mail object.
+
+        Args:
+            sender (str): The ID of the sender.
+            recipient (str): The ID of the recipient.
+            category (str): The category of the mail.
+            package (Any): The content of the package.
+            request_source (Any, optional): The source of the request.
+
+        Returns:
+            Mail: A new Mail object.
+        """
+        pack = Package(
+            category=category, package=package, request_source=request_source
+        )
+        return Mail(sender=sender, recipient=recipient, package=pack)
+
+    def delete_source(self, source_id: IDType) -> None:
+        """
+        Delete a source from the MailManager.
+
+        Args:
+            source_id (str): The ID of the source to delete.
+
+        Raises:
+            LionValueError: If the source does not exist.
+        """
+        if source_id not in self.sources:
+            raise ItemNotFoundError(f"Source {source_id} does not exist.")
+        self.sources.pop(source_id)
+        self.mails.pop(source_id)
+
+    def collect(self, sender: IDType) -> None:
+        """Collect mail from a specific sender."""
+        if sender not in self.sources:
+            raise ItemNotFoundError(f"Sender source {sender} does not exist.")
+        mailbox: Exchange = (
+            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: Mail = mailbox.pile_.pop(mail_id)
+            if mail.recipient not in self.sources:
+                rec_ = mail.recipient
+                raise ItemNotFoundError(
+                    f"Recipient source {rec_} 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: IDType) -> None:
+        """Send mail to a specific recipient."""
+        if recipient not in self.sources:
+            raise ItemNotFoundError(
+                f"Recipient source {recipient} does not exist."
+            )
+        if not self.mails[recipient]:
+            return
+        for key in list(self.mails[recipient].keys()):
+            pending_mails = self.mails[recipient].pop(key)
+            mailbox: Exchange = (
+                self.sources[recipient]
+                if isinstance(self.sources[recipient], Exchange)
+                else self.sources[recipient].mailbox
+            )
+            while pending_mails:
+                mail = pending_mails.popleft()
+                mailbox.include(mail, direction="in")
+
+    def collect_all(self) -> None:
+        """Collect mail from all sources."""
+        for source in self.sources:
+            self.collect(sender=source.id)
+
+    def send_all(self) -> None:
+        """Send mail to all recipients."""
+        for source in self.sources:
+            self.send(recipient=source.id)
+
+    async def execute(self, refresh_time: int = 1) -> None:
+        """
+        Execute mail collection and sending process asynchronously.
+
+        This method runs in a loop, collecting and sending mail at
+            regular intervals.
+
+        Args:
+            refresh_time (int, optional): The time to wait between
+                each cycle in seconds. Defaults to 1.
+        """
+        while not self.execute_stop:
+            self.collect_all()
+            self.send_all()
+            await asyncio.sleep(refresh_time)
+
+
+# File: lion_core/communication/mail_manager.py

lionagi/protocols/mail/package.py

@@ -0,0 +1,55 @@
+# Copyright (c) 2023 - 2024, HaiyangLi <quantocean.li at gmail dot com>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from enum import Enum
+from typing import Any
+
+from lionagi.protocols.generic.element import ID, IDType
+from lionagi.utils import time
+
+from .._concepts import Communicatable, Observable
+
+
+class PackageCategory(str, Enum):
+    """Enumeration of package categories in the Lion framework."""
+
+    MESSAGE = "message"
+    TOOL = "tool"
+    IMODEL = "imodel"
+    NODE = "node"
+    NODE_LIST = "node_list"
+    NODE_ID = "node_id"
+    START = "start"
+    END = "end"
+    CONDITION = "condition"
+    SIGNAL = "signal"
+
+
+def validate_category(value: Any) -> PackageCategory:
+    """Validate the category field."""
+    if isinstance(value, PackageCategory):
+        return value
+    try:
+        return PackageCategory(str(value))
+    except ValueError as e:
+        raise ValueError("Invalid value for category.") from e
+
+
+class Package(Observable):
+
+    def __init__(
+        self,
+        category: PackageCategory,
+        item: Any,
+        request_source: ID[Communicatable] = None,
+    ):
+
+        super().__init__()
+        self.id = IDType.create()
+        self.created_at = time(type_="timestamp")
+        self.category = validate_category(category)
+        self.item = item
+        self.request_source = request_source
+
+    __slots__ = ("id", "created_at", "category", "item", "request_source")

lionagi/protocols/messages/action_request.py

@@ -0,0 +1,165 @@
+# Copyright (c) 2023 - 2024, HaiyangLi <quantocean.li at gmail dot com>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from collections.abc import Callable
+from typing import Any
+
+from lionagi.utils import copy, to_dict
+
+from ..generic.element import IDType
+from .base import SenderRecipient
+from .message import MessageRole, RoledMessage, Template, jinja_env
+
+
+def prepare_action_request(
+    function: str | Callable,
+    arguments: dict,
+) -> dict[str, Any]:
+
+    if isinstance(function, Callable):
+        function = function.__name__
+    if hasattr(function, "function"):
+        function = function.function
+    if not isinstance(function, str):
+        raise ValueError("Function must be a string or callable.")
+
+    arguments = copy(arguments)
+    if not isinstance(arguments, dict):
+        try:
+            arguments = to_dict(arguments, fuzzy_parse=True)
+            if isinstance(arguments, list | tuple) and len(arguments) > 0:
+                arguments = arguments[0]
+        except Exception:
+            raise ValueError("Arguments must be a dictionary.")
+    return {"action_request": {"function": function, "arguments": arguments}}
+
+
+class ActionRequest(RoledMessage):
+
+    template: Template | str | None = jinja_env.get_template(
+        "action_request.jinja2"
+    )
+
+    @property
+    def action_response_id(self) -> IDType | None:
+        """
+        Get the ID of the corresponding action response.
+
+        Returns:
+            IDType | None: The ID of the action response, or None if not responded
+        """
+        return self.content.get("action_response_id", None)
+
+    @action_response_id.setter
+    def action_response_id(self, action_response_id: IDType) -> None:
+        """
+        Set the ID of the corresponding action response.
+
+        Args:
+            action_response_id: The ID of the action response
+        """
+        self.content["action_response_id"] = action_response_id
+
+    @property
+    def request(self) -> dict[str, Any]:
+        """
+        Get the action request content as a dictionary.
+
+        Returns:
+            dict[str, Any]: The request content excluding output
+        """
+        return copy(self.content.get("action_request", {}))
+
+    @property
+    def arguments(self) -> dict[str, Any]:
+        """
+        Get the arguments for the action request.
+
+        Returns:
+            dict[str, Any]: The arguments dictionary
+        """
+        return self.request.get("arguments", {})
+
+    @property
+    def function(self) -> str:
+        """
+        Get the function name for the action request.
+
+        Returns:
+            str: The name of the function to be invoked
+        """
+        return self.request.get("function", "")
+
+    @classmethod
+    def create(
+        cls,
+        function=None,
+        arguments: dict | None = None,
+        sender: SenderRecipient | None = None,
+        recipient: SenderRecipient | None = None,
+        template: Template | str | None = None,
+        **kwargs,
+    ) -> "ActionRequest":
+        """
+        Create a new ActionRequest instance.
+
+        Args:
+            function: The function to be invoked
+            arguments: The arguments to be passed to the function
+            sender: The sender of the request
+            recipient: The recipient of the request
+
+        Returns:
+            ActionRequest: The new instance
+        """
+        content = prepare_action_request(function, arguments)
+        content.update(kwargs)
+        params = {
+            "content": content,
+            "sender": sender,
+            "recipient": recipient,
+            "role": MessageRole.ACTION,
+        }
+        if template:
+            params["template"] = template
+        return cls(**{k: v for k, v in params.items() if v is not None})
+
+    def update(
+        self,
+        function: str = None,
+        arguments: dict | None = None,
+        sender: SenderRecipient = None,
+        recipient: SenderRecipient = None,
+        action_response: "ActionResponse" = None,  # type: ignore
+        template: Template | str | None = None,
+        **kwargs,
+    ):
+        if self.is_responded():
+            raise ValueError("Cannot update a responded action request.")
+
+        if (
+            isinstance(action_response, RoledMessage)
+            and action_response.class_name() == "ActionResponse"
+        ):
+            self.action_response_id = action_response.id
+
+        if any([function, arguments]):
+            action_request = prepare_action_request(
+                function or self.function, arguments or self.arguments
+            )
+            self.content.update(action_request)
+        super().update(
+            sender=sender, recipient=recipient, template=template, **kwargs
+        )
+
+    def is_responded(self) -> bool:
+        """
+        Check if the action request has been responded to.
+
+        Returns:
+            bool: True if the request has a response, False otherwise
+        """
+        if self.action_response_id is not None:
+            return True
+        return False

lionagi/protocols/messages/action_response.py

@@ -0,0 +1,132 @@
+# Copyright (c) 2023 - 2024, HaiyangLi <quantocean.li at gmail dot com>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import Any
+
+from typing_extensions import override
+
+from lionagi.protocols.generic.element import IDType
+from lionagi.utils import copy
+
+from .action_request import ActionRequest
+from .base import MessageRole, SenderRecipient
+from .message import RoledMessage, Template, jinja_env
+
+
+def prepare_action_response_content(
+    action_request: ActionRequest,
+    output: Any,
+) -> dict:
+    return {
+        "action_request_id": str(action_request.id),
+        "action_response": {
+            "function": action_request.function,
+            "arguments": action_request.arguments,
+            "output": output,
+        },
+    }
+
+
+class ActionResponse(RoledMessage):
+
+    template: Template | str | None = jinja_env.get_template(
+        "action_response.jinja2"
+    )
+
+    @property
+    def function(self) -> str:
+        """
+        Get the function name from the action response.
+
+        Returns:
+            str: The name of the function that was executed
+        """
+        return self.content.get("action_response", {}).get("function", None)
+
+    @property
+    def arguments(self) -> dict[str, Any]:
+        """
+        Get the function arguments from the action response.
+
+        Returns:
+            dict[str, Any]: The arguments that were used
+        """
+        return self.content.get("action_response", {}).get("arguments", {})
+
+    @property
+    def output(self) -> Any:
+        """
+        Get the function output from the action response.
+
+        Returns:
+            Any: The result returned by the function
+        """
+        return self.content.get("action_response", {}).get("output", None)
+
+    @property
+    def response(self) -> dict[str, Any]:
+        """
+        Get the complete action response as a dictionary.
+
+        Returns:
+            dict[str, Any]: The response including function details and output
+        """
+        return copy(self.content.get("action_response", {}))
+
+    @property
+    def action_request_id(self) -> IDType:
+        """
+        Get the ID of the corresponding action request.
+
+        Returns:
+            ID[ActionRequest].ID | None: The ID of the original request
+        """
+        return IDType.validate(self.content.get("action_request_id"))
+
+    @override
+    @classmethod
+    def create(
+        cls,
+        action_request: ActionRequest,
+        output: Any | None = None,
+        response_model=None,
+        sender: SenderRecipient | None = None,
+        recipient: SenderRecipient | None = None,
+    ) -> "ActionResponse":
+
+        if response_model:
+            output = response_model.output
+
+        instance = ActionResponse(
+            content=prepare_action_response_content(
+                action_request=response_model or action_request, output=output
+            ),
+            role=MessageRole.ACTION,
+            sender=sender or action_request.recipient,
+            recipient=recipient or action_request.sender,
+        )
+        action_request.action_response_id = instance.id
+        return instance
+
+    def update(
+        self,
+        action_request: ActionRequest = None,
+        output: Any = None,
+        response_model=None,
+        sender: SenderRecipient = None,
+        recipient: SenderRecipient = None,
+        template: Template | str | None = None,
+        **kwargs,
+    ):
+        if response_model:
+            output = response_model.output
+
+        if action_request:
+            self.content = prepare_action_response_content(
+                action_request=action_request, output=output or self.output
+            )
+            action_request.action_response_id = self.id
+        super().update(
+            sender=sender, recipient=recipient, template=template, **kwargs
+        )

lionagi/{core/communication → protocols/messages}/assistant_response.py

@@ -2,32 +2,21 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
-from lionagi.core.typing import ID, Any, BaseModel, JsonValue, Note, override
-from lionagi.libs.parse import to_str
-from lionagi.libs.utils import copy, is_same_dtype
+from typing import Any
 
-from .message import MessageFlag, MessageRole, RoledMessage
+from pydantic import BaseModel
 
+from lionagi.utils import copy, is_same_dtype
 
-def prepare_assistant_response(
-    assistant_response: BaseModel | list[BaseModel] | dict | str | Any, /
-) -> Note:
-    """
-    Prepare an assistant's response for storage and transmission.
-
-    This function handles various input formats including:
-    - Single model outputs (response.choices[0].message.content)
-    - Streaming responses (response[i].choices[0].delta.content)
-    - Direct content in dictionaries or strings
+from .base import MessageRole, SenderRecipient
+from .message import MessageRole, RoledMessage, Template, jinja_env
 
-    Args:
-        assistant_response: The response content in any supported format
 
-    Returns:
-        Note: Formatted response content
-    """
+def prepare_assistant_response(
+    assistant_response: BaseModel | list[BaseModel] | dict | str | Any, /
+) -> dict:
     if assistant_response:
-        content = Note()
+        content = {}
         # Handle model.choices[0].message.content format
         if isinstance(assistant_response, BaseModel):
             content["assistant_response"] = (
@@ -73,68 +62,17 @@ def prepare_assistant_response(
         elif isinstance(assistant_response, str):
             content["assistant_response"] = assistant_response
         else:
-            content["assistant_response"] = to_str(assistant_response)
+            content["assistant_response"] = str(assistant_response)
         return content
     else:
-        return Note(assistant_response="")
+        return {"assistant_response": ""}
 
 
 class AssistantResponse(RoledMessage):
-    """
-    Represents a response from an assistant in the system.
-
-    This class handles responses from AI assistants, supporting both direct
-    text responses and structured model outputs. It provides access to both
-    the formatted response content and the underlying model data.
-
-    Example:
-        >>> response = AssistantResponse(
-        ...     assistant_response="The answer is 42",
-        ...     sender="assistant",
-        ...     recipient="user"
-        ... )
-        >>> print(response.response)
-        'The answer is 42'
-    """
-
-    @override
-    def __init__(
-        self,
-        assistant_response: BaseModel | JsonValue | MessageFlag,
-        sender: ID.Ref | MessageFlag,
-        recipient: ID.Ref | MessageFlag,
-        protected_init_params: dict | None = None,
-    ) -> None:
-        """
-        Initialize an AssistantResponse instance.
-
-        Args:
-            assistant_response: The content of the assistant's response
-            sender: The sender of the response
-            recipient: The recipient of the response
-            protected_init_params: Protected initialization parameters
-        """
-        message_flags = [assistant_response, sender, recipient]
-
-        if all(x == MessageFlag.MESSAGE_LOAD for x in message_flags):
-            protected_init_params = protected_init_params or {}
-            super().__init__(**protected_init_params)
-            return
 
-        if all(x == MessageFlag.MESSAGE_CLONE for x in message_flags):
-            super().__init__(role=MessageRole.ASSISTANT)
-            return
-
-        super().__init__(
-            role=MessageRole.ASSISTANT,
-            sender=sender or "N/A",
-            recipient=recipient,
-        )
-
-        content = prepare_assistant_response(assistant_response)
-        if "model_response" in content:
-            self.metadata["model_response"] = content.pop("model_response")
-        self.content = content
+    template: Template | str | None = jinja_env.get_template(
+        "assistant_response.jinja2"
+    )
 
     @property
     def response(self) -> str:
@@ -166,6 +104,44 @@ class AssistantResponse(RoledMessage):
         """
         return copy(self.metadata.get("model_response", {}))
 
-    @override
-    def _format_content(self) -> dict[str, str]:
-        return {"role": self.role.value, "content": self.response}
+    @classmethod
+    def create(
+        cls,
+        assistant_response: BaseModel | list[BaseModel] | dict | str | Any,
+        sender: SenderRecipient | None = None,
+        recipient: SenderRecipient | None = None,
+        template: Template | str | None = None,
+        **kwargs,
+    ):
+        content = prepare_assistant_response(assistant_response)
+        model_response = content.pop("model_response", {})
+        content.update(kwargs)
+        params = {
+            "content": content,
+            "role": MessageRole.ASSISTANT,
+            "recipient": recipient or MessageRole.USER,
+        }
+        if sender:
+            params["sender"] = sender
+        if template:
+            params["template"] = template
+        if model_response:
+            params["metadata"] = {"model_response": model_response}
+        return cls(**params)
+
+    def update(
+        self,
+        assistant_response: (
+            BaseModel | list[BaseModel] | dict | str | Any
+        ) = None,
+        sender: SenderRecipient | None = None,
+        recipient: SenderRecipient | None = None,
+        template: Template | str | None = None,
+        **kwargs,
+    ):
+        if assistant_response:
+            content = prepare_assistant_response(assistant_response)
+            self.content.update(content)
+        super().update(
+            sender=sender, recipient=recipient, template=template, **kwargs
+        )