pyrit.models

Public model exports for PyRIT core data structures and helpers.

pyrit.models is the canonical data layer. Files in this package must import only from the standard library, pydantic, pyrit.common.deprecation, and other pyrit.models.* submodules. The CI test tests/unit/models/test_import_boundary.py enforces this. See .github/instructions/models.instructions.md for the rule.

Identifier types and helpers live in the pyrit.models.identifiers sub-package but are re-exported here, so external callers should import them directly from pyrit.models (e.g. from pyrit.models import ComponentIdentifier). The previous pyrit.identifiers location is kept as a deprecation shim through 0.16.0.

Functions¶

build_atomic_attack_identifier¶

build_atomic_attack_identifier(technique_identifier: ComponentIdentifier | None = None, attack_identifier: ComponentIdentifier | None = None, seed_group: SeedGroup | None = None) → ComponentIdentifier

Build a composite ComponentIdentifier for an atomic attack.

The identifier places the attack technique in children["attack_technique"] and all seeds from the seed group in children["seed_identifiers"] for traceability.

Callers that have an AttackTechnique object should pass technique_identifier=attack_technique.get_identifier(). Callers that only have a raw attack strategy identifier (e.g. legacy backward-compat paths) can pass attack_identifier instead, which is wrapped in a minimal technique node automatically.

Returns:

• ComponentIdentifier — A composite ComponentIdentifier with class_name=“AtomicAttack”.

Raises:

• ValueError — If both or neither of technique_identifier and attack_identifier are provided.

build_seed_identifier¶

build_seed_identifier(seed: Seed) → ComponentIdentifier

Build a ComponentIdentifier from a seed’s behavioral properties.

Captures the seed’s content hash, dataset name, and class type so that different seeds produce different identifiers while the same seed content always produces the same identifier.

Returns:

• ComponentIdentifier — An identifier capturing the seed’s behavioral properties.

class_name_to_snake_case¶

class_name_to_snake_case(class_name: str, suffix: str = '') → str

Convert a PascalCase class name to snake_case, optionally stripping a suffix.

Returns:

• str — The snake_case name (e.g., “self_ask_refusal” if suffix=“Scorer”).

compute_eval_hash¶

compute_eval_hash(identifier: ComponentIdentifier, child_eval_rules: dict[str, ChildEvalRule], own_rule: Optional[ChildEvalRule] = None) → str

Compute a behavioral equivalence hash for evaluation grouping.

Unlike ComponentIdentifier.hash (which includes all params of self and children), the eval hash applies per-child rules to strip operational params (like endpoint, max_requests_per_minute), exclude children entirely, or filter list items. own_rule extends this to the root entity itself, which is required for leaf components (e.g., a target) whose own params need filtering and which have no relevant children to delegate to. This ensures the same logical configuration on different deployments produces the same eval hash.

Children not listed in child_eval_rules receive full recursive treatment.

When both child_eval_rules is empty and own_rule is None, no filtering occurs and the result equals identifier.hash.

Returns:

• str — A hex-encoded SHA256 hash suitable for eval registry keying.

Raises:

• RuntimeError — If the identifier’s hash is None and no filtering is configured.

• ValueError — If own_rule carries fields that are not meaningful at the root.

config_hash¶

config_hash(config_dict: dict[str, Any]) → str

Compute a deterministic SHA256 hash from a config dictionary.

This is the single source of truth for identity hashing across the entire system. The dict is serialized with sorted keys and compact separators to ensure determinism.

Returns:

• str — Hex-encoded SHA256 hash string.

Raises:

• TypeError — If config_dict contains values that are not JSON-serializable.

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.

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.

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.

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.

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.

print_deprecation_message¶

print_deprecation_message(old_item: type | Callable[..., Any] | str, new_item: type | Callable[..., Any] | str, removed_in: str) → None

Emit a deprecation warning.

snake_case_to_class_name¶

snake_case_to_class_name(snake_case_name: str, suffix: str = '') → str

