1  ---
  2  title: Builders
  3  id: builders-api
  4  description: Extract the output of a Generator to an Answer format, and build prompts.
  5  slug: "/builders-api"
  6  ---
  7  
  8  <a id="answer_builder"></a>
  9  
 10  # Module answer\_builder
 11  
 12  <a id="answer_builder.AnswerBuilder"></a>
 13  
 14  ## AnswerBuilder
 15  
 16  Converts a query and Generator replies into a `GeneratedAnswer` object.
 17  
 18  AnswerBuilder parses Generator replies using custom regular expressions.
 19  Check out the usage example below to see how it works.
 20  Optionally, it can also take documents and metadata from the Generator to add to the `GeneratedAnswer` object.
 21  AnswerBuilder works with both non-chat and chat Generators.
 22  
 23  ### Usage example
 24  
 25  ```python
 26  from haystack.components.builders import AnswerBuilder
 27  
 28  builder = AnswerBuilder(pattern="Answer: (.*)")
 29  builder.run(query="What's the answer?", replies=["This is an argument. Answer: This is the answer."])
 30  ```
 31  
 32  <a id="answer_builder.AnswerBuilder.__init__"></a>
 33  
 34  #### AnswerBuilder.\_\_init\_\_
 35  
 36  ```python
 37  def __init__(pattern: Optional[str] = None,
 38               reference_pattern: Optional[str] = None,
 39               last_message_only: bool = False)
 40  ```
 41  
 42  Creates an instance of the AnswerBuilder component.
 43  
 44  **Arguments**:
 45  
 46  - `pattern`: The regular expression pattern to extract the answer text from the Generator.
 47  If not specified, the entire response is used as the answer.
 48  The regular expression can have one capture group at most.
 49  If present, the capture group text
 50  is used as the answer. If no capture group is present, the whole match is used as the answer.
 51  Examples:
 52      `[^\n]+$` finds "this is an answer" in a string "this is an argument.\nthis is an answer".
 53      `Answer: (.*)` finds "this is an answer" in a string "this is an argument. Answer: this is an answer".
 54  - `reference_pattern`: The regular expression pattern used for parsing the document references.
 55  If not specified, no parsing is done, and all documents are referenced.
 56  References need to be specified as indices of the input documents and start at [1].
 57  Example: `\[(\d+)\]` finds "1" in a string "this is an answer[1]".
 58  - `last_message_only`: If False (default value), all messages are used as the answer.
 59  If True, only the last message is used as the answer.
 60  
 61  <a id="answer_builder.AnswerBuilder.run"></a>
 62  
 63  #### AnswerBuilder.run
 64  
 65  ```python
 66  @component.output_types(answers=list[GeneratedAnswer])
 67  def run(query: str,
 68          replies: Union[list[str], list[ChatMessage]],
 69          meta: Optional[list[dict[str, Any]]] = None,
 70          documents: Optional[list[Document]] = None,
 71          pattern: Optional[str] = None,
 72          reference_pattern: Optional[str] = None)
 73  ```
 74  
 75  Turns the output of a Generator into `GeneratedAnswer` objects using regular expressions.
 76  
 77  **Arguments**:
 78  
 79  - `query`: The input query used as the Generator prompt.
 80  - `replies`: The output of the Generator. Can be a list of strings or a list of `ChatMessage` objects.
 81  - `meta`: The metadata returned by the Generator. If not specified, the generated answer will contain no metadata.
 82  - `documents`: The documents used as the Generator inputs. If specified, they are added to
 83  the`GeneratedAnswer` objects.
 84  If both `documents` and `reference_pattern` are specified, the documents referenced in the
 85  Generator output are extracted from the input documents and added to the `GeneratedAnswer` objects.
 86  - `pattern`: The regular expression pattern to extract the answer text from the Generator.
 87  If not specified, the entire response is used as the answer.
 88  The regular expression can have one capture group at most.
 89  If present, the capture group text
 90  is used as the answer. If no capture group is present, the whole match is used as the answer.
 91      Examples:
 92          `[^\n]+$` finds "this is an answer" in a string "this is an argument.\nthis is an answer".
 93          `Answer: (.*)` finds "this is an answer" in a string
 94          "this is an argument. Answer: this is an answer".
 95  - `reference_pattern`: The regular expression pattern used for parsing the document references.
 96  If not specified, no parsing is done, and all documents are referenced.
 97  References need to be specified as indices of the input documents and start at [1].
 98  Example: `\[(\d+)\]` finds "1" in a string "this is an answer[1]".
 99  
