ag2 0.9.1a1__py3-none-any.whl → 0.9.2__py3-none-any.whl

autogen/tools/function_utils.py

@@ -0,0 +1,411 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+# Portions derived from  https://github.com/microsoft/autogen are under the MIT License.
+# SPDX-License-Identifier: MIT
+import functools
+import inspect
+import json
+from logging import getLogger
+from typing import Annotated, Any, Callable, ForwardRef, Optional, TypeVar, Union
+
+from packaging.version import parse
+from pydantic import BaseModel, Field, TypeAdapter
+from pydantic import __version__ as pydantic_version
+from pydantic.json_schema import JsonSchemaValue
+from typing_extensions import Literal, get_args, get_origin
+
+from ..doc_utils import export_module
+from .dependency_injection import Field as AG2Field
+
+if parse(pydantic_version) < parse("2.10.2"):
+    from pydantic._internal._typing_extra import eval_type_lenient as try_eval_type
+else:
+    from pydantic._internal._typing_extra import try_eval_type
+
+
+__all__ = ["get_function_schema", "load_basemodels_if_needed", "serialize_to_str"]
+
+logger = getLogger(__name__)
+
+T = TypeVar("T")
+
+
+def get_typed_annotation(annotation: Any, globalns: dict[str, Any]) -> Any:
+    """Get the type annotation of a parameter.
+
+    Args:
+        annotation: The annotation of the parameter
+        globalns: The global namespace of the function
+
+    Returns:
+        The type annotation of the parameter
+    """
+    if isinstance(annotation, AG2Field):
+        annotation = annotation.description
+    if isinstance(annotation, str):
+        annotation = ForwardRef(annotation)
+        annotation, _ = try_eval_type(annotation, globalns, globalns)
+    return annotation
+
+
+def get_typed_signature(call: Callable[..., Any]) -> inspect.Signature:
+    """Get the signature of a function with type annotations.
+
+    Args:
+        call: The function to get the signature for
+
+    Returns:
+        The signature of the function with type annotations
+    """
+    signature = inspect.signature(call)
+    globalns = getattr(call, "__globals__", {})
+    typed_params = [
+        inspect.Parameter(
+            name=param.name,
+            kind=param.kind,
+            default=param.default,
+            annotation=get_typed_annotation(param.annotation, globalns),
+        )
+        for param in signature.parameters.values()
+    ]
+    typed_signature = inspect.Signature(typed_params)
+    return typed_signature
+
+
+def get_typed_return_annotation(call: Callable[..., Any]) -> Any:
+    """Get the return annotation of a function.
+
+    Args:
+        call: The function to get the return annotation for
+
+    Returns:
+        The return annotation of the function
+    """
+    signature = inspect.signature(call)
+    annotation = signature.return_annotation
+
+    if annotation is inspect.Signature.empty:
+        return None
+
+    globalns = getattr(call, "__globals__", {})
+    return get_typed_annotation(annotation, globalns)
+
+
+def get_param_annotations(typed_signature: inspect.Signature) -> dict[str, Union[Annotated[type[Any], str], type[Any]]]:
+    """Get the type annotations of the parameters of a function
+
+    Args:
+        typed_signature: The signature of the function with type annotations
+
+    Returns:
+        A dictionary of the type annotations of the parameters of the function
+    """
+    return {
+        k: v.annotation for k, v in typed_signature.parameters.items() if v.annotation is not inspect.Signature.empty
+    }
+
+
+class Parameters(BaseModel):
+    """Parameters of a function as defined by the OpenAI API"""
+
+    type: Literal["object"] = "object"
+    properties: dict[str, JsonSchemaValue]
+    required: list[str]
+
+
+class Function(BaseModel):
+    """A function as defined by the OpenAI API"""
+
+    description: Annotated[str, Field(description="Description of the function")]
+    name: Annotated[str, Field(description="Name of the function")]
+    parameters: Annotated[Parameters, Field(description="Parameters of the function")]
+
+
+class ToolFunction(BaseModel):
+    """A function under tool as defined by the OpenAI API."""
+
+    type: Literal["function"] = "function"
+    function: Annotated[Function, Field(description="Function under tool")]
+
+
+def get_parameter_json_schema(k: str, v: Any, default_values: dict[str, Any]) -> JsonSchemaValue:
+    """Get a JSON schema for a parameter as defined by the OpenAI API
+
+    Args:
+        k: The name of the parameter
+        v: The type of the parameter
+        default_values: The default values of the parameters of the function
+
+    Returns:
+        A Pydanitc model for the parameter
+    """
+
+    def type2description(k: str, v: Union[Annotated[type[Any], str], type[Any]]) -> str:
+        if not hasattr(v, "__metadata__"):
+            return k
+
+        # handles Annotated
+        retval = v.__metadata__[0]
+        if isinstance(retval, AG2Field):
+            return retval.description  # type: ignore[return-value]
+        else:
+            raise ValueError(f"Invalid {retval} for parameter {k}, should be a DescriptionField, got {type(retval)}")
+
+    schema = TypeAdapter(v).json_schema()
+    if k in default_values:
+        dv = default_values[k]
+        schema["default"] = dv
+
+    schema["description"] = type2description(k, v)
+
+    return schema
+
+
+def get_required_params(typed_signature: inspect.Signature) -> list[str]:
+    """Get the required parameters of a function
+
+    Args:
+        typed_signature: The signature of the function as returned by inspect.signature
+
+    Returns:
+        A list of the required parameters of the function
+    """
+    return [k for k, v in typed_signature.parameters.items() if v.default == inspect.Signature.empty]
+
+
+def get_default_values(typed_signature: inspect.Signature) -> dict[str, Any]:
+    """Get default values of parameters of a function
+
+    Args:
+        typed_signature: The signature of the function as returned by inspect.signature
+
+    Returns:
+        A dictionary of the default values of the parameters of the function
+    """
+    return {k: v.default for k, v in typed_signature.parameters.items() if v.default != inspect.Signature.empty}
+
+
+def get_parameters(
+    required: list[str],
+    param_annotations: dict[str, Union[Annotated[type[Any], str], type[Any]]],
+    default_values: dict[str, Any],
+) -> Parameters:
+    """Get the parameters of a function as defined by the OpenAI API
+
+    Args:
+        required: The required parameters of the function
+        param_annotations: The type annotations of the parameters of the function
+        default_values: The default values of the parameters of the function
+
+    Returns:
+        A Pydantic model for the parameters of the function
+    """
+    return Parameters(
+        properties={
+            k: get_parameter_json_schema(k, v, default_values)
+            for k, v in param_annotations.items()
+            if v is not inspect.Signature.empty
+        },
+        required=required,
+    )
+
+
+def get_missing_annotations(typed_signature: inspect.Signature, required: list[str]) -> tuple[set[str], set[str]]:
+    """Get the missing annotations of a function
+
+    Ignores the parameters with default values as they are not required to be annotated, but logs a warning.
+
+    Args:
+        typed_signature: The signature of the function with type annotations
+        required: The required parameters of the function
+
+    Returns:
+        A set of the missing annotations of the function
+    """
+    all_missing = {k for k, v in typed_signature.parameters.items() if v.annotation is inspect.Signature.empty}
+    missing = all_missing.intersection(set(required))
+    unannotated_with_default = all_missing.difference(missing)
+    return missing, unannotated_with_default
+
+
+@export_module("autogen.tools")
+def get_function_schema(f: Callable[..., Any], *, name: Optional[str] = None, description: str) -> dict[str, Any]:
+    """Get a JSON schema for a function as defined by the OpenAI API
+
+    Args:
+        f: The function to get the JSON schema for
+        name: The name of the function
+        description: The description of the function
+
+    Returns:
+        A JSON schema for the function
+
+    Raises:
+        TypeError: If the function is not annotated
+
+    Examples:
+    ```python
+    def f(a: Annotated[str, "Parameter a"], b: int = 2, c: Annotated[float, "Parameter c"] = 0.1) -> None:
+        pass
+
+
+    get_function_schema(f, description="function f")
+
+    #   {'type': 'function',
+    #    'function': {'description': 'function f',
+    #        'name': 'f',
+    #        'parameters': {'type': 'object',
+    #           'properties': {'a': {'type': 'str', 'description': 'Parameter a'},
+    #               'b': {'type': 'int', 'description': 'b'},
+    #               'c': {'type': 'float', 'description': 'Parameter c'}},
+    #           'required': ['a']}}}
+    ```
+
+    """
+    typed_signature = get_typed_signature(f)
+    required = get_required_params(typed_signature)
+    default_values = get_default_values(typed_signature)
+    param_annotations = get_param_annotations(typed_signature)
+    return_annotation = get_typed_return_annotation(f)
+    missing, unannotated_with_default = get_missing_annotations(typed_signature, required)
+
+    if return_annotation is None:
+        logger.warning(
+            f"The return type of the function '{f.__name__}' is not annotated. Although annotating it is "
+            + "optional, the function should return either a string, a subclass of 'pydantic.BaseModel'."
+        )
+
+    if unannotated_with_default != set():
+        unannotated_with_default_s = [f"'{k}'" for k in sorted(unannotated_with_default)]
+        logger.warning(
+            f"The following parameters of the function '{f.__name__}' with default values are not annotated: "
+            + f"{', '.join(unannotated_with_default_s)}."
+        )
+
+    if missing != set():
+        missing_s = [f"'{k}'" for k in sorted(missing)]
+        raise TypeError(
+            f"All parameters of the function '{f.__name__}' without default values must be annotated. "
+            + f"The annotations are missing for the following parameters: {', '.join(missing_s)}"
+        )
+
+    fname = name if name else f.__name__
+
+    parameters = get_parameters(required, param_annotations, default_values=default_values)
+
+    function = ToolFunction(
+        function=Function(
+            description=description,
+            name=fname,
+            parameters=parameters,
+        )
+    )
+
+    return function.model_dump()
+
+
+def get_load_param_if_needed_function(t: Any) -> Optional[Callable[[dict[str, Any], type[BaseModel]], BaseModel]]:
+    """Get a function to load a parameter if it is a Pydantic model
+
+    Args:
+        t: The type annotation of the parameter
+
+    Returns:
+        A function to load the parameter if it is a Pydantic model, otherwise None
+
+    """
+    origin = get_origin(t)
+
+    if origin is Annotated:
+        args = get_args(t)
+        if args:
+            return get_load_param_if_needed_function(args[0])
+        else:
+            # Invalid Annotated usage
+            return None
+
+    # Handle generic types (list[str], dict[str,Any], Union[...], etc.) or where t is not a type at all
+    # This means it's not a BaseModel subclass
+    if origin is not None or not isinstance(t, type):
+        return None
+
+    def load_base_model(v: dict[str, Any], model_type: type[BaseModel]) -> BaseModel:
+        return model_type(**v)
+
+    # Check if it's a class and a subclass of BaseModel
+    if issubclass(t, BaseModel):
+        return load_base_model
+    else:
+        return None
+
+
+@export_module("autogen.tools")
+def load_basemodels_if_needed(func: Callable[..., Any]) -> Callable[..., Any]:
+    """A decorator to load the parameters of a function if they are Pydantic models
+
+    Args:
+        func: The function with annotated parameters
+
+    Returns:
+        A function that loads the parameters before calling the original function
+
+    """
+    # get the type annotations of the parameters
+    typed_signature = get_typed_signature(func)
+    param_annotations = get_param_annotations(typed_signature)
+
+    # get functions for loading BaseModels when needed based on the type annotations
+    kwargs_mapping_with_nones = {k: get_load_param_if_needed_function(t) for k, t in param_annotations.items()}
+
+    # remove the None values
+    kwargs_mapping = {k: f for k, f in kwargs_mapping_with_nones.items() if f is not None}
+
+    # a function that loads the parameters before calling the original function
+    @functools.wraps(func)
+    def _load_parameters_if_needed(*args: Any, **kwargs: Any) -> Any:
+        # load the BaseModels if needed
+        for k, f in kwargs_mapping.items():
+            kwargs[k] = f(kwargs[k], param_annotations[k])
+
+        # call the original function
+        return func(*args, **kwargs)
+
+    @functools.wraps(func)
+    async def _a_load_parameters_if_needed(*args: Any, **kwargs: Any) -> Any:
+        # load the BaseModels if needed
+        for k, f in kwargs_mapping.items():
+            kwargs[k] = f(kwargs[k], param_annotations[k])
+
+        # call the original function
+        return await func(*args, **kwargs)
+
+    if inspect.iscoroutinefunction(func):
+        return _a_load_parameters_if_needed
+    else:
+        return _load_parameters_if_needed
+
+
+class _SerializableResult(BaseModel):
+    result: Any
+
+
+@export_module("autogen.tools")
+def serialize_to_str(x: Any) -> str:
+    if isinstance(x, str):
+        return x
+    if isinstance(x, BaseModel):
+        return x.model_dump_json()
+
+    retval_model = _SerializableResult(result=x)
+    try:
+        return str(retval_model.model_dump()["result"])
+    except Exception:
+        pass
+
+    # try json.dumps() and then just return str(x) if that fails too
+    try:
+        return json.dumps(x, ensure_ascii=False)
+    except Exception:
+        return str(x)

