lionagi 0.0.115__py3-none-any.whl → 0.0.204__py3-none-any.whl

lionagi/tools/tool_manager.py

@@ -0,0 +1,186 @@
+import json
+import asyncio
+from typing import Dict, Union, List, Tuple, Any
+from lionagi.utils import lcall
+from lionagi.schema import BaseNode, Tool
+
+
+class ToolManager(BaseNode):
+    """
+    A manager class to handle registration and invocation of tools that are subclasses of Tool.
+    
+    Attributes:
+        registry (Dict[str, Tool]): A dictionary to hold registered tools, using their names as keys.
+    """
+    registry: Dict = {}
+
+    def name_existed(self, name: str) -> bool:
+        """
+        Check if a tool name already exists in the registry.
+
+        Parameters:
+            name (str): The name of the tool to check.
+
+        Returns:
+            bool: True if the name exists, False otherwise.
+
+        Examples:
+            >>> tool_manager.name_existed('existing_tool')
+            True
+            >>> tool_manager.name_existed('nonexistent_tool')
+            False
+        """
+        return True if name in self.registry.keys() else False
+            
+    def _register_tool(self, tool: Tool) -> None:
+        """
+        Register a new tool in the registry if it's an instance of Tool.
+
+        Parameters:
+            tool (Tool): The tool instance to register.
+
+        Raises:
+            TypeError: If the provided tool is not an instance of Tool.
+
+        Examples:
+            >>> tool_manager._register_tool(Tool())
+            # Tool is registered without any output
+        """
+        if not isinstance(tool, Tool):
+            raise TypeError('Please register a Tool object.')
+        name = tool.schema_['function']['name']
+        self.registry.update({name: tool})
+                
+    async def invoke(self, func_call: Tuple[str, Dict[str, Any]]) -> Any:
+        """
+        Invoke a registered tool's function with the provided arguments.
+
+        Args:
+            func_call (Tuple[str, Dict[str, Any]]): A tuple containing the tool's function name and kwargs.
+
+        Returns:
+            Any: The result of the tool's function invocation.
+
+        Raises:
+            ValueError: If the function is not registered or an error occurs during invocation.
+
+        Examples:
+            >>> await tool_manager.invoke(('registered_function', {'arg1': 'value1'}))
+            # Result of the registered_function with given arguments
+        """
+        name, kwargs = func_call
+        if self.name_existed(name):
+            tool = self.registry[name]
+            func = tool.func
+            parser = tool.parser
+            try:
+                if asyncio.iscoroutinefunction(func):
+                    return await parser(func(**kwargs)) if parser else func(**kwargs)
+                else:
+                    return parser(func(**kwargs)) if parser else func(**kwargs)
+            except Exception as e:
+                raise ValueError(f"Error when invoking function {name} with arguments {kwargs} with error message {e}")
+        else: 
+            raise ValueError(f"Function {name} is not registered.")
+    
+    @staticmethod
+    def get_function_call(response: Dict) -> Tuple[str, Dict]:
+        """
+        Extract function name and arguments from a response JSON.
+
+        Parameters:
+            response (Dict): The JSON response containing function information.
+
+        Returns:
+            Tuple[str, Dict]: The function name and its arguments.
+
+        Raises:
+            ValueError: If the response is not a valid function call.
+
+        Examples:
+            >>> ToolManager.get_function_call({"action": "execute_add", "arguments": '{"x":1, "y":2}'})
+            ('add', {'x': 1, 'y': 2})
+        """
+        try:
+            func = response['action'][7:]
+            args = json.loads(response['arguments'])
+            return (func, args)
+        except:
+            try:
+                func = response['recipient_name'].split('.')[-1]
+                args = response['parameters']
+                return (func, args)
+            except:
+                raise ValueError('response is not a valid function call')
+    
+    def register_tools(self, tools: List[Tool]) -> None:
+        """
+        Register multiple tools using a given list.
+
+        Parameters:
+            tools (List[Tool]): A list of Tool instances to register.
+
+        Examples:
+            >>> tool_manager.register_tools([Tool(), Tool()])
+            # Multiple Tool instances registered
+        """
+        lcall(tools, self._register_tool) #, update=update, new=new, prefix=prefix, postfix=postfix)
+
+    def to_tool_schema_list(self) -> List[Dict[str, Any]]:
+        """
+        Convert the registry of tools to a list of their schemas.
+
+        Returns:
+            List[Dict[str, Any]]: A list of tool schemas.
+
+        Examples:
+            >>> tool_manager.to_tool_schema_list()
+            # Returns a list of registered tool schemas
+        """
+        schema_list = []
+        for tool in self.registry.values():
+            schema_list.append(tool.schema_)
+        return schema_list
+
+    def _tool_parser(self, tools: Union[Dict, Tool, List[Tool], str, List[str], List[Dict]], **kwargs) -> Dict:
+        """
+        Parse tools and additional keyword arguments to form a dictionary used for tool configuration.
+
+        Parameters:
+            tools: A single tool object, a list of tool objects, a tool name, a list of tool names, or a dictionary.
+            **kwargs: Additional keyword arguments.
+
+        Returns:
+            Dict: A dictionary of tools and additional keyword arguments.
+
+        Raises:
+            ValueError: If a tool name string does not correspond to a registered tool.
+
+        Examples:
+            >>> tool_manager._tool_parser('registered_tool')
+            # Returns a dictionary containing the schema of the registered tool
+        """
+        def tool_check(tool):
+            if isinstance(tool, dict):
+                return tool
+            elif isinstance(tool, Tool):
+                return tool.schema_
+            elif isinstance(tool, str):
+                if self.name_existed(tool):
+                    tool = self.registry[tool]
+                    return tool.schema_
+                else:
+                    raise ValueError(f'Function {tool} is not registered.')
+
+        if isinstance(tools, bool):
+            tool_kwarg = {"tools": self.to_tool_schema_list()}
+            kwargs = {**tool_kwarg, **kwargs}
+
+        else:
+            if not isinstance(tools, list):
+                tools = [tools]
+            tool_kwarg = {"tools": lcall(tools, tool_check)}
+            kwargs = {**tool_kwarg, **kwargs}
+            
+        return kwargs
+    

