🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org
Python agentai-societiesartificial-intelligencecommunicative-aicooperative-aideep-learninglarge-language-modelsmulti-agent-systemsnatural-language-processing
<a id="camel.toolkits.function_tool"></a>
<a id="camel.toolkits.function_tool._annotation_accepts"></a>
## _annotation_accepts
```python
def _annotation_accepts(annotation: Any, value: Any):
```
Quick structural check: could *annotation* plausibly apply to *value*?
Used by the Union handler to skip branches that clearly don't match
before attempting (potentially failing) coercion.
<a id="camel.toolkits.function_tool._coerce_arg"></a>
## _coerce_arg
```python
def _coerce_arg(value: Any, annotation: Any):
```
Coerce *value* so that plain dicts become Pydantic model instances
where the function signature expects them.
Handles `__INLINE_CODE_0____INLINE_CODE_1____INLINE_CODE_2____INLINE_CODE_3____INLINE_CODE_4__`,
`__INLINE_CODE_5____INLINE_CODE_6____INLINE_CODE_7__` annotations recursively.
Non-model annotations are returned unchanged.
<a id="camel.toolkits.function_tool._coerce_arguments"></a>
## _coerce_arguments
```python
def _coerce_arguments(func: Callable, args: tuple, kwargs: Dict[str, Any]):
```
Coerce positional and keyword arguments to match Pydantic model
type annotations in *func*'s signature.
This bridges the gap between the JSON dicts that the LLM produces (via
`__INLINE_CODE_0__`) and the Pydantic models that toolkit authors declare in
their function signatures. Plain values and non-model parameters are
passed through unchanged.
<a id="camel.toolkits.function_tool._remove_a_key"></a>
## _remove_a_key
```python
def _remove_a_key(d: Dict, remove_key: Any):
```
Remove a key from a dictionary recursively.
<a id="camel.toolkits.function_tool._remove_title_recursively"></a>
## _remove_title_recursively
```python
def _remove_title_recursively(data, parent_key = None):
```
Recursively removes the 'title' key from all levels of a nested
dictionary, except when 'title' is an argument name in the schema.
<a id="camel.toolkits.function_tool.get_openai_function_schema"></a>
## get_openai_function_schema
```python
def get_openai_function_schema(func: Callable):
```
Generates a schema dict for an OpenAI function based on its signature.
This function is deprecated and will be replaced by
:obj:`get_openai_tool_schema()` in future versions. It parses the
function's parameters and docstring to construct a JSON schema-like
dictionary.
**Parameters:**
- **func** (Callable): The OpenAI function to generate the schema for.
**Returns:**
Dict[str, Any]: A dictionary representing the JSON schema of the
function, including its name, description, and parameter
specifications.
<a id="camel.toolkits.function_tool.get_openai_tool_schema"></a>
## get_openai_tool_schema
```python
def get_openai_tool_schema(func: Callable):
```
Generates an OpenAI JSON schema from a given Python function.
This function creates a schema compatible with OpenAI's API specifications,
based on the provided Python function. It processes the function's
parameters, types, and docstrings, and constructs a schema accordingly.
**Parameters:**
- **func** (Callable): The Python function to be converted into an OpenAI JSON schema.
**Returns:**
Dict[str, Any]: A dictionary representing the OpenAI JSON schema of
the provided function.
See Also:
[OpenAI API Reference](https://platform.openai.com/docs/api-reference/assistants/object)
<a id="camel.toolkits.function_tool.sanitize_and_enforce_required"></a>
## sanitize_and_enforce_required
```python
def sanitize_and_enforce_required(parameters_dict):
```
Cleans and updates the function schema to conform with OpenAI's
requirements:
- Removes invalid 'default' fields from the parameters schema.
- Ensures all fields are marked as required or have null type for optional
fields.
- Recursively adds additionalProperties: false to all nested objects.
- Disables strict mode when an object intentionally allows additional
properties.
**Parameters:**
- **parameters_dict** (dict): The dictionary representing the function schema.
**Returns:**
dict: The updated dictionary with invalid defaults removed and strict
mode enabled only when every object schema is closed.
<a id="camel.toolkits.function_tool.generate_docstring"></a>
## generate_docstring
```python
def generate_docstring(code: str, model: Optional[BaseModelBackend] = None):
```
Generates a docstring for a given function code using LLM.
This function leverages a language model to generate a
PEP 8/PEP 257-compliant docstring for a provided Python function.
If no model is supplied, a default gpt-4o-mini is used.
**Parameters:**
- **code** (str): The source code of the function.
- **model** (Optional[BaseModelBackend]): An optional language model backend instance. If not provided, a default gpt-4o-mini is used.
**Returns:**
str: The generated docstring.
<a id="camel.toolkits.function_tool.FunctionTool"></a>
## FunctionTool
```python
class FunctionTool:
```
An abstraction of a function that OpenAI chat models can call. See
https://platform.openai.com/docs/api-reference/chat/create.
By default, the tool schema will be parsed from the func, or you can
provide a user-defined tool schema to override.
**Parameters:**
- **func** (Callable): The function to call. The tool schema is parsed from the function signature and docstring by default.
- **openai_tool_schema** (Optional[Dict[str, Any]], optional): A user-defined OpenAI tool schema to override the default result. (default: :obj:`None`)
- **synthesize_schema** (Optional[bool], optional): Whether to enable the use of a schema assistant model to automatically synthesize the schema if validation fails or no valid schema is provided. (default: :obj:`False`)
- **synthesize_schema_model** (Optional[BaseModelBackend], optional): An assistant model (e.g., an LLM model) used to synthesize the schema if `synthesize_schema` is enabled and no valid schema is provided. (default: :obj:`None`)
- **synthesize_schema_max_retries** (int, optional): The maximum number of attempts to retry schema synthesis using the schema assistant model if the previous attempts fail. (default: 2)
- **synthesize_output** (Optional[bool], optional): Flag for enabling synthesis output mode, where output is synthesized based on the function's execution. (default: :obj:`False`)
- **synthesize_output_model** (Optional[BaseModelBackend], optional): Model used for output synthesis in synthesis mode. (default: :obj:`None`)
- **synthesize_output_format** (Optional[Type[BaseModel]], optional): Format for the response when synthesizing output. (default: :obj:`None`)
<a id="camel.toolkits.function_tool.FunctionTool.__init__"></a>
### __init__
```python
def __init__(
self,
func: Callable,
openai_tool_schema: Optional[Dict[str, Any]] = None,
synthesize_schema: Optional[bool] = False,
synthesize_schema_model: Optional[BaseModelBackend] = None,
synthesize_schema_max_retries: int = 2,
synthesize_output: Optional[bool] = False,
synthesize_output_model: Optional[BaseModelBackend] = None,
synthesize_output_format: Optional[Type[BaseModel]] = None
):
```
<a id="camel.toolkits.function_tool.FunctionTool.__call__"></a>
### __call__
```python
def __call__(self, *args: Any, **kwargs: Any):
```
<a id="camel.toolkits.function_tool.FunctionTool._run_async_in_persistent_loop"></a>
### _run_async_in_persistent_loop
```python
def _run_async_in_persistent_loop(coro):
```
Run coroutine in persistent loop to preserve httpx connections.
<a id="camel.toolkits.function_tool.FunctionTool.is_async"></a>
### is_async
```python
def is_async(self):
```
<a id="camel.toolkits.function_tool.FunctionTool.validate_openai_tool_schema"></a>
### validate_openai_tool_schema
```python
def validate_openai_tool_schema(openai_tool_schema: Dict[str, Any]):
```
Validates the OpenAI tool schema against
:obj:`ToolAssistantToolsFunction`.
This function checks if the provided :obj:`openai_tool_schema` adheres
to the specifications required by OpenAI's
:obj:`ToolAssistantToolsFunction`. It ensures that the function
description and parameters are correctly formatted according to JSON
Schema specifications.
**Parameters:**
- **openai_tool_schema** (Dict[str, Any]): The OpenAI tool schema to validate.
<a id="camel.toolkits.function_tool.FunctionTool.get_openai_tool_schema"></a>
### get_openai_tool_schema
```python
def get_openai_tool_schema(self):
```
**Returns:**
Dict[str, Any]: The OpenAI tool schema for this function.
<a id="camel.toolkits.function_tool.FunctionTool.set_openai_tool_schema"></a>
### set_openai_tool_schema
```python
def set_openai_tool_schema(self, schema: Dict[str, Any]):
```
Sets the OpenAI tool schema for this function.
Allows setting a custom OpenAI tool schema for this function.
**Parameters:**
- **schema** (Dict[str, Any]): The OpenAI tool schema to set.
<a id="camel.toolkits.function_tool.FunctionTool.get_openai_function_schema"></a>
### get_openai_function_schema
```python
def get_openai_function_schema(self):
```
**Returns:**
Dict[str, Any]: The schema of the function within the OpenAI tool
schema.
<a id="camel.toolkits.function_tool.FunctionTool.set_openai_function_schema"></a>
### set_openai_function_schema
```python
def set_openai_function_schema(self, openai_function_schema: Dict[str, Any]):
```
Sets the schema of the function within the OpenAI tool schema.
**Parameters:**
- **openai_function_schema** (Dict[str, Any]): The function schema to set within the OpenAI tool schema.
<a id="camel.toolkits.function_tool.FunctionTool.get_function_name"></a>
### get_function_name
```python
def get_function_name(self):
```
**Returns:**
str: The name of the function.
<a id="camel.toolkits.function_tool.FunctionTool.set_function_name"></a>
### set_function_name
```python
def set_function_name(self, name: str):
```
Sets the name of the function in the OpenAI tool schema.
**Parameters:**
- **name** (str): The name of the function to set.
<a id="camel.toolkits.function_tool.FunctionTool.get_function_description"></a>
### get_function_description
```python
def get_function_description(self):
```
**Returns:**
str: The description of the function.
<a id="camel.toolkits.function_tool.FunctionTool.set_function_description"></a>
### set_function_description
```python
def set_function_description(self, description: str):
```
Sets the description of the function in the OpenAI tool schema.
**Parameters:**
- **description** (str): The description for the function.
<a id="camel.toolkits.function_tool.FunctionTool.get_parameter_description"></a>
### get_parameter_description
```python
def get_parameter_description(self, param_name: str):
```
Gets the description of a specific parameter from the function
schema.
**Parameters:**
- **param_name** (str): The name of the parameter to get the description.
**Returns:**
str: The description of the specified parameter.
<a id="camel.toolkits.function_tool.FunctionTool.set_parameter_description"></a>
### set_parameter_description
```python
def set_parameter_description(self, param_name: str, description: str):
```
Sets the description for a specific parameter in the function
schema.
**Parameters:**
- **param_name** (str): The name of the parameter to set the description for.
- **description** (str): The description for the parameter.
<a id="camel.toolkits.function_tool.FunctionTool.get_parameter"></a>
### get_parameter
```python
def get_parameter(self, param_name: str):
```
Gets the schema for a specific parameter from the function schema.
**Parameters:**
- **param_name** (str): The name of the parameter to get the schema.
**Returns:**
Dict[str, Any]: The schema of the specified parameter.
<a id="camel.toolkits.function_tool.FunctionTool.set_parameter"></a>
### set_parameter
```python
def set_parameter(self, param_name: str, value: Dict[str, Any]):
```
Sets the schema for a specific parameter in the function schema.
**Parameters:**
- **param_name** (str): The name of the parameter to set the schema for.
- **value** (Dict[str, Any]): The schema to set for the parameter.
<a id="camel.toolkits.function_tool.FunctionTool.synthesize_openai_tool_schema"></a>
### synthesize_openai_tool_schema
```python
def synthesize_openai_tool_schema(self, max_retries: Optional[int] = None):
```
Synthesizes an OpenAI tool schema for the specified function.
This method uses a language model (LLM) to synthesize the OpenAI tool
schema for the specified function by first generating a docstring and
then creating a schema based on the function's source code. The
schema synthesis and validation process is retried up to
`max_retries` times in case of failure.
**Parameters:**
- **max_retries** (Optional[int], optional): The maximum number of retries for schema synthesis and validation if the process fails. (default: :obj:`None`)
**Returns:**
Dict[str, Any]: The synthesis OpenAI tool schema for the function.
<a id="camel.toolkits.function_tool.FunctionTool.synthesize_execution_output"></a>
### synthesize_execution_output
```python
def synthesize_execution_output(
self,
args: Optional[tuple[Any, ...]] = None,
kwargs: Optional[Dict[str, Any]] = None
):
```
Synthesizes the output of the function based on the provided
positional arguments and keyword arguments.
**Parameters:**
- **args** (Optional[tuple]): Positional arguments to pass to the function during synthesis. (default: :obj:`None`)
- **kwargs** (Optional[Dict[str, Any]]): Keyword arguments to pass to the function during synthesis. (default: :obj:`None`)
**Returns:**
Any: Synthesized output from the function execution. If no
synthesis model is provided, a warning is logged.
<a id="camel.toolkits.function_tool.FunctionTool.parameters"></a>
### parameters
```python
def parameters(self):
```
**Returns:**
Dict[str, Any]: the dictionary containing information of
parameters of this function.
<a id="camel.toolkits.function_tool.FunctionTool.parameters"></a>
### parameters
```python
def parameters(self, value: Dict[str, Any]):
```
Setter method for the property :obj:`parameters`. It will
firstly check if the input parameters schema is valid. If invalid,
the method will raise :obj:`jsonschema.exceptions.SchemaError`.
**Parameters:**
- **value** (Dict[str, Any]): the new dictionary value for the function's parameters.
<a id="camel.toolkits.function_tool.tool"></a>
## tool
```python
def tool(func: Optional[Callable] = None):
```
A decorator that converts a Python function into a FunctionTool
instance.
This decorator can be used with or without parentheses:
- @tool - without parentheses, uses default settings
- @tool() - with parentheses, uses default settings
- @tool(synthesize_output=True) - with custom settings
**Parameters:**
- **func** (Optional[Callable], optional): The function to be decorated. This is automatically passed when using @tool without parentheses. (default: :obj:`None`)
- **openai_tool_schema** (Optional[Dict[str, Any]], optional): A user-defined OpenAI tool schema to override the default result. (default: :obj:`None`)
- **synthesize_schema** (bool, optional): Whether to enable schema synthesis. (default: :obj:`False`)
- **synthesize_schema_model** (Optional[BaseModelBackend], optional): Model to use for schema synthesis. (default: :obj:`None`)
- **synthesize_schema_max_retries** (int, optional): Maximum number of retries for schema synthesis. (default: :obj:`2`)
- **synthesize_output** (bool, optional): Whether to enable output synthesis. (default: :obj:`False`)
- **synthesize_output_model** (Optional[BaseModelBackend], optional): Model to use for output synthesis. (default: :obj:`None`)
- **synthesize_output_format** (Optional[Type[BaseModel]], optional): Format for synthesized output. (default: :obj:`None`)
**Returns:**
Callable[[Callable], FunctionTool]: A decorator function that converts
the decorated function into a FunctionTool instance.