pyrit.prompt_normalizer

Prompt normalization components for standardizing and converting prompts.

This module provides tools for normalizing prompts before sending them to targets, including converter configurations and request handling.

Functions¶

send_json_with_retry_async¶

send_json_with_retry_async(normalizer: PromptNormalizer, target: PromptTarget, message: Message, conversation_id: str, parse: Callable[[Message], T]) → T

Send a message expecting a JSON response, retrying each attempt on a clean conversation history.

JSON retries are only useful if each attempt is independent. This helper records a baseline sequence for the conversation and, on every attempt, rolls memory back to that baseline before resending: the first attempt deletes nothing; each retry deletes the previous failed turn (and records a ConversationRetry marker) so the target rebuilds history from memory and sees a clean conversation identical to the first attempt, instead of replaying its own malformed reply.

The retry loop keeps the @pyrit_json_retry (tenacity) decorator so retry logging and the RetryCollector attribution driven by after=log_exception are preserved.

Returns:

• T — The parsed result.

Raises:

• InvalidJsonException — When parsing still fails after the retry budget is exhausted.

• ValueError — If the target returns no response.

ConverterConfiguration¶

Represents the configuration for a converter.

The list of converters are applied to a response, which can have multiple response pieces. indexes_to_apply are which pieces to apply to. By default, all indexes are applied. prompt_data_types_to_apply are the types of the responses to apply the converters.

Methods:

from_converters¶

from_converters(converters: list[Converter]) → list[ConverterConfiguration]

Convert a list of converters into a list of ConverterConfiguration objects. Each converter gets its own configuration with default settings.

Returns:

• list[ConverterConfiguration] — list[ConverterConfiguration]: List of configurations, one per converter

NormalizerRequest¶

Represents a single request sent to normalizer.

Constructor Parameters:

PromptNormalizer¶

Handles normalization and processing of prompts before they are sent to targets.

Methods:

add_prepended_conversation_to_memory_async¶

add_prepended_conversation_to_memory_async(conversation_id: str, should_convert: bool = True, converter_configurations: list[ConverterConfiguration] | None = None, prepended_conversation: list[Message] | None = None, target_identifier: ComponentIdentifier | None = None) → list[Message] | None

Process the prepended conversation by converting it if needed and adding it to memory.

Returns:

• list[Message] | None — list[Message] | None: The processed prepended conversation

convert_audio_async¶

convert_audio_async(raw_pcm: bytes, converter_configurations: list[ConverterConfiguration], sample_rate_hz: int, num_channels: int, sample_width_bytes: int) → bytes

Apply converters to raw PCM audio and return the converted PCM.

Wraps the input PCM in a temporary WAV file, builds a single-piece audio_path Message, runs convert_values, then reads the converted file back as raw PCM. The caller’s PCM format is preserved end-to-end; converters that change the format trigger a ValueError on read-back.

Returns:

• bytes — The converted raw PCM, matching the input format.

Raises:

• ValueError — If the converted audio has a different sample rate, channel count, or sample width than the input.

convert_values_async¶

convert_values_async(converter_configurations: list[ConverterConfiguration], message: Message) → None

Apply converter configurations to message pieces.

Raises:

• Exception — Any exception from converters propagates with execution context for error tracing.

hash_and_persist_message_async¶

hash_and_persist_message_async(message: Message) → None

Hash and persist a Message to memory.

Use when a target assembles a Message outside the send_prompt_async flow (e.g. streaming sessions that yield per-turn Messages directly). Register the conversation once via MemoryInterface.add_conversation_to_memory before persisting its messages.

send_prompt_async¶

send_prompt_async(message: Message, target: PromptTarget, conversation_id: str | None = None, request_converter_configurations: list[ConverterConfiguration] | None = None, response_converter_configurations: list[ConverterConfiguration] | None = None) → Message

Send a single request to a target.

Returns:

• Message — The response received from the target.

Raises:

• Exception — If an error occurs during the request processing.

• ValueError — If the message pieces are not part of the same sequence.

send_prompt_batch_to_target_async¶

send_prompt_batch_to_target_async(requests: list[NormalizerRequest], target: PromptTarget, batch_size: int = 10) → list[Message]

Send a batch of prompts to the target asynchronously.

Returns:

• list[Message] — list[Message]: A list of Message objects representing the responses received for each prompt.