Addressing code review feedback.

Author: debymf

+llms/+internal/callOpenAIChatAPI.m

@@ -3,93 +3,123 @@
 
 %callOpenAIChatAPI Calls the openAI chat completions API.
 %
-%   MESSAGES and FUNCTIONS should be structs matching the json format 
+%   MESSAGES and FUNCTIONS should be structs matching the json format
 %   required by the OpenAI Chat Completions API.
 %   Ref: https://platform.openai.com/docs/guides/gpt/chat-completions-api
 %
-%   Currently, the supported NVP are, including the equivalent name in the API:              
-%    - FunctionCall (function_call)             
+%   Currently, the supported NVP are, including the equivalent name in the API:
+%    - FunctionCall (function_call)
 %    - ModelName (model)
 %    - Temperature (temperature)
-%    - TopProbabilityMass (top_p)        
+%    - TopProbabilityMass (top_p)
 %    - NumCompletions (n)
-%    - StopSequences (stop)           
-%    - MaxNumTokens (max_tokens)          
-%    - PresencePenalty (presence_penalty)                         
-%    - FrequencyPenalty (frequence_penalty)                    
-%    - ApiKey 
+%    - StopSequences (stop)
+%    - MaxNumTokens (max_tokens)
+%    - PresencePenalty (presence_penalty)
+%    - FrequencyPenalty (frequence_penalty)
+%    - ApiKey
 %   More details on the parameters: https://platform.openai.com/docs/api-reference/chat/create
+%
+%   Example
+%   
+%   % Create messages struct
+%   messages = {struct("role", "system",...
+%       "content", "You are a helpful assistant");
+%       struct("role", "user", ...
+%       "content", "What is the edit distance between hi and hello?")};
+%
+%   % Create functions struct
+%   functions = {struct("name", "editDistance", ...
+%       "description", "Find edit distance between two strings or documents.", ...
+%       "parameters", struct( ...
+%       "type", "object", ...
+%       "properties", struct(...
+%           "str1", struct(...
+%               "description", "Source string.", ...
+%               "type", "string"),...
+%           "str2", struct(...
+%               "description", "Target string.", ...
+%               "type", "string")),...
+%       "required", ["str1", "str2"]))};
+%
+%   % Define your API key
+%   apiKey = "your-api-key-here"
+%
+%   % Send a request
+%   [text, message] = llms.internal.callOpenAIChatAPI(messages, functions, ApiKey=apiKey)
 
 %   Copyright 2023 The MathWorks, Inc.
 
 arguments
     messages
     functions
-    nvp.FunctionCall
-    nvp.ModelName
-    nvp.Temperature
-    nvp.TopProbabilityMass
-    nvp.NumCompletions
-    nvp.StopSequences
-    nvp.MaxNumTokens
-    nvp.PresencePenalty
-    nvp.FrequencyPenalty
-    nvp.ApiKey
+    nvp.FunctionCall = []
+    nvp.ModelName = "gpt-3.5-turbo"
+    nvp.Temperature = 1
+    nvp.TopProbabilityMass = 1
+    nvp.NumCompletions = 1
+    nvp.StopSequences = []
+    nvp.MaxNumTokens = inf
+    nvp.PresencePenalty = 0
+    nvp.FrequencyPenalty = 0
+    nvp.ApiKey = ""
 end
 
-    END_POINT = "https://api.openai.com/v1/chat/completions";
+END_POINT = "https://api.openai.com/v1/chat/completions";
 
-    parameters = buildParametersCall(messages, functions, nvp);
+parameters = buildParametersCall(messages, functions, nvp);
 
-    response = llms.internal.sendRequest(parameters,nvp.ApiKey, END_POINT);
+response = llms.internal.sendRequest(parameters,nvp.ApiKey, END_POINT);
 
-    if response.StatusCode=="OK"
-        message = response.Body.Data.choices(1).message;
-        if isfield(message, "function_call")
-            text = "";
-            message.function_call.arguments = message.function_call.arguments;
-        else
-            text = string(message.content);
-        end
-    else
+% If call errors, "choices" will not be part of response.Body.Data, instead
+% we get response.Body.Data.error
+if response.StatusCode=="OK"
+    % Outputs the first generation
+    message = response.Body.Data.choices(1).message;
+    if isfield(message, "function_call")
         text = "";
