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¶

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: ChildEvalRule | None = None, root_unwrap_child: str | None = 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 (and no root unwrap applies), 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: dict[str, str | int] | None = None, error: PromptResponseError = 'none') → Message

Construct a response message from a request message piece.

Returns:

• Message — Constructed response message.

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.

get_common_json_schema¶

get_common_json_schema(name: str) → JsonSchemaDefinition

Return a deep copy of the named schema from COMMON_JSON_SCHEMAS.

Triggers a one-shot YAML scan of JSON_SCHEMAS_PATH on first call. A fresh dict is returned so callers may freely mutate, extend, or merge the schema without affecting other consumers of the same name.

Returns:

• JsonSchemaDefinition — A new dict containing the schema body.

Raises:

• KeyError — If name is not registered in COMMON_JSON_SCHEMAS.

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.

register_common_json_schema¶

register_common_json_schema(name: str, schema: JsonSchemaDefinition, overwrite: bool = False) → None

Register a JSON schema in COMMON_JSON_SCHEMAS under a stable name.

YAML seed prompts (and any other SeedPrompt caller) can then reference the schema via the response_json_schema_name constructor kwarg / YAML key instead of inlining the schema body. A deep copy of schema is stored so later mutation of the caller’s dict does not affect the registry.

Bundled schemas under pyrit/datasets/json_schemas/ are discovered on first access and live in the same registry; this function is the runtime path for adding more (e.g. from a PyRITInitializer body or a test fixture).

Tests that register custom schemas should clean up via unregister_common_json_schema (typically in a fixture’s teardown) so registrations do not leak between tests.

Raises:

• TypeError — If schema is not a dict.

• ValueError — If name is already registered and overwrite is False.

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.

unregister_common_json_schema¶

unregister_common_json_schema(name: str) → None

Remove a previously registered schema from COMMON_JSON_SCHEMAS.

Works uniformly on YAML-discovered and runtime-registered entries. Primarily intended for test teardown so transient registrations do not leak across test cases.

Raises:

• KeyError — If name is not currently registered.

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.

Rules are derived from AtomicAttackIdentifier’s field markers, which propagate down the technique/attack subtree. The behavioral projection of targets, the objective_target restriction to temperature, and the exclusion of objective_scorer / seed_identifiers all live on the typed identifier fields.

AtomicAttackIdentifier¶

Bases: ComponentIdentifier

Strongly-typed projection of an atomic attack’s ComponentIdentifier.

Promotes the attack technique (attack_technique) and all seed identifiers from the dataset (seed_identifiers). seed_identifiers is excluded from the eval hash — it is present for traceability only.

Methods:

build¶

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

Build a composite AtomicAttackIdentifier 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:

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

Raises:

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

AttackIdentifier¶

Bases: ComponentIdentifier

Strongly-typed projection of an AttackStrategy’s ComponentIdentifier.

Promotes the effective adversarial system/seed prompts and the attack’s own child slots — objective target, adversarial chat target, objective scorer, and the request/response converter pipelines.

Evaluate.* markers: objective_target is restricted to temperature for the eval hash (its other behavioral params do not affect grouping at the objective slot), and objective_scorer is excluded entirely.

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.

AttackTechniqueIdentifier¶

Bases: ComponentIdentifier

Strongly-typed projection of an AttackTechnique’s ComponentIdentifier.

Promotes the attack strategy child (attack) and the optional technique seeds (technique_seeds).

CapabilityName¶

Bases: str, Enum

Canonical identifiers for target capabilities.

This keeps capability identity in one place so policy, requirements, and normalization code do not duplicate string field names.

ChatMessage¶

Bases: BaseModel

Represents a single OpenAI Chat Completions message.

Mirrors the OpenAI message schema. 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:

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.

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.

Typed projections: subclasses (TargetIdentifier, ConverterIdentifier, …) may promote well-known params and children to ordinary typed fields. Promotion is automatic and keyed off the field’s annotation: a scalar field maps to a params entry; a field annotated as a ComponentIdentifier subclass (or a list thereof) maps to a children slot of the same name. The promoted value is mirrored back into params / children before hashing, so a typed subclass serializes and hashes identically to a plain ComponentIdentifier built with the same params/children. Non-promoted members simply stay in params / children.

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. Param values are stored in full (no truncation). model_validate() accepts the same flat shape (plus a structured form with an explicit params dict); the content hash is always recomputed on validation, so any stored hash is ignored.

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

from_component_identifier(identifier: ComponentIdentifier) → Self

Return identifier as an instance of this typed subclass.

Pass-through when identifier is already an instance of cls; otherwise revalidate its flat dump into cls (e.g. a base identifier loaded from the DB), rehydrating promoted typed fields. The content hash is recomputed identically across the round-trip.

Returns:

• Self — An instance of cls describing the same identity.

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

Get a single child by key.

Returns:

• ComponentIdentifier | None — 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: dict[str, Any] | None = None, children: dict[str, ComponentIdentifier | list[ComponentIdentifier]] | None = None, promoted: Any = {}) → Self

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:

• Self — A new ComponentIdentifier describing obj.

to_dict¶

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

