# `Omni.Message`
[🔗](https://github.com/aaronrussell/omni/blob/v2.0.0/lib/omni/message.ex#L1)

A message in a conversation.

A message has a role and a list of content blocks. There are two roles,
`:user` and `:assistant`. There is no `:tool` role: a tool result is an
`Omni.Content.ToolResult` block inside a user message.
[Contexts and messages](text-generation.md#contexts-and-messages) shows
messages in a conversation.

```elixir
Omni.message("What is Elixir?")
Omni.message(role: :assistant, content: "A functional language on the BEAM.")
```

## Struct fields

- `:role` - `:user` or `:assistant`
- `:content` - the content blocks, in order (see `t:content/0`)
- `:timestamp` - when the message was created, in UTC. Set by `new/1`
  unless given
- `:origin` - on assistant messages Omni produced, the model that wrote
  the message and the dialect it spoke; otherwise `nil` (see
  [Origin](#module-origin))
- `:private` - data a provider needs back on later turns, which Omni
  writes and reads. Leave it as it is, and keep it when storing messages

## Origin

Thinking blocks and signatures only mean something to the provider that
wrote them. Omni stamps each assistant message it produces with its
origin, and on later requests sends thinking, signatures and `:private`
back only to the same provider and dialect. A message from anywhere else,
or with no origin, is sent without them; its text and tool uses are kept.

# `content`

```elixir
@type content() ::
  Omni.Content.Text.t()
  | Omni.Content.Thinking.t()
  | Omni.Content.Attachment.t()
  | Omni.Content.ToolUse.t()
  | Omni.Content.ToolResult.t()
```

Any content block that can appear in a message.

# `origin`

```elixir
@type origin() :: %{model: {atom(), String.t()}, dialect: module()}
```

The model that wrote an assistant message, and the dialect it spoke.

# `t`

```elixir
@type t() :: %Omni.Message{
  content: [content()],
  origin: origin() | nil,
  private: map(),
  role: :user | :assistant,
  timestamp: DateTime.t()
}
```

A conversation message.

# `new`

```elixir
@spec new(Enumerable.t() | String.t() | t()) :: t()
```

Creates a new message from a string, keyword list, or map.

A string is a user message with that text as content. String content is
wrapped in an `Omni.Content.Text` block, and so is each string in a
content list:

```elixir
Message.new(role: :user, content: ["What's in this image?", Attachment.new({:base64, png}, "image/png")])
```

`:timestamp` defaults to `DateTime.utc_now/0`.

`:origin` takes the `Omni.Model` that wrote the message, recorded as its
reference and dialect, or an origin map as is:

```elixir
Message.new(role: :assistant, content: "Hi", origin: model)
```

---

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