# `Sycophant.Message`

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"}
    ])

# `content_part`

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

# `t`

```elixir
@type t() :: %Sycophant.Message{
  content: String.t() | [content_part()] | nil,
  metadata: map(),
  role: :user | :assistant | :system | :tool_result,
  tool_call_id: String.t() | nil,
  tool_calls: [Sycophant.ToolCall.t()] | nil,
  wire_protocol: atom() | nil
}
```

# `assistant`

```elixir
@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."}>

# `from_map`

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

Deserializes a message from a plain map produced by `Sycophant.Serializable`.

Used internally by the serialization layer for JSON round-tripping.

# `system`

```elixir
@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."}>

# `tool_result`

```elixir
@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`

```elixir
@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?"}>

---

*Consult [api-reference.md](api-reference.md) for complete listing*