Spring AI

https://github.com/spring-projects/spring-ai
Admin
Spring AI provides a Spring-friendly API and abstractions for developing AI applications, connecting...
Tokens:663,795
Snippets:5,110
Trust Score:-
License:Apache-2.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### Example format instructions for JSON output

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/structured-output/converters.adoc

Example formatting instructions that a FormatProvider might return. These instructions are appended to the user input to guide the model to produce JSON output matching a specified Java class.

```text
  Your response should be in JSON format.
  The data structure for the JSON should match this Java class: java.util.HashMap
  Do not include any explanations, only provide a RFC8259 compliant JSON response following this format without deviation.
```

--------------------------------

### Sample Output

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/mcp/mcp-annotations-examples.adoc

Example console output when running the MCP client.

```text
> USER: What is the weather in Amsterdam right now?
Please incorporate all creative responses from all LLM providers.
After the other providers add a poem that synthesizes the poems from all the other providers.

> ASSISTANT:
OpenAI poem about the weather:
**Amsterdam's Winter Whisper**
*Temperature: 4.2°C*

In Amsterdam's embrace, where canals reflect the sky,
A gentle chill of 4.2 degrees drifts by...

Anthropic poem about the weather:
**Canal-Side Contemplation**
*Current conditions: 4.2°C*

Along the waterways where bicycles rest,
The winter air puts Amsterdam to test...

Weather Data:
{
  "current": {
    "time": "2025-01-23T11:00",
    "interval": 900,
    "temperature_2m": 4.2
  }
}
```

--------------------------------

### ci-alert-config.json example

Source: https://github.com/spring-projects/spring-ai/blob/main/src/ecosystem-ci/README.md

Example configuration for the dashboard. Each dependency requires an 'owner' and 'repo'. The 'tracked_branch' setting (default: main) determines the branch monitored.

```json
{
  "dependencies": [
    { "owner": "org-name", "repo": "repo-name" },
    ...
  ]
}
```

--------------------------------

### Simple MCP Server Tool Example

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/mcp/mcp-server-boot-starter-docs.adoc

A simple example of an MCP server component using the @McpTool annotation to expose a calculator tool.

```java
@Component
public class CalculatorTools {

```

--------------------------------

### Example Video Response

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/bedrock-converse.adoc

Example output from the video input, showing the model's description of the video content.

```text
The video shows a group of baby chickens, also known as chicks, huddled together on a surface
...
```

--------------------------------

### Basic OAuth 2.0 Setup - application.properties

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/mcp/mcp-security.adoc

Enable the MCP server in your application.properties file.

```properties
spring.ai.mcp.server.name=my-cool-mcp-server
```

--------------------------------

### Simple PromptTemplate example

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/prompt.adoc

Creates a prompt with placeholders for adjective and topic, then calls the chat model.

```java
PromptTemplate promptTemplate = new PromptTemplate("Tell me a {adjective} joke about {topic}");

Prompt prompt = promptTemplate.create(Map.of("adjective", adjective, "topic", topic));

return chatModel.call(prompt).getResult();
```

--------------------------------

### Start Milvus with Docker Compose

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/milvus.adoc

Run from the `src/test/resources/` folder to start the Milvus environment. Connects to the vector store at http://localhost:19530 and management UI at http://localhost:9001 (user: minioadmin, pass: minioadmin).

```bash
docker-compose up
```

--------------------------------

### Complete example of extended usage

Source: https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-google-genai/README.md

A complete example demonstrating how to access extended usage metadata, including basic token counts, thinking tokens, cached tokens, tool-use tokens, modality breakdowns, traffic type, and native SDK object.

```java
@Component
public class ExtendedUsageExample {

    private final GoogleGenAiChatModel chatModel;

    public void demonstrateExtendedUsage() {
        Prompt prompt = new Prompt("Analyze this complex multi-modal request");
        ChatResponse response = chatModel.call(prompt);

        // Cast to GoogleGenAiUsage for extended metadata
        GoogleGenAiUsage usage = (GoogleGenAiUsage) response.getMetadata().getUsage();

        // Basic token counts (standard Usage interface)
        System.out.println("Prompt tokens: " + usage.getPromptTokens());
        System.out.println("Completion tokens: " + usage.getCompletionTokens());
        System.out.println("Total tokens: " + usage.getTotalTokens());

        // Extended metadata (Google GenAI specific)
        System.out.println("Thinking tokens: " + usage.getThoughtsTokenCount());
        System.out.println("Cached tokens: " + usage.getCachedContentTokenCount());
        System.out.println("Tool-use tokens: " + usage.getToolUsePromptTokenCount());

        // Modality breakdowns
        if (usage.getPromptTokensDetails() != null) {
            usage.getPromptTokensDetails().forEach(detail ->
                System.out.println("  " + detail.getModality() + ": " + detail.getTokenCount())
            );
        }

        // Traffic type
        System.out.println("Traffic type: " + usage.getTrafficType());

        // Access native SDK object for any additional metadata
        GenerateContentResponseUsageMetadata nativeUsage =
            (GenerateContentResponseUsageMetadata) usage.getNativeUsage();
    }
}
```

--------------------------------

### vLLM server configuration example

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/openai-chat.adoc

Example properties for using vLLM with a Llama model. Includes vLLM-specific sampling parameters like `top_k`, `top_p`, `repetition_penalty`, and `min_p`.

```properties
spring.ai.openai.base-url=http://localhost:8000
spring.ai.openai.chat.model=meta-llama/Llama-3-8B-Instruct
spring.ai.openai.chat.extra-body.top_k=40
spring.ai.openai.chat.extra-body.top_p=0.95
spring.ai.openai.chat.extra-body.repetition_penalty=1.05
spring.ai.openai.chat.extra-body.min_p=0.05

```

