lionagi 0.7.0__py3-none-any.whl → 0.7.2__py3-none-any.whl

lionagi/protocols/mail/package.py

@@ -2,6 +2,12 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+"""
+Defines `Package` and `PackageCategory`, encapsulating the contents
+and classification of mail items. Also includes a simple validator
+to ensure categories are valid.
+"""
+
 from enum import Enum
 from typing import Any
 
@@ -12,7 +18,20 @@ from .._concepts import Communicatable, Observable
 
 
 class PackageCategory(str, Enum):
-    """Enumeration of package categories in the Lion framework."""
+    """
+    Enumeration of common package categories in LionAGI:
+
+    - MESSAGE: General message content
+    - TOOL: A tool or action to be invoked
+    - IMODEL: Some internal model reference
+    - NODE: A node in a graph
+    - NODE_LIST: A list of nodes
+    - NODE_ID: A node ID
+    - START: A 'start' signal
+    - END: An 'end' signal
+    - CONDITION: A condition or gating logic
+    - SIGNAL: A more generic signal or marker
+    """
 
     MESSAGE = "message"
     TOOL = "tool"
@@ -27,7 +46,24 @@ class PackageCategory(str, Enum):
 
 
 def validate_category(value: Any) -> PackageCategory:
-    """Validate the category field."""
+    """
+    Validate and convert the input to a valid PackageCategory.
+
+    Parameters
+    ----------
+    value : Any
+        The input to interpret as a `PackageCategory`.
+
+    Returns
+    -------
+    PackageCategory
+        The validated category.
+
+    Raises
+    ------
+    ValueError
+        If the value cannot be converted into a valid package category.
+    """
     if isinstance(value, PackageCategory):
         return value
     try:
@@ -37,6 +73,23 @@ def validate_category(value: Any) -> PackageCategory:
 
 
 class Package(Observable):
