Struct Usage 

#[non_exhaustive]
pub struct Usage {
    pub prompt_tokens: u32,
    pub completion_tokens: u32,
    pub cache_read_tokens: u32,
    pub cache_creation_tokens: u32,
}

Token usage report.

Marked #[non_exhaustive] — future field additions are additive (no SemVer-major bump required). Code outside klieo-core that constructs a Usage must use Usage::new instead of a struct literal; pattern matching must use the .. rest pattern. In-crate construction is unaffected.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

prompt_tokens: u32

Prompt tokens. For providers with prompt caching (e.g. Anthropic) this is the uncached prompt count; cached tokens are reported separately in Usage::cache_read_tokens / Usage::cache_creation_tokens.

completion_tokens: u32

Completion tokens. Includes reasoning/thinking tokens where the provider bills them as output (e.g. Gemini thoughtsTokenCount).

cache_read_tokens: u32

Prompt tokens served from the provider’s cache. Billed at a reduced tier (Anthropic ~0.1x the input rate); 0 when caching is absent or unused. #[serde(default)] keeps pre-cache Usage JSON deserializable.

cache_creation_tokens: u32

Prompt tokens written to the provider’s cache. Billed at a premium tier (Anthropic ~1.25x the input rate); 0 when caching is absent or unused.

Implementations

impl Usage

pub fn new(prompt_tokens: u32, completion_tokens: u32) -> Self

Prefer this over struct literals outside klieo-core — #[non_exhaustive] forbids external struct-literal construction so that future field additions remain additive. Cache token counts default to 0; set them with Usage::with_cache_tokens.

pub fn with_cache_tokens( self, cache_read_tokens: u32, cache_creation_tokens: u32, ) -> Self

Attach prompt-cache token counts (read = served from cache, creation = written to cache). Both bill at provider-specific tiers distinct from the base prompt rate, so they are tracked apart for correct cost pricing.

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 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 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.