pyrit.models.Message

class Message(message_pieces: Sequence[MessagePiece], *, skip_validation: bool | None = False)

Bases: object

Represents a message in a conversation, for example a prompt or a response to a prompt.

This is a single request to a target. It can contain multiple message pieces.

__init__(message_pieces: Sequence[MessagePiece], *, skip_validation: bool | None = False) → None

Initialize a Message from one or more message pieces.

Parameters:

• message_pieces (Sequence[MessagePiece]) – Pieces belonging to the same message turn.

• skip_validation (Optional[bool]) – Whether to skip consistency validation.

Raises:

ValueError – If no message pieces are provided.

Methods

__init__(message_pieces, *[, skip_validation])	Initialize a Message from one or more message pieces.
duplicate_message()	Create a deep copy of this message with new IDs and timestamp for all message pieces.
flatten_to_message_pieces(messages)	Flatten messages into a single list of message pieces.
from_prompt(*, prompt, role[, prompt_metadata])	Build a single-piece message from prompt text.
from_system_prompt(system_prompt)	Build a message from a system prompt.
get_all_values(messages)	Return all converted values across the provided messages.
get_piece([n])	Return the nth message piece.
get_piece_by_type(*[, data_type, ...])	Return the first message piece matching the given data type, or None.
get_pieces_by_type(*[, data_type, ...])	Return all message pieces matching the given data type.
get_value([n])	Return the converted value of the nth message piece.
get_values()	Return the converted values of all message pieces.
is_error()	Check whether any message piece indicates an error.
set_response_not_in_database()	Set that the prompt is not in the database.
set_simulated_role()	Set the role of all message pieces to simulated_assistant.
to_dict()	Convert the message to a dictionary representation.
validate()	Validate that all message pieces are internally consistent.

Attributes

api_role	Return the API-compatible role of the first message piece.
conversation_id	Return the conversation ID of the first request piece.
is_simulated	Check if this is a simulated assistant response.
role	Use api_role for comparisons or _role for internal storage.
sequence	Return the sequence value of the first request piece.

property api_role: ChatMessageRole

Return the API-compatible role of the first message piece.

Maps simulated_assistant to assistant for API compatibility. All message pieces in a Message should have the same role.

Returns:

Role compatible with external API calls.

Return type:

ChatMessageRole

Raises:

ValueError – If the message has no pieces.

property conversation_id: str

Return the conversation ID of the first request piece.

Returns:

Conversation identifier.

Return type:

str

Raises:

ValueError – If the message has no pieces.

duplicate_message() → Message

Create a deep copy of this message with new IDs and timestamp for all message pieces.

This is useful when you need to reuse a message template but want fresh IDs to avoid database conflicts (e.g., during retry attempts).

The original_prompt_id is intentionally kept the same to track the origin. Generates a new timestamp to reflect when the duplicate is created.

Returns:

A new Message with deep-copied message pieces, new IDs, and fresh timestamp.

Return type:

Message

static flatten_to_message_pieces(messages: Sequence[Message]) → MutableSequence[MessagePiece]

Flatten messages into a single list of message pieces.

Parameters:

messages (Sequence[Message]) – Messages to flatten.

Returns:

Flattened message pieces.

Return type:

MutableSequence[MessagePiece]

classmethod from_prompt(*, prompt: str, role: ChatMessageRole, prompt_metadata: dict[str, str | int] | None = None) → Message

Build a single-piece message from prompt text.

Parameters:

• prompt (str) – Prompt text.

• role (ChatMessageRole) – Role assigned to the message piece.

• prompt_metadata (Optional[Dict[str, Union[str, int]]]) – Optional prompt metadata.

Returns:

Constructed message instance.

Return type:

Message

classmethod from_system_prompt(system_prompt: str) → Message

Build a message from a system prompt.

Parameters:

system_prompt (str) – System instruction text.

Returns:

Constructed system-role message.

Return type:

Message

static get_all_values(messages: Sequence[Message]) → list[str]

Return all converted values across the provided messages.

Parameters:

messages (Sequence[Message]) – Messages to aggregate.

Returns:

Flattened list of converted values.

Return type:

list[str]

get_piece(n: int = 0) → MessagePiece

Return the nth message piece.

Parameters:

n (int) – Zero-based index of the piece to return.

Returns:

Selected message piece.

Return type:

MessagePiece

Raises:

• ValueError – If the message has no pieces.

• IndexError – If the index is out of bounds.

get_piece_by_type(*, data_type: PromptDataType | None = None, original_value_data_type: PromptDataType | None = None, converted_value_data_type: PromptDataType | None = None) → MessagePiece | None

Return the first message piece matching the given data type, or None.

Parameters:

• data_type – Alias for converted_value_data_type (for convenience).

• original_value_data_type – The original_value_data_type to filter by.

• converted_value_data_type – The converted_value_data_type to filter by.

Returns:

The first matching MessagePiece, or None if no match is found.

get_pieces_by_type(*, data_type: PromptDataType | None = None, original_value_data_type: PromptDataType | None = None, converted_value_data_type: PromptDataType | None = None) → list[MessagePiece]

Return all message pieces matching the given data type.

Parameters:

• data_type – Alias for converted_value_data_type (for convenience).

• original_value_data_type – The original_value_data_type to filter by.

• converted_value_data_type – The converted_value_data_type to filter by.

Returns:

A list of matching MessagePiece objects (may be empty).

get_value(n: int = 0) → str

Return the converted value of the nth message piece.

Parameters:

n (int) – Zero-based index of the piece to read.

Returns:

Converted value of the selected message piece.

Return type:

str

Raises:

IndexError – If the index is out of bounds.

get_values() → list[str]

Return the converted values of all message pieces.

Returns:

Converted values for all message pieces.

Return type:

list[str]

is_error() → bool

Check whether any message piece indicates an error.

Returns:

True when any piece has a non-none error flag or error data type.

Return type:

bool

property is_simulated: bool

Check if this is a simulated assistant response.

Simulated responses come from prepended conversations or generated simulated conversations, not from actual target responses.

property role: ChatMessageRole

Use api_role for comparisons or _role for internal storage.

This property is deprecated and will be removed in a future version. Returns api_role for backward compatibility.

Type:

Deprecated

property sequence: int

Return the sequence value of the first request piece.

Returns:

Sequence number for the message turn.

Return type:

int

Raises:

ValueError – If the message has no pieces.

set_response_not_in_database() → None

Set that the prompt is not in the database.

This is needed when we’re scoring prompts or other things that have not been sent by PyRIT

set_simulated_role() → None

Set the role of all message pieces to simulated_assistant.

This marks the message as coming from a simulated conversation rather than an actual target response.

to_dict() → dict[str, object]

Convert the message to a dictionary representation.

Returns:

A dictionary with ‘role’, ‘converted_value’, ‘conversation_id’, ‘sequence’,

and ‘converted_value_data_type’ keys.

Return type:

dict

validate() → None

Validate that all message pieces are internally consistent.

Raises:

ValueError – If piece collection is empty or contains mismatched conversation IDs, sequence numbers, roles, or missing converted values.