Convert a snake_case name to a PascalCase class name.

Returns:

• str — The PascalCase class name (e.g., “MyCustomScenario”).

sort_message_pieces¶

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

Group by conversation_id, ordering by earliest timestamp then sequence.

Conversations are ordered by their earliest piece’s timestamp; pieces within a conversation are ordered by sequence.

Returns:

• list[MessagePiece] — A new list containing the same pieces in deterministic order.

validate_registry_name¶

validate_registry_name(name: str) → None

Validate that name is a legal registry name.

Raises:

• ValueError — If name does not match the required pattern.

AtomicAttackEvaluationIdentifier¶

Bases: EvaluationIdentifier

Evaluation identity for atomic attacks.

Per-child rules:

• seed_identifiers — excluded entirely (present for traceability only).

• attack_technique — not listed, so fully included by default. Its nested children (objective_target, adversarial_chat, objective_scorer, technique_seeds) are processed recursively using the same rules dict, so the rules below apply at any depth.

• objective_target — include only temperature.

• adversarial_chat — include underlying_model_name, temperature, top_p.

• objective_scorer — excluded entirely.

Non-target children (e.g., request_converters, response_converters, technique_seeds) receive full recursive eval treatment.

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:

from_dict¶

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

Reconstruct an AttackResult from a dictionary.

Deprecated: use model_validate(...) for the canonical Pydantic deserialization. This shim accepts the legacy to_dict() wire shape (base fields only) through the deprecation window.

Returns:

• AttackResult — Reconstructed instance.

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() → ComponentIdentifier | None

Return the attack strategy identifier from the composite atomic identifier.

This is the non-deprecated replacement for the attack_identifier property. Extracts the "attack" child from the nested "attack_technique" child of atomic_attack_identifier.

Falls back to children["attack"] for rows created before the nested structure was introduced.

Returns:

• ComponentIdentifier | None — ComponentIdentifier | None: The attack strategy identifier, or None if atomic_attack_identifier is not set or the expected children are missing.

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.

to_dict¶

to_dict() → dict[str, Any]

Serialize this attack result to a JSON-compatible dictionary.

Deprecated: use model_dump(mode="json") for the canonical Pydantic serialization. This shim preserves the legacy wire shape (base fields only, raw metadata, sorted related_conversations) through the deprecation window.

Returns:

• dict[str, Any] — dict[str, Any]: Serialized payload suitable for REST APIs or persistence.

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_async¶

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

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

is_file_async¶