lionagi/tools/tool_util.py

@@ -1,7 +1,270 @@
-# use schema and convert_util
-from ..utils.convert_util import func_to_schema
+import inspect
 from ..schema.base_tool import Tool
 
+def _extract_docstring_details_google(func):
+    """
+    Extracts the function description and parameter descriptions from the
+    docstring following the Google style format.
+
+    Args:
+        func (Callable): The function from which to extract docstring details.
+
+    Returns:
+        Tuple[str, Dict[str, str]]: A tuple containing the function description
+        and a dictionary with parameter names as keys and their descriptions as values.
+
+    Examples:
+        >>> def example_function(param1: int, param2: str):
+        ...     '''Example function.
+        ...
+        ...     Args:
+        ...         param1 (int): The first parameter.
+        ...         param2 (str): The second parameter.
+        ...     '''
+        ...     pass
+        >>> description, params = _extract_docstring_details_google(example_function)
+        >>> description
+        'Example function.'
+        >>> params == {'param1': 'The first parameter.', 'param2': 'The second parameter.'}
+        True
+    """
+    docstring = inspect.getdoc(func)
+    if not docstring:
+        return "No description available.", {}
+    lines = docstring.split('\n')
+    func_description = lines[0].strip()
+
+    param_start_pos = 0
+    lines_len = len(lines)
+
+    params_description = {}
+    for i in range(1, lines_len):
+        if lines[i].startswith('Args') or lines[i].startswith('Arguments') or lines[i].startswith('Parameters'):
+            param_start_pos = i + 1
+            break
+
+    current_param = None
+    for i in range(param_start_pos, lines_len):
+        if lines[i] == '':
+            continue
+        elif lines[i].startswith(' '):
+            param_desc = lines[i].split(':', 1)
+            if len(param_desc) == 1:
+                params_description[current_param] += ' ' + param_desc[0].strip()
+                continue
+            param, desc = param_desc
+            param = param.split('(')[0].strip()
+            params_description[param] = desc.strip()
+            current_param = param
+        else:
+            break
+    return func_description, params_description
+
+def _extract_docstring_details_rest(func):
+    """
+    Extracts the function description and parameter descriptions from the
+    docstring following the reStructuredText (reST) style format.
+
+    Args:
+        func (Callable): The function from which to extract docstring details.
+
+    Returns:
+        Tuple[str, Dict[str, str]]: A tuple containing the function description
+        and a dictionary with parameter names as keys and their descriptions as values.
+
+    Examples:
+        >>> def example_function(param1: int, param2: str):
+        ...     '''Example function.
+        ...
+        ...     :param param1: The first parameter.
+        ...     :type param1: int
+        ...     :param param2: The second parameter.
+        ...     :type param2: str
+        ...     '''
+        ...     pass
+        >>> description, params = _extract_docstring_details_rest(example_function)
+        >>> description
+        'Example function.'
+        >>> params == {'param1': 'The first parameter.', 'param2': 'The second parameter.'}
+        True
+    """
+    docstring = inspect.getdoc(func)
+    if not docstring:
+        return "No description available.", {}
+    lines = docstring.split('\n')
+    func_description = lines[0].strip()
+
+    params_description = {}
+    current_param = None
+    for line in lines[1:]:
+        line = line.strip()
+        if line.startswith(':param'):
+            param_desc = line.split(':', 2)
+            _, param, desc = param_desc
+            param = param.split()[-1].strip()
+            params_description[param] = desc.strip()
+            current_param = param
+        elif line.startswith(' '):
+            params_description[current_param] += ' ' + line
+
+    return func_description, params_description
+
+def _extract_docstring_details(func, style='google'):
+    """
+    Extracts the function description and parameter descriptions from the
+    docstring of the given function using either Google style or reStructuredText
+    (reST) style format.
+
+    Args:
+        func (Callable): The function from which to extract docstring details.
+        style (str): The style of docstring to parse ('google' or 'reST').
+
+    Returns:
+        Tuple[str, Dict[str, str]]: A tuple containing the function description
+        and a dictionary with parameter names as keys and their descriptions as values.
+
+    Raises:
+        ValueError: If an unsupported style is provided.
+
+    Examples:
+        >>> def example_function(param1: int, param2: str):
+        ...     '''Example function.
+        ...
+        ...     Args:
+        ...         param1 (int): The first parameter.
+        ...         param2 (str): The second parameter.
+        ...     '''
+        ...     pass
+        >>> description, params = _extract_docstring_details(example_function, style='google')
+        >>> description
+        'Example function.'
+        >>> params == {'param1': 'The first parameter.', 'param2': 'The second parameter.'}
+        True
+    """
+    if style == 'google':
+        func_description, params_description = _extract_docstring_details_google(func)
+    elif style == 'reST':
+        func_description, params_description = _extract_docstring_details_rest(func)
+    else:
+        raise ValueError(f'{style} is not supported. Please choose either "google" or "reST".')
+    return func_description, params_description
+
+def _python_to_json_type(py_type):
+    """
+    Converts a Python type to its JSON type equivalent.
+
+    Args:
+        py_type (str): The name of the Python type.
+
+    Returns:
+        str: The corresponding JSON type.
+
+    Examples:
+        >>> _python_to_json_type('str')
+        'string'
+        >>> _python_to_json_type('int')
+        'number'
+    """
+    type_mapping = {
+        'str': 'string',
+        'int': 'number',
+        'float': 'number',
+        'list': 'array',
+        'tuple': 'array',
+        'bool': 'boolean',
+        'dict': 'object'
+    }
+    return type_mapping.get(py_type, 'object')
+
+def _func_to_schema(func, style='google'):
+    """
+    Generates a schema description for a given function, using typing hints and
+    docstrings. The schema includes the function's name, description, and parameters.
+
+    Args:
+        func (Callable): The function to generate a schema for.
+        style (str): The docstring format ('google' or 'reST').
+
+    Returns:
+        Dict[str, Any]: A schema describing the function.
+
+    Examples:
+        >>> def example_function(param1: int, param2: str) -> bool:
+        ...     '''Example function.
+        ...
+        ...     Args:
+        ...         param1 (int): The first parameter.
+        ...         param2 (str): The second parameter.
+        ...     '''
+        ...     return True
+        >>> schema = _func_to_schema(example_function)
+        >>> schema['function']['name']
+        'example_function'
+    """
+    # Extracting function name and docstring details
+    func_name = func.__name__
+    func_description, params_description = _extract_docstring_details(func, style)
+
+    # Extracting parameters with typing hints
+    sig = inspect.signature(func)
+    parameters = {
+        "type": "object",
+        "properties": {},
+        "required": [],
+    }
+
+    for name, param in sig.parameters.items():
+        # Default type to string and update if type hint is available
+        param_type = "string"
+        if param.annotation is not inspect.Parameter.empty:
+            param_type = _python_to_json_type(param.annotation.__name__)
+
+        # Extract parameter description from docstring, if available
+        param_description = params_description.get(name, "No description available.")
+
+        # Assuming all parameters are required for simplicity
+        parameters["required"].append(name)
+        parameters["properties"][name] = {
+            "type": param_type,
+            "description": param_description,
+        }
+
+    # Constructing the schema
+    schema = {
+        "type": "function",
+        "function": {
+            "name": func_name,
+            "description": func_description,
+            "parameters": parameters,
+        }
+    }
+    return schema
+
 def func_to_tool(func_, parser=None, docstring_style='google'):
