Imp.History (Imp v0.5.0)

Copy Markdown View Source

Immutable conversation history for signature-shaped Imp programs.

A history is a sequence of prior task turns keyed by the same fields as the signature, not raw chat messages. For a signature like "question, history -> answer", a turn can be %{question: "Capital of France?", answer: "Paris"}. Turns are normalized through Imp.Example, so a turn must be a field map or a list of field pairs.

The Chat adapter renders each turn as prior user/assistant messages by splitting the fields according to the active signature, which keeps a history serializable and independent of any one provider's chat message schema.

iex> history =
...>   Imp.History.new()
...>   |> Imp.History.append(%{question: "Capital of France?", answer: "Paris"})
iex> Imp.History.messages(history)
[%{answer: "Paris", question: "Capital of France?"}]

Summary

Functions

Appends one signature-shaped history turn.

Dumps history to a JSON-safe map.

Loads a JSON-safe history map produced by dump/1.

Returns the signature-shaped field maps in insertion order.

Builds history from a list of signature-shaped field maps.

Redacts secret-looking values while preserving history structure.

Types

field_key()

@type field_key() :: atom() | String.t()

t()

@type t() :: %Imp.History{messages: [turn()]}

turn()

@type turn() :: %{optional(field_key()) => term()}

Functions

append(history, turn)

Appends one signature-shaped history turn.

dump(history)

Dumps history to a JSON-safe map.

load!(state)

Loads a JSON-safe history map produced by dump/1.

Existing atoms and typed values are preserved. Loading never creates atoms: a symbolic atom whose owning capability is not loaded becomes its exact name as a string, so earlier turns stay usable after a restart or a capability removal. Dumping the loaded history records that string representation.

Malformed tags and map-key collisions introduced by this conversion are rejected, and a state without a list "messages" raises ArgumentError.

messages(history)

Returns the signature-shaped field maps in insertion order.

new(messages \\ [])

Builds history from a list of signature-shaped field maps.

redact(history, keys \\ Imp.Redaction.default_keys())

Redacts secret-looking values while preserving history structure.