is_file_async(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_async¶

path_exists_async(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_async¶

read_file_async(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.

write_file_async¶

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

Write data to Azure Blob Storage at the specified path.

If the provided path is a full URL, the blob name is extracted from it. If a relative path is provided, it is used as the blob name directly.

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 (deprecated, use model_validate_json instead).

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 (deprecated, use model_dump_json instead).

Returns:

• str — A JSON string representation of the message.

ChatMessagesDataset¶

Bases: BaseModel

Represents a dataset of chat messages.

ChildEvalRule¶

Bases: BaseModel

Per-child configuration for eval-hash computation.

Controls how a specific named child is treated when building the evaluation hash:

• exclude — if True, drop this child entirely from the hash.

• included_params — if set, only include these param keys for this child (and its recursive descendants). None means all params.

• included_item_values — for list-valued children, only include items whose params match all specified key-value pairs. None means include all items.

• param_fallbacks — maps a primary param key to a fallback key. When the primary key’s value is falsy (empty string, None, or missing), the fallback key’s value from the component’s raw params is used instead. This keeps fallback logic in the eval layer without changing full component hashes. None means no fallbacks.

• inner_child_name — if set, names the sub-child to “look through” when the child being processed is a wrapper component (e.g., RoundRobinTarget). The first item of that sub-child list is substituted before applying param filtering, so the eval hash matches the unwrapped inner target. None means no unwrapping.

ComponentIdentifier¶

Bases: BaseModel

Immutable snapshot of a component’s behavioral configuration.

A single type for all component identity — scorers, targets, converters, and any future component types all produce a ComponentIdentifier with their relevant params and children.

The hash is content-addressed: two ComponentIdentifiers with the same class, params, and children produce the same hash. This enables deterministic metrics lookup, DB deduplication, and registry keying.

Serialization¶

model_dump() returns a flat dict where reserved keys (class_name, class_module, hash, pyrit_version, eval_hash, children) sit at the top level alongside the inlined param values. This shape is also the storage / REST format. Pass context={"max_value_length": N} to truncate long string param values. model_validate() accepts the same flat shape (plus a structured form with an explicit params dict).

Mutability¶

The model is frozen, but params and children are dicts whose contents are not deep-frozen — mutating them after construction creates an identifier whose stored hash no longer matches its content. Treat every identifier as a fully immutable value.

Methods:

from_dict¶

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

Reconstruct from a flat dict (deprecated; use model_validate instead).

Returns:

• ComponentIdentifier — A new ComponentIdentifier.

get_child¶

get_child(key: str) → Optional[ComponentIdentifier]

Get a single child by key.

Returns:

• Optional[ComponentIdentifier] — The child identifier, or None if not present.

Raises:

• ValueError — If the child at key is a list. Use get_child_list for list-valued children.

get_child_list¶

get_child_list(key: str) → list[ComponentIdentifier]

Get a list of children by key. Wraps singletons; [] if missing.

Returns:

• list[ComponentIdentifier] — A list of child identifiers.

of¶

of(obj: object, params: Optional[dict[str, Any]] = None, children: Optional[dict[str, Union[ComponentIdentifier, list[ComponentIdentifier]]]] = None) → ComponentIdentifier

Build a ComponentIdentifier from a live object instance.

Extracts class_name and class_module from the object’s type automatically. None-valued params and children are filtered out to keep schemas backward-compatible.

Returns:

• ComponentIdentifier — A new ComponentIdentifier describing obj.

to_dict¶

to_dict(max_value_length: Optional[int] = None) → dict[str, Any]

Return the flat storage dict (deprecated; use model_dump instead).

Returns:

• dict[str, Any] — The flat dict representation.

with_eval_hash¶

with_eval_hash(eval_hash: str) → ComponentIdentifier

Return a new identifier with eval_hash set.

Builds a fresh instance, passing the existing hash through explicitly so it is preserved rather than recomputed. This matters for identifiers reconstructed from truncated DB data, where recomputing from the truncated params would produce a wrong hash.

Returns:

• ComponentIdentifier — A new ComponentIdentifier identical to this one but with

• ComponentIdentifier — eval_hash set to the given value.

ConversationReference¶

Bases: BaseModel

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

Methods:

from_dict¶

from_dict(data: dict[str, str | None]) → ConversationReference

Reconstruct a ConversationReference from a dictionary.

.. deprecated:: Use model_validate instead. This method will be removed in version 0.16.0.

Returns:

• ConversationReference — Reconstructed instance.

to_dict¶

to_dict() → dict[str, str | None]

Serialize to a JSON-compatible dictionary.

.. deprecated:: Use model_dump with mode="json" instead. This method will be removed in version 0.16.0.

Returns:

• dict[str, str | None] — dict[str, str | None]: Dictionary with conversation_id, conversation_type, and description.

ConversationStats¶

Bases: BaseModel

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 (deprecated alias of get_data_filename_async).

Returns:

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

get_data_filename_async¶

get_data_filename_async(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 (deprecated alias of get_sha256_async).

Returns:

• str — Hex digest of the computed SHA256 hash.

get_sha256_async¶

get_sha256_async() → 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 (deprecated alias of read_data_async).

Returns:

• bytes — The data read from storage.

read_data_async¶

read_data_async() → 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 and return it as a base64 string (deprecated alias of read_data_base64_async).

Returns:

• str — Base64-encoded data.

read_data_base64_async¶

read_data_base64_async() → 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) → None

Save a base64-encoded image to storage (deprecated alias of save_b64_image_async).

save_b64_image_async¶

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

Save a base64-encoded image to storage.

Raises:

• RuntimeError — If storage IO is not initialized.

save_data¶

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

Save data to storage (deprecated alias of save_data_async).

save_data_async¶

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

Save data to storage.

Raises:

• RuntimeError — If storage IO is not initialized.

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 formatted audio data to storage (deprecated alias of save_formatted_audio_async).

save_formatted_audio_async¶

save_formatted_audio_async(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.

Raises:

• RuntimeError — If storage IO is not initialized.

DiskStorageIO¶

Bases: StorageIO

Implementation of StorageIO for local disk storage.

Methods:

create_directory_if_not_exists_async¶

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

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

is_file_async¶

is_file_async(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_async¶

path_exists_async(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_async¶

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

Asynchronously reads a file from the local disk.

Returns:

• bytes — The content of the file.

write_file_async¶

write_file_async(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 (deprecated, use model_dump_json instead).

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.

EvaluationIdentifier¶

Bases: ABC

Wraps a ComponentIdentifier with domain-specific eval-hash configuration.

Subclasses set CHILD_EVAL_RULES — a mapping of child names to ChildEvalRule instances that control how each child is treated during eval-hash computation. Children not listed receive full recursive treatment.

Leaf-entity subclasses (no relevant children to delegate to) may also set OWN_RULE to filter the root entity’s own params. See ObjectiveTargetEvaluationIdentifier for an example.

The concrete eval_hash property delegates to the module-level compute_eval_hash free function.

HarmDefinition¶

Bases: BaseModel

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.

Identifiable¶

Bases: ABC

Abstract base class for components that provide a behavioral identity.

Components implement _build_identifier() to return a frozen ComponentIdentifier snapshot. The identifier is built lazily on first access and cached for the component’s lifetime.

Methods:

get_identifier¶

get_identifier() → ComponentIdentifier

Get the component’s identifier, building it lazily on first access.

The identifier is computed once via _build_identifier() and then cached for subsequent calls. This ensures consistent identity throughout the component’s lifetime while deferring computation until actually needed.

Returns:

• ComponentIdentifier — The frozen identity snapshot representing this component’s behavioral configuration.

IdentifierFilter¶

Bases: BaseModel

Immutable filter definition for matching JSON-backed identifier properties.

IdentifierType¶

Bases: Enum

Enumeration of supported identifier types for filtering.

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¶

Bases: BaseModel

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.

Methods:

duplicate¶

duplicate() → 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.

duplicate_message¶

duplicate_message() → Message

Create a deep copy of this message (DEPRECATED — use duplicate).

Returns:

• Message — A new Message with deep-copied 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 (DEPRECATED — use the module function).

Returns:

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

from_dict¶

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

Reconstruct a Message from a dictionary (DEPRECATED — use model_validate).

Returns:

• Message — Reconstructed instance.

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 (DEPRECATED — use the module function).

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

Mark every piece in this message as ephemeral (DEPRECATED — use set_response_not_in_memory).

set_response_not_in_memory¶

set_response_not_in_memory() → None

Mark every piece in this message as ephemeral.

This is needed when we’re scoring prompts or other things that have not been sent by PyRIT. Ephemeral pieces are skipped by add_message_pieces_to_memory.

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 (DEPRECATED — use model_dump).

Includes the original top-level fields (‘role’, ‘converted_value’, ‘conversation_id’, ‘sequence’, ‘converted_value_data_type’) for backward compatibility, plus a ‘pieces’ list containing each piece’s Pydantic JSON dump.

Returns:

• dict[str, object] — dict[str, object]: Dictionary with ‘role’, ‘converted_value’, ‘conversation_id’, ‘sequence’, ‘converted_value_data_type’, and ‘pieces’ keys.

validate¶

validate() → None

Validate that all message pieces are internally consistent.

Retained as a public instance method because callers invoke message.validate() directly. Shadows the deprecated BaseModel.validate classmethod.

Raises:

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

MessagePiece¶

Bases: BaseModel

A single piece of a message exchanged with a target.

Targets that accept multimodal input (e.g., text + image) are represented as a list of MessagePiece instances grouped under one Message.

Methods:

copy_lineage_from¶

copy_lineage_from(source: MessagePiece) → None

Copy lineage metadata from source onto this piece.

Lineage fields are the metadata that tie a piece back to its originating conversation, attack, and target. Mutable containers (labels, prompt_metadata) are shallow-copied so that mutations on one piece do not affect others.

from_dict¶

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

Construct a MessagePiece from a dict (DEPRECATED — use model_validate).

Returns:

• MessagePiece — A new MessagePiece (same as cls.model_validate(data)).

has_error¶

has_error() → bool

Return True when response_error is not "none".

Returns:

• bool — True if the piece carries any non-"none" error code.

is_blocked¶

is_blocked() → bool

Return True when response_error is "blocked".

Returns:

• bool — True if the response was blocked by the target / content filter.

set_piece_not_in_database¶

set_piece_not_in_database() → None

Mark this piece as ephemeral (DEPRECATED — set not_in_memory directly).

Example::

piece.not_in_memory = True

set_sha256_values_async¶

set_sha256_values_async() → None

Compute SHA256 hash values for original and converted payloads.

Async because blob payloads may need to be fetched. Must be called explicitly after construction.

to_dict¶

to_dict() → dict[str, Any]

Return a JSON-mode dict representation (DEPRECATED — use model_dump).

Returns:

• dict[str, Any] — A JSON-mode dict representation of the piece (same as

• dict[str, Any] — self.model_dump(mode="json")).

to_message¶

to_message() → Message

Wrap this piece in a single-piece Message.

Returns:

• Message — A new Message containing only this piece.

Modality¶

Bases: str, Enum

Not yet used by TargetCapabilities (which still uses PromptDataType with finer-grained image_path/audio_path/video_path storage tokens). Unifying the two is tracked as a follow-up — see PR #1780.

NextMessageSystemPromptPaths¶

Bases: enum.Enum

Enum for predefined next message generation system prompt paths.

ObjectiveTargetEvaluationIdentifier¶

Bases: EvaluationIdentifier

Evaluation identity for an objective target.

Mirrors how ScorerEvaluationIdentifier filters its inner prompt_target child, except the target itself is the root of this identifier (it has no children carrying behavioral configuration). The target’s own params are filtered to the behavioral set (underlying_model_name, temperature, top_p) via OWN_RULE, so the same logical target on different deployments produces the same eval hash.

Wrapper targets (e.g., RoundRobinTarget) are not unwrapped — the caller must pass the inner target’s ComponentIdentifier directly if behavioral equivalence with the unwrapped form is desired. This mirrors the constraint on OWN_RULE (no inner_child_name at the root).

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.

RetryEvent¶

Bases: BaseModel

A single retry attempt captured during attack execution.

Records structured information about a Tenacity retry event, including which component was retrying, what exception triggered the retry, and timing information. These events are collected by a RetryCollector and attached to AttackResult objects for persistence and REST API exposure.

Methods:

from_dict¶

from_dict(data: dict) → RetryEvent

Deserialize from a dictionary.

.. deprecated:: Use model_validate instead. This method will be removed in version 0.16.0.

Returns:

• RetryEvent — Deserialized retry event.

to_dict¶

to_dict() → dict

Serialize to a dictionary suitable for JSON storage.

.. deprecated:: Use model_dump with mode="json" instead. This method will be removed in version 0.16.0.

Returns:

• dict — Dictionary representation of the retry event.

ScaleDescription¶

Bases: BaseModel

A single scale description entry from a harm definition.

ScenarioIdentifier¶

Bases: BaseModel

Identifier describing the executed scenario.

Methods:

from_dict¶

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

Reconstruct a ScenarioIdentifier from a dictionary.

Deprecated: use model_validate(...) instead.

Returns:

• ScenarioIdentifier — Reconstructed instance.

to_dict¶

to_dict() → dict[str, Any]

Serialize to a JSON-compatible dictionary.

Deprecated: use model_dump(by_alias=True) instead.

Returns:

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

ScenarioResult¶

Bases: BaseModel

Scenario result class for aggregating scenario results.

Methods:

from_dict¶

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

Reconstruct a ScenarioResult from a dictionary.

Deprecated: use model_validate(...) instead.

Returns:

• ScenarioResult — Reconstructed instance.

get_display_groups¶

get_display_groups() → dict[str, list[AttackResult]]

Aggregate attack results by display group.

When a display_group_map was provided, results from multiple atomic_attack_name keys that share the same display group are merged into a single list. When no map was provided, this returns the same structure as attack_results (identity mapping).

Returns:

• dict[str, list[AttackResult]] — dict[str, list[AttackResult]]: Results grouped by display label.

get_objectives¶

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

Get the list of unique objectives for this scenario.

Returns:

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

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: str | None = None) → int

Get the success rate of this scenario.

Returns:

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

to_dict¶

to_dict() → dict[str, Any]

Serialize this scenario result to a JSON-compatible dictionary.

Deprecated: use model_dump(mode="json", by_alias=True) instead.

Returns:

• dict[str, Any] — dict[str, Any]: Serialized payload suitable for REST APIs or persistence.

Score¶

Bases: BaseModel

Represents a normalized score generated by a scorer component.

Methods:

from_dict¶

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

Construct a Score from a dict (DEPRECATED — use model_validate).

Returns:

• Score — A new Score (same as cls.model_validate(data)).

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]

Return a JSON-mode dict representation (DEPRECATED — use model_dump).

Returns:

• dict[str, Any] — A JSON-mode dict representation of the score (same as

• dict[str, Any] — self.model_dump(mode="json")).

validate¶

validate(args: Any = (), kwargs: Any = {}) → None

Re-run construction-time validation (DEPRECATED).

Validation now happens automatically when a Score is constructed, so there is no need to call this. It is retained only as a no-op-style shim that re-validates the current instance. Any positional/keyword arguments are ignored.

Raises:

• ValueError — If the value is incompatible with the score-type constraints.

ScorerEvaluationIdentifier¶

Bases: EvaluationIdentifier

Evaluation identity for scorers.

The prompt_target child is filtered to behavioral params only (underlying_model_name, temperature, top_p), so the same scorer configuration on different deployments produces the same eval hash.

Seed¶

Bases: BaseModel

Represents seed data with various attributes and metadata.

Methods:

escape_for_jinja¶

escape_for_jinja(value: str) → str

Wrap a string in Jinja2 {% raw %}...{% endraw %} tags to prevent template evaluation.

Use this for any untrusted or externally-fetched text that will be stored as a Seed value, to ensure it is treated as literal text by the Jinja2 renderer.

Returns:

• str — The string wrapped in {% raw %}...{% endraw %} tags.

from_yaml_file¶

from_yaml_file(file: str | Path) → T

Create a new Seed from a YAML file, marking it as a trusted Jinja2 template.

Thin shim that delegates to load_seed_from_yaml in the yaml_seed_loader module; file I/O and the is_jinja_template trust marker live in the loader module.

Returns:

• T — A new Seed of the specific subclass type.

Raises:

• FileNotFoundError — If the path does not resolve to an existing file.

• ValueError — If the YAML file is invalid or empty.

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.

Methods:

filter_compatible¶

filter_compatible(seed_groups: Sequence[SeedAttackGroup], technique: SeedAttackTechniqueGroup) → list[SeedAttackGroup]

Return only the seed groups compatible with the given technique.

A seed group is incompatible when the technique carries a SeedSimulatedConversation whose sequence range overlaps with the group’s prompt sequences.

Returns:

• list[SeedAttackGroup] — The compatible subset of seed_groups.

is_compatible_with_technique¶

is_compatible_with_technique(technique: SeedAttackTechniqueGroup) → bool

Check whether this seed group can be merged with the given technique.

A technique containing a SeedSimulatedConversation is incompatible with seed groups that have SeedPrompt objects whose sequences fall within the simulated conversation’s range.

Returns:

• bool — True if the merge would succeed, False if it would cause a

• bool — sequence overlap.

with_technique¶

with_technique(technique: SeedAttackTechniqueGroup) → SeedAttackGroup

Return a new SeedAttackGroup with technique seeds merged in.

The original group is not mutated. Technique seeds are inserted at technique.insertion_index (or appended at the end when None).

Returns:

• SeedAttackGroup — A new SeedAttackGroup with the merged seeds.

Raises:

• ValueError — If the technique contains a SeedSimulatedConversation whose sequence range overlaps with existing prompt sequences.

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.

SeedDataset¶

Bases: BaseModel

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).

Methods:

from_dict¶

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

Build a SeedDataset, assigning per-seed prompt_group_id by alias.

Default merging now lives in _build_seeds so direct construction and from_dict produce equivalent results. This method handles the YAML-only concerns: rejecting pre-set prompt_group_id on input seeds and resolving prompt_group_alias into a shared prompt_group_id.

Returns:

• SeedDataset — Constructed dataset.

Raises:

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

from_yaml_file¶

from_yaml_file(file: str | Path) → SeedDataset

Create a SeedDataset from a YAML file, marking nested seeds as trusted templates.

Thin shim that delegates to pyrit.models.seeds.yaml_seed_loader.load_seed_dataset_from_yaml; file I/O and the is_jinja_template trust marker live in the loader module.

Returns:

• SeedDataset — The loaded dataset.

Raises:

• FileNotFoundError — If the path does not resolve to an existing file.

• ValueError — If the YAML file is invalid or empty.

get_random_values¶

get_random_values(number: PositiveInt, harm_categories: Sequence[str] | None = 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: PositiveInt | None = None, last: PositiveInt | None = None, harm_categories: Sequence[str] | None = 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: BaseModel

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.

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.

SeedObjective¶

Bases: Seed

Represents a seed objective with various attributes and metadata.

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: uuid.UUID | None = 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: str | Path, required_parameters: list[str], error_message: str | None = None) → SeedPrompt

Load a SeedPrompt from a YAML file and validate that it declares each required parameter.

Thin shim that delegates to pyrit.models.seeds.yaml_seed_loader.load_seed_prompt_from_yaml_with_required_parameters.

Returns:

• SeedPrompt — The loaded and validated SeedPrompt.

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.

Methods:

compute_hash¶

compute_hash() → str

Compute a deterministic hash of this configuration.

Returns:

• str — A SHA256 hash string representing the configuration.

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: str | Path | None = None) → str | None

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:

• str | None — 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

Create a directory if it does not exist (deprecated alias of create_directory_if_not_exists_async).

create_directory_if_not_exists_async¶

create_directory_if_not_exists_async(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

Check whether the given path is a file (deprecated alias of is_file_async).

Returns:

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

is_file_async¶

is_file_async(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

Check whether a path exists (deprecated alias of path_exists_async).

Returns:

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

path_exists_async¶

path_exists_async(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

Read a file from storage (deprecated alias of read_file_async).

Returns:

• bytes — The content of the file.

read_file_async¶

read_file_async(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

Write data to storage (deprecated alias of write_file_async).

write_file_async¶

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

Asynchronously writes data to the given path.

StrategyResult¶

Bases: BaseModel, ABC

Base class for all strategy results.

Methods:

duplicate¶

duplicate() → Self

Create a deep copy of the result.

Returns:

• Self — 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.