@spec decode_object(
  term(),
  LLMDB.Model.t()
  | String.t()
  | {atom(), String.t(), keyword()}
  | {atom(), keyword()},
  keyword()
) :: {:ok, t()} | {:error, term()}

Decode provider response data into a Response with structured object.

Similar to decode_response/2 but specifically for object generation responses. Extracts the structured object from tool calls and validates it against the schema.

Parameters

• raw_data - Raw provider response data
• model_spec - Model specification (supports all formats from ReqLLM.model/1)
• schema - Schema definition for validation

Returns

• {:ok, %ReqLLM.Response{}} with object field populated on success
• {:error, reason} on failure

@spec decode_object_stream(
  term(),
  LLMDB.Model.t()
  | String.t()
  | {atom(), String.t(), keyword()}
  | {atom(), keyword()},
  keyword()
) :: {:ok, t()} | {:error, term()}

Decode provider streaming response data into a Response with object stream.

Similar to decode_response/2 but for streaming object generation. The response will contain a stream of structured objects.

Parameters

• raw_data - Raw provider streaming response data
• model_spec - Model specification (supports all formats from ReqLLM.model/1)
• schema - Schema definition for validation

Returns

• {:ok, %ReqLLM.Response{}} with stream populated on success
• {:error, reason} on failure

@spec decode_response(
  term(),
  LLMDB.Model.t()
  | String.t()
  | {atom(), String.t(), keyword()}
  | {atom(), keyword()}
) :: {:ok, t()} | {:error, term()}

Decode provider response data into a canonical ReqLLM.Response.

This is a façade function that accepts raw provider data and a model specification, and directly calls the provider's decode_response/1 callback for zero-ceremony decoding.

Supports Model struct, string, and tuple inputs, automatically resolving model specifications using ReqLLM.model/1.

Parameters

• raw_data - Raw provider response data or Stream
• model_spec - Model specification in any format supported by ReqLLM.model/1:
  • String: "anthropic:claude-3-sonnet"
  • Tuple: {:anthropic, "claude-3-sonnet", temperature: 0.7}
  • LLMDB.Model struct: %LLMDB.Model{provider: :anthropic, id: "claude-3-sonnet"}

Returns

• {:ok, %ReqLLM.Response{}} on success
• {:error, reason} on failure

Examples

{:ok, response} = ReqLLM.Response.decode_response(raw_json, "anthropic:claude-3-sonnet")
{:ok, response} = ReqLLM.Response.decode_response(raw_json, model_struct)
{:ok, response} = ReqLLM.Response.decode_response(raw_json, {:anthropic, "claude-3-sonnet"})

@spec finish_reason(t()) ::
  :stop | :length | :tool_calls | :content_filter | :error | nil

Get the finish reason for this response.

Examples

iex> ReqLLM.Response.finish_reason(response)
:stop

@spec image(t()) :: ReqLLM.Message.ContentPart.t() | nil

Returns the first image content part (or nil if none).

@spec image_data(t()) :: binary() | nil

Returns the binary data of the first :image part (or nil).

@spec image_url(t()) :: String.t() | nil

Returns the URL of the first :image_url part (or nil).

@spec images(t()) :: [ReqLLM.Message.ContentPart.t()]

Extract image content parts from the response message.

Returns a list of ReqLLM.Message.ContentPart where type is :image or :image_url.

@spec join_stream(t()) :: {:ok, t()} | {:error, term()}

Materialize a streaming response into a complete response.

Consumes the entire stream, builds the complete message, and returns a new response with the stream consumed and message populated.

Examples

{:ok, complete_response} = ReqLLM.Response.join_stream(streaming_response)

@spec object(t()) :: map() | nil

Extracts the generated object from a Response.

@spec object_stream(t()) :: Enumerable.t()

Create a stream of structured objects from a streaming response.

Only yields valid objects from tool call stream chunks, filtering out metadata and other chunk types.

Examples

response
|> ReqLLM.Response.object_stream()
|> Stream.each(&IO.inspect/1)
|> Stream.run()

@spec ok?(t()) :: boolean()

Check if the response completed successfully without errors.

Examples

iex> ReqLLM.Response.ok?(response)
true

@spec reasoning_tokens(t()) :: integer()

Get reasoning token count from the response usage.

Returns the number of reasoning tokens used by reasoning models (GPT-5, o1, o3, etc.) during their internal thinking process. Returns 0 if no reasoning tokens were used.

Examples

iex> ReqLLM.Response.reasoning_tokens(response)
64

@spec text(t()) :: String.t() | nil

Extract text content from the response message.

Returns the concatenated text from all content parts in the assistant message. Returns nil when no message is present. For streaming responses, this may be nil until the stream is joined.

Examples

iex> ReqLLM.Response.text(response)
"Hello! I'm Claude and I can help you with questions."

@spec text_stream(t()) :: Enumerable.t()

Create a stream of text content chunks from a streaming response.

Only yields content from :content type stream chunks, filtering out metadata and other chunk types.

Examples

response
|> ReqLLM.Response.text_stream()
|> Stream.each(&IO.write/1)
|> Stream.run()

@spec thinking(t()) :: String.t() | nil

Extract thinking/reasoning content from the response message.

Returns the concatenated thinking content if the message contains thinking parts, empty string otherwise.

Examples

iex> ReqLLM.Response.thinking(response)
"The user is asking about the weather..."

@spec tool_calls(t()) :: [term()]

Extract tool calls from the response message.

Returns a list of tool calls if the message contains them, empty list otherwise. Always returns normalized maps with .name and .arguments fields.

Examples

iex> ReqLLM.Response.tool_calls(response)
[%{name: "get_weather", arguments: %{location: "San Francisco"}}]

@spec unwrap_object(t()) :: {:ok, map()} | {:error, term()}

Unwraps the object from a structured output response, regardless of mode used.

Handles extraction from:

• json_schema mode: parses from content
• tool modes: extracts from tool call arguments

Examples

{:ok, object} = ReqLLM.Response.unwrap_object(response)
#=> {:ok, %{"name" => "John", "age" => 30}}

@spec usage(t()) :: map() | nil

Get usage statistics for this response.

Examples

iex> ReqLLM.Response.usage(response)
%{input_tokens: 12, output_tokens: 8, total_tokens: 20, reasoning_tokens: 64, input_cost: 0.01, output_cost: 0.02, total_cost: 0.03}