-        message = struct();
+    else
+        text = string(message.content);
     end
+else
+    text = "";
+    message = struct();
+end
 end
 
 function parameters = buildParametersCall(messages, functions, nvp)
-    % Builds a struct in the format that is expected by the API, combining
-    % MESSAGES, FUNCTIONS and parameters in NVP.
+% Builds a struct in the format that is expected by the API, combining
+% MESSAGES, FUNCTIONS and parameters in NVP.
 
-    parameters = struct();
-    parameters.messages = messages;
-    if ~isempty(functions)
-        parameters.functions = functions;
-    end
+parameters = struct();
+parameters.messages = messages;
+if ~isempty(functions)
+    parameters.functions = functions;
+end
 
-    if ~isempty(nvp.FunctionCall)
-        parameters.function_call = nvp.FunctionCall;
-    end
+if ~isempty(nvp.FunctionCall)
+    parameters.function_call = nvp.FunctionCall;
+end
+
+parameters.model = nvp.ModelName;
 
-    parameters.model = nvp.ModelName;
+dict = mapNVPToParameters;
 
-    dict = mapNVPToParameters;
-    
-    nvpOptions = keys(dict);
-    for i=1:length(nvpOptions)
-        if isfield(nvp, nvpOptions(i))
-            parameters.(dict(nvpOptions(i))) = nvp.(nvpOptions(i));
-        end
+nvpOptions = keys(dict);
+for i=1:length(nvpOptions)
+    if isfield(nvp, nvpOptions(i))
+        parameters.(dict(nvpOptions(i))) = nvp.(nvpOptions(i));
     end
 end
+end
 
 function dict = mapNVPToParameters()
-    dict = dictionary();
-    dict("Temperature") = "temperature";
-    dict("TopProbabilityMass") = "top_p";
-    dict("NumCompletions") = "n";
-    dict("StopSequences") = "stop";
-    dict("MaxNumTokens") = "max_tokens";
-    dict("PresencePenalty") = "presence_penalty";
-    dict("FrequencyPenalty ") = "frequency_penalty";
+dict = dictionary();
+dict("Temperature") = "temperature";
+dict("TopProbabilityMass") = "top_p";
+dict("NumCompletions") = "n";
+dict("StopSequences") = "stop";
+dict("MaxNumTokens") = "max_tokens";
+dict("PresencePenalty") = "presence_penalty";
+dict("FrequencyPenalty ") = "frequency_penalty";
 end

+llms/+internal/checkEnvOrNVP.m renamed to +llms/+internal/getApiKeyFromNvpOrEnv.m

@@ -1,7 +1,7 @@
-function key = checkEnvOrNVP(nvp)
+function key = getApiKeyFromNvpOrEnv(nvp)
 % This function is undocumented and will change in a future release
 
-%checkEnvOrNVP Retrieves an API key from a Name-Value Pair struct or environment variable.
+%getApiKeyFromNvpOrEnv Retrieves an API key from a Name-Value Pair struct or environment variable.
 %
 %   This function takes a struct nvp containing name-value pairs and checks
 %   if it contains a field called "ApiKey". If the field is not found, 

+llms/+utils/errorMessageCatalog.m

@@ -40,14 +40,14 @@
 catalog("llms:mustBeVarName") = "Parameter name must begin with a letter and contain not more than 'namelengthmax' characters.";
 catalog("llms:parameterMustBeUnique") = "A parameter name equivalent to '{1}' already exists in Parameters. Redefining a parameter is not allowed.";
 catalog("llms:mustBeAssistantCall") = "Input struct must contain field 'role' with value 'assistant', and field 'content'.";
-catalog("llms:mustBeAssistantWithContent") = "Input struct must contain field 'content' containing text with one or more characters";
-catalog("llms:mustBeAssistantWithNameAndArguments") = "Field 'function_call' must be a struct with fields 'name' and 'arguments'";
-catalog("llms:assistantMustHaveTextNameAndArguments") = "Fields 'name' and 'arguments' must be text with one or more characters";
-catalog("llms:mustBeValidIndex") = "Value is larger than the number of elements in Messages ({1})";
+catalog("llms:mustBeAssistantWithContent") = "Input struct must contain field 'content' containing text with one or more characters.";
+catalog("llms:mustBeAssistantWithNameAndArguments") = "Field 'function_call' must be a struct with fields 'name' and 'arguments'.";
+catalog("llms:assistantMustHaveTextNameAndArguments") = "Fields 'name' and 'arguments' must be text with one or more characters.";
+catalog("llms:mustBeValidIndex") = "Value is larger than the number of elements in Messages ({1}).";
 catalog("llms:stopSequencesMustHaveMax4Elements") = "Number of elements must not be larger than 4.";