autogen/tools/tool.py

@@ -0,0 +1,187 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import inspect
+from typing import TYPE_CHECKING, Any, Callable, Optional, Union
+
+from ..doc_utils import export_module
+from ..tools.function_utils import get_function_schema
+from .dependency_injection import ChatContext, get_context_params, inject_params
+
+if TYPE_CHECKING:
+    from ..agentchat.conversable_agent import ConversableAgent
+
+__all__ = ["Tool", "tool"]
+
+
+@export_module("autogen.tools")
+class Tool:
+    """A class representing a Tool that can be used by an agent for various tasks.
+
+    This class encapsulates a tool with a name, description, and an executable function.
+    The tool can be registered with a ConversableAgent for use either with an LLM or for direct execution.
+
+    Attributes:
+        name (str): The name of the tool.
+        description (str): The description of the tool.
+        func_or_tool (Union[Tool, Callable[..., Any]]): The function or Tool instance to create a Tool from.
+        parameters_json_schema (Optional[ict[str, Any]]): A schema describing the parameters that the function accepts. If None, the schema will be generated from the function signature.
+    """
+
+    def __init__(
+        self,
+        *,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+        func_or_tool: Union["Tool", Callable[..., Any]],
+        parameters_json_schema: Optional[dict[str, Any]] = None,
+    ) -> None:
+        """Create a new Tool object.
+
+        Args:
+            name (str): The name of the tool.
+            description (str): The description of the tool.
+            func_or_tool (Union[Tool, Callable[..., Any]]): The function or Tool instance to create a Tool from.
+            parameters_json_schema (Optional[dict[str, Any]]): A schema describing the parameters that the function accepts. If None, the schema will be generated from the function signature.
+        """
+        if isinstance(func_or_tool, Tool):
+            self._name: str = name or func_or_tool.name
+            self._description: str = description or func_or_tool.description
+            self._func: Callable[..., Any] = func_or_tool.func
+            self._chat_context_param_names: list[str] = func_or_tool._chat_context_param_names
+        elif inspect.isfunction(func_or_tool) or inspect.ismethod(func_or_tool):
+            self._chat_context_param_names = get_context_params(func_or_tool, subclass=ChatContext)
+            self._func = inject_params(func_or_tool)
+            self._name = name or func_or_tool.__name__
+            self._description = description or func_or_tool.__doc__ or ""
+        else:
+            raise ValueError(
+                f"Parameter 'func_or_tool' must be a function, method or a Tool instance, it is '{type(func_or_tool)}' instead."
+            )
+
+        self._func_schema = (
+            {
+                "type": "function",
+                "function": {
+                    "name": name,
+                    "description": description,
+                    "parameters": parameters_json_schema,
+                },
+            }
+            if parameters_json_schema
+            else None
+        )
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def description(self) -> str:
+        return self._description
+
+    @property
+    def func(self) -> Callable[..., Any]:
+        return self._func
+
+    def register_for_llm(self, agent: "ConversableAgent") -> None:
+        """Registers the tool for use with a ConversableAgent's language model (LLM).
+
+        This method registers the tool so that it can be invoked by the agent during
+        interactions with the language model.
+
+        Args:
+            agent (ConversableAgent): The agent to which the tool will be registered.
+        """
+        if self._func_schema:
+            agent.update_tool_signature(self._func_schema, is_remove=False)
+        else:
+            agent.register_for_llm()(self)
+
+    def register_for_execution(self, agent: "ConversableAgent") -> None:
+        """Registers the tool for direct execution by a ConversableAgent.
+
+        This method registers the tool so that it can be executed by the agent,
+        typically outside of the context of an LLM interaction.
+
+        Args:
+            agent (ConversableAgent): The agent to which the tool will be registered.
+        """
+        agent.register_for_execution()(self)
+
+    def register_tool(self, agent: "ConversableAgent") -> None:
+        """Register a tool to be both proposed and executed by an agent.
+
+        Equivalent to calling both `register_for_llm` and `register_for_execution` with the same agent.
+
+        Note: This will not make the agent recommend and execute the call in the one step. If the agent
+        recommends the tool, it will need to be the next agent to speak in order to execute the tool.
+
+        Args:
+            agent (ConversableAgent): The agent to which the tool will be registered.
+        """
+        self.register_for_llm(agent)
+        self.register_for_execution(agent)
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        """Execute the tool by calling its underlying function with the provided arguments.
+
+        Args:
+            *args: Positional arguments to pass to the tool
+            **kwargs: Keyword arguments to pass to the tool
+
+        Returns:
+            The result of executing the tool's function.
+        """
+        return self._func(*args, **kwargs)
+
+    @property
+    def tool_schema(self) -> dict[str, Any]:
+        """Get the schema for the tool.
+
+        This is the preferred way of handling function calls with OpeaAI and compatible frameworks.
+
+        """
+        return get_function_schema(self.func, name=self.name, description=self.description)
+
+    @property
+    def function_schema(self) -> dict[str, Any]:
+        """Get the schema for the function.
+
+        This is the old way of handling function calls with OpenAI and compatible frameworks.
+        It is provided for backward compatibility.
+
+        """
+        schema = get_function_schema(self.func, name=self.name, description=self.description)
+        return schema["function"]  # type: ignore[no-any-return]
+
+    @property
+    def realtime_tool_schema(self) -> dict[str, Any]:
+        """Get the schema for the tool.
+
+        This is the preferred way of handling function calls with OpeaAI and compatible frameworks.
+
+        """
+        schema = get_function_schema(self.func, name=self.name, description=self.description)
+        schema = {"type": schema["type"], **schema["function"]}
+
+        return schema
+
+
+@export_module("autogen.tools")
+def tool(name: Optional[str] = None, description: Optional[str] = None) -> Callable[[Callable[..., Any]], Tool]:
+    """Decorator to create a Tool from a function.
+
+    Args:
+        name (str): The name of the tool.
+        description (str): The description of the tool.
+
+    Returns:
+        Callable[[Callable[..., Any]], Tool]: A decorator that creates a Tool from a function.
+    """
+
+    def decorator(func: Callable[..., Any]) -> Tool:
+        return Tool(name=name, description=description, func_or_tool=func)
+
+    return decorator

