tool2schema 2.0.0

A library to generate function schemas for use in the OpenAI API.

tool2schema

Inspired by janekb04/py2gpt and fastai/lm-hackers

Why tool2schema?

Sometimes you can provide a large language model (LLM) with functions for it to call, but it needs to follow a specific schema. tool2schema is a small depedency-free library that converts your functions into that specific schema. So yeah, it's in the name!

Installation

You can install tool2schema using pip.

pip3 install tool2schema

Usage

On all functions that you would like to get the schema for, simply add the EnableTool decorator. Then use the return value of FindToolEnabledSchemas method directly in your requests to whatever LLM you are using.

from tool2schema import EnableTool

@EnableTool
def my_function1(a: int, b: str = "Hello"):
    """
    Example function description.

    :param a: First parameter
    :param b: Second parameter
    """
    # Function code here...

Note: To understand the appropriate format required for tool2schema to generate the appropriate schema, see the 'How it Works' section.

OpenAI

import my_tools  # Module with your functions

from openai import OpenAI
from tool2schema import FindToolEnabledSchemas

client = OpenAI()
completion = client.chat.completions.create(
  model="gpt-4-turbo",
  tools=FindToolEnabledSchemas(my_tools)  # <-- As easy as that!
  messages=[
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello!"}
  ]
)

If finetuning an OpenAI model, then the schema is slightly different.

import my_tools  # Module with your functions

from openai import OpenAI
from tool2schema import FindToolEnabledSchemas, SchemaType

client = OpenAI()
completion = client.chat.completions.create(
  model="gpt-4-turbo",
  tools=FindToolEnabledSchemas(my_tools, SchemaType.OPENAI_TUNE)  # <-- As easy as that!
  messages=[
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello!"}
  ]
)

Anthropic

import my_tools  # Module with your functions

import anthropic
from tool2schema import FindToolEnabledSchemas, SchemaType

client = anthropic.Anthropic()
response = client.beta.tools.messages.create(
    model="claude-3-opus-20240229",
    tools=FindToolEnabledSchemas(my_tools, SchemaType.ANTHROPIC_CLAUDE), # <-- As easy as that!
    messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}],
)

Mistral

Currently the same as OpenAI.

Public API

In this section we describe in more detail how to utilise this library to its fullest extent.

Configuration

There are a number of setting available for you to tweak.

Name	Description	Default Value
ignore_parameters	A list of parameter names to exclude from the schema	[]
ignore_all_parameters	A boolean value indicating whether to exclude all parameters from the schema. When set to true, ignore_parameters and ignore_parameter_descriptions will be ignored.	False
ignore_function_description	A boolean value indicating whether to exclude the function description from the schema.	False
ignore_parameter_descriptions	A boolean value indicating whether to exclude all parameter descriptions from the schema	False
schema_type	Default schema type to use.	SchemaType.OPENAI_API

Decorator Configuration

You can provide the EnableTool decorator with the settings listed above.

For example, to omit parameters b and c:

@GPTEnabled(ignore_parameters=["b", "c"])
def my_function(a: int, b: str, c: float):
    # Function code here...

Global Configuration

It is also possible to specify the settings globally, so that they apply to all functions unless explicitly overridden. It can be done by editing the global configuration as follows:

import tool2schema

# Ignore all parameters named "a" or "b" by default
tool2schema.CONFIG.ignore_parameters = ["a", "b"]

Module Operations

tool2schema has methods available to get functions from a module. See below for example usage of each of the public API methods that tool2schema exposes.

The examples assume the existance of this my_functions module.

from tool2schema import GPTEnabled

@GPTEnabled
def my_function1(a: int, b: str = "Hello"):
    """
    Example function description.

    :param a: First parameter
    :param b: Second parameter
    """
    # Function code here...


@GPTEnabled(tags=["tag1"])
def my_function2(a: int, b: str = "Hello"):
    """
    Example function description.

    :param a: First parameter
    :param b: Second parameter
    """
    # Function code here...

import my_functions
import tool2schema

# Return all functions with the ToolEnable decorator
functions = tool2schema.FindToolEnabled(my_functions)
schemas = tool2schema.FindToolEnabledSchemas(my_functions)

# Return the function with a ToolEnable decorator and the given name
function = tool2schema.FindToolEnabledByName(my_functions, "my_function1")
schema = tool2schema.FindToolEnabledByNameSchema(my_functions, "my_function1")

# Return all functions with a ToolEnable decorator and the given tag
functions = tool2schema.FindToolEnabledByTag(my_functions, "tag1")
schemas = tool2schema.FindToolEnabledByTagSchemas(my_functions, "tag1")

# Save the schemas of all functions with a ToolEnable decorator to a JSON file
json_path = "path/to/json/file"
tool2schema.SaveToolEnabled(my_functions, json_path)

Function Schema

To get the schema (in JSON format) for a function with the EnableTool decorator, either use the methods in the Method Operations section, or call the to_json() method on the function directly.

@GPTEnabled
def my_function(a: int):
    """
    Example function description.

    :param a: First parameter
    """
    # Function code here...

my_function.to_json()  # <-- returns the function schema

Note: that the decorator returns a new ToolEnabled object with additional attributes, but can be called just like the original function.

Function Tags

The EnableTool decorator also supports the tags keyword argument. This allows you to add tags to your function schema.

@GPTEnabled(tags=["tag1", "tag2"])
def my_function(a: int, b: str = "Hello"):
    """
    Example function description.

    :param a: First parameter
    :param b: Second parameter
    """
    # Function code here...

The tags can then be accessed using the tags attribute.

my_function.tags  # ["tag1", "tag2"]

You can check if a function has a certain tag using the has_tag method.

my_function.has_tag("tag1")  # True

How it Works

tool2schema uses certain features of your function definition to correctly populate the schema.

• Parameter type hints
• Parameter default values
• Docstring with parameter descriptions

The docstring must be using the Sphinx docstring format. Note: We use the parameter type hints instead of the docstring for parameter types.

Supported Parameter Types

Most of the common types are supported. See type_schema.py for more details.

Any parameter types not supported will be listed as object in the schema.

Enumerations

Enumeration in the schema are listed as strings of the enumeration names rather than the values. This was a design choice we felt made more sense for use with LLMs. We introduce some additional pre-processing to ensure that the enumeration name strings are mapped back to the correct enum value. Therefore, @EnableTool decorator allows to invoke the function using the name of the enum member rather than an instance of the class. For example, you may invoke my_function(1, MyEnum.YES) as my_function(1, "YES"). See the code for more details.

Enumerations are used to explcitly indicate what values are permitted for the parameter value.

If the enumeration values are not known at the time of defining the function, you can add them later using the add_enum method.

@GPTEnabled
def my_function(a: int, b: str):
    """
    Example function description.

    :param a: First parameter
    :param b: Second parameter
    """
    # Function code here...

my_function.schema.add_enum("b", ["yes", "no"])  #  <-- Add enum values for parameter 'b'