-    schema = func_to_schema(func_, docstring_style)
+    """
+    Wraps a function into a Tool object, using the provided docstring style to parse
+    the function's docstring and generate a schema.
+
+    Args:
+        func_ (Callable): The function to wrap into a Tool object.
+        parser (Any): The parser associated with the Tool (not used).
+        docstring_style (str): The docstring format ('google' or 'reST').
+
+    Returns:
+        Tool: A Tool object containing the wrapped function and its schema.
+
+    Examples:
+        >>> def example_function(param1: int, param2: str) -> bool:
+        ...     '''Example function.
+        ...
+        ...     Args:
+        ...         param1 (int): The first parameter.
+        ...         param2 (str): The second parameter.
+        ...     '''
+        ...     return True
+        >>> tool = func_to_tool(example_function)
+        >>> isinstance(tool, Tool)
+        True
+    """
+    schema = _func_to_schema(func_, docstring_style)
     return Tool(func=func_, parser=parser, schema_=schema)

lionagi/utils/__init__.py

@@ -1,69 +1,29 @@
 from .sys_util import (
-    create_copy, create_id, create_path, create_hash, 
-    change_dict_key, get_timestamp, get_bins, timestamp_to_datetime, 
-    is_schema, split_path
-)
+    get_timestamp, create_copy, create_path, split_path, 
+    get_bins, change_dict_key, str_to_num, create_id, 
+    as_dict)
 
