Skip to contents

A lightweight S3 container for generative model calls. It standardizes finish reasons and token usage across providers and keeps the raw response for advanced users.

Returns the standardized finish reason for an llmr_response.

Returns a list with token counts for an llmr_response.

Convenience check for truncation due to token limits.

Usage

finish_reason(x)

tokens(x)

is_truncated(x)

# S3 method for class 'llmr_response'
as.character(x, ...)

# S3 method for class 'llmr_response'
print(x, ...)

Arguments

x

An llmr_response object.

...

Ignored.

Value

A length-1 character vector or NA_character_.

A list list(sent, rec, total, reasoning, cached). Missing values are NA, meaning the provider did not report the count. total is the provider's own total when it reports one, otherwise sent + rec, and NA when either part is unknown.

Providers count reasoning differently. OpenAI-compatible providers include reasoning tokens in rec (their completion_tokens). Gemini's rec is the visible output only (candidatesTokenCount, zero when Gemini omits it), while its total (totalTokenCount) includes the thoughts; for Gemini, sent also includes tool-use prompt tokens. Where a provider reports them separately, reasoning holds the reasoning or thought tokens.

cached counts prompt tokens the provider read from its cache (cheaper than fresh input tokens); it is NA for providers that do not report cache usage. Anthropic's sent excludes these cache reads; other providers' sent includes them.

TRUE if truncated, otherwise FALSE.

Details

Fields

  • text: character scalar. Assistant reply.

  • provider: character. Provider id (e.g., "openai", "gemini").

  • model: character. Model id as requested in the config.

  • model_version: character. The model identifier the server reports having served (e.g., a dated snapshot). Useful for reproducibility records; NA when the provider does not echo it.

  • finish_reason: one of "stop", "length", "filter", "tool", "other".

  • usage: list with integers sent, rec, total, reasoning, and cached (tokens read from the provider's prompt cache; NA when not reported).

  • thinking: character. Reasoning text when the provider returns it separately (e.g., Anthropic thinking blocks, Gemini thought parts, DeepSeek reasoning_content); NA otherwise.

  • response_id: provider's response identifier if present.

  • duration_s: numeric seconds from request to parse.

  • raw: parsed provider JSON (list).

  • raw_json: raw JSON string.

  • messages, tool_history, tool_loop: tool-loop provenance present on responses returned by call_llm_tools(); respectively, the full conversation, executed-call table, and aggregate loop usage.

Printing

print() shows the text, then a compact status line with model, finish reason, token counts, and a terse hint if truncated or filtered.

Coercion

as.character() extracts text so the object remains drop-in for code that expects a character return.

Examples

# Minimal fabricated example (no network):
r <- structure(
  list(
    text = "Hello!",
    provider = "openai",
    model = "demo",
    finish_reason = "stop",
    usage = list(sent = 12L, rec = 5L, total = 17L, reasoning = NA_integer_),
    response_id = "resp_123",
    duration_s = 0.012,
    raw = list(choices = list(list(message = list(content = "Hello!")))),
    raw_json = "{}"
  ),
  class = "llmr_response"
)
as.character(r)
finish_reason(r)
tokens(r)
print(r)
r <- structure(list(text="hi", model="demo", finish_reason="stop",
  usage=list(sent=1L, rec=1L, total=2L, reasoning=NA_integer_, cached=NA_integer_),
  duration_s=0.01), class="llmr_response")
finish_reason(r)
r <- structure(list(text="hi", model="demo", finish_reason="stop",
  usage=list(sent=1L, rec=1L, total=2L, reasoning=NA_integer_, cached=NA_integer_),
  duration_s=0.01), class="llmr_response")
tokens(r)
r <- structure(list(text="hi", model="demo", finish_reason="stop",
  usage=list(sent=1L, rec=1L, total=2L, reasoning=NA_integer_, cached=NA_integer_),
  duration_s=0.01), class="llmr_response")
is_truncated(r)