langfuse-rb 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ba92036fbe7b63b8355a113e44ff3f62cfcb11817ae3b3c1c444756af55ebf84
-  data.tar.gz: 44097d4d441ad6d2d8780a95cb836d0368ed0b772f16036e301ece7e018df0a1
+  metadata.gz: 1eedf02269727792fdb13a343429d2108556cc4c7df52dea9e2c638a011409a0
+  data.tar.gz: 0130f17065fa3e4233090e858a2699105d9be48dce85d6765b0c3ee394c88bff
 SHA512:
-  metadata.gz: 6e8880c58683dc7ff719f0c966515841e9a3e3df024f88175297090949a6befaddf23528b24a65d3825fa40e33118348087c0dbe5312543c16bfef65856eaf12
-  data.tar.gz: a82f8be469125e99355c5b6a1bd747a1f2e395dd6e0eb098f8319a0976419dfd60087c6252e26c2570db15994ed084d3156069019541c3b32acc7f1827c92792
+  metadata.gz: 036b34ce7908114bdad51bf895c5f50159f005bbf53f3256a347dc7a6c813d9c49d18c9f7491dc42c8771d66fb6b509ae1441af6812d575ff45b80fe4e73ce6e
+  data.tar.gz: c4cf129fd0260c35f91e75797903d29e16d74b0bf543a89d9f566201a69e08eaf6245fc9d117e5f2f0e3bad5673cfee5cd54e0802d46a53809ab9c5ea825f172

