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.

AttackTechniqueMetadata¶

Bases: RegistryMetadata

Metadata describing a registered attack-technique class.

Placeholder for the buildable catalog, which is intentionally empty until the factory is decoupled into a buildable component. It carries only the common RegistryMetadata fields today; technique-specific fields are added when the catalog is lit up.

AttackTechniqueRegistry¶

Bases: Registry['AttackTechniqueFactory', AttackTechniqueMetadata]

Registry that holds reusable AttackTechniqueFactory instances.

Scenarios and initializers register self-describing AttackTechniqueFactory instances; scenarios retrieve them via get_factories / get_factories_or_raise and call factory.create() with the scenario’s objective target and scorer.

It is a Registry: pre-configured factories live under the instances property (register, get, get_all_instances, get_by_tag, …), a DefaultInstanceRegistry. The buildable class catalog is intentionally empty for now — the factory still owns construction — so _discover registers no classes.

Constructor Parameters:

Methods:

build_technique_class_from_factories¶

build_technique_class_from_factories(class_name: str, factories: list[AttackTechniqueFactory], aggregate_tags: dict[str, TagQuery], available: TagQuery | None = None, default: TagQuery | None = None, default_technique_names: set[str] | None = None) → type

Build a ScenarioTechnique enum subclass dynamically from technique factories.

Creates an enum class with:

• An ALL aggregate member (always included).

• A DEFAULT aggregate member when a default selection is provided.

• Additional aggregate members from aggregate_tags keys.

• One technique member per available factory, with tags from the factory.

The three selection roles are all expressed the same way — as tag queries over factories — and relate as strict subsets:

• available (the pool): available filters factories to the techniques this scenario exposes. When None the whole factories list is the pool (back-compatible).

• aggregates: named TagQuery presets (e.g. single_turn); each is evaluated only over the pool, so every aggregate is a subset of available.

• default: what runs when the caller selects nothing. Given as a TagQuery (default) and/or explicit default_technique_names; both are intersected with the pool, so DEFAULT is always a subset of available.

default is deliberately not an intrinsic technique tag: what runs by default differs per scenario. A scenario selects its default set via a query or by name so the same technique can be default for one scenario and not another, without a catalog-wide tag.

Returns:

• type — A ScenarioTechnique subclass with the generated members.

get_factories¶

get_factories() → dict[str, AttackTechniqueFactory]

Return all registered factories as a name→factory dict.

Callers filter the result in-place using factory properties (e.g. factory.uses_adversarial or factory.technique_tags).

Returns:

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

get_factories_or_raise¶

get_factories_or_raise() → dict[str, AttackTechniqueFactory]

Return all registered factories, raising if the registry is empty.

Use this from any code path that needs the registry to be populated (scenario technique builders, scenario initialization) so an empty registry surfaces a single, descriptive error instead of silently producing empty technique enums or empty attack lists.

Returns:

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

Raises:

• RuntimeError — If the registry has no registered factories.

register_from_factories¶

register_from_factories(factories: list[AttackTechniqueFactory]) → None

Register a list of factories under their name.

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.

ConverterMetadata¶

Bases: RegistryMetadata

Metadata describing a registered Converter class.

Carries the derived parameters build contract (the same list the resolver consumes to build an instance) and, via class_attributes on the base, the converter’s class-level supported input/output types. Presentation facts — the supported types and whether the converter is LLM-based — are projected from those rather than stored, so the entry can never drift from the class or the contract.

Use ConverterRegistry.get_class() to get the actual class or create_instance() to build a configured instance.

ConverterRegistry¶

Bases: Registry['Converter', ConverterMetadata]

Registry that discovers, builds, and holds Converter instances.

Discovers all concrete Converter subclasses exported from pyrit.converter (keyed by their exact class name, e.g. "Base64Converter") for the buildable catalog. Pre-configured instances registered via initializers or the backend are held under the instances property.

Building a converter resolves its arguments through the shared resolver, so LLM converters can be constructed by passing a converter_target that names a target in the TargetRegistry.

Constructor Parameters:

DefaultInstanceRegistry¶

Bases: Generic[T]

Concrete InstanceRegistry implementation assigned to .instances.

Holds named, pre-configured instances with tags and derived metadata. It owns no singleton lifecycle — the registry that exposes it via .instances owns that.

Constructor Parameters:

Methods:

add_tags¶

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

Add tags to an existing 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 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.

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[RegistryEntry[T]]: Entries that depend on tagged entries, sorted

