Implementation:Deepset ai Haystack PromptBuilder

Overview

PromptBuilder is a Haystack component that renders prompt templates using Jinja2 syntax, filling in variables so the resulting prompt string can be sent to a Generator. It supports both static templates defined at initialization and dynamic template overrides at runtime, enabling flexible prompt engineering within pipelines.

Source Location

• File: haystack/components/builders/prompt_builder.py (Lines 17-269)
• Class: PromptBuilder
• Component decorator: @component

Import

from haystack.components.builders import PromptBuilder

Dependencies

• jinja2: Provides SandboxedEnvironment for secure template rendering.
• haystack.utils: Provides Jinja2TimeExtension for optional time-related template functions.

Constructor

def __init__(
    self,
    template: str,
    required_variables: list[str] | Literal["*"] | None = None,
    variables: list[str] | None = None,
)

Parameters

• template (str): A Jinja2 template string used to render the prompt. Variables in the template become component inputs. Example: "Summarize this document: {{ documents[0].content }}\nSummary:"
• required_variables (list[str] | Literal["*"] | None): Variables that must be provided at runtime. If set to "*", all template variables are required. If None (default), all variables are optional and default to empty strings when not provided.
• variables (list[str] | None): Explicit list of input variables to use instead of those inferred from the template. Useful for prompt engineering when testing with more variables than the default template contains.

Initialization Behavior

• Creates a SandboxedEnvironment with optional Jinja2TimeExtension.
• Compiles the template string into a Jinja2 template object.
• Extracts template variables automatically via _extract_template_variables_and_assignments unless explicitly provided via the variables parameter.
• Registers each variable as a component input using component.set_input_type, with required variables having no default and optional variables defaulting to "".
• Logs a warning if variables exist but required_variables is not set, to alert about potential issues in multi-branch pipelines.

Run Method

@component.output_types(prompt=str)
def run(
    self,
    template: str | None = None,
    template_variables: dict[str, Any] | None = None,
    **kwargs,
) -> dict:  # Returns {"prompt": str}

Parameters

• template (str | None): An optional template string to override the default template for this invocation.
• template_variables (dict | None): An optional dictionary of variables that overwrite pipeline-provided kwargs. This is useful for overriding values that come through pipeline connections.
• **kwargs: Pipeline variables used for rendering. These are the template variable values passed through pipeline connections.

Returns

• {"prompt": str}: A dictionary containing the rendered prompt string.

Behavior

1. Merges kwargs with template_variables (template_variables take precedence).
2. Validates that all required variables are present; raises ValueError if any are missing.
3. If a runtime template is provided, compiles it; otherwise uses the default template.
4. Renders the template with the combined variables and returns the result.

Serialization

def to_dict(self) -> dict[str, Any]

Returns a dictionary representation of the component, including the template string, variables, and required_variables, using default_to_dict.

Usage Examples

Standalone Usage

from haystack.components.builders import PromptBuilder

template = "Translate the following context to {{ target_language }}. Context: {{ snippet }}; Translation:"
builder = PromptBuilder(template=template)
result = builder.run(target_language="spanish", snippet="I can't speak spanish.")
# result["prompt"] == "Translate the following context to spanish. Context: I can't speak spanish.; Translation:"

In a RAG Pipeline

from haystack import Pipeline, Document
from haystack.utils import Secret
from haystack.components.generators import OpenAIGenerator
from haystack.components.builders import PromptBuilder

documents = [Document(content="Joe lives in Berlin"), Document(content="Joe is a software engineer")]
prompt_template = """
Given these documents, answer the question.
Documents:
{% for doc in documents %}
    {{ doc.content }}
{% endfor %}

Question: {{ query }}
Answer:
"""

p = Pipeline()
p.add_component(instance=PromptBuilder(template=prompt_template), name="prompt_builder")
p.add_component(instance=OpenAIGenerator(api_key=Secret.from_env_var("OPENAI_API_KEY")), name="llm")
p.connect("prompt_builder", "llm")

result = p.run({"prompt_builder": {"documents": documents, "query": "Where does Joe live?"}})

Runtime Template Override

new_template = """
You are a helpful assistant.
Given these documents, answer the question.
Documents:
{% for doc in documents %}
    Document {{ loop.index }}:
    Document name: {{ doc.meta['name'] }}
    {{ doc.content }}
{% endfor %}

Question: {{ query }}
Answer:
"""
result = p.run({
    "prompt_builder": {
        "documents": documents,
        "query": "Where does Joe live?",
        "template": new_template,
    },
})

Overwriting Variables at Runtime

language_template = """
Given these documents, answer the question.
Documents:
{% for doc in documents %}
    {{ doc.content }}
{% endfor %}

Question: {{ query }}
Please provide your answer in {{ answer_language | default('English') }}
Answer:
"""
result = p.run({
    "prompt_builder": {
        "documents": documents,
        "query": "Where does Joe live?",
        "template": language_template,
        "template_variables": {"answer_language": "German"},
    },
})

Related Pages

• Principle:Deepset_ai_Haystack_Prompt_Templating