100  **Returns**:
101  
102  A dictionary with the following keys:
103  - `answers`: The answers received from the output of the Generator.
104  
105  <a id="prompt_builder"></a>
106  
107  # Module prompt\_builder
108  
109  <a id="prompt_builder.PromptBuilder"></a>
110  
111  ## PromptBuilder
112  
113  Renders a prompt filling in any variables so that it can send it to a Generator.
114  
115  The prompt uses Jinja2 template syntax.
116  The variables in the default template are used as PromptBuilder's input and are all optional.
117  If they're not provided, they're replaced with an empty string in the rendered prompt.
118  To try out different prompts, you can replace the prompt template at runtime by
119  providing a template for each pipeline run invocation.
120  
121  ### Usage examples
122  
123  #### On its own
124  
125  This example uses PromptBuilder to render a prompt template and fill it with `target_language`
126  and `snippet`. PromptBuilder returns a prompt with the string "Translate the following context to Spanish.
127  Context: I can't speak Spanish.; Translation:".
128  ```python
129  from haystack.components.builders import PromptBuilder
130  
131  template = "Translate the following context to {{ target_language }}. Context: {{ snippet }}; Translation:"
132  builder = PromptBuilder(template=template)
133  builder.run(target_language="spanish", snippet="I can't speak spanish.")
134  ```
135  
136  #### In a Pipeline
137  
138  This is an example of a RAG pipeline where PromptBuilder renders a custom prompt template and fills it
139  with the contents of the retrieved documents and a query. The rendered prompt is then sent to a Generator.
140  ```python
141  from haystack import Pipeline, Document
142  from haystack.utils import Secret
143  from haystack.components.generators import OpenAIGenerator
144  from haystack.components.builders.prompt_builder import PromptBuilder
145  
146  # in a real world use case documents could come from a retriever, web, or any other source
147  documents = [Document(content="Joe lives in Berlin"), Document(content="Joe is a software engineer")]
148  prompt_template = """
149      Given these documents, answer the question.
150      Documents:
151      {% for doc in documents %}
152          {{ doc.content }}
153      {% endfor %}
154  
155      Question: {{query}}
156      Answer:
157      """
158  p = Pipeline()
159  p.add_component(instance=PromptBuilder(template=prompt_template), name="prompt_builder")
160  p.add_component(instance=OpenAIGenerator(api_key=Secret.from_env_var("OPENAI_API_KEY")), name="llm")
161  p.connect("prompt_builder", "llm")
162  
163  question = "Where does Joe live?"
164  result = p.run({"prompt_builder": {"documents": documents, "query": question}})
165  print(result)
166  ```
167  
168  #### Changing the template at runtime (prompt engineering)
169  
170  You can change the prompt template of an existing pipeline, like in this example:
171  ```python
172  documents = [
173      Document(content="Joe lives in Berlin", meta={"name": "doc1"}),
174      Document(content="Joe is a software engineer", meta={"name": "doc1"}),
175  ]
176  new_template = """
177      You are a helpful assistant.
178      Given these documents, answer the question.
179      Documents:
180      {% for doc in documents %}
181          Document {{ loop.index }}:
182          Document name: {{ doc.meta['name'] }}
183          {{ doc.content }}
184      {% endfor %}
185  
186      Question: {{ query }}
187      Answer:
188      """
189  p.run({
190      "prompt_builder": {
191          "documents": documents,
192          "query": question,
193          "template": new_template,
194      },
195  })
196  ```
197  To replace the variables in the default template when testing your prompt,
198  pass the new variables in the `variables` parameter.
199  
200  #### Overwriting variables at runtime
201  
202  To overwrite the values of variables, use `template_variables` during runtime:
203  ```python
204  language_template = """
205  You are a helpful assistant.
206  Given these documents, answer the question.
207  Documents:
208  {% for doc in documents %}
209      Document {{ loop.index }}:
210      Document name: {{ doc.meta['name'] }}
211      {{ doc.content }}
212  {% endfor %}
213  
214  Question: {{ query }}
215  Please provide your answer in {{ answer_language | default('English') }}
216  Answer:
217  """
218  p.run({
219      "prompt_builder": {
220          "documents": documents,
221          "query": question,
222          "template": language_template,
223          "template_variables": {"answer_language": "German"},
224      },
225  })
226  ```
227  Note that `language_template` introduces variable `answer_language` which is not bound to any pipeline variable.
228  If not set otherwise, it will use its default value 'English'.
229  This example overwrites its value to 'German'.
230  Use `template_variables` to overwrite pipeline variables (such as documents) as well.
231  
232  <a id="prompt_builder.PromptBuilder.__init__"></a>
233  
234  #### PromptBuilder.\_\_init\_\_
235  
236  ```python
237  def __init__(template: str,
238               required_variables: Optional[Union[list[str],
239                                                  Literal["*"]]] = None,
240               variables: Optional[list[str]] = None)
241  ```
242  
243  Constructs a PromptBuilder component.
244  
245  **Arguments**:
246  
247  - `template`: A prompt template that uses Jinja2 syntax to add variables. For example:
248  `"Summarize this document: {{ documents[0].content }}\nSummary:"`
249  It's used to render the prompt.
250  The variables in the default template are input for PromptBuilder and are all optional,
251  unless explicitly specified.
252  If an optional variable is not provided, it's replaced with an empty string in the rendered prompt.
253  - `required_variables`: List variables that must be provided as input to PromptBuilder.
254  If a variable listed as required is not provided, an exception is raised.
255  If set to "*", all variables found in the prompt are required. Optional.
256  - `variables`: List input variables to use in prompt templates instead of the ones inferred from the
257  `template` parameter. For example, to use more variables during prompt engineering than the ones present
258  in the default template, you can provide them here.
259  
260  <a id="prompt_builder.PromptBuilder.to_dict"></a>
261  
262  #### PromptBuilder.to\_dict
263  
264  ```python
265  def to_dict() -> dict[str, Any]
266  ```
267  
268  Returns a dictionary representation of the component.
269  
270  **Returns**:
271  
272  Serialized dictionary representation of the component.
273  
274  <a id="prompt_builder.PromptBuilder.run"></a>
275  
276  #### PromptBuilder.run
277  
278  ```python
279  @component.output_types(prompt=str)
280  def run(template: Optional[str] = None,
281          template_variables: Optional[dict[str, Any]] = None,
282          **kwargs)
283  ```
284  
285  Renders the prompt template with the provided variables.
286  
287  It applies the template variables to render the final prompt. You can provide variables via pipeline kwargs.
288  In order to overwrite the default template, you can set the `template` parameter.
289  In order to overwrite pipeline kwargs, you can set the `template_variables` parameter.
290  
291  **Arguments**:
292  
293  - `template`: An optional string template to overwrite PromptBuilder's default template. If None, the default template
294  provided at initialization is used.
295  - `template_variables`: An optional dictionary of template variables to overwrite the pipeline variables.
296  - `kwargs`: Pipeline variables used for rendering the prompt.
297  
298  **Raises**:
299  
300  - `ValueError`: If any of the required template variables is not provided.
301  
302  **Returns**:
303  
304  A dictionary with the following keys:
305  - `prompt`: The updated prompt text after rendering the prompt template.
306  
307  <a id="chat_prompt_builder"></a>
308  
309  # Module chat\_prompt\_builder
310  
311  <a id="chat_prompt_builder.ChatPromptBuilder"></a>
312  
313  ## ChatPromptBuilder
314  
315  Renders a chat prompt from a template using Jinja2 syntax.
316  
317  A template can be a list of `ChatMessage` objects, or a special string, as shown in the usage examples.
318  
319  It constructs prompts using static or dynamic templates, which you can update for each pipeline run.
320  
321  Template variables in the template are optional unless specified otherwise.
322  If an optional variable isn't provided, it defaults to an empty string. Use `variable` and `required_variables`
323  to define input types and required variables.
324  
325  ### Usage examples
326  
327  #### Static ChatMessage prompt template
328  
329  ```python
330  template = [ChatMessage.from_user("Translate to {{ target_language }}. Context: {{ snippet }}; Translation:")]
331  builder = ChatPromptBuilder(template=template)
332  builder.run(target_language="spanish", snippet="I can't speak spanish.")
333  ```
334  
335  #### Overriding static ChatMessage template at runtime
336  
337  ```python
338  template = [ChatMessage.from_user("Translate to {{ target_language }}. Context: {{ snippet }}; Translation:")]
339  builder = ChatPromptBuilder(template=template)
340  builder.run(target_language="spanish", snippet="I can't speak spanish.")
341  
342  msg = "Translate to {{ target_language }} and summarize. Context: {{ snippet }}; Summary:"
343  summary_template = [ChatMessage.from_user(msg)]
344  builder.run(target_language="spanish", snippet="I can't speak spanish.", template=summary_template)
345  ```
346  
347  #### Dynamic ChatMessage prompt template
348  
349  ```python
350  from haystack.components.builders import ChatPromptBuilder
351  from haystack.components.generators.chat import OpenAIChatGenerator
352  from haystack.dataclasses import ChatMessage
353  from haystack import Pipeline
354  from haystack.utils import Secret
355  
356  # no parameter init, we don't use any runtime template variables
357  prompt_builder = ChatPromptBuilder()
358  llm = OpenAIChatGenerator(api_key=Secret.from_token("<your-api-key>"), model="gpt-4o-mini")
359  
360  pipe = Pipeline()
361  pipe.add_component("prompt_builder", prompt_builder)
362  pipe.add_component("llm", llm)
363  pipe.connect("prompt_builder.prompt", "llm.messages")
364  
365  location = "Berlin"
366  language = "English"
367  system_message = ChatMessage.from_system("You are an assistant giving information to tourists in {{language}}")
368  messages = [system_message, ChatMessage.from_user("Tell me about {{location}}")]
369  
370  res = pipe.run(data={"prompt_builder": {"template_variables": {"location": location, "language": language},
371                                      "template": messages}})
372  print(res)
373  
374  >> {'llm': {'replies': [ChatMessage(_role=<ChatRole.ASSISTANT: 'assistant'>, _content=[TextContent(text=
375  "Berlin is the capital city of Germany and one of the most vibrant
376  and diverse cities in Europe. Here are some key things to know...Enjoy your time exploring the vibrant and dynamic
377  capital of Germany!")], _name=None, _meta={'model': 'gpt-4o-mini',
378  'index': 0, 'finish_reason': 'stop', 'usage': {'prompt_tokens': 27, 'completion_tokens': 681, 'total_tokens':
379  708}})]}}
380  
381  messages = [system_message, ChatMessage.from_user("What's the weather forecast for {{location}} in the next
382  {{day_count}} days?")]
383  
384  res = pipe.run(data={"prompt_builder": {"template_variables": {"location": location, "day_count": "5"},
385                                      "template": messages}})
386  
387  print(res)
388  >> {'llm': {'replies': [ChatMessage(_role=<ChatRole.ASSISTANT: 'assistant'>, _content=[TextContent(text=
389  "Here is the weather forecast for Berlin in the next 5
390  days:\n\nDay 1: Mostly cloudy with a high of 22°C (72°F) and...so it's always a good idea to check for updates
391  closer to your visit.")], _name=None, _meta={'model': 'gpt-4o-mini',
392  'index': 0, 'finish_reason': 'stop', 'usage': {'prompt_tokens': 37, 'completion_tokens': 201,
393  'total_tokens': 238}})]}}
394  ```
395  
396  #### String prompt template
397  ```python
398  from haystack.components.builders import ChatPromptBuilder
399  from haystack.dataclasses.image_content import ImageContent
400  
401  template = """
402  {% message role="system" %}
403  You are a helpful assistant.
404  {% endmessage %}
405  
406  {% message role="user" %}
407  Hello! I am {{user_name}}. What's the difference between the following images?
408  {% for image in images %}
409  {{ image | templatize_part }}
410  {% endfor %}
411  {% endmessage %}
412  """
413  
414  images = [ImageContent.from_file_path("apple.jpg"), ImageContent.from_file_path("orange.jpg")]
415  
416  builder = ChatPromptBuilder(template=template)
417  builder.run(user_name="John", images=images)
418  ```
419  
420  <a id="chat_prompt_builder.ChatPromptBuilder.__init__"></a>
421  
422  #### ChatPromptBuilder.\_\_init\_\_
423  
424  ```python
425  def __init__(template: Optional[Union[list[ChatMessage], str]] = None,
426               required_variables: Optional[Union[list[str],
427                                                  Literal["*"]]] = None,
428               variables: Optional[list[str]] = None)
429  ```
430  
431  Constructs a ChatPromptBuilder component.
432  
433  **Arguments**:
434  
435  - `template`: A list of `ChatMessage` objects or a string template. The component looks for Jinja2 template syntax and
436  renders the prompt with the provided variables. Provide the template in either
437  the `init` method` or the `run` method.
438  - `required_variables`: List variables that must be provided as input to ChatPromptBuilder.
439  If a variable listed as required is not provided, an exception is raised.
440  If set to "*", all variables found in the prompt are required. Optional.
441  - `variables`: List input variables to use in prompt templates instead of the ones inferred from the
442  `template` parameter. For example, to use more variables during prompt engineering than the ones present
443  in the default template, you can provide them here.
444  
445  <a id="chat_prompt_builder.ChatPromptBuilder.run"></a>
446  
447  #### ChatPromptBuilder.run
448  
449  ```python
450  @component.output_types(prompt=list[ChatMessage])
451  def run(template: Optional[Union[list[ChatMessage], str]] = None,
452          template_variables: Optional[dict[str, Any]] = None,
453          **kwargs)
454  ```
455  
456  Renders the prompt template with the provided variables.
457  
458  It applies the template variables to render the final prompt. You can provide variables with pipeline kwargs.
459  To overwrite the default template, you can set the `template` parameter.
460  To overwrite pipeline kwargs, you can set the `template_variables` parameter.
461  
462  **Arguments**:
463  
464  - `template`: An optional list of `ChatMessage` objects or string template to overwrite ChatPromptBuilder's default
465  template.
466  If `None`, the default template provided at initialization is used.
467  - `template_variables`: An optional dictionary of template variables to overwrite the pipeline variables.
468  - `kwargs`: Pipeline variables used for rendering the prompt.
469  
470  **Raises**:
471  
472  - `ValueError`: If `chat_messages` is empty or contains elements that are not instances of `ChatMessage`.
473  
474  **Returns**:
475  
476  A dictionary with the following keys:
477  - `prompt`: The updated list of `ChatMessage` objects after rendering the templates.
478  
479  <a id="chat_prompt_builder.ChatPromptBuilder.to_dict"></a>
480  
481  #### ChatPromptBuilder.to\_dict
482  
483  ```python
484  def to_dict() -> dict[str, Any]
485  ```
486  
487  Returns a dictionary representation of the component.
488  
489  **Returns**:
490  
491  Serialized dictionary representation of the component.
492  
493  <a id="chat_prompt_builder.ChatPromptBuilder.from_dict"></a>
494  
495  #### ChatPromptBuilder.from\_dict
496  
497  ```python
498  @classmethod
499  def from_dict(cls, data: dict[str, Any]) -> "ChatPromptBuilder"
500  ```
501  
502  Deserialize this component from a dictionary.
503  
504  **Arguments**:
505  
506  - `data`: The dictionary to deserialize and create the component.
507  
508  **Returns**:
509  
510  The deserialized component.