Alloy.Message (alloy v0.13.0)

Copy Markdown View Source

Normalized message struct used throughout Alloy.

All providers translate their wire format to/from this struct. Internal format uses content blocks (similar to Anthropic's API) since it's the most expressive.

Content Block Types

Text and tool blocks

  • %{type: "text", text: "..."} - Plain text
  • %{type: "tool_use", id: "...", name: "...", input: %{}} - Tool call from assistant
  • %{type: "tool_result", tool_use_id: "...", content: "..."} - Tool execution result

Media blocks (pass-through — providers map these to their wire format)

  • %{type: "image", mime_type: "image/jpeg", data: "base64..."} - Inline image
  • %{type: "audio", mime_type: "audio/mp3", data: "base64..."} - Inline audio
  • %{type: "video", mime_type: "video/mp4", data: "base64..."} - Inline video
  • %{type: "document", mime_type: "application/pdf", uri: "..."} - URI-referenced document

Alloy Core does not read, transcode, or base64-encode media. It expects callers (e.g. Anvil connectors) to supply pre-encoded data or provider-specific URIs.

Reasoning and provider-specific blocks

Assistant messages can also hold blocks only their own provider can read back: "thinking" with a :signature (Anthropic, Gemini), "redacted_thinking", "reasoning" and "output_item" (OpenAI and xAI raw items), "server_tool_use" and server tool results (Anthropic), and :signature or :thought_signature on text and tool-call blocks (Gemini).

Provenance

The loop records which provider and model wrote each assistant message in :provider and :model, and in :origin a fingerprint of the provider module, its :api_url and its :api_key (a hash; the key itself is never stored). All three are nil for messages you build yourself. When a conversation moves to a different origin — a fallback provider, another account or endpoint, or a different provider after a model switch — normalize_for/3 rewrites the other origin's messages so the new one can read them; see its docs. Persist these fields with your transcripts: without them a reloaded message is sent as it is.

Summary

Functions

Creates an assistant message with text content.

Creates an assistant message with content blocks (used for tool calls).

Creates an inline audio content block.

Creates a URI-referenced document content block.

Creates an inline image content block.

Prepares a conversation for provider configured with config.

The origin fingerprint for a provider and its config: a hash of the module, :api_url and :api_key. Two configs share an origin exactly when they reach the same endpoint with the same credentials.

Extracts plain text from a message, ignoring tool blocks.

Extracts thinking/reasoning text from a message, joining all thinking blocks.

Extracts tool_use blocks from an assistant message.

Creates a user message containing tool results.

Creates a user message with text content.

Creates an inline video content block.

Types

content_block()

@type content_block() :: map()

role()

@type role() :: :user | :assistant

t()

@type t() :: %Alloy.Message{
  content: String.t() | [content_block()],
  model: String.t() | nil,
  origin: String.t() | nil,
  provider: module() | nil,
  role: role()
}

Functions

assistant(text)

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

Creates an assistant message with text content.

assistant_blocks(blocks)

@spec assistant_blocks([content_block()]) :: t()

Creates an assistant message with content blocks (used for tool calls).

audio(mime_type, data)

@spec audio(String.t(), String.t()) :: content_block()

Creates an inline audio content block.

mime_type is typically "audio/mp3", "audio/wav", "audio/ogg", etc. data must be a base64-encoded string of the raw audio bytes.

document(mime_type, uri)

@spec document(String.t(), String.t()) :: content_block()

Creates a URI-referenced document content block.

Used with provider APIs that require pre-uploaded files (e.g. Google File API). uri is the provider-specific URI returned after uploading the file.

image(mime_type, data)

@spec image(String.t(), String.t()) :: content_block()

Creates an inline image content block.

mime_type should be one of "image/jpeg", "image/png", "image/gif", "image/webp". data must be a base64-encoded string of the raw image bytes.

normalize_for(messages, provider, config)

@spec normalize_for([t()], module(), map()) :: [t()]

Prepares a conversation for provider configured with config.

Assistant messages from a different origin (see "Provenance") — another provider module, endpoint or account — are rewritten so provider can read them, following the rules the providers document:

  • thinking becomes plain text (empty thinking is dropped), so the new model keeps the earlier reasoning without a signature it can't verify
  • other provider-specific blocks are dropped: redacted thinking, OpenAI and xAI raw items, server tool records
  • signatures are removed from text and tool-call blocks
  • tool-call ids outside [a-zA-Z0-9_-]{1,64} are rewritten, along with the tool results that answer them
  • a message left with no content is dropped

Messages from the same origin, messages without one (built by hand, or persisted without the provenance fields) and user messages are unchanged. Switching models on one origin changes nothing: Anthropic, OpenAI and Gemini each document that their APIs handle another model's reasoning themselves. The result depends only on the arguments, so the same history is sent as the same bytes on every request.

The loop applies this before every provider request, including fallback providers; call it yourself only when you call a provider directly.

origin(provider, config)

@spec origin(module(), map()) :: String.t()

The origin fingerprint for a provider and its config: a hash of the module, :api_url and :api_key. Two configs share an origin exactly when they reach the same endpoint with the same credentials.

text(message)

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

Extracts plain text from a message, ignoring tool blocks.

Joins the message's text blocks with newlines. Returns "" (never nil) when the message has no text blocks, for example when it only calls tools.

thinking(message)

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

Extracts thinking/reasoning text from a message, joining all thinking blocks.

Returns nil when the message carries no thinking content (plain-text messages and messages without "thinking" blocks).

tool_calls(message)

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

Extracts tool_use blocks from an assistant message.

tool_result_block(tool_use_id, content, is_error \\ false)

@spec tool_result_block(String.t(), String.t(), boolean()) :: content_block()

Builds a tool_result content block.

tool_results(results)

@spec tool_results([content_block()]) :: t()

Creates a user message containing tool results.

user(text)

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

Creates a user message with text content.

video(mime_type, data)

@spec video(String.t(), String.t()) :: content_block()

Creates an inline video content block.

mime_type is typically "video/mp4", "video/webm", etc. data must be a base64-encoded string of the raw video bytes.