feat: Implement cache management for Anthropic API with eligibility tracking

gh-4325: Enhance cache management for Anthropic API by introudicing per-message TTL and configurable content block usage optimization.
Signed-off-by: Austin Dase <[email protected]>

Author: adase11

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

@@ -32,7 +32,7 @@
 
 import org.springframework.ai.anthropic.api.AnthropicApi;
 import org.springframework.ai.anthropic.api.AnthropicApi.ChatCompletionRequest;
-import org.springframework.ai.anthropic.api.AnthropicCacheStrategy;
+import org.springframework.ai.anthropic.api.AnthropicCacheOptions;
 import org.springframework.ai.model.tool.ToolCallingChatOptions;
 import org.springframework.ai.tool.ToolCallback;
 import org.springframework.lang.Nullable;
@@ -46,6 +46,7 @@
  * @author Alexandros Pappas
  * @author Ilayaperumal Gopinathan
  * @author Soby Chacko
+ * @author Austin Dase
  * @since 1.0.0
  */
 @JsonInclude(Include.NON_NULL)
@@ -61,35 +62,16 @@ public class AnthropicChatOptions implements ToolCallingChatOptions {
 	private @JsonProperty("top_k") Integer topK;
 	private @JsonProperty("thinking") ChatCompletionRequest.ThinkingConfig thinking;
 
-	/**
-	 * The caching strategy to use. Defines which parts of the prompt should be cached.
-	 */
 	@JsonIgnore
-	private AnthropicCacheStrategy cacheStrategy = AnthropicCacheStrategy.NONE;
-
-	/**
-	 * Cache time-to-live. Either "5m" (5 minutes, default) or "1h" (1 hour).
-	 * The 1-hour cache requires a beta header.
-	 */
-	@JsonIgnore
-	private String cacheTtl = "5m";
-
-	public AnthropicCacheStrategy getCacheStrategy() {
-		return this.cacheStrategy;
-	}
-
-	public void setCacheStrategy(AnthropicCacheStrategy cacheStrategy) {
-		this.cacheStrategy = cacheStrategy;
-	}
+	private AnthropicCacheOptions cacheOptions = AnthropicCacheOptions.DISABLED;
 
-	public String getCacheTtl() {
-		return this.cacheTtl;
+	public AnthropicCacheOptions getCacheOptions() {
+		return this.cacheOptions;
 	}
 
-	public void setCacheTtl(String cacheTtl) {
-		this.cacheTtl = cacheTtl;
+	public void setCacheOptions(AnthropicCacheOptions cacheOptions) {
+		this.cacheOptions = cacheOptions;
 	}
-
 	/**
 	 * Collection of {@link ToolCallback}s to be used for tool calling in the chat
 	 * completion requests.
@@ -142,8 +124,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)
-			.cacheStrategy(fromOptions.getCacheStrategy())
-			.cacheTtl(fromOptions.getCacheTtl())
+			.cacheOptions(fromOptions.getCacheOptions())
 			.build();
 	}
 
@@ -316,15 +297,14 @@ public boolean equals(Object o) {
 				&& Objects.equals(this.internalToolExecutionEnabled, that.internalToolExecutionEnabled)
 				&& Objects.equals(this.toolContext, that.toolContext)
 				&& Objects.equals(this.httpHeaders, that.httpHeaders)
-				&& Objects.equals(this.cacheStrategy, that.cacheStrategy)
-				&& Objects.equals(this.cacheTtl, that.cacheTtl);
+				&& Objects.equals(this.cacheOptions, that.cacheOptions);
 	}
 
 	@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.cacheStrategy, this.cacheTtl);
+				this.toolContext, this.httpHeaders, this.cacheOptions);
 	}
 
 	public static class Builder {
@@ -424,19 +404,8 @@ public Builder httpHeaders(Map<String, String> httpHeaders) {
 			return this;
 		}
 
-		/**
-		 * Set the caching strategy to use.
-		 */
-		public Builder cacheStrategy(AnthropicCacheStrategy cacheStrategy) {
-			this.options.cacheStrategy = cacheStrategy;
-			return this;
-		}
-
-		/**
-		 * Set the cache time-to-live. Either "5m" (5 minutes, default) or "1h" (1 hour).
-		 */
-		public Builder cacheTtl(String cacheTtl) {
-			this.options.cacheTtl = cacheTtl;
+		public Builder cacheOptions(AnthropicCacheOptions cacheOptions) {
+			this.options.setCacheOptions(cacheOptions);
 			return this;
 		}
 

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

@@ -67,6 +67,7 @@
  * @author Claudio Silva Junior
  * @author Filip Hrisafov
  * @author Soby Chacko
+ * @author Austin Dase
  * @since 1.0.0
  */
 public final class AnthropicApi {
@@ -860,6 +861,10 @@ 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, null);
 		}
 
+		public static ContentBlockBuilder from(ContentBlock contentBlock) {
+			return new ContentBlockBuilder(contentBlock);
+		}
+
 		/**
 		 * The ContentBlock type.
 		 */
@@ -984,6 +989,121 @@ public Source(String url) {
 
 		}
 
+		public static class ContentBlockBuilder {
+
+			private Type type;
+
+			private Source source;
+
+			private String text;
+
+			private Integer index;
+
+			private String id;
+
+			private String name;
+
+			private Map<String, Object> input;
+
+			private String toolUseId;
+
+			private String content;
+
+			private String signature;
+
+			private String thinking;
+
+			private String data;
+
+			private CacheControl cacheControl;
+
+			public ContentBlockBuilder(ContentBlock contentBlock) {
+				this.type = contentBlock.type;
+				this.source = contentBlock.source;
+				this.text = contentBlock.text;
+				this.index = contentBlock.index;
+				this.id = contentBlock.id;
+				this.name = contentBlock.name;
+				this.input = contentBlock.input;
+				this.toolUseId = contentBlock.toolUseId;
+				this.content = contentBlock.content;
+				this.signature = contentBlock.signature;
+				this.thinking = contentBlock.thinking;
+				this.data = contentBlock.data;
+				this.cacheControl = contentBlock.cacheControl;
+			}
+
+			public ContentBlockBuilder type(Type type) {
+				this.type = type;
+				return this;
+			}
+
+			public ContentBlockBuilder source(Source source) {
+				this.source = source;
+				return this;
+			}
+
+			public ContentBlockBuilder text(String text) {
+				this.text = text;
+				return this;
+			}
+
+			public ContentBlockBuilder index(Integer index) {
+				this.index = index;
+				return this;
+			}
+
+			public ContentBlockBuilder id(String id) {
+				this.id = id;
+				return this;
+			}
+
+			public ContentBlockBuilder name(String name) {
+				this.name = name;
+				return this;
+			}
+
+			public ContentBlockBuilder input(Map<String, Object> input) {
+				this.input = input;
+				return this;
+			}
+
+			public ContentBlockBuilder toolUseId(String toolUseId) {
+				this.toolUseId = toolUseId;
+				return this;
+			}
+
+			public ContentBlockBuilder content(String content) {
+				this.content = content;
+				return this;
+			}
+
+			public ContentBlockBuilder signature(String signature) {
+				this.signature = signature;
+				return this;
+			}
+
+			public ContentBlockBuilder thinking(String thinking) {
+				this.thinking = thinking;
+				return this;
+			}
+
+			public ContentBlockBuilder data(String data) {
+				this.data = data;
+				return this;
+			}
+
+			public ContentBlockBuilder cacheControl(CacheControl cacheControl) {
+				this.cacheControl = cacheControl;
+				return this;
+			}
+
+			public ContentBlock build() {
+				return new ContentBlock(this.type, this.source, this.text, this.index, this.id, this.name, this.input,
+						this.toolUseId, this.content, this.signature, this.thinking, this.data, this.cacheControl);
+			}
+
+		}
 	}
 
 	///////////////////////////////////////