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

lionagi/core/action/function_calling.py

@@ -1,118 +1,153 @@
-from collections.abc import Callable
-from functools import singledispatchmethod
-from typing import Any, Dict
+# Copyright (c) 2023 - 2024, HaiyangLi <quantocean.li at gmail dot com>
+#
+# SPDX-License-Identifier: Apache-2.0
 
-from lionagi.core.collections.abc import Actionable
-from lionagi.core.message.action_request import ActionRequest
-from lionagi.libs import ParseUtil
-from lionagi.libs.ln_func_call import call_handler
+import asyncio
 
+from lionagi.core.typing import Any, Field, PrivateAttr, override
+from lionagi.libs.func.decorators import CallDecorator as cd
+from lionagi.libs.func.types import tcall
+from lionagi.settings import TimedFuncCallConfig
 
-class FunctionCalling(Actionable):
-    """
-    A class for dynamically invoking functions based on various input types,
-    allowing for specification of the function and arguments through multiple
-    formats including tuples, dictionaries, ActionRequests, or JSON strings.
+from .base import EventStatus, ObservableAction
+from .tool import Tool
+
+
+class FunctionCalling(ObservableAction):
+    """Represents an action that calls a function with specified arguments.
+
+    Encapsulates the complete function execution pipeline including:
+    1. Pre-processing of input arguments
+    2. Timed function execution
+    3. Post-processing of results
+    4. Optional result parsing
+    5. Error handling and status tracking
+
+    The execution is performed asynchronously and includes timing information
+    and comprehensive error handling. The execution status, timing, and any
+    errors are tracked and can be accessed after execution.
+
+    Attributes:
+        func_tool (Tool): Tool containing the function to be invoked and its
+            processing pipeline configuration.
+        arguments (dict[str, Any]): Arguments to pass to the function.
+        function (str): Name of the function being called (derived from tool).
+        _content_fields (list): Fields to include in log content section.
     """
 
-    def __init__(self, function: Callable, arguments: dict[str, Any] = None):
-        """
-        Initializes a new instance of FunctionCalling with the given function
-        and optional arguments.
+    func_tool: Tool | None = Field(default=None, exclude=True)
+    _content_fields: list = PrivateAttr(
+        default=["execution_response", "arguments", "function"]
+    )
+    arguments: dict[str, Any] | None = None
+    function: str | None = None
+
+    def __init__(
+        self,
+        func_tool: Tool,
+        arguments: dict[str, Any],
+        timed_config: dict | TimedFuncCallConfig = None,
+        **kwargs: Any,
+    ) -> None:
+        """Initialize a FunctionCalling instance.
 
         Args:
-            function (Callable): The function to be called.
-            arguments (Dict[str, Any]): Arguments to pass to the function.
-                Defaults to an empty dictionary.
+            func_tool: Tool containing the function to invoke and its
+                processing pipeline configuration.
+            arguments: Arguments to pass to the function.
+            timed_config: Configuration for timing and retries.
+                If None, uses default config.
+            **kwargs: Additional keyword arguments for timed config.
         """
-        self.function = function
+        super().__init__(timed_config=timed_config, **kwargs)
+        self.func_tool = func_tool
         self.arguments = arguments or {}
+        self.function = self.func_tool.function_name
 
-    @property
-    def func_name(self) -> str:
-        """
-        Returns the name of the function.
-
-        Returns:
-            str: The function's name.
-        """
-        return self.function.__name__
-
-    @singledispatchmethod
-    @classmethod
-    def create(cls, func_call: Any) -> "FunctionCalling":
-        """
-        Creates an instance of FunctionCalling based on the type of input.
+    @override
+    async def invoke(self) -> Any:
+        """Asynchronously invokes the function with stored arguments.
 
-        Args:
-            func_call (Any): The function call description, which can be a tuple, dict,
-                ActionRequest, or JSON string.
+        Executes the complete function pipeline:
+        1. Pre-processes arguments using tool's pre_processor if defined
+        2. Executes function with timing and retry logic
+        3. Post-processes result using tool's post_processor if defined
+        4. Parses result using tool's parser if defined
+        5. Tracks execution status, timing, and any errors
 
         Returns:
-            FunctionCalling: An instance of FunctionCalling prepared to invoke
-                the specified function.
-
-        Raises:
-            TypeError: If the input type is not supported.
+            The final processed result of the function execution.
+            If execution fails, returns None and sets error information.
+
+        Note:
+            - All processing steps (pre/post/parse) are optional
+            - Timing information is stored in execution_time
+            - Errors are stored in execution_error
+            - Raw response is stored in execution_response
+            - Final status is stored in status
         """
-        raise TypeError(f"Unsupported type {type(func_call)}")
-
-    @create.register(tuple)
-    def _(cls, function_calling: tuple) -> "FunctionCalling":
-        if len(function_calling) == 2:
-            return cls(
-                function=function_calling[0], arguments=function_calling[1]
-            )
-        else:
-            raise ValueError(f"Invalid function call {function_calling}")
-
-    @create.register(dict)
-    def _(cls, function_calling: dict[str, Any]) -> "FunctionCalling":
-        if len(function_calling) == 2 and (
-            {"function", "arguments"} <= function_calling.keys()
-        ):
-            return cls.create(
-                (function_calling["function"], function_calling["arguments"])
+        start = asyncio.get_event_loop().time()
+        try:
+            # Create inner function with pre/post processing
+            @cd.pre_post_process(
+                preprocess=self.func_tool.pre_processor,
+                postprocess=self.func_tool.post_processor,
+                preprocess_kwargs=self.func_tool.pre_processor_kwargs or {},
+                postprocess_kwargs=self.func_tool.post_processor_kwargs or {},
             )
-        raise ValueError(f"Invalid function call {function_calling}")
-
-    @create.register(ActionRequest)
-    def _(cls, function_calling: ActionRequest) -> "FunctionCalling":
-        return cls.create(
-            (function_calling.function, function_calling.arguments)
-        )
+            async def _inner(**kwargs) -> Any:
+                """Inner function that handles the actual execution.
+
+                Applies timing and retry logic through tcall, and handles
+                special case of timing information in result tuple.
+                """
+                config = self._timed_config.to_dict()
+                result = await tcall(
+                    self.func_tool.function, **kwargs, **config
+                )
+                # Handle tuple result from tcall when retry_timing is True
+                if isinstance(result, tuple) and len(result) == 2:
+                    return result[0]  # Return just the result, not timing info
+                return result
+
+            # Execute function with pre/post processing
+            result = await _inner(**self.arguments)
+            self.execution_response = result
+            self.execution_time = asyncio.get_event_loop().time() - start
+            self.status = EventStatus.COMPLETED
+
+            # Apply parser if defined
+            if self.func_tool.parser is not None:
+                if asyncio.iscoroutinefunction(self.func_tool.parser):
+                    result = await self.func_tool.parser(result)
+                else:
+                    result = self.func_tool.parser(result)
+            return result
 
-    @create.register(str)
-    def _(cls, function_calling: str) -> "FunctionCalling":
-        _call = None
-        try:
-            _call = ParseUtil.fuzzy_parse_json(function_calling)
         except Exception as e:
-            raise ValueError(
-                f"Invalid function call {function_calling}"
-            ) from e
+            self.status = EventStatus.FAILED
+            self.execution_error = str(e)
+            self.execution_time = asyncio.get_event_loop().time() - start
+            return None
 
-        if isinstance(_call, dict):
-            return cls.create(_call)
-        raise ValueError(f"Invalid function call {function_calling}")
-
-    async def invoke(self) -> Any:
-        """
-        Asynchronously invokes the stored function with the provided arguments.
+    def __str__(self) -> str:
+        """Returns a string representation of the function call.
 
         Returns:
-            Any: The result of the function call.
+            A string in the format "function_name(arguments)".
         """
-        return await call_handler(self.function, **self.arguments)
+        return f"{self.func_tool.function_name}({self.arguments})"
 
-    def __str__(self) -> str:
-        """
-        Returns a string representation of the function call.
+    def __repr__(self) -> str:
+        """Returns a detailed string representation of the function call.
 
         Returns:
