## Description `Drupal\ai\Dto\TokenUsageDto` was introduced in ai:1.2.0 as the canonical way to read and set token usage on a `ChatOutput`, but it is not mentioned anywhere in `docs/`. A module developer has no documented way to find out that it exists, what its properties mean, or that the older per-value accessors are on their way out. At the same time, the previous API on `ChatOutput` is deprecated: * `setTotalTokenUsage()`, `setInputTokenUsage()`, `setOutputTokenUsage()`, `setReasoningTokenUsage()`, `setCachedTokenUsage()` * `getTotalTokenUsage()`, `getInputTokenUsage()`, `getOutputTokenUsage()`, `getReasoningTokenUsage()`, `getCachedTokenUsage()` All are marked `@deprecated in ai:1.2.0 and is removed from ai:2.0.0`, pointing at `setTokenUsage()` / `getTokenUsage()`. Contrib modules already consume token usage (ai_metering, ai_observability, and the OpenAI and Anthropic providers), so the deprecation affects real downstream code. Without documentation, module and provider authors have no migration path other than reading the source. ## Tasks * [x] Document `TokenUsageDto`: its five nullable properties (`input`, `output`, `total`, `reasoning`, `cached`), that any of them may be `NULL` when a provider does not report that value, and the `create()` / `toArray()` methods it gets from `DtoBaseMethodsTrait`. * [x] Document the consumer side: getting usage off a response via `$output->getTokenUsage()`, including what to expect for streamed responses, where usage is only available after the stream is fully consumed (`StreamedChatMessageIterator`). * [x] Document the provider side: setting usage via `$output->setTokenUsage(new TokenUsageDto(...))` when implementing an AI provider. * [x] Note the deprecation of the individual `get*TokenUsage()` / `set*TokenUsage()` methods on `ChatOutput` and show the equivalent `TokenUsageDto` call for each. * [x] Decide where this lives — likely `docs/developers/call_chat.md` and `docs/developers/call_chat_streaming.md` for the consumer side, and `docs/developers/writing_an_ai_provider.md` for the provider side, with one canonical description of the DTO that the others link to. ## Acceptance criteria * A developer can find out how to read token usage from a chat response without reading the source of `ChatOutput`. * A provider author can find out how to report token usage from their provider plugin. * Every deprecated `ChatOutput` token usage method has a documented replacement, so the ai:2.0.0 removal has a clear migration path. * Streaming behaviour is called out explicitly, since usage is not populated until the iterator is exhausted. ## Related issues *(optional)* * #3586576 — Add cache-write and tool-use prompt tokens to TokenUsageDto. If that lands, the documentation should cover the added properties too. <!-- If this issue description was significantly AI-generated (entire sections, not autocomplete), please note it in a comment below. See https://www.drupal.org/docs/develop/issues/issue-procedures-and-etiquette/policy-on-the-use-of-ai-when-contributing-to-drupal -->