3.5 KiB

Raw Blame History Unescape Escape

Tool Decorator Documentation

Module Overview

The tool decorator is designed to enhance functions by automatically generating an OpenAI function schema based on the function's signature and provided metadata. This schema can be outputted in different formats based on the decorator's arguments. The primary use of this decorator is to facilitate the integration of Python functions with external systems that require structured metadata, making it ideal for creating machine-readable descriptions of functions.

Key Features

Automatic Schema Generation: Generates a schema based on the function's signature.
Flexible Output Formats: Supports returning the schema as a dictionary, string, or YAML (if integrated).
Logging Support: Includes logging of function calls and errors, aiding in debugging and monitoring.

Installation and Setup

Before using the tool decorator, ensure that the required libraries are installed and configured. Here’s a basic setup:

$ pip install -U swarms

Decorator Definition

Signature

def tool(name: str = None, description: str = None, return_dict: bool = True, verbose: bool = True, return_string: bool = False, return_yaml: bool = False):

Parameters

Parameter	Type	Default	Description
`name`	str	None	Name of the OpenAI function. Optional.
`description`	str	None	Description of the OpenAI function. Optional.
`return_dict`	bool	True	Whether to return the schema as a dictionary.
`verbose`	bool	True	Enables verbose output.
`return_string`	bool	False	Whether to return the schema as a string.
`return_yaml`	bool	False	Whether to return the schema in YAML format.

Functionality and Usage

Basic Usage

Here is an example of using the tool decorator to enhance a simple function:

@tool(name="ExampleFunction", description="Demonstrates the use of the tool decorator")
def example_function(param1: int, param2: str):
    print(f"Received param1: {param1}, param2: {param2}")

example_function(123, "abc")

Advanced Usage

Returning Schema as String

To get the schema as a string instead of a dictionary:

@tool(name="StringSchemaFunction", description="Returns schema as string", return_dict=False, return_string=True)
def another_function():
    pass

print(another_function())  # Outputs the schema as a string

Handling Exceptions

Demonstrating error handling with the decorator:

@tool(name="ErrorHandlingFunction", description="Handles errors gracefully")
def error_prone_function():
    raise ValueError("An example error")

try:
    error_prone_function()
except Exception as e:
    print(f"Caught an error: {e}")

Additional Information and Tips

Logging: The decorator logs all function calls and exceptions. Make sure to configure the loguru logger accordingly to capture these logs.
Assertion Errors: The decorator performs type checks on the arguments, and if the types do not match, it will raise an assertion error.

References

For more on decorators: Python Decorators Documentation
Loguru library for logging: Loguru Documentation

3.5 KiB Raw Blame History Unescape Escape