pyrit.models

Public model exports for PyRIT core data structures and helpers.

Functions¶

construct_response_from_request¶

construct_response_from_request(request: MessagePiece, response_text_pieces: list[str], response_type: PromptDataType = 'text', prompt_metadata: Optional[dict[str, Union[str, int]]] = None, error: PromptResponseError = 'none') → Message

Construct a response message from a request message piece.

Returns:

• Message — Constructed response message.

data_serializer_factory¶

data_serializer_factory(data_type: PromptDataType, value: Optional[str] = None, extension: Optional[str] = None, category: AllowedCategories) → DataTypeSerializer

Create a DataTypeSerializer instance.

Returns:

• DataTypeSerializer — An instance of the appropriate serializer.

Raises:

• ValueError — If the category is not provided or invalid.

get_all_harm_definitions¶

get_all_harm_definitions() → dict[str, HarmDefinition]

Load all harm definitions from the standard harm_definition directory.

This function scans the HARM_DEFINITION_PATH directory for all YAML files and loads each one as a HarmDefinition.

Returns:

• dict[str, HarmDefinition] — Dict[str, HarmDefinition]: A dictionary mapping category names to their HarmDefinition objects. The keys are the category names from the YAML files (e.g., “violence”, “hate_speech”).

Raises:

• ValueError — If any YAML file in the directory is invalid.

group_conversation_message_pieces_by_sequence¶

group_conversation_message_pieces_by_sequence(message_pieces: Sequence[MessagePiece]) → MutableSequence[Message]

Example:

>>> message_pieces = [
>>>     MessagePiece(conversation_id=1, sequence=1, text="Given this list of creatures, which is your
>>>     favorite:"),
>>>     MessagePiece(conversation_id=1, sequence=2, text="Good question!"),
>>>     MessagePiece(conversation_id=1, sequence=1, text="Raccoon, Narwhal, or Sloth?"),
>>>     MessagePiece(conversation_id=1, sequence=2, text="I'd have to say raccoons are my favorite!"),
>>> ]
>>> grouped_responses = group_conversation_message_pieces(message_pieces)
... [
...     Message(message_pieces=[
...         MessagePiece(conversation_id=1, sequence=1, text="Given this list of creatures, which is your
...         favorite:"),
...         MessagePiece(conversation_id=1, sequence=1, text="Raccoon, Narwhal, or Sloth?")
...     ]),
...     Message(message_pieces=[
...         MessagePiece(conversation_id=1, sequence=2, text="Good question!"),
...         MessagePiece(conversation_id=1, sequence=2, text="I'd have to say raccoons are my favorite!")
...     ])
... ]

Returns:

• MutableSequence[Message] — MutableSequence[Message]: A list of Message objects representing grouped message pieces. This is ordered by the sequence number.

Raises:

• ValueError — If the conversation ID of any message piece does not match the conversation ID of the first message piece.

group_message_pieces_into_conversations¶

group_message_pieces_into_conversations(message_pieces: Sequence[MessagePiece]) → list[list[Message]]

Example:

>>> message_pieces = [
>>>     MessagePiece(conversation_id="conv1", sequence=1, text="Hello"),
>>>     MessagePiece(conversation_id="conv2", sequence=1, text="Hi there"),
>>>     MessagePiece(conversation_id="conv1", sequence=2, text="How are you?"),
>>>     MessagePiece(conversation_id="conv2", sequence=2, text="I'm good"),
>>> ]
>>> conversations = group_message_pieces_into_conversations(message_pieces)
>>> # Returns a list of 2 conversations:
>>> # [
>>> #   [Message(seq=1), Message(seq=2)],  # conv1
>>> #   [Message(seq=1), Message(seq=2)]   # conv2
>>> # ]

Returns:

• list[list[Message]] — list[list[Message]]: A list of conversations, where each conversation is a list of Message objects grouped by sequence.

sort_message_pieces¶

sort_message_pieces(message_pieces: list[MessagePiece]) → list[MessagePiece]

Group by conversation_id. Order conversations by the earliest timestamp within each conversation_id. Within each conversation, order messages by sequence.

Returns:

• list[MessagePiece] — list[MessagePiece]: Sorted message pieces.

AttackOutcome¶

Bases: str, Enum

Enum representing the possible outcomes of an attack.

Inherits from str so that values serialize naturally in Pydantic models and REST responses without a dedicated mapping function.

AttackResult¶

Bases: StrategyResult

Base class for all attack results.

Methods:

get_active_conversation_ids¶

get_active_conversation_ids() → set[str]

Return the main conversation ID plus pruned (user-visible) related conversation IDs.

Excludes adversarial chat conversations which are internal implementation details.

Returns:

• set[str] — set[str]: Main + pruned conversation IDs.

get_all_conversation_ids¶

get_all_conversation_ids() → set[str]

Return the main conversation ID plus all related conversation IDs.

Returns:

• set[str] — set[str]: All conversation IDs associated with this attack.

get_attack_strategy_identifier¶

get_attack_strategy_identifier() → Optional[ComponentIdentifier]

Return the attack strategy identifier from the composite atomic identifier.

This is the non-deprecated replacement for the attack_identifier property. Extracts and returns the "attack" child from atomic_attack_identifier.

Returns:

• Optional[ComponentIdentifier] — Optional[ComponentIdentifier]: The attack strategy identifier, or None if atomic_attack_identifier is not set.

get_conversations_by_type¶

get_conversations_by_type(conversation_type: ConversationType) → list[ConversationReference]

Return all related conversations of the requested type.

Returns:

• list[ConversationReference] — A list of related conversations matching the specified type.

get_pruned_conversation_ids¶

get_pruned_conversation_ids() → list[str]

Return IDs of pruned (branched) conversations only.

Returns:

• list[str] — list[str]: Pruned conversation IDs.

includes_conversation¶

includes_conversation(conversation_id: str) → bool

Check whether a conversation belongs to this attack (main or any related).

Returns:

• bool — True if the conversation is part of this attack.

AudioPathDataTypeSerializer¶

Bases: DataTypeSerializer

Serializer for audio path values stored on disk.

Constructor Parameters:

Methods:

data_on_disk¶

data_on_disk() → bool

Indicate whether this serializer persists data on disk.

Returns:

• bool — Always True for audio path serializers.

AzureBlobStorageIO¶

Bases: StorageIO

Implementation of StorageIO for Azure Blob Storage.

Constructor Parameters:

Methods:

create_directory_if_not_exists¶

create_directory_if_not_exists(directory_path: Union[Path, str]) → None

Log a no-op directory creation for Azure Blob Storage.

is_file¶

is_file(path: Union[Path, str]) → bool

Check whether the path refers to a file (blob) in Azure Blob Storage.

Returns:

• bool — True when the blob exists and has non-zero content size.

parse_blob_url¶

parse_blob_url(file_path: str) → tuple[str, str]

Parse a blob URL to extract the container and blob name.

Returns:

• tuple[str, str] — tuple[str, str]: Container name and blob name.

Raises:

• ValueError — If file_path is not a valid blob URL.

path_exists¶

path_exists(path: Union[Path, str]) → bool

Check whether a given path exists in the Azure Blob Storage container.

Returns:

• bool — True when the path exists.

read_file¶

read_file(path: Union[Path, str]) → bytes

Asynchronously reads the content of a file (blob) from Azure Blob Storage.

If the provided path is a full URL (e.g., “https://account.blob.core.windows.net/container/dir1/dir2/sample.png”), it extracts the relative blob path (e.g., “dir1/dir2/sample.png”) to correctly access the blob. If a relative path is provided, it will use it as-is.

Returns:

• bytes — The content of the file (blob) as bytes.

Raises:

• Exception — If there is an error in reading the blob file, an exception will be logged and re-raised.

write_file¶

write_file(path: Union[Path, str], data: bytes) → None

Write data to Azure Blob Storage at the specified path.

BinaryPathDataTypeSerializer¶

Bases: DataTypeSerializer

Serializer for generic binary path values stored on disk.

Constructor Parameters:

Methods:

data_on_disk¶

data_on_disk() → bool

Indicate whether this serializer persists data on disk.

Returns:

• bool — Always True for binary path serializers.

ChatMessage¶

Bases: BaseModel

Represents a chat message for API consumption.

The content field can be:

• A simple string for single-part text messages

• A list of dicts for multipart messages (e.g., text + images)

Methods:

from_json¶

from_json(json_str: str) → ChatMessage

Deserialize a ChatMessage from a JSON string.

Returns:

• ChatMessage — A ChatMessage instance.

to_dict¶

to_dict() → dict[str, Any]

Convert the ChatMessage to a dictionary.

Returns:

• dict[str, Any] — A dictionary representation of the message, excluding None values.

to_json¶

to_json() → str

Serialize the ChatMessage to a JSON string.

Returns:

• str — A JSON string representation of the message.

ChatMessageListDictContent¶

Bases: ChatMessage

Deprecated: Use ChatMessage instead.

This class exists for backward compatibility and will be removed in a future version.

Constructor Parameters:

ChatMessagesDataset¶

Bases: BaseModel

Represents a dataset of chat messages.

ConversationReference¶

Immutable reference to a conversation that played a role in the attack.

ConversationStats¶

Lightweight aggregate statistics for a conversation.

Used to build attack summaries without loading full message pieces.

ConversationType¶

Bases: Enum

Types of conversations that can be associated with an attack.

DataTypeSerializer¶

Bases: abc.ABC

Abstract base class for data type normalizers.

Responsible for reading and saving multi-modal data types to local disk or Azure Storage Account.

Methods:

data_on_disk¶

data_on_disk() → bool

Indicate whether the data is stored on disk.

Returns:

• bool — True when data is persisted on disk.

get_data_filename¶

get_data_filename(file_name: Optional[str] = None) → Union[Path, str]

Generate or retrieve a unique filename for the data file.

Returns:

• Union[Path, str] — Union[Path, str]: Full storage path for the generated data file.

Raises:

• TypeError — If the serializer is not configured for on-disk data.

• RuntimeError — If required data subdirectory information is missing.

get_extension¶

get_extension(file_path: str) → str | None

Get the file extension from the file path.

Returns:

• str | None — str | None: File extension (including dot) or None if unavailable.

get_mime_type¶

get_mime_type(file_path: str) → str | None

Get the MIME type of the file path.

Returns:

• str | None — str | None: MIME type if detectable; otherwise None.

get_sha256¶

get_sha256() → str

Compute SHA256 hash for this serializer’s current value.

Returns:

• str — Hex digest of the computed SHA256 hash.

Raises:

• FileNotFoundError — If on-disk data path does not exist.

• ValueError — If in-memory data cannot be converted to bytes.

read_data¶

read_data() → bytes

Read data from storage.

Returns:

• bytes — The data read from storage.

Raises:

• TypeError — If the serializer does not represent on-disk data.

• RuntimeError — If no value is set.

• FileNotFoundError — If the referenced file does not exist.

read_data_base64¶

read_data_base64() → str

Read data from storage and return it as a base64 string.

Returns:

• str — Base64-encoded data.

save_b64_image¶

save_b64_image(data: str | bytes, output_filename: str = None) → None

Save a base64-encoded image to storage.

save_data¶

save_data(data: bytes, output_filename: Optional[str] = None) → None

Save data to storage.

save_formatted_audio¶

save_formatted_audio(data: bytes, num_channels: int = 1, sample_width: int = 2, sample_rate: int = 16000, output_filename: Optional[str] = None) → None

Save PCM16 or similarly formatted audio data to storage.

DiskStorageIO¶

Bases: StorageIO

Implementation of StorageIO for local disk storage.

Methods:

create_directory_if_not_exists¶

create_directory_if_not_exists(path: Union[Path, str]) → None

Asynchronously creates a directory if it doesn’t exist on the local disk.

is_file¶

is_file(path: Union[Path, str]) → bool

Check whether the given path is a file (not a directory).

Returns:

• bool — True if the path is a file, False otherwise.

path_exists¶

path_exists(path: Union[Path, str]) → bool

Check whether a path exists on the local disk.

Returns:

• bool — True if the path exists, False otherwise.

read_file¶

read_file(path: Union[Path, str]) → bytes

Asynchronously reads a file from the local disk.

Returns:

• bytes — The content of the file.

write_file¶

write_file(path: Union[Path, str], data: bytes) → None

Asynchronously writes data to a file on the local disk.

EmbeddingData¶

Bases: BaseModel

Single embedding vector payload with index and object metadata.

EmbeddingResponse¶

Bases: BaseModel

Embedding API response containing vectors, model metadata, and usage.

Methods:

load_from_file¶

load_from_file(file_path: Path) → EmbeddingResponse

Load the embedding response from disk.

Returns:

• EmbeddingResponse — The loaded embedding response.

save_to_file¶

save_to_file(directory_path: Path) → str

Save the embedding response to disk and return the path of the new file.

Returns:

• str — The full path to the file that was saved.

to_json¶

to_json() → str

Serialize this embedding response to JSON.

Returns:

• str — JSON-encoded embedding response.

EmbeddingSupport¶

Bases: ABC

Protocol-like interface for classes that generate text embeddings.

Methods:

generate_text_embedding¶

generate_text_embedding(text: str, kwargs: object = {}) → EmbeddingResponse

Generate text embedding synchronously.

Returns:

• EmbeddingResponse — The embedding response

generate_text_embedding_async¶

generate_text_embedding_async(text: str, kwargs: object = {}) → EmbeddingResponse

Generate text embedding asynchronously.

Returns:

• EmbeddingResponse — The embedding response

EmbeddingUsageInformation¶

Bases: BaseModel

Token usage metadata returned by an embedding API.

ErrorDataTypeSerializer¶

Bases: DataTypeSerializer

Serializer for error payloads stored as in-memory text.

Constructor Parameters:

Methods:

data_on_disk¶

data_on_disk() → bool

Indicate whether this serializer persists data on disk.

Returns:

• bool — Always False for error serializers.

HarmDefinition¶

A harm definition loaded from a YAML file.

This class represents the structured content of a harm definition YAML file, which includes the version, category name, and scale descriptions that define how to score content for this harm category.

Methods:

from_yaml¶

from_yaml(harm_definition_path: Union[str, Path]) → HarmDefinition

Load and validate a harm definition from a YAML file.

The function first checks if the path is a simple filename (e.g., “violence.yaml”) and if so, looks for it in the standard HARM_DEFINITION_PATH directory. Otherwise, it treats the path as a full or relative path.

Returns:

• HarmDefinition — The loaded harm definition.

Raises:

• FileNotFoundError — If the harm definition file does not exist.

• ValueError — If the YAML file is invalid or missing required fields.

get_scale_description¶

get_scale_description(score_value: str) → Optional[str]

Get the description for a specific score value.

Returns:

• Optional[str] — The description for the score value, or None if not found.

validate_category¶

validate_category(category: str, check_exists: bool = False) → bool

Validate a harm category name.

Validates that the category name follows the naming convention (lowercase letters and underscores only) and optionally checks if it exists in the standard harm definitions.

Returns:

• bool — True if the category is valid (and exists if check_exists is True),

• bool — False otherwise.

ImagePathDataTypeSerializer¶

Bases: DataTypeSerializer

Serializer for image path values stored on disk.

Constructor Parameters:

Methods:

data_on_disk¶

data_on_disk() → bool

Indicate whether this serializer persists data on disk.

Returns:

• bool — Always True for image path serializers.

Message¶

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.

Constructor Parameters:

Methods:

duplicate_message¶

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:

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

flatten_to_message_pieces¶

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

Flatten messages into a single list of message pieces.

Returns:

• MutableSequence[MessagePiece] — MutableSequence[MessagePiece]: Flattened message pieces.

from_prompt¶

from_prompt(prompt: str, role: ChatMessageRole, prompt_metadata: Optional[dict[str, Union[str, int]]] = None) → Message

Build a single-piece message from prompt text.

Returns:

• Message — Constructed message instance.

from_system_prompt¶

from_system_prompt(system_prompt: str) → Message

Build a message from a system prompt.

Returns:

• Message — Constructed system-role message.

get_all_values¶

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

Return all converted values across the provided messages.

Returns:

• list[str] — list[str]: Flattened list of converted values.

get_piece¶

get_piece(n: int = 0) → MessagePiece

Return the nth message piece.

Returns:

• MessagePiece — Selected message piece.

Raises:

• ValueError — If the message has no pieces.

• IndexError — If the index is out of bounds.

get_piece_by_type¶

get_piece_by_type(data_type: Optional[PromptDataType] = None, original_value_data_type: Optional[PromptDataType] = None, converted_value_data_type: Optional[PromptDataType] = None) → Optional[MessagePiece]

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

Returns:

• Optional[MessagePiece] — The first matching MessagePiece, or None if no match is found.

get_pieces_by_type¶

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

Return all message pieces matching the given data type.

Returns:

• list[MessagePiece] — A list of matching MessagePiece objects (may be empty).

get_value¶

get_value(n: int = 0) → str

Return the converted value of the nth message piece.

Returns:

• str — Converted value of the selected message piece.

Raises:

• IndexError — If the index is out of bounds.

get_values¶

get_values() → list[str]

Return the converted values of all message pieces.

Returns:

• list[str] — list[str]: Converted values for all message pieces.

is_error¶

is_error() → bool

Check whether any message piece indicates an error.

Returns:

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

set_response_not_in_database¶

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¶

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¶

to_dict() → dict[str, object]

Convert the message to a dictionary representation.

Returns:

• dict[str, object] — A dictionary with ‘role’, ‘converted_value’, ‘conversation_id’, ‘sequence’, and ‘converted_value_data_type’ keys.

validate¶

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.

MessagePiece¶

Represents a piece of a message to a target.

This class represents a single piece of a message that will be sent to a target. Since some targets can handle multiple pieces (e.g., text and images), requests are composed of lists of MessagePiece objects.

Constructor Parameters:

Methods:

get_role_for_storage¶

get_role_for_storage() → ChatMessageRole

Get the actual stored role, including simulated_assistant.

Use this when duplicating messages or preserving role information for storage. For API calls or comparisons, use api_role instead.

Returns:

• ChatMessageRole — The actual role stored (may be simulated_assistant).

has_error¶

has_error() → bool

Check if the message piece has an error.

Returns:

• bool — True when the response_error is not “none”.

is_blocked¶

is_blocked() → bool

Check if the message piece is blocked.

Returns:

• bool — True when the response_error is “blocked”.

set_piece_not_in_database¶

set_piece_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_sha256_values_async¶

set_sha256_values_async() → None

Compute SHA256 hash values for original and converted payloads. It should be called after object creation if original_value and converted_value are set.

Note, this method is async due to the blob retrieval. And because of that, we opted to take it out of main and setter functions. The disadvantage is that it must be explicitly called.

to_dict¶

to_dict() → dict[str, object]

Convert this message piece to a dictionary representation.

Returns:

• dict[str, object] — dict[str, object]: Dictionary representation suitable for serialization.

to_message¶

to_message() → Message

Convert this message piece into a Message.

Returns:

• Message — A Message containing this piece.

NextMessageSystemPromptPaths¶

Bases: enum.Enum

Enum for predefined next message generation system prompt paths.

QuestionAnsweringDataset¶

Bases: BaseModel

Represents a dataset for question answering.

QuestionAnsweringEntry¶

Bases: BaseModel

Represents a question model.

Methods:

get_correct_answer_text¶

get_correct_answer_text() → str

Get the text of the correct answer.

Returns:

• str — Text corresponding to the configured correct answer index.

Raises:

• ValueError — If no choice matches the configured correct answer.

QuestionChoice¶

Bases: BaseModel

Represents a choice for a question.

ScaleDescription¶

A single scale description entry from a harm definition.

ScenarioIdentifier¶

Scenario result class for aggregating results from multiple AtomicAttacks.

Constructor Parameters:

ScenarioResult¶

Scenario result class for aggregating scenario results.

Constructor Parameters:

Methods:

get_objectives¶

get_objectives(atomic_attack_name: Optional[str] = None) → list[str]

Get the list of unique objectives for this scenario.

Returns:

• list[str] — List[str]: Deduplicated list of objectives.

get_scorer_evaluation_metrics¶

get_scorer_evaluation_metrics() → Optional[ScorerMetrics]

Get the evaluation metrics for the scenario’s scorer from the scorer evaluation registry.

Returns:

• Optional[ScorerMetrics] — The evaluation metrics object, or None if not found.

get_strategies_used¶

get_strategies_used() → list[str]

Get the list of strategies used in this scenario.

Returns:

• list[str] — List[str]: Atomic attack strategy names present in the results.

normalize_scenario_name¶

normalize_scenario_name(scenario_name: str) → str

Normalize a scenario name to match the stored class name format.

Converts CLI-style snake_case names (e.g., “foundry” or “content_harms”) to PascalCase class names (e.g., “Foundry” or “ContentHarms”) for database queries. If the input is already in PascalCase or doesn’t match the snake_case pattern, it is returned unchanged.

This is the inverse of ScenarioRegistry._class_name_to_scenario_name().

Returns:

• str — The normalized scenario name suitable for database queries.

objective_achieved_rate¶

objective_achieved_rate(atomic_attack_name: Optional[str] = None) → int

Get the success rate of this scenario.

Returns:

• int — Success rate as a percentage (0-100).

Score¶

Represents a normalized score generated by a scorer component.

Constructor Parameters:

Methods:

get_value¶

get_value() → bool | float

Return the value of the score based on its type.

If the score type is “true_false”, it returns True if the score value is “true” (case-insensitive), otherwise it returns False.

If the score type is “float_scale”, it returns the score value as a float.

Returns:

• bool | float — bool | float: Parsed score value.

Raises:

• ValueError — If the score type is unknown.

to_dict¶

to_dict() → dict[str, Any]

Convert this score to a dictionary.

Returns:

• dict[str, Any] — Dict[str, Any]: Serialized score payload.

validate¶

validate(scorer_type: str, score_value: str) → None

Validate score value against scorer type constraints.

Raises:

• ValueError — If value is incompatible with scorer type constraints.

Seed¶

Bases: YamlLoadable

Represents seed data with various attributes and metadata.

Methods:

from_yaml_with_required_parameters¶

from_yaml_with_required_parameters(template_path: Union[str, Path], required_parameters: list[str], error_message: Optional[str] = None) → Seed

Load a Seed from a YAML file and validate that it contains specific parameters.

Returns:

• Seed — The loaded and validated seed of the specific subclass type.

render_template_value¶

render_template_value(kwargs: Any = {}) → str

Render self.value as a template with provided parameters.

Returns:

• str — A new prompt with the parameters applied.

Raises:

• ValueError — If parameters are missing or invalid in the template.

render_template_value_silent¶

render_template_value_silent(kwargs: Any = {}) → str

Render self.value as a template with provided parameters. For parameters in the template that are not provided as kwargs here, this function will leave them as is instead of raising an error.

Returns:

• str — A new prompt with the parameters applied.

Raises:

• ValueError — If parameters are missing or invalid in the template.

set_sha256_value_async¶

set_sha256_value_async() → None

Compute the SHA256 hash value asynchronously. It should be called after prompt value is serialized to text, as file paths used in the value may have changed from local to memory storage paths.

Note, this method is async due to the blob retrieval. And because of that, we opted to take it out of main and setter functions. The disadvantage is that it must be explicitly called.

SeedAttackGroup¶

Bases: SeedGroup

A group of seeds for use in attack scenarios.

This class extends SeedGroup with attack-specific validation:

• Requires exactly one SeedObjective (not optional like in SeedGroup)

All other functionality (simulated conversation, prepended conversation, next_message, etc.) is inherited from SeedGroup.

Constructor Parameters:

Methods:

validate¶

validate() → None

Validate the seed attack group state.

Extends SeedGroup validation to require exactly one objective.

Raises:

• ValueError — If validation fails.

SeedAttackTechniqueGroup¶

Bases: SeedGroup

A group of seeds representing a general attack technique.

This class extends SeedGroup with technique-specific validation:

• Requires all seeds to have is_general_technique=True

All other functionality (simulated conversation, prepended conversation, next_message, etc.) is inherited from SeedGroup.

Constructor Parameters:

Methods:

validate¶

validate() → None

Validate the seed attack technique group state.

Extends SeedGroup validation to require all seeds to be general strategies.

Raises:

• ValueError — If validation fails.

SeedDataset¶

Bases: YamlLoadable

SeedDataset manages seed prompts plus optional top-level defaults. Prompts are stored as a Sequence[Seed], so references to prompt properties are straightforward (e.g. ds.seeds[0].value).

Constructor Parameters:

Methods:

from_dict¶

from_dict(data: dict[str, Any]) → SeedDataset

Build a SeedDataset by merging top-level defaults into each item in seeds.

Returns:

• SeedDataset — Constructed dataset with merged defaults.

Raises:

• ValueError — If any seed entry includes a pre-set prompt_group_id.

get_random_values¶

get_random_values(number: PositiveInt, harm_categories: Optional[Sequence[str]] = None) → Sequence[str]

Extract and return random prompt values from the dataset.

Returns:

• Sequence[str] — Sequence[str]: A list of prompt values.

get_values¶

get_values(first: Optional[PositiveInt] = None, last: Optional[PositiveInt] = None, harm_categories: Optional[Sequence[str]] = None) → Sequence[str]

Extract and return prompt values from the dataset.

Returns:

• Sequence[str] — Sequence[str]: A list of prompt values.

group_seed_prompts_by_prompt_group_id¶

group_seed_prompts_by_prompt_group_id(seeds: Sequence[Seed]) → Sequence[SeedGroup]

Group the given list of seeds by prompt_group_id and create SeedGroup or SeedAttackGroup instances.

For each group, this method first attempts to create a SeedAttackGroup (which has attack-specific properties like objective). If validation fails, it falls back to a basic SeedGroup.

Returns:

• Sequence[SeedGroup] — A list of SeedGroup or SeedAttackGroup objects, with seeds grouped by

• Sequence[SeedGroup] — prompt_group_id. Each group will be ordered by the sequence number of

• Sequence[SeedGroup] — the seeds, if available.

render_template_value¶

render_template_value(kwargs: object = {}) → None

Render seed values as templates using provided parameters.

Raises:

• ValueError — If parameters are missing or invalid in the template.

SeedGroup¶

Bases: YamlLoadable

A container for grouping prompts that need to be sent together.

This class handles:

• Grouping of SeedPrompt, SeedObjective, and SeedSimulatedConversation

• Consistent group IDs and roles across seeds

• Prepended conversation and next message extraction

• Validation of sequence overlaps between SeedPrompts and SeedSimulatedConversation

All prompts in the group share the same prompt_group_id.

Constructor Parameters:

Methods:

is_single_part_single_text_request¶

is_single_part_single_text_request() → bool

Check if this is a single text prompt.

Returns:

• bool — True when there is exactly one prompt and it is text.

is_single_request¶

is_single_request() → bool

Check if all prompts are in a single sequence.

Returns:

• bool — True when all prompts share one sequence number.

is_single_turn¶

is_single_turn() → bool

Check if this is a single-turn group (single request without objective).

Returns:

• bool — True when the group is a single request and has no objective.

render_template_value¶

render_template_value(kwargs: Any = {}) → None

Render seed values as templates with provided parameters.

validate¶

validate() → None

Validate the seed group state.

This method can be called after external modifications to seeds to ensure the group remains in a valid state. It is automatically called during initialization.

Raises:

• ValueError — If validation fails.

SeedObjective¶

Bases: Seed

Represents a seed objective with various attributes and metadata.

Methods:

from_yaml_with_required_parameters¶

from_yaml_with_required_parameters(template_path: Union[str, Path], required_parameters: list[str], error_message: Optional[str] = None) → SeedObjective

Load a Seed from a YAML file. Because SeedObjectives do not have any parameters, the required_parameters and error_message arguments are unused.

Returns:

• SeedObjective — The loaded and validated seed of the specific subclass type.

SeedPrompt¶

Bases: Seed

Represents a seed prompt with various attributes and metadata.

Methods:

from_messages¶

from_messages(messages: list[Message], starting_sequence: int = 0, prompt_group_id: Optional[uuid.UUID] = None) → list[SeedPrompt]

Convert a list of Messages to a list of SeedPrompts.

Each MessagePiece becomes a SeedPrompt. All pieces from the same message share the same sequence number, preserving the grouping.

Returns:

• list[SeedPrompt] — List of SeedPrompts with incrementing sequence numbers per message.

from_yaml_with_required_parameters¶

from_yaml_with_required_parameters(template_path: Union[str, Path], required_parameters: list[str], error_message: Optional[str] = None) → SeedPrompt

Load a Seed from a YAML file and validate that it contains specific parameters.

Returns:

• SeedPrompt — The loaded and validated SeedPrompt of the specific subclass type.

Raises:

• ValueError — If the template doesn’t contain all required parameters.

set_encoding_metadata¶

set_encoding_metadata() → None

Set encoding metadata for the prompt within metadata dictionary. For images, this is just the file format. For audio and video, this also includes bitrate (kBits/s as int), samplerate (samples/second as int), bitdepth (as int), filesize (bytes as int), and duration (seconds as int) if the file type is supported by TinyTag. Example supported file types include: MP3, MP4, M4A, and WAV.

SeedSimulatedConversation¶

Bases: Seed

Configuration for generating a simulated conversation dynamically.

This class holds the paths and parameters needed to generate prepended conversation content by running an adversarial chat against a simulated (compliant) target.

This is a pure configuration class. The actual generation is performed by generate_simulated_conversation_async in the executor layer, which accepts this config along with runtime dependencies (adversarial_chat target, scorer).

The value property returns a JSON serialization of the config for database storage and deduplication.

Constructor Parameters:

Methods:

compute_hash¶

compute_hash() → str

Compute a deterministic hash of this configuration.

Returns:

• str — A SHA256 hash string representing the configuration.

from_dict¶

from_dict(data: dict[str, Any]) → SeedSimulatedConversation

Create a SeedSimulatedConversation from a dictionary, typically from YAML.

Returns:

• SeedSimulatedConversation — A new SeedSimulatedConversation instance.

Raises:

• ValueError — If required configuration fields are missing.

from_yaml_with_required_parameters¶

from_yaml_with_required_parameters(template_path: Union[str, Path], required_parameters: list[str], error_message: Optional[str] = None) → SeedSimulatedConversation

Load a SeedSimulatedConversation from a YAML file and validate required parameters.

Returns:

• SeedSimulatedConversation — The loaded and validated SeedSimulatedConversation.

Raises:

• ValueError — If required parameters are missing.

get_identifier¶

get_identifier() → dict[str, Any]

Get an identifier dict capturing this configuration for comparison/storage.

Returns:

• dict[str, Any] — Dictionary with configuration details.

load_simulated_target_system_prompt¶

load_simulated_target_system_prompt(objective: str, num_turns: int, simulated_target_system_prompt_path: Optional[Union[str, Path]] = None) → Optional[str]

Load and render the simulated target system prompt.

If no path is provided, returns None (no system prompt). Validates that the template has required objective and num_turns parameters.

Returns:

• Optional[str] — The rendered system prompt string, or None if no path is provided.

Raises:

• ValueError — If the template doesn’t have required parameters.

SimulatedTargetSystemPromptPaths¶

Bases: enum.Enum

Enum for predefined simulated target system prompt paths.

StorageIO¶

Bases: ABC

Abstract interface for storage systems (local disk, Azure Storage Account, etc.).

Methods:

create_directory_if_not_exists¶

create_directory_if_not_exists(path: Union[Path, str]) → None

Asynchronously creates a directory or equivalent in the storage system if it doesn’t exist.

is_file¶

is_file(path: Union[Path, str]) → bool

Asynchronously checks if the path refers to a file (not a directory or container).

path_exists¶

path_exists(path: Union[Path, str]) → bool

Asynchronously checks if a file or blob exists at the given path.

read_file¶

read_file(path: Union[Path, str]) → bytes

Asynchronously reads the file (or blob) from the given path.

write_file¶

write_file(path: Union[Path, str], data: bytes) → None

Asynchronously writes data to the given path.

StrategyResult¶

Bases: ABC

Base class for all strategy results.

Methods:

duplicate¶

duplicate() → StrategyResultT

Create a deep copy of the result.

Returns:

• StrategyResultT — A deep copy of the result.

TextDataTypeSerializer¶

Bases: DataTypeSerializer

Serializer for text and text-like prompt values that stay in-memory.

Constructor Parameters:

Methods:

data_on_disk¶

data_on_disk() → bool

Indicate whether this serializer persists data on disk.

Returns:

• bool — Always False for text serializers.

UnvalidatedScore¶

Score is an object that validates all the fields. However, we need a common data class that can be used to store the raw score value before it is normalized and validated.

Methods:

to_score¶

to_score(score_value: str, score_type: ScoreType) → Score

Convert this unvalidated score into a validated Score.

Returns:

• Score — Validated score object.

VideoPathDataTypeSerializer¶

Bases: DataTypeSerializer

Serializer for video path values stored on disk.

Constructor Parameters:

Methods:

data_on_disk¶

data_on_disk() → bool

Indicate whether this serializer persists data on disk.

Returns:

• bool — Always True for video path serializers.