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.

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.

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.

AttackTechniqueRegistry¶

Bases: BaseInstanceRegistry['AttackTechniqueFactory']

Singleton registry of reusable attack technique factories.

Scenarios and initializers register technique factories (capturing technique-specific config). Scenarios retrieve factories via get_factories() and call factory.create() with the scenario’s objective target and scorer.

Methods:

build_factory_from_spec¶

build_factory_from_spec(spec: AttackTechniqueSpec, scorer_override_policy: ScorerOverridePolicy | None = None) → AttackTechniqueFactory

Build an AttackTechniqueFactory from an AttackTechniqueSpec.

The adversarial chat target (spec.adversarial_chat) is stored on the factory as an AttackAdversarialConfig. The factory injects it into the attack constructor at create() time if the attack class accepts attack_adversarial_config.

Returns:

• AttackTechniqueFactory — A factory ready for registration.

Raises:

• ValueError — If extra_kwargs contains the reserved key attack_adversarial_config.

build_strategy_class_from_specs¶

build_strategy_class_from_specs(class_name: str, specs: list[AttackTechniqueSpec], aggregate_tags: dict[str, TagQuery]) → type

Build a ScenarioStrategy enum subclass dynamically from technique specs.

Creates an enum class with:

• An ALL aggregate member (always included).

• Additional aggregate members from aggregate_tags keys.

• One technique member per spec, with tags from the spec.

Each aggregate maps to a TagQuery that determines which technique specs belong to it.

This reads from the spec list (pure data), not from the mutable registry. This ensures deterministic output regardless of registry state.

Returns:

• type — A ScenarioStrategy subclass with the generated members.

get_factories¶

get_factories() → dict[str, AttackTechniqueFactory]

Return all registered factories as a name→factory dict.

Returns:

• dict[str, AttackTechniqueFactory] — dict[str, AttackTechniqueFactory]: Mapping of technique name to factory.

register_from_specs¶

register_from_specs(specs: list[AttackTechniqueSpec]) → None

Build factories from specs and register them.

Per-name idempotent: existing entries are not overwritten.

register_technique¶

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

Register an attack technique factory.

AttackTechniqueSpec¶

Declarative definition of an attack technique.

The registry converts specs into AttackTechniqueFactory instances. A minimal spec only needs name and attack_class::

AttackTechniqueSpec(name="prompt_sending", attack_class=PromptSendingAttack)

Use extra_kwargs for constructor arguments specific to a particular attack class (as opposed to common arguments like objective_target and attack_scoring_config, which the factory injects automatically)::

AttackTechniqueSpec(
    name="role_play",
    attack_class=RolePlayAttack,
    strategy_tags=["core", "single_turn"],
    extra_kwargs={"role_play_definition_path": RolePlayPaths.MOVIE_SCRIPT.value},
)

Attacks that need an adversarial chat target should set adversarial_chat (resolved target) or adversarial_chat_key (deferred TargetRegistry key resolved at runtime by build_scenario_techniques()). These are mutually exclusive. The registry automatically injects an AttackAdversarialConfig when the attack class accepts one and adversarial_chat is set.

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:

Methods:

create_instance¶

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

Create an instance of a registered class.

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.

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.

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

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) → None

Register a class with the registry.

reset_instance¶

reset_instance() → None

Reset the singleton instance.

Useful for testing or when re-discovery is needed.

unregister¶

unregister(name: str) → None

Remove a registered class from the registry.

Raises:

• KeyError — If the name is not registered.

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.

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.

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.

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

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, metadata: dict[str, Any] | None = None) → None

Register an item.

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:

Methods:

create_instance¶

create_instance(kwargs: object = {}) → T

Create an instance of the registered class.

Returns:

• T — An instance of type T.

get_description¶

get_description(fallback: str = '') → str

Resolve description from docstring, falling back to provided default.

Returns:

• str — The resolved description string.

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.

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

Register a converter instance.

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:

Methods:

is_builtin¶

is_builtin(name: str) → bool

Return True if name was registered during built-in discovery.

register_from_content¶

register_from_content(name: str, script_content: str) → str

Register an initializer from uploaded Python source code.

Writes script_content to a managed directory, loads it as a module, discovers the first concrete PyRITInitializer subclass, and registers it under name.

Returns:

• str — The registry name that was registered.

Raises:

• ValueError — If the source cannot be compiled, does not contain a valid initializer class, or name collides with an existing entry.

resolve_script_paths¶

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

Resolve and validate custom script paths.

Returns:

• list[Path] — List of resolved Path objects.

Raises:

• FileNotFoundError — If any script path does not exist.

unregister_and_cleanup¶

unregister_and_cleanup(name: str) → None

Unregister a custom initializer and clean up its script file.

Built-in initializers cannot be removed. For custom initializers added via register_from_content, the saved script file is also deleted.

Raises:

• KeyError — If the name is not registered.

• ValueError — If the name refers to a built-in initializer.

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.

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.

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.

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.

ScenarioParameterMetadata¶

Bases: NamedTuple

A scenario-declared parameter rendered for user-facing display.

NamedTuple so existing positional construction (e.g. in tests) keeps working while consumers can read fields by name.

ScenarioRegistry¶

Bases: BaseClassRegistry['Scenario', ScenarioMetadata]

Registry for discovering and managing available scenario classes.

This class discovers all Scenario subclasses from:

1. Built-in scenarios in pyrit.scenario.scenarios module

2. 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:

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.

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

Register a scorer instance.

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

TagQuery¶

Boolean predicate over string tag sets.

Leaf fields (include_all, include_any, exclude) are evaluated against a tag set directly. Composite queries are produced by the & and | operators and stored in _op / _children.

Prefer the classmethod shortcuts all, any_of, and exclude for single-field leaves.

Methods:

all¶

all(tags: str = ()) → TagQuery

Leaf query: every tag must be present.

Returns:

• TagQuery — A TagQuery that matches when all given tags are present.

any_of¶

any_of(tags: str = ()) → TagQuery

Leaf query: at least one tag must be present.

Returns:

• TagQuery — A TagQuery that matches when at least one given tag is present.

filter¶

filter(items: list[_T]) → list[_T]

Return items whose tags satisfy this query.

Returns:

• list[_T] — Filtered list preserving original order.

matches¶

matches(tags: set[str] | frozenset[str]) → bool

Return True if tags satisfies this query.

Returns:

• bool — Whether the tag set matches.

none_of¶

none_of(tags: str = ()) → TagQuery

Leaf query: none of the given tags may be present.

Returns:

• TagQuery — A TagQuery that matches when none of the given tags are present.

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.

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

Register a target instance.

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