langfuse-rb 0.10.0 → 0.11.0

data/lib/langfuse/app_root_tracking.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module Langfuse
+  # Owns application-root state for active span trees.
+  #
+  # @api private
+  module AppRootTracking
+    APP_ROOT_INELIGIBLE_SPANS = [
+      %w[litellm raw_gen_ai_request]
+    ].freeze
+    private_constant :APP_ROOT_INELIGIBLE_SPANS
+
+    # Return whether an exported span can be an application root when its parent is untracked.
+    #
+    # LiteLLM can emit `raw_gen_ai_request` after its exported parent finishes.
+    # The late child must not become a second application root.
+    #
+    # @param span [OpenTelemetry::SDK::Trace::Span] Span to inspect
+    # @return [Boolean] Whether the span can be an application root
+    # @api private
+    def self.eligible_without_tracked_parent?(span)
+      return true if span.parent_span_id == OpenTelemetry::Trace::INVALID_SPAN_ID
+
+      identity = [span.instrumentation_scope&.name, span.name]
+      !APP_ROOT_INELIGIBLE_SPANS.include?(identity)
+    end
+
+    # Defers a finished span until its active ancestors have final export decisions.
+    #
+    # @api private
+    class Tracker
+      ReadySpan = Struct.new(:span, :app_root, keyword_init: true)
+      private_constant :ReadySpan
+
+      State = Struct.new(
+        :span,
+        :trace_claimed,
+        :untracked_parent_root_eligible,
+        :parent_span_id,
+        :active_child_count,
+        :finished,
+        :exportable,
+        :enqueued,
+        keyword_init: true
+      )
+      private_constant :State
+
+      def initialize
+        @mutex = Mutex.new
+        @state_by_span_id = {}
+      end
+
+      # @param span [OpenTelemetry::SDK::Trace::Span] The active span
+      # @param trace_claimed [Boolean] Whether propagated context already owns the root
+      # @param untracked_parent_root_eligible [Boolean] Whether an untracked parent permits a root
+      # @return [void]
+      def remember(span, trace_claimed:, untracked_parent_root_eligible:)
+        @mutex.synchronize do
+          parent_state = @state_by_span_id[span.parent_span_id]
+          parent_state.active_child_count += 1 if parent_state
+          @state_by_span_id[span.context.span_id] = build_state(
+            span,
+            trace_claimed: trace_claimed,
+            untracked_parent_root_eligible: untracked_parent_root_eligible
+          )
+        end
+      end
+
+      # Resolve finished spans whose ancestor export decisions are final.
+      #
+      # @param span [OpenTelemetry::SDK::Trace::Span] The finished span
+      # @param exportable [Boolean] Whether the final export filter accepted the span
+      # @return [Array<ReadySpan>] Spans that the batch processor can enqueue
+      def finish(span, exportable:)
+        @mutex.synchronize do
+          state = @state_by_span_id[span.context.span_id]
+          return [] unless state
+
+          state.finished = true
+          state.exportable = exportable
+          ready_spans = resolve_ready_spans
+          release_finished_states
+          ready_spans
+        end
+      end
+
+      # @return [Boolean] Whether the tracker has no active span trees
+      def empty?
+        @mutex.synchronize { @state_by_span_id.empty? }
+      end
+
+      private
+
+      def build_state(span, trace_claimed:, untracked_parent_root_eligible:)
+        State.new(
+          span: span,
+          trace_claimed: trace_claimed,
+          untracked_parent_root_eligible: untracked_parent_root_eligible,
+          parent_span_id: span.parent_span_id,
+          active_child_count: 0,
+          finished: false,
+          exportable: nil,
+          enqueued: false
+        )
+      end
+
+      def resolve_ready_spans
+        @state_by_span_id.values.filter_map do |state|
+          next unless state.finished && state.exportable && !state.enqueued
+
+          app_root = app_root_status(state)
+          next if app_root.nil?
+
+          state.enqueued = true
+          ReadySpan.new(span: state.span, app_root: app_root)
+        end
+      end
+
+      def app_root_status(state)
+        trace_claimed = state.trace_claimed
+        parent_span_id = state.parent_span_id
+        parent_state = @state_by_span_id[parent_span_id]
+        return false unless parent_state || state.untracked_parent_root_eligible
+
+        while parent_state
+          return nil unless parent_state.finished
+          return false if parent_state.exportable
+
+          trace_claimed = parent_state.trace_claimed
+          parent_span_id = parent_state.parent_span_id
+          parent_state = @state_by_span_id[parent_span_id]
+        end
+        !trace_claimed
+      end
+
+      def release_finished_states
+        releasable_span_ids = @state_by_span_id.filter_map do |span_id, state|
+          span_id if releasable?(state)
+        end
+        until releasable_span_ids.empty?
+          span_id = releasable_span_ids.pop
+          state = @state_by_span_id[span_id]
+          next unless releasable?(state)
+
+          parent_span_id = release_state(span_id, state)
+          releasable_span_ids << parent_span_id if parent_span_id
+        end
+      end
+
+      def releasable?(state)
+        state&.finished && state.active_child_count.zero? && (!state.exportable || state.enqueued)
+      end
+
+      def release_state(span_id, state)
+        @state_by_span_id.delete(span_id)
+        parent_state = @state_by_span_id[state.parent_span_id]
+        return unless parent_state
+
+        parent_state.active_child_count -= 1
+        state.parent_span_id
+      end
+    end
+  end
+end

