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 callers should import them directly from pyrit.models (e.g. from pyrit.models import ComponentIdentifier).

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.

compute_seed_group_hash¶

compute_seed_group_hash(seed_identifiers: Sequence[SeedIdentifier]) → str

Return the deterministic hash of ordered canonical seed identifiers.

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.

display_choices¶

display_choices(param_type: Any) → tuple[Any, ...] | None

A list[...] parameter is unwrapped to its element type first, so a constrained list (list[Literal[...]] / list[Enum]) surfaces its element’s allowed set — the is_list + choices projection a multi-select consumer needs.

Returns:

• tuple[Any, ...] | None — tuple[Any, ...] | None: The allowed members for a constrained scalar

• tuple[Any, ...] | None — (Literal args or Enum member values), or None when unconstrained.

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.

get_lazy_dir¶

get_lazy_dir(module_globals: dict[str, Any], exports: Mapping[str, LazyExport]) → list[str]

Return package attributes and unresolved public exports.

Returns:

• list[str] — list[str]: Sorted package attribute names.

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.

group_seeds_into_attack_groups¶

group_seeds_into_attack_groups(seeds: Sequence[Seed]) → list[AttackSeedGroup]

Group flat seeds by prompt_group_id into AttackSeedGroup instances.

Seeds sharing a prompt_group_id are collapsed into a single AttackSeedGroup; seeds without one (prompt_group_id is None) each become their own group. Within a group, seeds are ordered by sequence when available before construction.

Construction validates the grouping: AttackSeedGroup requires exactly one objective per group (plus the inherited SeedGroup invariants), so a group that lacks an objective -- or otherwise violates the invariants -- raises a ValueError here. This is intentional: callers that want stored groupings turned into attack groups get a fail-fast error on malformed data.

Returns:

• list[AttackSeedGroup] — list[AttackSeedGroup]: One attack group per prompt_group_id (and one per ungrouped seed), each self-validated on construction.

Raises:

• ValueError — If any resulting group does not satisfy AttackSeedGroup’s invariants (e.g. it has no objective or more than one).

load_next_message_prompt¶

load_next_message_prompt(template_path: str | Path) → SeedPrompt

Load a next-message system prompt template and verify it declares the parameters it needs.

Returns:

• SeedPrompt — The loaded template.

Raises:

• ValueError — If the template does not declare objective and conversation_context.

Examples:

• Creating Seeds Programmatically and with YAML

load_simulated_target_prompt¶

load_simulated_target_prompt(template_path: str | Path) → SeedPrompt

Load a simulated target system prompt template and verify it declares the parameters it needs.

Returns:

• SeedPrompt — The loaded template.

Raises:

• ValueError — If the template does not declare objective and num_turns.

project_behavioral_identity¶

project_behavioral_identity(identifier: ComponentIdentifier, identifier_type: type[ComponentIdentifier]) → ComponentIdentifier

Return the behavioral view of an identifier tree.

Each component is filtered by its own typed markers, so operational params (endpoints, deployment names, rate limits) are dropped and declared fallbacks are applied. A parent may drop a child outright with Evaluate.Exclude; wrapper slots marked Evaluate.Unwrap are replaced by their first inner component.

Returns:

• ComponentIdentifier — A tree containing only behavior-defining details.

read_usage_int¶

read_usage_int(source: Any, name: str) → int | None

Read name from a provider usage payload and return it only when it is an integer count.

Which field name holds which count is wire-format specific and therefore the caller’s concern; this helper only owns the read and the int guard, so a partial usage payload contributes just the counts the provider actually reports. Booleans are rejected even though bool is a subclass of int.

Returns:

• int | None — int | None: The integer value, or None when absent or not an integer.

read_usage_value¶

read_usage_value(source: Any, name: str) → Any

Read name from a provider usage payload, which may be a mapping or an attribute object.

Provider SDKs surface usage either as a typed object (OpenAI/LiteLLM Usage) or as a model_dump’d mapping, so both access styles are supported. Use this to reach nested breakdown objects (for example prompt_tokens_details) before reading counts out of them with read_usage_int.

Returns:

• Any — The field value, or None when absent.

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.

resolve_lazy_export¶

resolve_lazy_export(name: str, module_name: str, module_globals: dict[str, Any], exports: Mapping[str, LazyExport]) → Any

Resolve and cache one package export.

Returns:

• Any — The resolved public value.

Raises:

• AttributeError — If name is not a declared lazy export.

resolve_prompt_source¶

resolve_prompt_source(prompt: SeedPrompt | None, path: str | Path | None, prompt_name: str, path_name: str, load_prompt: Callable[[str | Path], SeedPrompt]) → SeedPrompt | None

Choose between a canonical prompt and its deprecated path input, loading the path if needed.

Every boundary that still accepts a *_system_prompt_path uses this so they all warn the same way and reject the same ambiguity. It reads from disk, so async callers must run it through asyncio.to_thread.

Returns:

• SeedPrompt | None — SeedPrompt | None: The resolved prompt, or None when neither input was supplied.

Raises:

• ValueError — If both the canonical prompt and its deprecated path are supplied.

scorable_from_dict¶

scorable_from_dict(value: dict[str, Any]) → ScorableUnion

Rebuild a stored scorable from its scorable_type tag.

Returns:

• ScorableUnion — The rebuilt scorable.

Raises:

• ValidationError — If the stored value names no known scorable.

scoring_expectation_fingerprint¶

scoring_expectation_fingerprint(exp: ScoringExpectation) → str

Return a stable content fingerprint of an expectation.

The fingerprint is the lowercase SHA-256 hex of the canonical JSON serialization (sorted keys, compact separators). JSON object key order does not affect the digest, but condition tuple order is preserved and remains significant.

Returns:

• str — The lowercase SHA-256 hex digest.

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, then order by sequence and piece timestamp.

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

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.

warn_prompt_path_deprecated¶

warn_prompt_path_deprecated(prompt: SeedPrompt | None, prompt_name: str, path_name: str) → None

Reject an ambiguous prompt source and warn that the path input is deprecated.

Separated from loading so async callers can run this on the event loop, where the warning points at their own call site, and send only the file read to a worker thread.

Raises:

• ValueError — If both the canonical prompt and its deprecated path are supplied.

Acquisition¶

Bases: str, Enum

