langfuse-rb 0.8.0 → 0.10.0

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

@@ -46,7 +46,8 @@ module Langfuse
         base_url: config.base_url,
         timeout: config.timeout,
         logger: config.logger,
-        cache: cache
+        cache: cache,
+        cache_observer: config.prompt_cache_observer
       )
 
       @project_id = nil
@@ -68,6 +69,7 @@ module Langfuse
     # @param label [String, nil] Optional label (e.g., "production", "latest")
     # @param fallback [String, Array, nil] Optional fallback prompt to use on error
     # @param type [Symbol, nil] Required when fallback is provided (:text or :chat)
+    # @param cache_ttl [Integer, nil] Optional TTL override for this fetch
     # @return [TextPromptClient, ChatPromptClient] The prompt client
     # @raise [ArgumentError] if both version and label are provided
     # @raise [ArgumentError] if fallback is provided without type
@@ -77,24 +79,114 @@ module Langfuse
     #
     # @example With fallback for graceful degradation
     #   prompt = client.get_prompt("greeting", fallback: "Hello {{name}}!", type: :text)
-    def get_prompt(name, version: nil, label: nil, fallback: nil, type: nil)
-      # Validate fallback usage
-      if fallback && !type
-        raise ArgumentError, "type parameter is required when fallback is provided (use :text or :chat)"
-      end
+    def get_prompt(name, version: nil, label: nil, fallback: nil, type: nil, cache_ttl: nil)
+      get_prompt_result(
+        name,
+        version: version,
+        label: label,
+        fallback: fallback,
+        type: type,
+        cache_ttl: cache_ttl
+      ).prompt
+    end
 
-      # Try to fetch from API
-      prompt_data = api_client.get_prompt(name, version: version, label: label)
-      build_prompt_client(prompt_data)
+    # Fetch a prompt and return cache metadata.
+    #
+    # @param name [String] The name of the prompt
+    # @param version [Integer, nil] Optional specific version number
+    # @param label [String, nil] Optional label (e.g., "production", "latest")
+    # @param fallback [String, Array, nil] Optional fallback prompt to use on error
+    # @param type [Symbol, nil] Required when fallback is provided (:text or :chat)
+    # @param cache_ttl [Integer, nil] Optional TTL override for this fetch
+    # @return [PromptFetchResult] Prompt client plus cache metadata
+    # @raise [ArgumentError] if fallback is provided without type
+    # @raise [NotFoundError] if the prompt is not found and no fallback provided
+    # @raise [UnauthorizedError] if authentication fails and no fallback provided
+    # @raise [ApiError] for other API errors and no fallback provided
+    def get_prompt_result(name, version: nil, label: nil, fallback: nil, type: nil, cache_ttl: nil)
+      validate_fallback_usage!(fallback, type)
+
+      api_result = api_client.get_prompt_result(name, version: version, label: label, cache_ttl: cache_ttl)
+      build_client_fetch_result(api_result, build_prompt_client(api_result.prompt))
     rescue ApiError, NotFoundError, UnauthorizedError => e
       # If no fallback, re-raise the error
       raise e unless fallback
 
       # Log warning and return fallback
       config.logger.warn("Langfuse API error for prompt '#{name}': #{e.message}. Using fallback.")
-      build_fallback_prompt_client(name, fallback, type)
+      key = api_client.prompt_cache_key(name, version: version, label: label)
+      build_fallback_prompt_result(key, fallback: fallback, type: type, cache_ttl: cache_ttl, error: e)
+    end
+
+    # Refresh a prompt from the API, optionally writing through to cache.
+    #
+    # @param name [String] The name of the prompt
+    # @param version [Integer, nil] Optional specific version number
+    # @param label [String, nil] Optional label (e.g., "production", "latest")
+    # @param cache_ttl [Integer, nil] Optional TTL override for this refresh
+    # @return [PromptFetchResult] Prompt client plus cache metadata
+    # @raise [ArgumentError] if both version and label are provided
+    # @raise [NotFoundError] if the prompt is not found
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] for other API errors
+    def refresh_prompt(name, version: nil, label: nil, cache_ttl: nil)
+      api_result = api_client.refresh_prompt(name, version: version, label: label, cache_ttl: cache_ttl)
+      build_client_fetch_result(api_result, build_prompt_client(api_result.prompt))
     end
 
