Token Usage Utils

Helpers for working with token usage payloads.

append_token_usage(token_usages_by_model, token_usage)

Append model-keyed token usage.

Parameters:

Name	Type	Description	Default
token_usages_by_model	dict[str, list[TokenUsage]]	Accumulator grouped by model_id.	required
token_usage	dict[str, TokenUsage] | None	Model-keyed usage to group.	required

merge_token_usage(usages)

Aggregate multiple token usage payloads into one total.

Parameters:

Name	Type	Description	Default
usages	list[TokenUsage]	Usage payloads to merge, e.g. one TokenUsage per judge in a multi-judge run, or one per metric when summing an evaluator's total.	required

Returns:

Type	Description
TokenUsage | None	TokenUsage | None: Summed usage, or None when the list is empty.

Example

merge_token_usage([ ... TokenUsage(input_tokens=10, output_tokens=5), ... TokenUsage(input_tokens=7, output_tokens=2), ... ]) TokenUsage(input_tokens=17, output_tokens=7)

merge_token_usage_by_model(token_usages_by_model)

Merge per-model token usage lists into a dict of totals.

Parameters:

Name	Type	Description	Default
token_usages_by_model	dict[str, list[TokenUsage]]	Grouped usages by model_id.	required

Returns:

Type	Description
dict[str, TokenUsage] | None	dict[str, TokenUsage] | None: Merged usage per model, or None when no valid usages exist.