openAIFunction from struct

Add creation from struct or cell array of struct

This is for interaction with MCP tool definitions

---------

Co-authored-by: Miriam Scharnke <[email protected]>

Author: ccreutzi

+llms/+utils/errorMessageCatalog.m

@@ -44,6 +44,8 @@
 catalog = dictionary("string", "string");
 catalog("llms:mustBeUnique") = "Values must be unique.";
 catalog("llms:mustBeVarName") = "Parameter name must begin with a letter and contain not more than 'namelengthmax' characters.";
+catalog("llms:mustBeNonzeroLengthTextOrStruct") = "Value must be a character vector, string scalar, scalar cell array of character vectors, struct, or cell array of structs.";
+catalog("llms:mustOnlyBeStruct") = "When creating an openAIFunction object from tools provided by MCP servers, additional parameters are not supported.";
 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.";

README.md

@@ -18,7 +18,8 @@ Using this add-on, you can:
 -  Generate responses to natural language prompts.
 -  Manage chat history.
 -  Generate JSON\-formatted and structured output. 
--  Use tool calling.  
+-  Use tool calling.
+-  Call external tools provided by MCP servers (requires the MATLAB MCP HTTP Client add\-on).
 -  Generate, edit, and describe images. 
 
 For more information about the features in this add-on, see the documentation in the [`doc`](/doc) directory.

doc/functions/openAIFunction.md

@@ -8,10 +8,14 @@ Use Function Calls from MATLAB®
 
 `f = openAIFunction(name,description)`
 
+`f = openAIFunction(mcpTool)`
+
 ## 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.
 
+If you have the MATLAB MCP HTTP Client add\-on installed, then you can also use tools provided by external MCP servers.
+
 Use `openAIFunction` objects to call tools using OpenAI® or Ollama™.
 
 
@@ -21,7 +25,9 @@ For example:
 ![Diagram illustrating how to incorporate function calling in text generation.](images/openAIFunction1.png)
 
 
-`f = openAIFunction(name,description)` creates an `openAIFunction` object. 
+`f = openAIFunction(name,description)` creates an `openAIFunction` object with a name `name` and description `description`.
+
+`f = openAIFunction(mcpTool)` creates an `openAIFunction` object from one or more tools provided by an MCP server specified as a cell array of struct. For example, `mcpTool = client.Tools` for an `mcpHTTPClient` object `client` (requires the MATLAB MCP HTTP Client add\-on).
 
 # Input Arguments
 ### `name` — Function name
@@ -38,6 +44,13 @@ Specify the function name and set the `FunctionName` property.
 
 Describe the function using natural language and set the `Description` property.
 
+### `mcpTool` — Tool provided by MCP server
+cell array of struct
+
+Tool provided by an external MCP server, specified as a cell array of struct (requires the MATLAB MCP HTTP Client add\-on).  
+
+For example, if you have an `mcpHTTPClient` (MATLAB MCP HTTP Client) object `client`, then you can specify `mcpTool` as `client.Tools`.
+
 # Properties
 ### `FunctionName` — Tool name
 

functionSignatures.json

@@ -153,5 +153,28 @@
             {"name":"message","type":"struct"},
             {"name":"response","type":"matlab.net.http.ResponseMessage"}
         ]
+    },
+    "openAIFunction.openAIFunction":
+    {
+        "inputs":
+        [
+            {"name":"name","kind":"required","type":["string","scalar"]},
+            {"name":"description","kind":"positional","type":["string","scalar"]}
+        ],
+        "outputs":
+        [
+            {"name":"this","type":"openAIFunction"}
+        ]
+    },
+    "openAIFunction.openAIFunction":
+    {
+        "inputs":
+        [
+            {"name":"definition","kind":"required","type":[["struct"],["cell"]]}
+        ],
+        "outputs":
+        [
+            {"name":"this","type":"openAIFunction"}
+        ]
     }
 }

openAIFunction.m

@@ -37,10 +37,19 @@
     methods
         function this = openAIFunction(name, description)
             arguments