Whether evidence was acquired and the selected scope was completely covered.

AnswerMatches¶

Bases: Condition

The evidence answers a question with the expected choice label or answer text.

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.

AttackAnalyticsCell¶

Bases: _AnalyticsModel

A heatmap cell and the predicates that select its exact cohort.

AttackAnalyticsConverterDirection¶

Bases: str, Enum

The converter pipeline recorded on an attack.

AttackAnalyticsDimension¶

Bases: _AnalyticsModel

A metadata dimension, optionally selecting a literal label key or pipeline side.

Label keys containing dots are still literal keys, not nested JSON paths. The dedicated operation/operator dimensions must be used for attribution.

AttackAnalyticsDimensionName¶

Bases: str, Enum

Supported dimensions from saved result metadata, not current registry state.

Target and scenario keys are persisted identities, not their display names. Harm categories describe the attack’s intended coverage, not detected harms. Converter membership describes recorded usage, not an ordered per-turn pipeline.

AttackAnalyticsFacetQuery¶

Bases: _AnalyticsModel

A bounded lookup for one opened filter control.

Other dimension predicates and outcome/date restrictions remain active. Predicates on this exact dimension are omitted so alternatives remain discoverable. Search narrows option labels, not attack objectives.

AttackAnalyticsFacets¶

Bases: _AnalyticsModel

A single page of facet options.

AttackAnalyticsFilter¶

Bases: _AnalyticsModel

One predicate, with ANY/ALL applied only to the values inside this predicate.

Separate predicates are AND-combined, including repeated predicates for the same dimension. A drill-down must append its predicate instead of replacing an existing converter ANY filter and unintentionally broadening the cohort.

AttackAnalyticsFilters¶

Bases: _AnalyticsModel

The shared cohort selection for reports, facets, and result pages.

No predicates and no outcomes means unrestricted saved results. All four outcomes normalize to the same unrestricted representation. Updated bounds form a half-open interval [after, before) over last-modified timestamps, not attack execution time. Bounds are stored as UTC instants; values outside the supported UTC datetime range are rejected. Request-size limits bound work without sampling results.

AttackAnalyticsGroup¶

Bases: AttackAnalyticsOption

One grouped outcome aggregate and its additional drill-down predicate.

AttackAnalyticsMatchMode¶

Bases: str, Enum

How values within one dimension predicate are combined.

AttackAnalyticsOption¶

Bases: _AnalyticsModel

A filter or axis option with a stable, typed key.

AttackAnalyticsQuery¶

Bases: _AnalyticsModel

A report request, including the initial lightweight result page.

compare_by=None requests one-dimensional groups; otherwise the response contains a bounded heatmap. Group offset/limits paginate groups, not individual attacks. Result and axis limits affect displayed output, never the cohort totals.

AttackAnalyticsReport¶

Bases: _AnalyticsModel

A coherent saved-result report; all numeric analytics come from the SDK.

computed_at belongs to this report and its included first result page. outcome_filter_applied requests the ASR asterisk but never changes the rate formula. groups_overlap warns that multi-valued group/cell totals cannot be summed to recover the overall result count. A non-null drilldown_unavailable_reason means appending this chart’s predicates would exceed the shared filter budget; the current report and result pages remain valid.

AttackAnalyticsResultRow¶

Bases: _AnalyticsModel

A result projection without conversation, score, or media hydration.

AttackAnalyticsResults¶

Bases: _AnalyticsModel

One fresh result page, independent of the last report’s refresh time.

AttackAnalyticsResultsQuery¶

Bases: _AnalyticsModel

A results-only request that does not recalculate aggregates.

The opaque cursor belongs to these filters and must be discarded when the cohort changes. Each page is a new read, not a frozen snapshot of an old report.

AttackAnalyticsStatistics¶

Bases: AttackStats

Outcome statistics for one cohort, group, or heatmap cell.

success_rate uses successes / decided results; errors and undetermined outcomes do not enter that denominator. decided_share and outcome_shares instead use all results. Rates with no applicable denominator are None; shares for an empty cohort are zero. All proportions are in the range 0 through 1.

AttackAnalyticsValue¶

Bases: _AnalyticsModel

An exact metadata value or an explicit absence bucket.

A real empty string or a label named “Unknown” remains a VALUE. MISSING and NO_CONVERTERS carry no string, so neither can collide with user metadata; an absent identifier is different from a known empty pipeline.

AttackAnalyticsValueKind¶

Bases: str, Enum

Disambiguate real metadata from missing values and empty pipelines.

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.

Examples:

• Benchmarks

• Trace-backed tool-call scoring

AttackResult¶

Bases: StrategyResult

Base class for all attack results.

Methods:

get_active_conversation_ids¶

get_active_conversation_ids() → set[str]

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

Excludes adversarial chat conversations which are internal implementation details.

Returns:

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

get_all_conversation_ids¶

get_all_conversation_ids() → set[str]

Return the main conversation ID plus all related conversation IDs.

Returns:

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

get_attack_strategy_identifier¶

get_attack_strategy_identifier() → ComponentIdentifier | None

Return the attack strategy identifier from the composite atomic identifier.

This replaces the removed 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.

AttackResultSelection¶

Bases: str, Enum

The identity used when selecting persisted results.

ALL_RESULTS keeps different result IDs distinct even when they share a conversation. LATEST_PER_CONVERSATION represents the legacy newest-matching-result-per-conversation behavior. Defining these modes does not change any caller’s selection policy.

AttackSeedGroup¶

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.

Examples:

• Attack Techniques

• Compound Attacks

• Creating Seeds Programmatically and with YAML

Methods:

filter_compatible¶

filter_compatible(seed_groups: Sequence[AttackSeedGroup], technique: AttackTechniqueSeedGroup) → list[AttackSeedGroup]

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[AttackSeedGroup] — The compatible subset of seed_groups.

is_compatible_with_technique¶

is_compatible_with_technique(technique: AttackTechniqueSeedGroup) → 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: AttackTechniqueSeedGroup) → AttackSeedGroup

Return a new AttackSeedGroup 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:

• AttackSeedGroup — A new AttackSeedGroup with the merged seeds.

Raises:

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

• ValueError — If preserving prompt placement combines conflicting roles at the same sequence.

AttackStats¶

Statistics for attack analysis results.

AttackTechniqueIdentifier¶

