Skip to content

Commit da1f1c4

Browse files
MiriamScharnkeccreutzi
MiriamScharnke
authored and
ccreutzi
committed
Documentation: Reference Pages (#5)
* Documentation: Reference Pages We have added a new directory `functions` to the `documentation` directory. The `functions` folder contains documentation for these functions and objects: - openAIChat - azureChat - ollamaChat - generate - openAIFunction - addParameter - openAIImages - openAIImages.generate - edit - createVariation - messageHistory - addSystemMessage - addUserMessage - addUserMessageWithImages - addToolMessage - addResponseMessage - removeMessage
1 parent 4101015 commit da1f1c4

26 files changed

+3054
-0
lines changed

‎doc/functions/addParameter.md

+192
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
2+
# addParameter
3+
4+
Add input argument to `openAIFunction` object
5+
6+
# Syntax
7+
8+
`fUpdated = addParameter(f,parameterName)`
9+
10+
11+
`___ = addParameter(___,Name=Value)`
12+
13+
# Description
14+
15+
`fUpdated = addParameter(f,parameterName)` adds an input argument `parameterName` to the `openAIFunction` object `f`.
16+
17+
18+
`___ = addParameter(___,Name=Value)` specifies additional options using one or more name\-value arguments.
19+
20+
# Examples
21+
## Compute Sine Using OpenAI Function Call
22+
23+
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.
24+
25+
```matlab
26+
loadenv(".env")
27+
```
28+
29+
Create an `openAIFunction` object that represents the [`sind`](https://www.mathworks.com/help/matlab/ref/sind.html) function. The `sind` function has a single input argument, `x`, representing the input angle in degrees.
30+
31+
```matlab
32+
f = openAIFunction("sind","Sine of argument in degrees");
33+
f = addParameter(f,"x",type="number",description="Angle in degrees");
34+
```
35+
36+
Connect to the OpenAI Chat Completion API. Pass the `openAIFunction` object `f` as an input argument.
37+
38+
```matlab
39+
model = openAIChat("You are a helpful assistant.",Tools=f);
40+
```
41+
42+
Initialize the message history. Add a user message to the message history.
43+
44+
```matlab
45+
messages = messageHistory;
46+
messages = addUserMessage(messages,"What is the sine of thirty?");
47+
```
48+
49+
Generate a response based on the message history.
50+
51+
```matlab
52+
[~,completeOutput] = generate(model,messages)
53+
```
54+
55+
```matlabTextOutput
56+
completeOutput = struct with fields:
57+
role: 'assistant'
58+
content: []
59+
tool_calls: [1x1 struct]
60+
refusal: []
61+
62+
```
63+
64+
The model has not generated any text. Instead, it has detected a function call, `completeOutput.tool_calls`.
65+
66+
67+
Add the response to the message history.
68+
69+
```matlab
70+
messages = addResponseMessage(messages,completeOutput);
71+
```
72+
73+
Extract the tool call ID and the name of the called function.
74+
75+
```matlab
76+
toolCallID = string(completeOutput.tool_calls.id)
77+
```
78+
79+
```matlabTextOutput
80+
toolCallID = "call_Scx4xE9whYiL2FbQWYslDgDr"
81+
```
82+
83+
```matlab
84+
functionCalled = string(completeOutput.tool_calls.function.name)
85+
```
86+
87+
```matlabTextOutput
88+
functionCalled = "sind"
89+
```
90+
91+
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.
92+
93+
94+
Extract the input argument values from the complete output using the [`jsondecode`](https://www.mathworks.com/help/matlab/ref/jsondecode.html) function. Compute the sine of the generated argument value and add the result to the message history using the `addToolMessage` function.
95+
96+
```matlab
97+
if functionCalled == "sind"
98+
args = jsondecode(completeOutput.tool_calls.function.arguments);
99+
result = sind(args.x)
100+
messages = addToolMessage(messages,toolCallID,functionCalled,"x="+result);
101+
end
102+
```
103+
104+
```matlabTextOutput
105+
result = 0.5000
106+
```
107+
108+
Finally, generate a natural language response.
109+
110+
```matlab
111+
generatedText = generate(model,messages)
112+
```
113+
114+
```matlabTextOutput
115+
generatedText = "The sine of 30 degrees is 0.5."
116+
```
117+
# Input Arguments
118+
### f — OpenAI function
119+
120+
[`openAIFunction`](openAIFunction.md) object
121+
122+
123+
OpenAI function, specified as an `openAIFunction` object.
124+
125+
### `parameterName` — Name of new input argument
126+
127+
string scalar | character array
128+
129+
130+
Specify the name of the new input argument. The name must be a valid MATLAB variable name.
131+
132+
133+
For more information on variable naming rules in MATLAB, see [https://www.mathworks.com/help/matlab/matlab\_prog/variable\-names.html](https://www.mathworks.com/help/matlab/matlab_prog/variable-names.html).
134+
135+
## Name\-Value Arguments
136+
### `RequiredParameter` — Flag to require argument
137+
138+
`true` (default) | `false`
139+
140+
141+
Specify whether the argument is required (`true`) or optional (`false`).
142+
143+
### `description` — Argument description
144+
145+
string scalar | character vector
146+
147+
148+
Natural language description of the input argument, specified as a string or character array.
149+
150+
### `type` — Argument type
151+
152+
string scalar | string vector | character vector
153+
154+
155+
Data type or types of the input argument, specified as JSON data type. The possible argument types and their corresponding MATLAB data types are:
156+
157+
- `"string"` — character vector
158+
- `"number"` — scalar double
159+
- `"integer"` — scalar integer
160+
- `"object"` — scalar structure
161+
- `"boolean"` — scalar logical
162+
- `"null"` — `NaN` or empty double
163+
164+
For more information on how to decode JSON\-formatted data in MATLAB, see [jsondecode](https://www.mathworks.com/help/matlab/ref/jsondecode.html).
165+
166+
### `enum` — List of possible argument values
167+
168+
string vector
169+
170+
171+
List of all possible values of an input argument.
172+
173+
174+
**Example**: `["on" "off" "auto"]`
175+
176+
# Output Argument
177+
### `fUpdated` — Updated OpenAI function
178+
179+
`openAIFunction` object
180+
181+
182+
Updated OpenAI function, specified as an `openAIFunction` object.
183+
184+
# See Also
185+
186+
[`openAIFunction`](openAIFunction.md) | [`openAIChat`](openAIChat.md) | [`generate`](generate.md) | [`addToolMessage`](addToolMessage.md)
187+
188+
- [Analyze Scientific Papers Using ChatGPT Function Calls](../../examples/AnalyzeScientificPapersUsingFunctionCalls.md)
189+
- [Analyze Text Data Using Parallel Function Calls with ChatGPT](../../examples/AnalyzeTextDataUsingParallelFunctionCallwithChatGPT.md)
190+
191+
*Copyright 2024 The MathWorks, Inc.*
192+

‎doc/functions/addResponseMessage.md

+196
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,196 @@
1+
2+
# addResponseMessage
3+
4+
Add response message to message history
5+
6+
7+
`updatedMessages = addResponseMessage(messages,completeOutput)`
8+
9+
# Description
10+
11+
`updatedMessages = addResponseMessage(messages,completeOutput)` adds the generated output of a large language model to the `messageHistory` object `messages`.
12+
13+
# Examples
14+
## Add Response Message to Message History
15+
16+
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.
17+
18+
```matlab
19+
loadenv(".env")
20+
```
21+
22+
Connect to the OpenAI Chat Completion API.
23+
24+
```matlab
25+
model = openAIChat("You are a helpful assistant.");
26+
```
27+
28+
Initialize the message history.
29+
30+
```matlab
31+
messages = messageHistory;
32+
```
33+
34+
Add a user message to the message history.
35+
36+
```matlab
37+
messages = addUserMessage(messages,"Why is a raven like a writing desk?");
38+
39+
Generate a response.
40+
41+
```matlab
42+
[generatedText,completeOutput,httpResponse] = generate(model,messages);
43+
```
44+
45+
Add the response to the message history.
46+
47+
```matlab
48+
messages = addResponseMessage(messages,completeOutput);
49+
messages.Messages{end}
50+
```
51+
52+
```matlabTextOutput
53+
ans = struct with fields:
54+
role: "assistant"
55+
content: "The question "Why is a raven like a writing desk?" is famously posed by the Mad Hatter in Lewis Carroll's "Alice's Adventures in Wonderland." Initially, it is presented as a riddle without a clear answer, contributing to the absurdity and nonsensical nature of the story. However, over time, various interpretations and answers have been suggested, such as:↵↵1. **Both can produce notes**: Ravens can "caw" or make sounds like a note, and writing desks are used for writing notes or letters.↵2. **Both are associated with writing**: Ravense have historically been linked to writers (like Edgar Allan Poe's famous poem "The Raven"), and desks are where writing is done.↵3. **The riddle is inherently nonsensical**: The whole point may be that some riddles don't have answers, fitting into the whimsical and illogical world of Wonderland.↵↵Carroll himself later suggested that the riddle was meant to be without an answer, thus adding to its charm and mystique in the context of his work."
56+
57+
```
58+
## Compute Sine Using OpenAI Function Call
59+
60+
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.
61+
62+
```matlab
63+
loadenv(".env")
64+
```
65+
66+
Create an `openAIFunction` object that represents the [`sind`](https://www.mathworks.com/help/matlab/ref/sind.html) function. The `sind` function has a single input argument, `x`, representing the input angle in degrees.
67+
68+
```matlab
69+
f = openAIFunction("sind","Sine of argument in degrees");
70+
f = addParameter(f,"x",type="number",description="Angle in degrees");
71+
```
72+
73+
Connect to the OpenAI Chat Completion API. Pass the `openAIFunction` object `f` as an input argument.
74+
75+
```matlab
76+
model = openAIChat("You are a helpful assistant.",Tools=f);
77+
```
78+
79+
Initialize the message history. Add a user message to the message history.
80+
81+
```matlab
82+
messages = messageHistory;
83+
messages = addUserMessage(messages,"What is the sine of thirty?");
84+
```
85+
86+
Generate a response based on the message history.
87+
88+
```matlab
89+
[~,completeOutput] = generate(model,messages)
90+
```
91+
92+
```matlabTextOutput
93+
completeOutput = struct with fields:
94+
role: 'assistant'
95+
content: []
96+
tool_calls: [1x1 struct]
97+
refusal: []
98+
99+
```
100+
101+
The model has not generated any text. Instead, it has detected a function call, `completeOutput.tool_calls`.
102+
103+
104+
Add the response to the message history.
105+
106+
```matlab
107+
messages = addResponseMessage(messages,completeOutput);
108+
```
109+
110+
Extract the tool call ID and the name of the called function.
111+
112+
```matlab
113+
toolCallID = string(completeOutput.tool_calls.id)
114+
```
115+
116+
```matlabTextOutput
117+
toolCallID = "call_VLRxaOUTDEyzCY4c8rDnq0jM"
118+
```
119+
120+
```matlab
121+
functionCalled = string(completeOutput.tool_calls.function.name)
122+
```
123+
124+
```matlabTextOutput
125+
functionCalled = "sind"
126+
```
127+
128+
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.
129+
130+
131+
Extract the input argument values from the complete output using the [`jsondecode`](https://www.mathworks.com/help/matlab/ref/jsondecode.html) function. Compute the sine of the generated argument value and add the result to the message history using the `addToolMessage` function.
132+
133+
```matlab
134+
if functionCalled == "sind"
135+
args = jsondecode(completeOutput.tool_calls.function.arguments);
136+
result = sind(args.x)
137+
messages = addToolMessage(messages,toolCallID,functionCalled,"x="+result);
138+
end
139+
```
140+
141+
```matlabTextOutput
142+
result = 0.5000
143+
```
144+
145+
Finally, generate a natural language response.
146+
147+
```matlab
148+
generatedText = generate(model,messages)
149+
```
150+
151+
```matlabTextOutput
152+
generatedText = "The sine of thirty degrees is 0.5."
153+
```
154+
# Input Arguments
155+
### `messages` — Message history
156+
157+
`messageHistory` object
158+
159+
160+
Message history, specified as a [`messageHistory`](messageHistory.md) object.
161+
162+
### completeOutput — Complete output
163+
164+
structure array
165+
166+
167+
Complete output generated from a large language model using the [`generate`](generate.md) function, specified as a structure array.
168+
169+
170+
The type and name of the fields in the structure depend on the API, the model, whether you use function calls, and whether you stream the output.
171+
172+
# Output Argument
173+
### `updatedMessages` — Updated message history
174+
175+
`messageHistory` object
176+
177+
178+
Updated message history, specified as a [`messageHistory`](messageHistory.md) object.
179+
180+
181+
The updated message history includes a new structure array with these fields:
182+
183+
- role —`"assistant"`
184+
- content — Set by the `content` input argument
185+
186+
If the generated response includes a function call, then the updated message history also includes this field:
187+
188+
- tool\_calls — `completeOutput.tool_calls` structure array
189+
# See Also
190+
191+
[`generate`](generate.md) | [`messageHistory`](messageHistory.md) | [`openAIChat`](openAIChat.md) | [`ollamaChat`](ollamaChat.md) | [`azureChat`](azureChat.md) | [`addUserMessage`](addUserMessage.md) | [`addUserMessageWithImage`](addUserMessageWithImage.md) | [`addToolMessage`](addToolMessage.md) | [`addSystemMessage`](addSystemMessage.md)
192+
193+
- [Analyze Text Data Using Parallel Function Calls with ChatGPT](../../examples/AnalyzeTextDataUsingParallelFunctionCallwithChatGPT.md)
194+
195+
*Copyright 2024 The MathWorks, Inc.*
196+

0 commit comments

Comments
 (0)