# `PhoenixKitAgent.Turns.History`
[🔗](https://github.com/BeamLabEU/phoenix_kit_agent/blob/v0.1.0/lib/phoenix_kit_agent/turns/history.ex#L1)

What a turn shows the model of the chat so far (spec §6.6): the `user`
messages and the final `assistant` answers of earlier turns, newest kept
first, up to `agent_history_chars`. Tool calls and tool results of earlier
turns are left out — after a loss of rights the model must not see old
data — and so are notices, but for one kind: the outcome of a confirmation
card (`PhoenixKitAgent.Confirmations`) goes in as a `user` message with the
module's own fixed phrase in the user's language — "[confirmation] done:
<the tool's name>", "cancelled", "expired", "the data changed", "failed" —
never anything the tool returned, and never a text a person wrote. So does a
card with no such notice yet, where it stands in the chat: "[confirmation]
waiting: <the tool's name>", so the model knows that its proposal still
waits. Before it reads the chat, a turn gives the cards core no longer holds
their notice (`Confirmations.settle_lapsed_in_turn/2`), so a card that ran
out, or whose click was lost, does not read as waiting.

The extracted text of a message's attachments (the user's own files) is
part of that message; the attachments of one message share `limit` between
them, so that five files cannot by themselves outgrow the window and push
the earlier conversation out of it. A text that holds less than its file
ends with a line that says so (`PhoenixKitAgent.Attachments.Extract`), and
so does one cut to its share here: the model is not left to take part of
the data for all of it.

# `entry`

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

A message as the model reads it.

# `build`

```elixir
@spec build(
  [PhoenixKitAgent.Schemas.Message.t()],
  [PhoenixKitAgent.Schemas.Attachment.t()],
  entry(),
  pos_integer()
) :: [entry()]
```

The model messages for a turn: the earlier `messages` of the chat (oldest
first: `user` and `assistant` messages, the notices of confirmation cards
and the cards, `tool` messages `needs_confirmation`) and then `current`, the
new user message, which is always kept. The earlier ones are kept from the
newest back while the characters of all kept messages stay within `limit`;
the first that does not fit ends the window. `attachments` are the chat's
ready attachments.

# `confirmation_phrase`

```elixir
@spec confirmation_phrase(term(), String.t()) :: String.t() | nil
```

The phrase the model reads for the outcome of a confirmation card of the
tool `action` (the name the model knows it by), or for a card still
`"waiting"`, in the current Gettext locale; `nil` for anything else.

# `user_content`

```elixir
@spec user_content(
  String.t(),
  [PhoenixKitAgent.Schemas.Attachment.t()],
  pos_integer()
) :: String.t()
```

The content of a user message: its text, then each attachment — the text it
carries (cut to its share of `limit`), or, for a picture the model is shown
as pixels, a line that names it (the pixels themselves go with the message of
their own turn only).

---

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