--------------------------------

### Prompt Caching: Cost Calculation Example

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/bedrock-converse.adoc

Illustrates the cost savings of prompt caching with a concrete example. It shows the token costs for 5 requests with and without caching, resulting in a 65% cost reduction.

```java
// System prompt: 2000 tokens
// User question: 50 tokens

// Without caching (5 requests):
// Cost: 5 × (2000 + 50) = 10,250 tokens at base rate

// With caching (5 requests):
// Request 1: 2000 tokens × 1.25 (cache write) + 50 = 2,550 tokens
// Requests 2-5: 4 × (2000 × 0.10 (cache read) + 50) = 4 × 250 = 1,000 tokens
// Total: 2,550 + 1,000 = 3,550 tokens equivalent

// Savings: (10,250 - 3,550) / 10,250 = 65% cost reduction
```

--------------------------------

### Custom SimpleLoggerAdvisor example

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chatclient.adoc

Example of creating a custom SimpleLoggerAdvisor with custom request and response formatting. Be cautious about logging sensitive information in production.

```java
SimpleLoggerAdvisor customLogger = new SimpleLoggerAdvisor(
    request -> "Custom request: " + request.prompt().getUserMessage(),
    response -> "Custom response: " + response.getResult(),
    0
);
```

--------------------------------

### Create and use VertexAiMultimodalEmbeddingModel

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/vertexai-embeddings-multimodal.adoc

Java example showing how to create a VertexAiMultimodalEmbeddingModel with connection details and options, then use it to generate embeddings for documents and text. The example includes creating media objects and documents, and calling the model for responses.

```java
VertexAiEmbeddingConnectionDetails connectionDetails = 
    VertexAiEmbeddingConnectionDetails.builder()
        .projectId(System.getenv(<VERTEX_AI_GEMINI_PROJECT_ID>))
        .location(System.getenv(<VERTEX_AI_GEMINI_LOCATION>))
        .build();

VertexAiMultimodalEmbeddingOptions options = VertexAiMultimodalEmbeddingOptions.builder()
    .model(VertexAiMultimodalEmbeddingOptions.DEFAULT_MODEL_NAME)
    .build();

var embeddingModel = new VertexAiMultimodalEmbeddingModel(this.connectionDetails, this.options);

Media imageMedial = new Media(MimeTypeUtils.IMAGE_PNG, new ClassPathResource("/test.image.png"));
Media videoMedial = new Media(new MimeType("video", "mp4"), new ClassPathResource("/test.video.mp4"));

var document = new Document("Explain what do you see on this video?", List.of(this.imageMedial, this.videoMedial), Map.of());

EmbeddingResponse embeddingResponse = this.embeddingModel
	.embedForResponse(List.of("Hello World", "World is big and salvation is near"));

DocumentEmbeddingRequest embeddingRequest = new DocumentEmbeddingRequest(List.of(this.document),
        EmbeddingOptions.EMPTY);

EmbeddingResponse embeddingResponse = multiModelEmbeddingModel.call(this.embeddingRequest);

assertThat(embeddingResponse.getResults()).hasSize(3);
```

--------------------------------

### Creating a Spring Boot Application with MCP Server

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/mcp/mcp-streamable-http-server-boot-starter-docs.adoc

Example of defining a tool service and registering it as an MCP tool callback provider.

```APIDOC
## Creating a Spring Boot Application with MCP Server

### Description
Example of defining a tool service and registering it as an MCP tool callback provider.

### Components
- **WeatherService** - A Spring service that exposes a tool method annotated with `@Tool`.
- **McpServerApplication** - The main Spring Boot application class.
- **weatherTools** - A `@Bean` method that creates a `ToolCallbackProvider` from the `WeatherService`.

### Tool Method
- **getWeather(String cityName)** - Returns weather information for the given city.

### Example Code
```java
@Service
public class WeatherService {

    @Tool(description = "Get weather information by city name")
    public String getWeather(String cityName) {
        // Implementation
    }
}

@SpringBootApplication
public class McpServerApplication {

    private static final Logger logger = LoggerFactory.getLogger(McpServerApplication.class);

    public static void main(String[] args) {
        SpringApplication.run(McpServerApplication.class, args);
    }

	@Bean
	public ToolCallbackProvider weatherTools(WeatherService weatherService) {
		return MethodToolCallbackProvider.builder().toolObjects(weatherService).build();
	}
}
```

### Notes
- The auto-configuration will automatically register the tool callbacks as MCP tools.
- You can have multiple beans producing ToolCallbacks, and the auto-configuration will merge them.
```

--------------------------------

### Client Application Setup

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/mcp/mcp-annotations-examples.adoc

Registers MCP tools and handlers in the client application using @SpringBootApplication and CommandLineRunner.

```java
@SpringBootApplication
public class McpClientApplication {

    public static void main(String[] args) {
        SpringApplication.run(McpClientApplication.class, args).close();
    }

    @Bean
    public CommandLineRunner predefinedQuestions(OpenAiChatModel openAiChatModel,
            ToolCallbackProvider mcpToolProvider) {

        return args -> {

            ChatClient chatClient = ChatClient.builder(openAiChatModel)
                    .defaultTools(mcpToolProvider)
                    .build();

            String userQuestion = """
                    What is the weather in Amsterdam right now?
                    Please incorporate all creative responses from all LLM providers.
                    After the other providers add a poem that synthesizes the poems from all the other providers.
                    """;
```

--------------------------------

### Instantiating a container with ClassPathXmlApplicationContext (Java)

Source: https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-openai/src/test/resources/text_source.txt

Java example of creating an ApplicationContext by passing resource strings to the ClassPathXmlApplicationContext constructor.

```java
ApplicationContext context = new ClassPathXmlApplicationContext("services.xml",
"daos.xml");
```