+    # Invalidate one exact logical prompt cache key.
+    #
+    # @param name [String] The prompt name
+    # @param version [Integer, nil] Optional specific version number
+    # @param label [String, nil] Optional label
+    # @return [PromptCacheKey] The invalidated key
+    def invalidate_prompt_cache(name, version: nil, label: nil)
+      api_client.invalidate_prompt_cache(name, version: version, label: label)
+    end
+
+    # Invalidate all cached variants for one prompt name.
+    #
+    # @param name [String] The prompt name
+    # @return [Integer, nil] New generation, or nil when cache is disabled
+    def invalidate_prompt_cache_by_name(name)
+      api_client.invalidate_prompt_cache_by_name(name)
+    end
+
+    # Logically clear the whole Langfuse prompt cache namespace.
+    #
+    # @return [Integer, nil] New global generation, or nil when cache is disabled
+    def clear_prompt_cache
+      api_client.clear_prompt_cache
+    end
+
+    # Return prompt cache statistics.
+    #
+    # @return [Hash] Cache statistics
+    def prompt_cache_stats
+      api_client.prompt_cache_stats
+    end
+
+    # Inspect the logical and generated cache keys for a prompt.
+    #
+    # @param name [String] The prompt name
+    # @param version [Integer, nil] Optional specific version number
+    # @param label [String, nil] Optional label
+    # @return [PromptCacheKey] Logical and generated cache keys
+    def prompt_cache_key(name, version: nil, label: nil)
+      api_client.prompt_cache_key(name, version: version, label: label)
+    end
+
+    # Validate the configured prompt cache backend before first prompt fetch.
+    #
+    # @return [Boolean] true when the configured backend is usable
+    # @raise [ConfigurationError] if the backend is invalid
+    # rubocop:disable Naming/PredicateMethod
+    def validate_prompt_cache_backend!
+      api_client.cache&.validate! if api_client.cache.respond_to?(:validate!)
+      true
+    end
+    # rubocop:enable Naming/PredicateMethod
+
     # List all prompts in the Langfuse project
     #
     # Fetches a list of all prompt names available in your project.
@@ -126,6 +218,7 @@ module Langfuse
     # @param label [String, nil] Optional label (e.g., "production", "latest")
     # @param fallback [String, Array, nil] Optional fallback prompt to use on error
     # @param type [Symbol, nil] Required when fallback is provided (:text or :chat)
+    # @param cache_ttl [Integer, nil] Optional TTL override for this fetch
     # @return [String, Array<Hash>] Compiled prompt (String for text, Array for chat)
     # @raise [ArgumentError] if both version and label are provided
     # @raise [ArgumentError] if fallback is provided without type
@@ -148,10 +241,19 @@ module Langfuse
     #     fallback: "Hello {{name}}!",
     #     type: :text
     #   )
-    def compile_prompt(name, variables: {}, version: nil, label: nil, fallback: nil, type: nil)
-      prompt = get_prompt(name, version: version, label: label, fallback: fallback, type: type)
+    # rubocop:disable Metrics/ParameterLists
+    def compile_prompt(name, variables: {}, version: nil, label: nil, fallback: nil, type: nil, cache_ttl: nil)
+      prompt = get_prompt(
+        name,
+        version: version,
+        label: label,
+        fallback: fallback,
+        type: type,
+        cache_ttl: cache_ttl
+      )
       prompt.compile(**variables)
     end
+    # rubocop:enable Metrics/ParameterLists
 
     # Create a new prompt (or new version if name already exists)
     #
@@ -738,6 +840,48 @@ module Langfuse
       list_dataset_items(dataset_name: dataset_name)
     end
 
