feat!: Update LLM component to dynamically set messages as required or optional based on init config (#11300)

Author: sjrl

haystack/components/generators/chat/llm.py

@@ -48,7 +48,7 @@ def __init__(
         *,
         chat_generator: ChatGenerator,
         system_prompt: str | None = None,
-        user_prompt: str,
+        user_prompt: str | None = None,
         required_variables: list[str] | Literal["*"] = "*",
         streaming_callback: StreamingCallbackT | None = None,
     ) -> None:
@@ -57,21 +57,18 @@ def __init__(
 
         :param chat_generator: An instance of the chat generator that the LLM should use.
         :param system_prompt: System prompt for the LLM.
-        :param user_prompt: User prompt for the LLM. Must contain at least one Jinja2 template variable
-            (e.g., ``{{ variable_name }}``). This prompt is appended to the messages provided at runtime.
+        :param user_prompt: User prompt for the LLM. This prompt is appended to the messages provided at
+            runtime. If it contains Jinja2 template variables (e.g., `{{ variable_name }}`), they become
+            inputs to the component. If omitted or if there are no template variables, `messages` must be
+            provided at runtime instead.
         :param required_variables:
             Variables that must be provided as input to user_prompt.
             If a variable listed as required is not provided, an exception is raised.
-            If set to ``"*"``, all variables found in the prompt are required. Defaults to ``"*"``.
+            If set to `"*"`, all variables found in the prompt are required. Defaults to `"*"`.
+            Only relevant when `user_prompt` contains template variables.
         :param streaming_callback: A callback that will be invoked when a response is streamed from the LLM.
-        :raises ValueError: If user_prompt contains no template variables.
-        :raises ValueError: If required_variables is an empty list.
+        :raises ValueError: If user_prompt contains template variables but required_variables is an empty list.
         """
-        if isinstance(required_variables, list) and len(required_variables) == 0:
-            raise ValueError(
-                "required_variables must not be empty. Set it to '*' to require all variables, "
-                "or provide a non-empty list of variable names."
-            )
         super(LLM, self).__init__(  # noqa: UP008
             chat_generator=chat_generator,
             system_prompt=system_prompt,
@@ -80,11 +77,17 @@ def __init__(
             streaming_callback=streaming_callback,
         )
         if self._user_chat_prompt_builder is None or len(self._user_chat_prompt_builder.variables) == 0:
-            raise ValueError(
-                "user_prompt must contain at least one template variable (e.g., '{{ variable_name }}'). "
-                "The LLM component requires at least one required input variable to ensure proper "
-                "pipeline scheduling."
-            )
+            # This means user_prompt is empty or has no template variables.
+            # To ensure properly scheduling we then require messages to be passed at runtime.
+            component.set_input_type(self, "messages", list[ChatMessage])
+        else:
+            # user prompt was provided with variables
+            if isinstance(required_variables, list) and len(required_variables) == 0:
+                raise ValueError(
+                    "required_variables must not be empty. Set it to '*' to require all variables, "
+                    "or provide a non-empty list of variable names."
+                )
+            component.set_input_type(self, "messages", list[ChatMessage], None)
 
     def to_dict(self) -> dict[str, Any]:
         """
@@ -118,11 +121,10 @@ def from_dict(cls, data: dict[str, Any]) -> "LLM":
 
         return default_from_dict(cls, data)
 
-    def run(
+    def run(  # type: ignore[override]  # `messages` is in **kwargs to allow dynamic required/optional status
         self,
-        messages: list[ChatMessage] | None = None,
-        streaming_callback: StreamingCallbackT | None = None,
         *,
+        streaming_callback: StreamingCallbackT | None = None,
         generation_kwargs: dict[str, Any] | None = None,
         system_prompt: str | None = None,
         user_prompt: str | None = None,
@@ -131,7 +133,9 @@ def run(
         """
         Process messages and generate a response from the language model.
 
-        :param messages: List of Haystack ChatMessage objects to process.
+        :param messages: Optional list of ChatMessage objects to prepend to the conversation. Whether this is
+            required or optional depends on the `user_prompt` configuration: if `user_prompt` has no template
+            variables, `messages` must be provided. Passed via `**kwargs`.
         :param streaming_callback: A callback that will be invoked when a response is streamed from the LLM.
         :param generation_kwargs: Additional keyword arguments for the underlying chat generator. These parameters
             will override the parameters passed during component initialization.
@@ -145,6 +149,9 @@ def run(
             - "messages": List of all messages exchanged during the LLM's run.
             - "last_message": The last message exchanged during the LLM's run.
         """
+        # `messages` is intentionally omitted from the signature so the framework can treat it as required
+        # or optional depending on init configuration. See __init__ for details.
+        messages = kwargs.pop("messages", None)
         return super(LLM, self).run(  # noqa: UP008
             messages=messages or [],
             streaming_callback=streaming_callback,
@@ -154,11 +161,10 @@ def run(
             **kwargs,
         )
 
-    async def run_async(
+    async def run_async(  # type: ignore[override]  # `messages` is in **kwargs to allow dynamic required/optional status
         self,
-        messages: list[ChatMessage] | None = None,
-        streaming_callback: StreamingCallbackT | None = None,
         *,
+        streaming_callback: StreamingCallbackT | None = None,
         generation_kwargs: dict[str, Any] | None = None,
         system_prompt: str | None = None,
         user_prompt: str | None = None,
@@ -167,7 +173,9 @@ async def run_async(
         """
         Asynchronously process messages and generate a response from the language model.
 
-        :param messages: List of Haystack ChatMessage objects to process.
+        :param messages: Optional list of ChatMessage objects to prepend to the conversation. Whether this is
+            required or optional depends on the `user_prompt` configuration: if `user_prompt` has no template
+            variables, `messages` must be provided. Passed via `**kwargs`.
         :param streaming_callback: An asynchronous callback that will be invoked when a response is streamed
             from the LLM.
         :param generation_kwargs: Additional keyword arguments for the underlying chat generator. These parameters
@@ -182,6 +190,9 @@ async def run_async(
             - "messages": List of all messages exchanged during the LLM's run.
             - "last_message": The last message exchanged during the LLM's run.
         """
+        # `messages` is intentionally omitted from the signature so the framework can treat it as required
+        # or optional depending on init configuration. See __init__ for details.
+        messages = kwargs.pop("messages", None)
         return await super(LLM, self).run_async(  # noqa: UP008
             messages=messages or [],
             streaming_callback=streaming_callback,

releasenotes/notes/fix-llm-comp-dynamic-inputs-1edfd14d341b8a8b.yaml

@@ -0,0 +1,23 @@
+---
+upgrade:
+  - |
+    ``LLM.run`` and ``LLM.run_async`` no longer accept ``messages`` and ``streaming_callback`` as positional
+    arguments — they must now be passed as keyword arguments. Update any direct calls accordingly:
+
+    .. code:: python
+
+      # Before
+      llm.run([message], my_callback)
+
+      # After
+      llm.run(messages=[message], streaming_callback=my_callback)
+
+enhancements:
+  - |
+    ``LLM`` now supports two usage modes:
+
+    1. **Template-variable mode**: provide a ``user_prompt`` with Jinja2 variables (e.g. ``{{ query }}``).
+       Those variables become pipeline inputs and ``messages`` is optional. The rendered ``user_prompt``
+       is always appended after any ``messages`` provided at runtime.
+    2. **Pass-through mode**: omit ``user_prompt`` or provide one with no template variables. ``messages``
+       becomes a required input, allowing a fully-constructed list of ``ChatMessage``s to be passed from upstream.

test/components/generators/chat/test_llm.py

@@ -3,22 +3,30 @@
 # SPDX-License-Identifier: Apache-2.0
 
 from typing import Any
+from unittest.mock import MagicMock
 
 import pytest
 
 from haystack import Document, Pipeline, component
 from haystack.components.agents.agent import Agent
 from haystack.components.generators.chat import LLM
 from haystack.components.generators.chat.openai import OpenAIChatGenerator
+from haystack.components.joiners.branch import BranchJoiner
 from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
-from haystack.core.component.types import OutputSocket
+from haystack.components.routers.conditional_router import ConditionalRouter
+from haystack.core.component.types import InputSocket, OutputSocket
 from haystack.dataclasses import ChatMessage
 from haystack.dataclasses.chat_message import ChatRole
+from haystack.dataclasses.streaming_chunk import StreamingChunk
 from haystack.document_stores.in_memory import InMemoryDocumentStore
 from haystack.tools import Tool
 from haystack.tools.toolset import Toolset
 
 
+def sync_streaming_callback(chunk: StreamingChunk) -> None:
+    pass
+
+
 @component
 class MockChatGeneratorWithTools:
     """A mock chat generator that accepts a tools parameter."""
@@ -93,12 +101,19 @@ def test_detects_tools_support(self):
             llm = LLM(chat_generator=MockChatGeneratorWithTools(), user_prompt=self.USER_PROMPT)
             assert llm._chat_generator_supports_tools is True
 
-        def test_raises_if_user_prompt_has_no_variables(self):
-            with pytest.raises(ValueError, match="at least one template variable"):
-                LLM(
-                    chat_generator=MockChatGenerator(),
-                    user_prompt='{% message role="user" %}Hello world{% endmessage %}',
-                )
+        def test_messages_required_when_no_prompt_variables(self):
+            llm = LLM(
+                chat_generator=MockChatGenerator(), user_prompt='{% message role="user" %}Hello world{% endmessage %}'
+            )
+            messages_socket = llm.__haystack_input__._sockets_dict["messages"]
+            assert isinstance(messages_socket, InputSocket)
+            assert messages_socket.is_mandatory
+
+        def test_messages_optional_when_prompt_has_variables(self):
+            llm = LLM(chat_generator=MockChatGenerator(), user_prompt=self.USER_PROMPT)
+            messages_socket = llm.__haystack_input__._sockets_dict["messages"]
+            assert isinstance(messages_socket, InputSocket)
+            assert not messages_socket.is_mandatory
 
         def test_raises_if_required_variables_empty(self):
             with pytest.raises(ValueError, match="required_variables must not be empty"):
@@ -195,6 +210,31 @@ def test_roundtrip(self, monkeypatch):
             assert restored.system_prompt == original.system_prompt
             assert restored.tools == []
 
+    class TestRun:
+        USER_PROMPT = '{% message role="user" %}{{ query }}{% endmessage %}'
+
+        def test_run_accepts_messages_via_kwargs(self):
+            llm = LLM(chat_generator=MockChatGenerator(), user_prompt=self.USER_PROMPT)
+            prior_message = ChatMessage.from_user("Some prior context")
+            result = llm.run(query="What is 2+2?", messages=[prior_message])
+            assert result["last_message"].text == "Sync reply"
+            assert prior_message in result["messages"]
+
+        def test_run_without_messages(self):
+            llm = LLM(chat_generator=MockChatGenerator(), user_prompt=self.USER_PROMPT)
+            result = llm.run(query="What is 2+2?")
+            assert result["last_message"].text == "Sync reply"
+            user_messages = [m for m in result["messages"] if m.is_from(ChatRole.USER)]
+            assert any("What is 2+2?" in m.text for m in user_messages)
+
+        @pytest.mark.asyncio
+        async def test_run_async_accepts_messages_via_kwargs(self):
+            llm = LLM(chat_generator=MockChatGenerator(), user_prompt=self.USER_PROMPT)
+            prior_message = ChatMessage.from_user("Some prior context")
+            result = await llm.run_async(query="What is 2+2?", messages=[prior_message])
+            assert result["last_message"].text == "Async reply"
+            assert prior_message in result["messages"]
+
     class TestPipelineIntegration:
         @pytest.fixture()
         def document_store_with_docs(self):
@@ -250,3 +290,60 @@ def test_rag_pipeline(self, document_store_with_docs):
 
             assert llm_output["last_message"].is_from(ChatRole.ASSISTANT)
             assert llm_output["last_message"].text == "Sync reply"
+
+
+class TestLLMNotTriggeredByInjectedInput:
+    """
+    Regression guard for the optional-messages scheduling hazard described in
+    https://github.com/deepset-ai/haystack/issues/11109.
+
+    When `user_prompt` contains template variables, `messages` is optional on the LLM.
+    An optional input with `sender=None` (i.e., injected directly via `pipeline.run`)
+    would flip `has_user_input()` to True and incorrectly trigger the component even
+    when its required inputs (e.g. `query`) never arrive.
+    """
+
+    def test_llm_not_triggered_by_injected_streaming_callback(self):
+
+        @component
+        class Planner:
+            @component.output_types(messages=list[ChatMessage], last_role=str)
+            def run(self) -> dict:
+                return {"messages": [ChatMessage.from_user("hello")], "last_role": "assistant"}
+
+        chat_generator = MockChatGenerator()
+        llm = LLM(chat_generator=chat_generator)
+        chat_generator.run = MagicMock(return_value={"replies": [ChatMessage.from_assistant("x")]})
+
+        router = ConditionalRouter(
+            routes=[
+                {
+                    "condition": "{{ last_role == 'tool' }}",
+                    "output": "{{ messages }}",
+                    "output_name": "processing",
+                    "output_type": list[ChatMessage],
+                },
+                {
+                    "condition": "{{ True }}",
+                    "output": "{{ messages }}",
+                    "output_name": "planning",
+                    "output_type": list[ChatMessage],
+                },
+            ],
+            unsafe=True,
+        )
+
+        pipeline = Pipeline()
+        pipeline.add_component("planner", Planner())
+        pipeline.add_component("router", router)
+        pipeline.add_component("branch_joiner", BranchJoiner(type_=list[ChatMessage]))
+        pipeline.add_component("llm", llm)
+        pipeline.connect("planner.messages", "router.messages")
+        pipeline.connect("planner.last_role", "router.last_role")
+        pipeline.connect("router.processing", "branch_joiner.value")
+        pipeline.connect("branch_joiner.value", "llm.messages")
+
+        result = pipeline.run(data={"llm": {"streaming_callback": sync_streaming_callback}})
+
+        assert "llm" not in result
+        chat_generator.run.assert_not_called()