pyrit.registry

Registry module for PyRIT class and object registries.

Functions¶

`discover_in_directory`¶

discover_in_directory(directory: Path, base_class: type[T], recursive: bool = True) → Iterator[tuple[str, Path, type[T]]]

Discover all subclasses of base_class in a directory by loading Python files.

This function walks a directory, loads Python files dynamically, and yields any classes that are subclasses of the specified base_class.

Parameter	Type	Description
`directory`	`Path`	The directory to search for Python files.
`base_class`	`type[T]`	The base class to filter subclasses of.
`recursive`	`bool`	Whether to recursively search subdirectories. Defaults to True. Defaults to `True`.

`discover_in_package`¶

discover_in_package(package_path: Path, package_name: str, base_class: type[T], recursive: bool = True, name_builder: Optional[Callable[[str, str], str]] = None, _prefix: str = '') → Iterator[tuple[str, type[T]]]

Discover all subclasses using pkgutil.iter_modules on a package.

This function uses Python’s package infrastructure to discover modules, making it suitable for discovering classes in installed packages.

Parameter	Type	Description
`package_path`	`Path`	The filesystem path to the package directory.
`package_name`	`str`	The dotted module name of the package (e.g., “pyrit.scenario.scenarios”).
`base_class`	`type[T]`	The base class to filter subclasses of.
`recursive`	`bool`	Whether to recursively search subpackages. Defaults to True. Defaults to `True`.
`name_builder`	`Optional[Callable[[str, str], str]]`	Optional callable to build the registry name from (prefix, module_name). Defaults to returning just the module_name. Defaults to `None`.
`_prefix`	`str`	Internal parameter to track the current subdirectory prefix. Defaults to `''`.

`discover_subclasses_in_loaded_modules`¶

discover_subclasses_in_loaded_modules(base_class: type[T], exclude_module_prefixes: Optional[tuple[str, ...]] = None) → Iterator[tuple[str, type[T]]]

Discover subclasses of a base class from already-loaded modules.

This is useful for discovering user-defined classes that were loaded via initialization scripts or dynamic imports.

Parameter	Type	Description
`base_class`	`type[T]`	The base class to filter subclasses of.
`exclude_module_prefixes`	`Optional[tuple[str, ...]]`	Module prefixes to exclude from search. Defaults to common system modules. Defaults to `None`.

`AttackTechniqueRegistry`¶

Bases: BaseInstanceRegistry['AttackTechniqueFactory']

Singleton registry of reusable attack technique factories.

Scenarios and initializers register technique factories (capturing technique-specific config). Scenarios retrieve them via create_technique(), which calls the factory with the scenario’s objective target and scorer.

Methods:

`create_technique`¶

create_technique(name: str, objective_target: PromptTarget, attack_scoring_config: AttackScoringConfig, attack_adversarial_config: AttackAdversarialConfig | None = None, attack_converter_config: AttackConverterConfig | None = None) → AttackTechnique

Retrieve a factory by name and produce a fresh attack technique.

Parameter	Type	Description
`name`	`str`	The registry name of the technique.
`objective_target`	`PromptTarget`	The target to attack.
`attack_scoring_config`	`AttackScoringConfig`	Scoring configuration for the attack.
`attack_adversarial_config`	`AttackAdversarialConfig	None`
`attack_converter_config`	`AttackConverterConfig	None`

Returns:

AttackTechnique — A fresh AttackTechnique with a newly-constructed attack strategy.

Raises:

KeyError — If no technique is registered with the given name.

`register_technique`¶

register_technique(name: str, factory: AttackTechniqueFactory, tags: dict[str, str] | list[str] | None = None) → None

