Camel.toolkits.function tool
_remove_a_key
Remove a key from a dictionary recursively.
_remove_title_recursively
Recursively removes the ‘title’ key from all levels of a nested dictionary, except when ‘title’ is an argument name in the schema.
get_openai_function_schema
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.
get_openai_tool_schema
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.
Note:
- Each parameter in
func
must have a type annotation; otherwise, it’s treated as ‘Any’. - Variable arguments (*args) and keyword arguments (**kwargs) are not supported and will be ignored.
- A functional description including a brief and detailed explanation
should be provided in the docstring of
func
. - All parameters of
func
must be described in its docstring. - Supported docstring styles: ReST, Google, Numpydoc, and Epydoc.
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
sanitize_and_enforce_required
Cleans and updates the function schema to conform with OpenAI’s requirements:
- Removes invalid ‘default’ fields from the parameters schema.
- Ensures all fields or function parameters are marked as required.
Parameters:
- parameters_dict (dict): The dictionary representing the function schema.
Returns:
dict: The updated dictionary with invalid defaults removed and all fields set as required.
generate_docstring
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.
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
)
init
call
is_async
validate_openai_tool_schema
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.
get_openai_tool_schema
Returns:
Dict[str, Any]: The OpenAI tool schema for this function.
set_openai_tool_schema
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.
get_openai_function_schema
Returns:
Dict[str, Any]: The schema of the function within the OpenAI tool schema.
set_openai_function_schema
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.
get_function_name
Returns:
str: The name of the function.
set_function_name
Sets the name of the function in the OpenAI tool schema.
Parameters:
- name (str): The name of the function to set.
get_function_description
Returns:
str: The description of the function.
set_function_description
Sets the description of the function in the OpenAI tool schema.
Parameters:
- description (str): The description for the function.
get_paramter_description
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.
set_paramter_description
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.
get_parameter
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.
set_parameter
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.
synthesize_openai_tool_schema
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.
synthesize_execution_output
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.
parameters
Returns:
Dict[str, Any]: the dictionary containing information of parameters of this function.
parameters
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.