Skip to contents

Reads the diagnostic columns produced by call_llm_par() (and call_llm_broadcast() / llm_fn() with .return = "columns") or by llm_mutate(), and returns a one-row tibble of counts and token totals. It reports tokens, not money: sent, received, total, and reasoning tokens are summed with na.rm = TRUE (correct under row batching, which attributes a batch's tokens to its first row and leaves the rest NA). To estimate cost, multiply these by your provider's current per-token prices yourself.

Usage

llm_usage(x, prefix = NULL, price_table = NULL)

Arguments

x

A data frame from call_llm_par() or llm_mutate().

prefix

For an llm_mutate() result, the output column name whose diagnostics to summarize (e.g. "answer"). Inferred automatically when a single diagnostic block is present; required when several are.

price_table

Optional data frame you supply with your provider's current prices, holding columns model, input, and output (US dollars per million tokens), and optionally cached (price per million cached prompt tokens). When given, a cost_estimate column is added: cached tokens are billed at the cached rate (or the input rate if no cached column), the remaining sent tokens at input, and everything beyond the prompt (total_tokens - sent_tokens when both are known, which includes Gemini's thinking tokens; otherwise the received tokens) at output. For Anthropic rows, whose sent count already excludes cache reads, all sent tokens are billed at input. The provider of a row is read from x's provider column, which call_llm_par() results carry, or else from an optional provider column of price_table; results of llm_mutate(), llm_fn(), and llm_batch_fetch() need the latter for Anthropic models, and rows with cached tokens and no known provider draw a warning. Rates must be numeric, finite, and nonnegative, and each model may appear once; a missing cached rate is allowed only for models whose rows have no cached tokens. Cache-write charges are not included. LLMR ships no price list, because prices change and a bundled table would go out of date without notice.

Value

A one-row tibble: n, n_ok, n_failed, ok_rate, n_truncated (finish "length"), n_filtered (finish "filter"), sent_tokens, rec_tokens, total_tokens, reasoning_tokens, cached_tokens (prompt tokens served from the provider's cache, when reported), n_unknown_tokens (rows whose sent, received, or total count was not reported, so the token sums above understate the truth by those rows; failed calls count here when their usage is missing, although providers usually do not bill them, and skipped rows and batch follow-on rows do not), duration_s, (when a batch id column is present) rowpack_calls and rows_per_rowpack, and (when price_table is supplied) cost_estimate in the table's currency.

Examples

res <- tibble::tibble(
  success = c(TRUE, TRUE, FALSE),
  finish_reason = c("stop", "length", "error:rate_limit"),
  sent_tokens = c(10L, 12L, NA_integer_),
  rec_tokens = c(5L, 7L, NA_integer_),
  total_tokens = c(15L, 19L, NA_integer_),
  reasoning_tokens = c(NA_integer_, NA_integer_, NA_integer_),
  duration = c(0.4, 0.5, 0.1)
)
llm_usage(res)