+    """
+    A self-contained package that can be attached to `Mail` items.
+    Includes a unique ID, creation timestamp, category, payload item,
+    and an optional request source for context.
+
+    Attributes
+    ----------
+    category : PackageCategory
+        The classification or type of package.
+    item : Any
+        The main payload or data of this package.
+    request_source : ID[Communicatable] | None
+        An optional reference indicating the origin or context
+        for this package.
+    """
+
+    __slots__ = ("id", "created_at", "category", "item", "request_source")
 
     def __init__(
         self,
@@ -52,4 +105,5 @@ class Package(Observable):
         self.item = item
         self.request_source = request_source
 
-    __slots__ = ("id", "created_at", "category", "item", "request_source")
+
+# File: lionagi/protocols/mail/package.py

lionagi/protocols/messages/action_request.py

@@ -2,6 +2,12 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+"""
+Defines the `ActionRequest` class, a specific `RoledMessage` for requesting
+a function or action call within LionAGI. It is typically accompanied by
+arguments and can later be answered by an `ActionResponse`.
+"""
+
 from collections.abc import Callable
 from typing import Any
 
@@ -16,7 +22,23 @@ def prepare_action_request(
     function: str | Callable,
     arguments: dict,
 ) -> dict[str, Any]:
-
+    """
+    Build a structured dict describing the request details.
+
+    Args:
+        function (str | Callable):
+            The name (or callable) representing the function to invoke.
+        arguments (dict):
+            The arguments necessary for the function call.
+
+    Returns:
+        dict[str, Any]: A standardized dictionary containing
+        'action_request' -> {'function':..., 'arguments':...}
+
+    Raises:
+        ValueError: If `function` is neither a string nor callable, or
+            if `arguments` cannot be turned into a dictionary.
+    """
     if isinstance(function, Callable):
         function = function.__name__
     if hasattr(function, "function"):
@@ -36,6 +58,11 @@ def prepare_action_request(
 
 
 class ActionRequest(RoledMessage):
+    """
+    A message that requests an action or function to be executed.
+    It inherits from `RoledMessage` and includes function name,
+    arguments, and optional linking to a subsequent `ActionResponse`.
+    """
 
     template: Template | str | None = jinja_env.get_template(
         "action_request.jinja2"
@@ -44,50 +71,44 @@ class ActionRequest(RoledMessage):
     @property
     def action_response_id(self) -> IDType | None:
         """
-        Get the ID of the corresponding action response.
+        Get or set the ID of the corresponding action response.
 
         Returns:
-            IDType | None: The ID of the action response, or None if not responded
+            IDType | None: The ID of the action response, or None if none assigned.
         """
         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.
+        Get the entire 'action_request' dictionary if present.
 
         Returns:
-            dict[str, Any]: The request content excluding output
+            dict[str, Any]: The request content or empty dict if missing.
         """
         return copy(self.content.get("action_request", {}))
 
     @property
     def arguments(self) -> dict[str, Any]:
         """
-        Get the arguments for the action request.
+        Access just the 'arguments' from the action request.
 
         Returns:
-            dict[str, Any]: The arguments dictionary
+            dict[str, Any]: The arguments to be used by the function call.
         """
         return self.request.get("arguments", {})
 
     @property
     def function(self) -> str:
         """
-        Get the function name for the action request.
+        Name of the function to be invoked.
 
         Returns:
-            str: The name of the function to be invoked
+            str: The function name or empty string if none provided.
         """
         return self.request.get("function", "")
 
@@ -102,16 +123,24 @@ class ActionRequest(RoledMessage):
         **kwargs,
     ) -> "ActionRequest":
         """
-        Create a new ActionRequest instance.
+        Build a new ActionRequest.
 
         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
+            function (str | Callable | None):
+                The function or callable name.
+            arguments (dict | None):
+                Arguments for that function call.
+            sender (SenderRecipient | None):
+                The sender identifier or role.
+            recipient (SenderRecipient | None):
+                The recipient identifier or role.
+            template (Template | str | None):
+                Optional custom template.
+            **kwargs:
+                Extra key-value pairs to merge into the content.
 
         Returns:
-            ActionRequest: The new instance
+            ActionRequest: A newly constructed instance.
         """
         content = prepare_action_request(function, arguments)
         content.update(kwargs)
@@ -135,15 +164,36 @@ class ActionRequest(RoledMessage):
         template: Template | str | None = None,
         **kwargs,
     ):
+        """
+        Update this request with new function, arguments, or link to an
+        action response.
+
+        Args:
+            function (str): New function name, if changing.
+            arguments (dict): New arguments dictionary, if changing.
+            sender (SenderRecipient): New sender.
+            recipient (SenderRecipient): New recipient.
+            action_response (ActionResponse):
+                If provided, this request is flagged as responded.
+            template (Template | str | None):
+                Optional new template.
+            **kwargs:
+                Additional fields to store in content.
+
+        Raises:
+            ValueError: If the request is already responded to.
+        """
         if self.is_responded():
             raise ValueError("Cannot update a responded action request.")
 
+        # Link action response if given
         if (
             isinstance(action_response, RoledMessage)
             and action_response.class_name() == "ActionResponse"
         ):
             self.action_response_id = action_response.id
 
+        # If new function or arguments, create new 'action_request' content
         if any([function, arguments]):
             action_request = prepare_action_request(
                 function or self.function, arguments or self.arguments
@@ -155,11 +205,12 @@ class ActionRequest(RoledMessage):
 
     def is_responded(self) -> bool:
         """
-        Check if the action request has been responded to.
+        Check if there's a linked action response.
 
         Returns:
-            bool: True if the request has a response, False otherwise
+            bool: True if an action response ID is present.
         """
-        if self.action_response_id is not None:
-            return True
-        return False
+        return self.action_response_id is not None
+
+
+# File: lionagi/protocols/messages/action_request.py

lionagi/protocols/messages/action_response.py

@@ -2,6 +2,11 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+"""
+Defines `ActionResponse`, an `RoledMessage` that answers an `ActionRequest`
+with output from a function call or action.
+"""
+
 from typing import Any
 
 from typing_extensions import override
@@ -18,6 +23,16 @@ def prepare_action_response_content(
     action_request: ActionRequest,
     output: Any,
 ) -> dict:
+    """
+    Convert an ActionRequest + function output into response-friendly dictionary.
+
+    Args:
+        action_request (ActionRequest): The original action request.
+        output (Any): The result of the function call.
+
+    Returns:
+        dict: A dictionary containing `action_request_id` and `action_response`.
+    """
     return {
         "action_request_id": str(action_request.id),
         "action_response": {
@@ -29,6 +44,10 @@ def prepare_action_response_content(
 
 
 class ActionResponse(RoledMessage):
+    """
+    A message fulfilling an `ActionRequest`. It stores the function name,
+    the arguments used, and the output produced by the function.
+    """
 
     template: Template | str | None = jinja_env.get_template(
         "action_response.jinja2"
@@ -36,52 +55,32 @@ class ActionResponse(RoledMessage):
 
     @property
     def function(self) -> str:
-        """
-        Get the function name from the action response.
-
-        Returns:
-            str: The name of the function that was executed
-        """
+        """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
-        """
+        """Arguments used for the executed function."""
         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
-        """
+        """The result or returned data from the function call."""
         return self.content.get("action_response", {}).get("output", None)
 
     @property
     def response(self) -> dict[str, Any]:
         """
-        Get the complete action response as a dictionary.
+        A helper to get the entire 'action_response' dictionary.
 
         Returns:
-            dict[str, Any]: The response including function details and output
+            dict[str, Any]: The entire response, including function, arguments, 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
-        """
+        """The ID of the original action request."""
         return IDType.validate(self.content.get("action_request_id"))
 
     @override
@@ -94,7 +93,22 @@ class ActionResponse(RoledMessage):
         sender: SenderRecipient | None = None,
         recipient: SenderRecipient | None = None,
     ) -> "ActionResponse":
+        """
+        Build an ActionResponse from a matching `ActionRequest` and output.
+
+        Args:
+            action_request (ActionRequest): The original request being fulfilled.
+            output (Any, optional): The function output or result.
+            response_model (Any, optional):
+                If present and has `.output`, this is used instead of `output`.
+            sender (SenderRecipient, optional):
+                The role or ID of the sender (defaults to the request's recipient).
+            recipient (SenderRecipient, optional):
+                The role or ID of the recipient (defaults to the request's sender).
 
+        Returns:
+            ActionResponse: A new instance referencing the `ActionRequest`.
+        """
         if response_model:
             output = response_model.output
 
@@ -119,6 +133,18 @@ class ActionResponse(RoledMessage):
         template: Template | str | None = None,
         **kwargs,
     ):
+        """
+        Update this response with a new request reference or new output.
+
+        Args:
+            action_request (ActionRequest): The updated request.
+            output (Any): The new function output data.
+            response_model: If present, uses response_model.output.
+            sender (SenderRecipient): New sender ID or role.
+            recipient (SenderRecipient): New recipient ID or role.
+            template (Template | str | None): Optional new template.
+            **kwargs: Additional fields to store in content.
+        """
         if response_model:
             output = response_model.output
 
@@ -130,3 +156,6 @@ class ActionResponse(RoledMessage):
         super().update(
             sender=sender, recipient=recipient, template=template, **kwargs
         )
+
+
+# File: lionagi/protocols/messages/action_response.py

lionagi/protocols/messages/assistant_response.py

@@ -2,6 +2,10 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+"""
+Defines `AssistantResponse`, a specialized `RoledMessage` for the AI's
+assistant replies (usually from LLM or related).
+"""
 from typing import Any
 
 from pydantic import BaseModel
@@ -69,6 +73,11 @@ def prepare_assistant_response(
 
 
 class AssistantResponse(RoledMessage):
+    """
+    A message representing the AI assistant's reply, typically
+    from a model or LLM call. If the raw model output is available,
+    it's placed in `metadata["model_response"]`.
+    """
 
     template: Template | str | None = jinja_env.get_template(
         "assistant_response.jinja2"
@@ -76,31 +85,20 @@ class AssistantResponse(RoledMessage):
 
     @property
     def response(self) -> str:
-        """
-        Get the assistant response content.
-
-        Returns:
-            str: The formatted content of the assistant's response
-        """
+        """Get or set the text portion of the assistant's response."""
         return copy(self.content["assistant_response"])
 
     @response.setter
     def response(self, value: str) -> None:
-        """
-        Set the assistant response content.
-
-        Args:
-            value: The new response content
-        """
         self.content["assistant_response"] = value
 
     @property
     def model_response(self) -> dict | list[dict]:
         """
-        Get the underlying model response data.
+        Access the underlying model's raw data, if available.
 
         Returns:
-            Union[dict, List[dict]]: The complete model response data
+            dict or list[dict]: The stored model output data.
         """
         return copy(self.metadata.get("model_response", {}))
 
@@ -112,7 +110,26 @@ class AssistantResponse(RoledMessage):
         recipient: SenderRecipient | None = None,
         template: Template | str | None = None,
         **kwargs,
-    ):
+    ) -> "AssistantResponse":
+        """
+        Build an AssistantResponse from arbitrary assistant data.
+
+        Args:
+            assistant_response:
+                A pydantic model, list, dict, or string representing
+                an LLM or system response.
+            sender (SenderRecipient | None):
+                The ID or role denoting who sends this response.
+            recipient (SenderRecipient | None):
+                The ID or role to receive it.
+            template (Template | str | None):
+                Optional custom template.
+            **kwargs:
+                Additional content key-value pairs.
+
+        Returns:
+            AssistantResponse: The constructed instance.
+        """
         content = prepare_assistant_response(assistant_response)
         model_response = content.pop("model_response", {})
         content.update(kwargs)
@@ -139,9 +156,27 @@ class AssistantResponse(RoledMessage):
         template: Template | str | None = None,
         **kwargs,
     ):
