Skip to content

feat(firebase_ai): expose Live API usage metadata - #18962

Open
jamesblasco wants to merge 4 commits into
firebase:mainfrom
Sparkli-AI:feat/live-api-usage-metadata
Open

jamesblasco wants to merge 4 commits into
firebase:mainfrom
Sparkli-AI:feat/live-api-usage-metadata

Conversation

@jamesblasco

Copy link
Copy Markdown
Contributor

Description

Live API responses currently discard top-level usageMetadata. Add an optional LiveServerResponse.usageMetadata field and populate it with the existing usage metadata parser so callers can inspect token usage, including modality breakdowns. Export ContentModality and ModalityTokenCount through the public package API.

Metadata remains available for metadata-only responses and unrecognized messages. Responses without metadata retain a null value. This is an additive, non-breaking change.

Validation

  • flutter test --no-pub --reporter expanded: 400 passed, 9 skipped.
  • flutter analyze --no-pub lib test: no issues found.
  • Dart formatting and git diff --check: passed.
  • Full package analysis is blocked by missing example/lib/firebase_options.dart in the example integration tests (four existing configuration errors).

Tests cover token counts and modality details, absent and null metadata, metadata-only responses, unknown messages, constructor compatibility, and public type exports.

Related Issues

None linked.

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces support for parsing and exporting usageMetadata within LiveServerResponse, along with comprehensive unit tests. The review feedback highlights opportunities to align with the repository's style guide by making the LiveServerResponse constructor const for immutability and refactoring the tests to avoid using the ! operator for null safety.

@SelaseKay SelaseKay left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @jamesblasco, thanks for the PR. Analyze step needs resolving in ci.

@jamesblasco
jamesblasco force-pushed the feat/live-api-usage-metadata branch from da7327c to b7c5a74 Compare November 18, 2026 09:54
@cynthiajoan

Copy link
Copy Markdown
Contributor

Thanks @jamesblasco for putting this together—and great catch on exporting ContentModality and ModalityTokenCount from the barrel file as well!

Because adding LiveServerResponse.usageMetadata introduces new public API surface, we need to take this through our cross-platform Firebase API review process first so the design stays aligned across all supported SDKs. I've kicked off that internal API review and will follow up here once it's approved so we can move forward with merging.

In the meantime, one implementation detail we caught while testing the Live API wire format across both backends:

  • On Agent Platform (FirebaseAI.agentPlatform()) Live sessions (and unary/streaming generateContent), output token counts are serialized under 'candidatesTokenCount' and 'candidatesTokensDetails'.
  • On Gemini Developer API (FirebaseAI.googleAI()) Live sessions, BidiGenerateContentServerMessage.usageMetadata serializes output token counts under 'responseTokenCount' and 'responseTokensDetails' instead (see the BidiGenerateContentServerMessage UsageMetadata reference).

Because parseUsageMetadata in packages/firebase_ai/firebase_ai/lib/src/api.dart currently only checks 'candidatesTokenCount' and 'candidatesTokensDetails', both fields come back null on FirebaseAI.googleAI() Live sessions. Could you update parseUsageMetadata to fall back to the response-named keys?

  final candidatesTokenCount = switch (jsonObject) {
    {'candidatesTokenCount': final int count} ||
    {'responseTokenCount': final int count} =>
      count,
    _ => null,
  };
  final candidatesTokensDetails = switch (jsonObject) {
    {'candidatesTokensDetails': final List<Object?> details} ||
    {'responseTokensDetails': final List<Object?> details} =>
      details.map(_parseModalityTokenCount).toList(),
    _ => null,
  };

Could you also add a unit test in packages/firebase_ai/firebase_ai/test/live_test.dart covering the 'responseTokenCount' / 'responseTokensDetails' payload shape (and address the CI analyze failure)? Thanks again!

@cynthiajoan cynthiajoan added the blocked: API review Block a PR until Firebase internal API review is done label Nov 18, 2026
@jamesblasco

Copy link
Copy Markdown
Contributor Author

@cynthiajoan thanks for the review. Solved the problem you mentioned. Let's see what is the resolution about making the usageMetadata a public api

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

blocked: API review Block a PR until Firebase internal API review is done

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants