langfuse-rb 0.9.0 → 0.10.0

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]

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/prompt_cache.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "monitor"
+require "base64"
 require_relative "stale_while_revalidate"
 
 module Langfuse
@@ -14,9 +15,15 @@ module Langfuse
   #   cache.set("greeting:1", prompt_data)
   #   cache.get("greeting:1") # => prompt_data
   #
+  # rubocop:disable Metrics/ClassLength
   class PromptCache
     include StaleWhileRevalidate
 
+    # Caps the per-name generation map. Without a cap, long-lived processes
+    # that invalidate across many distinct prompts grow it unboundedly; LRU
+    # eviction keeps the working set live and lets cold names go.
+    MAX_NAME_GENERATIONS = 1024
+
     # Cache entry with data and expiration time
     #
     # Supports stale-while-revalidate pattern:
@@ -79,6 +86,9 @@ module Langfuse
       @stale_ttl = stale_ttl
       @logger = logger
       @cache = {}
+      @global_generation = 0
+      @name_generations = {}
+      @name_generation_counter = 0
       @monitor = Monitor.new
       @locks = {} # Track locks for in-memory locking
       initialize_swr(refresh_threads: refresh_threads) if swr_enabled?
@@ -98,24 +108,45 @@ module Langfuse
       end
     end
 
+    # Read a raw cache entry, including stale entries.
+    #
+    # @param key [String] Cache key
+    # @return [CacheEntry, nil] Raw cache entry
+    def entry(key)
+      @monitor.synchronize do
+        @cache[key]
+      end
+    end
+
     # Set a value in the cache
     #
     # @param key [String] Cache key
     # @param value [Object] Value to cache
     # @return [Object] The cached value
-    def set(key, value)
+    def set(key, value, ttl: nil, stale_ttl: nil)
       @monitor.synchronize do
         # Evict oldest entry if at max size
         evict_oldest if @cache.size >= max_size
-
-        now = Time.now
-        fresh_until = now + ttl
-        stale_until = fresh_until + stale_ttl
-        @cache[key] = CacheEntry.new(value, fresh_until, stale_until)
+        # TTL math is inlined (not extracted to a helper) to keep this hot path
+        # allocation-free apart from the CacheEntry below.
+        effective_ttl = ttl.nil? ? self.ttl : ttl
+        effective_stale_ttl = stale_ttl.nil? ? self.stale_ttl : stale_ttl
+        fresh_until = Time.now + effective_ttl
+        @cache[key] = CacheEntry.new(value, fresh_until, fresh_until + effective_stale_ttl)
         value
       end
     end
 
+    # Delete one generated storage key.
+    #
+    # @param key [String] Generated storage key
+    # @return [Boolean] true if an entry was removed
+    def delete(key)
+      @monitor.synchronize do
+        !@cache.delete(key).nil?
+      end
+    end
+
     # Clear the entire cache
     #
     # @return [void]
@@ -125,6 +156,65 @@ module Langfuse
       end
     end
 
