#[non_exhaustive]pub struct TokenUsage {
pub prompt: u64,
pub completion: u64,
pub total: u64,
pub cached: u64,
pub reasoning: u64,
}Expand description
Token consumption reported by a provider, as one increment.
This is the payload of Event::Usage, which is incremental: these five
numbers describe the tokens consumed since the previous usage event of the
same generation, and a consumer adds them up.
use reef_core::runtime::model;
// The common case: a provider that reports one total per call.
let usage = model::TokenUsage::new(1_200, 340);
assert_eq!(usage.total, 1_540);
// A provider that also breaks its counts down. Neither detail is added to
// the count it belongs to; both are already inside it.
let detailed = model::TokenUsage::new(1_200, 340)
.with_cached(900)
.with_reasoning(210);
assert_eq!(detailed.prompt, 1_200);
assert_eq!(detailed.total, 1_540);
assert_eq!(detailed.cached, 900);
assert_eq!(detailed.reasoning, 210);§What the five numbers mean
The two detail fields are parts of the counts above them, not additions to them, which is the convention providers that report them already use. An adapter that added them separately would make every budget over-count.
promptis every input token,cachedincluded.completionis every output token,reasoningincluded.totalis the provider’s own total for this increment.Self::newsets it toprompt + completion, which is what a provider that reports no separate total means;Self::with_totalstates a different one, for a provider that does.
§The fields are public, deliberately
Every other value type in this crate hides its fields, and this one does not,
because the rule is about who has to construct the value rather than about
consistency of style. A struct that a trait method returns — Info, two
types away — must be buildable by every provider that will ever exist, so a
field added later would break all of them, and its fields are private with a
builder in front. A TokenUsage is built inside one optional event, and read
by policies that want all five numbers at once. Privatising the fields would
add five getters to the five setters, make the #[non_exhaustive] above a
no-op that then has to be removed, and buy nothing: the attribute already
stops an external struct literal, so a sixth field stays additive either way.
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.prompt: u64Input tokens consumed, including cached.
completion: u64Output tokens generated, including reasoning.
total: u64Provider-reported total for this increment.
cached: u64The part of prompt that was served from cache.
reasoning: u64The part of completion that was reasoning.
Implementations§
Source§impl TokenUsage
impl TokenUsage
Sourcepub const fn new(prompt: u64, completion: u64) -> Self
pub const fn new(prompt: u64, completion: u64) -> Self
Reports one increment of input and output tokens.
total becomes prompt + completion, saturating; the two detail fields
are zero. Each is stated separately by the builder below when a provider
reports it.
Sourcepub const fn with_total(self, total: u64) -> Self
pub const fn with_total(self, total: u64) -> Self
States a provider-reported total that is not prompt + completion.
Sourcepub const fn with_cached(self, cached: u64) -> Self
pub const fn with_cached(self, cached: u64) -> Self
States how much of prompt came from cache.
Sourcepub const fn with_reasoning(self, reasoning: u64) -> Self
pub const fn with_reasoning(self, reasoning: u64) -> Self
States how much of completion was reasoning.