Parameter	Type	Description
`name`	`str`	The registry name for this technique.
`factory`	`AttackTechniqueFactory`	The factory that produces attack techniques.
`tags`	`dict[str, str]	list[str]

`BaseClassRegistry`¶

Bases: ABC, RegistryProtocol[MetadataT], Generic[T, MetadataT]

Abstract base class for registries that store classes (Type[T]).

This class implements RegistryProtocol and provides the common infrastructure for class registries including:

Lazy discovery of classes
Registration of classes or factory callables
Metadata caching
Consistent API: get_class(), get_names(), list_metadata(), create_instance()
Singleton pattern support via get_registry_singleton()

Subclasses must implement:

_discover(): Populate the registry with discovered classes
_build_metadata(): Build a metadata TypedDict for a class

Constructor Parameters:

Parameter	Type	Description
`lazy_discovery`	`bool`	If True, discovery is deferred until first access. If False, discovery runs immediately in constructor. Defaults to `True`.

Methods:

`create_instance`¶

create_instance(name: str, kwargs: object = {}) → T

Create an instance of a registered class.

Parameter	Type	Description
`name`	`str`	The registry name of the class.
`**kwargs`	`object`	Keyword arguments to pass to the factory or constructor. Defaults to `{}`.

Returns:

T — A new instance of type T.

Raises:

KeyError — If the name is not registered.

`get_class`¶

get_class(name: str) → type[T]

Get a registered class by name.

Parameter	Type	Description
`name`	`str`	The registry name (snake_case identifier).

Returns:

type[T] — The registered class (Type[T]).
type[T] — This returns the class itself, not an instance.

Raises:

KeyError — If the name is not registered.

`get_entry`¶

get_entry(name: str) → Optional[ClassEntry[T]]

Get the full ClassEntry for a registered class.

This is useful when you need access to factory or default_kwargs.

Parameter	Type	Description
`name`	`str`	The registry name.

Returns:

Optional[ClassEntry[T]] — The ClassEntry containing class, factory, and defaults, or None if not found.

`get_names`¶

get_names() → list[str]

Get a sorted list of all registered names.

These are the snake_case registry keys (e.g., “encoding”, “self_ask_refusal”), not the actual class names (e.g., “EncodingScenario”, “SelfAskRefusalScorer”).

Returns:

list[str] — Sorted list of registry names.

`get_registry_singleton`¶

get_registry_singleton() → Self

Get the singleton instance of this registry.

Creates the instance on first call with default parameters.

Returns:

Self — The singleton instance of this registry class.

`list_metadata`¶

list_metadata(include_filters: Optional[dict[str, object]] = None, exclude_filters: Optional[dict[str, object]] = None) → list[MetadataT]

List metadata for all registered classes, optionally filtered.

Supports filtering on any metadata property:

Simple types (str, int, bool): exact match
List types: checks if filter value is in the list

Parameter	Type	Description
`include_filters`	`Optional[dict[str, object]]`	Optional dict of filters that items must match. Keys are metadata property names, values are the filter criteria. All filters must match (AND logic). Defaults to `None`.
`exclude_filters`	`Optional[dict[str, object]]`	Optional dict of filters that items must NOT match. Keys are metadata property names, values are the filter criteria. Any matching filter excludes the item. Defaults to `None`.

Returns:

list[MetadataT] — List of metadata dictionaries (TypedDict) describing each registered class.
list[MetadataT] — This returns descriptive info, not the classes themselves.

`register`¶

register(name: Optional[str] = None, factory: Optional[Callable[..., T]] = None, default_kwargs: Optional[dict[str, object]] = None, description: Optional[str] = None) → None

Parameter	Type	Description
`cls`	`type[T]`	The class to register (Type[T], not an instance).
`name`	`Optional[str]`	Optional custom registry name. If not provided, derived from class name. Defaults to `None`.
`factory`	`Optional[Callable[..., T]]`	Optional callable for creating instances with custom logic. Defaults to `None`.
`default_kwargs`	`Optional[dict[str, object]]`	Default keyword arguments for instance creation. Defaults to `None`.
`description`	`Optional[str]`	Optional description override. Defaults to `None`.

`reset_instance`¶

reset_instance() → None

Reset the singleton instance.

Useful for testing or when re-discovery is needed.

`BaseInstanceRegistry`¶

Bases: ABC, RegistryProtocol[ComponentIdentifier], Generic[T]

Abstract base class providing shared registry infrastructure.

Provides singleton lifecycle, registration, tag-based lookup, metadata filtering, and the standard container protocol (__contains__, __len__, __iter__).

Subclass directly when stored items should not be retrievable via get() (e.g., factory registries). For registries that expose direct item retrieval, subclass RetrievableInstanceRegistry instead.

All stored items must implement Identifiable, which provides get_identifier() for metadata generation.

Methods:

`add_tags`¶

add_tags(name: str, tags: dict[str, str] | list[str]) → None

Add tags to an existing registry entry.

Parameter	Type	Description
`name`	`str`	The registry name of the entry to tag.
`tags`	`dict[str, str]	list[str]`

Raises:

KeyError — If no entry with the given name exists.

`find_dependents_of_tag`¶

find_dependents_of_tag(tag: str) → list[RegistryEntry[T]]

Find entries whose children depend on entries with the given tag.

Scans each registry entry’s ComponentIdentifier tree and checks whether any child’s eval_hash matches the eval_hash of an entry that carries tag. Entries that themselves carry tag are excluded from the results.

This enables automatic dependency detection: for example, tagging base refusal scorers with "refusal" lets you discover all wrapper scorers (inverters, composites) that embed a refusal scorer without any explicit depends_on declaration.

Parameter	Type	Description
`tag`	`str`	The tag key that identifies the “base” entries.

Returns:

list[RegistryEntry[T]] — List of RegistryEntry objects that depend on tagged entries,
list[RegistryEntry[T]] — sorted by name.

`get_by_tag`¶

get_by_tag(tag: str, value: str | None = None) → list[RegistryEntry[T]]

Get all entries that have a given tag, optionally matching a specific value.

Parameter	Type	Description
`tag`	`str`	The tag key to match.
`value`	`str	None`

Returns:

list[RegistryEntry[T]] — List of matching RegistryEntry objects sorted by name.

`get_names`¶

get_names() → list[str]

Get a sorted list of all registered names.

Returns:

list[str] — Sorted list of registry names (keys).

`get_registry_singleton`¶

get_registry_singleton() → Self

Get the singleton instance of this registry.

Creates the instance on first call with default parameters.

Returns:

Self — The singleton instance of this registry class.

`list_metadata`¶

list_metadata(include_filters: dict[str, object] | None = None, exclude_filters: dict[str, object] | None = None) → list[ComponentIdentifier]

List metadata for all registered items, optionally filtered.

Supports filtering on any metadata property:

Simple types (str, int, bool): exact match
List types: checks if filter value is in the list

Parameter	Type	Description
`include_filters`	`dict[str, object]	None`
`exclude_filters`	`dict[str, object]	None`

Returns:

list[ComponentIdentifier] — List of ComponentIdentifier metadata for each registered item.

`register`¶

register(instance: T, name: str, tags: dict[str, str] | list[str] | None = None) → None

Parameter	Type	Description
`instance`	`T`	The item to register.
`name`	`str`	The registry name for this item.
`tags`	`dict[str, str]	list[str]

