Add mutual exclusivity validation for maxTokens and maxCompletionTokens in OpenAI ChatOptions

- Add SLF4J logger to OpenAiChatOptions class for validation warnings
- Implement 'last-set-wins' validation in builder methods for maxTokens() and maxCompletionTokens()
- Add javadoc with model-specific usage guidance:
  * maxTokens: Use for non-reasoning models (gpt-4o, gpt-3.5-turbo)
  * maxCompletionTokens: Required for reasoning models (o1, o3, o4-mini series)
- Add 8 unit tests covering mutual exclusivity scenarios:
  * Validation when setting conflicting parameters
  * Null value handling (no validation triggered)
  * Individual parameter setting
  * Direct setter behavior (no validation enforced)
- Fix existing unit tests that set both parameters simultaneously
- Update OpenAI documentation with detailed usage patterns and examples
- Add model compatibility table and builder validation examples

This ensures OpenAI API compatibility by preventing simultaneous use of
mutually exclusive token limit parameters, matching the robust validation
already implemented for Azure OpenAI integration.

Signed-off-by: Mark Pollack <[email protected]>

Author: markpollack

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

@@ -30,6 +30,9 @@
 import com.fasterxml.jackson.annotation.JsonInclude.Include;
 import com.fasterxml.jackson.annotation.JsonProperty;
 
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
 import org.springframework.ai.model.ModelOptionsUtils;
 import org.springframework.ai.model.tool.ToolCallingChatOptions;
 import org.springframework.ai.openai.api.OpenAiApi;
