Python: fix Anthropic streaming double-counting token usage

[he-yufeng]

Motivation & Context

On the Anthropic streaming path, usage tokens are double-counted. _process_stream_event emits a usage Content on both message_start and message_delta, and ChatResponse.from_updates sums every usage Content it sees. But Anthropic's message_delta usage is a cumulative total for the message, not a per-delta increment (from their streaming docs: "The token counts shown in the usage field of the message_delta event are cumulative"). Summing the message_start seed onto the cumulative message_delta total inflates usage_details: output_token_count lands at 26 when the API reported 25 (the seed is output_tokens: 1), and for server-tool turns that also report cumulative input on message_delta, the prompt tokens get double-counted too.

The streaming total should match what the non-streaming path produces.

Description & Review Guide

• What are the major changes? Anthropic streams cumulative usage snapshots, but from_updates expects each update's usage to be an increment it can sum. _process_stream_event now takes a per-stream emitted_usage accumulator and emits the increment of each snapshot over what has already been emitted, so the summation reconstructs the final cumulative usage instead of inflating it. The accumulator lives in the per-request _stream() generator rather than on the client, so concurrent streams don't interfere, and when no accumulator is passed (a direct single-event call) the snapshot is returned unchanged, so existing callers and tests are untouched.
• What is the impact of these changes? response.usage_details after a streaming Anthropic call now equals the cumulative totals the API reported, matching the non-streaming path. This fixes both the unconditional output-seed inflation and the server-tool input double-count.
• What do you want reviewers to focus on? The reconciliation in _incremental_usage, and that message_start's input-side counts are preserved when message_delta carries only output_tokens (the basic case).

Two regression tests cover the basic case (output 25 / input 10, not 26) and the server-tool case where message_delta also reports cumulative input (output 25 / input 12, not doubled).

Related Issue

Fixes #7143

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass, and I have added new tests where possible

[Copilot]

Pull request overview

Fixes incorrect token accounting for Anthropic streaming responses in the Python Anthropic package by converting Anthropic’s cumulative usage snapshots into incremental usage updates that can be safely summed by ChatResponse.from_updates, aligning streaming totals with the non-streaming path.

Changes:

• Thread a per-stream UsageDetails accumulator through the streaming generator to emit usage increments instead of cumulative snapshots.
• Update _process_stream_event to optionally accept the per-stream accumulator and apply _incremental_usage to both message_start and message_delta usage.
• Add regression tests covering both the basic cumulative-output case and the server-tool cumulative-input case.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
python/packages/anthropic/agent_framework_anthropic/_chat_client.py	Adds per-stream usage reconciliation (_incremental_usage) and threads an accumulator through streaming event processing to prevent double-counting.
python/packages/anthropic/tests/test_anthropic_client.py	Adds regression tests ensuring streaming usage totals match Anthropic-reported cumulative totals for both output-only and input+output delta usage.

[eavanvalkenburg]

overall this is fine, but it is redoing stuff already covered in the core library

[eavanvalkenburg]

we have a built-in helper for this: _types.add_usage_details

[github-actions]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/anthropic/agent_framework_anthropic
_chat_client.py	530	36	93%	467, 470, 555, 676, 688, 776, 810, 900, 939–940, 1018, 1020, 1050–1051, 1135–1137, 1141–1143, 1147–1150, 1185, 1192, 1296, 1306, 1358, 1506–1507, 1524, 1537, 1550, 1575–1576
TOTAL	44606	5214	88%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
9048	33 💤	0 ❌	0 🔥	2m 21s ⏱️

[giles17]

Hey @he-yufeng can you please address the comments on the PR if you're still working on it?

[he-yufeng]

Both addressed in e198d31:

• The string-cast TypedDict views are gone. The emitted accumulator is now a plain dict[str, int], so pyright sees real types across the whole helper (verified 0 errors locally).
• The increment now goes through _types.add_usage_details: the emitted totals are negated and added back, restricted to the keys the current snapshot reports. One subtlety this preserves: a message_delta that reports only a subset of keys must not emit negative corrections for the absent ones, so the negation is filtered by the snapshot's key set.

pytest tests/test_anthropic_client.py: 139 passed, 9 skipped.