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)
@@ -280,4 +280,251 @@ void testFromOptions_webSearchOptions() {
 		assertThat(target.getWebSearchOptions().userLocation().approximate().timezone()).isEqualTo("UTC+8");
 	}
 
+	@Test
+	void testEqualsAndHashCode() {
+		OpenAiChatOptions options1 = OpenAiChatOptions.builder()
+			.model("test-model")
+			.temperature(0.7)
+			.maxTokens(100)
+			.build();
+
+		OpenAiChatOptions options2 = OpenAiChatOptions.builder()
+			.model("test-model")
+			.temperature(0.7)
+			.maxTokens(100)
+			.build();
+
+		OpenAiChatOptions options3 = OpenAiChatOptions.builder()
+			.model("different-model")
+			.temperature(0.7)
+			.maxTokens(100)
+			.build();
+
+		// Test equals
+		assertThat(options1).isEqualTo(options2);
+		assertThat(options1).isNotEqualTo(options3);
+		assertThat(options1).isNotEqualTo(null);
+		assertThat(options1).isEqualTo(options1);
+
+		// Test hashCode
+		assertThat(options1.hashCode()).isEqualTo(options2.hashCode());
+		assertThat(options1.hashCode()).isNotEqualTo(options3.hashCode());
+	}
+
+	@Test
+	void testBuilderWithNullValues() {
+		OpenAiChatOptions options = OpenAiChatOptions.builder()
+			.temperature(null)
+			.logitBias(null)
+			.stop(null)
+			.tools(null)
+			.metadata(null)
+			.build();
+
+		assertThat(options.getModel()).isNull();
+		assertThat(options.getTemperature()).isNull();
+		assertThat(options.getLogitBias()).isNull();
+		assertThat(options.getStop()).isNull();
+		assertThat(options.getTools()).isNull();
+		assertThat(options.getMetadata()).isNull();
+	}
+
+	@Test
+	void testBuilderChaining() {
+		OpenAiChatOptions.Builder builder = OpenAiChatOptions.builder();
+
+		OpenAiChatOptions.Builder result = builder.model("test-model").temperature(0.7).maxTokens(100);
+
+		assertThat(result).isSameAs(builder);
+
+		OpenAiChatOptions options = result.build();
+		assertThat(options.getModel()).isEqualTo("test-model");
+		assertThat(options.getTemperature()).isEqualTo(0.7);
+		assertThat(options.getMaxTokens()).isEqualTo(100);
+	}
+
+	@Test
+	void testNullAndEmptyCollections() {
+		OpenAiChatOptions options = new OpenAiChatOptions();
+
+		// Test setting null collections
+		options.setLogitBias(null);
+		options.setStop(null);
+		options.setTools(null);
+		options.setMetadata(null);
+		options.setOutputModalities(null);
+
+		assertThat(options.getLogitBias()).isNull();
+		assertThat(options.getStop()).isNull();
+		assertThat(options.getTools()).isNull();
+		assertThat(options.getMetadata()).isNull();
+		assertThat(options.getOutputModalities()).isNull();
+
+		// Test setting empty collections
+		options.setLogitBias(new HashMap<>());
+		options.setStop(new ArrayList<>());
+		options.setTools(new ArrayList<>());
+		options.setMetadata(new HashMap<>());
+		options.setOutputModalities(new ArrayList<>());
+
+		assertThat(options.getLogitBias()).isEmpty();
+		assertThat(options.getStop()).isEmpty();
+		assertThat(options.getTools()).isEmpty();
+		assertThat(options.getMetadata()).isEmpty();
+		assertThat(options.getOutputModalities()).isEmpty();
+	}
+
+	@Test
+	void testStreamUsageStreamOptionsInteraction() {
+		OpenAiChatOptions options = new OpenAiChatOptions();
+
+		// Initially false
+		assertThat(options.getStreamUsage()).isFalse();
+		assertThat(options.getStreamOptions()).isNull();
+
+		// Setting streamUsage to true should set streamOptions
+		options.setStreamUsage(true);
+		assertThat(options.getStreamUsage()).isTrue();
+		assertThat(options.getStreamOptions()).isEqualTo(StreamOptions.INCLUDE_USAGE);
+
+		// Setting streamUsage to false should clear streamOptions
+		options.setStreamUsage(false);
+		assertThat(options.getStreamUsage()).isFalse();
+		assertThat(options.getStreamOptions()).isNull();
+
+		// Setting streamOptions directly should update streamUsage
+		options.setStreamOptions(StreamOptions.INCLUDE_USAGE);
+		assertThat(options.getStreamUsage()).isTrue();
+		assertThat(options.getStreamOptions()).isEqualTo(StreamOptions.INCLUDE_USAGE);
+
+		// Setting streamOptions to null should set streamUsage to false
+		options.setStreamOptions(null);
+		assertThat(options.getStreamUsage()).isFalse();
+		assertThat(options.getStreamOptions()).isNull();
+	}
+
+	@Test
+	void testStopSequencesAlias() {
+		OpenAiChatOptions options = new OpenAiChatOptions();
+		List<String> stopSequences = List.of("stop1", "stop2");
+
+		// Setting stopSequences should also set stop
+		options.setStopSequences(stopSequences);
+		assertThat(options.getStopSequences()).isEqualTo(stopSequences);
+		assertThat(options.getStop()).isEqualTo(stopSequences);
+
+		// Setting stop should also update stopSequences
+		List<String> newStop = List.of("stop3", "stop4");
+		options.setStop(newStop);
+		assertThat(options.getStop()).isEqualTo(newStop);
+		assertThat(options.getStopSequences()).isEqualTo(newStop);
+	}
+
+	@Test
+	void testFromOptionsWithWebSearchOptionsNull() {
+		OpenAiChatOptions source = OpenAiChatOptions.builder()
+			.model("test-model")
+			.temperature(0.7)
+			.webSearchOptions(null)
+			.build();
+
+		OpenAiChatOptions result = OpenAiChatOptions.fromOptions(source);
+		assertThat(result.getModel()).isEqualTo("test-model");
+		assertThat(result.getTemperature()).isEqualTo(0.7);
+		assertThat(result.getWebSearchOptions()).isNull();
+	}
+
+	@Test
+	void testCopyChangeIndependence() {
+		OpenAiChatOptions original = OpenAiChatOptions.builder().model("original-model").temperature(0.5).build();
+
+		OpenAiChatOptions copied = original.copy();
+
+		// Modify original
+		original.setModel("modified-model");
+		original.setTemperature(0.9);
+
+		// Verify copy is unchanged
+		assertThat(copied.getModel()).isEqualTo("original-model");
+		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);
+	}
+
 }