PromptBuilder

Render a prompt filling in any variables and send it to a Generator.

Basic Information

• Type: components.builders.prompt_builder.PromptBuilder
• Components it can connect with:
  • Rankers: PromptBuilder can receive documents to add to the prompt from a Ranker.
  • Generators: PromptBuilder sends the rendered prompt to a Generator.
  • Retrievers: PromptBuilder can receive documents to add to the prompt from a Retriever.

Inputs

Parameter	Type	Default	Description
template	Optional[str]	None	An optional string template to overwrite PromptBuilder's default template.
template_variables	Optional[Dict[str, Any]]	None	An optional dictionary of template variables to overwrite the pipeline variables.
kwargs	Any		Pipeline variables used for rendering the prompt.

Outputs

Parameter	Type	Default	Description
prompt	str		The updated prompt text after rendering the prompt template.

Overview

PromptBuilder renders prompt templates by filling in variables and sends the rendered prompt to a Generator. It uses Jinja2 template syntax to create dynamic prompts that can include documents, queries, and other variables.

You can use PromptBuilder to:

• Create prompts that include retrieved documents and user queries.
• Customize prompts with conditional logic using Jinja2 syntax.
• Test different prompt templates in Prompt Explorer.
• Override template variables at runtime using the template_variables parameter

PromptBuilder takes a template string with Jinja2 syntax and replaces variables with actual values it receives from the pipeline. Variables in the template become inputs for PromptBuilder and are optional by default. If a variable isn't provided, it's replaced with an empty string in the rendered prompt.

You can use the required_variables parameter to define the variables that are required to render the prompt. If a required variable is missing, the component raises and error and stops. You can pass a list of required variable names or use * to mark all variables in the template as required.

PromptBuilder works with Generators that accept string prompts, such as OpenAIGenerator, AnthropicGenerator, and AmazonBedrockGenerator. For chat-based interactions that require ChatMessage objects, use ChatPromptBuilder instead.

To learn more about prompting, see Writing prompts in Haystack Enterprise Platform.

Usage Example

Using the Component in a Pipeline

This is a RAG pipeline that uses PromptBuilder with OpenAIGenerator:

components:
  bm25_retriever:
    type: haystack_integrations.components.retrievers.opensearch.bm25_retriever.OpenSearchBM25Retriever
    init_parameters:
      document_store:
        type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
        init_parameters:
          hosts:
            - ${OPENSEARCH_HOST}
          http_auth:
            - ${OPENSEARCH_USER}
            - ${OPENSEARCH_PASSWORD}
          use_ssl: true
          verify_certs: false
      top_k: 20

  query_embedder:
    type: haystack.components.embedders.sentence_transformers_text_embedder.SentenceTransformersTextEmbedder
    init_parameters:
      model: intfloat/e5-base-v2

  embedding_retriever:
    type: haystack_integrations.components.retrievers.opensearch.embedding_retriever.OpenSearchEmbeddingRetriever
    init_parameters:
      document_store:
        type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
        init_parameters:
          hosts:
            - ${OPENSEARCH_HOST}
          http_auth:
            - ${OPENSEARCH_USER}
            - ${OPENSEARCH_PASSWORD}
          use_ssl: true
          verify_certs: false
      top_k: 20

  document_joiner:
    type: haystack.components.joiners.document_joiner.DocumentJoiner
    init_parameters:
      join_mode: concatenate

  ranker:
    type: haystack.components.rankers.transformers_similarity.TransformersSimilarityRanker
    init_parameters:
      model: intfloat/simlm-msmarco-reranker
      top_k: 8

  prompt_builder:
    type: haystack.components.builders.prompt_builder.PromptBuilder
    init_parameters:
      template: |-
        You are a technical expert.
        You answer questions truthfully based on provided documents.
        Ignore typing errors in the question.
        For each document check whether it is related to the question.
        Only use documents that are related to the question to answer it.
        Ignore documents that are not related to the question.
        If the answer exists in several documents, summarize them.
        Only answer based on the documents provided. Don't make things up.
        Just output the structured, informative and precise answer and nothing else.
        If the documents can't answer the question, say so.
        Always use references in the form [NUMBER OF DOCUMENT] when using information from a document, e.g. [3] for Document[3].
        Never name the documents, only enter a number in square brackets as a reference.
        The reference must only refer to the number that comes in square brackets after the document.
        Otherwise, do not use brackets in your answer and reference ONLY the number of the document without mentioning the word document.

        These are the documents:
        {% for document in documents %}
        Document[{{ loop.index }}]:
        {{ document.content }}
        {% endfor %}

        Question: {{ question }}
        Answer:

  llm:
    type: haystack.components.generators.openai.OpenAIGenerator
    init_parameters:
      api_key: {"type": "env_var", "env_vars": ["OPENAI_API_KEY"], "strict": False}
      model: "gpt-4o"
      generation_kwargs:
        max_tokens: 400
        temperature: 0.0
        seed: 0

  answer_builder:
    type: haystack.components.builders.answer_builder.AnswerBuilder
    init_parameters: {}

connections:
  - sender: bm25_retriever.documents
    receiver: document_joiner.documents
  - sender: query_embedder.embedding
    receiver: embedding_retriever.query_embedding
  - sender: embedding_retriever.documents
    receiver: document_joiner.documents
  - sender: document_joiner.documents
    receiver: ranker.documents
  - sender: ranker.documents
    receiver: prompt_builder.documents
  - sender: ranker.documents
    receiver: answer_builder.documents
  - sender: prompt_builder.prompt
    receiver: answer_builder.prompt
  - sender: prompt_builder.prompt
    receiver: llm.prompt
  - sender: llm.replies
    receiver: answer_builder.replies

max_runs_per_component: 100

inputs:
  query:
    - bm25_retriever.query
    - query_embedder.text
    - ranker.query
    - prompt_builder.question
    - answer_builder.query
  filters:
    - bm25_retriever.filters
    - embedding_retriever.filters

outputs:
  documents: ranker.documents
  answers: answer_builder.answers

metadata: {}

Parameters

Init Parameters

These are the parameters you can configure in Pipeline Builder:

Parameter	Type	Default	Description
template	str		A prompt template that uses Jinja2 syntax to add variables. For example: "Summarize this document: {{ documents[0].content }}\nSummary:" It's used to render the prompt. The variables in the default template are input for PromptBuilder and are all optional, unless explicitly specified. If an optional variable is not provided, it's replaced with an empty string in the rendered prompt.
required_variables	Optional[Union[List[str], Literal['*']]]	None	List variables that must be provided as input to PromptBuilder. If a variable listed as required is not provided, an exception is raised. If set to "*", all variables found in the prompt are required. Optional.
variables	Optional[List[str]]	None	List input variables to use in prompt templates instead of the ones inferred from the template parameter. For example, to use more variables during prompt engineering than the ones present in the default template, you can provide them here.

Run Method Parameters

These are the parameters you can configure for the component's run() method. This means you can pass these parameters at query time through the API, in Playground, or when running a job. For details, see Modify Pipeline Parameters at Query Time.

Parameter	Type	Default	Description
template	Optional[str]	None	An optional string template to overwrite PromptBuilder's default template. If None, the default template provided at initialization is used.
template_variables	Optional[Dict[str, Any]]	None	An optional dictionary of template variables to overwrite the pipeline variables.
kwargs	Any		Pipeline variables used for rendering the prompt.