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¶

class_name_to_snake_case¶

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

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

Returns:

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

compute_eval_hash¶

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

Compute a behavioral equivalence hash for evaluation grouping.

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

Children not listed in child_eval_rules receive full recursive treatment.

When both child_eval_rules is empty and own_rule is None (and no root unwrap applies), no filtering occurs and the result equals identifier.hash.

Returns:

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

Raises:

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

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

config_hash¶

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

Compute a deterministic SHA256 hash from a config dictionary.

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

Returns:

• str — Hex-encoded SHA256 hash string.

Raises:

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

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.

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.

ChildEvalRule¶

Bases: BaseModel

Per-child configuration for eval-hash computation.

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

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

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

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

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

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

ComponentIdentifier¶

Bases: BaseModel

Immutable snapshot of a component’s behavioral configuration.

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

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

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

Serialization: model_dump() returns a flat dict where reserved keys (class_name, class_module, hash, pyrit_version, eval_hash, children) sit at the top level alongside the inlined param values. This shape is also the storage / REST format. Param values are stored in full (no truncation). model_validate() accepts the same flat shape (plus a structured form with an explicit params dict); the content hash is always recomputed on validation, so any stored hash is ignored.

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

Methods:

from_component_identifier¶

from_component_identifier(identifier: ComponentIdentifier) → Self

Return identifier as an instance of this typed subclass.

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

Returns:

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

from_dict¶

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

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

Returns:

• ComponentIdentifier — A new ComponentIdentifier.

get_child¶

get_child(key: str) → ComponentIdentifier | None

Get a single child by key.

Returns:

• ComponentIdentifier | None — The child identifier, or None if not present.

Raises:

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

get_child_list¶

get_child_list(key: str) → list[ComponentIdentifier]

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

Returns:

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

of¶

of(obj: object, params: dict[str, Any] | None = None, children: dict[str, ComponentIdentifier | list[ComponentIdentifier]] | None = None, promoted: Any = {}) → Self

Build a ComponentIdentifier from a live object instance.

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

Returns:

• Self — A new ComponentIdentifier describing obj.

to_dict¶

to_dict() → dict[str, Any]

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

Returns:

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

with_eval_hash¶

with_eval_hash(eval_hash: str) → ComponentIdentifier

Return a new identifier with eval_hash set.

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

Returns:

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

• ComponentIdentifier — eval_hash set to the given value.

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.

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.

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.

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