This is the single supported way to set eval_hash: it is not computed by the base model, so callers attach it here rather than via the constructor. The content hash is recomputed from the (unchanged) params and children, so it is identical to this identifier’s hash.

Returns:

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

• ComponentIdentifier — eval_hash set to the given value.

Conversation¶

Bases: BaseModel

Conversation-scoped metadata shared by every piece in a conversation.

A Conversation records identifiers that belong to the conversation as a whole rather than to any individual MessagePiece -- most importantly the target the conversation is held with. Persisting these once per conversation (instead of stamping them onto every piece/row) is what keeps MessagePiece small.

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.

ConverterIdentifier¶

Bases: ComponentIdentifier

Strongly-typed projection of a PromptConverter’s ComponentIdentifier.

Promotes the supported input/output data types; any converter-specific params stay in params. The converter’s own child slots — converter_target (an LLM target) and sub_converters (nested converters) — are promoted to typed fields.

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.

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.

Evaluate¶

Namespace for the field-level evaluation markers (see module docstring).

EvaluationIdentifier¶

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

Concrete subclasses name their root typed-identifier type via EVAL_ROOT; the per-child rules (CHILD_EVAL_RULES), the root OWN_RULE, and the root-unwrap slot (ROOT_UNWRAP_CHILD) are then derived from the Evaluate.* field markers on that type’s class graph (see derive_eval_config). The typed identifier fields are the single source of truth for what feeds the eval hash.

Subclasses may instead set CHILD_EVAL_RULES (and optionally OWN_RULE / ROOT_UNWRAP_CHILD) directly to bypass derivation.

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

Get the description for a specific score value.

Returns:

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

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: dict[str, str | int] | None = 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: PromptDataType | None = None, original_value_data_type: PromptDataType | None = None, converted_value_data_type: PromptDataType | None = None) → MessagePiece | None

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

Returns:

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

get_pieces_by_type¶

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

Return all message pieces matching the given data type.

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

.. deprecated:: 0.15.0 Use pyrit.memory.storage.serializers.set_message_piece_sha256_async instead. This method will be removed in 0.17.0.

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.

Rules are derived from TargetIdentifier’s field markers: the target’s own params are filtered to the behavioral set (underlying_model_name, temperature, top_p) via the derived OWN_RULE, and wrapper targets (e.g. RoundRobinTarget) are unwrapped at the root, so the same logical target produces the same eval hash whether bare or wrapped.

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[str, Any]) → 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[str, Any]

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[str, Any] — 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.

ScenarioRunState¶

Bases: str, Enum

Lifecycle state of a scenario run.

Inherits from str so values serialize naturally in Pydantic models and REST responses, and compare equal to their string form.

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.

Rules are derived from ScorerIdentifier’s field markers. The prompt_target child is projected to behavioral target params only (underlying_model_name, temperature, top_p) and wrapper targets are unwrapped, so the same scorer configuration on different deployments produces the same eval hash.

ScorerIdentifier¶

Bases: ComponentIdentifier

Strongly-typed projection of a Scorer’s ComponentIdentifier.

Promotes the scorer_type discriminator, the score_aggregator name, and the scorer’s own child slots — prompt_target (an LLM target) and sub_scorers (nested scorers).

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.

.. deprecated:: 0.15.0 Use pyrit.memory.storage.serializers.set_seed_sha256_async instead. This method will be removed in 0.17.0.

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.

SeedIdentifier¶

Bases: ComponentIdentifier

Strongly-typed projection of a Seed’s ComponentIdentifier.

Promotes the seed properties that define its identity: the raw value, its SHA256, the originating dataset, the data type, and whether it is a general technique.

Methods:

from_seed¶

from_seed(seed: Seed) → SeedIdentifier

Build a SeedIdentifier 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:

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

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.

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.

TargetCapabilities¶

Bases: BaseModel

Describes the capabilities of a PromptTarget so that attacks and other components can adapt their behavior accordingly.

Each target class defines default capabilities via the _DEFAULT_CONFIGURATION class attribute. Users can override individual capabilities per instance through constructor parameters, which is useful for targets whose capabilities depend on deployment configuration (e.g., Playwright, HTTP).

Immutable (frozen) so a single capabilities object can be safely shared across targets and reused as a known-model profile.

Methods:

includes¶

includes(capability: CapabilityName) → bool

Return whether this target supports the given capability.

Returns:

• bool — True if supported, otherwise False.

TargetIdentifier¶

Bases: ComponentIdentifier

Strongly-typed projection of a PromptTarget’s ComponentIdentifier.

Promotes the common target params to typed fields; any other params stay in params. Capabilities are not part of identity and are not surfaced here.

Promotes the one child slot a target owns in its own constructor: targets (inner targets of a multi-target like RoundRobinTarget), typed recursively as TargetIdentifier.

Evaluate.* markers declare the behavioral projection used for the eval hash: operational params (endpoint / model_name / max_requests_per_minute) are excluded, underlying_model_name falls back to model_name, and targets is a wrapper passthrough that is unwrapped so a multi-target hashes the same as its inner target.

ToolCall¶

Bases: BaseModel

Represents a tool invocation requested by the assistant.

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.