calute.session.replay

calute.session.replay#

Session replay and timeline inspection.

Provides ReplayView for exploring recorded session data – filtering by agent, aggregating tool calls, generating timelines, and producing human-readable markdown summaries.

class calute.session.replay.ReplayView(session: SessionRecord, turns: list[calute.session.models.TurnRecord] | None = None)[source]#

Bases: object

Read-only view over a recorded session for inspection and replay.

Provides methods for querying turns, aggregating tool calls, building chronological timelines, filtering by agent, and rendering the session as a human-readable markdown summary.

session#

The underlying SessionRecord being viewed.

turns#

The list of TurnRecord instances visible in this view. May be a subset of the full session when created via filter_by_agent().

Example

>>> from calute.session.models import SessionRecord
>>> record = SessionRecord(session_id="s1")
>>> view = ReplayView(session=record)
>>> len(view.turns)
0
filter_by_agent(agent_id: str) → ReplayView[source]#

Create a new ReplayView containing only turns from a specific agent.

Parameters

agent_id – The agent ID to filter by.

Returns

A new ReplayView with filtered turns.

get_agent_transitions() → list[calute.session.models.AgentTransitionRecord][source]#

Return all agent transitions for the session.

Returns

List of AgentTransitionRecord.

get_timeline() → list[calute.session.replay.TimelineEvent][source]#

Build a chronologically sorted timeline of session events.

Events include turn starts/ends, tool calls, and agent transitions.

Returns

Chronologically sorted list of TimelineEvent.

get_tool_calls() → list[calute.session.models.ToolCallRecord][source]#

Aggregate all tool calls across all turns.

Returns

Flat list of ToolCallRecord from every turn.

get_turn(index_or_id: int | str) → calute.session.models.TurnRecord | None[source]#

Retrieve a turn by integer index or turn_id string.

Parameters

index_or_id – Zero-based index or turn_id.

Returns

The matching TurnRecord, or None if not found.

to_markdown() → str[source]#

Render the session as a human-readable markdown summary.

Returns

Markdown string summarizing the session.

class calute.session.replay.SessionReplay[source]#

Bases: object

Factory for creating ReplayView instances from session records.

This class acts as the primary entry point for replaying recorded sessions. It is stateless and exposes only a static factory method.

Example

>>> from calute.session.models import SessionRecord
>>> record = SessionRecord(session_id="s1")
>>> view = SessionReplay.load(record)
>>> isinstance(view, ReplayView)
True
static load(session: SessionRecord) → ReplayView[source]#

Create a ReplayView from a SessionRecord.

This is the recommended way to start inspecting a recorded session.

Parameters

session – The session record to replay.

Returns

A new ReplayView over the entire session, including all turns and agent transitions.

Example

>>> view = SessionReplay.load(SessionRecord(session_id="s1"))
>>> view.session.session_id
's1'
class calute.session.replay.TimelineEvent(timestamp: str, event_type: str, summary: str, data: dict[str, typing.Any] = <factory>)[source]#

Bases: object

A single event on the session timeline.

timestamp#

ISO 8601 timestamp of the event.

Type

str

event_type#

Category string (turn_start, turn_end, tool_call, agent_transition).

Type

str

summary#

Short human-readable description.

Type

str

data#

Arbitrary data payload for the event.

Type

dict[str, Any]

data: dict[str, Any]#
event_type: str#
summary: str#
timestamp: str#
Contents