Allow ToolChoice="required"

* Add "required" ToolChoice
* ToolChoice not actually supported for Ollama (yet)

Setting the ToolChoice argument does not have any effect on Ollama models. Ollama lists `tool_choice` as not yet supported (though on the plan): https://github.com/ollama/ollama/blob/main/docs/openai.md

Author: MiriamScharnke

+llms/+internal/callOllamaChatAPI.m

@@ -94,7 +94,7 @@
     parameters.tools = functions;
 end
 
-if ~isempty(nvp.ToolChoice)
+if isfield(nvp,"ToolChoice") && ~isempty(nvp.ToolChoice)
     parameters.tool_choice = nvp.ToolChoice;
 end
 

+llms/+internal/hasTools.m

@@ -20,7 +20,7 @@ function mustBeValidFunctionCall(this, functionCall)
                 if isempty(this.FunctionNames)
                     error("llms:mustSetFunctionsForCall", llms.utils.errorMessageCatalog.getMessage("llms:mustSetFunctionsForCall"));
                 end
-                mustBeMember(functionCall, ["none","auto", this.FunctionNames]);
+                mustBeMember(functionCall, ["none","auto","required", this.FunctionNames]);
             end
         end
 
@@ -31,9 +31,10 @@ function mustBeValidFunctionCall(this, functionCall)
                 if ~isempty(this.Tools)
                     toolChoice = "auto";
                 end
-            elseif ~ismember(toolChoice,["auto","none"])
-                % if toolChoice is not empty, then it must be "auto", "none" or in the format
-                % {"type": "function", "function": {"name": "my_function"}}
+            elseif ~ismember(toolChoice,["auto","none","required"])
+                % if toolChoice is not empty, then it must be "auto", "none",
+                % "required", or in the format {"type": "function", "function":
+                % {"name": "my_function"}}
                 toolChoice = struct("type","function","function",struct("name",toolChoice));
             end
 

azureChat.m

@@ -173,7 +173,7 @@
             %       MaxNumTokens     - Maximum number of tokens in the generated response.
             %                          Default value is inf.
             %
-            %       ToolChoice       - Function to execute. 'none', 'auto',
+            %       ToolChoice       - Function to execute. 'none', 'auto', 'required',
             %                          or specify the function to call.
             %
             %       Seed             - An integer value to use to obtain

doc/functions/generate.md

@@ -99,7 +99,7 @@ The supported name\-value arguments depend on the chat completion API.
 | `PresencePenalty`   | Supported   | Supported   |   |
 | `FrequencyPenalty`   | Supported   | Supported   |   |
 | `NumCompletions`   | Supported   | Supported   |   |
-| `ToolChoice`   | Supported   | Supported   | Supported  |
+| `ToolChoice`   | Supported   | Supported   |   |
 | `MinP`   |  |  | Supported    |
 | `TopK`   |  |  | Supported    |
 | `TailFreeSamplingZ`   |  |  | Supported    |
@@ -261,25 +261,26 @@ This option is only supported for these chat completion APIs:
 -  [`azureChat`](azureChat.md) objects 
 ### `ToolChoice` — Tool choice
 
-`model.ToolChoice` (default) | `"auto"` | `"none"` | `openAIFunction` object | array of `openAIFunction` objects
+`"auto"` (default) | `"none"` | `"required"` | string scalar
 
 
-OpenAI functions to call during output generation. For more information on OpenAI function calling, see [`openAIFunction`](openAIFunction.md).
+Tools that a model is allowed to call during output generation, specified as `"auto"`, `"none"`, `"required"`, or as a tool name. For more information on OpenAI function calling, see [`openAIFunction`](openAIFunction.md).
 
 
-If the tool choice is `"auto"`, then any function calls specified in `chat` are executed during generation. To see whether any function calls are specified, check the `FunctionNames` property of `chat`.
+If the tool choice is set to `"auto"`, then any tools available to the model can be called during output generation. To find out which tools are available to the model, see the `FunctionNames` property of the `model` input argument.
 
 
-If the tool choice is `"none"`, then no function call is executed during generation.
+If the tool choice is set to `"none"`, then no tools are called during output generation.
 
