pyrit.message_normalizer

Functionality to normalize messages into compatible formats for targets.

ChatMessageNormalizer¶

Bases: MessageListNormalizer[ChatMessage], MessageStringNormalizer

Normalizer that converts a list of Messages to a list of ChatMessages.

This normalizer handles both single-part and multipart messages:

• Single piece messages: content is a simple string

• Multiple piece messages: content is a list of dicts with type/text or type/image_url

Constructor Parameters:

Methods:

normalize_async¶

normalize_async(messages: list[Message]) → list[ChatMessage]

Convert a list of Messages to a list of ChatMessages.

For single-piece text messages, content is a string. For multi-piece or non-text messages, content is a list of content dicts.

Returns:

• list[ChatMessage] — A list of ChatMessage objects.

Raises:

• ValueError — If the messages list is empty.

normalize_string_async¶

normalize_string_async(messages: list[Message]) → str

Convert a list of Messages to a JSON string representation.

This serializes the list of ChatMessages to JSON format.

Returns:

• str — A JSON string representation of the ChatMessages.

ConversationContextNormalizer¶

Bases: MessageStringNormalizer

Normalizer that formats conversation history as turn-based text.

This is the standard format used by attacks like Crescendo and TAP for including conversation context in adversarial chat prompts. The output format is:

Turn 1:
User: <content>
Assistant: <content>

Turn 2:
User: <content>
...

Methods:

normalize_string_async¶

normalize_string_async(messages: list[Message]) → str

Normalize a list of messages into a turn-based context string.

Returns:

• str — A formatted string with turn numbers and role prefixes.

Raises:

• ValueError — If the messages list is empty.

GenericSystemSquashNormalizer¶

Bases: MessageListNormalizer[Message]

Normalizer that combines the first system message with the first user message using generic instruction tags.

Methods:

normalize_async¶

normalize_async(messages: list[Message]) → list[Message]

Return messages with the first system message combined into the first user message.

The format uses generic instruction tags:

Instructions¶

{system_content}

¶

{user_content}

Returns:

• list[Message] — A Message with the system message squashed into the first user message.

Raises:

• ValueError — If the messages list is empty.

MessageListNormalizer¶

Bases: abc.ABC, Generic[T]

Abstract base class for normalizers that return a list of items.

Subclasses specify the type T (e.g., Message, ChatMessage) that the list contains. T must implement the DictConvertible protocol (have a to_dict() method).

Methods:

normalize_async¶

normalize_async(messages: list[Message]) → list[T]

Normalize the list of messages into a list of items.

Returns:

• list[T] — A list of normalized items of type T.

normalize_to_dicts_async¶

normalize_to_dicts_async(messages: list[Message]) → list[dict[str, Any]]

Normalize the list of messages into a list of dictionaries.

This method uses normalize_async and calls to_dict() on each item.

Returns:

• list[dict[str, Any]] — A list of dictionaries representing the normalized messages.

MessageStringNormalizer¶

Bases: abc.ABC

Abstract base class for normalizers that return a string representation.

Use this for formatting messages into text for non-chat targets or context strings.

Methods:

normalize_string_async¶

normalize_string_async(messages: list[Message]) → str

Normalize the list of messages into a string representation.

Returns:

• str — A string representation of the messages.

TokenizerTemplateNormalizer¶

Bases: MessageStringNormalizer

Enable application of the chat template stored in a Hugging Face tokenizer to a list of messages. For more details, see https://huggingface.co/docs/transformers/main/en/chat_templating.

Constructor Parameters:

Methods:

from_model¶

from_model(model_name_or_alias: str, token: Optional[str] = None, system_message_behavior: Optional[TokenizerSystemBehavior] = None) → TokenizerTemplateNormalizer

Create a normalizer from a model name or alias.

This factory method simplifies creating a normalizer by handling tokenizer loading automatically. Use aliases for common models or provide a full HuggingFace model path.

Returns:

• TokenizerTemplateNormalizer — TokenizerTemplateNormalizer configured with the model’s tokenizer.

Raises:

• ValueError — If the tokenizer doesn’t have a chat_template.

normalize_string_async¶

normalize_string_async(messages: list[Message]) → str

Apply the chat template stored in the tokenizer to a list of messages.

Handles system messages based on the configured system_message_behavior:

• “keep”: Pass system messages as-is

• “squash”: Merge system into first user message

• “ignore”: Drop system messages entirely

• “developer”: Change system role to developer role

Returns:

• str — The formatted chat messages as a string.