# `Dsxir.Primitives.History`

Multi-turn conversation value type. Bind one to a signature input field whose
Zoi type is `Dsxir.Primitives.History`; the chat adapter materializes the
conversation into the prompt sequence.

Distinct from `Dsxir.History` (the `inspect_history` developer tool). The
name overlap mirrors DSPy's `dspy.History` (the value type) and
`dspy.inspect_history` (the debug helper).

Entries are plain maps to keep the struct cheap and serializable:

    %Dsxir.Primitives.History{
      messages: [
        %{role: :user, content: "What is the capital of France?"},
        %{role: :assistant, content: "Paris."}
      ]
    }

# `message`

```elixir
@type message() :: %{role: role(), content: String.t()}
```

# `role`

```elixir
@type role() :: :system | :user | :assistant
```

# `t`

```elixir
@type t() :: %Dsxir.Primitives.History{messages: [message()]}
```

# `new`

```elixir
@spec new([message()]) :: t()
```

Build a new conversation, optionally seeded with `messages`.

# `push`

```elixir
@spec push(t(), role(), String.t()) :: t()
```

Append a message with the given `role` and `content` to the conversation.

# `to_messages`

```elixir
@spec to_messages(t()) :: [Sycophant.Message.t()]
```

Materialize as a list of `%Sycophant.Message{}` for adapter consumption.

---

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