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

lionagi/operations/ReAct/ReAct.py

@@ -21,7 +21,7 @@ async def ReAct(
     interpret: bool = False,
     tools: Any = None,
     tool_schemas: Any = None,
-    response_format: type[BaseModel] = None,
+    response_format: type[BaseModel] | BaseModel = None,
     extension_allowed: bool = False,
     max_extensions: int | None = None,
     response_kwargs: dict | None = None,
@@ -60,7 +60,7 @@ async def ReAct(
     kwargs_for_operate["actions"] = True
     kwargs_for_operate["reason"] = True
 
-    # We'll pass the refined instruct_dict plus the user’s other kwargs
+    # We'll pass the refined instruct_dict plus the user's other kwargs
     from .utils import ReActAnalysis
 
     # Step 1: Generate initial ReAct analysis

lionagi/operations/_act/act.py

@@ -7,9 +7,10 @@ from typing import TYPE_CHECKING
 
 from pydantic import BaseModel
 
-from lionagi.protocols.types import ActionResponse, Log
+from lionagi.protocols.types import Log
 
 if TYPE_CHECKING:
+    from lionagi.operatives.types import ActionResponseModel
     from lionagi.session.branch import Branch
 
 
@@ -17,7 +18,7 @@ async def _act(
     branch: "Branch",
     action_request: BaseModel | dict,
     suppress_errors: bool = False,
-) -> ActionResponse:
+) -> "ActionResponseModel":
 
     _request = {}
 
@@ -35,7 +36,13 @@ async def _act(
     try:
         func_call = await branch._action_manager.invoke(_request)
     except Exception as e:
-        branch._log_manager.log(Log(content={"error": str(e)}))
+        content = {
+            "error": str(e),
+            "function": _request.get("function"),
+            "arguments": _request.get("arguments"),
+            "branch": str(branch.id),
+        }
+        branch._log_manager.log(Log(content=content))
         if suppress_errors:
             logging.error(
                 f"Error invoking action '{_request['function']}': {e}"

lionagi/operations/communicate/communicate.py

@@ -37,65 +37,6 @@ async def communicate(
     operative_model=None,
     **kwargs,
 ):
-    """
-    A simpler orchestration than `operate()`, typically without tool invocation.
-
-    **Flow**:
-        1. Sends an instruction (or conversation) to the chat model.
-        2. Optionally parses the response into a structured model or fields.
-        3. Returns either the raw string, the parsed model, or a dict of fields.
-
-    Args:
-        instruction (Instruction | dict, optional):
-            The user's main query or data.
-        guidance (JsonValue, optional):
-            Additional instructions or context for the LLM.
-        context (JsonValue, optional):
-            Extra data or context.
-        plain_content (str, optional):
-            Plain text content appended to the instruction.
-        sender (SenderRecipient, optional):
-            Sender ID (defaults to `Branch.user`).
-        recipient (SenderRecipient, optional):
-            Recipient ID (defaults to `self.id`).
-        progression (ID.IDSeq, optional):
-            Custom ordering of messages.
-        request_model (type[BaseModel] | BaseModel | None, optional):
-            Model for validating or structuring the LLM's response.
-        response_format (type[BaseModel], optional):
-            Alias for `request_model`. If both are provided, raises ValueError.
-        request_fields (dict|list[str], optional):
-            If you only need certain fields from the LLM's response.
-        imodel (iModel, optional):
-            Deprecated alias for `chat_model`.
-        chat_model (iModel, optional):
-            An alternative to the default chat model.
-        parse_model (iModel, optional):
-            If parsing is needed, you can override the default parse model.
-        skip_validation (bool, optional):
-            If True, returns the raw response string unvalidated.
-        images (list, optional):
-            Any relevant images.
-        image_detail (Literal["low","high","auto"], optional):
-            Image detail level (if used).
-        num_parse_retries (int, optional):
-            Maximum parsing retries (capped at 5).
-        fuzzy_match_kwargs (dict, optional):
-            Additional settings for fuzzy field matching (if used).
-        clear_messages (bool, optional):
-            Whether to clear stored messages before sending.
-        operative_model (type[BaseModel], optional):
-            Deprecated, alias for `response_format`.
-        **kwargs:
-            Additional arguments for the underlying LLM call.
-
-    Returns:
-        Any:
-            - Raw string (if `skip_validation=True`),
-            - A validated Pydantic model,
-            - A dict of the requested fields,
-            - or `None` if parsing fails and `handle_validation='return_none'`.
-    """
     if operative_model:
         logging.warning(
             "operative_model is deprecated. Use response_format instead."

lionagi/operations/interpret/interpret.py

@@ -30,11 +30,10 @@ async def interpret(
     # Default temperature if none provided
     kwargs["temperature"] = kwargs.get("temperature", 0.1)
 
-    refined_prompt = await branch.communicate(
+    refined_prompt = await branch.chat(
         instruction=instruction,
         guidance=guidance,
         context=context,
-        skip_validation=True,
         **kwargs,
     )
     return str(refined_prompt)

lionagi/operations/operate/operate.py

@@ -7,9 +7,14 @@ from typing import TYPE_CHECKING, Literal
 
 from pydantic import BaseModel, JsonValue
 
-from lionagi.operatives.models.field_model import FieldModel
-from lionagi.operatives.models.model_params import ModelParams
-from lionagi.operatives.types import Instruct, Operative, Step, ToolRef
+from lionagi.operatives.types import (
+    FieldModel,
+    Instruct,
+    ModelParams,
+    Operative,
+    Step,
+    ToolRef,
+)
 from lionagi.protocols.types import Instruction, Progression, SenderRecipient
 from lionagi.service.imodel import iModel
 
@@ -110,7 +115,7 @@ async def operate(
 
     # If we want to auto-invoke tools, fetch or generate the schemas
     if invoke_actions and tools:
-        tool_schemas = branch.acts.get_tool_schema(tools=tools)
+        tool_schemas = tool_schemas or branch.acts.get_tool_schema(tools=tools)
 
     # 2) Send the instruction to the chat model
     ins, res = await branch.chat(
@@ -138,7 +143,7 @@ async def operate(
     if skip_validation:
         return operative if return_operative else operative.response_str_dict
 
-    # 5) Parse or validate the response into the operative’s model
+    # 5) Parse or validate the response into the operative's model
     response_model = operative.update_response_model(res.response)
     if not isinstance(response_model, BaseModel):
         # If the response isn't directly a model, attempt a parse

lionagi/operations/parse/parse.py

@@ -35,42 +35,6 @@ async def parse(
     suppress_conversion_errors: bool = False,
     response_format=None,
 ):
-    """Attempts to parse text into a structured Pydantic model.
-
-    Uses optional fuzzy matching to handle partial or unclear fields.
-
-    Args:
-        text (str): The raw text to parse.
-        handle_validation (Literal["raise","return_value","return_none"]):
-            What to do if parsing fails. Defaults to "return_value".
-        max_retries (int):
-            How many times to retry parsing if it fails.
-        request_type (type[BaseModel], optional):
-            The Pydantic model to parse into.
-        operative (Operative, optional):
-            If provided, uses its model and max_retries setting.
-        similarity_algo (str):
-            The similarity algorithm for fuzzy field matching.
-        similarity_threshold (float):
-            A threshold for fuzzy matching (0.0 - 1.0).
-        fuzzy_match (bool):
-            If True, tries to match unrecognized keys to known ones.
-        handle_unmatched (Literal["ignore","raise","remove","fill","force"]):
-            How to handle unmatched fields.
-        fill_value (Any):
-            A default value used when fill is needed.
-        fill_mapping (dict[str, Any] | None):
-            A mapping from field -> fill value override.
-        strict (bool):
-            If True, raises errors on ambiguous fields or data types.
-        suppress_conversion_errors (bool):
-            If True, logs or ignores errors during data conversion.
-
-    Returns:
-        BaseModel | Any | None:
-            The parsed model instance, or a dict/string/None depending
-            on the handling mode.
-    """
     _should_try = True
     num_try = 0
     response_model = text

lionagi/operations/plan/plan.py

@@ -6,7 +6,7 @@ from typing import Any, Literal
 
 from pydantic import BaseModel
 
-from lionagi.operatives.instruct.instruct import (
+from lionagi.operatives.types import (
     LIST_INSTRUCT_FIELD_MODEL,
     Instruct,
     InstructResponse,
@@ -293,7 +293,7 @@ async def plan(
             # ---------------------------------------------------------
             # Strategy C: SEQUENTIAL_CONCURRENT_CHUNK
             #   - process plan steps in chunks (one chunk after another),
-            #   - each chunk’s steps run in parallel.
+            #   - each chunk's steps run in parallel.
             # ---------------------------------------------------------
             case "sequential_concurrent_chunk":
                 chunk_size = (execution_kwargs or {}).get("chunk_size", 5)
@@ -334,7 +334,7 @@ async def plan(
             # Strategy D: CONCURRENT_SEQUENTIAL_CHUNK
             #   - split plan steps into chunks,
             #   - run all chunks in parallel,
-            #   - but each chunk’s steps run sequentially.
+            #   - but each chunk's steps run sequentially.
             # ---------------------------------------------------------
             case "concurrent_sequential_chunk":
                 chunk_size = (execution_kwargs or {}).get("chunk_size", 5)

lionagi/operatives/action/manager.py

@@ -2,6 +2,12 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+"""
+Defines the `ActionManager` class, a specialized Manager that registers
+`Tool` objects (or callables) for function invocation. It can match
+incoming requests (ActionRequest) to a registered tool, then run it.
+"""
+
 from typing import Any
 
 from lionagi.protocols._concepts import Manager
@@ -17,9 +23,22 @@ __all__ = ("ActionManager",)
 
 
 class ActionManager(Manager):
+    """
+    A manager that registers function-based tools and invokes them
+    when triggered by an ActionRequest. Tools can be registered
+    individually or in bulk, and each tool must have a unique name.
+    """
 
     def __init__(self, *args: FuncTool, **kwargs) -> None:
+        """
+        Create an ActionManager, optionally registering initial tools.
 
+        Args:
+            *args (FuncTool):
+                A variable number of tools or callables.
+            **kwargs:
+                Additional named arguments that are also considered tools.
+        """
         super().__init__()
         self.registry: dict[str, Tool] = {}
 
@@ -27,24 +46,19 @@ class ActionManager(Manager):
         if args:
             tools.extend(to_list(args, dropna=True, flatten=True))
         if kwargs:
-            tools.extend(
-                to_list(kwargs, dropna=True, flatten=True, use_values=True)
-            )
+            tools.extend(to_list(kwargs.values(), dropna=True, flatten=True))
+
         self.register_tools(tools, update=True)
 
     def __contains__(self, tool: FuncToolRef) -> bool:
-        """Check if a tool is registered in the registry.
-
-        Supports checking by:
-        - Tool object
-        - Tool name (string)
-        - Callable function
-
-        Args:
-            tool: The tool to check for registration.
+        """
+        Check if a tool is registered, by either:
+        - The Tool object itself,
+        - A string name for the function,
+        - Or the callable's __name__.
 
         Returns:
-            bool: True if tool is registered, False otherwise.
+            bool: True if found, else False.
         """
         if isinstance(tool, Tool):
             return tool.function in self.registry
@@ -54,24 +68,21 @@ class ActionManager(Manager):
             return tool.__name__ in self.registry
         return False
 
-    def register_tool(
-        self,
-        tool: FuncTool,
-        update: bool = False,
-    ) -> None:
-        """Register a single tool in the registry.
-
-        If the tool is a callable function, it is automatically converted
-        to a Tool object. Existing tools can be updated if update=True.
+    def register_tool(self, tool: FuncTool, update: bool = False) -> None:
+        """
+        Register a single tool/callable in the manager.
 
         Args:
-            tool: The tool to register (Tool object or callable).
-            update: If True, update existing tool; if False, raise error.
+            tool (FuncTool):
+                A `Tool` object or a raw callable function.
+            update (bool):
+                If True, allow replacing an existing tool with the same name.
 
         Raises:
             ValueError: If tool already registered and update=False.
-            TypeError: If tool is not a Tool object or callable.
+            TypeError: If `tool` is not a Tool or callable.
         """
+        # Check if tool already exists
         if not update and tool in self:
             name = None
             if isinstance(tool, Tool):
@@ -80,81 +91,85 @@ class ActionManager(Manager):
                 name = tool.__name__
             raise ValueError(f"Tool {name} is already registered.")
 
+        # Convert raw callable to a Tool if needed
         if callable(tool):
             tool = Tool(func_callable=tool)
         if not isinstance(tool, Tool):
-            raise TypeError("Please register a Tool object or callable.")
-
+            raise TypeError(
+                "Must provide a `Tool` object or a callable function."
+            )
         self.registry[tool.function] = tool
 
     def register_tools(
-        self,
-        tools: list[FuncTool] | FuncTool,
-        update: bool = False,
+        self, tools: list[FuncTool] | FuncTool, update: bool = False
     ) -> None:
-        """Register multiple tools in the registry.
-
-        Handles both single tools and lists of tools. Each tool can be
-        either a Tool object or a callable function.
+        """
+        Register multiple tools at once.
 
         Args:
-            tools: Single tool or list of tools to register.
-            update: If True, update existing tools; if False, raise error.
+            tools (list[FuncTool] | FuncTool):
+                A single or list of tools/callables.
+            update (bool):
+                If True, allow updating existing tools.
 
         Raises:
-            ValueError: If any tool is already registered.
-            TypeError: If any tool is not a Tool object or callable.
+            ValueError: If a duplicate tool is found and update=False.
+            TypeError: If any item is not a Tool or callable.
         """
         tools_list = tools if isinstance(tools, list) else [tools]
-        [
-            self.register_tool(tool, update=update)
-            for tool in to_list(tools_list, dropna=True, flatten=True)
-        ]
+        for t in tools_list:
+            self.register_tool(t, update=update)
 
     def match_tool(
         self, action_request: ActionRequest | ActionRequestModel | dict
     ) -> FunctionCalling:
+        """
+        Convert an ActionRequest (or dict with "function"/"arguments")
+        into a `FunctionCalling` instance by finding the matching tool.
+
+        Raises:
+            TypeError: If `action_request` is an unsupported type.
+            ValueError: If no matching tool is found in the registry.
+
+        Returns:
+            FunctionCalling: The event object that can be invoked.
+        """
         if not isinstance(
             action_request, ActionRequest | ActionRequestModel | dict
         ):
             raise TypeError(f"Unsupported type {type(action_request)}")
 
-        func = (
-            action_request["function"]
-            if isinstance(action_request, dict)
-            else action_request.function
-        )
-        args = (
-            action_request["arguments"]
-            if isinstance(action_request, dict)
-            else action_request.arguments
-        )
-        tool = self.registry.get(func, None)
+        func, args = None, None
+        if isinstance(action_request, dict):
+            func = action_request["function"]
+            args = action_request["arguments"]
+        else:
+            func = action_request.function
+            args = action_request.arguments
 
+        tool = self.registry.get(func, None)
         if not isinstance(tool, Tool):
             raise ValueError(f"Function {func} is not registered.")
+
         return FunctionCalling(func_tool=tool, arguments=args)
 
     async def invoke(
-        self, func_call: ActionRequestModel | ActionRequest
-    ) -> FunctionCalling | Execution | None:
-        """Invoke a tool based on the provided function call.
+        self,
+        func_call: ActionRequestModel | ActionRequest,
+    ) -> FunctionCalling:
+        """
+        High-level API to parse and run a function call.
 
-        1. Matches function call to registered tool
-        2. Creates FunctionCalling instance
-        3. Invokes function with arguments
-        4. Logs execution details
-        5. Returns result
+        Steps:
+          1) Convert `func_call` to FunctionCalling via `match_tool`.
+          2) `invoke()` the resulting object.
+          3) Return the `FunctionCalling`, which includes `execution`.
 
         Args:
-            func_call: Function call specification in supported format.
-            log_manager: Optional logger for execution tracking.
+            func_call: The action request model or ActionRequest object.
 
         Returns:
-            Result of tool invocation after processing pipeline.
-
-        Raises:
-            ValueError: If function not registered or call format invalid.
+            `FunctionCalling` event after it completes execution.
         """
         function_calling = self.match_tool(func_call)
         await function_calling.invoke()
@@ -162,11 +177,7 @@ class ActionManager(Manager):
 
     @property
     def schema_list(self) -> list[dict[str, Any]]:
-        """List all tool schemas currently registered.
-
-        Returns:
-            List of OpenAI function schemas for all registered tools.
-        """
+        """Return the list of JSON schemas for all registered tools."""
         return [tool.tool_schema for tool in self.registry.values()]
 
     def get_tool_schema(
@@ -175,20 +186,25 @@ class ActionManager(Manager):
         auto_register: bool = True,
         update: bool = False,
     ) -> dict:
-        """Retrieve the schema for specific tools or all tools.
+        """
+        Retrieve schemas for a subset of tools or for all.
 
         Args:
-            tools: Specification of which tools to retrieve schemas for.
-                If True, return all tools. If False, return empty dict.
-                Can also be a specific tool or list of tools.
-            **kwargs: Additional keyword arguments to include in output.
+            tools (ToolRef):
+                - If True, return schema for all tools.
+                - If False, return an empty dict.
+                - If specific tool(s), returns only those schemas.
+            auto_register (bool):
+                If a tool (callable) is not yet in the registry, register if True.
+            update (bool):
+                If True, allow updating existing tools.
 
         Returns:
-            Dictionary containing tool schemas and additional kwargs.
+            dict: e.g., {"tools": [list of schemas]}
 
         Raises:
-            ValueError: If a specified tool is not registered.
-            TypeError: If an unsupported tool type is provided.
+            ValueError: If requested tool is not found and auto_register=False.
+            TypeError: If tool specification is invalid.
         """
         if isinstance(tools, list | tuple) and len(tools) == 1:
             tools = tools[0]
@@ -207,10 +223,15 @@ class ActionManager(Manager):
         tool: Any,
         auto_register: bool = True,
         update: bool = False,
-    ) -> dict[str, Any] | list[dict[str, Any]]:
+    ) -> list[dict[str, Any]] | dict[str, Any]:
+        """
+        Internal helper to handle retrieval or registration of a single or
+        multiple tools, returning their schema(s).
+        """
         if isinstance(tool, dict):
-            return tool
+            return tool  # Already a schema
         if callable(tool):
+            # Possibly unregistered function
             name = tool.__name__
             if name not in self.registry:
                 if auto_register:
@@ -233,3 +254,5 @@ class ActionManager(Manager):
 
 
 __all__ = ["ActionManager"]
+
+# File: lionagi/operatives/action/manager.py

lionagi/operatives/action/request_response_model.py

@@ -2,6 +2,12 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+"""
+Defines Pydantic models for action requests and responses. They typically map
+to conversation messages describing which function is called, with what arguments,
+and any returned output.
+"""
+
 from typing import Any
 
 from pydantic import Field, field_validator
@@ -28,6 +34,10 @@ __all__ = (
 
 
 class ActionRequestModel(HashableModel):
+    """
+    Captures a single action request, typically from a user or system message.
+    Includes the name of the function and the arguments to be passed.
+    """
 
     function: str | None = Field(
         None,
@@ -43,6 +53,12 @@ class ActionRequestModel(HashableModel):
 
     @field_validator("arguments", mode="before")
     def validate_arguments(cls, value: Any) -> dict[str, Any]:
+        """
+        Coerce arguments into a dictionary if possible, recursively.
+
+        Raises:
+            ValueError if the data can't be coerced.
+        """
         return to_dict(
             value,
             fuzzy_parse=True,
@@ -52,10 +68,19 @@ class ActionRequestModel(HashableModel):
 
     @field_validator("function", mode="before")
     def validate_function(cls, value: str) -> str:
+        """
+        Ensure the function name is a valid non-empty string (if provided).
+        """
         return validate_nullable_string_field(cls, value, "function", False)
 
     @classmethod
     def create(cls, content: str):
+        """
+        Attempt to parse a string (usually from a conversation or JSON) into
+        one or more ActionRequestModel instances.
+
+        If no valid structure is found, returns an empty list.
+        """
         try:
             content = parse_action_request(content)
             if content:
@@ -75,6 +100,10 @@ ACTION_REQUESTS_FIELD = FieldModel(
 
 
 class ActionResponseModel(HashableModel):
+    """
+    Encapsulates a function's output after being called. Typically
+    references the original function name, arguments, and the result.
+    """
 
     function: str = Field(default_factory=str, title="Function")
     arguments: dict[str, Any] = Field(default_factory=dict)
@@ -88,3 +117,5 @@ ACTION_RESPONSES_FIELD = FieldModel(
     title="Actions",
     description="**do not fill**",
 )
+
+# File: lionagi/operatives/action/request_response_model.py