@@ -55,6 +58,8 @@
 @JsonInclude(Include.NON_NULL)
 public class OpenAiChatOptions implements ToolCallingChatOptions {
 
+	private static final Logger logger = LoggerFactory.getLogger(OpenAiChatOptions.class);
+
 	// @formatter:off
 	/**
 	 * ID of the model to use.
@@ -84,13 +89,31 @@ public class OpenAiChatOptions implements ToolCallingChatOptions {
 	 */
 	private @JsonProperty("top_logprobs") Integer topLogprobs;
 	/**
-	 * The maximum number of tokens to generate in the chat completion. The total length of input
-	 * tokens and generated tokens is limited by the model's context length.
+	 * The maximum number of tokens to generate in the chat completion.
+	 * The total length of input tokens and generated tokens is limited by the model's context length.
+	 *
+	 * <p><strong>Model-specific usage:</strong></p>
+	 * <ul>
+	 * <li><strong>Use for non-reasoning models</strong> (e.g., gpt-4o, gpt-3.5-turbo)</li>
+	 * <li><strong>Cannot be used with reasoning models</strong> (e.g., o1, o3, o4-mini series)</li>
+	 * </ul>
+	 *
+	 * <p><strong>Mutual exclusivity:</strong> This parameter cannot be used together with
+	 * {@link #maxCompletionTokens}. Setting both will result in an API error.</p>
 	 */
 	private @JsonProperty("max_tokens") Integer maxTokens;
 	/**
 	 * An upper bound for the number of tokens that can be generated for a completion,
 	 * including visible output tokens and reasoning tokens.
+	 *
+	 * <p><strong>Model-specific usage:</strong></p>
+	 * <ul>
+	 * <li><strong>Required for reasoning models</strong> (e.g., o1, o3, o4-mini series)</li>
+	 * <li><strong>Cannot be used with non-reasoning models</strong> (e.g., gpt-4o, gpt-3.5-turbo)</li>
+	 * </ul>
+	 *
+	 * <p><strong>Mutual exclusivity:</strong> This parameter cannot be used together with
+	 * {@link #maxTokens}. Setting both will result in an API error.</p>
 	 */
 	private @JsonProperty("max_completion_tokens") Integer maxCompletionTokens;
 	/**
@@ -678,12 +701,72 @@ public Builder topLogprobs(Integer topLogprobs) {
 			return this;
 		}
 
+		/**
+		 * Sets the maximum number of tokens to generate in the chat completion. The total
+		 * length of input tokens and generated tokens is limited by the model's context
+		 * length.
+		 *
+		 * <p>
+		 * <strong>Model-specific usage:</strong>
+		 * </p>
+		 * <ul>
+		 * <li><strong>Use for non-reasoning models</strong> (e.g., gpt-4o,
+		 * gpt-3.5-turbo)</li>
+		 * <li><strong>Cannot be used with reasoning models</strong> (e.g., o1, o3,
+		 * o4-mini series)</li>
+		 * </ul>
+		 *
+		 * <p>
+		 * <strong>Mutual exclusivity:</strong> This parameter cannot be used together
+		 * with {@link #maxCompletionTokens(Integer)}. If both are set, the last one set
+		 * will be used and the other will be cleared with a warning.
+		 * </p>
+		 * @param maxTokens the maximum number of tokens to generate, or null to unset
+		 * @return this builder instance
+		 */
 		public Builder maxTokens(Integer maxTokens) {
+			if (maxTokens != null && this.options.maxCompletionTokens != null) {
+				logger
+					.warn("Both maxTokens and maxCompletionTokens are set. OpenAI API does not support setting both parameters simultaneously. "
+							+ "The previously set maxCompletionTokens ({}) will be cleared and maxTokens ({}) will be used.",
+							this.options.maxCompletionTokens, maxTokens);
+				this.options.maxCompletionTokens = null;
+			}
 			this.options.maxTokens = maxTokens;
 			return this;
 		}
 
+		/**
+		 * Sets an upper bound for the number of tokens that can be generated for a
+		 * completion, including visible output tokens and reasoning tokens.
+		 *
+		 * <p>
+		 * <strong>Model-specific usage:</strong>
+		 * </p>
+		 * <ul>
+		 * <li><strong>Required for reasoning models</strong> (e.g., o1, o3, o4-mini
+		 * series)</li>
+		 * <li><strong>Cannot be used with non-reasoning models</strong> (e.g., gpt-4o,
+		 * gpt-3.5-turbo)</li>
+		 * </ul>
+		 *
+		 * <p>
+		 * <strong>Mutual exclusivity:</strong> This parameter cannot be used together
+		 * with {@link #maxTokens(Integer)}. If both are set, the last one set will be
+		 * used and the other will be cleared with a warning.
+		 * </p>
+		 * @param maxCompletionTokens the maximum number of completion tokens to generate,
+		 * or null to unset
+		 * @return this builder instance
+		 */
 		public Builder maxCompletionTokens(Integer maxCompletionTokens) {
+			if (maxCompletionTokens != null && this.options.maxTokens != null) {
+				logger
+					.warn("Both maxTokens and maxCompletionTokens are set. OpenAI API does not support setting both parameters simultaneously. "
+							+ "The previously set maxTokens ({}) will be cleared and maxCompletionTokens ({}) will be used.",
+							this.options.maxTokens, maxCompletionTokens);
+				this.options.maxTokens = null;
+			}
 			this.options.maxCompletionTokens = maxCompletionTokens;
 			return this;
 		}

models/spring-ai-openai/src/test/java/org/springframework/ai/openai/OpenAiChatOptionsTests.java

@@ -91,7 +91,7 @@ void testBuilderWithAllFields() {
 					"streamOptions", "seed", "stop", "temperature", "topP", "tools", "toolChoice", "user",
 					"parallelToolCalls", "store", "metadata", "reasoningEffort", "internalToolExecutionEnabled",
 					"httpHeaders", "toolContext")
-			.containsExactly("test-model", 0.5, logitBias, true, 5, 100, 50, 2, outputModalities, outputAudio, 0.8,
+			.containsExactly("test-model", 0.5, logitBias, true, 5, null, 50, 2, outputModalities, outputAudio, 0.8,
 					responseFormat, streamOptions, 12345, stopSequences, 0.7, 0.9, tools, toolChoice, "test-user", true,
 					false, metadata, "medium", false, Map.of("header1", "value1"), toolContext);
 
@@ -120,8 +120,8 @@ void testCopy() {
 			.logitBias(logitBias)
 			.logprobs(true)
 			.topLogprobs(5)
-			.maxTokens(100)
-			.maxCompletionTokens(50)
+			.maxCompletionTokens(50) // Only set maxCompletionTokens to avoid validation
+										// conflict
 			.N(2)
 			.outputModalities(outputModalities)
 			.outputAudio(outputAudio)
@@ -449,4 +449,82 @@ void testCopyChangeIndependence() {
 		assertThat(copied.getTemperature()).isEqualTo(0.5);
 	}
 
+	@Test
+	void testMaxTokensMutualExclusivityValidation() {
+		// Test that setting maxTokens clears maxCompletionTokens
+		OpenAiChatOptions options = OpenAiChatOptions.builder()
+			.maxCompletionTokens(100)
+			.maxTokens(50) // This should clear maxCompletionTokens
+			.build();
+
+		assertThat(options.getMaxTokens()).isEqualTo(50);
+		assertThat(options.getMaxCompletionTokens()).isNull();
+	}
+
+	@Test
+	void testMaxCompletionTokensMutualExclusivityValidation() {
+		// Test that setting maxCompletionTokens clears maxTokens
+		OpenAiChatOptions options = OpenAiChatOptions.builder()
+			.maxTokens(50)
+			.maxCompletionTokens(100) // This should clear maxTokens
+			.build();
+
+		assertThat(options.getMaxTokens()).isNull();
+		assertThat(options.getMaxCompletionTokens()).isEqualTo(100);
+	}
+
+	@Test
+	void testMaxTokensWithNullDoesNotClearMaxCompletionTokens() {
+		// Test that setting maxTokens to null doesn't trigger validation
+		OpenAiChatOptions options = OpenAiChatOptions.builder()
+			.maxCompletionTokens(100)
+			.maxTokens(null) // This should not clear maxCompletionTokens
+			.build();
+
+		assertThat(options.getMaxTokens()).isNull();
+		assertThat(options.getMaxCompletionTokens()).isEqualTo(100);
+	}
+
+	@Test
+	void testMaxCompletionTokensWithNullDoesNotClearMaxTokens() {
+		// Test that setting maxCompletionTokens to null doesn't trigger validation
+		OpenAiChatOptions options = OpenAiChatOptions.builder()
+			.maxTokens(50)
+			.maxCompletionTokens(null) // This should not clear maxTokens
+			.build();
+
+		assertThat(options.getMaxTokens()).isEqualTo(50);
+		assertThat(options.getMaxCompletionTokens()).isNull();
+	}
+
+	@Test
+	void testBuilderCanSetOnlyMaxTokens() {
+		// Test that we can set only maxTokens without issues
+		OpenAiChatOptions options = OpenAiChatOptions.builder().maxTokens(100).build();
+
+		assertThat(options.getMaxTokens()).isEqualTo(100);
+		assertThat(options.getMaxCompletionTokens()).isNull();
+	}
+
+	@Test
+	void testBuilderCanSetOnlyMaxCompletionTokens() {
+		// Test that we can set only maxCompletionTokens without issues
+		OpenAiChatOptions options = OpenAiChatOptions.builder().maxCompletionTokens(150).build();
+
+		assertThat(options.getMaxTokens()).isNull();
+		assertThat(options.getMaxCompletionTokens()).isEqualTo(150);
+	}
+
+	@Test
+	void testSettersMutualExclusivityNotEnforced() {
+		// Test that direct setters do NOT enforce mutual exclusivity (only builder does)
+		OpenAiChatOptions options = new OpenAiChatOptions();
+		options.setMaxTokens(50);
+		options.setMaxCompletionTokens(100);
+
+		// Both should be set when using setters directly
+		assertThat(options.getMaxTokens()).isEqualTo(50);
+		assertThat(options.getMaxCompletionTokens()).isEqualTo(100);
+	}
+
 }

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/openai-chat.adoc

@@ -150,8 +150,8 @@ The prefix `spring.ai.openai.chat` is the property prefix that lets you configur
 | spring.ai.openai.chat.options.temperature | The sampling temperature to use that controls the apparent creativity of generated completions. Higher values will make output more random while lower values will make results more focused and deterministic. It is not recommended to modify `temperature` and `top_p` for the same completions request as the interaction of these two settings is difficult to predict. | 0.8
 | spring.ai.openai.chat.options.frequencyPenalty | Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. | 0.0f
 | spring.ai.openai.chat.options.logitBias | Modify the likelihood of specified tokens appearing in the completion. | -
-| spring.ai.openai.chat.options.maxTokens | (Deprecated in favour of `maxCompletionTokens`) The maximum number of tokens to generate in the chat completion. The total length of input tokens and generated tokens is limited by the model's context length. | -
-| spring.ai.openai.chat.options.maxCompletionTokens | An upper bound for the number of tokens that can be generated for a completion, including visible output tokens and reasoning tokens. | -
+| spring.ai.openai.chat.options.maxTokens | The maximum number of tokens to generate in the chat completion. The total length of input tokens and generated tokens is limited by the model's context length. *Use for non-reasoning models* (e.g., gpt-4o, gpt-3.5-turbo). *Cannot be used with reasoning models* (e.g., o1, o3, o4-mini series). *Mutually exclusive with maxCompletionTokens* - setting both will result in an API error. | -
+| spring.ai.openai.chat.options.maxCompletionTokens | An upper bound for the number of tokens that can be generated for a completion, including visible output tokens and reasoning tokens. *Required for reasoning models* (e.g., o1, o3, o4-mini series). *Cannot be used with non-reasoning models* (e.g., gpt-4o, gpt-3.5-turbo). *Mutually exclusive with maxTokens* - setting both will result in an API error. | -
 | spring.ai.openai.chat.options.n | How many chat completion choices to generate for each input message. Note that you will be charged based on the number of generated tokens across all of the choices. Keep `n` as 1 to minimize costs. | 1
 | spring.ai.openai.chat.options.store | Whether to store the output of this chat completion request for use in our model | false
 | spring.ai.openai.chat.options.metadata | Developer-defined tags and values used for filtering completions in the chat completion dashboard | empty map
@@ -193,6 +193,62 @@ This is useful if you want to use different OpenAI accounts for different models
 
 TIP: All properties prefixed with `spring.ai.openai.chat.options` can be overridden at runtime by adding request-specific <<chat-options>> to the `Prompt` call.
 
+=== Token Limit Parameters: Model-Specific Usage
+
+OpenAI provides two mutually exclusive parameters for controlling token generation limits:
+
+[cols="2,3,3", stripes=even]
+|====
+| Parameter | Use Case | Compatible Models
+
+| `maxTokens` | Non-reasoning models | gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-3.5-turbo
+| `maxCompletionTokens` | Reasoning models | o1, o1-mini, o1-preview, o3, o4-mini series
+|====
+
+IMPORTANT: These parameters are **mutually exclusive**. Setting both will result in an API error from OpenAI.
+
+==== Usage Examples
+
+**For non-reasoning models (gpt-4o, gpt-3.5-turbo):**
+[source,java]
+----
+ChatResponse response = chatModel.call(
+    new Prompt(
+        "Explain quantum computing in simple terms.",
+        OpenAiChatOptions.builder()
+            .model("gpt-4o")
+            .maxTokens(150)  // Use maxTokens for non-reasoning models
+        .build()
+    ));
+----
+
+**For reasoning models (o1, o3 series):**
+[source,java]
+----
+ChatResponse response = chatModel.call(
+    new Prompt(
+        "Solve this complex math problem step by step: ...",
+        OpenAiChatOptions.builder()
+            .model("o1-preview")
+            .maxCompletionTokens(1000)  // Use maxCompletionTokens for reasoning models
+        .build()
+    ));
+----
+
+**Builder Pattern Validation:**
+The OpenAI ChatOptions builder automatically enforces mutual exclusivity with a "last-set-wins" approach:
+
+[source,java]
+----
+// This will automatically clear maxTokens and use maxCompletionTokens
+OpenAiChatOptions options = OpenAiChatOptions.builder()
+    .maxTokens(100)           // Set first
+    .maxCompletionTokens(200) // This clears maxTokens and logs a warning
+    .build();
+
+// Result: maxTokens = null, maxCompletionTokens = 200
+----
+
 == Runtime Options [[chat-options]]
 
 The https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-openai/src/main/java/org/springframework/ai/openai/OpenAiChatOptions.java[OpenAiChatOptions.java] class provides model configurations such as the model to use, the temperature, the frequency penalty, etc.