Fixes #4983 - Add ThinkingLevel support in ThinkingConfig

  Add support for ThinkingLevel (LOW, HIGH, THINKING_LEVEL_UNSPECIFIED)
  to control the depth of reasoning tokens generated by Gemini models.

  - Create GoogleGenAiThinkingLevel enum for type-safe thinking level values
  - Add thinkingLevel field to GoogleGenAiChatOptions with builder support
  - Add mapping method to convert Spring AI enum to SDK ThinkingLevel.Known
  - Update createGeminiRequest() to include thinkingLevel in ThinkingConfig
  - Add comprehensive unit tests for options and request building
  - Add integration tests for thinkingLevel with Gemini 3 Pro Preview
  - Document changes
  - Document thinkingLevel/thinkingBudget mutual exclusivity
  - Add model compatibility table with endpoint requirements
  - Use global endpoint for Gemini 3 Pro Preview tests

Signed-off-by: ddobrin <ddobrin@google.com>
Signed-off-by: markpollack <mark.pollack@broadcom.com>

Author: ddobrin

models/spring-ai-google-genai/src/main/java/org/springframework/ai/google/genai/GoogleGenAiChatModel.java

@@ -40,6 +40,7 @@
 import com.google.genai.types.SafetySetting;
 import com.google.genai.types.Schema;
 import com.google.genai.types.ThinkingConfig;
+import com.google.genai.types.ThinkingLevel;
 import com.google.genai.types.Tool;
 import io.micrometer.observation.Observation;
 import io.micrometer.observation.ObservationRegistry;
@@ -73,6 +74,7 @@
 import org.springframework.ai.google.genai.cache.GoogleGenAiCachedContentService;
 import org.springframework.ai.google.genai.common.GoogleGenAiConstants;
 import org.springframework.ai.google.genai.common.GoogleGenAiSafetySetting;
+import org.springframework.ai.google.genai.common.GoogleGenAiThinkingLevel;
 import org.springframework.ai.google.genai.metadata.GoogleGenAiUsage;
 import org.springframework.ai.google.genai.schema.GoogleGenAiToolCallingManager;
 import org.springframework.ai.model.ChatModelDescription;
@@ -759,15 +761,19 @@ GeminiRequest createGeminiRequest(Prompt prompt) {
 			configBuilder.presencePenalty(requestOptions.getPresencePenalty().floatValue());
 		}
 
-		// Build thinking config if either thinkingBudget or includeThoughts is set
-		if (requestOptions.getThinkingBudget() != null || requestOptions.getIncludeThoughts() != null) {
+		// Build thinking config if any thinking option is set
+		if (requestOptions.getThinkingBudget() != null || requestOptions.getIncludeThoughts() != null
+				|| requestOptions.getThinkingLevel() != null) {
 			ThinkingConfig.Builder thinkingBuilder = ThinkingConfig.builder();
 			if (requestOptions.getThinkingBudget() != null) {
 				thinkingBuilder.thinkingBudget(requestOptions.getThinkingBudget());
 			}
 			if (requestOptions.getIncludeThoughts() != null) {
 				thinkingBuilder.includeThoughts(requestOptions.getIncludeThoughts());
 			}
+			if (requestOptions.getThinkingLevel() != null) {
+				thinkingBuilder.thinkingLevel(mapToGenAiThinkingLevel(requestOptions.getThinkingLevel()));
+			}
 			configBuilder.thinkingConfig(thinkingBuilder.build());
 		}
 
@@ -866,6 +872,14 @@ private static com.google.genai.types.HarmBlockThreshold mapToGenAiHarmBlockThre
 		};
 	}
 