• list[RegistryEntry[T]] — by name.

get¶

get(name: str) → T | None

Get a registered instance by name.

Returns:

• T | None — 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[RegistryEntry[T]]: The entries sorted by name.

get_by_tag¶

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

Get entries that carry a given tag, optionally matching a value.

Returns:

• list[RegistryEntry[T]] — list[RegistryEntry[T]]: Matching entries sorted by name.

get_entry¶

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

Get the full entry (including tags) by name.

Returns:

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

get_names¶

get_names() → list[str]

Get a sorted list of all registered instance names.

Returns:

• list[str] — list[str]: The instance names sorted alphabetically.

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 instances, optionally filtered.

Returns:

• list[ComponentIdentifier] — list[ComponentIdentifier]: The identifier metadata for each instance.

query_by_tags¶

query_by_tags(query: TagQuery) → list[RegistryEntry[T]]

Get entries whose tag keys satisfy a composable TagQuery.

Where get_by_tag matches a single key (optionally a value), this evaluates an arbitrary AND / OR / exclude predicate built with TagQuery (e.g. TagQuery.all("core") & TagQuery.any_of("fast", "cheap")). Matching is on the tag keys only; tag values are not considered.

Returns:

• list[RegistryEntry[T]] — list[RegistryEntry[T]]: Matching entries sorted by name.

register¶

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

Register a pre-configured instance.

Raises:

• TypeError — If this registry was created with an instance_type and instance is not of that type.

InitializerMetadata¶

Bases: RegistryMetadata

Metadata describing a registered PyRITInitializer class.

Use get_class() to get the actual class.

InitializerRegistry¶

Bases: ParamBagRegistry['PyRITInitializer', InitializerMetadata]

Registry for discovering and managing available initializers.

Discovers all PyRITInitializer subclasses from the pyrit/setup/initializers directory structure via a filesystem scan (so _discover is overridden rather than supplying _base_type / _discovery_package). Initializers are identified by their suffix-stripped snake_case class name (e.g., "objective_target", "simple"); the directory structure is used for organization but not exposed to users.

Constructor Parameters:

Methods:

create_and_configure¶

create_and_configure(name: str, initializer_params: dict[str, Any] | None = None) → PyRITInitializer

Build and parameterize an initializer in one call.

Parallels ScenarioRegistry.create_and_initialize_async (which takes scenario_params): the registry — not the caller — owns the build → set-params → validate lifecycle. Unlike scenarios, initialize_async is invoked later by the PyRIT init flow, so this stops at configure and returns a configured, not-yet-initialized instance.

Returns:

• PyRITInitializer — The configured initializer, ready for initialize_async.

Raises:

• KeyError — If the name is not registered.

• ValueError — If the configured parameters are invalid.

create_from_script_paths¶

create_from_script_paths(script_paths: Sequence[str | Path]) → list[PyRITInitializer]

Load initializer instances from external Python script files.

The registry owns turning script files into initializers: each .py file is imported and every PyRITInitializer subclass defined in that file (imported ones are ignored) is instantiated. Instances are returned in load order, ready for the caller to validate and initialize; they are not added to the class catalog.

Returns:

• list[PyRITInitializer] — list[PyRITInitializer]: Instantiated initializers, in load order.

Raises:

• FileNotFoundError — If a script path does not exist.

• ValueError — If a path is not a .py file or defines no initializer.

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.

InstanceRegistry¶

Bases: Protocol[T]

Typed instance-container capability a registry exposes as .instances.

Holds named, pre-configured instances that callers register and retrieve by name, list, tag, and filter. Stored items must implement Identifiable. DefaultInstanceRegistry is the concrete default implementation; expressing the surface as a protocol lets callers depend on the capability rather than a concrete class.

Methods:

add_tags¶

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

Add tags to an existing entry.

find_dependents_of_tag¶

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

Return entries whose identifier tree references a tagged entry’s eval_hash.

get¶

get(name: str) → T | None

Return the instance registered under name, or None.

get_all_instances¶

get_all_instances() → list[RegistryEntry[T]]

Return all entries sorted by name.

get_by_tag¶

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

Return entries carrying tag (optionally matching value), sorted by name.

get_entry¶

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

Return the full entry (including tags) for name, or None.

get_names¶

get_names() → list[str]

Return the sorted names of registered instances.

list_metadata¶

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

List per-instance identifier metadata, optionally filtered.

query_by_tags¶

query_by_tags(query: TagQuery) → list[RegistryEntry[T]]

