llm_response_record: Flatten one LLM response to a provenance row

In LLMR: Interface for Large Language Model APIs in R

Flatten one LLM response to a provenance row

Description

Turns a single llmr_response (or a caught error) into a one-row tibble with the columns the LLMR family treats as the response contract: response_text, response_id, provider, model, model_version, finish_reason, sent_tokens, rec_tokens, total_tokens, reasoning_tokens, cached_tokens, success, error_message, duration_s, created_at, and request_hash. It is the canonical flattening path: reuse it rather than reaching into a response's fields, so a sealed archive or an audit reconstructs the same columns everywhere.

Usage

llm_response_record(
  x,
  request = NULL,
  config = NULL,
  error = NULL,
  started_at = NULL,
  ended_at = NULL
)

Arguments

x	An llmr_response. If x is a condition (a caught error) it is treated as a failed call. Any other object yields a failed row whose message notes the unexpected class.
request	The messages or prompt that produced x, used together with config to fill request_hash via llm_request_hash(). NULL leaves request_hash as NA.
config	The llm_config() used for the call, for request_hash and to backfill provider/model when the response does not carry them.
error	Optional caught condition to record instead of (or alongside) a missing response; when supplied, the row is a failure carrying its message.
started_at, ended_at	Optional POSIXct/numeric timestamps. When both are given and the response does not report a duration, duration_s is their difference; created_at is ended_at when supplied.

Details

A failure is a record, not a gap. Pass a caught condition (or any non-response object) as error, or as x, and the row carries success = FALSE with the message in error_message; the call is never silently dropped.

Value

A one-row tibble with the response-contract columns.

See Also

llm_request_hash(), llmr_response, llm_usage()

Examples

r <- structure(
  list(text = "Hello!", provider = "openai", model = "demo",
       model_version = NA_character_, finish_reason = "stop",
       usage = list(sent = 12L, rec = 5L, total = 17L,
                    reasoning = NA_integer_, cached = NA_integer_),
       response_id = "resp_123", duration_s = 0.012),
  class = "llmr_response")
llm_response_record(r)
# a caught error is a row too:
llm_response_record(simpleError("boom"))

LLMR documentation built on July 11, 2026, 1:06 a.m.