+    # Logically invalidate every generated storage key.
+    #
+    # @return [Integer] New global generation
+    def clear_logically
+      @monitor.synchronize do
+        @global_generation += 1
+      end
+    end
+
+    # Logically invalidate every cache variant for one prompt name.
+    #
+    # Generations come from a monotonic global counter, not a per-name counter,
+    # so an evicted name re-entering the map can't reuse a generation value
+    # that's still embedded in a stale @cache entry.
+    #
+    # @param name [String] Prompt name
+    # @return [Integer] New name generation
+    def invalidate_name(name)
+      @monitor.synchronize do
+        name_str = name.to_s
+        @name_generations.delete(name_str)
+        @name_generations.shift if @name_generations.size >= MAX_NAME_GENERATIONS
+        @name_generation_counter += 1
+        @name_generations[name_str] = @name_generation_counter
+      end
+    end
+
+    # Build a generated storage key for the current cache generation.
+    #
+    # @param logical_key [String] Stable logical cache identity
+    # @param name [String] Prompt name
+    # @return [String] Generated storage key
+    def storage_key(logical_key, name:)
+      @monitor.synchronize do
+        self.class.storage_key(
+          logical_key,
+          name: name,
+          global_generation: @global_generation,
+          name_generation: @name_generations.fetch(name.to_s, 0)
+        )
+      end
+    end
+
+    # @return [Hash] Prompt cache statistics
+    def stats
+      @monitor.synchronize do
+        counts = count_entries_by_generation
+        {
+          backend: CacheBackend::MEMORY,
+          enabled: true,
+          current_generation_entries: counts.fetch(:current),
+          orphaned_entries: counts.fetch(:orphaned),
+          total_entries: @cache.size,
+          global_generation: @global_generation,
+          unsupported_counts: []
+        }
+      end
+    end
+
     # Remove expired entries from cache
     #
     # @return [Integer] Number of entries removed
@@ -154,6 +244,15 @@ module Langfuse
       end
     end
 
+    # Validate that the memory cache backend is usable.
+    #
+    # @return [Boolean]
+    # rubocop:disable Naming/PredicateMethod
+    def validate!
+      true
+    end
+    # rubocop:enable Naming/PredicateMethod
+
     # Build a cache key from prompt name and options
     #
     # @param name [String] Prompt name
@@ -168,6 +267,18 @@ module Langfuse
       key
     end
 
+    # Build a generated storage key from generation metadata.
+    #
+    # @param logical_key [String] Stable logical cache identity
+    # @param name [String] Prompt name
+    # @param global_generation [Integer] Global cache generation
+    # @param name_generation [Integer] Prompt-name cache generation
+    # @return [String] Generated storage key
+    def self.storage_key(logical_key, name:, global_generation:, name_generation:)
+      encoded_name = Base64.urlsafe_encode64(name.to_s, padding: false)
+      "g#{global_generation}:n#{encoded_name}:#{name_generation}:#{logical_key}"
+    end
+
     private
 
     # Implementation of StaleWhileRevalidate abstract methods
@@ -187,7 +298,7 @@ module Langfuse
     # @param key [String] Cache key
     # @param value [PromptCache::CacheEntry] Value to cache
     # @return [PromptCache::CacheEntry] The cached value
-    def cache_set(key, value)
+    def cache_set(key, value, **_options)
       @monitor.synchronize do
         # Evict oldest entry if at max size
         evict_oldest if @cache.size >= max_size
@@ -230,6 +341,29 @@ module Langfuse
       end
     end
 
+    def count_entries_by_generation
+      @cache.each_key.with_object({ current: 0, orphaned: 0 }) do |key, counts|
+        if current_generation_key?(key)
+          counts[:current] += 1
+        else
+          counts[:orphaned] += 1
+        end
+      end
+    end
+
+    def current_generation_key?(key)
+      parts = key.split(":", 4)
+      return false unless parts.size == 4
+      return false unless parts[0].start_with?("g") && parts[1].start_with?("n")
+
+      global = Integer(parts[0][1..])
+      name = Base64.urlsafe_decode64(parts[1][1..])
+      name_generation = Integer(parts[2])
+      global == @global_generation && name_generation == @name_generations.fetch(name, 0)
+    rescue ArgumentError
+      false
+    end
+
     # In-memory cache helper methods
 
     # Evict the oldest entry from cache
@@ -250,4 +384,5 @@ module Langfuse
       Logger.new($stdout, level: Logger::WARN)
     end
   end
+  # rubocop:enable Metrics/ClassLength
 end

