Skip to main content
A rollout returns a 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 are SystemMessage, 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:
To record something of your own, such as which question a context turn asked, define a frozen tagged dataclass with a type ID in a domain you control, and wrap each value with DynamicData.from_tagged:
Add an entry to existing metadata with 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:
fxtr checks stored records strictly: give fields their declared types (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

The fxtr-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
A new project’s renderer package doesn’t depend on it yet: add "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().