+If the tool choice is set to `"required"`, then one or more tools are called during output generation. 
 
-You can also specify one or more [`openAIFunction`](openAIFunction.md) objects directly.
-
+You can also require that the model uses a specific tool by setting `ToolChoice` to the name of that tool. The name must be part of `model.FunctionNames`.
 
 This option is only supported for these chat completion APIs:
 
 -  [`openAIChat`](openAIChat.md) objects 
--  [`azureChat`](azureChat.md) objects 
+-  [`azureChat`](azureChat.md) objects
+  
 ### `MinP` — Minimum probability ratio
 
 `model.MinP` (default) | numeric scalar between `0` and `1`

functionSignatures.json

@@ -30,7 +30,7 @@
             {"name":"messages","kind":"required","type":[["messageHistory","row"],["string","scalar"]]},
             {"name":"NumCompletions","kind":"namevalue","type":["numeric","scalar","integer","positive"]},
             {"name":"MaxNumTokens","kind":"namevalue","type":["numeric","scalar","positive"]},
-            {"name":"ToolChoice","kind":"namevalue","type":"choices=[\"none\",\"auto\",this.FunctionNames]"},
+            {"name":"ToolChoice","kind":"namevalue","type":"choices=[\"none\",\"auto\",\"required\",this.FunctionNames]"},
             {"name":"Seed","kind":"namevalue","type":["numeric","integer","scalar"]},
             {"name":"ModelName","kind":"namevalue","type":"choices=llms.openai.models"},
             {"name":"Temperature","kind":"namevalue","type":["numeric","scalar",">=0","<=2"]},
@@ -82,7 +82,7 @@
             {"name":"messages","kind":"required","type":[["messageHistory","row"],["string","scalar"]]},
             {"name":"NumCompletions","kind":"namevalue","type":["numeric","scalar","integer","positive"]},
             {"name":"MaxNumTokens","kind":"namevalue","type":["numeric","scalar","positive"]},
-            {"name":"ToolChoice","kind":"namevalue","type":"choices=[\"none\",\"auto\",this.FunctionNames]"},
+            {"name":"ToolChoice","kind":"namevalue","type":"choices=[\"none\",\"auto\",\"required\",this.FunctionNames]"},
             {"name":"Seed","kind":"namevalue","type":["numeric","integer","scalar"]},
             {"name":"APIKey","kind":"namevalue","type":["string","scalar"]},
             {"name":"Temperature","kind":"namevalue","type":["numeric","scalar",">=0","<=2"]},
@@ -108,6 +108,7 @@
             {"name":"modelName","kind":"positional","type":"choices=ollamaChat.models"},
             {"name":"systemPrompt","kind":"ordered","type":["string","scalar"]},
             {"name":"Temperature","kind":"namevalue","type":["numeric","scalar",">=0","<=2"]},
+            {"name":"Tools","kind":"namevalue","type":"openAIFunction"},
             {"name":"TopP","kind":"namevalue","type":["numeric","scalar",">=0","<=1"]},
             {"name":"MinP","kind":"namevalue","type":["numeric","scalar",">=0","<=1"]},
             {"name":"TopK","kind":"namevalue","type":["numeric","scalar","integer",">=1"]},

ollamaChat.m

@@ -160,9 +160,6 @@
             %                           values reduce it. Setting Temperature=0 removes
             %                           randomness from the output altogether.
             %
-            %       ToolChoice       - Function to execute. 'none', 'auto',
-            %                          or specify the function to call.
-            %
             %       TopP              - Top probability mass value for controlling the
             %                           diversity of the output. Default value is CHAT.TopP;
             %                           lower values imply that only the more likely
@@ -218,7 +215,6 @@
                 nvp.StreamFun           (1,1) {mustBeA(nvp.StreamFun,'function_handle')}
                 nvp.Endpoint            (1,1) string = this.Endpoint
                 nvp.MaxNumTokens        (1,1) {mustBeNumeric,mustBePositive} = inf
