gpt-functions 0.0.8
A Python package that provides a simple interface for producing function data in a structured format for the OpenAI GPT models.
Requires Python: >=3.7

The `gpt-functions` Python package provides a simplified interface for generating function metadata in a structured format for use with OpenAI GPT models. It allows users to create instances of `Function` and `Parameter` classes to define the metadata.

To install the package, you can use the following command:

```shell
pip install gpt-functions
```

Here are two examples demonstrating how to define function metadata using the package.

**Example Usage 1: Manually defining metadata**

In this example, you manually define the metadata for a function called `get_current_weather` using the `Function` and `Parameter` classes:

```python
from gpt_functions.meta import Function, Parameter

# Create instances of your Parameter metadata
location = Parameter(name="location", type="str", description="The city and state, e.g. San Francisco, CA", required=True)
unit = Parameter(name="unit", type="str", enum=["celsius", "fahrenheit"])

# Create an instance of Function metadata for retrieving current weather
func = Function(name="get_current_weather", description="Get the current weather in a given location")

# Add your parameters to the function metadata
func.add_parameter(location)
func.add_parameter(unit)

# Print the resulting dictionary
print(func.to_dict())
```

This code will output a dictionary representing the function metadata.

**Example Usage 2: Automatically defining metadata**

In this example, you define a Python function `get_current_weather` and use the `auto` method of the `Function` class to automatically generate the metadata based on the function's signature and docstring:

```python
from gpt_functions.meta import Function, Parameter

# Define your function
def get_current_weather(location: str, unit: str = "celsius"):
    """
    Get the current weather in a given location

    Args:
        location (str): The city and state, e.g. San Francisco, CA
        unit (str, optional): The unit of the temperature. Defaults to "celsius".

    Returns:
        dict: The current weather.
    """
    pass

# Use the auto method to create the Function metadata instance
func = Function.auto(get_current_weather)

# Print the resulting dictionary
print(func.to_dict())
```

In this case, the `Function.auto` method examines the function's signature and docstring to automatically generate the metadata.

### Alternatives

As an alternative, you can directly define the function metadata as a dictionary according to OpenAI's prescribed approach:

```python
func = {
    "name": "get_current_weather",
    "description": "Get the current weather in a given location",
    "parameters": {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA",
            },
            "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
        },
        "required": ["location"],
    },
}
```

This alternative approach directly defines the metadata structure without using the `gpt-functions` package.

# Tutorial: Using the `gpt-functions` Package

In this tutorial, we will explore how to use the `gpt-functions` package, which provides a simple interface for generating function metadata in a structured format for OpenAI GPT models. The package consists of two main classes: `Parameter` and `Function`.

## Understanding the Classes

Before diving into usage examples, let's understand the purpose and structure of the classes provided by the package.

### `Parameter` Class

The `Parameter` class represents the metadata for a function parameter. It has the following attributes:

- `name` (required): The name of the function parameter.
- `type` (required): The type of the function parameter.
- `description` (optional): The description of the function parameter.
- `enum` (optional): A list of possible values for the function parameter.
- `required` (optional): Specifies whether the function parameter is required.

The `Parameter` class also provides a `to_dict()` method to convert the instance into a dictionary.

### `Function` Class

The `Function` class represents the metadata for a function. It has the following attributes:

- `name` (required): The name of the function.
- `description` (optional): The description of the function.
- `parameters` (optional): A list of `Parameter` instances representing the function's parameters.

The `Function` class provides several methods:

- `to_dict()`: Converts the `Function` instance to a dictionary.
- `add_parameter(parameter)`: Adds a parameter to the `Function` instance.
- `get_parameters()`: Returns the parameters of the `Function` instance as a dictionary.
- `get_required_parameters()`: Returns the required parameters of the `Function` instance as a list.

Additionally, the `Function` class includes a static method called `auto()`, which automatically generates a `Function` instance based on a given function's signature and docstring.

Now that we understand the classes provided by the package, let's explore some usage examples.

