feat: Extend ChatPromptBuilder with messages tag (#11486)

Author: sjrl

haystack/utils/jinja2_chat_extension.py

@@ -72,6 +72,20 @@ class ChatMessageExtension(Extension):
     {% endmessage %}
     ```
 
+    This extension also provides an `{% insert %}` placeholder tag that evaluates an expression to a `ChatMessage`
+    or a list of `ChatMessage` objects and expands it into the prompt, so a runtime conversation can be interleaved
+    with literal `{% message %}` blocks:
+
+    ```
+    {% message role="system" %}You are a helpful assistant.{% endmessage %}
+    {% insert messages %}
+    {% message role="user" %}{{ query }}{% endmessage %}
+    ```
+
+    The expression can be a plain variable (`{% insert messages %}`), a slice or index
+    (`{% insert messages[-1:] %}`, `{% insert messages[-1] %}`), or a combination of variables
+    (`{% insert previous + current %}`).
+
     ### How it works
     1. The `{% message %}` tag is used to define a chat message.
     2. The message can contain text and other structured content parts.
@@ -85,24 +99,67 @@ class ChatMessageExtension(Extension):
 
     SUPPORTED_ROLES = [role.value for role in ChatRole]
 
-    tags = {"message"}
+    tags = {"message", "insert"}
 
     def __init__(self, environment: Any) -> None:
         super().__init__(environment)
         environment.finalize = _escape_sentinel_tags
         environment.filters["templatize_part"] = templatize_part
 
     def parse(self, parser: Any) -> nodes.Node | list[nodes.Node]:
+        """
+        Dispatch parsing based on the tag that triggered the extension.
+
+        Handles both the single `{% message %}` block tag and the `{% insert %}` placeholder tag.
+
+        :param parser: The Jinja2 parser instance
+        :return: A CallBlock node containing the parsed configuration
+        """
+        tag = next(parser.stream)
+        if tag.value == "insert":
+            return self._parse_insert_tag(parser, tag.lineno)
+        return self._parse_message_tag(parser, tag.lineno)
+
+    def _parse_insert_tag(self, parser: Any, lineno: int) -> nodes.Node:
+        """
+        Parse the `{% insert %}` placeholder tag.
+
+        This bodyless tag evaluates an expression to a `ChatMessage` or a list of `ChatMessage` objects and expands
+        it into the same JSON-line format produced by `{% message %}` blocks, so messages provided at runtime can be
+        interleaved with literal message blocks (for example a system message above and a user message below).
+
+        The expression can be a plain variable (`{% insert messages %}`), a slice or index
+        (`{% insert messages[-1:] %}`, `{% insert messages[-1] %}`), or a combination of variables
+        (`{% insert previous + current %}`).
+
+        :param parser: The Jinja2 parser instance
+        :param lineno: The line number of the tag, used for error reporting.
+        :return: A CallBlock node that expands the evaluated expression.
+        :raises TemplateSyntaxError: If the tag is not given an expression.
+        """
+        if parser.stream.current.test("block_end"):
+            raise TemplateSyntaxError(
+                "The 'insert' tag requires an expression that evaluates to a ChatMessage or a list of ChatMessage "
+                "objects, for example '{% insert messages %}' or '{% insert messages[-1:] %}'.",
+                lineno,
+            )
+        expr = parser.parse_expression()
+        # Bodyless tag: empty body, no matching end tag required.
+        return nodes.CallBlock(
+            self.call_method(name="_build_inserted_messages_json", args=[expr]), [], [], []
+        ).set_lineno(lineno)
+
+    def _parse_message_tag(self, parser: Any, lineno: int) -> nodes.Node | list[nodes.Node]:
         """
         Parse the message tag and its attributes in the Jinja2 template.
 
         This method handles the parsing of role (mandatory), name (optional), meta (optional) and message body content.
 
         :param parser: The Jinja2 parser instance
+        :param lineno: The line number of the tag, used for error reporting.
         :return: A CallBlock node containing the parsed message configuration
         :raises TemplateSyntaxError: If an invalid role is provided
         """
-        lineno = next(parser.stream).lineno
 
         # Parse role attribute (mandatory)
         parser.stream.expect("name:role")
@@ -173,6 +230,39 @@ def _build_chat_message_json(self, role: str, name: str | None, meta: dict, call
 
         return json.dumps(chat_message.to_dict()) + "\n"
 
+    def _build_inserted_messages_json(
+        self,
+        messages: list[ChatMessage] | ChatMessage,
+        caller: Callable[[], str],  # noqa: ARG002
+    ) -> str:
+        """
+        Expand a list of ChatMessage objects into newline-separated JSON, one message per line.
+
+        This method is called by Jinja2 when processing an `{% insert %}` tag. It produces the same JSON-line format
+        as `_build_chat_message_json`, so the messages are parsed back into ChatMessage objects by the
+        ChatPromptBuilder alongside any literal `{% message %}` blocks. The full `ChatMessage.to_dict()` payload is
+        serialized so that all content types (tool calls, tool call results, images, reasoning, name and meta) round
+        trip without loss.
+
+        :param messages: The value the `{% insert %}` expression evaluated to. A missing or empty value expands to
+            nothing. A single ChatMessage is also accepted, since indexing with an integer (for example
+            `{% insert messages[-1] %}`) yields one message rather than a list. The value is validated at render time
+            because it comes from untrusted template input.
+        :param caller: Callable that returns the (empty) rendered body. Unused.
+        :return: Newline-terminated JSON lines, one per message, or an empty string if there are no messages.
+        :raises ValueError: If the value is not a ChatMessage or a list of ChatMessage objects.
+        """
+        if isinstance(messages, ChatMessage):
+            messages = [messages]
+        if not messages:
+            return ""
+        if not isinstance(messages, (list, tuple)) or not all(isinstance(m, ChatMessage) for m in messages):
+            raise ValueError(
+                "The '{% insert %}' expression must evaluate to a ChatMessage or a list of ChatMessage objects. "
+                f"Got: {type(messages).__name__}."
+            )
+        return "".join(json.dumps(message.to_dict()) + "\n" for message in messages)
+
     @staticmethod
     def _parse_content_parts(content: str) -> list[ChatMessageContentT]:
         """

releasenotes/notes/add-messages-jinja-tag-483cca5bda6884f2.yaml

@@ -0,0 +1,34 @@
+---
+features:
+  - |
+    Added a new ``{% insert %}`` tag to the Jinja2 string templates used by ``ChatPromptBuilder``.
+    The tag is a placeholder that evaluates an expression to a ``ChatMessage`` or a list of ``ChatMessage``
+    objects and expands it into the prompt, so messages provided at runtime can be interleaved with literal
+    ``{% message %}`` blocks. For example, you can wrap the runtime messages with a system message above
+    and a templated user message below, then pass the messages (and any template variables) at run time:
+
+    .. code-block:: python
+
+        from haystack.components.builders import ChatPromptBuilder
+        from haystack.dataclasses import ChatMessage
+
+        template = """
+        {% message role="system" %}You are a helpful assistant.{% endmessage %}
+        {% insert messages %}
+        {% message role="user" %}{{ query }}{% endmessage %}
+        """
+
+        builder = ChatPromptBuilder(template=template)
+        result = builder.run(
+            messages=[ChatMessage.from_user("Hi"), ChatMessage.from_assistant("Hello!")],
+            query="What's the weather?",
+        )
+        # result["prompt"] -> [system, user "Hi", assistant "Hello!", user "What's the weather?"]
+
+    All content types (tool calls, tool call results, images, reasoning, ``name`` and ``meta``) round trip
+    without loss. A missing or empty value expands to nothing.
+
+    The expression can be a plain variable (``{% insert messages %}``), a slice or index
+    (``{% insert messages[-1:] %}``, ``{% insert messages[-1] %}``), or a combination of variables
+    (``{% insert previous + current %}``). Multiple ``{% insert %}`` tags can be used in a single template,
+    so the runtime messages can be split, reordered, or repeated across different positions.

test/components/builders/test_chat_prompt_builder.py

@@ -1076,3 +1076,47 @@ def test_poisoned_document_does_not_inject_image(self, in_memory_doc_store):
 
         images = [p for p in msg._content if isinstance(p, ImageContent)]
         assert len(images) == 0
+
+    def test_insert_placeholder(self):
+        builder = ChatPromptBuilder(template="{% insert messages %}")
+        assert builder.variables == ["messages"]
+        runtime = [ChatMessage.from_user("Hello"), ChatMessage.from_assistant("Hi")]
+        result = builder.run(messages=runtime)
+        assert result["prompt"] == runtime
+
+    def test_insert_placeholder_with_subscript(self):
+        builder = ChatPromptBuilder(template="{% insert messages[-1:] %}")
+        assert builder.variables == ["messages"]
+        runtime = [ChatMessage.from_user("first"), ChatMessage.from_assistant("last")]
+        result = builder.run(messages=runtime)
+        assert result["prompt"] == [ChatMessage.from_assistant("last")]
+
+    def test_insert_placeholder_custom_variable_name(self):
+        builder = ChatPromptBuilder(template="{% insert chat_history %}")
+        assert builder.variables == ["chat_history"]
+        runtime = [ChatMessage.from_user("Hello"), ChatMessage.from_assistant("Hi")]
+        result = builder.run(chat_history=runtime)
+        assert result["prompt"] == runtime
+
+    def test_insert_placeholder_combines_variables(self):
+        builder = ChatPromptBuilder(template="{% insert previous + current %}")
+        assert set(builder.variables) == {"previous", "current"}
+        previous = [ChatMessage.from_user("p1"), ChatMessage.from_assistant("p2")]
+        current = [ChatMessage.from_user("c1")]
+        result = builder.run(previous=previous, current=current)
+        assert result["prompt"] == previous + current
+
+    def test_insert_placeholder_interleaved_with_blocks(self):
+        template = (
+            '{% message role="system" %}You are helpful.{% endmessage %}'
+            "{% insert messages %}"
+            '{% message role="user" %}{{ query }}{% endmessage %}'
+        )
+        builder = ChatPromptBuilder(template=template)
+        assert set(builder.variables) == {"messages", "query"}
+        result = builder.run(messages=[ChatMessage.from_user("earlier")], query="now")
+        assert result["prompt"] == [
+            ChatMessage.from_system("You are helpful."),
+            ChatMessage.from_user("earlier"),
+            ChatMessage.from_user("now"),
+        ]

test/utils/test_jinja2_chat_extension.py

@@ -7,10 +7,11 @@
 from unittest.mock import patch
 
 import pytest
-from jinja2 import TemplateSyntaxError
+from jinja2 import TemplateSyntaxError, meta
 from jinja2.sandbox import SandboxedEnvironment
 
 from haystack.dataclasses.chat_message import (
+    ChatMessage,
     FileContent,
     ImageContent,
     ReasoningContent,
@@ -604,6 +605,152 @@ def test_common_symbols_not_escaped(self, jinja_env):
         assert output["content"][0]["text"] == text_with_symbols
 
 
+class TestInsertTag:
+    def _parse_lines(self, rendered: str) -> list[ChatMessage]:
+        return [ChatMessage.from_dict(json.loads(line)) for line in rendered.strip().split("\n") if line.strip()]
+
+    def test_expands_messages(self, jinja_env):
+        template = "{% insert messages %}"
+        messages = [ChatMessage.from_user("Hello"), ChatMessage.from_assistant("Hi there")]
+        rendered = jinja_env.from_string(template).render(messages=messages)
+        assert self._parse_lines(rendered) == messages
+
+    def test_empty_messages_expands_to_nothing(self, jinja_env):
+        template = "{% insert messages %}"
+        assert jinja_env.from_string(template).render(messages=[]).strip() == ""
+
+    def test_missing_variable_expands_to_nothing(self, jinja_env):
+        # The expression resolves to Undefined (falsy) when not provided -> emits nothing rather than raising
+        template = "{% insert messages %}"
+        assert jinja_env.from_string(template).render().strip() == ""
+
+    def test_interleaved_with_literal_message_blocks(self, jinja_env):
+        template = """
+        {% message role="system" %}You are helpful.{% endmessage %}
+        {% insert messages %}
+        {% message role="user" %}{{ query }}{% endmessage %}
+        """
+        runtime = [ChatMessage.from_user("first"), ChatMessage.from_assistant("second")]
+        rendered = jinja_env.from_string(template).render(messages=runtime, query="final question")
+        parsed = self._parse_lines(rendered)
+        assert [m.role.value for m in parsed] == ["system", "user", "assistant", "user"]
+        assert parsed[0].text == "You are helpful."
+        assert parsed[1].text == "first"
+        assert parsed[2].text == "second"
+        assert parsed[3].text == "final question"
+
+    def test_is_detected_as_template_variable(self):
+        # The `{% insert %}` expression must surface its variables as undeclared so that the
+        # ChatPromptBuilder (and Agent) can register and pass them.
+        env = SandboxedEnvironment(extensions=[ChatMessageExtension])
+        assert "messages" in meta.find_undeclared_variables(env.parse("{% insert messages %}"))
+        assert "messages" in meta.find_undeclared_variables(env.parse("{% insert messages[-1] %}"))
+        assert {"previous", "current"} <= meta.find_undeclared_variables(env.parse("{% insert previous + current %}"))
+
+    def test_round_trips_all_content_types(self, jinja_env, base64_image_string):
+        tool_call = ToolCall(tool_name="search", arguments={"query": "q"}, id="search_1")
+        messages = [
+            ChatMessage.from_system("system text", meta={"k": "v"}),
+            ChatMessage.from_user("user text", name="Bob"),
+            ChatMessage.from_user(
+                content_parts=["look", ImageContent(base64_image=base64_image_string, mime_type="image/png")]
+            ),
+            ChatMessage.from_assistant(
+                text="thinking then calling",
+                tool_calls=[tool_call],
+                reasoning=ReasoningContent(reasoning_text="let me think", extra={"a": 1}),
+            ),
+            ChatMessage.from_tool(tool_result="result", origin=tool_call, error=False),
+        ]
+        rendered = jinja_env.from_string("{% insert messages %}").render(messages=messages)
+        assert self._parse_lines(rendered) == messages
+
+    @pytest.fixture
+    def three_messages(self) -> list[ChatMessage]:
+        return [ChatMessage.from_user("a"), ChatMessage.from_assistant("b"), ChatMessage.from_user("c")]
+
+    def test_single_index(self, jinja_env, three_messages):
+        # An integer index yields a single ChatMessage, which is expanded as a one-message list.
+        rendered = jinja_env.from_string("{% insert messages[-1] %}").render(messages=three_messages)
+        assert self._parse_lines(rendered) == [three_messages[-1]]
+
+    def test_slice(self, jinja_env, three_messages):
+        rendered = jinja_env.from_string("{% insert messages[-1:] %}").render(messages=three_messages)
+        assert self._parse_lines(rendered) == three_messages[-1:]
+
+        rendered = jinja_env.from_string("{% insert messages[:-1] %}").render(messages=three_messages)
+        assert self._parse_lines(rendered) == three_messages[:-1]
+
+        rendered = jinja_env.from_string("{% insert messages[1:] %}").render(messages=three_messages)
+        assert self._parse_lines(rendered) == three_messages[1:]
+
+    def test_combine_multiple_variables(self, jinja_env):
+        # The expression can combine several variables, e.g. concatenating two message lists.
+        previous = [ChatMessage.from_user("p1"), ChatMessage.from_assistant("p2")]
+        current = [ChatMessage.from_user("c1")]
+        rendered = jinja_env.from_string("{% insert previous + current %}").render(previous=previous, current=current)
+        assert self._parse_lines(rendered) == previous + current
+
+    def test_custom_variable_name(self, jinja_env, three_messages):
+        rendered = jinja_env.from_string("{% insert chat_history %}").render(chat_history=three_messages)
+        assert self._parse_lines(rendered) == three_messages
+
+    def test_slice_interleaved_with_blocks(self, jinja_env, three_messages):
+        template = (
+            '{% message role="system" %}sys{% endmessage %}'
+            "{% insert messages[-1:] %}"
+            '{% message role="user" %}{{ query }}{% endmessage %}'
+        )
+        rendered = jinja_env.from_string(template).render(messages=three_messages, query="q")
+        parsed = self._parse_lines(rendered)
+        assert [m.text for m in parsed] == ["sys", "c", "q"]
+
+    def test_multiple_inserts_split_and_reorder(self, jinja_env):
+        # Each `{% insert %}` tag expands independently, so a template can split the runtime messages across
+        # several positions, interleave literal blocks, and even repeat a slice.
+        messages = [
+            ChatMessage.from_system("S"),
+            ChatMessage.from_user("u1"),
+            ChatMessage.from_assistant("a1"),
+            ChatMessage.from_user("u2"),
+        ]
+        template = (
+            "{% insert messages[0] %}"
+            '{% message role="user" %}INJECTED{% endmessage %}'
+            "{% insert messages[1:] %}"
+            "{% insert messages[-1] %}"
+        )
+        rendered = jinja_env.from_string(template).render(messages=messages)
+        parsed = self._parse_lines(rendered)
+        assert [(m.role.value, m.text) for m in parsed] == [
+            ("system", "S"),
+            ("user", "INJECTED"),
+            ("user", "u1"),
+            ("assistant", "a1"),
+            ("user", "u2"),
+            ("user", "u2"),
+        ]
+
+    def test_message_text_with_sentinel_tag_is_not_escaped(self, jinja_env):
+        # The tag uses a CallBlock so its output bypasses `finalize` sentinel-escaping. This is safe here because
+        # `{% insert %}` serializes with ChatMessage.to_dict and the builder reparses with json.loads +
+        # ChatMessage.from_dict -- it never runs the content-part parser. So a user-injected `<haystack_content_part>`
+        # string in the message text stays plain text and can't be promoted to a structured part (image, tool call,
+        # ...); it just has to round trip intact.
+        message = ChatMessage.from_user("see <haystack_content_part> here")
+        rendered = jinja_env.from_string("{% insert messages %}").render(messages=[message])
+        assert self._parse_lines(rendered) == [message]
+
+    def test_requires_an_expression(self, jinja_env):
+        with pytest.raises(TemplateSyntaxError, match="requires an expression"):
+            jinja_env.from_string("{% insert %}").render(messages=[])
+
+    def test_non_message_value_raises_error(self, jinja_env):
+        template = "{% insert messages %}"
+        with pytest.raises(ValueError, match="must evaluate to a ChatMessage or a list of ChatMessage objects"):
+            jinja_env.from_string(template).render(messages=["not a message"])
+
+
 class TestSentinelTagInjectionPrevention:
     def test_sentinel_tag_injection_via_text_variable(self, jinja_env):
         fake_b64 = base64.b64encode(b"ATTACKER_PAYLOAD").decode()