Accumulated token usage and cost for an agent session.
Updated after every LLM turn via add_turn/4. Cost is computed from the
model's per-token rates and accumulated alongside token counts — it never
decreases, even when messages are rewound.
Summary
Functions
Add one turn's token counts and compute its cost from model.
Build a Usage struct from agent start-up keyword options.
Return a zeroed usage struct.
Types
@type t() :: %Planck.Agent.Usage{ cost: float(), input_tokens: non_neg_integer(), output_tokens: non_neg_integer() }
:input_tokens— total input tokens consumed this session:output_tokens— total output tokens consumed this session:cost— total cost in USD this session
Functions
@spec add_turn(t(), non_neg_integer(), non_neg_integer(), term()) :: t()
Add one turn's token counts and compute its cost from model.
Returns the updated struct. The per-turn cost is calculated from the model's
cost.input and cost.output rates (per million tokens). When the model has
no cost information the cost field is left unchanged.
Build a Usage struct from agent start-up keyword options.
Reads :usage (a map with :input_tokens and :output_tokens) and :cost
to seed the struct when resuming a previous session.
@spec new() :: t()
Return a zeroed usage struct.