Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 92 additions & 2 deletions haystack/utils/jinja2_chat_extension.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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")
Expand Down Expand Up @@ -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):
Comment thread
anakin87 marked this conversation as resolved.
Resolved
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]:
"""
Expand Down
34 changes: 34 additions & 0 deletions releasenotes/notes/add-messages-jinja-tag-483cca5bda6884f2.yaml
Original file line number Diff line number Diff line change
@@ -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 %}
Comment thread
sjrl marked this conversation as resolved.
Resolved
"""

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.
44 changes: 44 additions & 0 deletions test/components/builders/test_chat_prompt_builder.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"),
]
149 changes: 148 additions & 1 deletion test/utils/test_jinja2_chat_extension.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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()
Expand Down
Loading