data/lib/langfuse/cache_warmer.rb

@@ -148,25 +148,22 @@ module Langfuse
     #
     # @return [Boolean]
     def cache_enabled?
-      cache = client.api_client.cache
-      return false if cache.nil?
-
-      cache.ttl&.positive? || false
+      client.prompt_cache_stats[:enabled] == true
     end
 
     # Get cache statistics (if supported by backend)
     #
     # @return [Hash, nil] Cache stats or nil if not supported
     def cache_stats
-      cache = client.api_client.cache
-      return nil unless cache
-
-      stats = {}
-      stats[:backend] = cache.class.name.split("::").last
-      stats[:ttl] = cache.ttl if cache.respond_to?(:ttl)
-      stats[:size] = cache.size if cache.respond_to?(:size)
-      stats[:max_size] = cache.max_size if cache.respond_to?(:max_size)
-      stats
+      stats = client.prompt_cache_stats
+      return nil unless stats[:enabled]
+
+      {
+        backend: public_backend_name(stats[:backend]),
+        ttl: stats[:ttl],
+        size: stats[:size],
+        max_size: stats[:max_size]
+      }
     end
 
     private
@@ -213,6 +210,17 @@ module Langfuse
     def record_failure(results, name, error)
       results[:failed] << { name: name, error: error }
     end
+
+    def public_backend_name(backend)
+      case backend
+      when CacheBackend::MEMORY
+        "PromptCache"
+      when CacheBackend::RAILS
+        "RailsCacheAdapter"
+      else
+        backend.to_s
+      end
+    end
   end
 
   # Error raised when cache warming fails with warm!

data/lib/langfuse/chat_prompt_client.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "prompt_renderer"
+require_relative "prompt_variables"
 
 module Langfuse
   # Chat prompt client for compiling chat prompts with variable substitution
@@ -11,7 +12,7 @@ module Langfuse
   # @example Basic usage
   #   prompt_data = api_client.get_prompt("support_chat")
   #   chat_prompt = Langfuse::ChatPromptClient.new(prompt_data)
-  #   chat_prompt.compile(variables: { user_name: "Alice", issue: "login" })
+  #   chat_prompt.compile(user_name: "Alice", issue: "login")
   #   # => [{ role: "system", content: "You are a support agent..." }, ...]
   #
   # @example Accessing metadata
@@ -28,6 +29,9 @@ module Langfuse
     # @return [Integer] Prompt version number
     attr_reader :version
 
+    # @return [Array<Hash>] Raw prompt template (array of role/content message hashes)
+    attr_reader :prompt
+
     # @return [Array<String>] Labels assigned to this prompt
     attr_reader :labels
 
@@ -37,9 +41,6 @@ module Langfuse
     # @return [Hash] Prompt configuration
     attr_reader :config
 
-    # @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
 
@@ -73,6 +74,22 @@ module Langfuse
       "chat"
     end
 
+    # Return the unique variables referenced by all message templates
+    #
+    # Section names are included because callers must provide their values.
+    # Message placeholder entries are not Mustache templates and are excluded.
+    #
+    # @return [Array<String>] Referenced variable names in message and source order
+    # @raise [Mustache::Parser::SyntaxError] if a message contains invalid Mustache syntax
+    def variables
+      prompt.each_with_object([]) do |message, names|
+        normalized = symbolize_keys(message)
+        next if normalized[:type].to_s == PLACEHOLDER_TYPE
+
+        names.concat(PromptVariables.extract(normalized[:content] || ""))
+      end.uniq
+    end
+
     # Compile the chat prompt with variable substitution and message placeholders
     #
     # Returns an array of message hashes with roles and compiled content.