feat: Add warning to ChatPromptBuilder and PromptBuilder if they have variables, but required_variables is not set (#9027)

* Add warning to ChatPromptBuilder and PromptBuilder if they have variables, but required variables is not set.

* Add reno

Author: sjrl

haystack/components/builders/chat_prompt_builder.py

@@ -136,6 +136,15 @@ def __init__(
                     variables += list(template_variables)
         self.variables = variables
 
+        if len(self.variables) > 0 and required_variables is None:
+            logger.warning(
+                "ChatPromptBuilder has {length} prompt variables, but `required_variables` is not set. "
+                "By default, all prompt variables are treated as optional, which may lead to unintended behavior in "
+                "multi-branch pipelines. To avoid unexpected execution, ensure that variables intended to be required "
+                "are explicitly set in `required_variables`.",
+                length=len(self.variables),
+            )
+
         # setup inputs
         for var in self.variables:
             if self.required_variables == "*" or var in self.required_variables:

haystack/components/builders/prompt_builder.py

@@ -7,9 +7,11 @@
 from jinja2 import meta
 from jinja2.sandbox import SandboxedEnvironment
 
-from haystack import component, default_to_dict
+from haystack import component, default_to_dict, logging
 from haystack.utils import Jinja2TimeExtension
 
+logger = logging.getLogger(__name__)
+
 
 @component
 class PromptBuilder:
@@ -180,6 +182,15 @@ def __init__(
         variables = variables or []
         self.variables = variables
 
+        if len(self.variables) > 0 and required_variables is None:
+            logger.warning(
+                "PromptBuilder has {length} prompt variables, but `required_variables` is not set. "
+                "By default, all prompt variables are treated as optional, which may lead to unintended behavior in "
+                "multi-branch pipelines. To avoid unexpected execution, ensure that variables intended to be required "
+                "are explicitly set in `required_variables`.",
+                length=len(self.variables),
+            )
+
         # setup inputs
         for var in self.variables:
             if self.required_variables == "*" or var in self.required_variables:

releasenotes/notes/warning-chat-and-prompt-builder-ca42295df9c1b770.yaml

@@ -0,0 +1,4 @@
+---
+enhancements:
+  - |
+    Added a warning to ChatPromptBuilder and PromptBuilder when prompt variables are present and `required_variables` is unset to help users avoid unexpected execution in multi-branch pipelines. The warning recommends users to set `required_variables`.

test/components/builders/test_chat_prompt_builder.py

@@ -1,5 +1,6 @@
 from typing import Any, Dict, List, Optional
 from jinja2 import TemplateSyntaxError
+import logging
 import pytest
 
 from haystack.components.builders.chat_prompt_builder import ChatPromptBuilder
@@ -335,6 +336,16 @@ def test_example_in_pipeline_simple(self):
         }
         assert result == expected_dynamic
 
+    def test_warning_no_required_variables(self, caplog):
+        with caplog.at_level(logging.WARNING):
+            _ = ChatPromptBuilder(
+                template=[
+                    ChatMessage.from_system("Write your response in this language:{{language}}"),
+                    ChatMessage.from_user("Tell me about {{location}}"),
+                ]
+            )
+            assert "ChatPromptBuilder has 2 prompt variables, but `required_variables` is not set. " in caplog.text
+
 
 class TestChatPromptBuilderDynamic:
     def test_multiple_templated_chat_messages(self):
@@ -521,13 +532,13 @@ def run(self):
         }
 
     def test_to_dict(self):
-        component = ChatPromptBuilder(
+        comp = ChatPromptBuilder(
             template=[ChatMessage.from_user("text and {var}"), ChatMessage.from_assistant("content {required_var}")],
             variables=["var", "required_var"],
             required_variables=["required_var"],
         )
 
-        assert component.to_dict() == {
+        assert comp.to_dict() == {
             "type": "haystack.components.builders.chat_prompt_builder.ChatPromptBuilder",
             "init_parameters": {
                 "template": [
@@ -545,7 +556,7 @@ def test_to_dict(self):
         }
 
     def test_from_dict(self):
-        component = ChatPromptBuilder.from_dict(
+        comp = ChatPromptBuilder.from_dict(
             data={
                 "type": "haystack.components.builders.chat_prompt_builder.ChatPromptBuilder",
                 "init_parameters": {
@@ -564,21 +575,21 @@ def test_from_dict(self):
             }
         )
 
-        assert component.template == [
+        assert comp.template == [
             ChatMessage.from_user("text and {var}"),
             ChatMessage.from_assistant("content {required_var}"),
         ]
-        assert component._variables == ["var", "required_var"]
-        assert component._required_variables == ["required_var"]
+        assert comp._variables == ["var", "required_var"]
+        assert comp._required_variables == ["required_var"]
 
     def test_from_dict_template_none(self):
-        component = ChatPromptBuilder.from_dict(
+        comp = ChatPromptBuilder.from_dict(
             data={
                 "type": "haystack.components.builders.chat_prompt_builder.ChatPromptBuilder",
                 "init_parameters": {"template": None},
             }
         )
 
-        assert component.template is None
-        assert component._variables is None
-        assert component._required_variables is None
+        assert comp.template is None
+        assert comp._variables is None
+        assert comp._required_variables is None

test/components/builders/test_prompt_builder.py

@@ -5,6 +5,7 @@
 from unittest.mock import patch
 
 import arrow
+import logging
 import pytest
 from jinja2 import TemplateSyntaxError
 
@@ -330,3 +331,8 @@ def test_invalid_offset(self) -> None:
         # Expect ValueError for invalid offset
         with pytest.raises(ValueError, match="Invalid offset or operator"):
             builder.run()
+
+    def test_warning_no_required_variables(self, caplog):
+        with caplog.at_level(logging.WARNING):
+            _ = PromptBuilder(template="This is a {{ variable }}")
+            assert "but `required_variables` is not set." in caplog.text