-catalog("llms:keyMustBeSpecified") = "API key not found as enviroment variable OPEN_API_KEY and not specified via ApiKey parameter.";
-catalog("llms:mustHaveMessages") = "Value must contain at least one message in Messages";
+catalog("llms:keyMustBeSpecified") = "API key not found as environment variable OPEN_API_KEY and not specified via ApiKey parameter.";
+catalog("llms:mustHaveMessages") = "Value must contain at least one message in Messages.";
 catalog("llms:mustSetFunctionsForCall") = "When no functions are defined, FunctionCall must not be specified.";
-catalog("llms:mustBeMessagesOrTxt") = "Messages must be text with one or more characters or an openAIMessages objects";
+catalog("llms:mustBeMessagesOrTxt") = "Messages must be text with one or more characters or an openAIMessages objects.";
 end
 

examples/ExampleAgentCreation.mlx

@@ -4,8 +4,4 @@ Redistribution and use in source and binary forms, with or without modification,
 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
 3. In all cases, the software is, and all modifications and derivatives of the software shall be, licensed to you solely for use in conjunction with MathWorks products and service offerings. 
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-
-
-
-
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

license.txt

@@ -1,23 +1,23 @@
 classdef(Sealed) openAIChat
-%openAIChat - Chat completion API from OpenAI.
+%openAIChat Chat completion API from OpenAI.
 %
 %   CHAT = openAIChat(systemPrompt) creates an openAIChat object with the
 %   specified system prompt.
 %
 %   CHAT = openAIChat(systemPrompt, Name=Value) specifies additional options
 %   using one or more name-value arguments:
 %
-%   'Functions'             - An array of openAIFunction objects representing
+%   'Functions'              - An array of openAIFunction objects representing
 %                             custom functions to be used during chat completions.
 %
 %   'ModelName'              - The name of the model to use for chat completions.
-%                             The default value is "gpt-3.5-turbo"
+%                             The default value is "gpt-3.5-turbo".
 %
 %   'Temperature'            - The temperature value for controlling the randomness
-%                             of the output. The default value is 1
+%                             of the output. The default value is 1.
 %
 %   'TopProbabilityMass'     - The top probability mass value for controlling the
-%                             diversity of the output. The default value is 1
+%                             diversity of the output. The default value is 1.
 %
 %   'StopSequences'          - Vector of strings that when encountered, will
 %                             stop the generation of tokens. The default
@@ -36,11 +36,11 @@
 %       generate             - Generate a response using the openAIChat instance.
 %
 %   openAIChat Properties:
-%       ModelName            - Model name
+%       ModelName            - Model name.
 %
-%       Temperature          - Temperature of generation
+%       Temperature          - Temperature of generation.
 %
-%       TopProbabilityMass   - Top probability mass to consider for generation
+%       TopProbabilityMass   - Top probability mass to consider for generation.
 %
 %       StopSequences        - Sequences to stop the generation of tokens.
 %
@@ -50,12 +50,12 @@
 %       FrequencyPenalty     - Penalty for using a token that is
 %                              frequent in the training data.
 %
-%       SystemPrompt         - System prompt
+%       SystemPrompt         - System prompt.
 %
 %       AvailableModels      - List of available models.
 %
-%       FunctionsNames       - Names of the functions that the model can
-%                              request calls
+%       FunctionNames        - Names of the functions that the model can
+%                              request calls.
 
 % Copyright 2023 The MathWorks, Inc.
 
@@ -83,8 +83,8 @@
     end
 
     properties(SetAccess=private)  
-        %FUNCTIONSNAMES   Names of the functions that the model can request calls
-        FunctionsNames
+        %FUNCTIONNAMES   Names of the functions that the model can request calls
+        FunctionNames
     end
 
     properties(Access=private)
@@ -105,7 +105,9 @@
             arguments
                 systemPrompt                       {llms.utils.mustBeTextOrEmpty} = []
                 nvp.Functions                (1,:) {mustBeA(nvp.Functions, "openAIFunction")} = openAIFunction.empty
