pyrit.identifiers

Deprecation shim — pyrit.identifiers was renamed to pyrit.models.identifiers in 0.14.

This module emits a DeprecationWarning (one per name per process) on first access of each public symbol and returns the symbol from its new location. The shim will be removed in 0.16.0.

Functions¶

build_atomic_attack_identifier¶

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

Build a composite ComponentIdentifier for an atomic attack.

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

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

Returns:

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

Raises:

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

build_seed_identifier¶

build_seed_identifier(seed: Seed) → ComponentIdentifier

Build a ComponentIdentifier from a seed’s behavioral properties.

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

Returns:

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

class_name_to_snake_case¶

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

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

Returns:

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

compute_eval_hash¶

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

Compute a behavioral equivalence hash for evaluation grouping.

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

Children not listed in child_eval_rules receive full recursive treatment.

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

Returns:

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

Raises:

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

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

config_hash¶

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

Compute a deterministic SHA256 hash from a config dictionary.

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

Returns:

• str — Hex-encoded SHA256 hash string.

Raises:

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

print_deprecation_message¶

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

Emit a deprecation warning.

snake_case_to_class_name¶

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

Convert a snake_case name to a PascalCase class name.

Returns:

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

validate_registry_name¶

validate_registry_name(name: str) → None

Validate that name is a legal registry name.

Raises:

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

AtomicAttackEvaluationIdentifier¶

Bases: EvaluationIdentifier

Evaluation identity for atomic attacks.

Per-child rules:

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

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

• objective_target — include only temperature.

• adversarial_chat — include underlying_model_name, temperature, top_p.

• objective_scorer — excluded entirely.

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

ChildEvalRule¶

Bases: BaseModel

Per-child configuration for eval-hash computation.

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

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

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

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

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

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

ComponentIdentifier¶

Bases: BaseModel

Immutable snapshot of a component’s behavioral configuration.

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

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

Serialization¶

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

Mutability¶

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

Methods:

from_dict¶

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

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

Returns:

• ComponentIdentifier — A new ComponentIdentifier.

get_child¶

get_child(key: str) → Optional[ComponentIdentifier]

Get a single child by key.

Returns:

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

Raises:

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

get_child_list¶

get_child_list(key: str) → list[ComponentIdentifier]

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

Returns:

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

of¶

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

Build a ComponentIdentifier from a live object instance.

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

Returns:

• ComponentIdentifier — A new ComponentIdentifier describing obj.

to_dict¶

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

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

Returns:

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

with_eval_hash¶

with_eval_hash(eval_hash: str) → ComponentIdentifier

Return a new identifier with eval_hash set.

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

Returns:

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

• ComponentIdentifier — eval_hash set to the given value.

EvaluationIdentifier¶

Bases: ABC

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

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

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

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

Identifiable¶

Bases: ABC

Abstract base class for components that provide a behavioral identity.

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

Methods:

get_identifier¶

get_identifier() → ComponentIdentifier

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

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

Returns:

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

IdentifierFilter¶

Bases: BaseModel

Immutable filter definition for matching JSON-backed identifier properties.

IdentifierType¶

Bases: Enum

Enumeration of supported identifier types for filtering.

ObjectiveTargetEvaluationIdentifier¶

Bases: EvaluationIdentifier

Evaluation identity for an objective target.

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

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

ScorerEvaluationIdentifier¶

Bases: EvaluationIdentifier

Evaluation identity for scorers.

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