-from .flat_util import (
-    flatten_dict, flatten_list, change_separator, 
-    unflatten_dict, is_flattenable, dynamic_flatten, 
-    unflatten_to_list, flatten_iterable, flatten_iterable_to_list, 
-    to_list
-)
+from .nested_util import (
+    to_readable_dict, nfilter, nset, nget, 
+    nmerge, ninsert, flatten, unflatten, 
+    is_structure_homogeneous, get_flattened_keys)
 
-from .api_util import (
-    api_method, api_endpoint_from_url, api_error, 
-    api_rate_limit_error
-)
-from .encrypt_util import generate_encryption_key, encrypt, decrypt
-from .convert_util import str_to_num, dict_to_xml, xml_to_dict
+from .api_util import APIUtil
+from .encrypt_util import EncrytionUtil
+from .io_util import IOUtil
 
-from .io_util import to_temp, to_csv, append_to_jsonl
 from .call_util import (
-    hcall, ahcall, lcall, alcall, 
-    mcall, amcall, ecall, aecall
-)
+    to_list,
+    lcall, alcall, mcall, tcall, bcall, 
+    rcall, CallDecorator)
 
 
 __all__ = [
-    'api_method', 
-    'api_endpoint_from_url', 
-    'api_error', 
-    'api_rate_limit_error', 
-    'flatten_dict', 
-    'flatten_list', 
-    'change_separator', 
-    'unflatten_dict', 
-    'is_flattenable', 
-    'dynamic_flatten', 
-    'unflatten_to_list', 
-    'flatten_iterable', 
-    'flatten_iterable_to_list', 
-    'create_copy', 
-    'create_id', 
-    'create_path', 
-    'create_hash', 
-    'change_dict_key', 
-    'get_timestamp', 
-    'get_bins', 
-    'timestamp_to_datetime', 
-    'is_schema', 
-    'split_path', 
-    'generate_encryption_key', 
-    'encrypt', 'decrypt', 
-    'str_to_num', 
-    'to_list', 
-    'dict_to_xml', 
-    'xml_to_dict', 
-    'to_temp', 
-    'to_csv', 
-    'append_to_jsonl', 
-    'hcall', 
-    'ahcall', 
-    'lcall', 
-    'alcall', 
-    'mcall', 
-    'amcall', 
-    'ecall', 
-    'aecall'
-]
+    'get_timestamp', 'create_copy', 'create_path', 'split_path',
+    'get_bins', 'change_dict_key', 'str_to_num', 'create_id',
+    'as_dict', 'to_list', 'to_readable_dict', 'nfilter', 'nset',
+    'nget', 'nmerge', 'ninsert', 'flatten', 'unflatten',
+    'is_structure_homogeneous', 'get_flattened_keys', 'APIUtil',
+    'EncrytionUtil', 'IOUtil', 'lcall', 'alcall', 'mcall', 'tcall',
+    'bcall', 'rcall', 'CallDecorator'
+]