PromptBuilder

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

Key Features

• Renders prompt templates using Jinja2 syntax, filling in variables from pipeline inputs.
• Variables in the template become required inputs by default.
• Works with components that accept a rendered prompt string. For chat models, prefer LLM, or pass the string into a Chat Generator messages input such as OpenAIChatGenerator.
• Supports required variable enforcement via the required_variables parameter.
• Supports runtime template overrides and variable injection via template_variables.

Configuration

1. Drag the PromptBuilder component onto the canvas from the Component Library.
2. Click on the component to open the configuration panel.
3. On the General tab:
   • Enter your prompt template using Jinja2 syntax. For example: "Answer this question: {{ query }}". Variables in the template become inputs for the component.
   • By default, all template variables are required. Set required_variables to a list to require only specific variables, or set it to null to make all variables optional.
4. Go to the Advanced tab to configure optional input variables for prompt engineering scenarios via variables.

Connections

PromptBuilder accepts template variables as dynamic inputs. The inputs depend on the variables in your template. Connect document or text outputs from retrievers or rankers to the corresponding variable inputs.

It outputs a rendered prompt string. For new pipelines, prefer the LLM component. If you still use a Chat Generator, convert the string into messages before connecting it.

Source Code

To check this component's source code, open prompt_builder.py in the Haystack repository.

Usage Examples

Basic Configuration

  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:

This is a RAG pipeline that uses PromptBuilder with OpenAIChatGenerator:

# haystack-pipeline
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_integrations.components.embedders.sentence_transformers.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_integrations.components.rankers.sentence_transformers.SentenceTransformersSimilarityRanker
    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.chat.openai.OpenAIChatGenerator
    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: llm.messages
  - sender: llm.replies
    receiver: answer_builder.replies
  - sender: prompt_builder.prompt
    receiver: llm.messages
  - 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

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.

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:". Variables in the default template become required component inputs.
required_variables	Optional[Union[List[str], Literal['*']]]	"*"	List of variables that must be provided as input to PromptBuilder. If a required variable is missing, an exception is raised. The default "*" requires all variables found in the prompt. Set this parameter to None to make all variables optional and render missing values as empty strings.
variables	Optional[List[str]]	None	List of input variables to use in prompt templates instead of the ones inferred from the template parameter. Useful for prompt engineering when you need more variables than the ones in the default template.

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.

Related Information

• Writing Prompts in deepset AI Platform