`reset_instance`¶

reset_instance() → None

Reset the singleton instance.

Useful for testing or reinitializing the registry.

`ClassEntry`¶

Bases: Generic[T]

Internal wrapper for a registered class.

This holds the class itself (Type[T]) along with optional factory and default parameters for creating instances.

Note: This is an internal implementation detail. Users interact with registries via get_class(), create_instance(), and list_metadata().

Constructor Parameters:

Parameter	Type	Description
`registered_class`	`type[T]`	The actual Python class (Type[T]).
`factory`	`Optional[Callable[..., T]]`	Optional callable that creates an instance. Defaults to `None`.
`default_kwargs`	`Optional[dict[str, object]]`	Default keyword arguments for instantiation. Defaults to `None`.
`description`	`Optional[str]`	Optional description override. Defaults to `None`.

Methods:

`create_instance`¶

create_instance(kwargs: object = {}) → T

Create an instance of the registered class.

Parameter	Type	Description
`**kwargs`	`object`	Additional keyword arguments. These override default_kwargs. Defaults to `{}`.

Returns:

T — An instance of type T.

`ConverterRegistry`¶

Bases: RetrievableInstanceRegistry['PromptConverter']

Registry for managing available converter instances.

This registry stores pre-configured PromptConverter instances (not classes). Converters are registered explicitly via initializers after being instantiated with their required parameters.

Methods:

`get_instance_by_name`¶

get_instance_by_name(name: str) → Optional[PromptConverter]

Get a registered converter instance by name.

Parameter	Type	Description
`name`	`str`	The registry name of the converter.

Returns:

Optional[PromptConverter] — The converter instance, or None if not found.

`register_instance`¶

register_instance(converter: PromptConverter, name: Optional[str] = None, tags: Optional[Union[dict[str, str], list[str]]] = None) → None

Parameter	Type	Description
`converter`	`PromptConverter`	The pre-configured converter instance (not a class).
`name`	`Optional[str]`	Optional custom registry name. If not provided, derived from the converter’s unique identifier. Defaults to `None`.
`tags`	`Optional[Union[dict[str, str], list[str]]]`	Optional tags for categorisation. Accepts a `dict[str, str]` or a `list[str]` (each string becomes a key with value `""`). Defaults to `None`.

`InitializerMetadata`¶

Bases: ClassRegistryEntry

Metadata describing a registered PyRITInitializer class.

Use get_class() to get the actual class.

`InitializerRegistry`¶

Bases: BaseClassRegistry['PyRITInitializer', InitializerMetadata]

Registry for discovering and managing available initializers.

This class discovers all PyRITInitializer subclasses from the pyrit/setup/initializers directory structure.

Initializers are identified by their filename (e.g., “objective_target”, “simple”). The directory structure is used for organization but not exposed to users.

Constructor Parameters:

Parameter	Type	Description
`discovery_path`	`Optional[Path]`	The path to discover initializers from. If None, defaults to pyrit/setup/initializers (discovers all). To discover only scenarios, pass pyrit/setup/initializers/scenarios. Defaults to `None`.
`lazy_discovery`	`bool`	If True, discovery is deferred until first access. Defaults to False for backwards compatibility. Defaults to `False`.

Methods:

`resolve_script_paths`¶

resolve_script_paths(script_paths: list[str]) → list[Path]

Resolve and validate custom script paths.

Parameter	Type	Description
`script_paths`	`list[str]`	List of script path strings to resolve.

Returns:

list[Path] — List of resolved Path objects.

Raises:

FileNotFoundError — If any script path does not exist.

`RegistryEntry`¶

Bases: Generic[T]

A wrapper around a registered item, holding its name, tags, and the item itself.

Tags are always stored as dict[str, str]. When callers pass a plain list[str], each string is normalized to a key with an empty-string value.

`RegistryProtocol`¶

Bases: Protocol[MetadataT]

Protocol defining the common interface for all registries.

Both class registries (BaseClassRegistry) and object registries (BaseInstanceRegistry) implement this interface, enabling code that works with either registry type.

Methods:

`get_names`¶

get_names() → list[str]

Get a sorted list of all registered names.

`get_registry_singleton`¶

get_registry_singleton() → Self

Get the singleton instance of this registry.

`list_metadata`¶

list_metadata(include_filters: Optional[dict[str, Any]] = None, exclude_filters: Optional[dict[str, Any]] = None) → list[MetadataT]

List metadata for all registered items, optionally filtered.

Parameter	Type	Description
`include_filters`	`Optional[dict[str, Any]]`	Optional dict of filters that items must match. Keys are metadata property names, values are the filter criteria. All filters must match (AND logic). Defaults to `None`.
`exclude_filters`	`Optional[dict[str, Any]]`	Optional dict of filters that items must NOT match. Keys are metadata property names, values are the filter criteria. Any matching filter excludes the item. Defaults to `None`.