+    def validate_fallback_usage!(fallback, type)
+      return unless fallback && !type
+
+      raise ArgumentError, "type parameter is required when fallback is provided (use :text or :chat)"
+    end
+
+    def build_client_fetch_result(api_result, prompt_client)
+      PromptFetchResult.new(
+        prompt: prompt_client,
+        logical_key: api_result.logical_key,
+        storage_key: api_result.storage_key,
+        cache_status: api_result.cache_status,
+        source: api_result.source,
+        name: prompt_client.name,
+        version: prompt_client.version,
+        label: api_result.label
+      )
+    end
+
+    def build_fallback_prompt_result(key, fallback:, type:, cache_ttl:, error:)
+      prompt_client = build_fallback_prompt_client(key.name, fallback, type)
+      cache_status = fallback_cache_status(cache_ttl)
+      api_client.emit_prompt_fallback_event(key, cache_status: cache_status, error: error)
+      PromptFetchResult.new(
+        prompt: prompt_client,
+        logical_key: key.logical_key,
+        storage_key: key.storage_key,
+        cache_status: cache_status,
+        source: CacheSource::FALLBACK,
+        name: key.name,
+        version: key.version || prompt_client.version,
+        label: key.resolved_label
+      )
+    end
+
+    def fallback_cache_status(cache_ttl)
+      return CacheStatus::BYPASS if cache_ttl&.zero?
+      return CacheStatus::DISABLED unless api_client.cache
+
+      CacheStatus::MISS
+    end
+
     # Check if caching is enabled in configuration
     #
     # @return [Boolean]
@@ -754,11 +898,17 @@ module Langfuse
         create_memory_cache
       when :rails
         create_rails_cache_adapter
+      when :auto
+        rails_cache_available? ? create_rails_cache_adapter : create_memory_cache
       else
         raise ConfigurationError, "Unknown cache backend: #{config.cache_backend}"
       end
     end
 
+    def rails_cache_available?
+      defined?(Rails) && Rails.respond_to?(:cache) && Rails.cache
+    end
+
     # Create in-memory cache with SWR support if enabled
     #
     # @return [PromptCache]
@@ -823,9 +973,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 +1006,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 +1017,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/config.rb

@@ -41,7 +41,7 @@ module Langfuse
     # @return [Integer] Maximum number of cached items
     attr_accessor :cache_max_size
 
-    # @return [Symbol] Cache backend (:memory or :rails)
+    # @return [Symbol] Cache backend (:memory, :rails, or :auto)
     attr_accessor :cache_backend
 
     # @return [Integer] Lock timeout in seconds for distributed cache stampede protection
@@ -57,6 +57,9 @@ module Langfuse
     # @return [Integer] Number of background threads for cache refresh
     attr_accessor :cache_refresh_threads
 
+    # @return [#call, nil] Observer called for prompt cache events
+    attr_accessor :prompt_cache_observer
+
     # @return [Boolean] Use async processing for traces (requires ActiveJob)
     attr_accessor :tracing_async
 
@@ -158,6 +161,7 @@ module Langfuse
       @cache_stale_while_revalidate = DEFAULT_CACHE_STALE_WHILE_REVALIDATE
       @cache_stale_ttl = 0 # Default to 0 (SWR disabled, entries expire immediately after TTL)
       @cache_refresh_threads = DEFAULT_CACHE_REFRESH_THREADS
+      @prompt_cache_observer = nil
       @tracing_async = DEFAULT_TRACING_ASYNC
       @batch_size = DEFAULT_BATCH_SIZE
       @flush_interval = DEFAULT_FLUSH_INTERVAL
@@ -189,6 +193,7 @@ module Langfuse
       validate_swr_config!
 
       validate_cache_backend!
+      validate_prompt_cache_observer!
       validate_sample_rate!
       validate_should_export_span!
       validate_mask!
@@ -240,13 +245,19 @@ module Langfuse
     end
 
     def validate_cache_backend!
-      valid_backends = %i[memory rails]
+      valid_backends = %i[memory rails auto]
       return if valid_backends.include?(cache_backend)
 
       raise ConfigurationError,
             "cache_backend must be one of #{valid_backends.inspect}, got #{cache_backend.inspect}"
     end
 
+    def validate_prompt_cache_observer!
+      return if prompt_cache_observer.nil? || prompt_cache_observer.respond_to?(:call)
+
+      raise ConfigurationError, "prompt_cache_observer must respond to #call"
+    end
+
     def validate_swr_config!
       validate_swr_stale_ttl!
       validate_refresh_threads!

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