Struct Usage 

pub struct Usage {
    pub prompt_tokens: u64,
    pub completion_tokens: u64,
    pub total_tokens: u64,
    pub cache_read_tokens: u64,
    pub cache_write_tokens: u64,
    pub reasoning_tokens: u64,
    pub server_tool_requests: u64,
}

Token usage for one completion, in a vendor-neutral shape. Used to enforce the cost budget and to record spend in the trace.

Construct with ..Default::default(): fields are added in minor releases — 0.18.0 added the cache, reasoning and server-tool counters below — and a literal naming every field is what a widening breaks.

use io_harness::{Containment, Draw, Ledger, Usage};

let ledger = Ledger::new(&Containment::new(4, 2, 1, 10_000));
let usage = Usage {
    prompt_tokens: 4_000,
    completion_tokens: 500,
    total_tokens: 4_500,
    // Of those 4,000 prompt tokens, 3,000 were served from the provider's
    // cache — which is billed at a fraction of a fresh read, and is why a
    // token-only figure understates nothing but overstates the bill.
    cache_read_tokens: 3_000,
    ..Default::default()
};

// `total_tokens` is the figure the budget is enforced in: the provider's own
// total, taken as reported rather than re-derived from the other two.
assert_eq!(ledger.draw_tokens(usage.total_tokens), Draw::Ok);
assert_eq!(ledger.remaining_tokens(), 5_500);

// The cache counters are a *breakdown* of the prompt, not an addition to it:
// adding them to `total_tokens` would double-count what the provider already
// counted once.
assert!(usage.cache_read_tokens <= usage.prompt_tokens);

// A provider that reports nothing gives `None`, not a zero: an unknown cost
// and a free step are different facts, and the loop treats them differently.
let unknown: Option<Usage> = None;
assert_eq!(unknown.map(|u| u.total_tokens), None);

Fields

prompt_tokens: u64

Tokens in the prompt.

completion_tokens: u64

Tokens the model generated.

total_tokens: u64

Total tokens billed for this completion.

cache_read_tokens: u64

(0.18.0) Prompt tokens served from the provider’s cache rather than read fresh. A breakdown of Usage::prompt_tokens, not an addition to it, and priced far lower — which is the whole reason to record it separately.

cache_write_tokens: u64

(0.18.0) Prompt tokens the provider wrote into its cache on this call. Also a breakdown of Usage::prompt_tokens, and usually priced above a fresh read rather than below it.

reasoning_tokens: u64

(0.18.0) Tokens the model spent reasoning before answering, where the provider reports them separately. A breakdown of Usage::completion_tokens.

server_tool_requests: u64

(0.18.0) Provider-executed tool requests — a server-side web search, say — made while serving this completion. Billed per request rather than per token, so a token-only schema under-reports the money silently.

Zero everywhere until the crate declares such tools (0.22.0). The counter exists first so that adding them is not a second widening of this type.

Trait Implementations

impl Clone for Usage

fn clone(&self) -> Usage

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for Usage

impl Debug for Usage

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Usage

fn default() -> Usage

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Usage

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Eq for Usage

impl PartialEq for Usage

fn eq(&self, other: &Usage) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for Usage

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Usage