+        """
+        Update this AssistantResponse with new data or fields.
+
+        Args:
+            assistant_response:
+                Additional or replaced assistant model output.
+            sender (SenderRecipient | None):
+                Updated sender.
+            recipient (SenderRecipient | None):
+                Updated recipient.
+            template (Template | str | None):
+                Optional new template.
+            **kwargs:
+                Additional content updates for `self.content`.
+        """
         if assistant_response:
             content = prepare_assistant_response(assistant_response)
             self.content.update(content)
         super().update(
             sender=sender, recipient=recipient, template=template, **kwargs
         )
+
+
+# File: lionagi/protocols/messages/assistant_response.py

lionagi/protocols/messages/base.py

@@ -2,6 +2,12 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+"""
+Holds foundational enumerations and types for messages, including
+roles like `SYSTEM`, `USER`, and helper functions for validating
+sender/recipient fields.
+"""
+
 from enum import Enum
 from typing import Any, TypeAlias
 
@@ -17,6 +23,9 @@ __all__ = (
 
 
 class MessageRole(str, Enum):
+    """
+    Predefined roles for conversation participants or message semantics.
+    """
 
     SYSTEM = "system"
     USER = "user"
@@ -26,15 +35,27 @@ class MessageRole(str, Enum):
 
 
 class MessageFlag(str, Enum):
+    """
+    Internal flags for certain message states, e.g., clones or loads.
+    """
 
     MESSAGE_CLONE = "MESSAGE_CLONE"
     MESSAGE_LOAD = "MESSAGE_LOAD"
 
 
 SenderRecipient: TypeAlias = IDType | MessageRole | str
+"""
+A union type indicating that a sender or recipient could be:
+- A lionagi IDType,
+- A string-based role or ID,
+- A specific enum role from `MessageRole`.
+"""
 
 
 class MessageField(str, Enum):
+    """
+    Common field names used in message objects.
+    """
 
     CREATED_AT = "created_at"
     ROLE = "role"
@@ -49,6 +70,18 @@ MESSAGE_FIELDS = [i.value for i in MessageField.__members__.values()]
 
 
 def validate_sender_recipient(value: Any, /) -> SenderRecipient:
+    """
+    Normalize a sender/recipient value into a recognized type.
+
+    Args:
+        value (Any): Input to interpret as a role or ID.
+
+    Returns:
+        SenderRecipient: A validated and normalized entity.
+
+    Raises:
+        ValueError: If the input cannot be recognized as a role or ID.
+    """
     if isinstance(value, MessageRole | MessageFlag):
         return value
 
@@ -71,3 +104,6 @@ def validate_sender_recipient(value: Any, /) -> SenderRecipient:
         return ID.get_id(value)
     except IDError as e:
         raise ValueError("Invalid sender or recipient") from e
+
+
+# File: lionagi/protocols/messages/base.py