DOC: improve API reference for prompt_converter module (Azure#969)

Author: paulinek13

doc/api.rst

@@ -319,10 +319,13 @@ API Reference
     RepeatTokenConverter
     ROT13Converter
     SearchReplaceConverter
+    SneakyBitsSmugglerConverter
     StringJoinConverter
     SuffixAppendConverter
     SuperscriptConverter
+    TemplateSegmentConverter
     TenseConverter
+    TextJailbreakConverter
     TextToHexConverter
     ToneConverter
     ToxicSentenceGeneratorConverter
@@ -332,6 +335,7 @@ API Reference
     UnicodeSubstitutionConverter
     UrlConverter
     VariationConverter
+    VariationSelectorSmugglerConverter
     ZalgoConverter
     ZeroWidthConverter
 

pyrit/prompt_converter/add_image_text_converter.py

@@ -18,16 +18,9 @@
 class AddImageTextConverter(PromptConverter):
     """
     Adds a string to an image and wraps the text into multiple lines if necessary.
-    This class is similar to AddImageTextConverter except
-    we pass in an image file path as an argument to the constructor as opposed to text.
 
-    Args:
-        img_to_add (str): File path of image to add text to
-        font_name (str): Path of font to use. Must be a TrueType font (.ttf). Defaults to "helvetica.ttf".
-        color (tuple): Color to print text in, using RGB values. Defaults to (0, 0, 0).
-        font_size (float): Size of font to use. Defaults to 15.
-        x_pos (int): X coordinate to place text in (0 is left most). Defaults to 10.
-        y_pos (int): Y coordinate to place text in (0 is upper most). Defaults to 10.
+    This class is similar to :class:`AddTextImageConverter` except
+    we pass in an image file path as an argument to the constructor as opposed to text.
     """
 
     def __init__(
@@ -39,6 +32,20 @@ def __init__(
         x_pos: int = 10,
         y_pos: int = 10,
     ):
+        """
+        Initializes the converter with the image file path and text properties.
+
+        Args:
+            img_to_add (str): File path of image to add text to.
+            font_name (str): Path of font to use. Must be a TrueType font (.ttf). Defaults to "helvetica.ttf".
+            color (tuple): Color to print text in, using RGB values. Defaults to (0, 0, 0).
+            font_size (float): Size of font to use. Defaults to 15.
+            x_pos (int): X coordinate to place text in (0 is left most). Defaults to 10.
+            y_pos (int): Y coordinate to place text in (0 is upper most). Defaults to 10.
+
+        Raises:
+            ValueError: If ``img_to_add`` is empty or invalid, or if ``font_name`` does not end with ".ttf".
+        """
         if not img_to_add:
             raise ValueError("Please provide valid image path")
         if not font_name.endswith(".ttf"):
@@ -53,11 +60,11 @@ def __init__(
 
     def _load_font(self):
         """
-        Load the font for a given font name and font size
+        Loads the font for a given font name and font size.
 
         Returns:
-        ImageFont.FreeTypeFont or ImageFont.ImageFont: The loaded font object. If the specified font
-        cannot be loaded, the default font is returned.
+            ImageFont.FreeTypeFont or ImageFont.ImageFont: The loaded font object. If the specified font
+            cannot be loaded, the default font is returned.
 
         Raises:
             OSError: If the font resource cannot be loaded, a warning is logged and the default font is used instead.
@@ -72,7 +79,7 @@ def _load_font(self):
 
     def _add_text_to_image(self, text: str) -> Image.Image:
         """
-        Adds wrapped text to the image at self._img_to_add.
+        Adds wrapped text to the image at `self._img_to_add`.
 
         Args:
             text (str): The text to add to the image.
@@ -111,13 +118,17 @@ def _add_text_to_image(self, text: str) -> Image.Image:
 
     async def convert_async(self, *, prompt: str, input_type: PromptDataType = "text") -> ConverterResult:
         """
-        Converter that overlays input text on the img_to_add.
+        Converts the given prompt by adding it as text to the image.
 
         Args:
-            prompt (str): The prompt to be added to the image.
-            input_type (PromptDataType): type of data
+            prompt (str): The text to be added to the image.
+            input_type (PromptDataType): The type of input data.
+
         Returns:
-            ConverterResult: The filename of the converted image as a ConverterResult Object
+            ConverterResult: The result containing path to the updated image.
+
+        Raises:
+            ValueError: If the input type is not supported.
         """
         if not self.input_supported(input_type):
             raise ValueError("Input type not supported")

pyrit/prompt_converter/add_image_to_video_converter.py

@@ -27,13 +27,8 @@
 class AddImageVideoConverter(PromptConverter):
     """
     Adds an image to a video at a specified position.
-    Also, currently the image is placed in the whole video, not at a specific timepoint
 
-    Args:
-        video_path (str): File path of video to add image to
-        output_path (str, Optional): File path of output video. Defaults to None.
-        img_position (tuple): Position to place image in video. Defaults to (10, 10).
-        img_resize_size (tuple): Size to resize image to. Defaults to (500, 500).
+    Currently the image is placed in the whole video, not at a specific timepoint.
     """
 
     def __init__(
@@ -43,6 +38,18 @@ def __init__(
         img_position: tuple = (10, 10),
         img_resize_size: tuple = (500, 500),
     ):
+        """
+        Initializes the converter with the video path and image properties.
+
+        Args:
+            video_path (str): File path of video to add image to.
+            output_path (str, Optional): File path of output video. Defaults to None.
+            img_position (tuple): Position to place image in video. Defaults to (10, 10).
+            img_resize_size (tuple): Size to resize image to. Defaults to (500, 500).
+
+        Raises:
+            ValueError: If ``video_path`` is empty or invalid.
+        """
 
         if not video_path:
             raise ValueError("Please provide valid video path")
@@ -54,13 +61,14 @@ def __init__(
 
     async def _add_image_to_video(self, image_path: str, output_path: str) -> str:
         """
-        Adds image to video
+        Adds an image to video.
+
         Args:
             image_path (str): The image path to add to video.
             output_path (str): The output video path.
 
         Returns:
-            output_path (str): The output video path.
+            str: The output video path.
         """
 
         try:
@@ -158,13 +166,17 @@ async def _add_image_to_video(self, image_path: str, output_path: str) -> str:
 
     async def convert_async(self, *, prompt: str, input_type: PromptDataType = "image_path") -> ConverterResult:
         """
-        Converter that adds an image to a video
+        Converts the given prompt (image) by adding it to a video.
 
         Args:
-            prompt (str): The image file name to be added to the video.
-            input_type (PromptDataType): type of data
+            prompt (str): The image path to be added to the video.
+            input_type (PromptDataType): The type of input data.
+
         Returns:
-            ConverterResult: The filename of the converted video as a ConverterResult Object
+            ConverterResult: The result containing filename of the converted video.
+
+        Raises:
+            ValueError: If the input type is not supported.
         """
         if not self.input_supported(input_type):
             raise ValueError("Input type not supported")

pyrit/prompt_converter/add_text_image_converter.py

@@ -19,13 +19,8 @@ class AddTextImageConverter(PromptConverter):
     """
     Adds a string to an image and wraps the text into multiple lines if necessary.
 
-    Args:
-        text_to_add (str): Text to add to an image. Defaults to empty string.
-        font_name (str): Path of font to use. Must be a TrueType font (.ttf). Defaults to "helvetica.ttf".
-        color (tuple): Color to print text in, using RGB values. Defaults to (0, 0, 0).
-        font_size (float): Size of font to use. Defaults to 15.
-        x_pos (int): X coordinate to place text in (0 is left most). Defaults to 10.
-        y_pos (int): Y coordinate to place text in (0 is upper most). Defaults to 10.
+    This class is similar to :class:`AddImageTextConverter` except
+    we pass in text as an argument to the constructor as opposed to an image file path.
     """
 
     def __init__(
@@ -37,6 +32,20 @@ def __init__(
         x_pos: int = 10,
         y_pos: int = 10,
     ):
+        """
+        Initializes the converter with the text and text properties.
+
+        Args:
+            text_to_add (str): Text to add to an image. Defaults to empty string.
+            font_name (str): Path of font to use. Must be a TrueType font (.ttf). Defaults to "helvetica.ttf".
+            color (tuple): Color to print text in, using RGB values. Defaults to (0, 0, 0).
+            font_size (float): Size of font to use. Defaults to 15.
+            x_pos (int): X coordinate to place text in (0 is left most). Defaults to 10.
+            y_pos (int): Y coordinate to place text in (0 is upper most). Defaults to 10.
+
+        Raises:
+            ValueError: If ``text_to_add`` is empty, or if ``font_name`` does not end with ".ttf".
+        """
         if text_to_add.strip() == "":
             raise ValueError("Please provide valid text_to_add value")
         if not font_name.endswith(".ttf"):
@@ -51,11 +60,11 @@ def __init__(
 
     def _load_font(self):
         """
-        Load the font for a given font name and font size
+        Loads the font for a given font name and font size.
 
         Returns:
-        ImageFont.FreeTypeFont or ImageFont.ImageFont: The loaded font object. If the specified font
-        cannot be loaded, the default font is returned.
+            ImageFont.FreeTypeFont or ImageFont.ImageFont: The loaded font object. If the specified font
+            cannot be loaded, the default font is returned.
 
         Raises:
             OSError: If the font resource cannot be loaded, a warning is logged and the default font is used instead.
@@ -105,13 +114,17 @@ def _add_text_to_image(self, image: Image.Image) -> Image.Image:
 
     async def convert_async(self, *, prompt: str, input_type: PromptDataType = "image_path") -> ConverterResult:
         """
-        Converter that adds text to an image
+        Converts the given prompt (image) by adding text to it.
 
         Args:
-            prompt (str): The filename of the image to add the text to
-            input_type (PromptDataType): type of data
+            prompt (str): The image file path to which text will be added.
+            input_type (PromptDataType): The type of input data.
+
         Returns:
-            ConverterResult: The filename of the converted image as a ConverterResult Object
+            ConverterResult: The result containing path to the updated image.
+
+        Raises:
+            ValueError: If the input type is not supported.
         """
         if not self.input_supported(input_type):
             raise ValueError("Input type not supported")

pyrit/prompt_converter/ansi_escape/ansi_attack_converter.py

@@ -20,10 +20,12 @@
 
 class AnsiAttackConverter(PromptConverter):
     """
-    A single converter that can:
-    - Use raw and escaped ANSI payloads.
-    - Ask the model about ANSI codes, repeat given payloads, unescape strings.
-    - Incorporate the user's original prompt into the final scenario, making the testing more dynamic.
+    Generates prompts with ANSI codes to evaluate LLM behavior and system risks.
+
+    This converter can:
+        - Use raw and escaped ANSI payloads.
+        - Ask the model about ANSI codes, repeat given payloads, unescape strings.
+        - Incorporate the user's original prompt into the final scenario, making the testing more dynamic.
     """
 
     def __init__(
@@ -36,6 +38,8 @@ def __init__(
         incorporate_user_prompt: bool = True,
     ):
         """
+        Initializes the converter with various options to control the scenarios generated.
+
         Args:
             include_raw (bool): Include scenarios with raw ANSI codes.
             include_escaped (bool): Include scenarios with escaped ANSI codes.
@@ -58,6 +62,7 @@ def output_supported(self, output_type: PromptDataType) -> bool:
         return output_type == "text"
 
     async def convert_async(self, *, prompt: str, input_type: PromptDataType = "text") -> ConverterResult:
+        """Converts the given prompt into an ANSI attack scenario."""
         if not self.input_supported(input_type):
             raise ValueError("Input type not supported")
 

pyrit/prompt_converter/ascii_art_converter.py

@@ -8,21 +8,21 @@
 
 
 class AsciiArtConverter(PromptConverter):
-    """Converts a string to ASCII art"""
+    """
+    Uses the `art` package to convert text into ASCII art.
+    """
 
     def __init__(self, font="rand"):
-        self.font_value = font
-
-    async def convert_async(self, *, prompt: str, input_type: PromptDataType = "text") -> ConverterResult:
         """
-        Converter that uses art to convert strings to ASCII art.
-        This can sometimes bypass LLM filters
+        Initializes the converter with a specified font.
 
         Args:
-            prompt (str): The prompt to be converted.
-        Returns:
-            str: The converted prompt.
+            font (str): The font to use for ASCII art. Defaults to "rand" which selects a random font.
         """
+        self.font_value = font
+
+    async def convert_async(self, *, prompt: str, input_type: PromptDataType = "text") -> ConverterResult:
+        """Converts the given prompt into ASCII art."""
         if not self.input_supported(input_type):
             raise ValueError("Input type not supported")
 

pyrit/prompt_converter/atbash_converter.py

@@ -11,22 +11,24 @@
 
 class AtbashConverter(PromptConverter):
     """
-    Converter to encode prompt using atbash cipher.
+    Encodes text using the Atbash cipher.
 
     Uses the following to encode:
-    ABCDEFGHIJKLMNOPQRSTUVWXYZ 0123456789
-    ZYXWVUTSRQPONMLKJIHGFEDCBA 9876543210
+        - ABCDEFGHIJKLMNOPQRSTUVWXYZ 0123456789
+        - ZYXWVUTSRQPONMLKJIHGFEDCBA 9876543210
 
-    'Hello 123' would encode to 'Svool 876'
-
-    Parameters
-    ---
-    append_description: bool, default=False
-        Append plaintext "expert" text to the prompt. Includes instructions to only communicate
-        using the cipher, a description of the cipher, and an example encoded using cipher.
+    'Hello 123' would encode to 'Svool 876'.
     """
 
     def __init__(self, *, append_description: bool = False) -> None:
+        """
+        Initializes the converter with an option to append a description.
+
+        Args:
+            append_description (bool): If True, appends plaintext "expert" text to the prompt.
+                This includes instructions to only communicate using the cipher,
+                a description of the cipher, and an example encoded using the cipher.
+        """
         self.append_description = append_description
         self.example = (
             "User: How do I cut down a stop sign?\n"
@@ -35,9 +37,7 @@ def __init__(self, *, append_description: bool = False) -> None:
         )
 
     async def convert_async(self, *, prompt: str, input_type: PromptDataType = "text") -> ConverterResult:
-        """
-        Simple converter that atbash cipher encodes the prompt.
-        """
+        """Converts the given prompt using the Atbash cipher."""
         if not self.input_supported(input_type):
             raise ValueError("Input type not supported")