Returns:

list[MetadataT] — List of metadata describing each registered item.

`reset_instance`¶

reset_instance() → None

Reset the singleton instance.

`RetrievableInstanceRegistry`¶

Bases: BaseInstanceRegistry[T]

Base class for registries that store directly-retrievable instances.

Extends BaseInstanceRegistry with get(), get_entry(), and get_all_instances() for registries where callers retrieve the stored objects directly (e.g., scorers, converters, targets).

For registries that store factories or other non-retrievable items, subclass BaseInstanceRegistry directly instead.

Methods:

`get`¶

get(name: str) → T | None

Get a registered instance by name.

Parameter	Type	Description
`name`	`str`	The registry name of the instance.

Returns:

T | None — The instance, or None if not found.

`get_all_instances`¶

get_all_instances() → list[RegistryEntry[T]]

Get all registered entries sorted by name.

Returns:

list[RegistryEntry[T]] — List of RegistryEntry objects sorted by name.

`get_entry`¶

get_entry(name: str) → RegistryEntry[T] | None

Get a full registry entry by name, including tags.

Parameter	Type	Description
`name`	`str`	The registry name of the entry.

Returns:

RegistryEntry[T] | None — The RegistryEntry, or None if not found.

`ScenarioMetadata`¶

Bases: ClassRegistryEntry

Metadata describing a registered Scenario class.

Use get_class() to get the actual class.

`ScenarioRegistry`¶

Bases: BaseClassRegistry['Scenario', ScenarioMetadata]

Registry for discovering and managing available scenario classes.

This class discovers all Scenario subclasses from:

Built-in scenarios in pyrit.scenario.scenarios module
User-defined scenarios from initialization scripts (set via globals)

Scenarios are identified by their dotted name (e.g., “garak.encoding”, “foundry.red_team_agent”).

Constructor Parameters:

Parameter	Type	Description
`lazy_discovery`	`bool`	If True, discovery is deferred until first access. Defaults to True for performance. Defaults to `True`.

Methods:

`discover_user_scenarios`¶

discover_user_scenarios() → None

Discover user-defined scenarios from global variables.

After initialization scripts are executed, they may define Scenario subclasses and store them in globals. This method searches for such classes.

User scenarios will override built-in scenarios with the same name.

`ScorerRegistry`¶

Bases: RetrievableInstanceRegistry['Scorer']

Registry for managing available scorer instances.

This registry stores pre-configured Scorer instances (not classes). Scorers are registered explicitly via initializers after being instantiated with their required parameters (e.g., chat_target).

Scorers are identified by their snake_case name derived from the class name, or a custom name provided during registration.

Methods:

`get_instance_by_name`¶

get_instance_by_name(name: str) → Optional[Scorer]

Get a registered scorer instance by name.

Note: This returns an already-instantiated scorer, not a class.

Parameter	Type	Description
`name`	`str`	The registry name of the scorer.

Returns:

Optional[Scorer] — The scorer instance, or None if not found.

`register_instance`¶

register_instance(scorer: Scorer, name: Optional[str] = None, tags: Optional[Union[dict[str, str], list[str]]] = None) → None

Note: Unlike ScenarioRegistry and InitializerRegistry which register classes, ScorerRegistry registers pre-configured instances.

Parameter	Type	Description
`scorer`	`Scorer`	The pre-configured scorer instance (not a class).
`name`	`Optional[str]`	Optional custom registry name. If not provided, derived from the scorer’s unique identifier. Defaults to `None`.
`tags`	`Optional[Union[dict[str, str], list[str]]]`	Optional tags for categorisation. Accepts a `dict[str, str]` or a `list[str]` (each string becomes a key with value `""`). Defaults to `None`.

`TargetRegistry`¶

Bases: RetrievableInstanceRegistry['PromptTarget']

Registry for managing available prompt target instances.

