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

lionagi/core/communication/action_request.py

@@ -0,0 +1,163 @@
+# Copyright (c) 2023 - 2024, HaiyangLi <quantocean.li at gmail dot com>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from typing_extensions import override
+
+from lionagi.core.typing import ID, Any, Callable, LnID, Note
+from lionagi.libs.parse import to_dict
+from lionagi.libs.utils import copy
+
+from .message import MessageFlag, MessageRole, RoledMessage
+
+
+def prepare_action_request(
+    function: str | Callable,
+    arguments: dict,
+) -> Note:
+    """
+    Prepare an action request with function and arguments.
+
+    This function validates and formats the action request parameters,
+    ensuring arguments are properly structured as a dictionary.
+
+    Args:
+        function: Function to execute, either as name or callable
+        arguments: Arguments to pass to the function
+
+    Returns:
+        Note: Formatted action request
+
+    Raises:
+        ValueError: If arguments cannot be converted to a dictionary
+    """
+    args = copy(arguments)
+    if not isinstance(arguments, dict):
+        try:
+            arguments = to_dict(
+                args, fuzzy_parse=True, str_type="json", suppress=True
+            )
+            if not arguments:
+                arguments = to_dict(args, str_type="xml", suppress=True)
+            if not arguments or not isinstance(arguments, dict):
+                raise ValueError
+        except Exception:
+            raise ValueError("Arguments must be a dictionary.")
+    return Note(action_request={"function": function, "arguments": arguments})
+
+
+class ActionRequest(RoledMessage):
+    """
+    Represents a request for an action in the system.
+
+    This class encapsulates the details needed to execute a function call,
+    including the function name/reference and its arguments. It also tracks
+    whether the request has been responded to.
+
+    Example:
+        >>> request = ActionRequest(
+        ...     function="calculate_sum",
+        ...     arguments={"numbers": [1, 2, 3]},
+        ...     sender="user",
+        ...     recipient="system"
+        ... )
+        >>> print(request.function)
+        'calculate_sum'
+    """
+
+    @override
+    def __init__(
+        self,
+        function: str | Callable | MessageFlag,
+        arguments: dict | MessageFlag,
+        sender: ID.Ref | MessageFlag = None,
+        recipient: ID.Ref | MessageFlag = None,
+        protected_init_params: dict | None = None,
+    ) -> None:
+        """
+        Initialize an ActionRequest instance.
+
+        Args:
+            function: The function to be invoked
+            arguments: The arguments for the function
+            sender: The sender of the request
+            recipient: The recipient of the request
+            protected_init_params: Protected initialization parameters
+        """
+        message_flags = [function, arguments, 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
+
+        function = function.__name__ if callable(function) else function
+
+        super().__init__(
+            role=MessageRole.ASSISTANT,
+            content=prepare_action_request(
+                function=function, arguments=arguments
+            ),
+            sender=sender,
+            recipient=recipient,
+        )
+
+    @property
+    def action_response_id(self) -> LnID | None:
+        """
+        Get the ID of the corresponding action response.
+
+        Returns:
+            LnID | None: The ID of the action response, or None if not responded
+        """
+        return self.content.get("action_response_id", None)
+
+    @property
+    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
+        """
+        return self.action_response_id is not None
+
+    @property
+    def request(self) -> dict[str, Any]:
+        """
+        Get the action request content as a dictionary.
+
+        Returns:
+            dict[str, Any]: The request content excluding output
+        """
+        a = copy(self.content.get("action_request", {}))
+        a.pop("output", None)
+        return a
+
+    @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", "")
+
+    @override
+    def _format_content(self) -> dict[str, Any]:
+        return {"role": self.role.value, "content": self.request}

lionagi/core/communication/action_response.py

@@ -0,0 +1,149 @@
+# Copyright (c) 2023 - 2024, HaiyangLi <quantocean.li at gmail dot com>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from lionagi.core.typing import ID, Any, Note, override
+from lionagi.libs.utils import copy
+
+from .action_request import ActionRequest
+from .message import MessageFlag, MessageRole, RoledMessage
+
+
+def prepare_action_response_content(
+    action_request: ActionRequest,
+    output: Any,
+) -> Note:
+    """
+    Prepare the content for an action response.
+
+    Creates a standardized Note object containing the response details and
+    maintaining reference to the original request.
+
+    Args:
+        action_request: The original action request being responded to
+        output: The result from executing the requested function
+
+    Returns:
+        Note: Formatted action response content
+    """
+    return Note(
+        action_request_id=action_request.ln_id,
+        action_response={
+            "function": action_request.function,
+            "arguments": action_request.arguments,
+            "output": output,
+        },
+    )
+
+
+class ActionResponse(RoledMessage):
+    """
+    Represents a response to an action request in the system.
+
+    This class encapsulates the result of executing an action request,
+    maintaining references to the original request and providing access
+    to the execution results.
+
+    Example:
+        >>> request = ActionRequest(function="sum", arguments={"nums": [1,2,3]})
+        >>> response = ActionResponse(action_request=request, output=6)
+        >>> print(response.output)
+        6
+    """
+
+    @override
+    def __init__(
+        self,
+        action_request: ID[ActionRequest].Item,
+        output: Any = None,
+        protected_init_params: dict | None = None,
+    ) -> None:
+        """
+        Initialize an ActionResponse instance.
+
+        Args:
+            action_request: The original action request to respond to
+            output: The result from the function execution
+            protected_init_params: Protected initialization parameters
+
+        Raises:
+            ValueError: If action_request is invalid or already responded to
+        """
+        message_flags = [
+            action_request,
+            output,
+        ]
+
+        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,
+            recipient=action_request.sender,
+            sender=action_request.recipient,
+            content=prepare_action_response_content(
+                action_request=action_request,
+                output=output,
+            ),
+        )
+        action_request.content["action_response_id"] = self.ln_id
+
+    @property
+    def function(self) -> str:
+        """
+        Get the function name from the action response.
+
+        Returns:
+            str: The name of the function that was executed
+        """
+        return copy(self.content.get(["action_response", "function"]))
+
+    @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 copy(self.content.get(["action_response", "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", "output"])
+
+    @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) -> ID[ActionRequest].ID | None:
+        """
+        Get the ID of the corresponding action request.
+
+        Returns:
+            ID[ActionRequest].ID | None: The ID of the original request
+        """
+        return copy(self.content.get("action_request_id", None))
+
+    @override
+    def _format_content(self) -> dict[str, Any]:
+        return {"role": self.role.value, "content": self.response}

lionagi/core/communication/assistant_response.py

@@ -0,0 +1,161 @@
+# Copyright (c) 2023 - 2024, HaiyangLi <quantocean.li at gmail dot com>
+#
+# 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 .message import MessageFlag, MessageRole, RoledMessage
+
+
+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
+
+    Args:
+        assistant_response: The response content in any supported format
+
+    Returns:
+        Note: Formatted response content
+    """
+    if assistant_response:
+        content = Note()
+        # Handle model.choices[0].message.content format
+        if isinstance(assistant_response, BaseModel):
+            content["assistant_response"] = (
+                assistant_response.choices[0].message.content or ""
+            )
+            content["model_response"] = assistant_response.model_dump(
+                exclude_none=True, exclude_unset=True
+            )
+        # Handle streaming response[i].choices[0].delta.content format
+        elif isinstance(assistant_response, list):
+            if is_same_dtype(assistant_response, BaseModel):
+                msg = "".join(
+                    [
+                        i.choices[0].delta.content or ""
+                        for i in assistant_response
+                    ]
+                )
+                content["assistant_response"] = msg
+                content["model_response"] = [
+                    i.model_dump(
+                        exclude_none=True,
+                        exclude_unset=True,
+                    )
+                    for i in assistant_response
+                ]
+            elif is_same_dtype(assistant_response, dict):
+                msg = "".join(
+                    [
+                        i["choices"][0]["delta"]["content"] or ""
+                        for i in assistant_response
+                    ]
+                )
+                content["assistant_response"] = msg
+                content["model_response"] = assistant_response
+        elif isinstance(assistant_response, dict):
+            if "content" in assistant_response:
+                content["assistant_response"] = assistant_response["content"]
+            elif "choices" in assistant_response:
+                content["assistant_response"] = assistant_response["choices"][
+                    0
+                ]["message"]["content"]
+            content["model_response"] = assistant_response
+        elif isinstance(assistant_response, str):
+            content["assistant_response"] = assistant_response
+        else:
+            content["assistant_response"] = to_str(assistant_response)
+        return content
+    else:
+        return Note(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
+
+    @property
+    def response(self) -> str:
+        """
+        Get the assistant response content.
+
+        Returns:
+            str: The formatted content of the assistant's response
+        """
+        return copy(self.content["assistant_response"])
+
+    @property
+    def model_response(self) -> dict | list[dict]:
+        """
+        Get the underlying model response data.
+
+        Returns:
+            Union[dict, List[dict]]: The complete model response data
+        """
+        return copy(self.metadata.get("model_response", {}))
+
+    @override
+    def _format_content(self) -> dict[str, str]:
+        return {"role": self.role.value, "content": self.response}

lionagi/core/communication/base_mail.py

@@ -0,0 +1,49 @@
+# Copyright (c) 2023 - 2024, HaiyangLi <quantocean.li at gmail dot com>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from lionagi.core.generic.types import Element
+from lionagi.core.typing import ID, Any, Communicatable, Field, field_validator
+
+from .utils import validate_sender_recipient
+
+
+class BaseMail(Element, Communicatable):
+    """
+    Base class for mail-like communication in the LION system.
+
+    This class provides the foundation for all message-based communication,
+    implementing sender and recipient functionality with proper validation.
+    It inherits from Element for core functionality and Communicatable for
+    communication capabilities.
+
+    Attributes:
+        sender (ID.SenderRecipient): The ID of the sender node or role.
+            Can be a specific node ID or one of: "system", "user", "assistant", "N/A"
+        recipient (ID.SenderRecipient): The ID of the recipient node or role.
+            Can be a specific node ID or one of: "system", "user", "assistant", "N/A"
+
+    Example:
+        >>> mail = BaseMail(sender="user", recipient="assistant")
+        >>> print(mail.sender)
+        'user'
+        >>> print(mail.recipient)
+        'assistant'
+    """
+
+    sender: ID.SenderRecipient = Field(
+        default="N/A",
+        title="Sender",
+        description="The ID of the sender node or a role.",
+    )
+
+    recipient: ID.SenderRecipient = Field(
+        default="N/A",
+        title="Recipient",
+        description="The ID of the recipient node or a role.",
+    )
+
+    @field_validator("sender", "recipient", mode="before")
+    @classmethod
+    def _validate_sender_recipient(cls, value: Any) -> ID.SenderRecipient:
+        return validate_sender_recipient(value)