> ## Documentation Index
> Fetch the complete documentation index at: https://docs.transluce.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Conversation records and checkpoints

> What a rollout records, how conversations are stored as fxtr entities and flattened into transcripts, and how to checkpoint a session.

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 `AssistantMessage`s, as the
[judge step's](https://docs.transluce.ai/behaviors/guides/language-models#a-judge-step) `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](https://docs.transluce.ai/fxtr/concepts/entities-and-custom-types.md#inline-tagged-unions) 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:

```python theme={null}
from behaviors.types import ModelResponse, find_metadata

response = find_metadata(model_turn.metadata, ModelResponse)
if response is not None:
    print(response.stop_reason.type, response.usage.output_tokens)
```

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`:

```python theme={null}
from dataclasses import dataclass

from behaviors.types import ContentText, ContextTurn, DynamicData, UserMessage, find_metadata
from fxtr.entity_defns.dataclass_bases import TaggedDataclass


@dataclass(frozen=True)
class QuestionIndex(TaggedDataclass, fxtr_type="org.example.my_experiment.QuestionIndex.v1"):
    index: int


turn = ContextTurn(
    messages=(UserMessage(content=(ContentText(text="What is 2 + 2?"),)),),
    available_tools=None,
    metadata=(DynamicData.from_tagged(QuestionIndex(index=0)),),
)
assert find_metadata(turn.metadata, QuestionIndex) == QuestionIndex(index=0)
```

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](https://docs.transluce.ai/behaviors/guides/docent-readings)'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](https://docs.transluce.ai/fxtr/concepts/entities-and-custom-types.md)), 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:

```python theme={null}
from behaviors.types import SetSystemMessage

init = rollout.initialization
set_system = init.try_as_type(SetSystemMessage) if init is not None else None
```

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](https://docs.transluce.ai/fxtr/concepts/managing-the-step-cache.md)).

## 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:

```ts views/src/bundle.ts theme={null}
import type { ViewBundle } from "fxtr-view";
import { behaviorsRenderers } from "fxtr-view-behaviors";

const bundle: ViewBundle = {
  renderers: [...behaviorsRenderers],
};

export default bundle;
```

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](https://docs.transluce.ai/fxtr/reference/renderers#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 `n`th 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](https://docs.transluce.ai/fxtr/reference/renderers#params-of-an-entitys-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](https://docs.transluce.ai/behaviors/guides/policies-and-tools#checkpointing-a-simulated-user)
(`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()`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.