usage_from_mapping#

Connect a provider and configure retries, credentials, and transport. See the guide.

zett_agent.providers.base.usage_from_mapping(payload)[source]#

Normalize token usage returned by OpenAI-compatible chat APIs.

This helper is shared by OpenAIProvider and DeepSeekProvider. Their response fields map as follows:

ModelUsage field     Accepted API fields
-------------------  -------------------------------------------------
input_tokens         prompt_tokens, input_tokens
output_tokens        completion_tokens, output_tokens
cache_read_tokens    prompt_cache_hit_tokens, cache_read_input_tokens,
                     cached_tokens, prompt_tokens_details.cached_tokens,
                     input_tokens_details.cached_tokens
cache_write_tokens   cache_write_tokens, cache_creation_input_tokens,
                     cache_creation_tokens,
                     prompt_tokens_details.cache_write_tokens,
                     input_tokens_details.cache_write_tokens
reasoning_tokens     completion_tokens_details.reasoning_tokens,
                     output_tokens_details.reasoning_tokens

The aliases exist because gateways front one protocol with another and return whichever usage schema their upstream speaks. Reading all of them keeps a relay from silently reporting zero cache reads.

prompt_tokens includes cached input tokens. For DeepSeek it is the sum of prompt_cache_hit_tokens and prompt_cache_miss_tokens; the miss count therefore has no separate destination in ModelUsage. Likewise, completion_tokens includes reasoning tokens rather than being added to them. Both providers return total_tokens, but ModelUsage derives that total from input plus output to preserve one internal invariant.

A payload that carries no cache counter at all leaves cache_reported False, so cache_hit_rate reports unknown instead of a false zero. Anthropic reports input_tokens, cache_read_input_tokens, and cache_creation_input_tokens separately. Gemini reports prompt_token_count, candidates_token_count, cached_content_token_count, and thoughts_token_count. Ollama reports prompt_eval_count and eval_count. Those provider-specific schemas are normalized in their own adapters rather than by this helper.

Parameters:: payload (Mapping[str, JsonValue])
Return type:: ModelUsage