Return entries whose tag keys satisfy the composable TagQuery, sorted by name.

register¶

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

Register a pre-configured instance, defaulting its name to the identifier’s unique_name.

ParamBagRegistry¶

Bases: Registry[ConfigurableT, MetadataT]

Registry whose components carry a parameter bag populated post-construction.

Extends the base Registry (catalog + create_instance from a flat arg dict) with the shared create → set-parameters lifecycle prefix used by the registries whose component type supports set_params_from_args (Scenario, PyRITInitializer). The component type parameter is bound to SupportsParamBag, so _create_and_configure is type-safe without a cast.

Subclasses layer the diverging post-configure step on top: ScenarioRegistry initializes, InitializerRegistry validates.

Registry¶

Bases: ABC, Generic[T, MetadataT]

Standalone base for PyRIT registries: a validated class catalog that builds instances.

Provides the common infrastructure every registry needs:

• Lazy discovery of classes (deferred until first access).

• A single add path (register_class) that validates a class before storing it.

• Metadata caching keyed by registry name.

• Construction from a type name plus arguments (create_instance), routed through resolve_constructor_args so string values are coerced and registry-reference parameters are resolved by name from the owning domain.

• Singleton support via get_registry_singleton().

Subclasses provide the domain specifics:

• _base_type() — the base class to discover (and the type the optional instances container is constrained to), imported lazily.

• _discovery_package() — the package whose __all__ is scanned for concrete subclasses of _base_type().

• _metadata_class() — return the concrete metadata dataclass the base builds.

The default _discover() scans _discovery_package().__all__ for concrete _base_type() subclasses and registers each by class name. A registry whose discovery is genuinely different (e.g. a directory or filesystem scan) overrides _discover() instead of supplying the two hooks.

Constructor Parameters:

Methods:

create_instance¶

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

Build a configured instance by class name.

Looks up the catalogued class, resolves the given arguments via resolve_constructor_args (coerce simple strings, resolve registry references by name, raise on unknown params), and constructs the object.

Returns:

• T — The constructed instance.

Raises:

• KeyError — If the name is not registered.

• ValueError — If an argument is not a valid constructor parameter, a registry reference cannot be resolved, or a value cannot be coerced.

get_all_registered_class_metadata¶

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

List metadata for all registered classes, optionally filtered.

Supports filtering on any metadata property:

• Simple types (str, int, bool): exact match.

• Sequence types (list, tuple): checks if the filter value is contained.

Returns:

• list[MetadataT] — list[MetadataT]: Metadata describing each registered class (filtered).

get_class¶

get_class(name: str) → type[T]

Get a registered class by name.

Returns:

• type[T] — type[T]: The registered class (the class itself, not an instance).

Raises:

• KeyError — If the name is not registered.

get_class_metadata¶

get_class_metadata() → MetadataT

Build metadata for any class (registered or not).

Derives the catalog name via _get_registry_name and builds a fresh descriptor. Useful for describing a class without registering it.

Returns:

• MetadataT — The metadata descriptor for the class.

get_class_names¶

get_class_names() → list[str]

Get a sorted list of all registered catalog names.

Returns:

• list[str] — list[str]: Sorted catalog names.

get_registered_class_metadata¶

get_registered_class_metadata(name: str) → MetadataT | None

Get the metadata for a single registered class by name.

Returns:

• MetadataT | None — MetadataT | None: The metadata, or None if the name is not registered.

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.

register_class¶

register_class(name: str | None = None) → None

Add a class to the catalog after validating it.

Registers a class type (not an instance) so the registry knows it exists and can later build instances of it via create_instance. The class is validated by _validate_class before being stored, so the catalog never holds a class whose build contract cannot be resolved.

Raises:

• ValueError — If the class fails validation.

reset_registry_singleton¶

reset_registry_singleton() → None

Reset the singleton instance.

Useful for testing or when re-discovery is needed.

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.

RegistryMetadata¶

Minimal base for class-level registry metadata.

Provides the common fields every registry metadata type needs for display, lookup, and filtering in class registries.

Methods:

description_from_docstring¶

description_from_docstring(fallback: str = '') → str

Extract a normalized description from a class docstring.

Collapses all whitespace into single spaces. Returns fallback if no docstring is present or the docstring is empty after cleaning.

Returns:

• str — The cleaned docstring or the fallback value.

summary_from_docstring¶

summary_from_docstring() → str

Extract a short summary from the first paragraph of a class docstring.

