feat(prompts): expose template variables

[kxzk]

TL;DR

Text and chat prompt clients expose the unique variables referenced by their Mustache templates.

Why

Callers need the variable list before compilation so they can validate inputs and build prompt-aware tools. The work tracks the prompt variable issue.

Checklist

• Has label
• Has linked issue
• Tests added for new behavior
• Docs updated (if user-facing)

Closes #

Note

Kade's words:

Summary

Text and chat prompt clients now return unique referenced variable names through #variables. The result keeps source order and full dotted paths. It includes section names and variables inside nested sections. Chat prompts combine variables across message templates and exclude message placeholders.

The extractor reads Mustache parser tokens. It recognizes escaped tags, unescaped tags, sections, inverted sections, and comments according to the template grammar. Existing prompt compilation behavior stays unchanged.

Change diagram

flowchart LR
    accTitle: Prompt variable extraction
    accDescr: Text and chat templates use the Mustache parser to return unique variable paths in source order.
    T["Text template"] --> P["Parse Mustache tokens"]
    C["Chat message templates"] --> P
    P --> X["Collect full variable paths"]
    X --> U["Keep first occurrence"]
    U --> V["Return variables"]

Loading

Verification

I ran the complete RSpec suite locally. All 1,575 examples passed. Line coverage was 97.25%.

I ran RuboCop against 97 files. RuboCop reported no offenses.

I fetched synthetic-prompt-132908c3d42c version 1 through the Ruby SDK with the latest label. The prompt source was Return a synthetic result for {{input}}.. #variables returned ["input"], and compilation produced Return a synthetic result for sdk-cli-e2e..

The Langfuse CLI read back the same prompt name, version, type, and source template. Unit tests cover repeated variables, dotted paths, nested and inverted sections, comments, unescaped tags, invalid syntax, cross-message deduplication, and message placeholders.

I did not preview the rendered Mermaid diagram in GitHub. I reviewed the Mermaid source and syntax locally.

---

Note

Low Risk
Additive read-only API on prompt clients with no changes to compilation; covered by new specs.

Overview
Text and chat prompt clients now expose #variables, returning unique Mustache variable names in source order (dotted paths, section names, and nested-section scoping).

A new Langfuse::PromptVariables helper walks Mustache parser tokens to collect tags and sections; chat prompts aggregate across message templates and skip message placeholder entries. Invalid template syntax surfaces as Mustache::Parser::SyntaxError. #compile behavior is unchanged.

^{Reviewed by Cursor Bugbot for commit c18a05b. Bugbot is set up for automated code reviews on this repo. Configure here.}

[linear-code]

AAI-392

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit a746f13. Configure here.}