This change introduces a new field for tracking cached tokens in the

OpenAI API response. It extends the Usage record to include
PromptTokensDetails, allowing for more granular token usage
reporting. The OpenAiUsage class is updated to expose this new data,
and corresponding unit tests are added to verify the behavior.

This enhancement provides more detailed insights into token usage,
indicating how many of the prompt tokens were a cache hit.

Author: dafriz

models/spring-ai-openai/src/main/java/org/springframework/ai/openai/api/OpenAiApi.java

@@ -939,17 +939,29 @@ public record TopLogProbs(// @formatter:off
 	 * @param promptTokens Number of tokens in the prompt.
 	 * @param totalTokens Total number of tokens used in the request (prompt +
 	 * completion).
-	 * @param completionTokenDetails Breakdown of tokens used in a completion
+	 * @param promptTokensDetails Breakdown of tokens used in the prompt.
+	 * @param completionTokenDetails Breakdown of tokens used in a completion.
 	 */
 	@JsonInclude(Include.NON_NULL)
 	public record Usage(// @formatter:off
 			@JsonProperty("completion_tokens") Integer completionTokens,
 			@JsonProperty("prompt_tokens") Integer promptTokens,
 			@JsonProperty("total_tokens") Integer totalTokens,
+			@JsonProperty("prompt_tokens_details") PromptTokensDetails promptTokensDetails,
 			@JsonProperty("completion_tokens_details") CompletionTokenDetails completionTokenDetails) {// @formatter:on
 
 		public Usage(Integer completionTokens, Integer promptTokens, Integer totalTokens) {
-			this(completionTokens, promptTokens, totalTokens, null);
+			this(completionTokens, promptTokens, totalTokens, null, null);
+		}
+
+		/**
+		 * Breakdown of tokens used in the prompt
+		 *
+		 * @param cachedTokens Cached tokens present in the prompt.
+		 */
+		@JsonInclude(Include.NON_NULL)
+		public record PromptTokensDetails(// @formatter:off
+				@JsonProperty("cached_tokens") Integer cachedTokens) {// @formatter:on
 		}
 
 		/**

models/spring-ai-openai/src/main/java/org/springframework/ai/openai/metadata/OpenAiUsage.java

@@ -58,6 +58,12 @@ public Long getGenerationTokens() {
 		return generationTokens != null ? generationTokens.longValue() : 0;
 	}
 
+	public Long getCachedTokens() {
+		OpenAiApi.Usage.PromptTokensDetails promptTokenDetails = getUsage().promptTokensDetails();
+		Integer cachedTokens = promptTokenDetails != null ? promptTokenDetails.cachedTokens() : null;
+		return cachedTokens != null ? cachedTokens.longValue() : 0;
+	}
+
 	public Long getReasoningTokens() {
 		OpenAiApi.Usage.CompletionTokenDetails completionTokenDetails = getUsage().completionTokenDetails();
 		Integer reasoningTokens = completionTokenDetails != null ? completionTokenDetails.reasoningTokens() : null;

models/spring-ai-openai/src/test/java/org/springframework/ai/openai/metadata/OpenAiUsageTests.java

@@ -55,27 +55,44 @@ void whenTotalTokensIsNull() {
 	}
 
 	@Test
-	void whenCompletionTokenDetailsIsNull() {
-		OpenAiApi.Usage openAiUsage = new OpenAiApi.Usage(100, 200, 300, null);
+	void whenPromptAndCompletionTokensDetailsIsNull() {
+		OpenAiApi.Usage openAiUsage = new OpenAiApi.Usage(100, 200, 300, null, null);
 		OpenAiUsage usage = OpenAiUsage.from(openAiUsage);
 		assertThat(usage.getTotalTokens()).isEqualTo(300);
+		assertThat(usage.getCachedTokens()).isEqualTo(0);
 		assertThat(usage.getReasoningTokens()).isEqualTo(0);
 	}
 
 	@Test
 	void whenReasoningTokensIsNull() {
-		OpenAiApi.Usage openAiUsage = new OpenAiApi.Usage(100, 200, 300,
+		OpenAiApi.Usage openAiUsage = new OpenAiApi.Usage(100, 200, 300, null,
 				new OpenAiApi.Usage.CompletionTokenDetails(null));
 		OpenAiUsage usage = OpenAiUsage.from(openAiUsage);
 		assertThat(usage.getReasoningTokens()).isEqualTo(0);
 	}
 
 	@Test
 	void whenCompletionTokenDetailsIsPresent() {
-		OpenAiApi.Usage openAiUsage = new OpenAiApi.Usage(100, 200, 300,
+		OpenAiApi.Usage openAiUsage = new OpenAiApi.Usage(100, 200, 300, null,
 				new OpenAiApi.Usage.CompletionTokenDetails(50));
 		OpenAiUsage usage = OpenAiUsage.from(openAiUsage);
 		assertThat(usage.getReasoningTokens()).isEqualTo(50);
 	}
 
+	@Test
+	void whenCacheTokensIsNull() {
+		OpenAiApi.Usage openAiUsage = new OpenAiApi.Usage(100, 200, 300, new OpenAiApi.Usage.PromptTokensDetails(null),
+				null);
+		OpenAiUsage usage = OpenAiUsage.from(openAiUsage);
+		assertThat(usage.getCachedTokens()).isEqualTo(0);
+	}
+
+	@Test
+	void whenCacheTokensIsPresent() {
+		OpenAiApi.Usage openAiUsage = new OpenAiApi.Usage(100, 200, 300, new OpenAiApi.Usage.PromptTokensDetails(15),
+				null);
+		OpenAiUsage usage = OpenAiUsage.from(openAiUsage);
+		assertThat(usage.getCachedTokens()).isEqualTo(15);
+	}
+
 }