Sycophant.Message (sycophant v0.5.0)

Represents a message in a conversation.

Messages are the building blocks of LLM conversations. Each message has a :role and :content, with optional :tool_calls for assistant responses and :tool_call_id for tool results.

Use the constructor functions to create messages with the correct role:

iex> Sycophant.Message.user("Hello!")
#Sycophant.Message<%{role: :user, content: "Hello!"}>

iex> Sycophant.Message.system("You are helpful.")
#Sycophant.Message<%{role: :system, content: "You are helpful."}>

iex> Sycophant.Message.assistant("Hi there!")
#Sycophant.Message<%{role: :assistant, content: "Hi there!"}>

Multimodal Content

Content can be a plain string or a list of content parts for multimodal input:

Sycophant.Message.user([
  %Sycophant.Message.Content.Text{text: "What's in this image?"},
  %Sycophant.Message.Content.Image{url: "https://example.com/photo.jpg"}
])

Summary

Types

content_part()

t()

Functions

assistant(content)

Creates an assistant message with the given content.

system(content)

Creates a system message with the given content.

t()

tool_result(tool_call, result)

Creates a tool result message from a tool call and its output.

user(content)

Creates a user message with the given content.

Types

content_part()

@type content_part() ::
  Sycophant.Message.Content.Text.t()
  | Sycophant.Message.Content.Image.t()
  | Sycophant.Message.Content.Document.t()
  | Sycophant.Message.Content.Thinking.t()
  | Sycophant.Message.Content.RedactedThinking.t()

t()

@type t() :: %Sycophant.Message{
  __type__: binary(),
  content:
    nil
    | binary()
    | [
        %Sycophant.Message.Content.Text{
          __type__: binary(),
          citations:
            nil
            | [
                %Sycophant.Citation{
                  __type__: binary(),
                  cited_text: nil | binary(),
                  document_index: nil | integer(),
                  document_title: nil | binary(),
                  end_index: nil | integer(),
                  file_id: nil | binary(),
                  source: nil | binary(),
                  start_index: nil | integer(),
                  title: nil | binary(),
                  type:
                    nil
                    | :page_location
                    | :char_location
                    | :content_block_location
                    | :web_search_result_location
                    | :search_result_location,
                  unit: nil | :page | :char | :block,
                  url: nil | binary()
                }
              ],
          text: binary(),
          type: binary()
        }
        | %Sycophant.Message.Content.Image{
            __type__: binary(),
            data: nil | binary(),
            media_type: nil | binary(),
            type: binary(),
            url: nil | binary()
          }
        | %Sycophant.Message.Content.Document{
            __type__: binary(),
            citations: boolean(),
            data: nil | binary(),
            file_id: nil | binary(),
            media_type: nil | binary(),
            name: nil | binary(),
            type: binary(),
            url: nil | binary()
          }
        | %Sycophant.Message.Content.Thinking{
            __type__: binary(),
            id: nil | binary(),
            signature: nil | binary(),
            summary: nil | binary(),
            text: nil | binary(),
            type: binary()
          }
        | %Sycophant.Message.Content.RedactedThinking{
            __type__: binary(),
            data: binary(),
            type: binary()
          }
      ],
  metadata: any(),
  role: :user | :assistant | :system | :tool_result,
  tool_call_id: nil | binary(),
  tool_calls:
    nil
    | [
        %Sycophant.ToolCall{
          __type__: binary(),
          arguments: any(),
          id: binary(),
          metadata: any(),
          name: binary()
        }
      ],
  wire_protocol:
    nil
    | :anthropic_messages
    | :openai_completions
    | :openai_responses
    | :bedrock_converse
    | :google_gemini
}

Functions

assistant(content)

@spec assistant(String.t() | [content_part()]) :: t()

Creates an assistant message with the given content.

Examples

iex> Sycophant.Message.assistant("Elixir is a functional language.")
#Sycophant.Message<%{role: :assistant, content: "Elixir is a functional language."}>

system(content)

@spec system(String.t() | [content_part()]) :: t()

Creates a system message with the given content.

Examples

iex> Sycophant.Message.system("You are a helpful assistant.")
#Sycophant.Message<%{role: :system, content: "You are a helpful assistant."}>

t()

tool_result(tool_call, result)

@spec tool_result(Sycophant.ToolCall.t(), String.t()) :: t()

Creates a tool result message from a tool call and its output.

Examples

iex> tool_call = %Sycophant.ToolCall{id: "call_123", name: "get_weather", arguments: %{}}
iex> Sycophant.Message.tool_result(tool_call, "72F and sunny")
#Sycophant.Message<%{role: :tool_result, content: "72F and sunny", tool_call_id: "call_123"}>

user(content)

@spec user(String.t() | [content_part()]) :: t()

Creates a user message with the given content.

Examples

iex> Sycophant.Message.user("What is Elixir?")
#Sycophant.Message<%{role: :user, content: "What is Elixir?"}>