ChatRollout: its context turns, its model turns, how it ended, and the
initialization its model session started from. This page covers what those records hold, how they
are stored and shown, and how they differ from a session’s checkpoint.
Messages and content
Messages areSystemMessage, UserMessage, AssistantMessage, and ToolMessage, each holding a
tuple of typed content blocks. An assistant’s content may include text, tool calls, reasoning,
redacted reasoning, or summarized reasoning, so don’t assume every block has .text. For the
answer’s text alone, keep the ContentText blocks of the turn’s AssistantMessages, as the
judge step’s answer_text does, and keep the
structured rollout for later inspection.
Metadata
Turns (ContextTurn, ModelTurn, UserTurn, ToolTurn), EndRollout, and ChatRollout carry
metadata: a tuple of DynamicData entries, each holding one
tagged dataclass in its stored
form. Whatever produced the turn decides which types it records, so a reader names the type it
expects. find_metadata(metadata, SomeType) returns the first entry of that type, decoded, or
None if there is none; entry.try_as_type(SomeType) does the same for a single entry. An entry
tagged with the type but holding fields that don’t match it raises ConversionError.
A model turn made by an API-backed session records the provider’s response as a ModelResponse,
including its stop reason and usage:
DynamicData.from_tagged:
turn.metadata + (DynamicData.from_tagged(value),).
Transcript, TranscriptGroup, and AgentRun metadata is different: it is a JSON object with
string keys, matching Docent’s metadata.
Storing records
ChatRollout, Transcript, TranscriptGroup, AgentRun, and the concrete session
initializations, such as SetSystemMessage, are fxtr entities, with type IDs of the form
org.transluce.behaviors.<Class>.v<N>, such as org.transluce.behaviors.ChatRollout.v2. A
version is bumped when a type’s stored shape changes, and a record stored under an earlier version
doesn’t load as the current type. Versions are per type: ChatRollout and its turns use .v2,
while messages and ModelResponse use .v1. Only the current version of each type is supported.
A step that returns a ChatRollout has it stored like any other entity
(see Entities and custom types), and
await storage.store(entity) and await storage.load(ref) work on them too. To load a bare ID,
pass the concrete type, as in as_type=ChatRollout, not an abstract base such as
SessionInitialization. A tree of transcripts and groups is stored as one entity, so there is no
need to store each child separately.
A stored rollout includes every field, including initialization. It keeps its initialization
inline, as DynamicData (or an explicit null if there was none), since initialization types are
open-ended. In Python, read it by naming the type you handle, which gives None for
any other type:
temperature=0.0, not
0), and keep transcript metadata to JSON values with string keys.
The step cache can still hold results written under another type version. When changing the
rollout version a project uses, launch under a fresh root or clear the affected steps’ cache
entries before rerunning (see Managing the step cache).
Transcripts
ChatRolloutTranscriptProjection, from behaviors.rollouts.chat, flattens a rollout into a plain
Transcript: await ChatRolloutTranscriptProjection().to_transcript(rollout) gives one message
list, starting with the system message of a recorded SetSystemMessage initialization and
followed by the turns in order, including a final context turn the model never answered.
to_agent_run wraps that transcript in an AgentRun. The projection drops each turn’s metadata,
so judge from the native rollout when you need usage, stop reasons, or other metadata.
Showing conversations in the viewer
Thefxtr-view-behaviors package draws rollouts, transcripts, transcript groups, agent runs, and
system-message initializations as conversations. To use it, spread its behaviorsRenderers into
your project’s bundle:
views/src/bundle.ts
"fxtr-view-behaviors": "link:./vendor/fxtr/packages/fxtr-view-behaviors" to the dependencies in
views/package.json, like the other fxtr packages, and run pnpm install in views/ (see
The renderer package). The package also exports
ChatRolloutView, for a rollout inside a view of your own, and ComparedRollouts.
A rollout’s or a transcript’s conversation view reads a selector param, { message: n }, and
marks and scrolls to that message: the nth of the messages it draws, counting a transcript’s
messages in order, and a rollout’s turn by turn, each turn’s context messages and then its model’s
(not its initialization). A view of your own links to it with that selector, read from an entity
that stores one (see Params of an entity’s
views); MessageSelector and
isMessageSelector are exported for it. This selector is provisional.
Checkpointing sessions
A serializable session can save its state and be restored from it.await session.get_state()
returns the state as DynamicData, tagged with the implementation’s own state type, and
await factory.restore_session(state) starts a session in that state; it raises ConversionError
for a state that isn’t its own. To keep a state as JSON, write
json.dumps(thaw_fxtr_data(state.data)) (thaw_fxtr_data is in fxtr.core.entity_data), and
read it back with DynamicData.from_data(json.loads(text)).
The sessions of chat_session_model_from_api, ScriptedUserSimulator, and the
simulated users
(BaseModelUserSimulator and PilotSteeredUserSimulator) support this, and the
serializable_context_policy_from_* combinators build checkpointable policies when every component
they combine is checkpointable. Generator-based policies can’t be checkpointed, because a
suspended generator can’t be saved.
A checkpoint is not a stored record: it is a session’s working state, apart from the transcript
entities and from fxtr’s step cache. fxtr doesn’t resume a partly finished rollout from a
checkpoint: a step that failed partway runs again from the start when its job resumes. Close the
sessions you start yourself with aclose().