data/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-04-28
+
+### Added
+- Expose `type`, `commit_message`, and `resolution_graph` metadata on text and chat prompt clients (#87)
+
+### Fixed
+- Preserve and compile chat prompt message placeholders in parity with Langfuse Python and JS SDKs (#86)
+- Preserve raw prompt compile variables instead of HTML-escaping JSON, XML, and HTML-like values (#85)
+- Suppress prompt name/version attribution on fallback prompt clients so fallback output is not reported as prompt version 0 (#84)
+
+### Documentation
+- Link to upstream Langfuse agent skills and refresh README header image (#81, #83)
+
 ## [0.8.0] - 2026-04-24
 
 ### Added
@@ -100,7 +113,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Migrated from legacy ingestion API to OTLP endpoint
 - Removed `tracing_enabled` configuration flag (#2)
 
-[Unreleased]: https://github.com/simplepractice/langfuse-rb/compare/v0.8.0...HEAD
+[Unreleased]: https://github.com/simplepractice/langfuse-rb/compare/v0.9.0...HEAD
+[0.9.0]: https://github.com/simplepractice/langfuse-rb/compare/v0.8.0...v0.9.0
 [0.8.0]: https://github.com/simplepractice/langfuse-rb/compare/v0.7.0...v0.8.0
 [0.7.0]: https://github.com/simplepractice/langfuse-rb/compare/v0.6.0...v0.7.0
 [0.6.0]: https://github.com/simplepractice/langfuse-rb/compare/v0.5.0...v0.6.0

data/README.md

@@ -1,4 +1,5 @@
-![header](https://camo.githubusercontent.com/26d19b945bc752101b4aca468e07b118a44af07340db79af29f7df95505f2cea/68747470733a2f2f6c616e67667573652e636f6d2f6c616e67667573655f6c6f676f5f77686974652e706e67)
+<img width="2255" height="527" alt="langfuse-wordart" src="https://github.com/user-attachments/assets/59422d0a-6ecb-4e5f-a21c-cae955b5ce75" />
+
 
 # Langfuse Ruby SDK
 
@@ -68,6 +69,8 @@ end
 - [Tracing](docs/TRACING.md)
 - [Scoring](docs/SCORING.md)
 - [Rails Patterns](docs/RAILS.md)
+- [Agent Skills](https://github.com/langfuse/skills)
+- [Agent Skill Docs](https://langfuse.com/docs/api-and-data-platform/features/agent-skill)
 
 ## License
 

data/lib/langfuse/chat_prompt_client.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "mustache"
+require_relative "prompt_renderer"
 
 module Langfuse
   # Chat prompt client for compiling chat prompts with variable substitution
@@ -20,6 +20,8 @@ module Langfuse
   #   chat_prompt.labels    # => ["production"]
   #
   class ChatPromptClient
+    PLACEHOLDER_TYPE = "placeholder"
+
     # @return [String] Prompt name
     attr_reader :name
 
@@ -35,14 +37,24 @@ module Langfuse
     # @return [Hash] Prompt configuration
     attr_reader :config
 
-    # @return [Array<Hash>] Array of message hashes with role and content
+    # @return [Array<Hash>] Array of message hashes and placeholder entries
     attr_reader :prompt
 
+    # @return [String, nil] Optional commit message for this prompt version
+    attr_reader :commit_message
+
+    # @return [Hash, nil] Optional dependency resolution graph for composed prompts
+    attr_reader :resolution_graph
+
+    # @return [Boolean] Whether this client uses caller-provided fallback content
+    attr_reader :is_fallback
+
     # Initialize a new chat prompt client
     #
     # @param prompt_data [Hash] The prompt data from the API
+    # @param is_fallback [Boolean] Whether this client wraps caller-provided fallback content
     # @raise [ArgumentError] if prompt data is invalid
-    def initialize(prompt_data)
+    def initialize(prompt_data, is_fallback: false)
       validate_prompt_data!(prompt_data)
 
       @name = prompt_data["name"]
@@ -51,16 +63,27 @@ module Langfuse
       @labels = prompt_data["labels"] || []
       @tags = prompt_data["tags"] || []
       @config = prompt_data["config"] || {}
+      @commit_message = prompt_data["commitMessage"]
+      @resolution_graph = prompt_data["resolutionGraph"]
+      @is_fallback = is_fallback
     end
 
-    # Compile the chat prompt with variable substitution
+    # @return [String] Prompt type ("chat")
+    def type
+      "chat"
+    end
+
+    # Compile the chat prompt with variable substitution and message placeholders
     #
     # Returns an array of message hashes with roles and compiled content.
-    # Each message in the prompt will have its content compiled with the
-    # provided variables using Mustache templating.
+    # Placeholder entries are resolved from keyword arguments: arrays are
+    # expanded, empty arrays are skipped, unresolved placeholders stay in the
+    # output, and malformed values raise before invalid messages are sent to
+    # an LLM provider.
     #
-    # @param kwargs [Hash] Variables to substitute in message templates (as keyword arguments)
-    # @return [Array<Hash>] Array of compiled messages with :role and :content keys
+    # @param kwargs [Hash] Variables and placeholder values to compile
+    # @return [Array<Hash>] Array of compiled messages and unresolved placeholders
+    # @raise [ArgumentError] if a placeholder value is malformed
     #
     # @example
     #   chat_prompt.compile(name: "Alice", topic: "Ruby")
@@ -69,9 +92,18 @@ module Langfuse
     #   #   { role: :user, content: "Hello Alice, let's discuss Ruby!" }
     #   # ]
     def compile(**kwargs)
-      prompt.map do |message|
-        compile_message(message, kwargs)
+      unresolved = []
+      compiled = []
+      prompt.each do |message|
+        normalized = symbolize_keys(message)
+        if normalized[:type].to_s == PLACEHOLDER_TYPE
+          append_placeholder(normalized, kwargs, compiled, unresolved)
+        else
+          compiled << compile_message(normalized, kwargs)
+        end
       end
+      warn_unresolved(unresolved)
+      compiled
     end
 
     private
@@ -88,19 +120,102 @@ module Langfuse
       raise ArgumentError, "prompt must be an Array" unless prompt_data["prompt"].is_a?(Array)
     end
 
-    # Compile a single message with variable substitution
+    # Compile a single role/content message with variable substitution
     #
-    # @param message [Hash] The message with role and content
+    # @param normalized [Hash] Symbolized message hash
     # @param variables [Hash] Variables to substitute
     # @return [Hash] Compiled message with :role and :content as symbols
-    def compile_message(message, variables)
-      content = message["content"] || ""
-      compiled_content = variables.empty? ? content : Mustache.render(content, variables)
-
-      {
-        role: normalize_role(message["role"]),
-        content: compiled_content
-      }
+    def compile_message(normalized, variables)
+      normalized.except(:type).merge(
+        role: normalize_role(normalized[:role]),
+        content: render(normalized[:content] || "", variables)
+      )
+    end
+
+    # @api private
+    def append_placeholder(message, variables, compiled, unresolved)
+      name = message[:name].to_s
+      found, value = lookup_placeholder(variables, name)
+      return append_unresolved(name, compiled, unresolved) unless found
+
+      expand_placeholder(name, value, variables, compiled)
+    end
+
+    # @api private
+    def append_unresolved(name, compiled, unresolved)
+      unresolved << name
+      compiled << { type: PLACEHOLDER_TYPE, name: name }
+    end
+
+    # @api private
+    def expand_placeholder(name, value, variables, compiled)
+      return if value.is_a?(Array) && value.empty?
+
+      unless value.is_a?(Array)
+        raise ArgumentError, "Placeholder '#{name}' must contain an array of chat message hashes, got #{value.class}."
+      end
+
+      value.each { |entry| compiled << placeholder_message(entry, variables, name) }
+    end
+
+    # @api private
+    def lookup_placeholder(variables, name)
+      return [true, variables[name.to_sym]] if variables.key?(name.to_sym)
+      return [true, variables[name]] if variables.key?(name)
+
+      [false, nil]
+    end
+
+    # @api private
+    def placeholder_message(message, variables, name)
+      unless message.is_a?(Hash)
+        raise ArgumentError,
+              "Placeholder '#{name}' must contain an array of chat message hashes with role and content fields."
+      end
+
+      normalized = symbolize_keys(message)
+      unless valid_placeholder_message?(normalized)
+        raise ArgumentError,
+              "Placeholder '#{name}' must contain an array of chat message hashes with role and content fields."
+      end
+
+      normalized.merge(
+        role: normalize_role(normalized[:role]),
+        content: render(normalized[:content] || "", variables)
+      )
+    end
+
+    # @api private
+    def render(content, variables)
+      variables.empty? ? content : PromptRenderer.render(content, variables)
+    end
+
+    # @api private
+    def valid_placeholder_message?(message)
+      message.is_a?(Hash) &&
+        message.key?(:role) &&
+        !message[:role].to_s.empty? &&
+        message.key?(:content)
+    end
+
+    # @api private
+    def warn_unresolved(names)
+      return if names.empty?
+
+      unresolved_names = names.uniq.sort
+      message = "Placeholders #{unresolved_names.inspect} have not been resolved. " \
+                "Pass them as keyword arguments to compile()."
+      warn_msg(message)
+    end
+
+    # @api private
+    def warn_msg(message)
+      Langfuse.configuration.logger.warn("Langfuse: #{message}")
+    end
+
+    # @api private
+    def symbolize_keys(hash)
+      hash.transform_keys(&:to_sym)
     end
 
     # Normalize role to symbol

data/lib/langfuse/client.rb

@@ -823,9 +823,9 @@ module Langfuse
 
       case type
       when :text
-        TextPromptClient.new(prompt_data)
+        TextPromptClient.new(prompt_data, is_fallback: true)
       when :chat
-        ChatPromptClient.new(prompt_data)
+        ChatPromptClient.new(prompt_data, is_fallback: true)
       end
     end
 
@@ -856,7 +856,8 @@ module Langfuse
 
     # Normalize prompt content for API request
     #
-    # Converts Ruby symbol keys to string keys for chat messages
+    # Converts Ruby symbol keys to string keys for chat messages and preserves
+    # Langfuse message placeholder entries.
     #
     # @param prompt [String, Array] The prompt content
     # @param type [Symbol] The prompt type
@@ -866,18 +867,28 @@ module Langfuse
 
       # Normalize chat messages to use string keys
       prompt.map do |message|
-        # Convert all keys to symbols first, then extract
-        normalized = message.transform_keys do |k|
-          k.to_sym
-        rescue StandardError
-          k
-        end
-        {
-          "role" => normalized[:role]&.to_s,
-          "content" => normalized[:content]
-        }
+        normalized = message.transform_keys(&:to_s)
+        next placeholder_prompt_content(normalized) if normalized["type"] == ChatPromptClient::PLACEHOLDER_TYPE
+
+        normalize_chat_message_content(normalized)
       end
     end
+
+    # @api private
+    def placeholder_prompt_content(message)
+      {
+        "type" => ChatPromptClient::PLACEHOLDER_TYPE,
+        "name" => message["name"].to_s
+      }
+    end
+
+    # @api private
+    def normalize_chat_message_content(message)
+      message.merge(
+        "role" => message["role"]&.to_s,
+        "content" => message["content"]
+      )
+    end
   end
   # rubocop:enable Metrics/ClassLength
 end

data/lib/langfuse/otel_attributes.rb

@@ -302,11 +302,9 @@ module Langfuse
     # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
     def self.add_prompt_attributes(otel_attributes, prompt)
       return unless prompt
+      return if fallback_prompt?(prompt)
 
-      # Handle hash-like prompts
       if prompt.is_a?(Hash) || prompt.respond_to?(:[])
-        return if prompt[:is_fallback] || prompt["is_fallback"]
-
         otel_attributes[OBSERVATION_PROMPT_NAME] = prompt[:name] || prompt["name"]
         otel_attributes[OBSERVATION_PROMPT_VERSION] = prompt[:version] || prompt["version"]
       # Handle objects with name/version methods (already converted in Trace#generation)
@@ -315,6 +313,16 @@ module Langfuse
         otel_attributes[OBSERVATION_PROMPT_VERSION] = prompt.version
       end
     end
+    # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+    # @api private
+    def self.fallback_prompt?(prompt)
+      return true if prompt.respond_to?(:is_fallback) && prompt.is_fallback
+      return false unless prompt.is_a?(Hash)
+
+      !!get_hash_value(prompt, :is_fallback)
+    end
+    private_class_method :fallback_prompt?
   end
-  # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/ModuleLength
+  # rubocop:enable Metrics/ModuleLength
 end

data/lib/langfuse/prompt_renderer.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "mustache"
+
+module Langfuse
+  # Renders prompt templates with Langfuse SDK-compatible variable semantics.
+  #
+  # @api private
+  class PromptRenderer < Mustache
+    # Langfuse variables are model input, not browser output; JS/Python SDKs substitute raw values.
+    #
+    # @param value [Object] Value to insert into the prompt
+    # @return [String] Raw string representation
+    def escape(value)
+      value.to_s
+    end
+  end
+end

data/lib/langfuse/text_prompt_client.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "mustache"
+require_relative "prompt_renderer"
 
 module Langfuse
   # Text prompt client for compiling text prompts with variable substitution
@@ -38,11 +38,21 @@ module Langfuse
     # @return [String] Raw prompt template string
     attr_reader :prompt
 
+    # @return [String, nil] Optional commit message for this prompt version
+    attr_reader :commit_message
+
+    # @return [Hash, nil] Optional dependency resolution graph for composed prompts
+    attr_reader :resolution_graph
+
+    # @return [Boolean] Whether this client uses caller-provided fallback content
+    attr_reader :is_fallback
+
     # Initialize a new text prompt client
     #
     # @param prompt_data [Hash] The prompt data from the API
+    # @param is_fallback [Boolean] Whether this client wraps caller-provided fallback content
     # @raise [ArgumentError] if prompt data is invalid
-    def initialize(prompt_data)
+    def initialize(prompt_data, is_fallback: false)
       validate_prompt_data!(prompt_data)
 
       @name = prompt_data["name"]
@@ -51,6 +61,14 @@ module Langfuse
       @labels = prompt_data["labels"] || []
       @tags = prompt_data["tags"] || []
       @config = prompt_data["config"] || {}
+      @commit_message = prompt_data["commitMessage"]
+      @resolution_graph = prompt_data["resolutionGraph"]
+      @is_fallback = is_fallback
+    end
+
+    # @return [String] Prompt type ("text")
+    def type
+      "text"
     end
 
     # Compile the prompt with variable substitution
@@ -64,7 +82,7 @@ module Langfuse
     def compile(**kwargs)
       return prompt if kwargs.empty?
 
-      Mustache.render(prompt, kwargs)
+      PromptRenderer.render(prompt, kwargs)
     end
 
     private

data/lib/langfuse/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Langfuse
-  VERSION = "0.8.0"
+  VERSION = "0.9.0"
 end

data/lib/langfuse.rb

@@ -54,6 +54,7 @@ require_relative "langfuse/span_processor"
 require_relative "langfuse/observations"
 require_relative "langfuse/trace_id"
 require_relative "langfuse/score_client"
+require_relative "langfuse/prompt_renderer"
 require_relative "langfuse/text_prompt_client"
 require_relative "langfuse/chat_prompt_client"
 require_relative "langfuse/timestamp_parser"

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: langfuse-rb
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - SimplePractice
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-24 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -177,6 +176,7 @@ files:
 - lib/langfuse/otel_attributes.rb
 - lib/langfuse/otel_setup.rb
 - lib/langfuse/prompt_cache.rb
+- lib/langfuse/prompt_renderer.rb
 - lib/langfuse/propagation.rb
 - lib/langfuse/rails_cache_adapter.rb
 - lib/langfuse/sampling.rb
@@ -198,7 +198,6 @@ metadata:
   source_code_uri: https://github.com/simplepractice/langfuse-rb
   changelog_uri: https://github.com/simplepractice/langfuse-rb/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -213,8 +212,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.1
-signing_key:
+rubygems_version: 4.0.8
 specification_version: 4
 summary: Ruby SDK for Langfuse - LLM observability and prompt management
 test_files: []