+	private static ThinkingLevel mapToGenAiThinkingLevel(GoogleGenAiThinkingLevel level) {
+		return switch (level) {
+			case THINKING_LEVEL_UNSPECIFIED -> new ThinkingLevel(ThinkingLevel.Known.THINKING_LEVEL_UNSPECIFIED);
+			case LOW -> new ThinkingLevel(ThinkingLevel.Known.LOW);
+			case HIGH -> new ThinkingLevel(ThinkingLevel.Known.HIGH);
+		};
+	}
+
 	private List<Content> toGeminiContent(List<Message> instructions) {
 
 		List<Content> contents = instructions.stream()

models/spring-ai-google-genai/src/main/java/org/springframework/ai/google/genai/GoogleGenAiChatOptions.java

@@ -32,6 +32,7 @@
 
 import org.springframework.ai.google.genai.GoogleGenAiChatModel.ChatModel;
 import org.springframework.ai.google.genai.common.GoogleGenAiSafetySetting;
+import org.springframework.ai.google.genai.common.GoogleGenAiThinkingLevel;
 import org.springframework.ai.model.tool.StructuredOutputChatOptions;
 import org.springframework.ai.model.tool.ToolCallingChatOptions;
 import org.springframework.ai.tool.ToolCallback;
@@ -132,6 +133,13 @@ public class GoogleGenAiChatOptions implements ToolCallingChatOptions, Structure
 	 */
 	private @JsonProperty("includeThoughts") Boolean includeThoughts;
 
+	/**
+	 * Optional. The level of thinking tokens the model should generate.
+	 * LOW = minimal thinking, HIGH = extensive thinking.
+	 * This is part of the thinkingConfig in GenerationConfig.
+	 */
+	private @JsonProperty("thinkingLevel") GoogleGenAiThinkingLevel thinkingLevel;
+
 	/**
 	 * Optional. Whether to include extended usage metadata in responses.
 	 * When true, includes thinking tokens, cached content, tool-use tokens, and modality details.
@@ -226,6 +234,7 @@ public static GoogleGenAiChatOptions fromOptions(GoogleGenAiChatOptions fromOpti
 		options.setToolContext(fromOptions.getToolContext());
 		options.setThinkingBudget(fromOptions.getThinkingBudget());
 		options.setIncludeThoughts(fromOptions.getIncludeThoughts());
+		options.setThinkingLevel(fromOptions.getThinkingLevel());
 		options.setLabels(fromOptions.getLabels());
 		options.setIncludeExtendedUsageMetadata(fromOptions.getIncludeExtendedUsageMetadata());
 		options.setCachedContentName(fromOptions.getCachedContentName());
@@ -393,6 +402,14 @@ public void setIncludeThoughts(Boolean includeThoughts) {
 		this.includeThoughts = includeThoughts;
 	}
 
+	public GoogleGenAiThinkingLevel getThinkingLevel() {
+		return this.thinkingLevel;
+	}
+
+	public void setThinkingLevel(GoogleGenAiThinkingLevel thinkingLevel) {
+		this.thinkingLevel = thinkingLevel;
+	}
+
 	public Boolean getIncludeExtendedUsageMetadata() {
 		return this.includeExtendedUsageMetadata;
 	}
@@ -497,6 +514,7 @@ public boolean equals(Object o) {
 				&& Objects.equals(this.presencePenalty, that.presencePenalty)
 				&& Objects.equals(this.thinkingBudget, that.thinkingBudget)
 				&& Objects.equals(this.includeThoughts, that.includeThoughts)
+				&& this.thinkingLevel == that.thinkingLevel
 				&& Objects.equals(this.maxOutputTokens, that.maxOutputTokens) && Objects.equals(this.model, that.model)
 				&& Objects.equals(this.responseMimeType, that.responseMimeType)
 				&& Objects.equals(this.responseSchema, that.responseSchema)
@@ -511,21 +529,22 @@ public boolean equals(Object o) {
 	public int hashCode() {
 		return Objects.hash(this.stopSequences, this.temperature, this.topP, this.topK, this.candidateCount,
 				this.frequencyPenalty, this.presencePenalty, this.thinkingBudget, this.includeThoughts,
-				this.maxOutputTokens, this.model, this.responseMimeType, this.responseSchema, this.toolCallbacks,
-				this.toolNames, this.googleSearchRetrieval, this.safetySettings, this.internalToolExecutionEnabled,
-				this.toolContext, this.labels);
+				this.thinkingLevel, this.maxOutputTokens, this.model, this.responseMimeType, this.responseSchema,
+				this.toolCallbacks, this.toolNames, this.googleSearchRetrieval, this.safetySettings,
+				this.internalToolExecutionEnabled, this.toolContext, this.labels);
 	}
 
 	@Override
 	public String toString() {
 		return "GoogleGenAiChatOptions{" + "stopSequences=" + this.stopSequences + ", temperature=" + this.temperature
 				+ ", topP=" + this.topP + ", topK=" + this.topK + ", frequencyPenalty=" + this.frequencyPenalty
 				+ ", presencePenalty=" + this.presencePenalty + ", thinkingBudget=" + this.thinkingBudget
-				+ ", includeThoughts=" + this.includeThoughts + ", candidateCount=" + this.candidateCount
-				+ ", maxOutputTokens=" + this.maxOutputTokens + ", model='" + this.model + '\'' + ", responseMimeType='"
-				+ this.responseMimeType + '\'' + ", toolCallbacks=" + this.toolCallbacks + ", toolNames="
-				+ this.toolNames + ", googleSearchRetrieval=" + this.googleSearchRetrieval + ", safetySettings="
-				+ this.safetySettings + ", labels=" + this.labels + '}';
+				+ ", includeThoughts=" + this.includeThoughts + ", thinkingLevel=" + this.thinkingLevel
+				+ ", candidateCount=" + this.candidateCount + ", maxOutputTokens=" + this.maxOutputTokens + ", model='"
+				+ this.model + '\'' + ", responseMimeType='" + this.responseMimeType + '\'' + ", toolCallbacks="
+				+ this.toolCallbacks + ", toolNames=" + this.toolNames + ", googleSearchRetrieval="
+				+ this.googleSearchRetrieval + ", safetySettings=" + this.safetySettings + ", labels=" + this.labels
+				+ '}';
 	}
 
 	@Override
@@ -668,6 +687,11 @@ public Builder includeThoughts(Boolean includeThoughts) {
 			return this;
 		}
 
+		public Builder thinkingLevel(GoogleGenAiThinkingLevel thinkingLevel) {
+			this.options.setThinkingLevel(thinkingLevel);
+			return this;
+		}
+
 		public Builder includeExtendedUsageMetadata(Boolean includeExtendedUsageMetadata) {
 			this.options.setIncludeExtendedUsageMetadata(includeExtendedUsageMetadata);
 			return this;

models/spring-ai-google-genai/src/main/java/org/springframework/ai/google/genai/common/GoogleGenAiThinkingLevel.java

@@ -0,0 +1,58 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.ai.google.genai.common;
+
+/**
+ * Enum representing the level of thinking tokens the model should generate. This controls
+ * the depth of reasoning the model applies during generation.
+ *
+ * <p>
+ * <strong>Model Compatibility:</strong> This option is only supported by Gemini 3 Pro
+ * models. For Gemini 2.5 series and earlier models, use
+ * {@link org.springframework.ai.google.genai.GoogleGenAiChatOptions#getThinkingBudget()
+ * thinkingBudget} instead.
+ *
+ * <p>
+ * <strong>Important:</strong> {@code thinkingLevel} and {@code thinkingBudget} are
+ * mutually exclusive. You cannot use both in the same request - doing so will result in
+ * an API error.
+ *
+ * @author Dan Dobrin
+ * @since 1.1.0
+ * @see <a href="https://ai.google.dev/gemini-api/docs/thinking">Google GenAI Thinking
+ * documentation</a>
+ */
+public enum GoogleGenAiThinkingLevel {
+
+	/**
+	 * Unspecified thinking level. The model uses its default behavior.
+	 */
+	THINKING_LEVEL_UNSPECIFIED,
+
+	/**
+	 * Low thinking level. Minimal reasoning tokens are generated. Use for simple queries
+	 * where speed is preferred over deep analysis.
+	 */
+	LOW,
+
+	/**
+	 * High thinking level. Extensive reasoning tokens are generated. Use for complex
+	 * problems requiring deep analysis and step-by-step reasoning.
+	 */
+	HIGH
+
+}

models/spring-ai-google-genai/src/test/java/org/springframework/ai/google/genai/CreateGeminiRequestTests.java

@@ -33,6 +33,7 @@
 import org.springframework.ai.chat.prompt.Prompt;
 import org.springframework.ai.content.Media;
 import org.springframework.ai.google.genai.GoogleGenAiChatModel.GeminiRequest;
+import org.springframework.ai.google.genai.common.GoogleGenAiThinkingLevel;
 import org.springframework.ai.google.genai.tool.MockWeatherService;
 import org.springframework.ai.model.tool.ToolCallingChatOptions;
 import org.springframework.ai.model.tool.ToolCallingManager;
@@ -418,4 +419,105 @@ public void createRequestWithLabels() {
 		assertThat(request.config().labels().get()).containsEntry("env", "test");
 	}
 
+	@Test
+	public void createRequestWithThinkingLevel() {
+		var client = GoogleGenAiChatModel.builder()
+			.genAiClient(this.genAiClient)
+			.defaultOptions(GoogleGenAiChatOptions.builder()
+				.model("DEFAULT_MODEL")
+				.thinkingLevel(GoogleGenAiThinkingLevel.HIGH)
+				.build())
+			.build();
+
+		GeminiRequest request = client
+			.createGeminiRequest(client.buildRequestPrompt(new Prompt("Test message content")));
+
+		assertThat(request.contents()).hasSize(1);
+		assertThat(request.modelName()).isEqualTo("DEFAULT_MODEL");
+
+		// Verify thinkingConfig is present and contains thinkingLevel
+		assertThat(request.config().thinkingConfig()).isPresent();
+		assertThat(request.config().thinkingConfig().get().thinkingLevel()).isPresent();
+		assertThat(request.config().thinkingConfig().get().thinkingLevel().get().toString()).isEqualTo("HIGH");
+	}
+
+	@Test
+	public void createRequestWithThinkingLevelOverride() {
+		var client = GoogleGenAiChatModel.builder()
+			.genAiClient(this.genAiClient)
+			.defaultOptions(GoogleGenAiChatOptions.builder()
+				.model("DEFAULT_MODEL")
+				.thinkingLevel(GoogleGenAiThinkingLevel.LOW)
+				.build())
+			.build();
+
+		// Override default thinkingLevel with prompt-specific value
+		GeminiRequest request = client.createGeminiRequest(client.buildRequestPrompt(new Prompt("Test message content",
+				GoogleGenAiChatOptions.builder().thinkingLevel(GoogleGenAiThinkingLevel.HIGH).build())));
+
+		assertThat(request.config().thinkingConfig()).isPresent();
+		assertThat(request.config().thinkingConfig().get().thinkingLevel()).isPresent();
+		assertThat(request.config().thinkingConfig().get().thinkingLevel().get().toString()).isEqualTo("HIGH");
+	}
+
+	@Test
+	public void createRequestWithThinkingLevelAndBudgetCombined() {
+		var client = GoogleGenAiChatModel.builder()
+			.genAiClient(this.genAiClient)
+			.defaultOptions(GoogleGenAiChatOptions.builder()
+				.model("DEFAULT_MODEL")
+				.thinkingBudget(8192)
+				.thinkingLevel(GoogleGenAiThinkingLevel.HIGH)
+				.includeThoughts(true)
+				.build())
+			.build();
+
+		GeminiRequest request = client
+			.createGeminiRequest(client.buildRequestPrompt(new Prompt("Test message content")));
+
+		assertThat(request.config().thinkingConfig()).isPresent();
+		var thinkingConfig = request.config().thinkingConfig().get();
+		assertThat(thinkingConfig.thinkingBudget()).isPresent();
+		assertThat(thinkingConfig.thinkingBudget().get()).isEqualTo(8192);
+		assertThat(thinkingConfig.thinkingLevel()).isPresent();
+		assertThat(thinkingConfig.thinkingLevel().get().toString()).isEqualTo("HIGH");
+		assertThat(thinkingConfig.includeThoughts()).isPresent();
+		assertThat(thinkingConfig.includeThoughts().get()).isTrue();
+	}
+
+	@Test
+	public void createRequestWithNullThinkingLevel() {
+		var client = GoogleGenAiChatModel.builder()
+			.genAiClient(this.genAiClient)
+			.defaultOptions(GoogleGenAiChatOptions.builder().model("DEFAULT_MODEL").thinkingLevel(null).build())
+			.build();
+
+		GeminiRequest request = client
+			.createGeminiRequest(client.buildRequestPrompt(new Prompt("Test message content")));
+
+		// Verify thinkingConfig is not present when only thinkingLevel is null
+		assertThat(request.config().thinkingConfig()).isEmpty();
+	}
+
+	@Test
+	public void createRequestWithOnlyThinkingLevel() {
+		var client = GoogleGenAiChatModel.builder()
+			.genAiClient(this.genAiClient)
+			.defaultOptions(GoogleGenAiChatOptions.builder()
+				.model("DEFAULT_MODEL")
+				.thinkingLevel(GoogleGenAiThinkingLevel.LOW)
+				.build())
+			.build();
+
+		GeminiRequest request = client
+			.createGeminiRequest(client.buildRequestPrompt(new Prompt("Test message content")));
+
+		// Verify thinkingConfig is present when only thinkingLevel is set
+		assertThat(request.config().thinkingConfig()).isPresent();
+		assertThat(request.config().thinkingConfig().get().thinkingLevel()).isPresent();
+		assertThat(request.config().thinkingConfig().get().thinkingLevel().get().toString()).isEqualTo("LOW");
+		// Budget should not be present
+		assertThat(request.config().thinkingConfig().get().thinkingBudget()).isEmpty();
+	}
+
 }