struct

Arcana::AI::Chat::Response

Inherits Struct < Value < Object

Constructors

from_openai_json(raw : String, provider : String = "openai") : self

Parse from an OpenAI-compatible JSON response body.

new(content : String | Nil = nil, tool_calls : Array(ToolCall) = [] of ToolCall, finish_reason : String | Nil = nil, model : String = "", provider : String = "", raw_request : String = "", raw_json : String = "", prompt_tokens : Int32 | Nil = nil, completion_tokens : Int32 | Nil = nil, cache_read_tokens : Int32 | Nil = nil, cache_creation_tokens : Int32 | Nil = nil, thinking_content : String | Nil = nil, reasoning_tokens : Int32 | Nil = nil, server_tool_results : Array(JSON::Any) = [] of JSON::Any)

Instance methods

cache_creation_tokens

cache_creation_tokens=(cache_creation_tokens : Int32 | Nil)

cache_read_tokens

Prompt caching tokens. cache_read_tokens is also OpenAI's usage.prompt_tokens_details.cached_tokens (the part of prompt_tokens served from the cache).

cache_read_tokens=(cache_read_tokens : Int32 | Nil)

Prompt caching tokens. cache_read_tokens is also OpenAI's usage.prompt_tokens_details.cached_tokens (the part of prompt_tokens served from the cache).

completion_tokens

completion_tokens=(completion_tokens : Int32 | Nil)

content

content=(content : String | Nil)

finish_reason

finish_reason=(finish_reason : String | Nil)

has_tool_calls?

model

model=(model : String)

prompt_tokens

Token usage from the API response.

prompt_tokens=(prompt_tokens : Int32 | Nil)

Token usage from the API response.

provider

provider=(provider : String)

raw_json

raw_json=(raw_json : String)

raw_request

raw_request=(raw_request : String)

reasoning_tokens

reasoning_tokens=(reasoning_tokens : Int32 | Nil)

retries

Retries the call needed (rate limits, server or network errors) and the time spent waiting between tries. See RetryPolicy.

retries=(retries : Int32)

Retries the call needed (rate limits, server or network errors) and the time spent waiting between tries. See RetryPolicy.

retry_wait

retry_wait=(retry_wait : Time::Span)

server_tool_results

Server-side tool results (e.g. web_search results).

server_tool_results=(server_tool_results : Array(JSON::Any))

Server-side tool results (e.g. web_search results).

thinking_content

Chain-of-thought / reasoning fields, when the model supports them.

thinking_content — the raw reasoning text if the provider surfaces it (Anthropic extended thinking, Gemini with includeThoughts). OpenAI o-series never surfaces the reasoning itself, so this stays nil for OpenAI even when reasoning ran.

reasoning_tokens — the token count the model spent on reasoning, when reported (OpenAI's completion_tokens_details.reasoning_tokens, Anthropic's cached thinking budget). Useful for cost tracking.

thinking_content=(thinking_content : String | Nil)

Chain-of-thought / reasoning fields, when the model supports them.

thinking_content — the raw reasoning text if the provider surfaces it (Anthropic extended thinking, Gemini with includeThoughts). OpenAI o-series never surfaces the reasoning itself, so this stays nil for OpenAI even when reasoning ran.

reasoning_tokens — the token count the model spent on reasoning, when reported (OpenAI's completion_tokens_details.reasoning_tokens, Anthropic's cached thinking budget). Useful for cost tracking.

tool_call(name : String) : ToolCall | Nil

Find the first tool call matching a given function name.

tool_calls

tool_calls=(tool_calls : Array(ToolCall))

with_retries(stats : RetryStats) : self

Did the model return any tool calls? This response with the retry record of the call that produced it.