feat(conversation): add metrics and usage types and deserializers

[pjkroker]

Problem

Streaming conversation responses from the Bedrock Converse API do not expose model usage or latency information. Consumers have no way to track token consumption or response latency for conversation turns.
Issue number: aws-amplify/amplify-backend#2355

Related PRs (all required for aws-amplify/amplify-backend#2355)

This feature spans 4 repositories. PRs should be merged in this order:

1. amplify-category-api — aws-amplify/amplify-category-api#3448 — Defines AmplifyAIMetrics/AmplifyAIUsage GraphQL types and updates resolvers
2. amplify-data — aws-amplify/amplify-data#697 — Adds TypeScript types and client-side deserializers
3. amplify-backend — aws-amplify/amplify-backend#3148 — Captures metrics/usage from Bedrock streaming response
4. amplify-codegen — aws-amplify/amplify-codegen#1008 — Adds fields to generated introspection metadata

Changes

Adds metrics and usage fields to conversation messages and stream events across the GraphQL schema, TypeScript types, and runtime deserializers.

Specifically:

• AmplifyAIMetrics GraphQL type (latencyMs: Int) added to ConversationSchemaGraphQLTypes.ts
• AmplifyAIUsage GraphQL type (inputTokens, outputTokens, totalTokens) added to ConversationSchemaGraphQLTypes.ts
• metrics and usage fields added to AmplifyAIConversationMessage and AmplifyAIConversationMessageStreamPart
• ConversationMessage TypeScript interface updated with optional metrics and usage
• ConversationStreamEvent types updated — metrics/usage present on turn-done events, never on other event types
• Runtime deserializers (convertItemToConversationMessage, conversationStreamEventDeserializers) pass through metrics and usage when present

Corresponding docs PR, if applicable:

Validation

• Ran yarn build in packages/data-schema — builds cleanly
• Ran yarn test in packages/data-schema — all tests pass
• Added unit tests for convertItemToConversationMessage (metrics/usage present and absent)
• Added unit tests for conversationStreamEventDeserializers (turn-done with metrics/usage, text event without, error event)
• Updated createOnStreamEventFunction tests to include metrics/usage in expected undefined fields
• Added defined behavior tests in 2-expected-use/ai-conversation.ts for list messages and turn-done stream events with metrics/usage
• Updated snapshots for new GraphQL types
• Manually tested against a Bedrock conversation endpoint

Checklist

• If this PR includes a functional change to the runtime or type-level behavior of the code, I have added or updated automated test coverage for this change. (see Testing Strategy README)
• If this PR requires a docs update, I have linked to that docs PR above.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

[changeset-bot]

🦋 Changeset detected

Latest commit: 814af54

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@aws-amplify/data-schema	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR