fix(langchain): silence intentional placeholder warnings

[fengjikui]

Summary

• Keep unresolved-placeholder warnings for direct ChatPromptClient.compile() calls.
• Stop emitting that warning from get_langchain_prompt() when unresolved placeholders are intentionally returned as LangChain MessagesPlaceholder objects.
• Add regression coverage to ensure the LangChain hand-off path stays quiet while preserving the existing placeholder output.

Fixes #1667.

Verification

• uv run --frozen pytest tests/unit/test_prompt_compilation.py::TestLangchainPromptCompilation::test_get_langchain_prompt_with_unresolved_placeholders -q
• uv run --frozen pytest tests/unit/test_prompt_compilation.py -q
• uv run --frozen ruff check langfuse/model.py tests/unit/test_prompt_compilation.py
• uv run --frozen ruff format --check langfuse/model.py tests/unit/test_prompt_compilation.py
• uv run --frozen mypy langfuse --no-error-summary
• git diff --check

I also tried uv run --frozen pytest tests/e2e/test_prompt.py::test_warning_on_unresolved_placeholders -q, but the local run requires Langfuse server credentials/API setup and failed before the assertion path with Langfuse client initialized without public_key.

Greptile Summary

This PR fixes spurious langfuse_logger.warning calls that fire during get_langchain_prompt() when unresolved placeholders are intentionally left for LangChain to handle as MessagesPlaceholder objects.

• compile() is refactored into a thin wrapper around a new private _compile(warn_on_unresolved_placeholders: bool) method; the public API is unchanged and still warns by default.
• get_langchain_prompt() now calls _compile(warn_on_unresolved_placeholders=False), suppressing the warning only on the LangChain hand-off path.
• A regression test asserts that langfuse_logger.warning is never called during get_langchain_prompt() when a placeholder is intentionally left unresolved.

Confidence Score: 4/5

Safe to merge; the behavioural change is narrow and well-tested.

The refactor correctly isolates warning behaviour behind a flag, public compile() is unchanged, and a targeted regression test covers the silent path. The only finding is a style-level import placed inside a test method body rather than at the module top.

No files require special attention beyond the minor import placement in the test.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["compile(kwargs)"] -->|"warn=True"| B["_compile()"]
    C["get_langchain_prompt(kwargs)"] -->|"warn=False"| B

    B --> D{placeholder resolved?}
    D -- Yes --> E[expand messages]
    D -- No --> F[keep as placeholder dict]
    F --> G{warn flag set?}
    G -- Yes --> H["langfuse_logger.warning()"]
    G -- No --> I[silent]

    A --> L[return raw dicts]
    C --> M["convert to LangChain tuples / MessagesPlaceholder"]

Loading

Prompt To Fix All With AI

Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 1
tests/unit/test_prompt_compilation.py:805-810
The `patch` import is placed inside the test method body. The project rule requires imports to be at the top of the module. The two pre-existing local imports (`Prompt_Chat`, `ChatPromptClient`) also violate this rule, but this PR actively adds a third one (`from unittest.mock import patch`) and is a good opportunity to move at least the new import to the top-level block.

```suggestion
    def test_get_langchain_prompt_with_unresolved_placeholders(self):
        """Test that unresolved placeholders become MessagesPlaceholder objects."""
        from langfuse.api import Prompt_Chat
        from langfuse.model import ChatPromptClient
```

_{Reviews (1): Last reviewed commit: "fix(langchain): silence intentional plac..." | Re-trigger Greptile}

Context used:

• Rule used - Move imports to the top of the module instead of p... (source)

Learned From
langfuse/langfuse-python#1387

[claude]

Claude Code Review

This pull request is from a fork — automated review is disabled. A repository maintainer can comment @claude review to run a one-time review.

[CLAassistant]

All committers have signed the CLA.

[Kairick]

Ran into the same warning and worked through this patch before finding this PR — the approach looks right to me. Two notes from that, both small:

1. The flag shares a namespace with template variables.

_compile(self, *, warn_on_unresolved_placeholders: bool, **kwargs) means a prompt that happens to contain a {{warn_on_unresolved_placeholders}} variable can no longer be compiled: the value binds to the keyword-only parameter instead of landing in kwargs, so the variable is left unsubstituted (and a bool reaches a code path expecting a string).

It's an unlikely name, but public compile(**kwargs) currently promises that every keyword is prompt data, and this is the one place that promise gets an exception. Passing the mapping explicitly keeps it intact:

def compile(self, **kwargs: Union[str, Any]) -> ...:
    return self._compile(kwargs, warn_on_unresolved_placeholders=True)

def _compile(
    self,
    kwargs: Dict[str, Any],
    *,
    warn_on_unresolved_placeholders: bool,
) -> ...:

and at the call site:

compiled_messages = self._compile(kwargs, warn_on_unresolved_placeholders=False)

2. Two regression tests worth adding.

The current test covers the quiet path. The two behaviours the issue explicitly asks to preserve aren't pinned yet, so a later refactor could silence them without failing anything:

def test_compile_still_warns_on_unresolved_placeholders(self, caplog):
    with caplog.at_level(logging.WARNING, logger="langfuse"):
        prompt_client.compile()
    assert "Placeholders ['chat_history'] have not been resolved" in caplog.text


def test_get_langchain_prompt_still_warns_on_malformed_placeholder(self, caplog):
    with caplog.at_level(logging.WARNING, logger="langfuse"):
        prompt_client.get_langchain_prompt(chat_history="not-a-list")
    assert "must contain a list of chat messages" in caplog.text

caplog also avoids patching the shared logger object, so it won't mask a second warning firing in the same call.

Happy to hand over the full test bodies if useful.