OpenAI - Adopt ToolCallingManager API

- Update OpenAiChatModel to use the new ToolCallingManager API, while ensuring full API backward compatibility.
- Introduce Builder to instantiate a new OpenAiChatModel since the number of overloaded constructors is growing too big.
- Update documentation about tool calling and OpenAI support for that.
- Add extra validation to ensure the uniqueness of tool names when aggregated from different sources.

Signed-off-by: Thomas Vitale <[email protected]>

Author: ThomasVitale

models/spring-ai-ollama/src/main/java/org/springframework/ai/ollama/OllamaChatModel.java

@@ -129,7 +129,10 @@ public OllamaChatModel(OllamaApi ollamaApi, OllamaOptions defaultOptions,
 			@Nullable FunctionCallbackResolver functionCallbackResolver,
 			@Nullable List<FunctionCallback> toolFunctionCallbacks, ObservationRegistry observationRegistry,
 			ModelManagementOptions modelManagementOptions) {
-		super(functionCallbackResolver, defaultOptions, toolFunctionCallbacks);
+		// We do not pass the 'defaultOptions' to the AbstractToolSupport,
+		// because it modifies them. We are using ToolCallingManager instead,
+		// so we just pass empty options here.
+		super(functionCallbackResolver, OllamaOptions.builder().build(), toolFunctionCallbacks);
 		Assert.notNull(ollamaApi, "ollamaApi must not be null");
 		Assert.notNull(defaultOptions, "defaultOptions must not be null");
 		Assert.notNull(observationRegistry, "observationRegistry must not be null");
@@ -147,10 +150,9 @@ public OllamaChatModel(OllamaApi ollamaApi, OllamaOptions defaultOptions,
 
 	public OllamaChatModel(OllamaApi ollamaApi, OllamaOptions defaultOptions, ToolCallingManager toolCallingManager,
 			ObservationRegistry observationRegistry, ModelManagementOptions modelManagementOptions) {
-		// We do not pass the 'defaultOptions' to the AbstractToolSupport, because it
-		// modifies them.
-		// We are not using the AbstractToolSupport class in this path, so we just pass
-		// empty options.
+		// We do not pass the 'defaultOptions' to the AbstractToolSupport,
+		// because it modifies them. We are using ToolCallingManager instead,
+		// so we just pass empty options here.
 		super(null, OllamaOptions.builder().build(), List.of());
 		Assert.notNull(ollamaApi, "ollamaApi must not be null");
 		Assert.notNull(defaultOptions, "defaultOptions must not be null");
@@ -424,6 +426,8 @@ else if (prompt.getOptions() instanceof FunctionCallingOptions functionCallingOp
 			throw new IllegalArgumentException("model cannot be null or empty");
 		}
 
+		ToolCallingChatOptions.validateToolCallbacks(requestOptions.getToolCallbacks());
+
 		return new Prompt(prompt.getInstructions(), requestOptions);
 	}
 

models/spring-ai-openai/src/main/java/org/springframework/ai/openai/OpenAiChatModel.java

@@ -17,6 +17,7 @@
 package org.springframework.ai.openai;
 
 import java.util.ArrayList;
+import java.util.Arrays;
 import java.util.HashMap;
 import java.util.HashSet;
 import java.util.List;
@@ -31,12 +32,14 @@
 
 import org.springframework.ai.model.ModelOptionsUtils;
 import org.springframework.ai.model.function.FunctionCallback;
-import org.springframework.ai.model.function.FunctionCallingOptions;
+import org.springframework.ai.model.tool.ToolCallingChatOptions;
 import org.springframework.ai.openai.api.OpenAiApi;
 import org.springframework.ai.openai.api.OpenAiApi.ChatCompletionRequest.AudioParameters;
 import org.springframework.ai.openai.api.OpenAiApi.ChatCompletionRequest.StreamOptions;
 import org.springframework.ai.openai.api.OpenAiApi.ChatCompletionRequest.ToolChoiceBuilder;
 import org.springframework.ai.openai.api.ResponseFormat;
+import org.springframework.ai.tool.ToolCallback;
+import org.springframework.lang.Nullable;
 import org.springframework.util.Assert;
 
 /**
@@ -49,7 +52,7 @@
  * @since 0.8.0
  */
 @JsonInclude(Include.NON_NULL)
-public class OpenAiChatOptions implements FunctionCallingOptions {
+public class OpenAiChatOptions implements ToolCallingChatOptions {
 
 	// @formatter:off
 	/**
@@ -192,33 +195,22 @@ public class OpenAiChatOptions implements FunctionCallingOptions {
 	private @JsonProperty("reasoning_effort") String reasoningEffort;
 
 	/**
-	 * OpenAI Tool Function Callbacks to register with the ChatModel.
-	 * For Prompt Options the functionCallbacks are automatically enabled for the duration of the prompt execution.
-	 * For Default Options the functionCallbacks are registered but disabled by default. Use the enableFunctions to set the functions
-	 * from the registry to be used by the ChatModel chat completion requests.
+	 * Collection of {@link ToolCallback}s to be used for tool calling in the chat completion requests.
 	 */
 	@JsonIgnore
-	private List<FunctionCallback> functionCallbacks = new ArrayList<>();
+	private List<FunctionCallback> toolCallbacks = new ArrayList<>();
 
 	/**
-	 * List of functions, identified by their names, to configure for function calling in
-	 * the chat completion requests.
-	 * Functions with those names must exist in the functionCallbacks registry.
-	 * The {@link #functionCallbacks} from the PromptOptions are automatically enabled for the duration of the prompt execution.
-	 *
-	 * Note that function enabled with the default options are enabled for all chat completion requests. This could impact the token count and the billing.
-	 * If the functions is set in a prompt options, then the enabled functions are only active for the duration of this prompt execution.
+	 * Collection of tool names to be resolved at runtime and used for tool calling in the chat completion requests.
 	 */
 	@JsonIgnore
-	private Set<String> functions = new HashSet<>();
+	private Set<String> toolNames = new HashSet<>();
 
 	/**
-	 * If true, the Spring AI will not handle the function calls internally, but will proxy them to the client.
-	 * It is the client's responsibility to handle the function calls, dispatch them to the appropriate function, and return the results.
-	 * If false, the Spring AI will handle the function calls internally.
+	 * Whether to enable the tool execution lifecycle internally in ChatModel.
 	 */
 	@JsonIgnore
-	private Boolean proxyToolCalls;
+	private Boolean internalToolExecutionEnabled;
 
 	/**
 	 * Optional HTTP headers to be added to the chat completion request.
@@ -227,7 +219,7 @@ public class OpenAiChatOptions implements FunctionCallingOptions {
 	private Map<String, String> httpHeaders = new HashMap<>();
 
 	@JsonIgnore
-	private Map<String, Object> toolContext;
+	private Map<String, Object> toolContext = new HashMap<>();
 
 	// @formatter:on
 
@@ -258,10 +250,10 @@ public static OpenAiChatOptions fromOptions(OpenAiChatOptions fromOptions) {
 			.toolChoice(fromOptions.getToolChoice())
 			.user(fromOptions.getUser())
 			.parallelToolCalls(fromOptions.getParallelToolCalls())
-			.functionCallbacks(fromOptions.getFunctionCallbacks())
-			.functions(fromOptions.getFunctions())
+			.toolCallbacks(fromOptions.getFunctionCallbacks())
+			.toolNames(fromOptions.getFunctions())
 			.httpHeaders(fromOptions.getHttpHeaders())
-			.proxyToolCalls(fromOptions.getProxyToolCalls())
+			.internalToolExecutionEnabled(fromOptions.getProxyToolCalls())
 			.toolContext(fromOptions.getToolContext())
 			.store(fromOptions.getStore())
 			.metadata(fromOptions.getMetadata())
@@ -447,12 +439,16 @@ public void setToolChoice(Object toolChoice) {
 	}
 
 	@Override
+	@Deprecated
+	@JsonIgnore
 	public Boolean getProxyToolCalls() {
-		return this.proxyToolCalls;
+		return this.internalToolExecutionEnabled != null ? !this.internalToolExecutionEnabled : null;
 	}
 
+	@Deprecated
+	@JsonIgnore
 	public void setProxyToolCalls(Boolean proxyToolCalls) {
-		this.proxyToolCalls = proxyToolCalls;
+		this.internalToolExecutionEnabled = proxyToolCalls != null ? !proxyToolCalls : null;
 	}
 
 	public String getUser() {
@@ -472,22 +468,73 @@ public void setParallelToolCalls(Boolean parallelToolCalls) {
 	}
 
 	@Override
+	@JsonIgnore
+	public List<FunctionCallback> getToolCallbacks() {
+		return this.toolCallbacks;
+	}
+
+	@Override
+	@JsonIgnore
+	public void setToolCallbacks(List<FunctionCallback> toolCallbacks) {
+		Assert.notNull(toolCallbacks, "toolCallbacks cannot be null");
+		Assert.noNullElements(toolCallbacks, "toolCallbacks cannot contain null elements");
+		this.toolCallbacks = toolCallbacks;
+	}
+
+	@Override
+	@JsonIgnore
+	public Set<String> getToolNames() {
+		return this.toolNames;
+	}
+
+	@Override
+	@JsonIgnore
+	public void setToolNames(Set<String> toolNames) {
+		Assert.notNull(toolNames, "toolNames cannot be null");
+		Assert.noNullElements(toolNames, "toolNames cannot contain null elements");
+		toolNames.forEach(tool -> Assert.hasText(tool, "toolNames cannot contain empty elements"));
+		this.toolNames = toolNames;
+	}
+
+	@Override
+	@Nullable
+	@JsonIgnore
+	public Boolean isInternalToolExecutionEnabled() {
+		return internalToolExecutionEnabled;
+	}
+
+	@Override
+	@JsonIgnore
+	public void setInternalToolExecutionEnabled(@Nullable Boolean internalToolExecutionEnabled) {
+		this.internalToolExecutionEnabled = internalToolExecutionEnabled;
+	}
+
+	@Override
+	@Deprecated
+	@JsonIgnore
 	public List<FunctionCallback> getFunctionCallbacks() {
-		return this.functionCallbacks;
+		return this.getToolCallbacks();
 	}
 
 	@Override
+	@Deprecated
+	@JsonIgnore
 	public void setFunctionCallbacks(List<FunctionCallback> functionCallbacks) {
-		this.functionCallbacks = functionCallbacks;
+		this.setToolCallbacks(functionCallbacks);
 	}
 
 	@Override
+	@Deprecated
+	@JsonIgnore
 	public Set<String> getFunctions() {
-		return this.functions;
+		return this.getToolNames();
 	}
 
+	@Override
+	@Deprecated
+	@JsonIgnore
 	public void setFunctions(Set<String> functionNames) {
-		this.functions = functionNames;
+		this.setToolNames(functionNames);
 	}
 
 	public Map<String, String> getHttpHeaders() {
@@ -505,11 +552,13 @@ public Integer getTopK() {
 	}
 
 	@Override
+	@JsonIgnore
 	public Map<String, Object> getToolContext() {
 		return this.toolContext;
 	}
 
 	@Override
+	@JsonIgnore
 	public void setToolContext(Map<String, Object> toolContext) {
 		this.toolContext = toolContext;
 	}
@@ -548,9 +597,9 @@ public int hashCode() {
 		return Objects.hash(this.model, this.frequencyPenalty, this.logitBias, this.logprobs, this.topLogprobs,
 				this.maxTokens, this.maxCompletionTokens, this.n, this.presencePenalty, this.responseFormat,
 				this.streamOptions, this.seed, this.stop, this.temperature, this.topP, this.tools, this.toolChoice,
-				this.user, this.parallelToolCalls, this.functionCallbacks, this.functions, this.httpHeaders,
-				this.proxyToolCalls, this.toolContext, this.outputModalities, this.outputAudio, this.store,
-				this.metadata, this.reasoningEffort);
+				this.user, this.parallelToolCalls, this.toolCallbacks, this.toolNames, this.httpHeaders,
+				this.internalToolExecutionEnabled, this.toolContext, this.outputModalities, this.outputAudio,
+				this.store, this.metadata, this.reasoningEffort);
 	}
 
 	@Override
@@ -574,11 +623,11 @@ public boolean equals(Object o) {
 				&& Objects.equals(this.topP, other.topP) && Objects.equals(this.tools, other.tools)
 				&& Objects.equals(this.toolChoice, other.toolChoice) && Objects.equals(this.user, other.user)
 				&& Objects.equals(this.parallelToolCalls, other.parallelToolCalls)
-				&& Objects.equals(this.functionCallbacks, other.functionCallbacks)
-				&& Objects.equals(this.functions, other.functions)
+				&& Objects.equals(this.toolCallbacks, other.toolCallbacks)
+				&& Objects.equals(this.toolNames, other.toolNames)
 				&& Objects.equals(this.httpHeaders, other.httpHeaders)
 				&& Objects.equals(this.toolContext, other.toolContext)
-				&& Objects.equals(this.proxyToolCalls, other.proxyToolCalls)
+				&& Objects.equals(this.internalToolExecutionEnabled, other.internalToolExecutionEnabled)
 				&& Objects.equals(this.outputModalities, other.outputModalities)
 				&& Objects.equals(this.outputAudio, other.outputAudio) && Objects.equals(this.store, other.store)
 				&& Objects.equals(this.metadata, other.metadata)
@@ -712,25 +761,54 @@ public Builder parallelToolCalls(Boolean parallelToolCalls) {
 			return this;
 		}
 
-		public Builder functionCallbacks(List<FunctionCallback> functionCallbacks) {
-			this.options.functionCallbacks = functionCallbacks;
+		public Builder toolCallbacks(List<FunctionCallback> toolCallbacks) {
+			this.options.setToolCallbacks(toolCallbacks);
 			return this;
 		}
 
-		public Builder functions(Set<String> functionNames) {
-			Assert.notNull(functionNames, "Function names must not be null");
-			this.options.functions = functionNames;
+		public Builder toolCallbacks(FunctionCallback... toolCallbacks) {
+			Assert.notNull(toolCallbacks, "toolCallbacks cannot be null");
+			this.options.toolCallbacks.addAll(Arrays.asList(toolCallbacks));
 			return this;
 		}
 
-		public Builder function(String functionName) {
-			Assert.hasText(functionName, "Function name must not be empty");
-			this.options.functions.add(functionName);
+		public Builder toolNames(Set<String> toolNames) {
+			Assert.notNull(toolNames, "toolNames cannot be null");
+			this.options.setToolNames(toolNames);
+			return this;
+		}
+
+		public Builder toolNames(String... toolNames) {
+			Assert.notNull(toolNames, "toolNames cannot be null");
+			this.options.toolNames.addAll(Set.of(toolNames));
 			return this;
 		}
 
+		public Builder internalToolExecutionEnabled(@Nullable Boolean internalToolExecutionEnabled) {
+			this.options.setInternalToolExecutionEnabled(internalToolExecutionEnabled);
+			return this;
+		}
+
+		@Deprecated
+		public Builder functionCallbacks(List<FunctionCallback> functionCallbacks) {
+			return toolCallbacks(functionCallbacks);
+		}
+
+		@Deprecated
+		public Builder functions(Set<String> functionNames) {
+			return toolNames(functionNames);
+		}
+
+		@Deprecated
+		public Builder function(String functionName) {
+			return toolNames(functionName);
+		}
+
+		@Deprecated
 		public Builder proxyToolCalls(Boolean proxyToolCalls) {
-			this.options.proxyToolCalls = proxyToolCalls;
+			if (proxyToolCalls != null) {
+				this.options.setInternalToolExecutionEnabled(!proxyToolCalls);
+			}
 			return this;
 		}