Bases: ComponentIdentifier

Strongly-typed projection of an AttackTechnique’s ComponentIdentifier.

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

AttackTechniqueSeedGroup¶

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.

Methods:

from_messages¶

from_messages(messages: list[Message], starting_sequence: int = 0, insertion_index: int | None = None, prompt_placement: Literal['preserve', 'prepend'] = 'prepend') → AttackTechniqueSeedGroup

Build a technique group from conversation messages.

This supports techniques that generate reusable teaching or priming messages programmatically before a generic attack sends each objective.

Returns:

• AttackTechniqueSeedGroup — A group containing general-technique prompts.

from_system_prompt¶

from_system_prompt(system_prompt: str, insertion_index: int | None = None) → AttackTechniqueSeedGroup

Build a technique group carrying a single system-role instruction.

This is the common shape for jailbreaks and role-play techniques whose only payload is a system prompt that should be prepended to every objective. The value is wrapped verbatim (is_jinja_template=False), so any literal {{ ... }} in system_prompt is preserved rather than re-rendered.

The group declares prompt_placement="prepend" so AttackSeedGroup.with_technique places the system framing before the base prompts without relying on a reserved sequence value.

Returns:

• AttackTechniqueSeedGroup — A group with a single general-technique system seed.

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.

• unordered_when — names a boolean param on the parent identifier. Only an explicit True sorts this slot’s projected child hashes. Duplicates are retained, and the original child list is not changed.

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.

Attributes: a third bucket alongside params and children for identity-bearing state that is neither behavioral nor a constructor input — e.g. a deployment / model version observed at runtime. Like params it feeds the content hash, but it is excluded from the eval hash and is never used to build the component. No identifier promotes attributes to a typed field today; they are populated explicitly through the attributes dict.

