#[non_exhaustive]pub struct Usage {
pub input_tokens: Option<u64>,
pub output_tokens: Option<u64>,
pub total_tokens: Option<u64>,
pub cached_input_tokens: Option<u64>,
pub cache_creation_input_tokens: Option<u64>,
pub tool_use_prompt_tokens: Option<u64>,
pub reasoning_tokens: Option<u64>,
pub cost: Option<Cost>,
/* private fields */
}Expand description
The token usage a provider reported for one completion.
Every provider mapping keeps one contract, so the counters read the same way on every provider:
cached_input_tokens + cache_creation_input_tokens <= input_tokens: input counts every prompt token, cache reads and writes included.reasoning_tokens <= output_tokens: output counts every generated token, reasoning included.total_tokens == input_tokens + output_tokens, absent unless both are reported.
A counter the provider did not send is None; a reported zero is
Some(0). Serialized as the same keys, absent when None.
use rig_core::completion::Usage;
let usage = Usage::new().input_tokens(12).output_tokens(3).total_tokens(15);
assert_eq!(usage.input_tokens, Some(12));
assert!(usage.cost.is_none());Fields (Non-exhaustive)§
This struct is marked as non-exhaustive
Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.input_tokens: Option<u64>Every input token of the request: uncached, read from a cache, written to a cache, and any prompt a provider’s hosted tools added.
output_tokens: Option<u64>Every output token, reasoning included.
total_tokens: Option<u64>input_tokens + output_tokens; absent unless both are reported.
cached_input_tokens: Option<u64>The part of input_tokens read from a provider-managed cache.
cache_creation_input_tokens: Option<u64>The part of input_tokens written to a provider-managed cache.
tool_use_prompt_tokens: Option<u64>The part of input_tokens a provider’s hosted tools added to the prompt.
reasoning_tokens: Option<u64>The part of output_tokens spent on internal reasoning (“thinking”,
“thoughts”).
cost: Option<Cost>What the turn cost in USD, when known. Never derived from the token
counters here, and none of them is derived from it. A cost the
provider reports is its figure. One priced from the model’s catalog
spec (Pricing::cost, from the
facts the wire was connected with) is the
standard-tier list price of the counted tokens: it leaves out the
service tier, long-context price tiers and hosted-tool fees (web
search, code execution), so it can be lower than the bill.
Implementations§
Source§impl Usage
impl Usage
Sourcepub fn is_reported(&self) -> bool
pub fn is_reported(&self) -> bool
Whether the provider reported any counter or a cost.
Sourcepub fn tokens_complete(&self) -> bool
pub fn tokens_complete(&self) -> bool
Whether this sum has a figure from every call for each of input,
output and total. false means a summed counter can be lower than
what the calls used. A counter no call reported stays None, which
does not make the sum incomplete, and the detail counters such as
Self::reasoning_tokens are not
considered.
Sourcepub fn context_tokens(&self) -> Option<u64>
pub fn context_tokens(&self) -> Option<u64>
The tokens the call read and wrote, what a conversation’s next
request sends again: Self::total_tokens,
else the input and output tokens. None without input tokens.
Sourcepub fn input_tokens(self, tokens: impl Into<Option<u64>>) -> Usage
pub fn input_tokens(self, tokens: impl Into<Option<u64>>) -> Usage
Set, or with None clear, Self::input_tokens.
Sourcepub fn output_tokens(self, tokens: impl Into<Option<u64>>) -> Usage
pub fn output_tokens(self, tokens: impl Into<Option<u64>>) -> Usage
Set, or with None clear, Self::output_tokens.
Sourcepub fn total_tokens(self, tokens: impl Into<Option<u64>>) -> Usage
pub fn total_tokens(self, tokens: impl Into<Option<u64>>) -> Usage
Set, or with None clear, Self::total_tokens.
Sourcepub fn cached_input_tokens(self, tokens: impl Into<Option<u64>>) -> Usage
pub fn cached_input_tokens(self, tokens: impl Into<Option<u64>>) -> Usage
Set, or with None clear,
Self::cached_input_tokens.
Sourcepub fn cache_creation_input_tokens(
self,
tokens: impl Into<Option<u64>>,
) -> Usage
pub fn cache_creation_input_tokens( self, tokens: impl Into<Option<u64>>, ) -> Usage
Set, or with None clear,
Self::cache_creation_input_tokens.
Sourcepub fn tool_use_prompt_tokens(self, tokens: impl Into<Option<u64>>) -> Usage
pub fn tool_use_prompt_tokens(self, tokens: impl Into<Option<u64>>) -> Usage
Set, or with None clear,
Self::tool_use_prompt_tokens.
Sourcepub fn reasoning_tokens(self, tokens: impl Into<Option<u64>>) -> Usage
pub fn reasoning_tokens(self, tokens: impl Into<Option<u64>>) -> Usage
Set, or with None clear, Self::reasoning_tokens.
Trait Implementations§
Source§impl AddAssign for Usage
Token counters add where an unreported side adds nothing. Cost sums only
when both sides have one: a turn whose cost is unknown makes the sum
unknown, rather than too low. A side that reports nothing at all
(Usage::is_reported is false) adds nothing, so a fold from
Usage::default keeps its first turn’s cost.
impl AddAssign for Usage
Token counters add where an unreported side adds nothing. Cost sums only
when both sides have one: a turn whose cost is unknown makes the sum
unknown, rather than too low. A side that reports nothing at all
(Usage::is_reported is false) adds nothing, so a fold from
Usage::default keeps its first turn’s cost.
The sum is no longer complete when either side
is not, when only one side has input, output or total, or when the right
side reports nothing, which counts as a call that reported nothing. An
empty left side counts as the start of a fold, so fold calls from
Usage::default: empty_call + call leaves no mark.
Source§fn add_assign(&mut self, other: Usage)
fn add_assign(&mut self, other: Usage)
+= operation. Read moreimpl Copy for Usage
Source§impl<'de> Deserialize<'de> for Usage
impl<'de> Deserialize<'de> for Usage
Source§fn deserialize<__D>(
__deserializer: __D,
) -> Result<Usage, <__D as Deserializer<'de>>::Error>where
__D: Deserializer<'de>,
fn deserialize<__D>(
__deserializer: __D,
) -> Result<Usage, <__D as Deserializer<'de>>::Error>where
__D: Deserializer<'de>,
Source§impl From<&EmbeddingUsage> for Usage
The provider’s counts are passed through unchanged, so a reply whose
prompt_tokens exceeds its total_tokens keeps both as sent.
impl From<&EmbeddingUsage> for Usage
The provider’s counts are passed through unchanged, so a reply whose
prompt_tokens exceeds its total_tokens keeps both as sent.