minor improvements

Signed-off-by: Christian Tzolov <[email protected]>

Author: tzolov

models/spring-ai-anthropic/src/test/java/org/springframework/ai/anthropic/client/AnthropicChatClientIT.java

@@ -124,7 +124,7 @@ void listOutputConverterBean2() {
 
 		// @formatter:off
 		List<ActorsFilms> actorsFilms = ChatClient.create(this.chatModel).prompt()
-				.advisors(AdvisorParams.WITH_NATIVE_STRUCTURED_OUTPUT)
+				.advisors(AdvisorParams.ENABLE_NATIVE_STRUCTURED_OUTPUT)
 				.options(AnthropicChatOptions.builder()
 					.model(AnthropicApi.ChatModel.CLAUDE_SONNET_4_5)
 					.build())

models/spring-ai-openai/src/test/java/org/springframework/ai/openai/chat/client/OpenAiChatClientIT.java

@@ -200,7 +200,7 @@ void beanOutputConverterNativeStructuredOutput() {
 
 		// @formatter:off
 		ActorsFilms actorsFilms = ChatClient.create(this.chatModel).prompt()
-				.advisors(AdvisorParams.WITH_NATIVE_STRUCTURED_OUTPUT)
+				.advisors(AdvisorParams.ENABLE_NATIVE_STRUCTURED_OUTPUT)
 				.user("Generate the filmography for a random actor.")
 				.call()
 				.entity(ActorsFilms.class);
@@ -230,7 +230,7 @@ void beanOutputConverterRecordsNativeStructuredOutput() {
 
 		// @formatter:off
 		ActorsFilms actorsFilms = ChatClient.create(this.chatModel).prompt()
-				.advisors(AdvisorParams.WITH_NATIVE_STRUCTURED_OUTPUT)
+				.advisors(AdvisorParams.ENABLE_NATIVE_STRUCTURED_OUTPUT)
 				.user("Generate the filmography of 5 movies for Tom Hanks.")
 				.call()
 				.entity(ActorsFilms.class);

models/spring-ai-vertex-ai-gemini/src/test/java/org/springframework/ai/vertexai/gemini/VertexAiGeminiChatModelIT.java

@@ -243,7 +243,7 @@ void listOutputConverterBean2() {
 
 		// @formatter:off
 		List<ActorsFilmsRecord> actorsFilms = ChatClient.create(this.chatModel).prompt()
-				.advisors(AdvisorParams.WITH_NATIVE_STRUCTURED_OUTPUT)
+				.advisors(AdvisorParams.ENABLE_NATIVE_STRUCTURED_OUTPUT)
 				.user("Generate the filmography of 5 movies for Tom Hanks and Bill Murray.")
 				.call()
 				.entity(new ParameterizedTypeReference<>() {
@@ -259,7 +259,7 @@ void chatClientBeanOutputConverterRecords2() {
 		var chatClient = ChatClient.builder(this.chatModel).build();
 
 		ActorsFilmsRecord actorsFilms = chatClient.prompt("Generate the filmography of 5 movies for Tom Hanks.")
-			.advisors(AdvisorParams.WITH_NATIVE_STRUCTURED_OUTPUT)
+			.advisors(AdvisorParams.ENABLE_NATIVE_STRUCTURED_OUTPUT)
 			.call()
 			.entity(ActorsFilmsRecord.class);
 

spring-ai-client-chat/src/main/java/org/springframework/ai/chat/client/AdvisorParams.java

@@ -32,7 +32,7 @@ public final class AdvisorParams {
 	private AdvisorParams() {
 	}
 
-	public static final Consumer<ChatClient.AdvisorSpec> WITH_NATIVE_STRUCTURED_OUTPUT = a -> a
+	public static final Consumer<ChatClient.AdvisorSpec> ENABLE_NATIVE_STRUCTURED_OUTPUT = a -> a
 		.param(ChatClientAttributes.STRUCTURED_OUTPUT_NATIVE.getKey(), true);
 
 }

spring-ai-client-chat/src/main/java/org/springframework/ai/chat/client/DefaultChatClient.java

@@ -475,15 +475,20 @@ public <T> T entity(Class<T> type) {
 
 		@Nullable
 		private <T> T doSingleWithBeanOutputConverter(StructuredOutputConverter<T> outputConverter) {
-			if (outputConverter != null && StringUtils.hasText(outputConverter.getFormat())) {
+
+			if (StringUtils.hasText(outputConverter.getFormat())) {
+				// Used for default struectured output format support, based on prompt
+				// instructions.
 				this.request.context().put(ChatClientAttributes.OUTPUT_FORMAT.getKey(), outputConverter.getFormat());
+			}
+
+			if (this.request.context().containsKey(ChatClientAttributes.STRUCTURED_OUTPUT_NATIVE.getKey())
+					&& outputConverter instanceof BeanOutputConverter beanOutputConverter) {
+				// Used for native structured output support, e.g. AI model API shoudl
+				// provide structured output support.
+				this.request.context()
+					.put(ChatClientAttributes.STRUCTURED_OUTPUT_SCHEMA.getKey(), beanOutputConverter.getJsonSchema());
 
-				if (this.request.context().containsKey(ChatClientAttributes.STRUCTURED_OUTPUT_NATIVE.getKey())
-						&& outputConverter instanceof BeanOutputConverter beanOutputConverter) {
-					this.request.context()
-						.put(ChatClientAttributes.STRUCTURED_OUTPUT_SCHEMA.getKey(),
-								beanOutputConverter.getJsonSchema());
-				}
 			}
 
 			var chatResponse = doGetObservableChatClientResponse(this.request).chatResponse();

spring-ai-client-chat/src/main/java/org/springframework/ai/chat/client/advisor/ChatModelCallAdvisor.java

@@ -62,22 +62,23 @@ public ChatClientResponse adviseCall(ChatClientRequest chatClientRequest, CallAd
 	}
 
 	private static ChatClientRequest augmentWithFormatInstructions(ChatClientRequest chatClientRequest) {
+
 		String outputFormat = (String) chatClientRequest.context().get(ChatClientAttributes.OUTPUT_FORMAT.getKey());
 
-		if (!StringUtils.hasText(outputFormat)) {
+		String outputSchema = (String) chatClientRequest.context()
+			.get(ChatClientAttributes.STRUCTURED_OUTPUT_SCHEMA.getKey());
+
+		if (!StringUtils.hasText(outputFormat) && !StringUtils.hasText(outputSchema)) {
 			return chatClientRequest;
 		}
 
-		if (chatClientRequest.prompt().getOptions() instanceof StructuredOutputChatOptions structuredOutputChatOptions
-				&& chatClientRequest.context().containsKey(ChatClientAttributes.STRUCTURED_OUTPUT_NATIVE.getKey())) {
+		if (chatClientRequest.context().containsKey(ChatClientAttributes.STRUCTURED_OUTPUT_NATIVE.getKey())
+				&& StringUtils.hasText(outputSchema) && chatClientRequest.prompt()
+					.getOptions() instanceof StructuredOutputChatOptions structuredOutputChatOptions) {
 
-			String outputSchema = (String) chatClientRequest.context()
-				.get(ChatClientAttributes.STRUCTURED_OUTPUT_SCHEMA.getKey());
+			structuredOutputChatOptions.setOutputSchema(outputSchema);
 
-			if (StringUtils.hasText(outputSchema)) {
-				structuredOutputChatOptions.setOutputSchema(outputSchema);
-				return chatClientRequest;
-			}
+			return chatClientRequest;
 		}
 
 		Prompt augmentedPrompt = chatClientRequest.prompt()

spring-ai-client-chat/src/test/java/org/springframework/ai/chat/client/ChatClientNativeStructuredResponseTests.java

@@ -111,7 +111,7 @@ public void nativeEntityTest() {
 			.build()
 			.prompt()
 			.options(this.structuredOutputChatOptions)
-			.advisors(AdvisorParams.WITH_NATIVE_STRUCTURED_OUTPUT)
+			.advisors(AdvisorParams.ENABLE_NATIVE_STRUCTURED_OUTPUT)
 			.advisors(textCallAdvisor)
 			.user("Tell me about John")
 			.call()

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

@@ -285,13 +285,13 @@ List<ActorFilms> actorFilms = chatClient.prompt()
 
 ==== Native Structured Output
 
-As more AI models support structured output natively, you can take advantage of this feature by using the `AdvisorParams.WITH_NATIVE_STRUCTURED_OUTPUT` advisor parameter when calling the `ChatClient`.
+As more AI models support structured output natively, you can take advantage of this feature by using the `AdvisorParams.ENABLE_NATIVE_STRUCTURED_OUTPUT` advisor parameter when calling the `ChatClient`.
 You can use the `defaultAdvisors()` method on the `ChatClient.Builder` to set this parameter globally for all calls or set it per call as shown below:
 
 [source,java]
 ----
 ActorFilms actorFilms = chatClient.prompt()
-    .advisors(AdvisorParams.WITH_NATIVE_STRUCTURED_OUTPUT)
+    .advisors(AdvisorParams.ENABLE_NATIVE_STRUCTURED_OUTPUT)
     .user("Generate the filmography for a random actor.")
     .call()
     .entity(ActorFilms.class);

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/structured-output-converter.adoc

@@ -14,7 +14,7 @@ Generating structured outputs from Large Language Models (LLMs) using generic co
 
 Before the LLM call, the converter appends format instructions to the prompt, providing explicit guidance to the models on generating the desired output structure. These instructions act as a blueprint, shaping the model's response to conform to the specified format.
 
-NOTE: As more AI models natively support structured outputs, you can leverage this capability using the xref:api/chatclient.adoc#_native_structured_output[Native Structured Output] feature with `AdvisorParams.WITH_NATIVE_STRUCTURED_OUTPUT`. This approach uses the generated JSON schema directly with the model's native structured output API, eliminating the need for pre-prompt formatting instructions and providing more reliable results.
+NOTE: As more AI models natively support structured outputs, you can leverage this capability using the xref:api/chatclient.adoc#_native_structured_output[Native Structured Output] feature with `AdvisorParams.ENABLE_NATIVE_STRUCTURED_OUTPUT`. This approach uses the generated JSON schema directly with the model's native structured output API, eliminating the need for pre-prompt formatting instructions and providing more reliable results.
 
 After the LLM call, the converter takes the model's output text and transforms it into instances of the structured type. This conversion process involves parsing the raw text output and mapping it to the corresponding structured data representation, such as JSON, XML, or domain-specific data structures.
 
@@ -264,12 +264,12 @@ When using native structured output, the JSON schema generated by `BeanOutputCon
 
 === Using Native Structured Output
 
-To enable native structured output, use the `AdvisorParams.WITH_NATIVE_STRUCTURED_OUTPUT` parameter:
+To enable native structured output, use the `AdvisorParams.ENABLE_NATIVE_STRUCTURED_OUTPUT` parameter:
 
 [source,java]
 ----
 ActorsFilms actorsFilms = ChatClient.create(chatModel).prompt()
-    .advisors(AdvisorParams.WITH_NATIVE_STRUCTURED_OUTPUT)
+    .advisors(AdvisorParams.ENABLE_NATIVE_STRUCTURED_OUTPUT)
     .user("Generate the filmography for a random actor.")
     .call()
     .entity(ActorsFilms.class);
@@ -282,7 +282,7 @@ You can also set this globally using `defaultAdvisors()` on the `ChatClient.Buil
 @Bean
 ChatClient chatClient(ChatClient.Builder builder) {
     return builder
-        .defaultAdvisors(AdvisorParams.WITH_NATIVE_STRUCTURED_OUTPUT)
+        .defaultAdvisors(AdvisorParams.ENABLE_NATIVE_STRUCTURED_OUTPUT)
         .build();
 }
 ----