openAIFunction.md

openAIFunction

Use Function Calls from MATLAB®

Creation

Syntax

f = openAIFunction(name,description)

Description

An openAIFunction object represents a tool that you have, such as a MATLAB function. It includes information about the name, syntax, and behavior of the tool. If you pass an openAIFunction object to a large language model (LLM), then the LLM can suggest calls to the tool in its generated output. The LLM does not execute the tool itself. However, you can write scripts that automate the tool calls suggested by the LLM.

Use openAIFunction objects to call tools using OpenAI® or Ollama™.

For example:

f = openAIFunction(name,description) creates an openAIFunction object.

Input Arguments

name — Function name

character vector | string scalar

Specify the function name and set the FunctionName property.

description — Function description

[] (default) | character vector | string scalar

Describe the function using natural language and set the Description property.

Properties

FunctionName — Tool name

character vector | string scalar

This property is read-only.

The name of your tool. This does not have to be the same as the name of your openAIFunction object.

Set this property at construction using the name input argument.

Description — Tool description

[] (default) | character vector | string array

This property is read-only.

Natural language description of your function.

Set this property at construction using the description input argument.

Parameters — Function arguments

empty structure array (default) | structure array

Each field corresponds to an input argument, specified as another structure array. Add parameters one-by-one using the addParameter function. The fields of the nested structure array depend on the input you provide to the addParameter function.

Field name	Field description	Optional
required	Whether the input argument is required, specified as true or false.	No
type	Data type or types of the input argument, specified as JSON data type. The possible argument types and their corresponding MATLAB data types are: - "string" — character vector - "number" — scalar double - "integer" — scalar integer - "object" — scalar structure - "boolean" — scalar logical - "null" — NaN or empty double For more information on how to decode JSON-formatted data in MATLAB, see jsondecode.	Yes
description	Natural language description of the input argument, specified as a string or character array.	Yes
enum	List of all possible values of an input argument.	Yes

For example, the Parameters structure describing the input arguments for a function myFun(x) with optional input arguments animalSpecies and isMammal could look like this:

Object Functions

addParameter — Add information about an input argument

Examples

Compute Sine Using OpenAI Function Call

First, specify the OpenAI® API key as an environment variable and save it to a file called ".env". Next, load the environment file using the loadenv function.

loadenv(".env")

Create an openAIFunction object that represents the sind function. The sind function has a single input argument, x, representing the input angle in degrees.

f = openAIFunction("sind","Sine of argument in degrees");
f = addParameter(f,"x",type="number",description="Angle in degrees");

Connect to the OpenAI Chat Completion API. Pass the openAIFunction object f as an input argument.

model = openAIChat("You are a helpful assistant.",Tools=f);

Initialize the message history. Add a user message to the message history.

messages = messageHistory;
messages = addUserMessage(messages,"What is the sine of thirty?");

Generate a response based on the message history.

[~,completeOutput] = generate(model,messages)

completeOutput = struct with fields:
          role: 'assistant'
       content: []
    tool_calls: [1x1 struct]
       refusal: []

The model has not generated any text. Instead, it has detected a function call, completeOutput.tool_calls.

Add the response to the message history.

messages = addResponseMessage(messages,completeOutput);

Extract the tool call ID and the name of the called function.

toolCallID = string(completeOutput.tool_calls.id)

toolCallID = "call_K4zqC0oO6vA97BTvSSCY9FHL"

functionCalled = string(completeOutput.tool_calls.function.name)

functionCalled = "sind"

Make sure that the model is calling the correct function. Even with only a single function, large language models can hallucinate function calls to fictitious functions.

Extract the input argument values from the complete output using the jsondecode function. Compute the sine of the generated argument value and add the result to the message history using the addToolMessage function.

if functionCalled == "sind"
    args = jsondecode(completeOutput.tool_calls.function.arguments);
    result = sind(args.x)
    messages = addToolMessage(messages,toolCallID,functionCalled,"x="+result);
end

result = 0.5000

Finally, generate a natural language response.

generatedText = generate(model,messages)

generatedText = "The sine of thirty degrees is 0.5."

See Also

• Analyze Scientific Papers Using ChatGPT Function Calls
• Analyze Text Data Using Parallel Function Calls with ChatGPT
• Analyze Text Data Using Parallel Function Calls with Ollama

Copyright 2024 The MathWorks, Inc.