## Example Usage 1: Manually Defining Metadata

In this example, we will manually define the metadata for a function called `get_current_weather`.

```python
from gpt_functions.meta import Function, Parameter

# Create instances of Parameter metadata
location = Parameter(name="location", type="str", description="The city and state, e.g. San Francisco, CA", required=True)
unit = Parameter(name="unit", type="str", enum=["celsius", "fahrenheit"])

# Create an instance of Function metadata for retrieving current weather
func = Function(name="get_current_weather", description="Get the current weather in a given location")

# Add parameters to the function metadata
func.add_parameter(location)
func.add_parameter(unit)

# Print the resulting dictionary
print(func.to_dict())
```

In this example, we create instances of `Parameter` metadata for the `location` and `unit` parameters. We then create an instance of `Function` metadata named `func` and add the parameters to it using the `add_parameter()` method. Finally, we print the resulting dictionary representation of the `Function` instance.

## Example Usage 2: Automatically Defining Metadata

In this example, we will automatically generate the metadata for a function called `get_current_weather` using the `auto()` method.

```python
from gpt_functions.meta import Function

def get_current_weather(location: str, unit: str = "celsius"):
    """
    Get the current weather in a given location.

    Args:
        location (str

): The city and state, e.g. San Francisco, CA.
        unit (str, optional): The unit of the temperature. Defaults to "celsius".

    Returns:
        dict: The current weather.
    """
    pass

# Automatically generate the Function metadata instance
func = Function.auto(get_current_weather)

# Print the resulting dictionary
print(func.to_dict())
```

In this example, we define a function `get_current_weather` with type annotations and a docstring describing its purpose and parameters. We then use the `auto()` method of the `Function` class to automatically generate the metadata based on the function's signature and docstring. Finally, we print the resulting dictionary representation of the `Function` instance.


# Tutorial: Using the `Parameter` Class in the `gpt-functions` Package

In this tutorial, we will explore in-depth the usage of the `Parameter` class provided by the `gpt-functions` package. The `Parameter` class represents the metadata for a function parameter. It allows you to define the name, type, description, possible values, and whether the parameter is required.

## Importing the `Parameter` Class

To use the `Parameter` class, we first need to import it from the `gpt-functions.meta` module:

```python
from gpt_functions.meta import Parameter
```

## Creating an Instance of `Parameter`

Let's start by creating an instance of the `Parameter` class. Here's an example:

```python
location = Parameter(name="location", type="str", description="The city and state, e.g. San Francisco, CA", required=True)
```

In this example, we create a `Parameter` instance named `location`. We provide the following arguments:

- `name`: The name of the parameter, which in this case is `"location"`.
- `type`: The type of the parameter, specified as a string. In this case, it is `"str"`.
- `description`: A description of the parameter, which helps provide additional information. Here, we describe it as "The city and state, e.g. San Francisco, CA".
- `required`: A boolean flag indicating whether the parameter is required. In this case, it is set to `True`.

## Accessing the Attributes of `Parameter`

The `Parameter` class provides several attributes that you can access:

- `name`: The name of the parameter.
- `type`: The type of the parameter.
- `description`: The description of the parameter.
- `enum`: A list of possible values for the parameter.
- `required`: A boolean indicating whether the parameter is required.

You can access these attributes directly from the `Parameter` instance. For example:

```python
print(location.name)  # Output: location
print(location.type)  # Output: str
print(location.description)  # Output: The city and state, e.g. San Francisco, CA
print(location.enum)  # Output: None
print(location.required)  # Output: True
```

## Converting `Parameter` to a Dictionary

The `Parameter` class provides a `to_dict()` method that allows you to convert the instance to a dictionary representation. Here's an example:

```python
parameter_dict = location.to_dict()
print(parameter_dict)
```

The output will be a dictionary representing the `Parameter` instance:

```python
{
    "name": "location",
    "type": "str",
    "description": "The city and state, e.g. San Francisco, CA",
    "enum": None,
    "required": True
}
```