-                nvp.ToolChoice          {mustBeValidFunctionCall(this, nvp.ToolChoice)} = []
                 nvp.Seed                      {mustBeIntegerOrEmpty(nvp.Seed)} = []
             end
 
@@ -233,8 +229,6 @@
                 messagesStruct = horzcat(this.SystemPrompt, messagesStruct);
             end
 
-            toolChoice = convertToolChoice(this, nvp.ToolChoice);
-
             if isfield(nvp,"StreamFun")
                 streamFun = nvp.StreamFun;
             else
@@ -244,7 +238,7 @@
             try
                 [text, message, response] = llms.internal.callOllamaChatAPI(...
                     nvp.ModelName, messagesStruct, this.FunctionsStruct, ...
-                    Temperature=nvp.Temperature, ToolChoice=toolChoice, ...
+                    Temperature=nvp.Temperature, ...
                     TopP=nvp.TopP, MinP=nvp.MinP, TopK=nvp.TopK,...
                     TailFreeSamplingZ=nvp.TailFreeSamplingZ,...
                     StopSequences=nvp.StopSequences, MaxNumTokens=nvp.MaxNumTokens, ...

openAIChat.m

@@ -161,7 +161,7 @@
             %       MaxNumTokens     - Maximum number of tokens in the generated response.
             %                          Default value is inf.
             %
-            %       ToolChoice       - Function to execute. 'none', 'auto',
+            %       ToolChoice       - Function to execute. 'none', 'auto', 'required',
             %                          or specify the function to call.
             %
             %       Seed             - An integer value to use to obtain

tests/hopenAIChat.m

@@ -1,4 +1,4 @@
-classdef (Abstract) hopenAIChat < hstructuredOutput & htoolCalls
+classdef (Abstract) hopenAIChat < hstructuredOutput & htoolCalls & htoolChoice
 % Tests for OpenAI-based chats (openAIChat, azureChat)
 
 %   Copyright 2023-2025 The MathWorks, Inc.

tests/htoolCalls.m

@@ -7,20 +7,7 @@
         defaultModel
     end
 
-    methods (Test) % not calling the server
-        function errorsWhenPassingToolChoiceWithEmptyTools(testCase)
-            testCase.verifyError(@()generate(testCase.defaultModel,"input", ToolChoice="bla"), "llms:mustSetFunctionsForCall");
-        end
-    end
-
     methods (Test) % calling the server, end-to-end tests
-        function settingToolChoiceWithNone(testCase)
-            functions = openAIFunction("funName");
-            chat = testCase.constructor(Tools=functions);
-
-            testCase.verifyWarningFree(@()generate(chat,"This is okay","ToolChoice","none"));
-        end
-
         function generateWithToolsAndStreamFunc(testCase)
             import matlab.unittest.constraints.HasField
 

tests/htoolChoice.m

@@ -0,0 +1,31 @@
+classdef (Abstract) htoolChoice < matlab.mock.TestCase
+% Tests for backends with ToolChoice support
+
+%   Copyright 2023-2025 The MathWorks, Inc.
+    properties(Abstract)
+        constructor
+        defaultModel
+    end
+    
+    methods (Test) % not calling the server
+        function errorsWhenPassingToolChoiceWithEmptyTools(testCase)
+            testCase.verifyError(@()generate(testCase.defaultModel,"input", ToolChoice="bla"), "llms:mustSetFunctionsForCall");
+        end
+    end
+
+    methods (Test) % calling the server, end-to-end tests
+        function settingToolChoiceWithNone(testCase)
+            functions = openAIFunction("funName");
+            chat = testCase.constructor(Tools=functions);
+
+            testCase.verifyWarningFree(@()generate(chat,"This is okay","ToolChoice","none"));
+        end
+
+        function settingToolChoiceAsRequired(testCase)
+            functions = openAIFunction("funName");
+            chat = testCase.constructor(Tools=functions);
+
+            testCase.verifyWarningFree(@()generate(chat,"This is okay","ToolChoice","required"));
+        end
+    end
+end