#[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>>) -> Self
pub fn input_tokens(self, tokens: impl Into<Option<u64>>) -> Self
Set, or with None clear, Self::input_tokens.
Sourcepub fn output_tokens(self, tokens: impl Into<Option<u64>>) -> Self
pub fn output_tokens(self, tokens: impl Into<Option<u64>>) -> Self
Set, or with None clear, Self::output_tokens.
Sourcepub fn total_tokens(self, tokens: impl Into<Option<u64>>) -> Self
pub fn total_tokens(self, tokens: impl Into<Option<u64>>) -> Self
Set, or with None clear, Self::total_tokens.
Sourcepub fn cached_input_tokens(self, tokens: impl Into<Option<u64>>) -> Self
pub fn cached_input_tokens(self, tokens: impl Into<Option<u64>>) -> Self
Set, or with None clear,
Self::cached_input_tokens.
Sourcepub fn cache_creation_input_tokens(self, tokens: impl Into<Option<u64>>) -> Self
pub fn cache_creation_input_tokens(self, tokens: impl Into<Option<u64>>) -> Self
Set, or with None clear,
Self::cache_creation_input_tokens.
Sourcepub fn tool_use_prompt_tokens(self, tokens: impl Into<Option<u64>>) -> Self
pub fn tool_use_prompt_tokens(self, tokens: impl Into<Option<u64>>) -> Self
Set, or with None clear,
Self::tool_use_prompt_tokens.
Sourcepub fn reasoning_tokens(self, tokens: impl Into<Option<u64>>) -> Self
pub fn reasoning_tokens(self, tokens: impl Into<Option<u64>>) -> Self
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: Self)
fn add_assign(&mut self, other: Self)
+= 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<Self, __D::Error>where
__D: Deserializer<'de>,
fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::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.
Source§fn from(usage: &EmbeddingUsage) -> Self
fn from(usage: &EmbeddingUsage) -> Self
impl StructuralPartialEq for Usage
Auto Trait Implementations§
impl Forget for Usage
impl Freeze for Usage
impl Move for Usage
impl RefUnwindSafe for Usage
impl Send for Usage
impl Sync for Usage
impl Unpin for Usage
impl UnsafeUnpin for Usage
impl UnwindSafe for Usage
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> DeserializeOwned for Twhere
T: for<'de> Deserialize<'de>,
Source§impl<T> Instrument for T
impl<T> Instrument for T
Source§fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
Source§fn in_current_span(self) -> Instrumented<Self> ⓘ
fn in_current_span(self) -> Instrumented<Self> ⓘ
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
self into a Left variant of Either<Self, Self>
if into_left is true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
self into a Left variant of Either<Self, Self>
if into_left(&self) returns true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read more