This registry stores pre-configured PromptTarget instances (not classes). Targets are registered explicitly via initializers after being instantiated with their required parameters (e.g., endpoint, API keys).

Targets are identified by their snake_case name derived from the class name, or a custom name provided during registration.

Methods:

`get_instance_by_name`¶

get_instance_by_name(name: str) → Optional[PromptTarget]

Get a registered target instance by name.

Note: This returns an already-instantiated target, not a class.

Parameter	Type	Description
`name`	`str`	The registry name of the target.

Returns:

Optional[PromptTarget] — The target instance, or None if not found.

`register_instance`¶

register_instance(target: PromptTarget, name: Optional[str] = None, tags: Optional[Union[dict[str, str], list[str]]] = None) → None

Note: Unlike ScenarioRegistry and InitializerRegistry which register classes, TargetRegistry registers pre-configured instances.

Parameter	Type	Description
`target`	`PromptTarget`	The pre-configured target instance (not a class).
`name`	`Optional[str]`	Optional custom registry name. If not provided, derived from class name with identifier hash appended (e.g., OpenAIChatTarget -> openai_chat_abc123). Defaults to `None`.
`tags`	`Optional[Union[dict[str, str], list[str]]]`	Optional tags for categorization. Accepts a `dict[str, str]` or a `list[str]` (each string becomes a key with value `""`). Defaults to `None`.

Functions¶

discover_in_directory¶

discover_in_package¶

discover_subclasses_in_loaded_modules¶

AttackTechniqueRegistry¶

create_technique¶

register_technique¶

BaseClassRegistry¶

create_instance¶

get_class¶

get_entry¶

get_names¶

get_registry_singleton¶

list_metadata¶

register¶

reset_instance¶

BaseInstanceRegistry¶

add_tags¶

find_dependents_of_tag¶

get_by_tag¶

get_names¶

get_registry_singleton¶

list_metadata¶

register¶

reset_instance¶

ClassEntry¶

create_instance¶

ConverterRegistry¶

get_instance_by_name¶

register_instance¶

InitializerMetadata¶

InitializerRegistry¶

resolve_script_paths¶

RegistryEntry¶

RegistryProtocol¶

get_names¶

get_registry_singleton¶

list_metadata¶

reset_instance¶

RetrievableInstanceRegistry¶

get¶

get_all_instances¶

get_entry¶

ScenarioMetadata¶

ScenarioRegistry¶

discover_user_scenarios¶

ScorerRegistry¶

get_instance_by_name¶

register_instance¶

TargetRegistry¶

get_instance_by_name¶

register_instance¶

`discover_in_directory`¶

`discover_in_package`¶

`discover_subclasses_in_loaded_modules`¶

`AttackTechniqueRegistry`¶

`create_technique`¶

`register_technique`¶

`BaseClassRegistry`¶

`create_instance`¶

`get_class`¶

`get_entry`¶

`get_names`¶

`get_registry_singleton`¶

`list_metadata`¶

`register`¶

`reset_instance`¶

`BaseInstanceRegistry`¶

`add_tags`¶

`find_dependents_of_tag`¶

`get_by_tag`¶

`get_names`¶

`get_registry_singleton`¶

`list_metadata`¶

`register`¶

`reset_instance`¶

`ClassEntry`¶

`create_instance`¶

`ConverterRegistry`¶

`get_instance_by_name`¶

`register_instance`¶

`InitializerMetadata`¶

`InitializerRegistry`¶

`resolve_script_paths`¶

`RegistryEntry`¶

`RegistryProtocol`¶

`get_names`¶

`get_registry_singleton`¶

`list_metadata`¶

`reset_instance`¶

`RetrievableInstanceRegistry`¶

`get`¶

`get_all_instances`¶

`get_entry`¶

`ScenarioMetadata`¶

`ScenarioRegistry`¶

`discover_user_scenarios`¶

`ScorerRegistry`¶

`get_instance_by_name`¶

`register_instance`¶

`TargetRegistry`¶

`get_instance_by_name`¶

`register_instance`¶