ModelUsage

Implement the model contract and normalize usage and stream output. See the guide.

class zett_agent.model.ModelUsage(input_tokens=0, output_tokens=0, cache_read_tokens=0, cache_write_tokens=0, cache_reported=True, reasoning_tokens=0)

Normalized token and cache measurements reported by a provider adapter.

input_tokens is the complete model input, including cache reads and cache writes. output_tokens includes reasoning tokens. This invariant makes totals and cache-hit ratios comparable across provider schemas.

cache_reported separates a verified cache miss from a protocol that never reports cache counters. Compatible gateways often relay one protocol through another and drop those counters on the way, so a zero without cache_reported means unknown rather than measured.

Parameters:

• input_tokens (int)

• output_tokens (int)

• cache_read_tokens (int)

• cache_write_tokens (int)

• cache_reported (bool)

• reasoning_tokens (int)

input_tokens: int

Total input tokens, including cached input and cache writes.

output_tokens: int

Total generated tokens, including reasoning tokens when reported.

cache_read_tokens: int

Input tokens reused from the provider cache, not extra input tokens.

cache_write_tokens: int

Input tokens written to the provider cache, not extra input tokens.

cache_reported: bool

Whether the response carried cache counters at all; False means unknown.

reasoning_tokens: int

Reasoning subset of output_tokens; zero when not reported.

property total_tokens: int

Return input plus output without double-counting cache or reasoning.

property cache_hit_rate: float | None

Return cached input divided by total input, or None when unknown.

None means there is no ratio to report: the request had no input tokens, or the provider did not report cache counters for it. A protocol that reports cache usage still yields zero for a genuine miss.