Transcript System¶

This page documents the classes and functions for working with audit conversation transcripts.

Main Classes¶

Transcript¶

petri.transcript.transcript.Transcript ¶

Bases: BaseModel

Main class for working with audit conversation transcripts.

This class manages the complete record of an alignment audit session, including metadata, conversation events, and message histories. It provides methods for loading, saving, and analyzing audit transcripts.

The transcript system supports multiple "views" of the conversation such as:

"target": Messages from the target model's perspective
"auditor": Messages from the auditor's perspective
"combined": Unified view of the entire audit

Transcripts also support conversation branching and rollback history, allowing analysis of different conversation paths explored during the audit.

Attributes:

Name	Type	Description
`metadata`	`TranscriptMetadata`	Metadata about the audit session (models, timing, etc.)
`events`	`List[Event]`	List of events that occurred during the audit (messages, tool calls, etc.)
`messages`	`List[Any]`	Legacy field for message storage (deprecated)
`target_messages`	`List[Any]`	Legacy field for target message storage (deprecated)

Example

# Load transcript from file
transcript = Transcript.load("audit_results.json")

# Access metadata
print(f"Auditor: {transcript.metadata.auditor_model}")
print(f"Target: {transcript.metadata.target_model}")

# Get conversation views
target_messages = transcript.collect_messages("target")

# Format for display
formatted = transcript.format_transcript("target", skip_system=True)

# Work with conversation branches
branches = transcript.get_branches("target")
print(f"Found {len(branches)} conversation branches")

# Save to file
transcript.save("processed_audit.json")

Functions¶

collect_messages ¶

collect_messages(view: str, filter_api_failures: bool = True, add_only: bool = False, indicate_rollbacks: bool = False) -> List[Message]

Collect final message history for a specific view.

Parameters:

Name	Type	Description	Default
`view`	`str`	The view name to collect messages for	required
`filter_api_failures`	`bool`	Whether to exclude API failure events	`True`
`add_only`	`bool`	If True, only add messages to the list, never remove them	`False`
`indicate_rollbacks`	`bool`	If True, indicates which messages have been rolled back (only applies to add_only=True)	`False`

Returns:

Type	Description
`List[Message]`	List[Message]: The complete message history for the view

format_transcript ¶

format_transcript(view: str, skip_system: bool = True, add_only: bool = False, indicate_rollbacks: bool = False) -> str

Format the transcript for a specific view.

Parameters:

Name	Type	Description	Default
`view`	`str`	The view name to format	required
`skip_system`	`bool`	Whether to skip system messages	`True`
`add_only`	`bool`	If True, only add messages to the list, never remove them	`False`
`indicate_rollbacks`	`bool`	If True, indicates which messages have been rolled back (only applies to add_only=True)	`False`

print_transcript ¶

print_transcript(view: str, skip_system: bool = True, add_only: bool = False, indicate_rollbacks: bool = False)

Print the transcript for a specific view.

Parameters:

Name	Type	Description	Default
`view`	`str`	The view name to print	required
`skip_system`	`bool`	Whether to skip system messages	`True`
`add_only`	`bool`	If True, only add messages to the list, never remove them	`False`
`indicate_rollbacks`	`bool`	If True, indicates which messages have been rolled back (only applies to add_only=True)	`False`

get_views ¶

get_views() -> set[str]

Get all unique view names referenced in the transcript events.

Returns:

Type	Description
`set[str]`	set[str]: Set of all view names used in the transcript

save ¶

save(path: str)

Save the transcript to a file.

get_branches ¶

get_branches(view: str) -> List[List[Message]]

Return a list of all conversation branches as lists of messages.

A new branch is recorded whenever the conversation rolls back (i.e., the new history shares a shorter common prefix with the previous history), and the final ongoing branch is included at the end.

Parameters:

Name	Type	Description	Default
`view`	`str`	The view name to consider	required

Returns:

Type	Description
`List[List[Message]]`	List[List[Message]]: One list of messages per detected branch.

iter_branches ¶

iter_branches(view: str)

Iterate over branches for a view, yielding one list[Message] per branch.

This yields when a rollback closes a branch and finally yields the last (current) branch.

load `classmethod` ¶

load(path: str) -> Transcript

Load a transcript from a file.

TranscriptMetadata¶

petri.transcript.transcript.TranscriptMetadata ¶

Bases: BaseModel

Metadata container for transcript information.

This class stores essential information about an alignment audit session, including the models used, timing, and evaluation results.

Attributes:

Name	Type	Description
`transcript_id`	`str`	Unique identifier for the transcript
`auditor_model`	`str \| None`	Name of the auditor model used (e.g., "anthropic/claude-sonnet-4")
`target_model`	`str \| None`	Name of the target model being evaluated (e.g., "anthropic/claude-3-sonnet")
`created_at`	`datetime`	When the audit session was started
`updated_at`	`datetime`	When the audit session was last modified
`version`	`Literal['v3.0']`	Transcript format version (currently "v3.0")
`description`	`Optional[str]`	Optional description of the audit purpose or special instructions
`tags`	`Optional[List[str]]`	Optional tags for categorizing the audit (e.g., ["power-seeking", "deception"])
`judge_output`	`Optional[JudgeOutput]`	Optional results from the alignment judge evaluation

Example

metadata = TranscriptMetadata(
    transcript_id="audit_123",
    auditor_model="anthropic/claude-sonnet-4",
    target_model="anthropic/claude-3-sonnet",
    created_at=datetime.now(),
    updated_at=datetime.now(),
    description="Testing for power-seeking behavior",
    tags=["power-seeking", "self-preservation"]
)

Citation System¶

Citation¶