-                nvp.ModelName                (1,1) {mustBeValidModelName} = "gpt-3.5-turbo"
+                nvp.ModelName                (1,1) {mustBeMember(nvp.ModelName,["gpt-4", "gpt-4-0613", "gpt-4-32k", "gpt-4-32k-0613",...
+                                                        "gpt-3.5-turbo", "gpt-3.5-turbo-0613", "gpt-3.5-turbo-16k",... 
+                                                        "gpt-3.5-turbo-16k-0613"])} = "gpt-3.5-turbo"
                 nvp.Temperature              (1,1) {mustBeValidTemperature} = 1
                 nvp.TopProbabilityMass       (1,1) {mustBeValidTopP} = 1
                 nvp.StopSequences            (1,:) {mustBeValidStop} = {}
@@ -116,11 +118,11 @@
 
             if ~isempty(nvp.Functions)
                 this.Functions = nvp.Functions;
-                [this.FunctionsStruct, this.FunctionsNames] = functionAsStruct(nvp.Functions);
+                [this.FunctionsStruct, this.FunctionNames] = functionAsStruct(nvp.Functions);
             else
                 this.Functions = [];
                 this.FunctionsStruct = [];
-                this.FunctionsNames = [];
+                this.FunctionNames = [];
             end
 
             if ~isempty(systemPrompt)
@@ -136,7 +138,7 @@
             this.StopSequences = nvp.StopSequences;
             this.PresencePenalty = nvp.PresencePenalty;
             this.FrequencyPenalty = nvp.FrequencyPenalty;
-            this.ApiKey = llms.internal.checkEnvOrNVP(nvp);
+            this.ApiKey = llms.internal.getApiKeyFromNvpOrEnv(nvp);
         end
 
         function [text, message, response] = generate(this, messages, nvp)
@@ -146,7 +148,7 @@
             %   with the specified MESSAGES and optional
             %   name-value pair arguments.
             %
-            %   [TEXT, MESSAGE, RESPONSE] = generate(_______, Name=Value) specifies additional options
+            %   [TEXT, MESSAGE, RESPONSE] = generate(__, Name=Value) specifies additional options
             %   using one or more name-value arguments:
             %
             %       NumCompletions   - Number of completions to generate.
@@ -230,17 +232,17 @@
         function mustBeValidFunctionCall(this, functionCall)
             if ~isempty(functionCall)
                 mustBeTextScalar(functionCall);
-                if isempty(this.FunctionsNames)
+                if isempty(this.FunctionNames)
                     error("llms:mustSetFunctionsForCall", llms.utils.errorMessageCatalog.getMessage("llms:mustSetFunctionsForCall"));
                 end
-                mustBeMember(functionCall, ["none","auto", this.FunctionsNames]);
+                mustBeMember(functionCall, ["none","auto", this.FunctionNames]);
             end
         end
 
         function functionCall = convertFunctionCall(this, functionCall)
             % If functionCall is not empty, then it must be in
             % the format {"name", functionCall}
-            if ~isempty(functionCall)&&ismember(functionCall, this.FunctionsNames)
+            if ~isempty(functionCall)&&ismember(functionCall, this.FunctionNames)
                 functionCall = struct("name", functionCall);
             end
 
@@ -249,14 +251,14 @@ function mustBeValidFunctionCall(this, functionCall)
 end
 
 
-function [functionsStruct, functionsNames] = functionAsStruct(functions)
+function [functionsStruct, functionNames] = functionAsStruct(functions)
 numFunctions = numel(functions);
 functionsStruct = cell(1, numFunctions);
-functionsNames = strings(1, numFunctions);
+functionNames = strings(1, numFunctions);
 
 for i = 1:numFunctions
     functionsStruct{i} = encodeStruct(functions(i));
-    functionsNames(i) = functions(i).FunctionName;
+    functionNames(i) = functions(i).FunctionName;
 end
 end
 
@@ -284,11 +286,6 @@ function mustBeValidTopP(value)
 mustBeLessThanOrEqual(value,1);
 end
 
-function mustBeValidModelName(value)
-mustBeNonzeroLengthText(value);
-mustBeMember(value,openAIChat.AvailableModels);
-end
-
 function mustBeValidTemperature(value)
 mustBeNonnegative(value);
 mustBeLessThanOrEqual(value,2)