spring-projectsGH-1403: Add Anthropic prompt caching via AnthropicChatOptions

- Add cacheControl field to AnthropicChatOptions with builder method
- Create AnthropicCacheType enum with EPHEMERAL type for type-safe cache creation
- Update AnthropicChatModel.createRequest() to apply cache control from options to user message ContentBlocks
- Extend ContentBlock record with cacheControl parameter and constructor for API compatibility
- Update Usage record to include cacheCreationInputTokens and cacheReadInputTokens fields
- Update StreamHelper to handle new Usage constructor with cache token parameters
- Add AnthropicApiIT.chatWithPromptCache() test for low-level API validation
- Add AnthropicChatModelIT.chatWithPromptCacheViaOptions() integration test
- Add comprehensive unit tests for AnthropicChatOptions cache control functionality
- Update documentation with cacheControl() method examples and usage patterns

Cache control is configured through AnthropicChatOptions rather than message classes
to maintain provider portability. The cache control gets applied during request creation
in AnthropicChatModel when building ContentBlocks for user messages.

Original implementation provided by @Claudio-code (Claudio Silva Junior)
See spring-projects@15e5026

Fixes spring-projects#1403

Signed-off-by: Soby Chacko <[email protected]>

Author: sobychacko

models/spring-ai-anthropic/src/main/java/org/springframework/ai/anthropic/AnthropicChatModel.java

