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

lionagi/operatives/action/function_calling.py

@@ -0,0 +1,136 @@
+# Copyright (c) 2023 - 2024, HaiyangLi <quantocean.li at gmail dot com>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import asyncio
+from typing import Any, Self
+
+from pydantic import Field, model_validator
+
+from lionagi.protocols.generic.event import Event, EventStatus
+from lionagi.utils import is_coro_func
+
+from .tool import Tool
+
+
+class FunctionCalling(Event):
+    """Handles asynchronous function execution with pre/post processing.
+
+    This class manages function calls with optional preprocessing and
+    postprocessing, handling both synchronous and asynchronous functions.
+    """
+
+    func_tool: Tool = Field(
+        ...,
+        description="Tool instance containing the function to be called",
+        exclude=True,
+    )
+
+    arguments: dict[str, Any] = Field(
+        ..., description="Dictionary of arguments to pass to the function"
+    )
+
+    @model_validator(mode="after")
+    def _validate_strict_tool(self) -> Self:
+        if self.func_tool.strict_func_call is True:
+            if (
+                not set(self.arguments.keys())
+                == self.func_tool.required_fields
+            ):
+                raise ValueError("arguments must match the function schema")
+
+        else:
+            if not self.func_tool.minimum_acceptable_fields.issubset(
+                set(self.arguments.keys())
+            ):
+                raise ValueError("arguments must match the function schema")
+        return self
+
+    @property
+    def function(self):
+        return self.func_tool.function
+
+    async def invoke(self) -> None:
+        """Execute the function call with pre/post processing.
+
+        Handles both synchronous and asynchronous functions, including optional
+        preprocessing of arguments and postprocessing of results.
+        """
+        start = asyncio.get_event_loop().time()
+
+        async def _preprocess(kwargs):
+            if is_coro_func(self.func_tool.preprocessor):
+                return await self.func_tool.preprocessor(
+                    kwargs, **self.func_tool.preprocessor_kwargs
+                )
+            return self.func_tool.preprocessor(
+                kwargs, **self.func_tool.preprocessor_kwargs
+            )
+
+        async def _post_process(arg: Any):
+            if is_coro_func(self.func_tool.postprocessor):
+                return await self.func_tool.postprocessor(
+                    arg, **self.func_tool.postprocessor_kwargs
+                )
+            return self.func_tool.postprocessor(
+                arg, **self.func_tool.postprocessor_kwargs
+            )
+
+        async def _inner() -> Any:
+            """Execute the function with pre/post processing.
+
+            Returns:
+                Function execution result after processing.
+            """
+            response = None
+            if self.func_tool.preprocessor:
+                self.arguments = await _preprocess(self.arguments)
+
+            if is_coro_func(self.func_tool.func_callable):
+                response = await self.func_tool.func_callable(**self.arguments)
+            else:
+                response = self.func_tool.func_callable(**self.arguments)
+
+            if self.func_tool.postprocessor:
+                response = await _post_process(response)
+            return response
+
+        try:
+            response = await _inner()
+            self.execution.duration = asyncio.get_event_loop().time() - start
+            self.execution.status = EventStatus.COMPLETED
+            self.execution.response = response
+        except Exception as e:
+            self.execution.duration = asyncio.get_event_loop().time() - start
+            self.execution.status = EventStatus.FAILED
+            self.execution.error = str(e)
+
+    def __str__(self) -> str:
+        """Returns a string representation of the function call.
+
+        Returns:
+            A string in the format "function_name(arguments)".
+        """
+        return f"{self.func_tool.function}({self.arguments})"
+
+    def __repr__(self) -> str:
+        """Returns a detailed string representation of the function call.
+
+        Returns:
+            A string containing the class name and key attributes.
+        """
+        return (
+            f"FunctionCalling(function={self.func_tool.function}, "
+            f"arguments={self.arguments})"
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert instance to dictionary.
+
+        Returns:
+            dict[str, Any]: Dictionary representation of the instance.
+        """
+        dict_ = super().to_dict()
+        dict_["function"] = self.function
+        dict_["arguments"] = self.arguments
+        return dict_

lionagi/operatives/action/manager.py

@@ -0,0 +1,236 @@
+# Copyright (c) 2023 - 2024, HaiyangLi <quantocean.li at gmail dot com>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import Any
+
+from lionagi.protocols._concepts import Manager
+from lionagi.protocols.generic.event import EventStatus, Execution
+from lionagi.protocols.generic.log import Log
+from lionagi.protocols.messages.action_request import ActionRequest
+from lionagi.utils import to_list
+
+from .function_calling import FunctionCalling
+from .request_response_model import ActionRequestModel
+from .tool import FuncTool, FuncToolRef, Tool, ToolRef
+
+__all__ = ("ActionManager",)
+
+
+class ActionManager(Manager):
+
+    def __init__(self, *args: FuncTool, **kwargs) -> None:
+
+        super().__init__()
+        self.registry: dict[str, Tool] = {}
+
+        tools = []
+        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)
+            )
+        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.
+
+        Returns:
+            bool: True if tool is registered, False otherwise.
+        """
+        if isinstance(tool, Tool):
+            return tool.function in self.registry
+        elif isinstance(tool, str):
+            return tool in self.registry
+        elif callable(tool):
+            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.
+
+        Args:
+            tool: The tool to register (Tool object or callable).
+            update: If True, update existing tool; if False, raise error.
+
+        Raises:
+            ValueError: If tool already registered and update=False.
+            TypeError: If tool is not a Tool object or callable.
+        """
+        if not update and tool in self:
+            name = None
+            if isinstance(tool, Tool):
+                name = tool.function
+            elif callable(tool):
+                name = tool.__name__
+            raise ValueError(f"Tool {name} is already registered.")
+
+        if callable(tool):
+            tool = Tool(func_callable=tool)
+        if not isinstance(tool, Tool):
+            raise TypeError("Please register a Tool object or callable.")
+
+        self.registry[tool.function] = tool
+
+    def register_tools(
+        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.
+
+        Args:
+            tools: Single tool or list of tools to register.
+            update: If True, update existing tools; if False, raise error.
+
+        Raises:
+            ValueError: If any tool is already registered.
+            TypeError: If any tool is not a Tool object 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)
+        ]
+
+    def match_tool(
+        self, action_request: ActionRequest | ActionRequestModel
+    ) -> FunctionCalling:
+        if not isinstance(action_request, ActionRequest | ActionRequestModel):
+            raise TypeError(f"Unsupported type {type(action_request)}")
+
+        tool = self.registry.get(action_request.function, None)
+        if not isinstance(tool, Tool):
+            raise ValueError(
+                f"Function {action_request.function} is not registered."
+            )
+        return FunctionCalling(
+            func_tool=tool, arguments=action_request.arguments
+        )
+
+    async def invoke(
+        self, func_call: ActionRequestModel | ActionRequest
+    ) -> FunctionCalling | Execution | None:
+        """Invoke a tool based on the provided 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
+
+        Args:
+            func_call: Function call specification in supported format.
+            log_manager: Optional logger for execution tracking.
+
+        Returns:
+            Result of tool invocation after processing pipeline.
+
+        Raises:
+            ValueError: If function not registered or call format invalid.
+        """
+        try:
+            function_calling = self.match_tool(func_call)
+        except ValueError as e:
+            return Log(
+                content={
+                    "event_type": "function_call",
+                    "status": EventStatus.FAILED,
+                    "error": str(e),
+                }
+            )
+        await function_calling.invoke()
+        return function_calling
+
+    @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 [tool.tool_schema for tool in self.registry.values()]
+
+    def get_tool_schema(
+        self,
+        tools: ToolRef = False,
+        auto_register: bool = True,
+        update: bool = False,
+    ) -> dict:
+        """Retrieve the schema for specific tools or all tools.
+
+        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.
+
+        Returns:
+            Dictionary containing tool schemas and additional kwargs.
+
+        Raises:
+            ValueError: If a specified tool is not registered.
+            TypeError: If an unsupported tool type is provided.
+        """
+        if isinstance(tools, list | tuple) and len(tools) == 1:
+            tools = tools[0]
+        if isinstance(tools, bool):
+            if tools is True:
+                return {"tools": self.schema_list}
+            return []
+        else:
+            schemas = self._get_tool_schema(
+                tools, auto_register=auto_register, update=update
+            )
+            return {"tools": schemas}
+
+    def _get_tool_schema(
+        self,
+        tool: Any,
+        auto_register: bool = True,
+        update: bool = False,
+    ) -> dict[str, Any] | list[dict[str, Any]]:
+        if isinstance(tool, dict):
+            return tool
+        if callable(tool):
+            name = tool.__name__
+            if name not in self.registry:
+                if auto_register:
+                    self.register_tool(tool, update=update)
+                else:
+                    raise ValueError(f"Tool {name} is not registered.")
+            return self.registry[name].tool_schema
+
+        elif isinstance(tool, Tool) or isinstance(tool, str):
+            name = tool.function if isinstance(tool, Tool) else tool
+            if name in self.registry:
+                return self.registry[name].tool_schema
+            raise ValueError(f"Tool {name} is not registered.")
+        elif isinstance(tool, list):
+            return [
+                self._get_tool_schema(t, auto_register=auto_register)
+                for t in tool
+            ]
+        raise TypeError(f"Unsupported type {type(tool)}")
+
+
+__all__ = ["ActionManager"]

lionagi/operatives/action/request_response_model.py

@@ -0,0 +1,90 @@
+# Copyright (c) 2023 - 2024, HaiyangLi <quantocean.li at gmail dot com>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import Any
+
+from pydantic import Field, field_validator
+
+from lionagi.libs.validate.common_field_validators import (
+    validate_nullable_string_field,
+)
+from lionagi.utils import HashableModel, to_dict
+
+from ..models.field_model import FieldModel
+from .utils import (
+    action_requests_field_description,
+    arguments_field_description,
+    function_field_description,
+    parse_action_request,
+)
+
+__all__ = (
+    "ActionRequestModel",
+    "ACTION_REQUESTS_FIELD",
+    "ActionResponseModel",
+    "ACTION_RESPONSES_FIELD",
+)
+
+
+class ActionRequestModel(HashableModel):
+
+    function: str | None = Field(
+        None,
+        title="Function",
+        description=function_field_description,
+        examples=["multiply", "create_user"],
+    )
+    arguments: dict[str, Any] | None = Field(
+        None,
+        title="Arguments",
+        description=arguments_field_description,
+    )
+
+    @field_validator("arguments", mode="before")
+    def validate_arguments(cls, value: Any) -> dict[str, Any]:
+        return to_dict(
+            value,
+            fuzzy_parse=True,
+            recursive=True,
+            recursive_python_only=False,
+        )
+
+    @field_validator("function", mode="before")
+    def validate_function(cls, value: str) -> str:
+        return validate_nullable_string_field(cls, value, "function", False)
+
+    @classmethod
+    def create(cls, content: str):
+        try:
+            content = parse_action_request(content)
+            if content:
+                return [cls.model_validate(i) for i in content]
+            return []
+        except Exception:
+            return []
+
+
+ACTION_REQUESTS_FIELD = FieldModel(
+    name="action_requests",
+    annotation=list[ActionRequestModel],
+    default_factory=list,
+    title="Actions",
+    description=action_requests_field_description,
+)
+
+
+class ActionResponseModel(HashableModel):
+
+    function: str = Field(default_factory=str, title="Function")
+    arguments: dict[str, Any] = Field(default_factory=dict)
+    output: Any = None
+
+
+ACTION_RESPONSES_FIELD = FieldModel(
+    name="action_responses",
+    annotation=list[ActionResponseModel],
+    default_factory=list,
+    title="Actions",
+    description="**do not fill**",
+)

lionagi/operatives/action/tool.py

@@ -0,0 +1,141 @@
+# Copyright (c) 2023 - 2024, HaiyangLi <quantocean.li at gmail dot com>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import inspect
+from collections.abc import Callable
+from typing import Any, Self, TypeAlias
+
+from pydantic import Field, field_validator, model_validator
+
+from lionagi.libs.schema.function_to_schema import function_to_schema
+from lionagi.libs.validate.common_field_validators import validate_callable
+from lionagi.protocols.generic.element import Element
+
+__all__ = (
+    "Tool",
+    "func_to_tool",
+    "FuncTool",
+    "FuncToolRef",
+    "ToolRef",
+)
+
+
+class Tool(Element):
+    """A class for handling function calls with schema validation and processing.
+
+    This class wraps callable objects with optional pre and post processing,
+    schema validation, and provides utility methods for function inspection.
+    """
+
+    func_callable: Callable[..., Any] = Field(
+        ...,  # ... indicates required field
+        description="The callable function to be wrapped by the tool",
+        exclude=True,
+    )
+
+    tool_schema: dict[str, Any] | None = Field(
+        default=None,
+        description="Schema describing the function's parameters and structure",
+    )
+
+    preprocessor: Callable[[Any], Any] | None = Field(
+        default=None,
+        description="Optional function for preprocessing inputs before execution",
+        exclude=True,
+    )
+
+    preprocessor_kwargs: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Keyword arguments passed to the preprocessor function",
+        exclude=True,
+    )
+
+    postprocessor: Callable[[Any], Any] | None = Field(
+        default=None,
+        description="Optional function for postprocessing outputs after execution",
+        exclude=True,
+    )
+
+    postprocessor_kwargs: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Keyword arguments passed to the postprocessor function",
+        exclude=True,
+    )
+
+    strict_func_call: bool = Field(
+        default=False,
+        description="Whether to enforce strict validation of function parameters",
+    )
+
+    @field_validator("func_callable", mode="before")
+    def _validate_func_callable(cls, value: Any) -> Callable[..., Any]:
+        return validate_callable(
+            cls, value, undefind_able=False, check_name=True
+        )
+
+    @model_validator(mode="after")
+    def _validate_tool_schema(self) -> Self:
+        if self.tool_schema is None:
+            self.tool_schema = function_to_schema(self.func_callable)
+        return self
+
+    @property
+    def function(self) -> str:
+        """Get the name of the function from the schema.
+
+        Returns:
+            str: The name of the function as defined in the schema.
+        """
+        return self.tool_schema["function"]["name"]
+
+    @property
+    def required_fields(self) -> set[str]:
+        """Get the required fields from the schema.
+
+        Returns:
+            set[str]: Set of required field names.
+        """
+        return set(self.tool_schema["function"]["parameters"]["required"])
+
+    @property
+    def minimum_acceptable_fields(self) -> set[str]:
+        """Get the minimum required fields from function signature.
+
+        Returns:
+            set[str]: Set of minimum required field names.
+        """
+        try:
+            a = {
+                k
+                for k, v in inspect.signature(
+                    self.func_callable
+                ).parameters.items()
+                if v.default == inspect.Parameter.empty
+            }
+            if "kwargs" in a:
+                a.remove("kwargs")
+            if "args" in a:
+                a.remove("args")
+            return a
+        except Exception:
+            return set()
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]):
+        raise NotImplementedError("Tool.from_dict is not implemented.")
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert Tool instance to dictionary.
+
+        Returns:
+            dict[str, Any]: Dictionary representation of the Tool.
+        """
+        dict_ = super().to_dict()
+        dict_["function"] = self.function
+        return dict_
+
+
+FuncTool: TypeAlias = Tool | Callable[..., Any]
+FuncToolRef: TypeAlias = FuncTool | str
+ToolRef: TypeAlias = FuncToolRef | list[FuncToolRef] | bool