feat(firebaseai): implicit caching, add metadata (#17979)

cynthiajoan · web-flow · commit e5fc7587e372 · 2026-01-28T10:51:42.000-08:00
* add metadata for caching

* fix analyzer

* fix format
diff --git a/packages/firebase_ai/firebase_ai/example/lib/pages/token_count_page.dart b/packages/firebase_ai/firebase_ai/example/lib/pages/token_count_page.dart
@@ -70,6 +70,17 @@ class _TokenCountPageState extends State<TokenCountPage> {
                       child: const Text('Count Tokens'),
                     ),
                   ),
+                  const SizedBox(width: 10),
+                  Expanded(
+                    child: ElevatedButton(
+                      onPressed: !_loading
+                          ? () async {
+                              await _testUsageMetadata();
+                            }
+                          : null,
+                      child: const Text('Usage Metadata'),
+                    ),
+                  ),
                 ],
               ),
             ),
@@ -94,4 +105,41 @@ class _TokenCountPageState extends State<TokenCountPage> {
       _loading = false;
     });
   }
+
+  Future<void> _testUsageMetadata() async {
+    setState(() {
+      _loading = true;
+    });
+
+    const prompt =
+        'Tell a story about a magic backpack and the person who found it.';
+    final content = [Content.text(prompt)];
+    final response = await widget.model.generateContent(content);
+    final usageMetadata = response.usageMetadata;
+
+    if (usageMetadata != null) {
+      final message = '''
+Usage Metadata:
+- promptTokenCount: ${usageMetadata.promptTokenCount}
+- candidatesTokenCount: ${usageMetadata.candidatesTokenCount}
+- totalTokenCount: ${usageMetadata.totalTokenCount}
+- thoughtsTokenCount: ${usageMetadata.thoughtsTokenCount}
+- toolUsePromptTokenCount: ${usageMetadata.toolUsePromptTokenCount}
+- cachedContentTokenCount: ${usageMetadata.cachedContentTokenCount}
+- promptTokensDetails: ${usageMetadata.promptTokensDetails?.map((d) => '${d.modality}: ${d.tokenCount}')}
+- candidatesTokensDetails: ${usageMetadata.candidatesTokensDetails?.map((d) => '${d.modality}: ${d.tokenCount}')}
+- toolUsePromptTokensDetails: ${usageMetadata.toolUsePromptTokensDetails?.map((d) => '${d.modality}: ${d.tokenCount}')}
+- cacheTokensDetails: ${usageMetadata.cacheTokensDetails?.map((d) => '${d.modality}: ${d.tokenCount}')}
+''';
+      _messages.add(MessageData(text: message, fromUser: false));
+    } else {
+      _messages.add(
+        MessageData(text: 'No usage metadata available.', fromUser: false),
+      );
+    }
+
+    setState(() {
+      _loading = false;
+    });
+  }
 }
diff --git a/packages/firebase_ai/firebase_ai/lib/src/api.dart b/packages/firebase_ai/firebase_ai/lib/src/api.dart
@@ -191,6 +191,8 @@ final class UsageMetadata {
     this.promptTokensDetails,
     this.candidatesTokensDetails,
     this.toolUsePromptTokensDetails,
+    this.cacheTokensDetails,
+    this.cachedContentTokenCount,
   });
 
   /// Number of tokens in the prompt.
@@ -217,6 +219,14 @@ final class UsageMetadata {
   /// A list of tokens used by tools whose usage was triggered from a prompt,
   /// broken down by modality.
   final List<ModalityTokenCount>? toolUsePromptTokensDetails;
+
+  /// The number of tokens in the prompt that were served from the cache.
+  /// If implicit caching is not active or no content was cached, this will be 0.
+  final int? cachedContentTokenCount;
+
+  /// Detailed breakdown of the cached tokens by modality (e.g., text, image).
+  /// This list provides granular insight into which parts of the content were cached.
+  final List<ModalityTokenCount>? cacheTokensDetails;
 }
 
 /// Response candidate generated from a [GenerativeModel].
@@ -1526,6 +1536,16 @@ UsageMetadata parseUsageMetadata(Object jsonObject) {
       toolUsePromptTokensDetails.map(_parseModalityTokenCount).toList(),
     _ => null,
   };
+  final cachedContentTokenCount = switch (jsonObject) {
+    {'cachedContentTokenCount': final int cachedContentTokenCount} =>
+      cachedContentTokenCount,
+    _ => null,
+  };
+  final cacheTokensDetails = switch (jsonObject) {
+    {'cacheTokensDetails': final List<Object?> cacheTokensDetails} =>
+      cacheTokensDetails.map(_parseModalityTokenCount).toList(),
+    _ => null,
+  };
   return UsageMetadata._(
     promptTokenCount: promptTokenCount,
     candidatesTokenCount: candidatesTokenCount,
@@ -1535,6 +1555,8 @@ UsageMetadata parseUsageMetadata(Object jsonObject) {
     promptTokensDetails: promptTokensDetails,
     candidatesTokensDetails: candidatesTokensDetails,
     toolUsePromptTokensDetails: toolUsePromptTokensDetails,
+    cachedContentTokenCount: cachedContentTokenCount,
+    cacheTokensDetails: cacheTokensDetails,
   );
 }
 
diff --git a/packages/firebase_ai/firebase_ai/test/response_parsing_test.dart b/packages/firebase_ai/firebase_ai/test/response_parsing_test.dart
@@ -711,7 +711,12 @@ void main() {
       "modality": "TEXT",
       "tokenCount": 76
     }],
-    "toolUsePromptTokenCount": 5
+    "toolUsePromptTokenCount": 5,
+    "cachedContentTokenCount": 10,
+    "cacheTokensDetails": [{
+      "modality": "TEXT",
+      "tokenCount": 10
+    }]
   }
 }
         ''';
@@ -722,6 +727,16 @@ void main() {
           generateContentResponse.text, 'Here is a description of the image:');
       expect(generateContentResponse.usageMetadata?.totalTokenCount, 1913);
       expect(generateContentResponse.usageMetadata?.toolUsePromptTokenCount, 5);
+      expect(
+          generateContentResponse.usageMetadata?.cachedContentTokenCount, 10);
+      expect(
+          generateContentResponse
+              .usageMetadata?.cacheTokensDetails?.first.modality,
+          ContentModality.text);
+      expect(
+          generateContentResponse
+              .usageMetadata?.cacheTokensDetails?.first.tokenCount,
+          10);
       expect(
           generateContentResponse
               .usageMetadata?.promptTokensDetails?[1].modality,
