AshAi.Transcript (ash_ai v1.5.6)

Copy Markdown View Source

Converts the assistant and tool messages of a tool loop to and from JSON-safe "parts", so they can be stored on a message row and replayed exactly.

A stored reply is an ordered list of parts:

[%{"type" => "step"},
 %{"type" => "reasoning", "text" => "...", "metadata" => ...},
 %{"type" => "text", "text" => "Let me check."},
 %{"type" => "tool_call", "id" => "c1", "name" => "list_items", "arguments" => "{}"},
 %{"type" => "tool_result", "id" => "c1", "content" => "[...]"},
 %{"type" => "step"},
 %{"type" => "text", "text" => "You have 3 items."}]

Each assistant message starts with a "step" part, which carries its message-level metadata. Tool results follow their assistant message. Parts of consecutive messages concatenate, so to_parts(a) ++ to_parts(b) equals to_parts(a ++ b), which lets callers append the parts of each {:message, message} event from AshAi.ToolLoop.stream/2 as it arrives.

Reasoning (thinking blocks, signatures, encrypted reasoning) is opaque provider data. Pass reasoning: false to leave it out. Replaying a turn without its reasoning is accepted by current providers, but the model loses that reasoning, and a paused tool round resumes without it.

Provider-specific values are encoded losslessly with AshAi.Transcript.Codec, so stores only need a JSON (or jsonb) column. Encrypt it if tool results or reasoning are sensitive.

Summary

Functions

A stable hash of a system prompt and tool list.

Rebuilds messages from parts created by to_parts/2.

Returns the tool calls in parts that have no result yet, in call order.

Removes reasoning from messages.

Returns the text the assistant wrote, joined across steps.

Converts assistant and tool messages to parts.

Functions

fingerprint(system_prompt, tools)

@spec fingerprint(String.t() | nil, [ReqLLM.Tool.t()]) :: String.t()

A stable hash of a system prompt and tool list.

Store it with a turn that keeps reasoning. If the hash differs when the turn is replayed, call strip_reasoning/1 first: reasoning is bound to the system prompt and tools it was produced with.

from_parts(parts)

@spec from_parts([map()]) :: [ReqLLM.Message.t()]

Rebuilds messages from parts created by to_parts/2.

pending_tool_calls(parts)

@spec pending_tool_calls([map()]) :: [map()]

Returns the tool calls in parts that have no result yet, in call order.

strip_reasoning(messages)

@spec strip_reasoning([ReqLLM.Message.t()]) :: [ReqLLM.Message.t()]

Removes reasoning from messages.

Use it before replaying a turn whose reasoning can no longer be sent, for example when the system prompt or tools changed since it was produced.

text(parts)

@spec text([map()]) :: String.t()

Returns the text the assistant wrote, joined across steps.

to_parts(messages, opts \\ [])

@spec to_parts([ReqLLM.Message.t()], keyword()) :: [map()]

Converts assistant and tool messages to parts.

Options

  • :reasoning - keep thinking and reasoning data. Defaults to true.