## Specifying Enumerated Values for a Parameter

In some cases, you might want to specify a list of possible values for a parameter. To achieve this, you can provide an additional `enum` argument when creating the `Parameter` instance. Here's an example:

```python
unit = Parameter(name="unit", type="str", enum=["celsius", "fahrenheit"])
```

In this example, we create a `Parameter` instance named `unit` with an additional `enum` argument. The `enum` argument is set to `["celsius", "fahrenheit"]`, indicating that the parameter can take either of these two values

# Tutorial: Using the `Function` Class in the `gpt-functions` Package

In this tutorial, we will explore the usage of the `Function` class provided by the `gpt-functions` package. The `Function` class allows you to define metadata for functions, including the function name, description, and parameters.

## Creating an Instance of `Function`

Let's start by creating an instance of the `Function` class. Here's an example:

```python
func = Function(name="get_current_weather", description="Get the current weather in a given location")
```

In this example, we create a `Function` instance named `func`. We provide the following arguments:

- `name`: The name of the function, which in this case is `"get_current_weather"`.
- `description`: A description of the function, which helps provide additional information. Here, we describe it as "Get the current weather in a given location".

## Adding Parameters to a `Function`

The `Function` class provides a method `add_parameter()` to add parameters to the function. Here's an example:

```python
from gpt_functions.meta import Parameter

# Create instances of Parameter metadata
location = Parameter(name="location", type="str", description="The city and state, e.g. San Francisco, CA")
unit = Parameter(name="unit", type="str", enum=["celsius", "fahrenheit"])

# Add parameters to the function metadata
func.add_parameter(location)
func.add_parameter(unit)
```

In this example, we create instances of `Parameter` metadata for the `location` and `unit` parameters. We then add these parameters to the `Function` instance using the `add_parameter()` method.

## Converting `Function` to a Dictionary

The `Function` class provides a `to_dict()` method that allows you to convert the instance to a dictionary representation. Here's an example:

```python
function_dict = func.to_dict()
print(function_dict)
```

The output will be a dictionary representing the `Function` instance:

```python
{
    "name": "get_current_weather",
    "description": "Get the current weather in a given location",
    "parameters": {
        "type": "object",
        "properties": {
            "location": {
                "type": "str",
                "description": "The city and state, e.g. San Francisco, CA"
            },
            "unit": {
                "type": "str",
                "enum": ["celsius", "fahrenheit"]
            }
        },
        "required": ["location"]
    }
}
```

## Automatically Generating `Function` Metadata

The `Function` class also provides an `auto()` method that allows you to automatically generate the `Function` instance based on a function's signature and docstring. Here's an example:

```python
def get_current_weather(location: str, unit: str = "celsius"):
    """
    Get the current weather in a given location

    Args:
        location (str): The city and state, e.g. San Francisco, CA
        unit (str, optional): The unit of the temperature. Defaults to "celsius".

    Returns:
        dict: The current weather.
    """
    pass

# Automatically generate the Function metadata instance
func = Function.auto(get_current_weather)
```

In this example, we define a function `get_current_weather()` with type hints and a docstring describing the function and its parameters. We then use the `auto()` method to automatically generate the `Function` metadata instance.

## Printing `Function` Instance

The `Function` class provides the `__str__()` and `__repr__()` methods to get a string representation of the `Function` instance. You can print the `Function` instance using the `print()` function or by directly calling `str(func)` or `repr(func)`.

```python
print(func)
```

The output will be:

```
Function(name=get_current_weather, description=Get the current weather in a given location, parameters=[location, unit])
```

## Summary

By using the `Function` class, you can define comprehensive function metadata that can be used with OpenAI GPT models. This metadata enables the models to understand the function structure, input parameters, and perform the intended tasks accurately.

Continue experimenting with the `Function` class to define function metadata effectively and utilize the power of the `gpt-functions` package in creating structured data for OpenAI GPT models.