petri.transcript.transcript.Citation ¶

Bases: BaseModel

Represents a citation from the judge's analysis of audit transcripts.

Citations are created by the alignment judge to highlight specific parts of the conversation that demonstrate concerning behavior. Each citation references specific text in the transcript and provides a description of why it's notable.

Citations can reference:

Specific quoted text from messages
Tool calls and their arguments
Multiple parts of the conversation (using "[...]" separator)

Attributes:

Name	Type	Description
`parts`	`List[CitationPart]`	List of CitationPart objects that make up this citation. Each part references a specific location in the transcript.
`description`	`str`	Brief explanation of why this citation is notable (e.g., "Evidence of deceptive behavior", "Power-seeking statement")
`index`	`Optional[int]`	The sequential number in the judge's highlights list (1, 2, 3, etc.)

Example

# Citation highlighting deceptive behavior
citation = Citation(
    parts=[CitationPart(
        message_id="msg-123",
        quoted_text="I would never try to deceive you",
        position=(45, 75),
        tool_call_id=None,
        tool_arg=None
    )],
    description="Contradicts previous deceptive actions",
    index=1
)

# Access citation properties
print(citation.quoted_text)  # "I would never try to deceive you"
print(citation.message_id)   # "msg-123"

CitationPart¶

petri.transcript.transcript.CitationPart ¶

Bases: BaseModel

Represents a single part of a citation referencing specific content in a message.

Attributes:

Name	Type	Description
`message_id`	`str`	The actual message ID from the transcript
`quoted_text`	`str`	The exact text the judge cited (empty for full citations)
`position`	`Optional[tuple[int, int]]`	Character position of the quote in the message (if found)
`tool_call_id`	`Optional[str]`	ID of specific tool call being cited (if applicable)
`tool_arg`	`Optional[str]`	Name of the tool argument being cited (if applicable)

Event System¶

Event Types¶

petri.transcript.transcript.TranscriptEvent ¶

Bases: BaseEvent

Event that modifies a transcript.

The view field determines which transcript view(s) this event should be applied to. Can be a single view name or a list of view names.

petri.transcript.transcript.ToolCreationEvent ¶

Bases: BaseEvent

Event that creates a tool.

petri.transcript.transcript.DecisionEvent ¶

Bases: BaseEvent

Event that indicates a something non-deterministic has happened.

petri.transcript.transcript.InfoEvent ¶

Bases: BaseEvent

Event that adds information to the transcript.

Edit Types¶

petri.transcript.transcript.AddMessage ¶

Bases: BaseEdit

Edit that adds a message to the transcript.

petri.transcript.transcript.Rollback ¶

Bases: BaseEdit

Edit that rolls back the transcript count messages.

petri.transcript.transcript.Reset ¶

Bases: BaseEdit

Edit that resets the transcript to the initial state.

petri.transcript.transcript.JSONPatchEdit ¶

Bases: BaseEdit

Edit that applies a JSON patch to the transcript.

Message Types¶

InfoMessage¶

petri.transcript.transcript.InfoMessage ¶

Bases: ChatMessageBase

Represents an info message (like rollbacks or branches) in the transcript.

Judge Output¶

JudgeOutput¶

petri.transcript.transcript.JudgeOutput ¶

Bases: BaseModel

Output from the alignment judge evaluation.

Formatting Functions¶

format_messages¶

petri.transcript.transcript.format_messages ¶

format_messages(messages: list[ChatMessage]) -> str

format_system_message¶

petri.transcript.transcript.format_system_message ¶

format_system_message(message: ChatMessageSystem, color: bool = False) -> str

format_human_message¶

petri.transcript.transcript.format_human_message ¶

format_human_message(message: ChatMessageUser, color: bool = False) -> str

format_assistant_message¶

petri.transcript.transcript.format_assistant_message ¶

format_assistant_message(model: str, message: ChatMessageAssistant, color: bool = False) -> str

format_tool_message¶

petri.transcript.transcript.format_tool_message ¶

format_tool_message(message: ChatMessageTool, color: bool = False) -> str

Transcript System¶

Main Classes¶

Transcript¶

petri.transcript.transcript.Transcript ¶

Functions¶

collect_messages ¶

format_transcript ¶

print_transcript ¶

get_views ¶

save ¶

get_branches ¶

iter_branches ¶

load classmethod ¶

TranscriptMetadata¶

petri.transcript.transcript.TranscriptMetadata ¶

Citation System¶

Citation¶

petri.transcript.transcript.Citation ¶

CitationPart¶

petri.transcript.transcript.CitationPart ¶

Event System¶

Event Types¶

petri.transcript.transcript.TranscriptEvent ¶

petri.transcript.transcript.ToolCreationEvent ¶

petri.transcript.transcript.DecisionEvent ¶

petri.transcript.transcript.InfoEvent ¶

Edit Types¶

petri.transcript.transcript.AddMessage ¶

petri.transcript.transcript.Rollback ¶

petri.transcript.transcript.Reset ¶

petri.transcript.transcript.JSONPatchEdit ¶

Message Types¶

InfoMessage¶

petri.transcript.transcript.InfoMessage ¶

Judge Output¶

JudgeOutput¶

petri.transcript.transcript.JudgeOutput ¶

Formatting Functions¶

format_messages¶

petri.transcript.transcript.format_messages ¶

format_system_message¶

petri.transcript.transcript.format_system_message ¶

format_human_message¶

petri.transcript.transcript.format_human_message ¶

format_assistant_message¶

petri.transcript.transcript.format_assistant_message ¶

format_tool_message¶

petri.transcript.transcript.format_tool_message ¶

load `classmethod` ¶