-            str: String representation of the function call.
+            A string containing the class name and key attributes.
         """
-        return f"{self.func_name}({self.arguments})"
+        return (
+            f"FunctionCalling(function={self.func_tool.function_name}, "
+            f"arguments={self.arguments})"
+        )
 
-    def __repr__(self) -> str:
-        return self.__str__()
+
+__all__ = ["FunctionCalling"]

lionagi/core/action/tool.py

@@ -1,102 +1,204 @@
-from collections.abc import Callable
-from typing import Any, Dict, List, Union
+# Copyright (c) 2023 - 2024, HaiyangLi <quantocean.li at gmail dot com>
+#
+# SPDX-License-Identifier: Apache-2.0
 
-from pydantic import Field, field_serializer
+import json
+from datetime import datetime
 
-from lionagi.core.collections.abc import Actionable
-from lionagi.core.generic.node import Node
-from lionagi.libs.ln_func_call import call_handler
+from pydantic import field_serializer, field_validator
 
-from .function_calling import FunctionCalling
+from lionagi.core.generic.types import Element
+from lionagi.core.typing import Any, Callable, Field, Literal, override
+from lionagi.libs.parse import function_to_schema, to_list
 
 
-class Tool(Node, Actionable):
-    """
-    Class representing a Tool with capabilities for pre-processing, post-processing,
-    and parsing function results.
+class Tool(Element):
+    """Represents a callable tool with pre/post-processing capabilities.
+
+    A Tool wraps a function with optional pre-processing, post-processing,
+    and result parsing capabilities. It also maintains a schema describing
+    the function's interface in OpenAI function calling format.
+
+    The processing pipeline consists of:
+    1. Pre-processor: Transforms input arguments before function call
+    2. Function: The actual function being called
+    3. Post-processor: Transforms function result
+    4. Parser: Converts result to JSON serializable format
+
+    Each processing step is optional and can be configured independently.
+    The schema is automatically generated from the function's signature
+    and docstring unless explicitly provided.
 
     Attributes:
-        function (Callable): The callable function or capability of the tool.
-        schema_ (Union[Dict, None]): Schema in OpenAI format.
-        pre_processor (Union[Callable, None]): Function to preprocess input arguments.
-        pre_processor_kwargs (Union[Dict, None]): Keyword arguments for the pre-processor.
-        post_processor (Union[Callable, None]): Function to post-process the result.
-        post_processor_kwargs (Union[Dict, None]): Keyword arguments for the post-processor.
-        parser (Union[Callable, None]): Function to parse the result to a JSON serializable format.
+        function: The callable function of the tool.
+        schema_: Schema of the function in OpenAI format.
+        pre_processor: Optional function to preprocess input arguments.
+        pre_processor_kwargs: Optional kwargs for the pre-processor.
+        post_processor: Optional function to post-process the result.
+        post_processor_kwargs: Optional kwargs for the post-processor.
+        parser: Optional function to parse result to JSON format.
     """
 
-    function: Callable = Field(
+    function: Callable[..., Any] = Field(
         ...,
-        description="The callable function or capability of the tool.",
+        description="The callable function of the tool.",
     )
-
-    schema_: dict | None = Field(
-        None,
-        description="Schema in OpenAI format.",
+    schema_: dict[str, Any] | None = Field(
+        default=None,
+        description="Schema of the function in OpenAI format.",
+    )
+    pre_processor: Callable[[Any], Any] | None = Field(
+        default=None,
+        description="Function to preprocess input arguments.",
+    )
+    pre_processor_kwargs: dict[str, Any] | None = Field(
+        default=None,
+        description="Keyword arguments for the pre-processor.",
+    )
+    post_processor: Callable[[Any], Any] | None = Field(
+        default=None,
+        description="Function to post-process the result.",
+    )
+    post_processor_kwargs: dict[str, Any] | None = Field(
+        default=None,
+        description="Keyword arguments for the post-processor.",
+    )
+    parser: Callable[[Any], Any] | None = Field(
+        default=None,
+        description="Function to parse result to JSON serializable format.",
     )
 
-    pre_processor: Callable | None = None
-    pre_processor_kwargs: dict | None = None
-
-    post_processor: Callable | None = None
-    post_processor_kwargs: dict | None = None
+    @override
+    def __init__(self, **data: Any) -> None:
+        """Initialize a Tool instance.
 
-    parser: Callable | None = None  # Parse result to JSON serializable format
+        If schema_ is not provided, automatically generates it from the
+        function's signature and docstring.
 
-    @field_serializer("function", check_fields=False)
-    def serialize_func(self, func: Callable) -> str:
+        Args:
+            **data: Keyword arguments to initialize the Tool instance.
         """
-        Serialize the function for storage or transmission.
+        super().__init__(**data)
+        if self.schema_ is None:
+            self.schema_ = function_to_schema(self.function)
+
+    @field_validator("function")
+    def _validate_function(cls, v: Any) -> Callable[..., Any]:
+        if not callable(v):
+            raise ValueError("Function must be callable.")
+        if not hasattr(v, "__name__"):
+            raise ValueError("Function must have a name.")
+        return v
+
+    @field_serializer(
+        "function",
+        "pre_processor",
+        "post_processor",
+        "parser",
+        "pre_processor_kwargs",
+        "post_processor_kwargs",
+    )
+    def serialize_field(self, v: Any) -> str | None:
+        """Serialize various fields of the Tool class.
+
+        Handles serialization of callable functions and dictionaries:
+        - Functions are serialized to their names
+        - Dictionaries are serialized to JSON strings
+        - Other values are returned as None
 
         Args:
-            func (Callable): The function to serialize.
+            v: The value to serialize.
 
         Returns:
-            str: The name of the function.
+            str: Serialized representation of the value.
+            None: If value cannot be serialized.
         """
-        return func.__name__
+        if callable(v):
+            return v.__name__
+        elif isinstance(v, dict):
+            return json.dumps(v)
+        return None
 
     @property
-    def name(self) -> str:
-        """
-        Get the name of the function from the schema.
+    def function_name(self) -> str:
+        """Get the name of the function from the schema.
 
         Returns:
-            str: The name of the function.
+            str: The name of the function as defined in the schema.
         """
         return self.schema_["function"]["name"]
 
-    async def invoke(self, kwargs: dict = {}) -> Any:
-        """
-        Invoke the tool's function with optional pre-processing and post-processing.
+    @override
+    def __str__(self) -> str:
+        """Return a string representation of the Tool.
 
-        Args:
-            kwargs (Dict): The arguments to pass to the function.
+        Includes class name, ID, timestamp, and schema for debugging
+        and logging purposes.
 
         Returns:
-            Any: The result of the function call.
+            str: A detailed string representation of the Tool.
         """
-        if self.pre_processor:
-            pre_process_kwargs = self.pre_processor_kwargs or {}
-            kwargs = await call_handler(
-                self.pre_processor(kwargs, **pre_process_kwargs)
-            )
-            if not isinstance(kwargs, dict):
-                raise ValueError("Pre-processor must return a dictionary.")
-
-        func_call_ = FunctionCalling(function=self.function, arguments=kwargs)
-        try:
-            result = await func_call_.invoke()
-        except Exception:
-            return None
-
-        if self.post_processor:
-            post_process_kwargs = self.post_processor_kwargs or {}
-            result = await call_handler(
-                self.post_processor(result, **post_process_kwargs)
-            )
-
-        return result if not self.parser else self.parser(result)
-
-
-TOOL_TYPE = Union[bool, Tool, str, list[Union[Tool, str, dict]], dict]
+        timestamp_str = datetime.fromtimestamp(self.timestamp).isoformat(
+            timespec="minutes"
+        )
+        return (
+            f"{self.class_name()}(ln_id={self.ln_id[:6]}.., "
+            f"timestamp={timestamp_str}), "
+            f"schema_={json.dumps(self.schema_, indent=4)}"
+        )
+
+
+def func_to_tool(
+    func_: Callable[..., Any] | list[Callable[..., Any]],
+    parser: Callable[[Any], Any] | list[Callable[[Any], Any]] | None = None,
+    docstring_style: Literal["google", "rest"] = "google",
+    **kwargs,
+) -> list[Tool]:
+    """Convert functions to Tool objects.
+
+    Helper function to create Tool instances from callable functions.
+    Supports both single functions and lists of functions, with optional
+    result parsers for each function.
+
+    Args:
+        func_: Single function or list of functions to convert.
+        parser: Optional parser(s) for function results. If provided for
+            multiple functions, must match length of func_ list.
+        docstring_style: Style of docstring parsing for schema generation.
+            Supports 'google' or 'rest' format.
+        **kwargs: Additional keyword arguments for Tool constructor.
+
+    Returns:
+        list[Tool]: List of Tool objects created from the functions.
+
+    Raises:
+        ValueError: If number of parsers doesn't match number of functions.
+
+    Example:
+        >>> def my_func(x: int) -> str:
+        ...     '''Convert int to string.'''
+        ...     return str(x)
+        >>> tools = func_to_tool(my_func)
+        >>> assert len(tools) == 1
+        >>> assert isinstance(tools[0], Tool)
+    """
+    funcs = to_list(func_)
+    parsers = to_list(parser)
+
+    if parser and len(funcs) != len(parsers):
+        raise ValueError("Length of parser must match length of func, ")
+
+    tools = []
+    for idx, func in enumerate(funcs):
+        tool = Tool(
+            function=func,
+            schema_=function_to_schema(func, style=docstring_style),
+            parser=parsers[idx] if parser else None,
+            **kwargs,
+        )
+        tools.append(tool)
+
+    return tools
+
+
+__all__ = ["Tool", "func_to_tool"]

lionagi/core/action/types.py

@@ -0,0 +1,16 @@
+# Copyright (c) 2023 - 2024, HaiyangLi <quantocean.li at gmail dot com>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from .action_manager import ActionManager
+from .base import ObservableAction
+from .function_calling import FunctionCalling
+from .tool import Tool, func_to_tool
+
+__all__ = (
+    "ObservableAction",
+    "FunctionCalling",
+    "Tool",
+    "func_to_tool",
+    "ActionManager",
+)

lionagi/core/communication/__init__.py

@@ -0,0 +1,3 @@
+# Copyright (c) 2023 - 2024, HaiyangLi <quantocean.li at gmail dot com>
+#
+# SPDX-License-Identifier: Apache-2.0