messagesplaceholder object returned

Author: nimarb

langfuse/model.py

@@ -302,9 +302,8 @@ def get_langchain_prompt(self, **kwargs) -> str:
 class ChatPromptClient(BasePromptClient):
     def __init__(self, prompt: Prompt_Chat, is_fallback: bool = False):
         super().__init__(prompt, is_fallback)
-
-        # Convert and store the prompt directly
         self.prompt = []
+
         for p in prompt.prompt:
             # Handle objects with attributes (normal case)
             if hasattr(p, "type") and hasattr(p, "name") and p.type == "placeholder":
@@ -340,15 +339,17 @@ def __init__(self, prompt: Prompt_Chat, is_fallback: bool = False):
                         ),
                     )
 
-    def compile(self, **kwargs) -> List[ChatMessageDict]:
+    def compile(
+        self, **kwargs
+    ) -> Sequence[Union[ChatMessageDict, ChatMessageWithPlaceholdersDict_Placeholder]]:
         """Compile the prompt with placeholders and variables.
 
         Args:
             **kwargs: Can contain both placeholder values (list of chat messages) and variable values.
                      Placeholders are resolved first, then variables are substituted.
 
         Returns:
-            List of compiled chat messages as plain dictionaries.
+            List of compiled chat messages as plain dictionaries, with unresolved placeholders kept as-is.
         """
         compiled_messages = []
         unresolved_placeholders = []
@@ -363,47 +364,48 @@ def compile(self, **kwargs) -> List[ChatMessageDict]:
                             chat_message["content"],
                             kwargs,
                         ),
-                    }
+                    },
                 )
             elif chat_message["type"] == "placeholder":
-                # Check if placeholder value is provided in kwargs
                 placeholder_name = chat_message["name"]
                 if placeholder_name in kwargs:
                     placeholder_value = kwargs[placeholder_name]
                     if isinstance(placeholder_value, list):
-                        # Add all messages from the placeholder
                         for msg in placeholder_value:
                             if (
                                 isinstance(msg, dict)
                                 and "role" in msg
                                 and "content" in msg
                             ):
-                                # Compile variables in placeholder messages too
                                 compiled_messages.append(
                                     {
                                         "role": msg["role"],
                                         "content": TemplateParser.compile_template(
                                             msg["content"],
                                             kwargs,
                                         ),
-                                    }
+                                    },
                                 )
                             else:
-                                raise ValueError(
-                                    f"Placeholder '{placeholder_name}' must contain a list of chat messages with 'role' and 'content' fields"
+                                compiled_messages.append(
+                                    str(placeholder_value),
                                 )
+                                no_role_content_in_placeholder = f"Placeholder '{placeholder_name}' should contain a list of chat messages with 'role' and 'content' fields. Appended as string."
+                                langfuse_logger.warning(no_role_content_in_placeholder)
                     else:
-                        raise ValueError(
-                            f"Placeholder '{placeholder_name}' must contain a list of chat messages, got {type(placeholder_value)}"
+                        compiled_messages.append(
+                            str(placeholder_value),
                         )
+                        placeholder_not_a_list = f"Placeholder '{placeholder_name}' must contain a list of chat messages, got {type(placeholder_value)}"
+                        langfuse_logger.warning(placeholder_not_a_list)
                 else:
-                    # Placeholder not resolved - track it
+                    # Keep unresolved placeholder in the compiled messages
+                    compiled_messages.append(chat_message)
                     unresolved_placeholders.append(placeholder_name)
 
-        # Warn about unresolved placeholders
         if unresolved_placeholders:
-            warning_msg = f"Placeholders {unresolved_placeholders} have not been resolved. Pass them as keyword arguments to compile()."
-            langfuse_logger.warning(warning_msg)
+            unresolved_placeholders = f"Placeholders {unresolved_placeholders} have not been resolved. Pass them as keyword arguments to compile()."
+            langfuse_logger.warning(unresolved_placeholders)
 
         return compiled_messages
 
@@ -415,7 +417,7 @@ def variables(self) -> List[str]:
         for chat_message in self.prompt:
             if chat_message["type"] == "message":
                 variables.extend(
-                    TemplateParser.find_variable_names(chat_message["content"])
+                    TemplateParser.find_variable_names(chat_message["content"]),
                 )
         return variables
 
@@ -452,26 +454,40 @@ def get_langchain_prompt(self, **kwargs):
 
         It specifically adapts the mustache-style double curly braces {{variable}} used in Langfuse
         to the single curly brace {variable} format expected by Langchain.
+        Placeholders are filled-in from kwargs and unresolved placeholders are returned as Langchain MessagesPlaceholder.
 
         kwargs: Optional keyword arguments to precompile the template string. Variables that match
                 the provided keyword arguments will be precompiled. Remaining variables must then be
                 handled by Langchain's prompt template.
-                Can also contain placeholders (list of chat messages) which will be expanded.
+                Can also contain placeholders (list of chat messages) which will be resolved prior to variable
+                compilation.
 
         Returns:
-            List of messages in the format expected by Langchain's ChatPromptTemplate: (role, content) tuple.
+            List of messages in the format expected by Langchain's ChatPromptTemplate:
+            (role, content) tuples for regular messages or MessagesPlaceholder objects for unresolved placeholders.
         """
-        # First compile with placeholders and variables to get full message list
         compiled_messages = self.compile(**kwargs)
+        langchain_messages = []
 
-        # Then convert to Langchain format
-        return [
-            (
-                msg["role"],
-                self._get_langchain_prompt_string(msg["content"]),
-            )
-            for msg in compiled_messages
-        ]
+        for msg in compiled_messages:
+            if "type" in msg and msg["type"] == "placeholder":
+                # unresolved placeholder -> add LC MessagesPlaceholder
+                placeholder_name = msg["name"]
+                try:
+                    from langchain_core.prompts.chat import MessagesPlaceholder  # noqa: PLC0415, I001
+
+                    langchain_messages.append(
+                        MessagesPlaceholder(variable_name=placeholder_name),
+                    )
+                except ImportError as e:
+                    import_error = "langchain_core is required to use get_langchain_prompt() with unresolved placeholders."
+                    raise ImportError(import_error) from e
+            else:
+                langchain_messages.append(
+                    (msg["role"], self._get_langchain_prompt_string(msg["content"])),
+                )
+
+        return langchain_messages
 
 
 PromptClient = Union[TextPromptClient, ChatPromptClient]

tests/test_prompt.py

@@ -205,16 +205,24 @@ def test_get_prompt_with_placeholders():
 @pytest.mark.parametrize(
     ("variables", "placeholders", "expected_len", "expected_contents"),
     [
-        # 0. Variables only, no placeholders. Expect verbatim message only
-        # Compile kills not filled placeholders
+        # 0. Variables only, no placeholders. Unresolved placeholders kept in output
         (
             {"role": "helpful", "task": "coding"},
             {},
-            2,
-            ["You are a helpful assistant", "Help me with coding"],
+            3,
+            [
+                "You are a helpful assistant",
+                None,
+                "Help me with coding",
+            ],  # None = placeholder
         ),
         # 1. No variables, no placeholders. Expect verbatim message+placeholder output
-        ({}, {}, 2, ["You are a {{role}} assistant", "Help me with {{task}}"]),
+        (
+            {},
+            {},
+            3,
+            ["You are a {{role}} assistant", None, "Help me with {{task}}"],
+        ),  # None = placeholder
         # 2. Placeholders only, empty variables. Expect output with placeholders filled in
         (
             {},
@@ -257,18 +265,45 @@ def test_get_prompt_with_placeholders():
         #     2,
         #     ["You are a helpful assistant", "Help me with coding"],
         # ),
-        # 4. Unused placeholder fill ins. Expect verbatim message+placeholder output
+        # 4. Unused placeholder fill ins. Unresolved placeholders kept in output
         (
             {"role": "helpful", "task": "coding"},
             {"unused": [{"role": "user", "content": "Won't appear"}]},
-            2,
-            ["You are a helpful assistant", "Help me with coding"],
+            3,
+            [
+                "You are a helpful assistant",
+                None,
+                "Help me with coding",
+            ],  # None = placeholder
+        ),
+        # 5. Placeholder with non-list value (should log warning and create invalid dict)
+        (
+            {"role": "helpful", "task": "coding"},
+            {"examples": "not a list"},
+            3,
+            [
+                "You are a helpful assistant",
+                "{'not a list'}",  # Invalid dict becomes string when checked
+                "Help me with coding",
+            ],
+        ),
+        # 6. Placeholder with invalid message structure (should log warning and include both)
+        (
+            {"role": "helpful", "task": "coding"},
+            {"examples": ["invalid message", {"role": "user", "content": "valid message"}]},
+            4,
+            [
+                "You are a helpful assistant",
+                "{\"['invalid message', {'role': 'user', 'content': 'valid message'}]\"}",  # Invalid structure becomes string
+                "valid message",  # Valid message processed normally
+                "Help me with coding",
+            ],
         ),
     ],
 )
 def test_compile_with_placeholders(
     variables, placeholders, expected_len, expected_contents
-):
+) -> None:
     """Test compile_with_placeholders with different variable/placeholder combinations."""
     from langfuse.api.resources.prompts import Prompt_Chat
     from langfuse.model import ChatPromptClient
@@ -292,13 +327,16 @@ def test_compile_with_placeholders(
 
     assert len(result) == expected_len
     for i, expected_content in enumerate(expected_contents):
-        if "content" in result[i]:
-            assert result[i]["content"] == expected_content
-        elif "name" in result[i]:
-            # this is a placeholder
-            continue
+        if expected_content is None:
+            # This should be an unresolved placeholder
+            assert "type" in result[i] and result[i]["type"] == "placeholder"
+        elif expected_content.startswith("{") and expected_content.endswith("}"):
+            # This is an invalid dictionary that becomes a string representation
+            assert str(result[i]) == expected_content
         else:
-            raise ValueError("Unexpected item in prompt compile output")
+            # This should be a regular message
+            assert "content" in result[i]
+            assert result[i]["content"] == expected_content
 
 
 def test_warning_on_unresolved_placeholders():

tests/test_prompt_compilation.py

@@ -801,3 +801,51 @@ def test_chat_prompt_with_placeholders_langchain(self):
         assert formatted_messages[1].content == "Example: What is 2+2?"
         assert formatted_messages[2].content == "2+2 equals 4."
         assert formatted_messages[3].content == "Help me with addition."
+
+    def test_get_langchain_prompt_with_unresolved_placeholders(self):
+        """Test that unresolved placeholders become MessagesPlaceholder objects."""
+        from langfuse.api.resources.prompts import Prompt_Chat
+        from langfuse.model import ChatPromptClient
+
+        chat_messages = [
+            {"role": "system", "content": "You are a {{role}} assistant"},
+            {"type": "placeholder", "name": "examples"},
+            {"role": "user", "content": "Help me with {{task}}"},
+        ]
+
+        prompt_client = ChatPromptClient(
+            Prompt_Chat(
+                type="chat",
+                name="test_unresolved_placeholder",
+                version=1,
+                config={},
+                tags=[],
+                labels=[],
+                prompt=chat_messages,
+            ),
+        )
+
+        # Call get_langchain_prompt without resolving placeholder
+        langchain_messages = prompt_client.get_langchain_prompt(
+            role="helpful", task="coding",
+        )
+
+        # Should have 3 items: system message, MessagesPlaceholder, user message
+        assert len(langchain_messages) == 3
+
+        # First message should be the system message
+        assert langchain_messages[0] == ("system", "You are a helpful assistant")
+
+        # Second should be a MessagesPlaceholder for the unresolved placeholder
+        placeholder_msg = langchain_messages[1]
+        try:
+            from langchain_core.prompts.chat import MessagesPlaceholder
+
+            assert isinstance(placeholder_msg, MessagesPlaceholder)
+            assert placeholder_msg.variable_name == "examples"
+        except ImportError:
+            # Fallback case when langchain_core is not available
+            assert placeholder_msg == ("system", "{examples}")
+
+        # Third message should be the user message
+        assert langchain_messages[2] == ("user", "Help me with coding")