pyrit.executor.attack.ConversationManager

pyrit.executor.attack.ConversationManager#

class ConversationManager(*, attack_identifier: dict[str, str], prompt_normalizer: PromptNormalizer | None = None)[source]#

Bases: object

Manages conversations for attacks, handling message history, system prompts, and conversation state. This class provides methods to retrieve conversations, add system prompts, and update conversation state with prepended messages.

__init__(*, attack_identifier: dict[str, str], prompt_normalizer: PromptNormalizer | None = None)[source]#

Initialize the conversation manager.

Parameters:

  • attack_identifier (dict[str, str]) – The identifier of the attack this manager belongs to.

  • prompt_normalizer (Optional[PromptNormalizer]) – Optional prompt normalizer to use for converting prompts. If not provided, a default PromptNormalizer instance will be created.

Methods

__init__(*, attack_identifier[, ...])

Initialize the conversation manager.

get_conversation(conversation_id)

Retrieve a conversation by its ID.

get_last_message(*, conversation_id[, role])

Retrieve the most recent message from a conversation.

set_system_prompt(*, target, ...[, labels])

Set or update the system-level prompt associated with a conversation.

update_conversation_state_async(*, ...[, ...])

Prepare a chat conversation by attaching history, enforcing target-specific rules, optionally normalizing prompts, and returning a serializable ConversationState.
get_conversation(conversation_id: str) → List[Message][source]#

Retrieve a conversation by its ID.

Parameters:

conversation_id (str) – The ID of the conversation to retrieve.

Returns:

A list of messages in the conversation, ordered by their creation time.

If no messages exist, an empty list is returned.

Return type:

List[Message]

get_last_message(*, conversation_id: str, role: Literal['system', 'user', 'assistant', 'tool', 'developer'] | None = None) → MessagePiece | None[source]#

Retrieve the most recent message from a conversation.

Parameters:

  • conversation_id (str) – The ID of the conversation to retrieve the last message from.

  • role (Optional[ChatMessageRole]) – If provided, only return the last message that matches this role.

Returns:

The last message piece from the conversation,

or None if no messages exist.

Return type:

Optional[MessagePiece]

set_system_prompt(*, target: PromptChatTarget, conversation_id: str, system_prompt: str, labels: Dict[str, str] | None = None) → None[source]#

Set or update the system-level prompt associated with a conversation.

This helper is intended for conversational (PromptChatTarget) goals, where a dedicated system prompt influences the behavior of the LLM for all subsequent user / assistant messages in the same conversation_id.

Parameters:

  • target (PromptChatTarget) – The target to set the system prompt on.

  • conversation_id (str) – Unique identifier for the conversation to set the system prompt on.

  • system_prompt (str) – The system prompt to set for the conversation.

  • labels (Optional[Dict[str, str]]) – Optional labels to associate with the system prompt. These can be used for categorization or filtering purposes.

async update_conversation_state_async(*, conversation_id: str, target: PromptTarget | PromptChatTarget | None = None, prepended_conversation: List[Message], request_converters: List[PromptConverterConfiguration] | None = None, response_converters: List[PromptConverterConfiguration] | None = None, max_turns: int | None = None) → ConversationState[source]#

Prepare a chat conversation by attaching history, enforcing target-specific rules, optionally normalizing prompts, and returning a serializable ConversationState.

This helper is designed to support two distinct usage patterns:

Single-turn bootstrap - When max_turns is not supplied the function simply injects the provided prepended_conversation into memory, performs any requested prompt conversions, and exits.

Multi-turn continuation - When max_turns is supplied the function acts as a state machine: it verifies that the running history does not exceed the allowed turn budget, excludes the most recent user-utterance (so that an attack can re-inject it as the “live” request), and extracts per-session counters such as the current turn index.

Parameters:

  • conversation_id (str) – Unique identifier for the conversation to update or create.

  • target (Optional[Union[PromptTarget, PromptChatTarget]]) – The target to set system prompts on (if applicable).

  • prepended_conversation (List[Message]) – List of messages to prepend to the conversation history.

  • request_converters (Optional[List[PromptConverterConfiguration]]) – List of configurations for converting user (request) messages.

  • response_converters (Optional[List[PromptConverterConfiguration]]) – List of configurations for converting assistant (response) messages.

  • max_turns (Optional[int]) – Maximum number of turns allowed in the conversation. If not provided, the function assumes a single-turn context.

Returns:

A snapshot of the conversation state after processing the prepended

messages, including turn count and last user message.

Return type:

ConversationState

Raises:

ValueError – If conversation_id is empty or if the last message in a multi-turn context is a user message (which should not be prepended).

Contents