@@ -483,12 +483,25 @@ private Map<String, String> mergeHttpHeaders(Map<String, String> runtimeHttpHead
 
 	ChatCompletionRequest createRequest(Prompt prompt, boolean stream) {
 
+		// Get cache control from options
+		AnthropicChatOptions requestOptions = (AnthropicChatOptions) prompt.getOptions();
+		AnthropicApi.ChatCompletionRequest.CacheControl cacheControl = (requestOptions != null)
+				? requestOptions.getCacheControl() : null;
+
 		List<AnthropicMessage> userMessages = prompt.getInstructions()
 			.stream()
 			.filter(message -> message.getMessageType() != MessageType.SYSTEM)
 			.map(message -> {
 				if (message.getMessageType() == MessageType.USER) {
-					List<ContentBlock> contents = new ArrayList<>(List.of(new ContentBlock(message.getText())));
+					List<ContentBlock> contents = new ArrayList<>();
+
+					// Apply cache control if enabled for user messages
+					if (cacheControl != null) {
+						contents.add(new ContentBlock(message.getText(), cacheControl));
+					}
+					else {
+						contents.add(new ContentBlock(message.getText()));
+					}
 					if (message instanceof UserMessage userMessage) {
 						if (!CollectionUtils.isEmpty(userMessage.getMedia())) {
 							List<ContentBlock> mediaContent = userMessage.getMedia().stream().map(media -> {
@@ -538,7 +551,6 @@ else if (message.getMessageType() == MessageType.TOOL) {
 		ChatCompletionRequest request = new ChatCompletionRequest(this.defaultOptions.getModel(), userMessages,
 				systemPrompt, this.defaultOptions.getMaxTokens(), this.defaultOptions.getTemperature(), stream);
 
-		AnthropicChatOptions requestOptions = (AnthropicChatOptions) prompt.getOptions();
 		request = ModelOptionsUtils.merge(requestOptions, request, ChatCompletionRequest.class);
 
 		// Add the tool definitions to the request's tools parameter.

models/spring-ai-anthropic/src/main/java/org/springframework/ai/anthropic/AnthropicChatOptions.java

@@ -44,6 +44,7 @@
  * @author Thomas Vitale
  * @author Alexandros Pappas
  * @author Ilayaperumal Gopinathan
+ * @author Soby Chacko
  * @since 1.0.0
  */
 @JsonInclude(Include.NON_NULL)
@@ -59,6 +60,20 @@ public class AnthropicChatOptions implements ToolCallingChatOptions {
 	private @JsonProperty("top_k") Integer topK;
 	private @JsonProperty("thinking") ChatCompletionRequest.ThinkingConfig thinking;
 
+	/**
+	 * Cache control for user messages. When set, enables caching for user messages.
+	 * Uses the existing CacheControl record from AnthropicApi.ChatCompletionRequest.
+	 */
+	private @JsonProperty("cache_control") ChatCompletionRequest.CacheControl cacheControl;
+
+	public ChatCompletionRequest.CacheControl getCacheControl() {
+		return this.cacheControl;
+	}
+
+	public void setCacheControl(ChatCompletionRequest.CacheControl cacheControl) {
+		this.cacheControl = cacheControl;
+	}
+
 	/**
 	 * Collection of {@link ToolCallback}s to be used for tool calling in the chat
 	 * completion requests.
@@ -111,6 +126,7 @@ public static AnthropicChatOptions fromOptions(AnthropicChatOptions fromOptions)
 			.internalToolExecutionEnabled(fromOptions.getInternalToolExecutionEnabled())
 			.toolContext(fromOptions.getToolContext() != null ? new HashMap<>(fromOptions.getToolContext()) : null)
 			.httpHeaders(fromOptions.getHttpHeaders() != null ? new HashMap<>(fromOptions.getHttpHeaders()) : null)
+			.cacheControl(fromOptions.getCacheControl())
 			.build();
 	}
 
@@ -282,14 +298,15 @@ public boolean equals(Object o) {
 				&& Objects.equals(this.toolNames, that.toolNames)
 				&& Objects.equals(this.internalToolExecutionEnabled, that.internalToolExecutionEnabled)
 				&& Objects.equals(this.toolContext, that.toolContext)
-				&& Objects.equals(this.httpHeaders, that.httpHeaders);
+				&& Objects.equals(this.httpHeaders, that.httpHeaders)
+				&& Objects.equals(this.cacheControl, that.cacheControl);
 	}
 
 	@Override
 	public int hashCode() {
 		return Objects.hash(this.model, this.maxTokens, this.metadata, this.stopSequences, this.temperature, this.topP,
 				this.topK, this.thinking, this.toolCallbacks, this.toolNames, this.internalToolExecutionEnabled,
-				this.toolContext, this.httpHeaders);
+				this.toolContext, this.httpHeaders, this.cacheControl);
 	}
 
 	public static class Builder {
@@ -389,6 +406,14 @@ public Builder httpHeaders(Map<String, String> httpHeaders) {
 			return this;
 		}
 
+		/**
+		 * Set cache control for user messages
+		 */
+		public Builder cacheControl(ChatCompletionRequest.CacheControl cacheControl) {
+			this.options.cacheControl = cacheControl;
+			return this;
+		}
+
 		public AnthropicChatOptions build() {
 			return this.options;
 		}

models/spring-ai-anthropic/src/main/java/org/springframework/ai/anthropic/api/AnthropicApi.java

@@ -35,6 +35,7 @@
 import reactor.core.publisher.Flux;
 import reactor.core.publisher.Mono;
 
+import org.springframework.ai.anthropic.api.AnthropicApi.ChatCompletionRequest.CacheControl;
 import org.springframework.ai.anthropic.api.StreamHelper.ChatCompletionResponseBuilder;
 import org.springframework.ai.model.ApiKey;
 import org.springframework.ai.model.ChatModelDescription;
@@ -65,6 +66,7 @@
  * @author Jonghoon Park
  * @author Claudio Silva Junior
  * @author Filip Hrisafov
+ * @author Soby Chacko
  * @since 1.0.0
  */
 public final class AnthropicApi {
@@ -557,6 +559,14 @@ public record Metadata(@JsonProperty("user_id") String userId) {
 
 		}
 
+		/**
+		 * @param type is the cache type supported by anthropic. <a href=
+		 * "https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching#cache-limitations">Doc</a>
+		 */
+		@JsonInclude(Include.NON_NULL)
+		public record CacheControl(String type) {
+		}
+
 		/**
 		 * Configuration for the model's thinking mode.
 		 *
@@ -763,8 +773,11 @@ public record ContentBlock(
 		@JsonProperty("thinking") String thinking,
 
 		// Redacted Thinking only
-		@JsonProperty("data") String data
-		) {
+		@JsonProperty("data") String data,
+
+		// cache object
+		@JsonProperty("cache_control") CacheControl cacheControl
+	) {
 		// @formatter:on
 
 		/**
@@ -782,23 +795,27 @@ public ContentBlock(String mediaType, String data) {
 		 * @param source The source of the content.
 		 */
 		public ContentBlock(Type type, Source source) {
-			this(type, source, null, null, null, null, null, null, null, null, null, null);
+			this(type, source, null, null, null, null, null, null, null, null, null, null, null);
 		}
 
 		/**
 		 * Create content block
 		 * @param source The source of the content.
 		 */
 		public ContentBlock(Source source) {
-			this(Type.IMAGE, source, null, null, null, null, null, null, null, null, null, null);
+			this(Type.IMAGE, source, null, null, null, null, null, null, null, null, null, null, null);
 		}
 
 		/**
 		 * Create content block
 		 * @param text The text of the content.
 		 */
 		public ContentBlock(String text) {
-			this(Type.TEXT, null, text, null, null, null, null, null, null, null, null, null);
+			this(Type.TEXT, null, text, null, null, null, null, null, null, null, null, null, null);
+		}
+
+		public ContentBlock(String text, CacheControl cache) {
+			this(Type.TEXT, null, text, null, null, null, null, null, null, null, null, null, cache);
 		}
 
 		// Tool result
@@ -809,7 +826,7 @@ public ContentBlock(String text) {
 		 * @param content The content of the tool result.
 		 */
 		public ContentBlock(Type type, String toolUseId, String content) {
-			this(type, null, null, null, null, null, null, toolUseId, content, null, null, null);
+			this(type, null, null, null, null, null, null, toolUseId, content, null, null, null, null);
 		}
 
 		/**
@@ -820,7 +837,7 @@ public ContentBlock(Type type, String toolUseId, String content) {
 		 * @param index The index of the content block.
 		 */
 		public ContentBlock(Type type, Source source, String text, Integer index) {
-			this(type, source, text, index, null, null, null, null, null, null, null, null);
+			this(type, source, text, index, null, null, null, null, null, null, null, null, null);
 		}
 
 		// Tool use input JSON delta streaming
@@ -832,7 +849,7 @@ public ContentBlock(Type type, Source source, String text, Integer index) {
 		 * @param input The input of the tool use.
 		 */
 		public ContentBlock(Type type, String id, String name, Map<String, Object> input) {
-			this(type, null, null, null, id, name, input, null, null, null, null, null);
+			this(type, null, null, null, id, name, input, null, null, null, null, null, null);
 		}
 
 		/**
@@ -1026,7 +1043,9 @@ public record ChatCompletionResponse(
 	public record Usage(
 	// @formatter:off
 		@JsonProperty("input_tokens") Integer inputTokens,
-		@JsonProperty("output_tokens") Integer outputTokens) {
+		@JsonProperty("output_tokens") Integer outputTokens,
+		@JsonProperty("cache_creation_input_tokens") Integer cacheCreationInputTokens,
+		@JsonProperty("cache_read_input_tokens") Integer cacheReadInputTokens) {
 		// @formatter:off
 	}
 

models/spring-ai-anthropic/src/main/java/org/springframework/ai/anthropic/api/AnthropicCacheType.java

@@ -0,0 +1,57 @@
+/*
+ * Copyright 2025-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.anthropic.api;
+
+import java.util.function.Supplier;
+
+import org.springframework.ai.anthropic.api.AnthropicApi.ChatCompletionRequest.CacheControl;
+
+/**
+ * Cache types supported by Anthropic's prompt caching feature.
+ *
+ * <p>
+ * Prompt caching allows reusing frequently used prompts to reduce costs and improve
+ * response times for repeated interactions.
+ *
+ * @see <a href=
+ * "https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching">Anthropic Prompt
+ * Caching</a>
+ * @author Claudio Silva Junior
+ * @author Soby Chacko
+ */
+public enum AnthropicCacheType {
+
+	/**
+	 * Ephemeral cache with 5-minute lifetime, refreshed on each use.
+	 */
+	EPHEMERAL(() -> new CacheControl("ephemeral"));
+
+	private final Supplier<CacheControl> value;
+
+	AnthropicCacheType(Supplier<CacheControl> value) {
+		this.value = value;
+	}
+
+	/**
+	 * Returns a new CacheControl instance for this cache type.
+	 * @return a CacheControl instance configured for this cache type
+	 */
+	public CacheControl cacheControl() {
+		return this.value.get();
+	}
+
+}

models/spring-ai-anthropic/src/main/java/org/springframework/ai/anthropic/api/StreamHelper.java

@@ -55,6 +55,8 @@
  * @author Christian Tzolov
  * @author Jihoon Kim
  * @author Alexandros Pappas
+ * @author Claudio Silva Junior
+ * @author Soby Chacko
  * @since 1.0.0
  */
 public class StreamHelper {
@@ -159,7 +161,7 @@ else if (event.type().equals(EventType.CONTENT_BLOCK_START)) {
 			}
 			else if (contentBlockStartEvent.contentBlock() instanceof ContentBlockThinking thinkingBlock) {
 				ContentBlock cb = new ContentBlock(Type.THINKING, null, null, contentBlockStartEvent.index(), null,
-						null, null, null, null, null, thinkingBlock.thinking(), null);
+						null, null, null, null, null, thinkingBlock.thinking(), null, null);
 				contentBlockReference.get().withType(event.type().name()).withContent(List.of(cb));
 			}
 			else {
@@ -176,12 +178,12 @@ else if (event.type().equals(EventType.CONTENT_BLOCK_DELTA)) {
 			}
 			else if (contentBlockDeltaEvent.delta() instanceof ContentBlockDeltaThinking thinking) {
 				ContentBlock cb = new ContentBlock(Type.THINKING_DELTA, null, null, contentBlockDeltaEvent.index(),
-						null, null, null, null, null, null, thinking.thinking(), null);
+						null, null, null, null, null, null, thinking.thinking(), null, null);
 				contentBlockReference.get().withType(event.type().name()).withContent(List.of(cb));
 			}
 			else if (contentBlockDeltaEvent.delta() instanceof ContentBlockDeltaSignature sig) {
 				ContentBlock cb = new ContentBlock(Type.SIGNATURE_DELTA, null, null, contentBlockDeltaEvent.index(),
-						null, null, null, null, null, sig.signature(), null, null);
+						null, null, null, null, null, sig.signature(), null, null, null);
 				contentBlockReference.get().withType(event.type().name()).withContent(List.of(cb));
 			}
 			else {
@@ -205,7 +207,9 @@ else if (event.type().equals(EventType.MESSAGE_DELTA)) {
 
 			if (messageDeltaEvent.usage() != null) {
 				Usage totalUsage = new Usage(contentBlockReference.get().usage.inputTokens(),
-						messageDeltaEvent.usage().outputTokens());
+						messageDeltaEvent.usage().outputTokens(),
+						contentBlockReference.get().usage.cacheCreationInputTokens(),
+						contentBlockReference.get().usage.cacheReadInputTokens());
 				contentBlockReference.get().withUsage(totalUsage);
 			}
 		}

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

@@ -32,6 +32,7 @@
 import reactor.core.publisher.Flux;
 
 import org.springframework.ai.anthropic.api.AnthropicApi;
+import org.springframework.ai.anthropic.api.AnthropicCacheType;
 import org.springframework.ai.anthropic.api.tool.MockWeatherService;
 import org.springframework.ai.chat.client.ChatClient;
 import org.springframework.ai.chat.messages.AssistantMessage;
@@ -491,6 +492,59 @@ void testToolUseContentBlock() {
 		}
 	}
 
+	@Test
+	void chatWithPromptCacheViaOptions() {
+		String userMessageText = "It could be eitherr a contraction of the full title Quenta Silmarillion (\"Tale of the Silmarils\") or also a plain Genitive which "
+				+ "(as in Ancient Greek) signifies reference. This genitive is translated in English with \"about\" or \"of\" "
+				+ "constructions; the titles of the chapters in The Silmarillion are examples of this genitive in poetic English "
+				+ "(Of the Sindar, Of Men, Of the Darkening of Valinor etc), where \"of\" means \"about\" or \"concerning\". "
+				+ "In the same way, Silmarillion can be taken to mean \"Of/About the Silmarils\"";
+
+		// Repeat content to meet minimum token requirements for caching (1024+ tokens)
+		String largeContent = userMessageText.repeat(20);
+
+		// First request - should create cache
+		ChatResponse firstResponse = this.chatModel.call(new Prompt(List.of(new UserMessage(largeContent)),
+				AnthropicChatOptions.builder()
+					.model(AnthropicApi.ChatModel.CLAUDE_3_HAIKU.getValue())
+					.cacheControl(AnthropicCacheType.EPHEMERAL.cacheControl())
+					.maxTokens(100)
+					.temperature(0.8)
+					.build()));
+
+		// Access native Anthropic usage data
+		AnthropicApi.Usage firstUsage = (AnthropicApi.Usage) firstResponse.getMetadata().getUsage().getNativeUsage();
+
+		// Verify first request created cache
+		assertThat(firstUsage.cacheCreationInputTokens()).isGreaterThan(0);
+		assertThat(firstUsage.cacheReadInputTokens()).isEqualTo(0);
+
+		// Second request with identical content - should read from cache
+		ChatResponse secondResponse = this.chatModel.call(new Prompt(List.of(new UserMessage(largeContent)),
+				AnthropicChatOptions.builder()
+					.model(AnthropicApi.ChatModel.CLAUDE_3_HAIKU.getValue())
+					.cacheControl(AnthropicCacheType.EPHEMERAL.cacheControl())
+					.maxTokens(100)
+					.temperature(0.8)
+					.build()));
+
+		// Access native Anthropic usage data
+		AnthropicApi.Usage secondUsage = (AnthropicApi.Usage) secondResponse.getMetadata().getUsage().getNativeUsage();
+
+		// Verify second request used cache
+		assertThat(secondUsage.cacheCreationInputTokens()).isEqualTo(0);
+		assertThat(secondUsage.cacheReadInputTokens()).isGreaterThan(0);
+
+		// Both responses should be valid
+		assertThat(firstResponse.getResult().getOutput().getText()).isNotBlank();
+		assertThat(secondResponse.getResult().getOutput().getText()).isNotBlank();
+
+		logger.info("First request - Cache creation: {}, Cache read: {}", firstUsage.cacheCreationInputTokens(),
+				firstUsage.cacheReadInputTokens());
+		logger.info("Second request - Cache creation: {}, Cache read: {}", secondUsage.cacheCreationInputTokens(),
+				secondUsage.cacheReadInputTokens());
+	}
+
 	record ActorsFilmsRecord(String actor, List<String> movies) {
 
 	}