data/lib/langfuse/prompt_cache_events.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Langfuse
+  # Prompt cache event emission for ApiClient.
+  #
+  # Includers must expose:
+  # - `cache_backend_name` — used in {#event_payload} to tag the cache backend
+  # - `logger` — used to warn on observer/notifier failures
+  module PromptCacheEvents
+    # ActiveSupport::Notifications event name used for prompt cache events.
+    PROMPT_CACHE_NOTIFICATION = "prompt_cache.langfuse"
+
+    # Configure prompt cache event dispatch. Wraps the observer once into a
+    # 1-arg callable so the per-event hot path never re-checks arity.
+    #
+    # @param cache_observer [#call, nil] Optional observer
+    # @return [void]
+    def setup_prompt_cache_events(cache_observer:)
+      @cache_observer_callable = wrap_cache_observer(cache_observer)
+      @active_support_notifications = defined?(ActiveSupport::Notifications) ? ActiveSupport::Notifications : nil
+    end
+
+    # Emit a prompt cache event to configured hooks. Accepts an eager payload
+    # hash or a block that builds one. The block is only evaluated when at
+    # least one listener is active, avoiding hash allocations on the hot path.
+    #
+    # @param event [Symbol] Event name
+    # @param payload [Hash, nil] Event payload (omit when passing a block)
+    # @yieldreturn [Hash] Lazily constructed payload
+    # @return [void]
+    def emit_prompt_cache_event(event, payload = nil)
+      observer_callable = @cache_observer_callable
+      as_listening = active_support_listening?
+      return if observer_callable.nil? && !as_listening
+
+      payload ||= block_given? ? yield : {}
+      normalized_payload = payload.merge(event: event.to_sym)
+      notify_cache_observer(normalized_payload) if observer_callable
+      notify_active_support(normalized_payload) if as_listening
+    end
+
+    # Emit a fallback event for a prompt fetch that fell back to caller-provided content.
+    #
+    # @param key [PromptCacheKey] Logical and storage cache key
+    # @param cache_status [Symbol] Cache status to report
+    # @param error [StandardError] The error that triggered the fallback
+    # @return [void]
+    def emit_prompt_fallback_event(key, cache_status:, error:)
+      emit_prompt_cache_event(:fallback) do
+        event_payload(key, cache_status, CacheSource::FALLBACK,
+                      error_class: error.class.name, error_message: error.message)
+      end
+    end
+
+    private
+
+    # @api private
+    def event_payload(key, cache_status, source, extra = {})
+      {
+        name: key.name,
+        version: key.version,
+        label: key.resolved_label,
+        logical_key: key.logical_key,
+        storage_key: key.storage_key,
+        backend: cache_backend_name,
+        cache_status: cache_status,
+        source: source
+      }.merge(extra)
+    end
+
+    # @api private
+    def notify_cache_observer(payload)
+      @cache_observer_callable.call(payload)
+    rescue StandardError => e
+      logger.warn("Langfuse prompt cache observer failed: #{e.class} - #{e.message}")
+    end
+
+    # @api private
+    def active_support_listening?
+      return false unless @active_support_notifications
+
+      notifier = @active_support_notifications.notifier
+      # Defensive: notifier stand-ins (test fakes, AS::Notifications forks,
+      # very old AS versions) may not implement listening?. Assume they're
+      # listening so we still attempt to instrument; notify_active_support
+      # rescues failures.
+      return true unless notifier.respond_to?(:listening?)
+
+      notifier.listening?(PROMPT_CACHE_NOTIFICATION)
+    end
+
+    # @api private
+    def notify_active_support(payload)
+      @active_support_notifications.instrument(PROMPT_CACHE_NOTIFICATION, payload)
+    rescue StandardError => e
+      logger.warn("Langfuse ActiveSupport cache notification failed: #{e.class} - #{e.message}")
+    end
+
+    # @api private
+    def wrap_cache_observer(observer)
+      return nil if observer.nil?
+
+      if observer.method(:call).arity == 1
+        ->(payload) { observer.call(payload) }
+      else
+        ->(payload) { observer.call(payload[:event], payload) }
+      end
+    end
+  end
+end