Claudio.Messages.Response (Claudio v0.6.0)

Extracts all server-side tool use requests (server_tool_use) from the response — e.g. web_search / web_fetch invocations Claude ran on the server. The matching results are web_search_tool_result blocks.

get_text(response)

Extracts all text content from the response.

get_tool_uses(response)

Extracts all tool use requests from the response.

to_assistant_content(response)

Converts the response content into API-shaped assistant content blocks for replaying as the assistant turn in a follow-up request

Types

content_block()

@type content_block() ::
  text_block()
  | thinking_block()
  | redacted_thinking_block()
  | tool_use_block()
  | tool_result_block()
  | mcp_tool_use_block()
  | mcp_tool_result_block()
  | server_tool_use_block()
  | web_search_tool_result_block()

mcp_tool_result_block()

@type mcp_tool_result_block() :: %{
  type: :mcp_tool_result,
  tool_use_id: String.t(),
  server_name: String.t(),
  content: term(),
  is_error: boolean()
}

mcp_tool_use_block()

@type mcp_tool_use_block() :: %{
  type: :mcp_tool_use,
  id: String.t(),
  name: String.t(),
  server_name: String.t(),
  input: map()
}

redacted_thinking_block()

@type redacted_thinking_block() :: %{type: :redacted_thinking, data: String.t()}

server_tool_use_block()

@type server_tool_use_block() :: %{
  type: :server_tool_use,
  id: String.t(),
  name: String.t(),
  input: map()
}

stop_reason()

@type stop_reason() ::
  :end_turn
  | :max_tokens
  | :stop_sequence
  | :tool_use
  | :pause_turn
  | :refusal
  | :model_context_window_exceeded

t()

@type t() :: %Claudio.Messages.Response{
  content: [content_block()],
  id: String.t(),
  model: String.t(),
  role: String.t(),
  stop_reason: stop_reason() | nil,
  stop_sequence: String.t() | nil,
  type: String.t(),
  usage: usage()
}

text_block()

@type text_block() :: %{
  :type => :text,
  :text => String.t(),
  optional(:citations) => list()
}

thinking_block()

@type thinking_block() :: %{
  type: :thinking,
  thinking: String.t(),
  signature: String.t() | nil
}

tool_result_block()

@type tool_result_block() :: %{
  type: :tool_result,
  tool_use_id: String.t(),
  content: String.t() | list()
}

tool_use_block()

@type tool_use_block() :: %{
  type: :tool_use,
  id: String.t(),
  name: String.t(),
  input: map()
}

usage()

@type usage() :: %{
  input_tokens: integer(),
  output_tokens: integer(),
  cache_creation_input_tokens: integer() | nil,
  cache_read_input_tokens: integer() | nil
}

web_search_tool_result_block()

@type web_search_tool_result_block() :: %{
  type: :web_search_tool_result,
  tool_use_id: String.t(),
  content: term()
}

Functions

from_map(data)

@spec from_map(map()) :: t()

Converts a raw API response map into a structured Response.

get_citations(response)

@spec get_citations(t()) :: list()

Aggregates every citation across all text blocks, in document order.

Each entry is the raw citation map as returned by the API (e.g. char_location, page_location, content_block_location, search_result_location, web_search_result_location). Returns [] when no citations are present.

get_mcp_tool_uses(response)

@spec get_mcp_tool_uses(t()) :: [mcp_tool_use_block()]

Extracts all MCP tool use requests from the response.

get_mcp_tool_uses(response, server_name)

@spec get_mcp_tool_uses(t(), String.t()) :: [mcp_tool_use_block()]

Extracts MCP tool use requests from the response for a specific server.

get_server_tool_uses(response)

@spec get_server_tool_uses(t()) :: [server_tool_use_block()]

get_text(response)

@spec get_text(t()) :: String.t()

Extracts all text content from the response.

get_tool_uses(response)

@spec get_tool_uses(t()) :: [tool_use_block()]

Extracts all tool use requests from the response.

to_assistant_content(response)

@spec to_assistant_content(t()) :: [map()]

Converts the response content into API-shaped assistant content blocks for replaying as the assistant turn in a follow-up request:

request
|> Request.add_message(:assistant, Response.to_assistant_content(response))

Emits string-keyed blocks that preserve signature (thinking) and data (redacted_thinking) — both required by the API when continuing an extended-thinking + tool-use conversation. Unknown block types are passed through unchanged (coverage grows in later specs).