Serialization: model_dump() returns a flat dict where reserved keys (class_name, class_module, hash, pyrit_version, eval_hash, Serialization: model_dump() returns a flat dict where reserved keys (class_name, class_module, hash, pyrit_version, eval_hash, children, attributes) 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.

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.

get_class_attribute_values¶

get_class_attribute_values(target_cls: type) → dict[str, Any]

Read each Param.ClassAttr-marked field’s value off a target class.

Lets a registry describe a class (with no configured instance) by sourcing the marked fields directly from class attributes. For every promoted field carrying a ClassAttrMarker, reads the named class attribute (defaulting to the field name upper-cased) from target_cls.

Returns:

• dict[str, Any] — dict[str, Any]: Field-name → class-attribute value, for each

• dict[str, Any] — Param.ClassAttr field. Missing attributes map to None.

get_reference_component_types¶

get_reference_component_types() → dict[str, ComponentType]

Map constructor-arg names to the component family each reference resolves to.

A promoted field that is an included constructor parameter (explicit Param.Include or unmarked) and is typed as a child identifier contributes {arg_name: component_type}, where arg_name is the marker alias or the field name and component_type is the child identifier type’s own component_type. Param.Exclude() fields, plain-value fields, and any field typed as a base ComponentIdentifier (whose component_type is None and is therefore not buildable) contribute nothing.

Returns:

• dict[str, ComponentType] — dict[str, ComponentType]: Constructor-arg-name → referenced component type.

of¶

of(obj: object, params: dict[str, Any] | None = None, children: Mapping[str, ComponentIdentifier | list[ComponentIdentifier] | None] | None = None, attributes: dict[str, Any] | 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.

promoted_child_field_names¶

promoted_child_field_names() → tuple[str, ...]

Get names of this identifier’s promoted child fields.

Returns:

• tuple[str, ...] — tuple[str, ...]: Promoted child field names.

promoted_scalar_field_names¶

promoted_scalar_field_names() → tuple[str, ...]

Get names of this identifier’s promoted scalar (param) fields — the DB-column projection.

Returns:

• tuple[str, ...] — tuple[str, ...]: Promoted scalar field names.

promoted_scalar_values¶

promoted_scalar_values() → dict[str, Any]

Get this identifier’s promoted scalar fields as {name: value} (children/targets excluded).

Returns:

• dict[str, Any] — dict[str, Any]: Promoted scalar field names and values.

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.

ComponentType¶

Bases: str, Enum

The component family a registry reference resolves to.

Each member maps one-to-one to a registry singleton that resolves references of that family by name (TARGET → TargetRegistry, CONVERTER → ConverterRegistry, SCORER → ScorerRegistry, SCENARIO → ScenarioRegistry).

Condition¶

Bases: BaseModel

What counts as satisfied.

A condition is a neutral predicate about evidence: it says what to detect, never whether detecting it is good or bad. Polarity belongs to a scorer that wraps another, such as TrueFalseInverterScorer. Each scoring domain adds its own subclass.

A concrete subclass declares a condition_type field as a single-value Literal with a matching default. That default is the stable discriminator persisted with the condition and carried in REST payloads, so the type survives serialization without its import path.

Methods:

model_validate¶

model_validate(obj: Any, strict: bool | None = None, extra: ExtraValues | None = None, from_attributes: bool | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate a condition, dispatching the registry root to its concrete subtype.

Returns:

• Self — The validated concrete condition.

Raises:

• ValueError — If the abstract root receives an invalid or unknown discriminator.

ContentEntryScorable¶

Bases: Scorable

Persisted loose content, named by id.

This is the stored anchor for a score about loose content: every scorable that reaches storage is a reference, so a persisted score never carries a payload.

ContentScorable¶

Bases: Scorable

Loose content with no conversation behind it.

This names content, not a message: there is no role or error state. A message-family resolver adapts it for existing message scorers. Once the content is persisted, the score anchors on a ContentEntryScorable naming the stored row instead.

Examples:

• Float-Scale Scorers

Methods:

from_message¶

from_message(message: Message) → ContentScorable

Describe the converted content of a single-piece ephemeral message.

Scorers consume converted_value, so this adapter preserves the converted value and data type rather than the pre-conversion input. Everything else the message carried is dropped, including its role and its error state, so a scorer’s deterministic blocked-response handling no longer applies. Use MessageScorer.score_message_async when that state is part of the evidence.

Returns:

• ContentScorable — A scorable holding the converted message content.

Conversation¶

Bases: BaseModel

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

A Conversation records state that belongs to the conversation as a whole rather than to any individual MessagePiece -- most importantly the target the conversation is held with, plus the record of any turns that were retried. Persisting the per-conversation identifiers once here (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.

ConversationRetry¶

Bases: BaseModel

Record of a single retried turn within a conversation.

A retry happens when a turn’s response failed validation (e.g. malformed JSON) and the failed turn was rolled back out of memory so the turn could be resent on a clean history. The record is conversation-scoped metadata: it captures which turn was retried and why, without keeping the discarded turn’s pieces around.

ConversationRetryReason¶

Bases: str, Enum

Why a turn in a conversation had to be retried.

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 Converter’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_converter (a wrapped converter) — are promoted to typed fields.

Build markers (Param.*) declare how these fields map to the converter’s constructor: the supported-type lists are class attributes sourced from the converter class (Param.ClassAttr), while converter_target and sub_converter are included constructor parameters whose identifier types make them references resolved from the target and converter registries.

DivergesFromRepetition¶

Bases: Condition

The evidence continues with other content after repeating the literal text.

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.

Examples:

• Memory Labels and Advanced Memory Queries

IdentifierType¶

Bases: Enum

Enumeration of supported identifier types for filtering.

Examples:

• Memory Labels and Advanced Memory Queries

JsonResponseConfig¶

Bases: BaseModel

Canonical PyRIT configuration for requesting a JSON response from a target.

A value object that owns PyRIT’s canonical MessagePiece.prompt_metadata keys for JSON responses ("response_format", JSON_SCHEMA_METADATA_KEY, "json_schema_name", "json_schema_strict") and (de)serializes them via from_metadata / to_metadata. Producers (scorers, attacks, converters) build one and call to_metadata to attach it to a piece; targets read it back with from_metadata.

Providing a json_schema implies enabled (a schema is meaningless without JSON output), so JSON-object mode is enabled=True with no schema and JSON-schema mode is just json_schema=....

These are PyRIT keys, not a provider’s wire format. Translating this config into a specific provider’s request block (e.g. the OpenAI chat response_format or Responses text.format shape) is the target’s job and lives in pyrit.prompt_target (build_response_format / _build_text_format).

For the provider shapes those translators emit, see: https://platform.openai.com/docs/api-reference/chat/create#chat_create-response_format-json_schema and https://platform.openai.com/docs/api-reference/responses/create#responses_create-text

Methods:

from_metadata¶

from_metadata(metadata: dict[str, Any] | None) → JsonResponseConfig

Reconstruct a config from a MessagePiece’s prompt_metadata.

Reads the canonical response_format / json_schema keys written by to_metadata. Returns a disabled config when JSON output was not requested (response_format absent or not "json"). A schema stored as a JSON string is parsed back into a dict.

Returns:

• JsonResponseConfig — The reconstructed config (enabled=False when none requested).

Raises:

• ValueError — If a schema string is present but is not valid JSON.

to_metadata¶

to_metadata() → dict[str, Any]

Serialize to the canonical response_format / json_schema metadata keys.

Symmetric with from_metadata: a disabled config produces an empty dict (nothing to request), an enabled config without a schema produces just the response_format marker, and an enabled config with a schema also writes the schema body plus its name and strict flag. The result is meant to be merged into a MessagePiece.prompt_metadata dict.

Returns:

• dict[str, Any] — dict[str, Any]: The metadata fragment to attach to a piece.

MatchesObjective¶

Bases: Condition

The evidence satisfies the expectation’s own objective, as a judge reads it.

This carries no text of its own. The objective lives on the ScoringExpectation, so a scorer matching this condition reads it from there and the two can never disagree.

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.

Examples:

• Attack Configuration

• Azure SQL Memory

• Float-Scale Scorers

• Generic Playwright Target

• Memory Labels and Advanced Memory Queries

• MessageNormalizer

• Modality feedback in multi-turn attacks (Crescendo example)

• Multi-Turn Attacks

• OpenAI Chat Target

• OpenAI Responses Target

• OpenAI Video Target

• Round Robin Target - optional

• Target Capabilities

• WebSocket Copilot Target

• WebSocket Target

• Workflows

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.

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.

from_system_prompts¶

from_system_prompts(system_prompts: str = ()) → list[Message]

Build a list of system-role messages, ready to pass as prepended_conversation.

Returns:

• list[Message] — list[Message]: One system-role message per input, in order.

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

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.

Examples:

• Attack Configuration

• Azure SQL Memory

• Basic Memory Programming Usage

• Combining & Stacking Scorers

• Float-Scale Scorers

• Modality feedback in multi-turn attacks (Crescendo example)

• OpenAI Chat Target

• OpenAI Responses Target

• OpenAI Video Target

• Target Capabilities

• True/False Scorers

• WebSocket Copilot Target

• WebSocket Target

• Workflows

Methods:

adversarial_placeholder¶

adversarial_placeholder(role: ChatMessageRole = 'user') → MessagePiece

Build a placeholder text piece that signals the adversarial chat will generate the text content at this position.

Intended for use inside AttackParameters.next_message when combining a user-supplied seed (e.g. a base image to edit) with adversarial-generated text on turn 1 of a multi-turn attack. A consumer that walks the message pieces can call is_adversarial_placeholder to detect a slot and replace its value with the generated text before sending the message.

Returns:

• MessagePiece — A text MessagePiece flagged via prompt_metadata.

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 (prompt_metadata) are shallow-copied so that mutations on one piece do not affect others.

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

is_adversarial_placeholder() → bool

Return True when this piece is a placeholder for adversarial-generated text.

Detection is based on the adversarial_placeholder flag set by adversarial_placeholder. Plain pieces (created without the flag) always return False.

Returns:

• bool — True if this piece should be filled in by an adversarial chat.

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.

mark_as_structured_refusal¶

mark_as_structured_refusal(refusal: str) → None

Record an SDK-provided model refusal on this blocked response piece.

Raises:

• ValueError — If the piece is not a blocked assistant response or the refusal explanation is empty.

mark_as_truncated¶

mark_as_truncated() → None

Record that the target cut this response off at its output-token limit.

A truncated piece may still carry a partial answer with response_error == "none", so without this flag a consumer cannot tell a complete answer from a clipped one.

to_message¶

to_message() → Message

Wrap this piece in a single-piece Message.

Returns:

• Message — A new Message containing only this piece.

MessageScorable¶

Bases: Scorable

Specific message pieces, named by id.

This names one message, or a subset of its pieces. Loose content that was never persisted has no ids to name, so it is a ContentScorable instead.

Examples:

• Combining & Stacking Scorers

• Float-Scale Scorers

• Memory Labels and Advanced Memory Queries

• Round Robin Target - optional

• Trace-backed tool-call scoring

Methods:

from_message¶

from_message(message: Message) → MessageScorable

Name the pieces of a persisted message.

Returns:

• MessageScorable — A scorable naming the message’s pieces.

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.

Observation¶

Bases: BaseModel

Managed evidence acquired about the caller’s scorable anchor.

Methods:

validate_evidence¶

validate_evidence(message_pieces: Mapping[uuid.UUID, MessagePiece], stored_content: tuple[ContentScorable, str] | None = None) → None

Validate supplied canonical evidence without loading or changing it.

Raises:

• ValueError — If scored or response evidence is missing, modified, or unsupported.

Parameter¶

Bases: BaseModel

Describes a parameter that a PyRIT component accepts.

This is the single JSON-serializable parameter descriptor reused across the registry, scenarios, the backend API, and the CLI. param_type carries the value’s live Python type and its allowed set (a Literal[...] or Enum is the allowed set) and drives coerce_value / validate; it is not serialized. Serialization instead projects the type into the display fields type_name, choices, and is_list (plus required from the REQUIRED_VALUE sentinel), so a consumer can rebuild a usable contract from the registry without the live type travelling on the wire.

reference, when set, marks the parameter as a registry reference: its value is supplied by name and resolved to a registered instance by the registry layer (Parameter itself never resolves references). The live reference is excluded from serialization; reference_type exposes its component family, while type_name and is_list expose whether clients supply one name or a list of names.

coerce_value and validate are the only public behaviors; all coercion branching lives behind them so callers never touch a free function.

Examples:

• Custom Scenario Parameters

Methods:

coerce_value¶

coerce_value(raw_value: Any) → Any

Coerce raw_value to this parameter’s declared type.

An opaque or reference parameter passes its value through unchanged (by identity — the registry layer resolves a reference by name; an opaque value is a live object owned by the caller). Otherwise it branches by shape: None passes through (deep-copied), a list coerces per element, and a scalar form (including Literal/Enum) coerces and validates membership. Arbitrary defaulted types pass through unchanged.

Returns:

• Any — The coerced value (the raw value unchanged for opaque/reference/ arbitrary types, a deep copy for the None passthrough, a coerced list for list types, or a coerced scalar for scalar types).

Raises:

• ValueError — If the value cannot be coerced to a constrained scalar or list element type.

is_reference_to¶

is_reference_to(component_type: ComponentType) → bool

Whether this parameter is a registry reference to the given component family.

A reference parameter is supplied by name and resolved to a registered instance by the registry layer. This is the single source of truth for “does this parameter point at a TARGET / CONVERTER / SCORER”, so callers never re-derive it from reference internals.

Returns:

• bool — True when this parameter is a reference to component_type.

validate¶

validate() → None

Reject a declaration with an unsupported param_type.

Supported forms are a plain scalar, a constrained scalar (Literal/Enum), a list of any of those, a registry reference, an opaque passthrough, or None. An otherwise-unsupported type is tolerated only when the parameter declares a default (the builder simply does not supply it, and the value passes through unchanged).

Raises:

• ValueError — If param_type is unsupported and no default is declared.

ParameterDestination¶

Bases: str, Enum

Where a declarative parameter is consumed at build time.

QuestionAnsweringDataset¶

Bases: BaseModel

Represents a dataset for question answering.

QuestionAnsweringEntry¶

Bases: BaseModel

Represents a question model.

Examples:

• Benchmarks

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.

Examples:

• Benchmarks

RegistryReference¶

Self-describing reference to another registry-backed component.

RequestTraceContext¶

Bases: BaseModel

Request metadata linking stored evidence to a W3C trace.

Methods:

from_metadata¶

from_metadata(metadata: dict[str, Any]) → RequestTraceContext | None

Read the request context, rejecting malformed stored metadata.

Returns:

• RequestTraceContext | None — RequestTraceContext | None: The recorded context, or None if absent.

to_metadata¶

to_metadata() → dict[str, str]

Return the namespaced request metadata.

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.

ScaleDescription¶

Bases: BaseModel

A single scale description entry from a harm definition.

ScenarioAtomicGroupProgress¶

Bases: ScenarioProgressCounts

Progress for one planned atomic-attack group.

ScenarioAttackResultDelta¶

Bases: BaseModel

Lightweight memory projection used to map one scenario progress delta.

ScenarioAttackTechniqueDetails¶

Bases: ScenarioComponentIdentity

REST details for the technique used by one scenario attack attempt.

ScenarioComponentIdentity¶

Bases: BaseModel

Display-safe projection of a component’s behavioral identity.

ScenarioDatasetSizeCap¶

Bases: BaseModel

One configured cap affecting a dataset or compound population.

ScenarioDatasetSummary¶

Bases: BaseModel

Logical seed-group counts for one default dataset or synthesized population.

ScenarioDisplayGroupProgress¶

Bases: ScenarioProgressCounts

Progress for one scenario-defined display group.

ScenarioEvaluationIdentifier¶

Bases: EvaluationIdentifier

Evaluation identity for scenarios.

Rules are derived from ScenarioIdentifier’s field markers: the definition version and resolved techniques / datasets feed the hash, the resolved scenario params are included, and the objective_target / objective_scorer children contribute their full behavioral projection. Two runs of the same scenario definition with the same configuration produce the same eval hash, which backs resume drift detection.

ScenarioIdentifier¶

Bases: ComponentIdentifier

Strongly-typed projection of a Scenario’s ComponentIdentifier.

Like the sibling projections (TargetIdentifier / ScorerIdentifier), this is produced by the scenario registry when a scenario is built. It is also the canonical per-run identity carried on the ScenarioResult aggregate and persisted with it: the scenario class name (class_name), definition version, resolved techniques / datasets, the resolved scenario params, and the objective_target / objective_scorer child references all live here rather than as separate denormalized fields. Its eval hash (via ScenarioEvaluationIdentifier) backs resume drift detection.

Promotes the scenario’s behavioral identity to typed params fields that feed both the content and eval hash: the definition version and the resolved techniques / datasets the scenario runs (a v1 vs a v2, or a different technique / dataset selection, is a different identity). The two run-resolved reference slots — objective_target (a PromptTarget) and objective_scorer (a Scorer) — are promoted children the registry resolves by name from the target / scorer registries when building a scenario.

ScenarioObjectiveScorer¶

Bases: ScenarioScorerIdentity

Objective scorer identity and official evaluation metrics.

ScenarioObjectiveScorerMetrics¶

Bases: BaseModel

Official evaluation metrics for an objective scorer configuration.

ScenarioProgressCounts¶

Bases: BaseModel

Canonical progress counts for a set of scenario execution units.

ScenarioProgressHeader¶

Bases: BaseModel

Compact persisted run header returned by the progress endpoint.

ScenarioProgressResult¶

Bases: BaseModel

One persisted attack attempt in ascending progress order.

ScenarioProgressScore¶

Bases: BaseModel

The objective score attached to one persisted scenario attack result.

ScenarioProgressSummary¶

Bases: BaseModel

Backend-owned progress rollups for a scenario run.

ScenarioQueueEntry¶

Bases: BaseModel

One active or queued scenario run in scheduler order.

ScenarioQueueSnapshot¶

Bases: BaseModel

Point-in-time FIFO scheduler state.

ScenarioResult¶

Bases: BaseModel

Scenario result class for aggregating scenario results.

Methods:

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

get_techniques_used() → list[str]

Get the list of techniques present in the results.

Results are aggregated by display group so each technique is counted once, even when it fans out into multiple atomic-attack cells (e.g. across datasets or targets in a matrix scenario). When no display_group_map is set, atomic-attack names are returned unchanged.

Returns:

• list[str] — list[str]: Technique (display-group) names that produced 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 the snake_case registry-name conversion (class_name_to_snake_case) applied to scenario class names during discovery.

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

ScenarioRunListItem¶

Bases: BaseModel

Lightweight scenario run metadata returned by the history endpoint.

ScenarioRunPlan¶

Bases: BaseModel

Versioned normalized execution plan persisted in ScenarioResult metadata.

ScenarioRunPlanAtomicGroup¶

Bases: BaseModel

A planned atomic-attack group and its ordered units of work.

ScenarioRunPlanSeedGroup¶

Bases: BaseModel

A de-duplicated logical seed group in a scenario run plan.

ScenarioRunPlanSeedPrompt¶

Bases: BaseModel

One non-objective prompt persisted with a logical seed group.

ScenarioRunProgress¶

Bases: BaseModel

Canonical rollups and an incremental page of scenario progress results.

ScenarioRunSizeComponent¶

Bases: BaseModel

One additive component of a default-run size estimate.

Methods:

validate_factor_product¶

validate_factor_product() → ScenarioRunSizeComponent

Require known component totals to equal their ordered factor product.

Returns:

• ScenarioRunSizeComponent — The validated component.

Raises:

• ValueError — If a component with factors has an inconsistent count.

ScenarioRunSizeEstimate¶

Bases: BaseModel

Structured estimate of default planned scenario execution units.

Counts use the same outer unit as ScenarioRunPlan: one atomic-attack and logical-seed-group pair. Retries and internal attack turns are excluded.

Methods:

normalize_legacy_estimate¶

normalize_legacy_estimate(data: Any) → Any

Infer status for callers using the original additive estimate fields.

Returns:

• Any — The normalized estimate input.

Raises:

• ValueError — If duplicate total fields disagree.

unavailable¶

unavailable(note: str = 'Default-run size estimate is unavailable.') → ScenarioRunSizeEstimate

Build an unavailable estimate without presenting a guessed total.

Returns:

• ScenarioRunSizeEstimate — An unavailable estimate.

validate_estimate¶

validate_estimate() → ScenarioRunSizeEstimate

Ensure status, bounds, and additive components describe one estimate.

Returns:

• ScenarioRunSizeEstimate — The validated estimate.

Raises:

• ValueError — If the estimate contains contradictory values.

ScenarioRunSizeEstimateCondition¶

Bases: str, Enum

Reason an estimate remains conditional until launch.

ScenarioRunSizeEstimateRequest¶

Bases: BaseModel

Request-specific scenario run-size configuration.

ScenarioRunSizeEstimateStatus¶

Bases: str, Enum

Confidence level for a scenario run-size estimate.

ScenarioRunSizeFactor¶

Bases: BaseModel

One labeled multiplicative factor in a run-size component.

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.

ScenarioScorerIdentity¶

Bases: ScenarioComponentIdentity

Display identity for a scorer and its nested sub-scorers.

ScenarioSeedGroupProgress¶

Bases: ScenarioProgressCounts

Progress for one logical seed group across atomic attacks.

ScenarioTechniqueProgress¶

Bases: ScenarioProgressCounts

Progress for one scenario technique.

ScenarioTechniqueSummary¶

Bases: BaseModel

One concrete attack technique available to a scenario.

Scorable¶

Bases: BaseModel, ABC

What a scorer looks at.

A scorable is normally an inert reference: it names the evidence instead of carrying or acquiring it. ContentScorable is the exception, because loose content has nothing behind it to point at. A scorer-family resolver acquires the named evidence.

A scorable that can be stored on a Score joins ScorableUnion and declares a scorable_type tag, which is what storage round-trips it on.

Score¶

Bases: BaseModel

Represents a normalized score generated by a scorer component.

Methods:

get_value¶

get_value() → bool | float

Return the value of the score based on its type.

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

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

Returns:

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

Raises:

• UndeterminedScoreError — If no verdict was reachable, so there is no value to read.

• ValueError — If the score type is unknown.

ScoreStatus¶

Bases: str, Enum

Whether a verdict was reachable at all.

Completeness is a separate axis from the value, which is what keeps the model honest on both score types at once: a complete true/false score has a boolean, a complete float score has a number, and an undetermined score of either type has nothing.

Inherits from str so values serialize naturally in Pydantic models and REST responses.

Examples:

• Trace-backed tool-call scoring

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

Build markers (Param.*) declare how the child slots map to the scorer’s constructor: prompt_target is an included parameter aliased to the chat_target constructor arg, and sub_scorers is an included parameter aliased to the composite scorer’s scorers arg. Their identifier types make them references resolved by name from the target and scorer registries.

The optional sub_scorers_order_independent param declares that the aggregation verdict does not depend on child order.

ScorerTargetResponsePayload¶

Bases: BaseModel

References to the retained response from the scorer’s target.

Methods:

validate_scored_evidence¶

validate_scored_evidence(scorable: ScorableUnion, scored_piece: MessagePiece | None = None, stored_content: tuple[ContentScorable, str] | None = None) → None

Check supplied scored evidence against the retained digest.

Raises:

• ValueError — If the evidence is missing, modified, or unsupported.

ScoringExpectation¶

Bases: BaseModel

What a scorer scores against.

An expectation is a single parameter, so a question authored in a technique configuration or a seed can reach a scorer through an attack that knows nothing about it. It has two independent axes.

objective carries optional scoring context. It can differ from the attack objective that drives adversarial prompts. Scorers may read it for framing or use it as criterion text through MatchesObjective.

conditions carry the criteria: typed objects routed by type to the scorers that match them. Attacks forward them without inspecting them. A typed leaf accepts exactly one of its declared type; wrappers validate coverage and route subsets to their children. Their tuple order is part of the persisted expectation and its fingerprint. SerializeAsAny keeps each condition serialized as its own subtype, so subclass fields survive a round trip.

Seeds can author these criteria; execution parameters transport the resolved expectation. Seed types and condition types need not map one-to-one.

Examples:

• Trace-backed tool-call scoring

• True/False Scorers

Methods:

model_validate_persisted¶

model_validate_persisted(value: Any) → ScoringExpectation

Validate an expectation loaded from its durable, versioned representation.

Returns:

• ScoringExpectation — The validated expectation.

validate_type¶

validate_type(value: object) → None

Check a runtime input without parsing or copying it.

Raises:

• TypeError — If the input is not a ScoringExpectation or None.

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.

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

Examples:

• Benchmarks

• Contributing Datasets to PyRIT

• Creating Seeds Programmatically and with YAML

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

For each group, this method first attempts to create a AttackSeedGroup (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 AttackSeedGroup 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.

Raises:

• ValueError — If a seed has an unsupported concrete type.

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.

SeedDatasetSummary¶

Aggregate statistics and metadata for the stored seeds in one dataset.

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.

Examples:

• Attack Configuration

• Common Scenario Parameters

• Image Converters

• OpenAI Chat Target

• OpenAI Image Target

• Playwright Copilot Target

• PromptSendingAttack with Azure SQL Memory

• Realtime Target - optional

• Simulated Conversations

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. Objective conditions are retained as an unpromoted parameter in the full identifier JSON; condition-free seeds retain their legacy identity.

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.

Examples:

• Attack Techniques

• Compound Attacks

• Creating Seeds Programmatically and with YAML

SeedPrompt¶

Bases: Seed

Represents a seed prompt with various attributes and metadata.

Examples:

• Attack Configuration

• Contributing Datasets to PyRIT

• Creating Seeds Programmatically and with YAML

• File Converters

• Image Converters

• Modality feedback in multi-turn attacks (Crescendo example)

• Multi-Turn Attacks

• OpenAI Chat Target

• OpenAI Image Target

• Playwright Copilot Target

• Prompt Generators

• PromptSendingAttack with Azure SQL Memory

• Realtime Target - optional

• Simulated Conversations

• Text-to-Text Converters

Methods:

compose_with_prefix¶

compose_with_prefix(base_prompt: SeedPrompt, prefix: str | SeedPrompt, required_parameters: list[str], base_component_name: str = 'prompt', prefix_component_name: str = 'prefix') → SeedPrompt

Prepend static guidance ahead of an already-resolved base prompt.

Combines prefix with base_prompt (separated by a blank line, prefix first). The combined prompt declares the union of both prompts’ parameters — not just required_parameters, which is only the minimum each is validated against — and its response_json_schema is whichever of the two declares one (an error if both do).

An inline string prefix must be static text (no Jinja syntax); an explicitly provided SeedPrompt prefix is exempt and validated against required_parameters like any other SeedPrompt.

The combined prompt is marked is_jinja_template only when both components are, so composing never promotes untrusted text into a trusted template. Promoting it would Jinja-render a value that was deliberately left unrendered, letting a crafted {% endraw %} escape its raw wrapper (see _render_and_infer_data_type).

Descriptive metadata (name, description, source) is intentionally not carried over: the composed prompt is a distinct prompt and should not inherit the base template’s identity.

Returns:

• SeedPrompt — The combined SeedPrompt.

Raises:

• ValueError — If prefix is an inline string containing Jinja syntax, if it is an explicitly provided SeedPrompt missing required parameters, or if both base_prompt and the resolved prefix declare a response_json_schema.

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

from_value_with_required_parameters(value: str | SeedPrompt, required_parameters: list[str], error_message: str | None = None, component_name: str = 'prompt') → SeedPrompt

Coerce an inline string or SeedPrompt into a SeedPrompt declaring required_parameters.

Inline strings are trusted: they are wrapped in a Jinja SeedPrompt whose declared parameters are set to required_parameters. Explicitly provided SeedPrompt objects are validated against required_parameters and returned unchanged (never copied).

Returns:

• SeedPrompt — The resolved SeedPrompt.

Raises:

• ValueError — If an explicitly provided SeedPrompt is missing required parameters.

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.

reject_jinja_syntax¶

reject_jinja_syntax(value: str, component_name: str = 'prompt') → None

Raise if an inline string contains Jinja template syntax.

Shared by callers that accept static, reviewable guidance rather than a template (e.g. compose_with_prefix, AttackTechniqueFactory.create).

Raises:

• ValueError — If value contains “{{”, “{%”, or “{#”.

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 prompts and parameters needed to generate prepended conversation content by running an adversarial chat against a simulated (compliant) target. Use with_layered_prefix to layer additional static guidance ahead of the adversarial chat system prompt on an already-built seed (e.g. from a factory producing a per-instance copy) rather than reconstructing its fields directly.

The actual multi-turn conversation is generated by generate_simulated_conversation_async in the executor layer, which accepts this config’s resolved prompt along with runtime dependencies (adversarial_chat target, scorer).

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

The prompts are canonical SeedPrompt templates, so a technique carries its prompt text rather than a file location and can be inspected or edited in place. The matching *_system_prompt_path inputs are still accepted at construction for legacy callers and for reading records persisted before the change; they are resolved immediately and are not stored on the model.

To change a prompt, edit the SeedPrompt and then build a new SeedSimulatedConversation from it. Like the other fields, value is a snapshot taken when the configuration is validated, so mutating a prompt on an existing instance changes what executes without changing what is stored.

Examples:

• Creating Seeds Programmatically and with YAML

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.

.. deprecated:: Render SeedSimulatedConversation.simulated_target_system_prompt directly with SeedPrompt.render_template_value(objective=..., num_turns=...) instead. This helper reads from disk, so it must not be called from an async path.

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.

with_layered_prefix¶

with_layered_prefix(prefix: str) → SeedSimulatedConversation

Return a copy of this seed with prefix layered ahead of the adversarial chat prompt.

Prepends prefix directly onto adversarial_chat_system_prompt via SeedPrompt.compose_with_prefix (new prefix first, separated by a blank line). Lets a caller (e.g. a factory layering shared guidance onto a baked technique) extend a seed’s adversarial prompt without reimplementing its copy-and-recompute mechanics. Calling this again on the result layers the new prefix ahead of the previous one.

The original seed is not mutated. The returned copy gets a fresh id and recomputed value/value_sha256 since its configuration changed. The other two prompts are passed through as the same already-resolved instances so they are not re-validated (see _keep_prompt_instance).

Returns:

• SeedSimulatedConversation — A new SeedSimulatedConversation with the combined adversarial chat system prompt.

Raises:

• ValueError — If prefix contains Jinja syntax.

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.

StructuredParameterValue¶

Bases: ABC

A parameter value with explicitly allowed structured variants.

Methods:

get_registry_input_variants¶

get_registry_input_variants() → dict[str, type[StructuredParameterValue]]

Declare the implementations available for registry construction.

Returns:

• dict[str, type[StructuredParameterValue]] — dict[str, type[StructuredParameterValue]]: Input names mapped to subclasses of the declaring type.

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.

This model also serves as the REST wire snapshot of a target’s capabilities (it is embedded in TargetInstance). The modality combination fields (input_modalities / output_modalities) are excluded from serialization; API consumers read the flattened supported_input_modalities / supported_output_modalities computed fields instead.

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. Message-handling capabilities are not part of identity and are not surfaced here. supported_auth_modes is the one non-identity fact surfaced: a Param.ClassAttr (Evaluate.Exclude) the registry reads off the class into TargetMetadata — never an identity input or a constructor argument.

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.

TokenUsage¶

Provider-neutral token accounting for a single model call.

Field names use the input/output vocabulary (aligned with the OpenAI Responses API, Anthropic, and Gemini) rather than the Chat Completions prompt/completion terms. The object is persisted onto a MessagePiece’s prompt_metadata via to_metadata using matching token_usage_input_tokens / token_usage_output_tokens key names (one consistent vocabulary end to end). reasoning_tokens and cached_tokens are the two widely-available sub-breakdowns promoted to fields; any other provider-specific counts (audio, predicted-output, cache-write) ride along in extra.

This is a pure value object: it holds counts and (de)serializes them to metadata. Turning a provider usage payload into a TokenUsage is the responsibility of the target/parser that knows which wire format it received (for example, the Chat Completions parser in pyrit.prompt_target.common.chat_completions_response_parser). Only the format-agnostic part of that read -- mapping-or-attribute access and the integer guard -- is shared here, via read_usage_value and read_usage_int.

Neither cost nor the responding model name is modeled here: cost is a currency amount (tracked separately under token_usage_cost) and the model identity is already recorded on the target’s identifier. Both would be a category error inside a token-count value object.

Only fields the provider actually reports are populated; absent values stay None (and are omitted from to_metadata) rather than being coerced to a misleading zero.

Methods:

from_metadata¶

from_metadata(metadata: dict[str, Any]) → TokenUsage | None

Reconstruct a TokenUsage from a MessagePiece’s prompt_metadata.

Reads the token_usage_input_tokens / token_usage_output_tokens keys written by to_metadata. Non-core integer token_usage_* keys are collected into extra; the string token_usage_cost key is ignored (cost is tracked separately).

Returns:

• TokenUsage | None — TokenUsage | None: The reconstructed usage, or None if no token-usage keys exist.

to_metadata¶

to_metadata() → dict[str, int]

Serialize to flat token_usage_* metadata keys, omitting fields that are None.

Uses the input/output vocabulary for the key names to match the field names (one consistent naming end to end). extra counts are written verbatim under the token_usage_ prefix.

Returns:

• dict[str, int] — dict[str, int]: The metadata fragment to merge into prompt_metadata.

ToolCall¶

Bases: BaseModel

Represents a tool invocation requested by the assistant.

ToolCallRequirement¶

Bases: BaseModel

One exact, case-sensitive tool name required as execution evidence.

Examples:

• Trace-backed tool-call scoring

ToolEventsObservationPayload¶

Bases: BaseModel

An immutable allowlisted tool snapshot, with arguments and results not retained.

ToolExecution¶

Bases: _TraceInterval

Safe immutable name-only execution evidence; arguments and results are not retained.

ToolsCalled¶

Bases: Condition

Require every named tool to have an execution attempt, regardless of success.

Examples:

• Trace-backed tool-call scoring

TraceCoverage¶

Bases: BaseModel

Explicit capture completeness and known reasons coverage is incomplete.

TraceQuery¶

Bases: BaseModel

A bounded request for the traces named by an immutable scoring scope.

TraceQueryResult¶

Bases: BaseModel

A transient span snapshot and the client’s explicit capture coverage.

Set available=False only when no evidence can be retrieved, for example after retention expires. Pending capture uses available=True with incomplete coverage. If only some requested traces are available, return their spans with incomplete coverage.

TraceScorable¶

Bases: Scorable

An exact trace scope supplied by the caller.

Examples:

• Trace-backed tool-call scoring

TraceSpan¶

Bases: _TraceInterval

Transient backend-neutral span; raw attributes are not durable scoring evidence.

TraceSpanStatus¶

Bases: str, Enum

The status of an observed execution attempt, not its scoring verdict.

UndeterminedScoreError¶

Bases: ValueError

Raised when a caller reads the value of a score that has none.

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.