Principle:Langfuse Langfuse Prompt Compilation with Variables
| Knowledge Sources | |
|---|---|
| Domains | Prompt Management, Template Compilation, LLM Integration |
| Last Updated | 2026-02-14 00:00 GMT |
Overview
Prompt Compilation with Variables is the final transformation step that converts a retrieved prompt template into a concrete, LLM-ready message array by expanding message-level placeholders and substituting text-level variables with user-supplied values.
Description
After a prompt template has been retrieved and its dependency graph resolved, the prompt still contains two kinds of dynamic slots that must be filled before it can be sent to an LLM:
- Text variables: Denoted by {{variableName}} syntax within message content strings. These are simple string substitutions where each variable name is replaced with a corresponding string value. Variables support optional whitespace around the name (e.g., {{ name }} is equivalent to {{name}}).
- Message placeholders: Entire message slots in a chat prompt that are replaced with arrays of messages at compilation time. A placeholder message has a special type ("placeholder") and a name, and is expanded into zero or more concrete chat messages provided by the caller.
These two mechanisms operate at different levels of granularity:
- Text variables operate within a message, performing string interpolation on the content field.
- Placeholders operate at the message level, replacing an entire slot in the conversation sequence with one or more messages.
This two-tier approach provides maximum flexibility: text variables handle the common case of injecting dynamic data (user names, context snippets, dates) into fixed message structures, while placeholders handle dynamic conversation structure (injecting few-shot examples, tool results, or variable-length context windows).
Usage
Use Prompt Compilation with Variables when:
- A retrieved chat prompt template contains {{variable}} patterns that must be filled with runtime data before sending to an LLM.
- A chat prompt template includes placeholder message slots that should be expanded with arrays of concrete messages (e.g., few-shot examples, conversation history, tool call results).
- You need to separate the static structure of a prompt (managed by prompt engineers) from the dynamic content (provided at runtime by application code).
Theoretical Basis
Compilation Pipeline
The compilation of chat messages proceeds in two sequential phases:
FUNCTION compileChatMessages(messages, placeholderValues, textVariables):
// Phase 1: Expand message-level placeholders
expandedMessages = []
FOR EACH message IN messages:
IF message.type == "placeholder":
replacementArray = placeholderValues[message.name]
IF replacementArray IS NULL:
RAISE error("Missing value for placeholder: " + message.name)
IF NOT isArray(replacementArray):
RAISE error("Placeholder value must be an array")
FOR EACH replacement IN replacementArray:
IF NOT isObject(replacement):
RAISE error("Each placeholder item must be an object")
expandedMessages.APPEND(replacement)
ELSE:
expandedMessages.APPEND(message)
// Phase 2: Substitute text variables within message content
IF textVariables IS EMPTY:
RETURN expandedMessages
result = []
FOR EACH message IN expandedMessages:
IF message.content IS NOT A STRING:
result.APPEND(message) // Skip non-string content
CONTINUE
newContent = message.content
FOR EACH (varName, varValue) IN textVariables:
pattern = REGEX("{{\\s*" + varName + "\\s*}}")
newContent = REPLACE_ALL(newContent, pattern, varValue)
result.APPEND({ ...message, content: newContent })
RETURN result
Placeholder Detection
A message is identified as a placeholder through its type field:
FUNCTION isPlaceholder(message):
RETURN "type" IN message AND message.type == "placeholder"
Placeholder names must match the pattern: starts with a letter, followed by alphanumeric characters or underscores. This restriction ensures placeholder names are valid identifiers and avoids collisions with other message properties.
Variable Extraction
Variables are extracted from prompt content using the mustache-style double-brace pattern:
MUSTACHE_PATTERN = /\{\{(.*?)\}\}/g
FUNCTION extractVariables(content):
matches = findAllGroups(content, MUSTACHE_PATTERN)
validMatches = FILTER(matches, isValidVariableName)
RETURN DEDUPLICATE(validMatches)
Variable-Placeholder Disjointness
At prompt creation time, the system enforces that variable names and placeholder names do not overlap. This prevents ambiguity during compilation:
FUNCTION validateNamingDisjointness(chatMessages):
placeholderNames = extractPlaceholderNames(chatMessages)
variableNames = extractVariablesFromAllMessages(chatMessages)
conflicts = INTERSECTION(placeholderNames, variableNames)
IF conflicts IS NOT EMPTY:
RAISE error("Variables and placeholders must be unique: " + conflicts)
Key properties:
- Order preservation: Placeholders are expanded in-place, maintaining the sequential order of the conversation. A placeholder at position 3 in the template expands to messages at positions 3, 4, 5, etc., shifting subsequent template messages accordingly.
- Type flexibility: Placeholder expansion accepts arbitrary objects as replacement messages. This supports ChatML with various role types (system, user, assistant, tool) and vendor-specific message formats.
- Idempotent variable substitution: If a variable is referenced multiple times in a single message content string, all occurrences are replaced. Variables not present in the textVariables map remain as literal {{varName}} text.
- Whitespace tolerance: The variable pattern {{ name }} with spaces is treated identically to {{name}} without spaces, improving authoring ergonomics.
- Non-string content passthrough: Messages with non-string content (such as arrays or objects for multimodal inputs) are passed through without variable substitution, preventing accidental corruption of structured content.