pyrit.identifiers.ComponentIdentifier

class ComponentIdentifier(class_name: str, class_module: str, params: dict[str, ~typing.Any] = <factory>, children: dict[str, ~pyrit.identifiers.component_identifier.ComponentIdentifier | list[~pyrit.identifiers.component_identifier.ComponentIdentifier]] = <factory>, pyrit_version: str = <factory>)

Bases: object

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.

__init__(class_name: str, class_module: str, params: dict[str, ~typing.Any] = <factory>, children: dict[str, ~pyrit.identifiers.component_identifier.ComponentIdentifier | list[~pyrit.identifiers.component_identifier.ComponentIdentifier]] = <factory>, pyrit_version: str = <factory>) → None

Methods

__init__(class_name, class_module[, params, ...])
from_dict(data)	Deserialize from a stored dictionary.
get_child(key)	Get a single child by key.
get_child_list(key)	Get a list of children by key.
normalize(value)	Normalize a value to a ComponentIdentifier instance.
of(obj, *[, params, children])	Build a ComponentIdentifier from a live object instance.
to_dict(*[, max_value_length])	Serialize to a JSON-compatible dictionary for DB/JSONL storage.

Attributes

KEY_CHILDREN
KEY_CLASS_MODULE
KEY_CLASS_NAME
KEY_HASH
KEY_PYRIT_VERSION
LEGACY_KEY_MODULE
LEGACY_KEY_TYPE
short_hash	Return the first 8 characters of the hash for display and logging.
unique_name	class_name::short_hash.
class_name	Python class name (e.g., "SelfAskScaleScorer").
class_module	Full module path (e.g., "pyrit.score.self_ask_scale_scorer").
params	Behavioral parameters that affect output.
children	Named child identifiers for compositional identity (e.g., a scorer's target).
hash	Content-addressed SHA256 hash computed from class, params, and children.
pyrit_version	Version tag for storage.

KEY_CHILDREN: ClassVar[str] = 'children'

KEY_CLASS_MODULE: ClassVar[str] = 'class_module'

KEY_CLASS_NAME: ClassVar[str] = 'class_name'

KEY_HASH: ClassVar[str] = 'hash'

KEY_PYRIT_VERSION: ClassVar[str] = 'pyrit_version'

LEGACY_KEY_MODULE: ClassVar[str] = '__module__'

LEGACY_KEY_TYPE: ClassVar[str] = '__type__'

children: dict[str, ComponentIdentifier | list[ComponentIdentifier]]

Named child identifiers for compositional identity (e.g., a scorer’s target).

class_module: str

Full module path (e.g., “pyrit.score.self_ask_scale_scorer”).

class_name: str

Python class name (e.g., “SelfAskScaleScorer”).

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

Deserialize from a stored dictionary.

Reconstructs a ComponentIdentifier from data previously saved via to_dict(). Handles both the current format (class_name/class_module) and legacy format (__type__/__module__) for backward compatibility with older database records.

Note

This reconstruction is lossy. If to_dict() was called with a max_value_length limit, param values may have been truncated before storage. The original untruncated values cannot be recovered. To preserve correct identity, the stored hash (computed from the original untruncated data) is kept as-is rather than recomputed from the potentially truncated params.

Parameters:

data (Dict[str, Any]) – Dictionary from DB/JSONL storage. The original dict is not mutated; a copy is made internally.

Returns:

Reconstructed identifier with the stored hash

preserved (if available) to maintain correct identity despite potential param truncation.

Return type:

ComponentIdentifier

get_child(key: str) → ComponentIdentifier | None

Get a single child by key.

Parameters:

key (str) – The child key.

Returns:

The child, or None if not found.

Return type:

Optional[ComponentIdentifier]

Raises:

ValueError – If the child is a list (use get_child_list instead).

get_child_list(key: str) → list[ComponentIdentifier]

Get a list of children by key.

Parameters:

key (str) – The child key.

Returns:

The children. Returns empty list if

not found, wraps single child in a list.

Return type:

List[ComponentIdentifier]

hash: str

Content-addressed SHA256 hash computed from class, params, and children.

classmethod normalize(value: ComponentIdentifier | dict[str, Any]) → ComponentIdentifier

Normalize a value to a ComponentIdentifier instance.

Accepts either an existing ComponentIdentifier (returned as-is) or a dict (reconstructed via from_dict). This supports code paths that may receive either typed identifiers or raw dicts from database storage.

Parameters:

value (Union[ComponentIdentifier, Dict[str, Any]]) – A ComponentIdentifier or a dictionary representation.

Returns:

The normalized identifier instance.

Return type:

ComponentIdentifier

Raises:

TypeError – If value is neither a ComponentIdentifier nor a dict.

classmethod of(obj: object, *, params: dict[str, Any] | None = None, children: dict[str, ComponentIdentifier | list[ComponentIdentifier]] | None = None) → ComponentIdentifier

Build a ComponentIdentifier from a live object instance.

This factory method extracts class_name and class_module from the object’s type automatically, making it the preferred way to create identifiers in component implementations. None-valued params and children are filtered out to ensure backward-compatible hashing.

Parameters:

• obj (object) – The live component instance whose type info will be captured.

• params (Optional[Dict[str, Any]]) – Behavioral parameters that affect the component’s output. Only include params that change behavior — exclude operational settings like rate limits, retry counts, or logging config.

• children (Optional[Dict[str, Union[ComponentIdentifier, List[ComponentIdentifier]]]]) – Named child component identifiers. Use for compositional components like scorers that wrap other scorers or targets that chain converters.

Returns:

The frozen identity snapshot with computed hash.

Return type:

ComponentIdentifier

params: dict[str, Any]

Behavioral parameters that affect output.

pyrit_version: str

Version tag for storage. Not included in hash.

property short_hash: str

Return the first 8 characters of the hash for display and logging.

Returns:

First 8 hex characters of the SHA256 hash.

Return type:

str

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

Serialize to a JSON-compatible dictionary for DB/JSONL storage.

Produces a flat structure where params are inlined at the top level alongside class_name, class_module, hash, and pyrit_version.

Children are recursively serialized into a nested “children” key.

Parameters:

max_value_length (Optional[int]) – If provided, string param values longer than this limit are truncated and suffixed with “…”. Useful for DB storage where column sizes may be limited. The truncation applies only to param values, not to structural keys like class_name or hash. The limit is propagated to children. Defaults to None (no truncation).

Returns:

JSON-serializable dictionary suitable for database storage

or JSONL export.

Return type:

Dict[str, Any]

property unique_name: str

class_name::short_hash.

Used as the default registration key in instance registries (e.g., “SelfAskScaleScorer::a1b2c3d4”).

Returns:

Unique name combining class name and short hash.

Return type:

str

Type:

Globally unique display name