Uses the class’s own docstring only (never an inherited one), normalizes indentation, and collapses the first paragraph’s whitespace onto one line. Empty when the class has no docstring. This is the catalog-display counterpart to description_from_docstring (which collapses the whole docstring); buildable registries populate class_description from this first-paragraph form.

Returns:

• str — The first-paragraph summary, or “” when there is no docstring.

ScenarioMetadata¶

Bases: RegistryMetadata

Metadata describing a registered Scenario class.

Use get_class() to get the actual class.

ScenarioRegistry¶

Bases: ParamBagRegistry['Scenario', ScenarioMetadata]

Registry for discovering and managing available scenario classes.

Discovers every concrete Scenario subclass under pyrit.scenario.scenarios via the unified Registry base (recursive subclass enumeration). Unlike the component registries, scenarios are keyed by their dotted module path (e.g. "garak.encoding", "foundry.red_team_agent") rather than class name, so only _get_registry_name and _build_metadata are customized.

Methods:

create_and_initialize_async¶

create_and_initialize_async(name: str, scenario_params: dict[str, Any] | None = None, scenario_result_id: str | None = None, initialize_kwargs: Any = {}) → Scenario

Build, parameterize, and initialize a scenario in one call.

This is the canonical entry point for producing a run-ready Scenario: the registry — not the caller — owns the full lifecycle.

1. create the scenario via create_instance (seeding scenario_result_id when resuming an existing run),

2. set parameters — the scenario-specific declared parameters (scenario_params) and the common run-resolved parameters (initialize_kwargs — objective_target, scenario_techniques, dataset_config, max_concurrency, max_retries, memory_labels, include_baseline) are merged into a single Scenario.set_params_from_args call, so every value flows through the one coerce/validate/inject-defaults path,

3. initialize — Scenario.initialize_async() is called with no arguments; it reads every input from the now-populated bag.

Prefer this over manually chaining create_instance + set_params_from_args + initialize_async.

Returns:

• Scenario — The fully initialized scenario, ready for run_async.

ScorerMetadata¶

Bases: RegistryMetadata

Metadata describing a registered Scorer class.

Carries the derived parameters build contract (the same list the resolver consumes to build an instance). Whether the scorer is LLM-based is projected from that contract rather than stored, so the entry can never drift from the class.

Use ScorerRegistry.get_class() to get the actual class or create_instance() to build a configured instance.

ScorerRegistry¶

Bases: Registry['Scorer', ScorerMetadata]

Registry that discovers, builds, and holds Scorer instances.

Discovers all concrete Scorer subclasses exported from pyrit.score (keyed by their exact class name, e.g. "SelfAskRefusalScorer") for the buildable catalog. Pre-configured instances registered via initializers or the backend are held under the instances property.

Building a scorer resolves its arguments through the shared resolver, so LLM scorers can be constructed by passing a chat_target that names a target in the TargetRegistry, and composite scorers by passing a list of scorers that name scorers already held under instances.

Constructor Parameters:

SupportsInstances¶

Bases: Protocol[T]

Structural marker for a registry that holds instances.

Lets callers and type-checkers express “a registry that holds instances” without naming a concrete class, so a registry’s capabilities are legible from its type.

.. note:: Introduced with the Phase 1 foundation but not yet consumed in the codebase. Its first real callers arrive when the target and scorer registries migrate onto .instances (Phase 4) and functions begin accepting “any registry that holds instances” structurally. It ships now so the typed capability is part of the foundation rather than a later additive change.

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.

TargetMetadata¶

Bases: RegistryMetadata

Metadata describing a registered PromptTarget class.

Carries the derived parameters build contract (the same list the resolver consumes to build an instance) and, via class_attributes on the base, the target’s declarative auth facts. supported_auth_modes is projected from those rather than stored, so the entry can never drift from the class. Use TargetRegistry.get_class() to get the actual class or create_instance() to build a configured instance.

TargetRegistry¶

Bases: Registry['PromptTarget', TargetMetadata]

Registry that discovers, builds, and holds PromptTarget instances.

Discovers all concrete PromptTarget subclasses exported from pyrit.prompt_target (keyed by their exact class name, e.g. "OpenAIChatTarget") for the buildable catalog. Pre-configured instances registered via initializers or the backend are held under the instances property.

Building a multi-target resolves its arguments through the shared resolver, so a RoundRobinTarget can be constructed by passing a list of targets that name targets already held under instances.

Constructor Parameters: