[AI] Implement cached token count in usage metadata (#7647)

`UsageMetadata` now includes details about cached token usage.

Author: rlazo

firebase-ai/api.txt

@@ -1373,6 +1373,8 @@ package com.google.firebase.ai.type {
 
   public final class UsageMetadata {
     ctor @Deprecated public UsageMetadata(int promptTokenCount, Integer? candidatesTokenCount, int totalTokenCount, java.util.List<com.google.firebase.ai.type.ModalityTokenCount> promptTokensDetails, java.util.List<com.google.firebase.ai.type.ModalityTokenCount> candidatesTokensDetails, int thoughtsTokenCount);
+    method public java.util.List<com.google.firebase.ai.type.ModalityTokenCount> getCacheTokensDetails();
+    method public int getCachedContentTokenCount();
     method public Integer? getCandidatesTokenCount();
     method public java.util.List<com.google.firebase.ai.type.ModalityTokenCount> getCandidatesTokensDetails();
     method public int getPromptTokenCount();
@@ -1381,6 +1383,8 @@ package com.google.firebase.ai.type {
     method public int getToolUsePromptTokenCount();
     method public java.util.List<com.google.firebase.ai.type.ModalityTokenCount> getToolUsePromptTokensDetails();
     method public int getTotalTokenCount();
+    property public final java.util.List<com.google.firebase.ai.type.ModalityTokenCount> cacheTokensDetails;
+    property public final int cachedContentTokenCount;
     property public final Integer? candidatesTokenCount;
     property public final java.util.List<com.google.firebase.ai.type.ModalityTokenCount> candidatesTokensDetails;
     property public final int promptTokenCount;

firebase-ai/src/main/kotlin/com/google/firebase/ai/type/UsageMetadata.kt

@@ -38,8 +38,10 @@ internal constructor(
   public val promptTokenCount: Int,
   public val candidatesTokenCount: Int?,
   public val totalTokenCount: Int,
+  public val cachedContentTokenCount: Int,
   public val promptTokensDetails: List<ModalityTokenCount>,
   public val candidatesTokensDetails: List<ModalityTokenCount>,
+  public val cacheTokensDetails: List<ModalityTokenCount>,
   public val thoughtsTokenCount: Int,
   public val toolUsePromptTokenCount: Int,
   public val toolUsePromptTokensDetails: List<ModalityTokenCount>
@@ -57,8 +59,10 @@ internal constructor(
     promptTokenCount,
     candidatesTokenCount,
     totalTokenCount,
+    0,
     promptTokensDetails,
     candidatesTokensDetails,
+    emptyList(),
     thoughtsTokenCount,
     0,
     emptyList()
@@ -69,8 +73,10 @@ internal constructor(
     val promptTokenCount: Int? = null,
     val candidatesTokenCount: Int? = null,
     val totalTokenCount: Int? = null,
+    val cachedContentTokenCount: Int? = null,
     val promptTokensDetails: List<ModalityTokenCount.Internal>? = null,
     val candidatesTokensDetails: List<ModalityTokenCount.Internal>? = null,
+    val cacheTokensDetails: List<ModalityTokenCount.Internal>? = null,
     val thoughtsTokenCount: Int? = null,
     val toolUsePromptTokenCount: Int? = null,
     val toolUsePromptTokensDetails: List<ModalityTokenCount.Internal>? = null,
@@ -81,8 +87,10 @@ internal constructor(
         promptTokenCount ?: 0,
         candidatesTokenCount ?: 0,
         totalTokenCount ?: 0,
+        cachedContentTokenCount ?: 0,
         promptTokensDetails = promptTokensDetails?.map { it.toPublic() } ?: emptyList(),
         candidatesTokensDetails = candidatesTokensDetails?.map { it.toPublic() } ?: emptyList(),
+        cacheTokensDetails = cacheTokensDetails?.map { it.toPublic() } ?: emptyList(),
         thoughtsTokenCount ?: 0,
         toolUsePromptTokenCount ?: 0,
         toolUsePromptTokensDetails = toolUsePromptTokensDetails?.map { it.toPublic() }

firebase-ai/src/test/java/com/google/firebase/ai/VertexAIUnarySnapshotTests.kt

@@ -379,6 +379,27 @@ internal class VertexAIUnarySnapshotTests {
       }
     }
 
+  @Test
+  fun `response includes implicit cached metadata`() =
+    goldenVertexUnaryFile("unary-success-implicit-caching.json") {
+      withTimeout(testTimeout) {
+        val response = model.generateContent("prompt")
+
+        response.candidates.isEmpty() shouldBe false
+        response.candidates.first().finishReason shouldBe FinishReason.STOP
+        response.usageMetadata shouldNotBe null
+        response.usageMetadata?.let {
+          it.promptTokenCount shouldBe 12013
+          it.candidatesTokenCount shouldBe 15
+          it.cachedContentTokenCount shouldBe 11243
+          it.cacheTokensDetails.first().let { count ->
+            count.modality shouldBe ContentModality.TEXT
+            count.tokenCount shouldBe 11243
+          }
+        }
+      }
+    }
+
   @Test
   fun `properly translates json text`() =
     goldenVertexUnaryFile("unary-success-constraint-decoding-json.json") {

firebase-ai/update_responses.sh

@@ -17,7 +17,7 @@
 # This script replaces mock response files for Vertex AI unit tests with a fresh
 # clone of the shared repository of Vertex AI test data.
 
-RESPONSES_VERSION='v15.*' # The major version of mock responses to use
+RESPONSES_VERSION='v16.*' # The major version of mock responses to use
 REPO_NAME="vertexai-sdk-test-data"
 REPO_LINK="https://github.com/FirebaseExtended/$REPO_NAME.git"