-                name (1,1) {mustBeNonzeroLengthText}
+                name {mustBeNonzeroLengthTextOrStruct}
                 description {llms.utils.mustBeTextOrEmpty} = []
             end
 
+            if isstruct(name) || (iscell(name) && ~isempty(name) && isstruct(name{1}))
+                if nargin > 1
+                    error("llms:mustOnlyBeStruct", ...
+                        llms.utils.errorMessageCatalog.getMessage("llms:mustOnlyBeStruct"));
+                end
+                this = structToFunction(name);
+                return
+            end
+
             this.FunctionName = name;
             this.Description = description;
         end
@@ -157,6 +166,18 @@ function mustBeValidVariableName(value)
 end
 end
 
+function mustBeNonzeroLengthTextOrStruct(value)
+if isstruct(value) || (iscell(value) && all(cellfun(@isstruct,value)))
+    return
+end
+try
+    mustBeNonzeroLengthText(value)
+    mustBeTextScalar(value)
+catch
+    error("llms:mustBeNonzeroLengthTextOrStruct", llms.utils.errorMessageCatalog.getMessage("llms:mustBeNonzeroLengthTextOrStruct"));
+end
+end
+
 function validatePropertyValue(value,name)
 switch(name)
     case "type"
@@ -181,4 +202,43 @@ function validatePropertyEnum(value)
 if ~llms.utils.isUnique(value)
     error("llms:mustBeUnique", llms.utils.errorMessageCatalog.getMessage("llms:mustBeUnique"));
 end
+end
+
+function fns = structToFunction(fnStruct)
+    if iscell(fnStruct)
+        fns = cellfun(@structToFunction,fnStruct,"UniformOutput",false);
+        fns = reshape([fns{:}],size(fnStruct));
+        return
+    end
+    if ~isscalar(fnStruct)
+        fns = arrayfun(@structToFunction,fnStruct,"UniformOutput",false);
+        fns = reshape([fns{:}],size(fnStruct));
+        return
+    end
+
+    if isfield(fnStruct,'description')
+        fns = openAIFunction(string(fnStruct.name),string(fnStruct.description));
+    else
+        fns = openAIFunction(string(fnStruct.name));
+    end
+    argStruct = fnStruct.inputSchema;
+    props = argStruct.properties;
+    names = string(fieldnames(props));
+    for name = names(:).'
+        optargs = {};
+        if isfield(props.(name),"type")
+            type = string(props.(name).type);
+            % openAIFunction only supports a subset of types
+            if ismember(type,["string","number","integer","object","boolean","null"])
+                optargs = [optargs, {"type",type}];%#ok<AGROW>
+            end
+        end
+        if isfield(props.(name),"description")
+            description = string(props.(name).description);
+            optargs = [optargs, {"description", description}];%#ok<AGROW>
+        end
+        required = isfield(argStruct,"required") && ismember(name,argStruct.required);
+        fns = addParameter(fns,name,optargs{:}, ...
+                RequiredParameter=required);
+    end
 end

tests/topenAIFunction.m

@@ -20,12 +20,50 @@ function testCreateFunctionWithDescription(testCase)
         end
 
         function testCreateFunctionWithoutDescription(testCase)
-            name = "functionName";
+            name = 'functionName';
             funObj = openAIFunction(name);
             testCase.verifyEqual(funObj.FunctionName, name);
             testCase.verifyEmpty(funObj.Description);
         end
 