autogen/tools/toolkit.py

@@ -0,0 +1,86 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import TYPE_CHECKING
+
+from ..doc_utils import export_module
+from .tool import Tool
+
+if TYPE_CHECKING:
+    from ..agentchat.conversable_agent import ConversableAgent
+
+__all__ = ["Toolkit"]
+
+
+@export_module("autogen.tools")
+class Toolkit:
+    """A class representing a set of tools that can be used by an agent for various tasks."""
+
+    def __init__(self, tools: list[Tool]) -> None:
+        """Create a new Toolkit object.
+
+        Args:
+            tools (list[Tool]): The list of tools in the
+        """
+        self.toolkit = {tool.name: tool for tool in tools}
+
+    @property
+    def tools(self) -> list[Tool]:
+        """Get the list of tools in the set."""
+        return list(self.toolkit.values())
+
+    def register_for_llm(self, agent: "ConversableAgent") -> None:
+        """Register the tools in the set with an LLM agent.
+
+        Args:
+            agent (ConversableAgent): The LLM agent to register the tools with.
+        """
+        for tool in self.toolkit.values():
+            tool.register_for_llm(agent)
+
+    def register_for_execution(self, agent: "ConversableAgent") -> None:
+        """Register the tools in the set with an agent for
+
+        Args:
+            agent (ConversableAgent): The agent to register the tools with.
+        """
+        for tool in self.toolkit.values():
+            tool.register_for_execution(agent)
+
+    def get_tool(self, tool_name: str) -> Tool:
+        """Get a tool from the set by name.
+
+        Args:
+            tool_name (str): The name of the tool to get.
+
+        Returns:
+            Tool: The tool with the given name.
+        """
+        if tool_name in self.toolkit:
+            return self.toolkit[tool_name]
+
+        raise ValueError(f"Tool '{tool_name}' not found in Toolkit.")
+
+    def set_tool(self, tool: Tool) -> None:
+        """Set a tool in the set.
+
+        Args:
+            tool (Tool): The tool to set.
+        """
+        self.toolkit[tool.name] = tool
+
+    def remove_tool(self, tool_name: str) -> None:
+        """Remove a tool from the set by name.
+
+        Args:
+            tool_name (str): The name of the tool to remove.
+        """
+        if tool_name in self.toolkit:
+            del self.toolkit[tool_name]
+        else:
+            raise ValueError(f"Tool '{tool_name}' not found in Toolkit.")
+
+    def __len__(self) -> int:
+        """Get the number of tools in the map."""
+        return len(self.toolkit)