Add documentation

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

Author: tzolov

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

@@ -283,6 +283,23 @@ List<ActorFilms> actorFilms = chatClient.prompt()
     .entity(new ParameterizedTypeReference<List<ActorFilms>>() {});
 ----
 
+==== 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`.
+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)
+    .user("Generate the filmography for a random actor.")
+    .call()
+    .entity(ActorFilms.class);
+----
+
+NOTE: Some AI models such as OpenAI don't support arrays of objects natively.
+In such cases, you can use the Spring AI default structured output conversion.
+
 === Streaming Responses
 
 The `stream()` method lets you get an asynchronous response as shown below:

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

@@ -2,9 +2,6 @@
 
 = Structured Output Converter
 
-NOTE: As of 02.05.2024 the old `OutputParser`, `BeanOutputParser`, `ListOutputParser` and `MapOutputParser` classes are deprecated in favor of the new `StructuredOutputConverter`, `BeanOutputConverter`, `ListOutputConverter` and `MapOutputConverter` implementations.
-the latter are drop-in replacements for the former ones and provide the same functionality.   The reason for the change was primarily naming, as there isn't any parsing being done, but also have aligned with the Spring `org.springframework.core.convert.converter` package bringing in some improved functionality.
-
 The ability of LLMs to produce structured outputs is important for downstream applications that rely on reliably parsing output values.
 Developers want to quickly turn results from an AI model into data types, such as JSON, XML or Java classes, that can be passed to other application functions and methods.
 
@@ -17,6 +14,8 @@ 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.
+
 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.
 
 TIP: The `StructuredOutputConverter` is a best effort to convert the model output into a structured output.
@@ -253,22 +252,52 @@ Generation generation = this.chatModel.call(this.prompt).getResult();
 List<String> list = this.listOutputConverter.convert(this.generation.getOutput().getText());
 ----
 
-== Supported AI Models
+== Native Structured Output
+
+Many modern AI models now provide native support for structured output, which offers more reliable results compared to prompt-based formatting. Spring AI supports this through the xref:api/chatclient.adoc#_native_structured_output[Native Structured Output] feature.
+
+When using native structured output, the JSON schema generated by `BeanOutputConverter` is sent directly to the model's structured output API, eliminating the need for format instructions in the prompt. This approach provides:
+
+* **Higher reliability**: The model guarantees output conforming to the schema
+* **Cleaner prompts**: No need to append format instructions
+* **Better performance**: Models can optimize for structured output internally
+
+=== Using Native Structured Output
+
+To enable native structured output, use the `AdvisorParams.WITH_NATIVE_STRUCTURED_OUTPUT` parameter:
+
+[source,java]
+----
+ActorsFilms actorsFilms = ChatClient.create(chatModel).prompt()
+    .advisors(AdvisorParams.WITH_NATIVE_STRUCTURED_OUTPUT)
+    .user("Generate the filmography for a random actor.")
+    .call()
+    .entity(ActorsFilms.class);
+----
+
+You can also set this globally using `defaultAdvisors()` on the `ChatClient.Builder`:
+
+[source,java]
+----
+@Bean
+ChatClient chatClient(ChatClient.Builder builder) {
+    return builder
+        .defaultAdvisors(AdvisorParams.WITH_NATIVE_STRUCTURED_OUTPUT)
+        .build();
+}
+----
+
+=== Supported Models for Native Structured Output
+
+The following models currently support native structured output:
 
-The following AI Models have been tested to support List, Map and Bean structured outputs.
+* **OpenAI**: GPT-4o and later models with JSON Schema support
+* **Anthropic**: Claude 3.5 Sonnet and later models
+* **Vertex AI Gemini**: Gemini 1.5 Pro and later models
 
-[cols="2,5"]
-|====
-| Model | Integration Tests / Samples
-| xref:api/chat/openai-chat.adoc[OpenAI]  | link:https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-openai/src/test/java/org/springframework/ai/openai/chat/OpenAiChatModelIT.java[OpenAiChatModelIT]
-| xref:api/chat/anthropic-chat.adoc[Anthropic Claude 3] | link:https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-anthropic/src/test/java/org/springframework/ai/anthropic/AnthropicChatModelIT.java[AnthropicChatModelIT.java]
-| xref:api/chat/azure-openai-chat.adoc[Azure OpenAI] | link:https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-azure-openai/src/test/java/org/springframework/ai/azure/openai/AzureOpenAiChatModelIT.java[AzureOpenAiChatModelIT.java]
-| xref:api/chat/mistralai-chat.adoc[Mistral AI] | link:https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-mistral-ai/src/test/java/org/springframework/ai/mistralai/MistralAiChatModelIT.java[MistralAiChatModelIT.java]
-| xref:api/chat/ollama-chat.adoc[Ollama] | link:https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-ollama/src/test/java/org/springframework/ai/ollama/OllamaChatModelIT.java[OllamaChatModelIT.java]
-| xref:api/chat/vertexai-gemini-chat.adoc[Vertex AI Gemini] | link:https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-vertex-ai-gemini/src/test/java/org/springframework/ai/vertexai/gemini/VertexAiGeminiChatModelIT.java[VertexAiGeminiChatModelIT.java]
-|====
+NOTE: Some AI models, such as OpenAI, don't support arrays of objects natively at the top level. In such cases, you can use the Spring AI default structured output conversion (without the native structured output advisor).
 
-== Built-in JSON mode
+=== Built-in JSON mode
 
 Some AI Models provide dedicated configuration options to generate structured (usually JSON) output.