+        function testCreateFromScalarStruct(testCase)
+            toolDef = hFcnStruct;
+            % difference between openAI and MCP:
+            toolDef = renameStructField(toolDef,'parameters','inputSchema');
+            funObj = openAIFunction(toolDef);
+            testCase.verifyEqual(funObj.FunctionName,toolDef.name);
+            testCase.verifyEqual(funObj.Description,[]);
+        end
+
+        function testCreateFromStructArray(testCase)
+            toolDef = hFcnStruct;
+            % difference between openAI and MCP:
+            toolDef = renameStructField(toolDef,'parameters','inputSchema');
+            toolDef2 = toolDef;
+            toolDef2.name = "otherTool";
+            funObj = openAIFunction([toolDef,toolDef2]);
+            testCase.assertSize(funObj,[1,2]);
+            testCase.verifyEqual(funObj(1).FunctionName,toolDef.name);
+            testCase.verifyEqual(funObj(1).Description,[]);
+            testCase.verifyEqual(funObj(2).FunctionName,"otherTool");
+            testCase.verifyEqual(funObj(2).Description,[]);
+        end
+
+        function testCreateFromCellOfStructs(testCase)
+            toolDef = hFcnStruct;
+            % difference between openAI and MCP:
+            toolDef = renameStructField(toolDef,'parameters','inputSchema');
+            toolDef2 = toolDef;
+            toolDef2.name = "otherTool";
+            toolDef2.description = "desc";
+            funObj = openAIFunction({toolDef,toolDef2});
+            testCase.assertSize(funObj,[1,2]);
+            testCase.verifyEqual(funObj(1).FunctionName,toolDef.name);
+            testCase.verifyEqual(funObj(1).Description,[]);
+            testCase.verifyEqual(funObj(2).FunctionName,"otherTool");
+            testCase.verifyEqual(funObj(2).Description,"desc");
+        end
+
         function testParametersAreAdded(testCase)
             funObj = openAIFunction("getCurrentWeather");
 
@@ -45,16 +83,7 @@ function testValidProperties(testCase, ValidProperties)
 
         function testValidOutputStructWithParameters(testCase)
             % Format expected from OpenAI 
-            expectedStruct = struct("name", "getCurrentWeather",...
-                "parameters", struct("type", "object", ...
-                    "properties", struct( ...
-                        "location", struct("type", "string", ...
-                            "description", "City and state."), ...
-                        "format", struct("type", "string",...
-                            "enum", ["celsius", "fahrenheit"], ...
-                            "description", "Temperature unit to use.")), ...
-                     "required", ["location", "format"]));
-
+            expectedStruct = hFcnStruct;
             funObj = openAIFunction("getCurrentWeather");
 
             funObj = addParameter(funObj, "location", type="string", ...
@@ -201,17 +230,33 @@ function testInvalidInputsAddParameter(testCase, InvalidInputsaddParameter)
 invalidInputsConstructor = struct( ...
     "NonTextName", ...
         struct("Input", {{123}}, ...
-            "Error", "MATLAB:validators:mustBeNonzeroLengthText"), ...
+            "Error", "llms:mustBeNonzeroLengthTextOrStruct"), ...
     ...
     "NonTextDescription", ...
         struct("Input", {{"functionName", 123}}, ...
             "Error", "MATLAB:validators:mustBeTextScalar"), ...
     ...
     "NonScalarName", ...
         struct("Input", {{["name1" "name2"]}}, ...
-            "Error", "MATLAB:validation:IncompatibleSize"), ...
+            "Error", "llms:mustBeNonzeroLengthTextOrStruct"), ...
     ...
     "NonScalarDescription", ...
         struct("Input", {{"functionName", ["desc1" "desc2"]}}, ...
-            "Error", "MATLAB:validators:mustBeTextScalar"));
+            "Error", "MATLAB:validators:mustBeTextScalar"), ...
+    ...
+    "StructPlusNVPs", ...
+        struct("Input", {{hFcnStruct, "description"}}, ...
+                "Error", "llms:mustOnlyBeStruct"));
+end
+
+function structEnc = hFcnStruct
+structEnc = struct("name", "getCurrentWeather",...
+    "parameters", struct("type", "object", ...
+        "properties", struct( ...
+            "location", struct("type", "string", ...
+                "description", "City and state."), ...
+            "format", struct("type", "string",...
+                "enum", ["celsius", "fahrenheit"], ...
+                "description", "Temperature unit to use.")), ...
+        "required", ["location", "format"]));
 end