Claudio.Messages.Request (Claudio v0.5.0)
View SourceBuilder for constructing Messages API requests.
Example
alias Claudio.Messages.Request
Request.new("claude-sonnet-4-5-20250929")
|> Request.add_message(:user, "Hello!")
|> Request.set_system("You are a helpful assistant")
|> Request.set_max_tokens(1024)
|> Request.set_temperature(0.7)
|> Request.to_map()Summary
Functions
Adds MCP (Model Context Protocol) server definitions.
Adds a message to the conversation.
Adds a text message with a document from the Files API.
Adds a text message with an image from a base64-encoded string.
Adds a text message with an image from a URL.
Adds a tool definition.
Adds a tool definition with prompt caching enabled.
Enables streaming responses.
Enables extended thinking with optional budget.
Creates a new request builder with the specified model.
Sets container identifier for tool reuse.
Sets context management configuration.
Sets the maximum number of tokens to generate.
Sets request metadata.
Sets service tier for capacity selection.
Sets custom stop sequences.
Sets the system prompt.
Sets the system prompt with prompt caching enabled.
Sets the temperature (0.0-1.0).
Sets tool choice strategy.
Sets top_k for sampling from top K options.
Sets top_p for nucleus sampling (0.0-1.0).
Converts the request to a map suitable for the API.
Types
@type role() :: :user | :assistant
@type t() :: %Claudio.Messages.Request{ container: String.t() | map() | nil, context_management: map() | nil, max_tokens: integer() | nil, mcp_servers: [map()] | nil, messages: [map()], metadata: map() | nil, model: String.t(), service_tier: String.t() | nil, stop_sequences: [String.t()] | nil, stream: boolean() | nil, system: String.t() | list() | nil, temperature: float() | nil, thinking: map() | nil, tool_choice: map() | nil, tools: [map()] | nil, top_k: integer() | nil, top_p: float() | nil }
@type tool_choice() :: :auto | :any | {:tool, String.t()} | :none
Functions
@spec add_mcp_server(t(), Claudio.MCP.ServerConfig.t() | map()) :: t()
Adds MCP (Model Context Protocol) server definitions.
Example
Request.new("claude-sonnet-4-5-20250929")
|> Request.add_mcp_server(%{
"name" => "my_server",
"url" => "http://localhost:8080"
})Adds a message to the conversation.
Content can be:
- A string for simple text messages
- A list of content blocks for multimodal messages (text, images, documents)
Examples
# Simple text message
Request.new("claude-3-5-sonnet-20241022")
|> Request.add_message(:user, "What is the weather?")
# Multimodal message with image
Request.new("claude-3-5-sonnet-20241022")
|> Request.add_message(:user, [
%{"type" => "image", "source" => %{
"type" => "base64",
"media_type" => "image/jpeg",
"data" => base64_image
}},
%{"type" => "text", "text" => "What's in this image?"}
])Adds a text message with a document from the Files API.
Example
Request.new("claude-3-5-sonnet-20241022")
|> Request.add_message_with_document(:user, "Summarize this document", "file_abc123")Adds a text message with an image from a base64-encoded string.
Example
Request.new("claude-3-5-sonnet-20241022")
|> Request.add_message_with_image(:user, "What's in this image?", base64_data, "image/jpeg")Adds a text message with an image from a URL.
Example
Request.new("claude-3-5-sonnet-20241022")
|> Request.add_message_with_image_url(:user, "What's in this image?", "https://example.com/image.jpg")Adds a tool definition.
Example
tool = %{
"name" => "get_weather",
"description" => "Get weather for a location",
"input_schema" => %{
"type" => "object",
"properties" => %{
"location" => %{"type" => "string"}
},
"required" => ["location"]
}
}
Request.new("claude-3-5-sonnet-20241022")
|> Request.add_tool(tool)Adds a tool definition with prompt caching enabled.
Useful when you have many tool definitions and want to cache them.
Example
tool = %{
"name" => "get_weather",
"description" => "Get weather for a location",
"input_schema" => %{"type" => "object", "properties" => %{}}
}
Request.new("claude-3-5-sonnet-20241022")
|> Request.add_tool_with_cache(tool)Enables streaming responses.
Example
Request.new("claude-3-5-sonnet-20241022")
|> Request.enable_streaming()Enables extended thinking with optional budget.
Example
Request.new("claude-3-5-sonnet-20241022")
|> Request.enable_thinking(%{"type" => "enabled", "budget_tokens" => 1000})Creates a new request builder with the specified model.
Example
Request.new("claude-sonnet-4-5-20250929")Sets container identifier for tool reuse.
Allows tools to maintain state across requests.
Example
# String container ID
Request.new("claude-3-5-sonnet-20241022")
|> Request.set_container("my-container-123")
# Container config object
Request.new("claude-3-5-sonnet-20241022")
|> Request.set_container(%{
"id" => "my-container",
"ttl" => 3600
})Sets context management configuration.
Controls how context is managed across requests.
Example
Request.new("claude-3-5-sonnet-20241022")
|> Request.set_context_management(%{
"strategy" => "auto",
"max_context_tokens" => 100000
})Sets the maximum number of tokens to generate.
Example
Request.new("claude-3-5-sonnet-20241022")
|> Request.set_max_tokens(1024)Sets request metadata.
Example
Request.new("claude-3-5-sonnet-20241022")
|> Request.set_metadata(%{"user_id" => "123"})Sets service tier for capacity selection.
Options:
"auto"- Automatically select based on availability"standard_only"- Only use standard tier capacity
Example
Request.new("claude-3-5-sonnet-20241022")
|> Request.set_service_tier("auto")Sets custom stop sequences.
Example
Request.new("claude-3-5-sonnet-20241022")
|> Request.set_stop_sequences(["END", "STOP"])Sets the system prompt.
Can be a string or a list of content blocks with optional cache_control.
Examples
# Simple string
Request.new("claude-3-5-sonnet-20241022")
|> Request.set_system("You are a helpful assistant")
# With prompt caching
Request.new("claude-3-5-sonnet-20241022")
|> Request.set_system([
%{
"type" => "text",
"text" => "Long system prompt here...",
"cache_control" => %{"type" => "ephemeral"}
}
])Sets the system prompt with prompt caching enabled.
Options
:ttl- Cache duration, either"5m"(default) or"1h"
Example
Request.new("claude-3-5-sonnet-20241022")
|> Request.set_system_with_cache("Long system prompt...", ttl: "1h")Sets the temperature (0.0-1.0).
Example
Request.new("claude-3-5-sonnet-20241022")
|> Request.set_temperature(0.7)@spec set_tool_choice(t(), tool_choice()) :: t()
Sets tool choice strategy.
Example
Request.new("claude-3-5-sonnet-20241022")
|> Request.set_tool_choice(:auto)
|> Request.set_tool_choice(:any)
|> Request.set_tool_choice({:tool, "get_weather"})
|> Request.set_tool_choice(:none)Sets top_k for sampling from top K options.
Example
Request.new("claude-3-5-sonnet-20241022")
|> Request.set_top_k(40)Sets top_p for nucleus sampling (0.0-1.0).
Example
Request.new("claude-3-5-sonnet-20241022")
|> Request.set_top_p(0.9)Converts the request to a map suitable for the API.