pyrit.prompt_converter.WordDocConverter

pyrit.prompt_converter.WordDocConverter#

class WordDocConverter(*, prompt_template: SeedPrompt | None = None, existing_docx: Path | None = None, placeholder: str = '{{INJECTION_PLACEHOLDER}}')[source]#

Bases: PromptConverter

Convert a text prompt into a Word (.docx) document.

This converter supports two main modes:

  1. New document generation If no existing document is provided, the converter creates a simple .docx containing the rendered prompt content in a single paragraph.

  2. Placeholder-based injection into an existing document If an existing_docx is provided, the converter searches for a literal placeholder string (for example {{INJECTION_PLACEHOLDER}}) in the document’s paragraphs. When the placeholder is found fully inside a single run, it is replaced with the rendered prompt content while preserving the rest of the paragraph and its formatting.

    Important

    Placeholders must be fully contained within a single run. If a placeholder spans multiple runs (for example due to mixed formatting), this converter will not replace it. This limitation is intentional to avoid collapsing mixed formatting or rewriting complex run structures.

Security note:

This converter does not render Jinja2 templates from arbitrary .docx content. Templating is handled via SeedPrompt (if provided), and only the already-rendered text is injected into the document. This avoids executing untrusted Jinja2 templates from document bodies.

__init__(*, prompt_template: SeedPrompt | None = None, existing_docx: Path | None = None, placeholder: str = '{{INJECTION_PLACEHOLDER}}') → None[source]#

Initialize the Word document converter.

Parameters:

  • prompt_template – Optional SeedPrompt template used to render the final content before injection. If provided, prompt passed to convert_async must be a string whose contents can be interpreted as the template parameters (for example, a JSON-encoded or other parseable mapping of keys to values).

  • existing_docx – Optional path to an existing .docx file. When provided, the converter will search for placeholder inside the document paragraphs and replace it with the rendered content. If not provided, a new document is generated instead.

  • placeholder – Literal placeholder text to search for in the existing document. This value must be fully contained within a single run for the replacement to succeed.

Raises:

Methods

__init__(*[, prompt_template, ...])

Initialize the Word document converter.

convert_async(*, prompt[, input_type])

Convert the given prompt into a Word document (.docx).

convert_tokens_async(*, prompt[, ...])

Convert substrings within a prompt that are enclosed by specified start and end tokens.

get_identifier()

Get the component's identifier, building it lazily on first access.

input_supported(input_type)

Check if the input type is supported by the converter.

output_supported(output_type)

Check if the output type is supported by the converter.

Attributes

SUPPORTED_INPUT_TYPES

Tuple of input modalities supported by this converter.

SUPPORTED_OUTPUT_TYPES

Tuple of output modalities supported by this converter.

supported_input_types

Returns a list of supported input types for the converter.

supported_output_types

Returns a list of supported output types for the converter.
SUPPORTED_INPUT_TYPES: tuple[Literal['text', 'image_path', 'audio_path', 'video_path', 'binary_path', 'url', 'reasoning', 'error', 'function_call', 'tool_call', 'function_call_output'], ...] = ('text',)#

Tuple of input modalities supported by this converter. Subclasses must override this.

SUPPORTED_OUTPUT_TYPES: tuple[Literal['text', 'image_path', 'audio_path', 'video_path', 'binary_path', 'url', 'reasoning', 'error', 'function_call', 'tool_call', 'function_call_output'], ...] = ('binary_path',)#

Tuple of output modalities supported by this converter. Subclasses must override this.

async convert_async(*, prompt: str, input_type: Literal['text', 'image_path', 'audio_path', 'video_path', 'binary_path', 'url', 'reasoning', 'error', 'function_call', 'tool_call', 'function_call_output'] = 'text') → ConverterResult[source]#

Convert the given prompt into a Word document (.docx).

If prompt_template is provided, the prompt is first used to render the template via SeedPrompt.render_template_value. Otherwise, the raw prompt string is used as the content.

  • When existing_docx is set, this content is injected into the document by replacing the configured placeholder string.

  • When no existing_docx is provided, a new document with a single paragraph containing the content is created.

Parameters:

  • prompt – The prompt or dynamic data used to generate the content.

  • input_type – The type of input data. Must be "text".

Returns:

Contains the path to the generated .docx file in output_text and output_type="binary_path".

Return type:

ConverterResult

Raises:

ValueError – If the input type is not supported.

Contents