--------------------------------

### Chat prefix completion example with DeepSeekChatModel

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/deepseek-chat.adoc

Complete Java example for chat prefix completion. Sets the assistant prefix to force Python code output and uses stop sequences to prevent extra explanations. Requires the last message to be a DeepSeekAssistantMessage.

```java
@RestController
public class CodeGenerateController {

    private final DeepSeekChatModel chatModel;

    @Autowired
    public ChatController(DeepSeekChatModel chatModel) {
        this.chatModel = chatModel;
    }

    @GetMapping("/ai/generatePythonCode")
    public String generate(@RequestParam(value = "message", defaultValue = "Please write quick sort code") String message) {
		UserMessage userMessage = new UserMessage(message);
		Message assistantMessage = DeepSeekAssistantMessage.builder().content("```python\n").prefix(true).build();
		Prompt prompt = new Prompt(List.of(userMessage, assistantMessage), ChatOptions.builder().stopSequences(List.of("```")).build());
		ChatResponse response = chatModel.call(prompt);
		return response.getResult().getOutput().getText();
    }
}
```

--------------------------------

### Auto-wire and use Chroma VectorStore

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/chroma.adoc

Java example showing how to autowire the VectorStore, create documents with metadata, add them to the store, and perform a similarity search with a query and topK parameter.

```java
@Autowired VectorStore vectorStore;

// ...

List <Document> documents = List.of(
    new Document("Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!!", Map.of("meta1", "meta1")),
    new Document("The World is Big and Salvation Lurks Around the Corner"),
    new Document("You walk forward facing the past and you turn back toward the future.", Map.of("meta2", "meta2")));

// Add the documents
vectorStore.add(documents);

// Retrieve documents similar to a query
List<Document> results = this.vectorStore.similaritySearch(SearchRequest.builder().query("Spring").topK(5).build());
```

--------------------------------

### Portable filter expression example

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/mongodb.adoc

Example of a portable filter expression that gets converted to MongoDB Atlas filter format.

```sql
author in ['john', 'jill'] && article_type == 'blog'
```

--------------------------------

### Portable filter expression

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/azure.adoc

Example of a portable filter expression that gets converted to OData.

```sql
country in ['UK', 'NL'] && year >= 2020
```

--------------------------------

### JsonReader JSON Pointer usage example

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/etl-pipeline.adoc

Example of using the get method with a JSON Pointer to extract a specific element from a JSON document. The JsonReader is configured with 'description' as the key to use.

```java
JsonReader jsonReader = new JsonReader(resource, "description");
List<Document> documents = this.jsonReader.get("/store/books/0");
```

--------------------------------

### SystemPromptTemplate example with user and system messages

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/prompt.adoc

Builds a prompt with user and system messages, using SystemPromptTemplate to create a system message with placeholders.

```java
String userText = """
    Tell me about three famous pirates from the Golden Age of Piracy and why they did.
    Write at least a sentence for each pirate.
    """;

Message userMessage = new UserMessage(userText);

String systemText = """
  You are a helpful AI assistant that helps people find information.
  Your name is {name}
  You should reply to the user's request with your name and also in the style of a {voice}.
  """;

SystemPromptTemplate systemPromptTemplate = new SystemPromptTemplate(systemText);
Message systemMessage = systemPromptTemplate.createMessage(Map.of("name", name, "voice", voice));

Prompt prompt = new Prompt(List.of(userMessage, systemMessage));

List<Generation> response = chatModel.call(prompt).getResults();
```

--------------------------------

### Manual Configuration: Create OpenAiAudioSpeechModel and call

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/audio/speech/openai-speech.adoc

Shows how to create an OpenAiAudioApi with an API key, build an OpenAiAudioSpeechModel, set speech options, and call the model. Also demonstrates accessing response metadata and output bytes.

```java
var openAiAudioApi = new OpenAiAudioApi()
    .apiKey(System.getenv("OPENAI_API_KEY"))
    .build();

var openAiAudioSpeechModel = new OpenAiAudioSpeechModel(openAiAudioApi);

var speechOptions = OpenAiAudioSpeechOptions.builder()
    .responseFormat(OpenAiAudioApi.SpeechRequest.AudioResponseFormat.MP3)
    .speed(1.0)
    .model(OpenAiAudioApi.TtsModel.GPT_4_O_MINI_TTS.value)
    .build();

var speechPrompt = new TextToSpeechPrompt("Hello, this is a text-to-speech example.", speechOptions);
TextToSpeechResponse response = openAiAudioSpeechModel.call(speechPrompt);

// Accessing metadata (rate limit info)
OpenAiAudioSpeechResponseMetadata metadata = (OpenAiAudioSpeechResponseMetadata) response.getMetadata();

byte[] responseAsBytes = response.getResult().getOutput();
```

--------------------------------

### Retrieve cached content with GoogleGenAiCachedContentService

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/google-genai-chat.adoc

Demonstrates retrieving cached content by its name using the GoogleGenAiCachedContentService. The example shows the get method call.

```java
// Retrieve cached content
GoogleGenAiCachedContent content = cachedContentService.get(cacheName);
```

--------------------------------

### Subclass Example: MyAuditingToolCallingAdvisor

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/tools/tool-calling-advisor.adoc

A concrete example of a ToolCallingAdvisor subclass that overrides doInitializeLoop and doInitializeLoopStream to index the tool set at session start and augment the system message, and doBeforeCall and doBeforeStream to inject only the tools discovered so far. The rest of the loop is inherited from the base class.

```java
public class MyAuditingToolCallingAdvisor extends ToolCallingAdvisor {

    private final AuditService audit;


```

--------------------------------

### Manual configuration: create ElevenLabsApi and model

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/audio/speech/elevenlabs-speech.adoc

Configure how to create an ElevenLabsTextToSpeechModel with default options.

```java
ElevenLabsApi elevenLabsApi = ElevenLabsApi.builder()
		.apiKey(System.getenv("ELEVEN_LABS_API_KEY"))
		.build();

ElevenLabsTextToSpeechModel elevenLabsTextToSpeechModel = ElevenLabsTextToSpeechModel.builder()
	.elevenLabsApi(elevenLabsApi)
	.options(ElevenLabsTextToSpeechOptions.builder()
		.model("eleven_turbo_v2_5")
		.voiceId("your_voice_id") // e.g. "9BWtsMINqrJLrRacOk9x"
		.outputFormat("mp3_44100_128")
		.build())
	.build();

// The call will use the default options configured above.
TextToSpeechPrompt speechPrompt = new TextToSpeechPrompt("Hello, this is a text-to-speech example.");
TextToSpeechResponse response = elevenLTextToSpeechModel.call(speechPrompt);

byte[] responseAsBytes = response.getResult().getOutput();

```

--------------------------------

### SYSTEM_AND_TOOLS cache strategy example

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/bedrock-converse.adoc

Shows two requests using the SYSTEM_AND_TOOLS strategy. The first request creates both caches. The second request changes only the system prompt while keeping the same tools, resulting in a tools cache hit and a system cache miss.

```java
// Request 1: Cache both tools and system
ChatResponse r1 = chatModel.call(
    new Prompt(
        List.of(new SystemMessage("System prompt"), new UserMessage("Question")),
        BedrockChatOptions.builder()
            .cacheOptions(BedrockCacheOptions.builder()
                .strategy(BedrockCacheStrategy.SYSTEM_AND_TOOLS)
                .build())
            .toolCallbacks(tools)
            .build()
    )
);
// Result: Both caches created

// Request 2: Change only system prompt (tools same)
ChatResponse r2 = chatModel.call(
    new Prompt(
        List.of(new SystemMessage("DIFFERENT system prompt"), new UserMessage("Question")),
        BedrockChatOptions.builder()
            .cacheOptions(BedrockCacheOptions.builder()
                .strategy(BedrockCacheStrategy.SYSTEM_AND_TOOLS)
                .build())
            .toolCallbacks(tools) // SAME tools
            .build()
    )
);
// Result: Tools cache HIT (reused), system cache MISS (recreated)
```

--------------------------------

### Starter dependency for Google GenAI

Source: https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-google-genai/README.md

Add the Spring AI Google GenAI starter dependency to your Maven project to get started with the chat model.

```xml
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-google-genai</artifactId>
</dependency>
```

--------------------------------

### Maven starter for Spring Boot

Source: https://github.com/spring-projects/spring-ai/blob/main/vector-stores/spring-ai-redis-semantic-cache/README.md

Use this starter dependency for Spring Boot applications to get auto-configuration for the Redis semantic cache.

```xml
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-vector-store-redis-semantic-cache</artifactId>
</dependency>
```

--------------------------------

### TextReader splitting with TokenTextSplitter

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/etl-pipeline.adoc

Shows how to split the text content read by TextReader into smaller chunks using TokenTextSplitter. The example uses the get() method to retrieve documents.

```java
List<Document> documents = textReader.get();
List<Document> splitDocuments = TokenTextSplitter.builder().build().apply(this.documents);
```

--------------------------------

### Kotlin: Define MathReasoning data class and use BeanOutputConverter

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/openai-chat.adoc

Kotlin version of the structured output example. Uses a data class with @get:JsonProperty annotations and BeanOutputConverter to handle JSON schema conversion.

```kotlin
data class MathReasoning(
	val steps: Steps,
	@get:JsonProperty(value = "final_answer") val finalAnswer: String) {

	data class Steps(val items: Array<Items>) {

		data class Items(
			val explanation: String,
			val output: String)
	}
}
```

```kotlin
val outputConverter = BeanOutputConverter(MathReasoning::class.java)

val jsonSchema = outputConverter.jsonSchema;

val prompt = Prompt("how can I solve 8x + 7 = -23",
	OpenAiChatOptions.builder()
		.model(ChatModel.GPT_4_O_MINI)
		.responseFormat(ResponseFormat(ResponseFormat.Type.JSON_SCHEMA, jsonSchema))
		.build())

val response = openAiChatModel.call(prompt)
val content = response.getResult().getOutput().getText()

val mathReasoning = outputConverter.convert(content)
```

--------------------------------

### Progress Token Null Checks

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/mcp/mcp-annotations-special-params.adoc

Use @McpProgressToken to safely handle progress notifications, always checking for null before sending. The example sends a starting and a complete progress notification with the provided token, only when it is not null, and returns a completion message.

```java
@McpTool(name = "safe-progress", description = "Safe progress handling")
public String safeProgress(
        @McpProgressToken String progressToken,
        @McpToolParam(description = "Task", required = true) String task,
        McpSyncServerExchange exchange) {
    
    // Always check if progress token is available
    if (progressToken != null) {
        exchange.progressNotification(ProgressNotification.builder(progressToken, 0.0)
            .total(1.0).message("Starting").build());
    }

    // Perform work...

    if (progressToken != null) {
        exchange.progressNotification(ProgressNotification.builder(progressToken, 1.0)
            .total(1.0).message("Complete").build());
    }
    
    return "Task completed";
}
```

--------------------------------

### Complete prompt caching example with cost tracking

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/bedrock-converse.adoc

Shows a full workflow: first request creates a cache entry, second request reads from it. Demonstrates accessing cacheWriteInputTokens and cacheReadInputTokens from response metadata to verify cache behavior.

```java
// Create system content that will be reused multiple times
String largeSystemPrompt = "You are an expert software architect specializing in distributed systems...";
// (Ensure this is 1024+ tokens for cache effectiveness)

// First request - creates cache
ChatResponse firstResponse = chatModel.call(
    new Prompt(
        List.of(
            new SystemMessage(largeSystemPrompt),
            new UserMessage("What is microservices architecture?")
        ),
        BedrockChatOptions.builder()
            .model("us.anthropic.claude-haiku-4-5-20251001-v1:0")
            .cacheOptions(BedrockCacheOptions.builder()
                .strategy(BedrockCacheStrategy.SYSTEM_ONLY)
                .build())
            .maxTokens(500)
            .build()
    )
);

// Access cache-related token usage from metadata
Integer cacheWrite1 = (Integer) firstResponse.getMetadata()
    .getMetadata()
    .get("cacheWriteInputTokens");
Integer cacheRead1 = (Integer) firstResponse.getMetadata()
    .getMetadata()
    .get("cacheReadInputTokens");

System.out.println("Cache creation tokens: " + cacheWrite1);
System.out.println("Cache read tokens: " + cacheRead1);

// Second request with same system prompt - reads from cache
ChatResponse secondResponse = chatModel.call(
    new Prompt(
        List.of(
            new SystemMessage(largeSystemPrompt),  // Same prompt - cache hit
            new UserMessage("What are the benefits of event sourcing?")
        ),
        BedrockChatOptions.builder()
            .model("us.anthropic.claude-haiku-4-5-20251001-v1:0")
            .cacheOptions(BedrockCacheOptions.builder()
                .strategy(BedrockCacheStrategy.SYSTEM_ONLY)
                .build())
            .maxTokens(500)
            .build()
    )
);

Integer cacheWrite2 = (Integer) secondResponse.getMetadata()
    .getMetadata()
    .get("cacheWriteInputTokens");
Integer cacheRead2 = (Integer) secondResponse.getMetadata()
    .getMetadata()
    .get("cacheReadInputTokens");

System.out.println("Cache creation tokens: " + cacheWrite2); // Should be 0
System.out.println("Cache read tokens: " + cacheRead2);      // Should be > 0
```

--------------------------------

### Filter string examples

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs.adoc

Examples of SQL-like filter strings that can be passed to similaritySearch overloads.

```text
"country == 'BG'"
```

```text
"genre == 'drama' && year >= 2020"
```

```text
"genre in ['comedy', 'documentary', 'drama']"
```

--------------------------------

### Build the project with Maven

Source: https://github.com/spring-projects/spring-ai/blob/main/CONTRIBUTING.md

Run the standard Maven build from the root directory using the Maven wrapper.

```shell
./mvnw clean package
```

--------------------------------

### Unified Context Example

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/mcp/mcp-annotations-server.adoc

Shows how to access root directories in stateful mode using the unified context. The code checks if roots are enabled and iterates over them, logging each root URI.

```java
    // Access root directories (only in stateful mode)
    if (context.rootsEnabled()) {
        ListRootsResult roots = context.roots();
        roots.roots().forEach(root -> context.info("Root: " + root.uri()));
    }

    return "Processed with unified context";
}
```

--------------------------------

### Kotlin: ExampleBean with int and String constructor args

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-client-chat/src/test/resources/text_source.txt

Kotlin data class with two constructor parameters, including comments for each.

```kotlin
package    examples


class    ExampleBean(
     private    val  years:    Int,   //  Number    of  years   to  calculate     the  Ultimate     Answer
     private    val  ultimateAnswer:       String    //  The   Answer   to  Life,    the   Universe,     and
Everything
)
```

--------------------------------

### SummaryMetadataEnricher usage example

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/etl-pipeline.adoc

Example of using SummaryMetadataEnricher with a ChatModel and summary types. Adds metadata fields section_summary, prev_section_summary, and next_section_summary to each document.

```java
ChatModel chatModel = // initialize your chat model
SummaryMetadataEnricher enricher = new SummaryMetadataEnricher(chatModel,
    List.of(SummaryType.PREVIOUS, SummaryType.CURRENT, SummaryType.NEXT));

Document doc1 = new Document("Content of document 1");
Document doc2 = new Document("Content of document 2");

List<Document> enrichedDocs = enricher.apply(List.of(this.doc1, this.doc2));
```

--------------------------------

### Bootstrap with Groovy configuration using GenericGroovyApplicationContext (Kotlin)

Source: https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-openai/src/test/resources/text_source.txt

Create an application context from Groovy configuration files with Kotlin.

```kotlin
val context = GenericGroovyApplicationContext("services.groovy", "daos.groovy")
```

--------------------------------

### Java: ExampleBean with int and String constructor args

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-client-chat/src/test/resources/text_source.txt

Example class with two constructor arguments (int years and String ultimateAnswer) used to illustrate simple type matching.

```java
package    examples;


public    class   ExampleBean      {


     //  Number    of  years   to  calculate     the  Ultimate     Answer
     private    final   int    years;


     //  The  Answer    to  Life,   the   Universe,     and  Everything
     private    final   String    ultimateAnswer;


     public   ExampleBean(int       years,    String    ultimateAnswer)       {
          this.years     =  years;
          this.ultimateAnswer         =  ultimateAnswer;
     }
}
```

--------------------------------

### Eviction strategy configuration examples

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/tools/tool-search-tool.adoc

Shows how to configure different eviction strategies for the ToolSearchToolCallingAdvisor, including default LRU, never evict, always evict, TTL, and composite strategies.

```java
// Default: LRU cap of 1000 sessions — no configuration needed
var advisor = ToolSearchToolCallingAdvisor.builder()
    .toolIndex(toolIndex)
    .build();

// Never evict — manage session lifetime yourself
var advisor = ToolSearchToolCallingAdvisor.builder()
    .toolIndex(toolIndex)
    .evictionStrategy(NeverEvictStrategy.INSTANCE)
    .build();

// Always evict — re-index every request (useful for testing)
var advisor = ToolSearchToolCallingAdvisor.builder()
    .toolIndex(toolIndex)
    .evictionStrategy(AlwaysEvictStrategy.INSTANCE)
    .build();

// LRU with custom cap
var advisor = ToolSearchToolCallingAdvisor.builder()
    .toolIndex(toolIndex)
    .evictionStrategy(new LruEvictionStrategy(200))
    .build();

// Evict sessions idle for more than 30 minutes
var advisor = ToolSearchToolCallingAdvisor.builder()
    .toolIndex(toolIndex)
    .evictionStrategy(new TtlEvictionStrategy(Duration.ofMinutes(30)))
    .build();

// Combine: TTL + LRU cap
var advisor = ToolSearchToolCallingAdvisor.builder()
    .toolIndex(toolIndex)
    .evictionStrategy(new CompositeEvictionStrategy(
        new TtlEvictionStrategy(Duration.ofMinutes(30)),
        new LruEvictionStrategy(200)))
    .build();
```

--------------------------------

### Get a list of typed objects with ParameterizedTypeReference

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/structured-output.adoc

Uses `ParameterizedTypeReference` to get a `List<ActorsFilms>` from the model. This is necessary for generic types like lists and maps.

```java
List<ActorsFilms> films = chatClient.prompt()
    .user("Generate filmographies for three random actors.")
    .call()
    .entity(new ParameterizedTypeReference<List<ActorsFilms>>() {});
```

--------------------------------

### XML bean definition with AnotherExampleBean

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-commons/src/test/resources/text_source.txt

Defines a bean of class examples.AnotherExampleBean. This is part of an example that has almost exactly the same effect as the previous init-method example, but uses the InitializingBean interface.

```xml
<bean id="exampleInitBean" class="examples.AnotherExampleBean"/>
```

--------------------------------

### Add Starter Dependency

Source: https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-google-genai-embedding/README.md

Include this dependency in your project to use the Google GenAI embedding starter.

```xml
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-google-genai-embedding</artifactId>
</dependency>
```

--------------------------------

### Maven artifact ID update example

Source: https://github.com/spring-projects/spring-ai/blob/main/src/prompts/update-to-snapshot.txt

Example of updating a Spring AI starter artifact ID in pom.xml. The pattern is spring-ai-{model}-spring-boot-starter to spring-ai-starter-model-{model}.

```xml
<!-- BEFORE -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
</dependency>
```

```xml
<!-- AFTER -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>
```

--------------------------------

### Runtime Options: Build OpenAiAudioSpeechOptions and call model

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/audio/speech/openai-speech.adoc

Shows how to create OpenAiAudioSpeechOptions with model, voice, response format, speed, and instructions, then build a TextToSpeechPrompt and call the model. The options can be overridden at runtime.

```java
OpenAiAudioSpeechOptions speechOptions = OpenAiAudioSpeechOptions.builder()
    .model("gpt-4o-mini-tts")
    .voice(OpenAiAudioApi.SpeechRequest.Voice.ALLOY)
    .responseFormat(OpenAiAudioApi.SpeechRequest.AudioResponseFormat.MP3)
    .speed(1.0)
    .instructions("Friendly; warm tone; natural pauses")
    .build();

TextToSpeechPrompt speechPrompt = new TextToSpeechPrompt("Hello, this is a text-to-speech example.", speechOptions);
TextToSpeechResponse response = openAiAudioSpeechModel.call(speechPrompt);
```

--------------------------------

### Complete example: working with existing index

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/azure.adoc

Complete configuration class for using an existing Azure AI Search index with custom field names. Includes SearchIndexClient bean and VectorStore bean with initializeSchema(false).

```java
@Configuration
public class VectorStoreConfig {

	@Bean
	public SearchIndexClient searchIndexClient() {
		return new SearchIndexClientBuilder()
			.endpoint(System.getenv("AZURE_AI_SEARCH_ENDPOINT"))
			.credential(new AzureKeyCredential(System.getenv("AZURE_AI_SEARCH_API_KEY")))
			.buildClient();
	}

	@Bean
	public VectorStore vectorStore(SearchIndexClient searchIndexClient,
			EmbeddingModel embeddingModel) {

		return AzureVectorStore.builder(searchIndexClient, embeddingModel)
			.indexName("production-documents-index")
			.initializeSchema(false) // Use existing index
			// Map to existing index field names
			.contentFieldName("document_text")
			.embeddingFieldName("text_vector")
			.metadataFieldName("document_metadata")
			// Define filterable metadata fields from existing schema
			.filterMetadataFields(List.of(
				MetadataField.text("department"),
				MetadataField.int64("year"),
				MetadataField.date("created_date")))
			.defaultTopK(10)
			.defaultSimilarityThreshold(0.75)
			.build();
	}
}
```

--------------------------------

### Remove streamToolCallResponses from builder chain (Before/After)

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/upgrade-notes.adoc

Shows the migration from using streamToolCallResponses(true) to a plain builder. The before example includes the line to remove, and the after example shows the simplified builder without it.

```java
// Before
var advisor = ToolCallingAdvisor.builder()
    .streamToolCallResponses(true)   // <-- remove this line
    .build();

// After
var advisor = ToolCallingAdvisor.builder().build();
```

--------------------------------

### Inject MCP client beans (sync and async)

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/mcp/mcp-client-boot-starter-docs.adoc

Shows how to autowire lists of McpSyncClient and McpAsyncClient beans that are automatically configured by the starter. Use the appropriate list depending on whether you need synchronous or asynchronous clients.

```java
@Autowired
private List<McpSyncClient> mcpSyncClients;  // For sync client

// OR

@Autowired
private List<McpAsyncClient> mcpAsyncClients;  // For async client
```

--------------------------------

### Read PDF with ParagraphPdfDocumentReader

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/etl-pipeline.adoc

Example of using ParagraphPdfDocumentReader to read a PDF file using its catalog (TOC) information, configured similarly to the PagePdfDocumentReader example. Note that not all PDFs contain a catalog.

```java
@Component
public class MyPagePdfDocumentReader {

	List<Document> getDocsFromPdfWithCatalog() {

        ParagraphPdfDocumentReader pdfReader = new ParagraphPdfDocumentReader("classpath:/sample1.pdf",
                PdfDocumentReaderConfig.builder()
                    .withPageTopMargin(0)
                    .withPageExtractedTextFormatter(ExtractedTextFormatter.builder()
                        .withNumberOfTopTextLinesToDelete(0)
                        .build())
                    .withPagesPerDocument(1)
                    .build());

	    return pdfReader.read();
    }
}
```

--------------------------------

### Sampling Client Implementation

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/mcp/mcp-annotations-examples.adoc

Demonstrates how to handle sampling requests by routing them to appropriate LLM providers based on model hints using the @McpSampling annotation.

```java
@Service
public class McpClientHandlers {

    private static final Logger logger = LoggerFactory.getLogger(McpClientHandlers.class);

    @Autowired
    Map<String, ChatClient> chatClients;

    @McpProgress(clients = "server1")
    public void progressHandler(ProgressNotification progressNotification) {
        logger.info("MCP PROGRESS: [{}] progress: {} total: {} message: {}",
                progressNotification.progressToken(), progressNotification.progress(),
                progressNotification.total(), progressNotification.message());
    }

    @McpLogging(clients = "server1")
    public void loggingHandler(LoggingMessageNotification loggingMessage) {
        logger.info("MCP LOGGING: [{}] {}", loggingMessage.level(), loggingMessage.data());
    }

    @McpSampling(clients = "server1")
    public CreateMessageResult samplingHandler(CreateMessageRequest llmRequest) {
        logger.info("MCP SAMPLING: {}", llmRequest);

        // Extract user prompt and model hint
        var userPrompt = ((McpSchema.TextContent) llmRequest.messages().get(0).content()).text();
        String modelHint = llmRequest.modelPreferences().hints().get(0).name();

        // Find appropriate ChatClient based on model hint
        ChatClient hintedChatClient = chatClients.entrySet().stream()
                .filter(e -> e.getKey().contains(modelHint))
                .findFirst()
                .orElseThrow()
                .getValue();

        // Generate response using the selected model
        String response = hintedChatClient.prompt()
                .system(llmRequest.systemPrompt())
                .user(userPrompt)
                .call()
                .content();

        return CreateMessageResult.builder(Role.ASSISTANT, response, modelHint)
                .build();
    }
}
```

--------------------------------

### TextReader example with Spring component

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/etl-pipeline.adoc

Example of using TextReader in a Spring component to read a text file from the classpath and add custom metadata. The reader returns a list of Document objects.

```java
@Component
class MyTextReader {

    private final Resource resource;

    MyTextReader(@Value("classpath:text-source.txt") Resource resource) {
        this.resource = resource;
    }

	List<Document> loadText() {
		TextReader textReader = new TextReader(this.resource);
		textReader.getCustomMetadata().put("filename", "text-source.txt");

		return textReader.read();
    }
}
```

--------------------------------

### JsonReader example

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/etl-pipeline.adoc

Example of using JsonReader to load JSON documents from a classpath resource, specifying the keys "description" and "content" to use as text content.

```java
@Component
class MyJsonReader {

	private final Resource resource;

    MyJsonReader(@Value("classpath:bikes.json") Resource resource) {
        this.resource = resource;
    }

	List<Document> loadJsonAsDocuments() {
        JsonReader jsonReader = new JsonReader(this.resource, "description", "content");
        return jsonReader.get();
	}
}
```

--------------------------------

### Build the JSoup Reader module with Maven

Source: https://github.com/spring-projects/spring-ai/blob/main/document-readers/spring-ai-jsoup-document-reader/ README.md

Use this command to build the document-readers/jsoup-reader module. It runs the Maven wrapper with the -pl flag to target the specific module and clean install to build and install it.

```bash
./mvnw -pl document-readers/jsoup-reader clean install
```

--------------------------------

### Weaviate GraphQL filter conversion example

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/weaviate.adoc

Shows the proprietary Weaviate GraphQL filter format that a filter expression is converted into. The example uses an And/Or combination with Equal and GreaterThanEqual operators on metadata fields.

```graphql
operator: And
operands:
    [{
        operator: Or
        operands:
            [{
                path: ["meta_country"]
                operator: Equal
                valueText: "UK"
            },
            {
                path: ["meta_country"]
                operator: Equal
                valueText: "NL"
            }]
    },
    {
        path: ["meta_year"]
        operator: GreaterThanEqual
        valueNumber: 2020
    }]
```

--------------------------------

### Add spring-ai-starter-mcp-client-webflux dependency

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/mcp/mcp-client-boot-starter-docs.adoc

Add the WebFlux MCP client starter for WebFlux-based Streamable-Http, Stateless Streamable-Http, and SSE transport implementations. Recommended for production deployment over the standard starter.

```xml
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-client-webflux</artifactId>
</dependency>
```

--------------------------------

### Build reference documentation

Source: https://github.com/spring-projects/spring-ai/blob/main/CONTRIBUTING.md

Build the Antora-based reference documentation for the spring-ai-docs module.

```shell
./mvnw -pl spring-ai-docs antora
```

--------------------------------

### Streaming example with thinking deltas

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/anthropic-chat.adoc

Configures thinking for streaming mode and subscribes to a `Flux<ChatResponse>` to receive thinking deltas and signature deltas as they arrive. Uses the same model and thinking budget as the non-streaming example.

```java
var options = AnthropicChatOptions.builder()
    .model("claude-sonnet-4-20250514")
    .temperature(1.0)
    .maxTokens(16000)
    .thinkingEnabled(10000L)
    .build();

Flux<ChatResponse> stream = chatModel.stream(
    new Prompt("Are there an infinite number of prime numbers such that n mod 4 == 3?", options));

stream.subscribe(response -> {
    Generation generation = response.getResult();
    AssistantMessage message = generation.getOutput();
```

--------------------------------

### Create OpenAiChatModel with builder (Java)

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/openai-chat.adoc

Builds an OpenAiChatModel with configuration options like API key, model, temperature, and max tokens. Demonstrates both synchronous call and streaming responses.

```java
var chatModel = OpenAiChatModel.builder()
    .options(OpenAiChatOptions.builder()
        .apiKey(System.getenv("OPENAI_API_KEY"))
        .model("gpt-3.5-turbo")
        .temperature(0.4)
        .maxTokens(200)
        .build())
    .build();

ChatResponse response = this.chatModel.call(
    new Prompt("Generate the names of 5 famous pirates."));

// Or with streaming responses
Flux<ChatResponse> response = this.chatModel.stream(
    new Prompt("Generate the names of 5 famous pirates."));
```

--------------------------------

### Auto-wire VectorStore and add documents

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/pgvector.adoc

Shows how to auto-wire the VectorStore and use it to add documents and perform a similarity search. The example creates three documents, adds them to the store, and retrieves results for the query 'Spring'.

```java
@Autowired VectorStore vectorStore;

// ...

List<Document> documents = List.of(
    new Document("Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!!", Map.of("meta1", "meta1")),
    new Document("The World is Big and Salvation Lurks Around the Corner"),
    new Document("You walk forward facing the past and you turn back toward the future.", Map.of("meta2", "meta2")));

// Add the documents to PGVector
vectorStore.add(documents);

// Retrieve documents similar to a query
List<Document> results = this.vectorStore.similaritySearch(SearchRequest.builder().query("Spring").topK(5).build());
```

--------------------------------

### One-shot and few-shot prompting with ChatClient

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/prompt-engineering-patterns.adoc

Demonstrates a few-shot prompting example that parses a pizza order into JSON using two examples. Uses ChatClient with model 'claude-sonnet-4-6', temperature 0.1, maxTokens 250.

```java
// Implementation of Section 2.2: One-shot & few-shot (page 16)
public void pt_one_shot_few_shots(ChatClient chatClient) {
    String pizzaOrder = chatClient.prompt("""
            Parse a customer's pizza order into valid JSON

            EXAMPLE 1:
            I want a small pizza with cheese, tomato sauce, and pepperoni.
            JSON Response:
            ```
            {
                "size": "small",
                "type": "normal",
                "ingredients": ["cheese", "tomato sauce", "pepperoni"]
            }
            ```

            EXAMPLE 2:
            Can I get a large pizza with tomato sauce, basil and mozzarella.
            JSON Response:
            ```
            {
                "size": "large",
                "type": "normal",
                "ingredients": ["tomato sauce", "basil", "mozzarella"]
            }
            ```

            Now, I would like a large pizza, with the first half cheese and mozzarella.
            And the other tomato sauce, ham and pineapple.
            """)
            .options(ChatOptions.builder()
                    .model("claude-sonnet-4-6")
                    .temperature(0.1)
                    .maxTokens(250)
                    .build())
            .call()
            .content();
}
```

--------------------------------

### Create and use OpenAiAudioTranscriptionModel

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/audio/transcriptions/openai-transcriptions.adoc

Builds an OpenAiAudioTranscriptionModel with options, loads an audio file, and performs a transcription call. The example uses an API key from the environment and sets response format to TEXT with temperature 0.

```java
var transcriptionOptions = OpenAiAudioTranscriptionOptions.builder()
    .apiKey(System.getenv("OPENAI_API_KEY"))
    .responseFormat(AudioResponseFormat.TEXT)
    .temperature(0f)
    .build();

var openAiAudioTranscriptionModel = OpenAiAudioTranscriptionModel.builder()
    .options(transcriptionOptions)
    .build();

var audioFile = new FileSystemResource("/path/to/your/resource/speech/jfk.flac");

AudioTranscriptionPrompt transcriptionRequest = new AudioTranscriptionPrompt(audioFile, transcriptionOptions);
AudioTranscriptionResponse response = openAiAudioTranscriptionModel.call(transcriptionRequest);
```

--------------------------------

### Gradle artifact ID update example

Source: https://github.com/spring-projects/spring-ai/blob/main/src/prompts/update-to-snapshot.txt

Example of updating Spring AI starter artifact IDs in Gradle. The patterns are spring-ai-{model}-spring-boot-starter to spring-ai-starter-model-{model} and spring-ai-{store}-store-spring-boot-starter to spring-ai-starter-vector-store-{store}.

```groovy
// BEFORE
implementation 'org.springframework.ai:spring-ai-openai-spring-boot-starter'
implementation 'org.springframework.ai:spring-ai-redis-store-spring-boot-starter'
```

```groovy
// AFTER
implementation 'org.springframework.ai:spring-ai-starter-model-openai'
implementation 'org.springframework.ai:spring-ai-starter-vector-store-redis'
```

--------------------------------

### Configure topK and topP sampling controls

Source: https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/prompt-engineering-patterns.adoc

Set topK to 40 and topP to 0.8 to control token selection diversity. These work with temperature to shape response characteristics.

```java
.options(ChatOptions.builder()
        .topK(40)      // Consider only the top 40 tokens
        .topP(0.8)     // Sample from tokens that cover 80% of probability mass
        .build())
```
Tokens:
Raw