claude_gleam - v1.0.0

claude/messages

Functions for calling the Anthropic Messages API.

Streaming limitation

The streaming functions (create_stream, build_stream_request) rely on gleam_httpc, which buffers the entire HTTP response before returning. This means SSE events are parsed from the complete buffered body rather than received incrementally as the API generates tokens. For true incremental streaming, a different HTTP client with chunked transfer-encoding support would be required.

The streaming functions are still useful for obtaining the granular SSE event structure (content block deltas, token-level events, etc.) even though all events arrive at once after the response completes.

Types

RequestParams

</>

Bundles all parameters for a Messages API request.

Instead of passing 8 separate named arguments to build_request, create, etc., callers construct a RequestParams value and pass it as one argument.

pub type RequestParams {
  RequestParams(
    config: client.Config,
    model: option.Option(String),
    max_tokens: option.Option(Int),
    messages: List(message.MessageParam),
    tools: tool.Registry,
    system: option.Option(String),
    tool_choice: option.Option(tool.ToolChoice),
    thinking: option.Option(Int),
  )
}

Constructors

Values

build_request

</> 
pub fn build_request(
  params: RequestParams,
) -> Result(request.Request(String), error.ApiError)

Build an HTTP request for the Messages API without sending it.

This is useful for testing and inspection. The request can later be sent with gleam/httpc.send.

build_stream_request

</> 
pub fn build_stream_request(
  params: RequestParams,
) -> Result(request.Request(String), error.ApiError)

Build an HTTP request for the streaming Messages API without sending it.

Identical to build_request but includes "stream": true in the body.

Important limitation: This builds a request intended for streaming, but when sent via gleam_httpc (as create_stream does), the entire response will be buffered before returning. The request itself is correct – the API will respond with SSE-formatted data – but gleam_httpc does not support reading the response incrementally. For true incremental streaming, a different HTTP client with chunked transfer-encoding support would be needed.

create

</> 
pub fn create(
  params: RequestParams,
) -> Result(message.Message, error.ApiError)

Send a Messages API request and return the decoded response.

On success (HTTP 200), decodes the response body into a Message. On error status codes, maps to the appropriate ApiError. On connection failure, returns a ConnectionError.

create_simple

</> 
pub fn create_simple(
  config config: client.Config,
  message message: String,
) -> Result(message.Message, error.ApiError)

Convenience: send a simple user message with config defaults.

create_stream

</> 
pub fn create_stream(
  params: RequestParams,
) -> Result(List(streaming.StreamEvent), error.ApiError)

Send a streaming Messages API request and return parsed SSE events.

Important limitation: This function uses gleam_httpc which buffers the complete HTTP response before returning. The SSE events are parsed from the buffered response body, so events are NOT received incrementally as they are generated by the API. For true streaming, a different HTTP client with chunked transfer-encoding support would be needed.

This function is still useful for obtaining the granular SSE event structure (e.g., content block deltas, token-level events) even though the events arrive all at once after the full response is received.

On success (HTTP 200), parses the body as SSE and returns events. On error status codes, maps to the appropriate ApiError. On connection failure, returns a ConnectionError.

create_with_retry

</> 
pub fn create_with_retry(
  params: RequestParams,
  max_retries: Int,
) -> Result(message.Message, error.ApiError)

Send a Messages API request with automatic retry for transient errors.

Retries on RateLimitError and ServerError up to max_retries times. Uses exponential backoff starting at 1 second, doubling each retry. If a RateLimitError includes a retry_after value, that is used instead.

new_params

</> 
pub fn new_params(
  config config: client.Config,
  messages messages: List(message.MessageParam),
) -> RequestParams

Create a new RequestParams with sensible defaults.

Only config and messages are required. The rest default to None (or an empty tool registry), which causes the API call to use the client-level defaults.

✨ Search Document