langfuse-rb 0.1.0 → 0.3.0

data/lib/langfuse/client.rb

@@ -17,6 +17,7 @@ module Langfuse
   #   prompt = client.get_prompt("greeting")
   #   compiled = prompt.compile(name: "Alice")
   #
+  # rubocop:disable Metrics/ClassLength
   class Client
     attr_reader :config, :api_client
 
@@ -139,6 +140,93 @@ module Langfuse
       prompt.compile(**variables)
     end
 
+    # Create a new prompt (or new version if name already exists)
+    #
+    # Creates a new prompt in Langfuse. If a prompt with the same name already
+    # exists, this creates a new version of that prompt.
+    #
+    # @param name [String] The prompt name (required)
+    # @param prompt [String, Array<Hash>] The prompt content (required)
+    #   - For text prompts: a string with {{variable}} placeholders
+    #   - For chat prompts: array of message hashes with role and content
+    # @param type [Symbol] Prompt type (:text or :chat) (required)
+    # @param config [Hash] Optional configuration (model parameters, tools, etc.)
+    # @param labels [Array<String>] Optional labels (e.g., ["production"])
+    # @param tags [Array<String>] Optional tags for categorization
+    # @param commit_message [String, nil] Optional commit message
+    # @return [TextPromptClient, ChatPromptClient] The created prompt client
+    # @raise [ArgumentError] if required parameters are missing or invalid
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] for other API errors
+    #
+    # @example Create a text prompt
+    #   prompt = client.create_prompt(
+    #     name: "greeting",
+    #     prompt: "Hello {{name}}!",
+    #     type: :text,
+    #     labels: ["production"],
+    #     config: { model: "gpt-4o", temperature: 0.7 }
+    #   )
+    #
+    # @example Create a chat prompt
+    #   prompt = client.create_prompt(
+    #     name: "support-bot",
+    #     prompt: [
+    #       { role: "system", content: "You are a {{role}} assistant" },
+    #       { role: "user", content: "{{question}}" }
+    #     ],
+    #     type: :chat,
+    #     labels: ["staging"]
+    #   )
+    # rubocop:disable Metrics/ParameterLists
+    def create_prompt(name:, prompt:, type:, config: {}, labels: [], tags: [], commit_message: nil)
+      validate_prompt_type!(type)
+      validate_prompt_content!(prompt, type)
+
+      prompt_data = api_client.create_prompt(
+        name: name,
+        prompt: normalize_prompt_content(prompt, type),
+        type: type.to_s,
+        config: config,
+        labels: labels,
+        tags: tags,
+        commit_message: commit_message
+      )
+
+      build_prompt_client(prompt_data)
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    # Update an existing prompt version's metadata
+    #
+    # Updates the labels of an existing prompt version.
+    # Note: The prompt content itself cannot be changed after creation.
+    #
+    # @param name [String] The prompt name (required)
+    # @param version [Integer] The version number to update (required)
+    # @param labels [Array<String>] New labels (replaces existing). Required.
+    # @return [TextPromptClient, ChatPromptClient] The updated prompt client
+    # @raise [ArgumentError] if labels is not an array
+    # @raise [NotFoundError] if the prompt is not found
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] for other API errors
+    #
+    # @example Update labels to promote to production
+    #   prompt = client.update_prompt(
+    #     name: "greeting",
+    #     version: 2,
+    #     labels: ["production"]
+    #   )
+    def update_prompt(name:, version:, labels:)
+      prompt_data = api_client.update_prompt(
+        name: name,
+        version: version,
+        labels: labels
+      )
+
+      build_prompt_client(prompt_data)
+    end
+
     # Generate URL for viewing a trace in Langfuse UI
     #
     # @param trace_id [String] The trace ID (hex-encoded, 32 characters)
@@ -252,9 +340,12 @@ module Langfuse
 
     # Shutdown the client and flush any pending scores
     #
+    # Also shuts down the cache if it supports shutdown (e.g., SWR thread pool).
+    #
     # @return [void]
     def shutdown
       @score_client.shutdown
+      @api_client.shutdown
     end
 
     private
@@ -274,20 +365,37 @@ module Langfuse
     def create_cache
       case config.cache_backend
       when :memory
-        PromptCache.new(
-          ttl: config.cache_ttl,
-          max_size: config.cache_max_size
-        )
+        create_memory_cache
       when :rails
-        RailsCacheAdapter.new(
-          ttl: config.cache_ttl,
-          lock_timeout: config.cache_lock_timeout
-        )
+        create_rails_cache_adapter
       else
         raise ConfigurationError, "Unknown cache backend: #{config.cache_backend}"
       end
     end
 
+    # Create in-memory cache with SWR support if enabled
+    #
+    # @return [PromptCache]
+    def create_memory_cache
+      PromptCache.new(
+        ttl: config.cache_ttl,
+        max_size: config.cache_max_size,
+        stale_ttl: config.normalized_stale_ttl,
+        refresh_threads: config.cache_refresh_threads,
+        logger: config.logger
+      )
+    end
+
+    def create_rails_cache_adapter
+      RailsCacheAdapter.new(
+        ttl: config.cache_ttl,
+        lock_timeout: config.cache_lock_timeout,
+        stale_ttl: config.normalized_stale_ttl,
+        refresh_threads: config.cache_refresh_threads,
+        logger: config.logger
+      )
+    end
+
     # Build the appropriate prompt client based on prompt type
     #
     # @param prompt_data [Hash] The prompt data from API
@@ -314,6 +422,8 @@ module Langfuse
     # @return [TextPromptClient, ChatPromptClient]
     # @raise [ArgumentError] if type is invalid
     def build_fallback_prompt_client(name, fallback, type)
+      validate_prompt_type!(type)
+
       # Create minimal prompt data structure
       prompt_data = {
         "name" => name,
@@ -330,9 +440,58 @@ module Langfuse
         TextPromptClient.new(prompt_data)
       when :chat
         ChatPromptClient.new(prompt_data)
-      else
-        raise ArgumentError, "Invalid type: #{type}. Must be :text or :chat"
+      end
+    end
+
+    # Validate prompt type parameter
+    #
+    # @param type [Symbol] The type to validate
+    # @raise [ArgumentError] if type is invalid
+    def validate_prompt_type!(type)
+      valid_types = %i[text chat]
+      return if valid_types.include?(type)
+
+      raise ArgumentError, "Invalid type: #{type}. Must be :text or :chat"
+    end
+
+    # Validate prompt content matches the declared type
+    #
+    # @param prompt [String, Array] The prompt content
+    # @param type [Symbol] The declared type
+    # @raise [ArgumentError] if content doesn't match type
+    def validate_prompt_content!(prompt, type)
+      case type
+      when :text
+        raise ArgumentError, "Text prompt must be a String" unless prompt.is_a?(String)
+      when :chat
+        raise ArgumentError, "Chat prompt must be an Array" unless prompt.is_a?(Array)
+      end
+    end
+
+    # Normalize prompt content for API request
+    #
+    # Converts Ruby symbol keys to string keys for chat messages
+    #
+    # @param prompt [String, Array] The prompt content
+    # @param type [Symbol] The prompt type
+    # @return [String, Array] Normalized content
+    def normalize_prompt_content(prompt, type)
+      return prompt if type == :text
+
+      # 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]
+        }
       end
     end
   end
+  # rubocop:enable Metrics/ClassLength
 end

data/lib/langfuse/config.rb

@@ -46,6 +46,16 @@ module Langfuse
     # @return [Integer] Lock timeout in seconds for distributed cache stampede protection
     attr_accessor :cache_lock_timeout
 
+    # @return [Boolean] Enable stale-while-revalidate caching (when true, sets cache_stale_ttl to cache_ttl if not customized)
+    attr_accessor :cache_stale_while_revalidate
+
+    # @return [Integer, Symbol] Stale TTL in seconds (grace period for serving stale data, default: 0 when SWR disabled, cache_ttl when SWR enabled)
+    #   Accepts :indefinite which is automatically normalized to 1000 years (31,536,000,000 seconds) for practical "never expire" behavior.
+    attr_accessor :cache_stale_ttl
+
+    # @return [Integer] Number of background threads for cache refresh
+    attr_accessor :cache_refresh_threads
+
     # @return [Boolean] Use async processing for traces (requires ActiveJob)
     attr_accessor :tracing_async
 
@@ -65,11 +75,16 @@ module Langfuse
     DEFAULT_CACHE_MAX_SIZE = 1000
     DEFAULT_CACHE_BACKEND = :memory
     DEFAULT_CACHE_LOCK_TIMEOUT = 10
+    DEFAULT_CACHE_STALE_WHILE_REVALIDATE = false
+    DEFAULT_CACHE_REFRESH_THREADS = 5
     DEFAULT_TRACING_ASYNC = true
     DEFAULT_BATCH_SIZE = 50
     DEFAULT_FLUSH_INTERVAL = 10
     DEFAULT_JOB_QUEUE = :default
 
+    # Number of seconds representing indefinite cache duration (~1000 years)
+    INDEFINITE_SECONDS = 1000 * 365 * 24 * 60 * 60
+
     # Initialize a new Config object
     #
     # @yield [config] Optional block for configuration
@@ -83,6 +98,9 @@ module Langfuse
       @cache_max_size = DEFAULT_CACHE_MAX_SIZE
       @cache_backend = DEFAULT_CACHE_BACKEND
       @cache_lock_timeout = DEFAULT_CACHE_LOCK_TIMEOUT
+      @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
       @tracing_async = DEFAULT_TRACING_ASYNC
       @batch_size = DEFAULT_BATCH_SIZE
       @flush_interval = DEFAULT_FLUSH_INTERVAL
@@ -110,10 +128,29 @@ module Langfuse
               "cache_lock_timeout must be positive"
       end
 
+      validate_swr_config!
+
       validate_cache_backend!
     end
     # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
+    # Normalize stale_ttl value
+    #
+    # Converts :indefinite to 1000 years in seconds for practical "never expire"
+    # behavior while keeping the value finite for calculations.
+    #
+    # @return [Integer] Normalized stale TTL in seconds
+    #
+    # @example
+    #   config.cache_stale_ttl = 300
+    #   config.normalized_stale_ttl # => 300
+    #
+    #   config.cache_stale_ttl = :indefinite
+    #   config.normalized_stale_ttl # => 31536000000
+    def normalized_stale_ttl
+      cache_stale_ttl == :indefinite ? INDEFINITE_SECONDS : cache_stale_ttl
+    end
+
     private
 
     def default_logger
@@ -131,5 +168,37 @@ module Langfuse
       raise ConfigurationError,
             "cache_backend must be one of #{valid_backends.inspect}, got #{cache_backend.inspect}"
     end
+
+    def validate_swr_config!
+      validate_swr_stale_ttl!
+      validate_refresh_threads!
+    end
+
+    def validate_swr_stale_ttl!
+      # Check if SWR is enabled but stale_ttl is nil
+      if cache_stale_while_revalidate && cache_stale_ttl.nil?
+        raise ConfigurationError,
+              "cache_stale_ttl cannot be nil when cache_stale_while_revalidate is enabled. " \
+              "Set it to cache_ttl for a logical default, or use :indefinite for never-expiring cache."
+      end
+
+      # Validate that cache_stale_ttl is not nil (unless already caught by SWR check)
+      if cache_stale_ttl.nil?
+        raise ConfigurationError,
+              "cache_stale_ttl must be non-negative or :indefinite"
+      end
+
+      # Validate numeric values are non-negative
+      return unless cache_stale_ttl.is_a?(Integer) && cache_stale_ttl.negative?
+
+      raise ConfigurationError,
+            "cache_stale_ttl must be non-negative or :indefinite"
+    end
+
+    def validate_refresh_threads!
+      return unless cache_refresh_threads.nil? || cache_refresh_threads <= 0
+
+      raise ConfigurationError, "cache_refresh_threads must be positive"
+    end
   end
 end

data/lib/langfuse/prompt_cache.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "monitor"
+require_relative "stale_while_revalidate"
 
 module Langfuse
   # Simple in-memory cache for prompt data with TTL
@@ -14,24 +15,63 @@ module Langfuse
   #   cache.get("greeting:1") # => prompt_data
   #
   class PromptCache
+    include StaleWhileRevalidate
+
     # Cache entry with data and expiration time
-    CacheEntry = Struct.new(:data, :expires_at) do
+    #
+    # Supports stale-while-revalidate pattern:
+    # - fresh_until: Time until entry is considered fresh (can be served immediately)
+    # - stale_until: Time until entry is considered stale (serve while revalidating in background)
+    # - After stale_until: Entry is expired (must revalidate synchronously)
+    CacheEntry = Struct.new(:data, :fresh_until, :stale_until) do
+      # Check if the cache entry is still fresh
+      #
+      # @return [Boolean] true if current time is before fresh_until
+      def fresh?
+        Time.now < fresh_until
+      end
+
+      # Check if the cache entry is stale but not expired
+      #
+      # Stale entries can be served immediately while a background
+      # revalidation occurs (stale-while-revalidate pattern)
+      #
+      # @return [Boolean] true if current time is between fresh_until and stale_until
+      def stale?
+        now = Time.now
+        now >= fresh_until && now < stale_until
+      end
+
+      # Check if the cache entry has expired
+      #
+      # Expired entries should not be served and must be revalidated
+      # synchronously before use.
+      #
+      # @return [Boolean] true if current time is at or after stale_until
       def expired?
-        Time.now > expires_at
+        Time.now >= stale_until
       end
     end
 
-    attr_reader :ttl, :max_size
+    attr_reader :ttl, :max_size, :stale_ttl, :logger
 
     # Initialize a new cache
     #
     # @param ttl [Integer] Time-to-live in seconds (default: 60)
     # @param max_size [Integer] Maximum cache size (default: 1000)
-    def initialize(ttl: 60, max_size: 1000)
+    # @param stale_ttl [Integer] Stale TTL for SWR in seconds (default: 0, SWR disabled).
+    #   Note: :indefinite is normalized to 1000 years by Config before being passed here.
+    # @param refresh_threads [Integer] Number of background refresh threads (default: 5)
+    # @param logger [Logger, nil] Logger instance for error reporting (default: nil, creates new logger)
+    def initialize(ttl: 60, max_size: 1000, stale_ttl: 0, refresh_threads: 5, logger: default_logger)
       @ttl = ttl
       @max_size = max_size
+      @stale_ttl = stale_ttl
+      @logger = logger
       @cache = {}
       @monitor = Monitor.new
+      @locks = {} # Track locks for in-memory locking
+      initialize_swr(refresh_threads: refresh_threads) if swr_enabled?
     end
 
     # Get a value from the cache
@@ -58,8 +98,10 @@ module Langfuse
         # Evict oldest entry if at max size
         evict_oldest if @cache.size >= max_size
 
-        expires_at = Time.now + ttl
-        @cache[key] = CacheEntry.new(value, expires_at)
+        now = Time.now
+        fresh_until = now + ttl
+        stale_until = fresh_until + stale_ttl
+        @cache[key] = CacheEntry.new(value, fresh_until, stale_until)
         value
       end
     end
@@ -117,15 +159,84 @@ module Langfuse
 
     private
 
+    # Implementation of StaleWhileRevalidate abstract methods
+
+    # Get value from cache (SWR interface)
+    #
+    # @param key [String] Cache key
+    # @return [PromptCache::CacheEntry, nil] Cached value
+    def cache_get(key)
+      @monitor.synchronize do
+        @cache[key]
+      end
+    end
+
+    # Set value in cache (SWR interface)
+    #
+    # @param key [String] Cache key
+    # @param value [PromptCache::CacheEntry] Value to cache
+    # @return [PromptCache::CacheEntry] The cached value
+    def cache_set(key, value)
+      @monitor.synchronize do
+        # Evict oldest entry if at max size
+        evict_oldest if @cache.size >= max_size
+
+        @cache[key] = value
+        value
+      end
+    end
+
+    # Acquire a lock using in-memory locking
+    #
+    # Prevents duplicate background refreshes from different threads within
+    # the same process. This is NOT distributed locking - it only works
+    # within a single process. For distributed locking, use RailsCacheAdapter.
+    #
+    # **MEMORY LEAK WARNING**: Locks are stored in a hash and only deleted on
+    # release_lock. If a refresh thread crashes or is killed externally (e.g., Thread#kill)
+    # between acquire_lock and release_lock, the lock persists forever. Unlike Redis locks
+    # which have TTL expiration, in-memory locks have no timeout. For production use with
+    # SWR, prefer RailsCacheAdapter to avoid lock accumulation and potential memory exhaustion.
+    #
+    # @param lock_key [String] Lock key
+    # @return [Boolean] true if lock was acquired, false if already held
+    def acquire_lock(lock_key)
+      @monitor.synchronize do
+        return false if @locks[lock_key]
+
+        @locks[lock_key] = true
+        true
+      end
+    end
+
+    # Release a lock
+    #
+    # @param lock_key [String] Lock key
+    # @return [void]
+    def release_lock(lock_key)
+      @monitor.synchronize do
+        @locks.delete(lock_key)
+      end
+    end
+
+    # In-memory cache helper methods
+
     # Evict the oldest entry from cache
     #
     # @return [void]
     def evict_oldest
       return if @cache.empty?
 
-      # Find entry with earliest expiration
-      oldest_key = @cache.min_by { |_key, entry| entry.expires_at }&.first
+      # Find entry with earliest expiration (using stale_until as expiration time)
+      oldest_key = @cache.min_by { |_key, entry| entry.stale_until }&.first
       @cache.delete(oldest_key) if oldest_key
     end
+
+    # Create a default logger
+    #
+    # @return [Logger]
+    def default_logger
+      Logger.new($stdout, level: Logger::WARN)
+    end
   end
 end

data/lib/langfuse/propagation.rb

@@ -364,7 +364,6 @@ module Langfuse
     def self._get_span_key_from_baggage_key(baggage_key)
       return nil unless baggage_key.start_with?(BAGGAGE_PREFIX)
 
-      # Remove prefix
       suffix = baggage_key[BAGGAGE_PREFIX.length..]
 
       # Handle metadata keys (format: langfuse_metadata_{key_name})
@@ -373,17 +372,7 @@ module Langfuse
         return "#{OtelAttributes::TRACE_METADATA}.#{metadata_key}"
       end
 
-      # Map standard keys
-      case suffix
-      when "user_id"
-        _get_propagated_span_key("user_id")
-      when "session_id"
-        _get_propagated_span_key("session_id")
-      when "version"
-        _get_propagated_span_key("version")
-      when "tags"
-        _get_propagated_span_key("tags")
-      end
+      SPAN_KEY_MAP[suffix]
     end
 
     # Check if baggage API is available
@@ -404,7 +393,7 @@ module Langfuse
     def self._extract_baggage_attributes(context)
       return {} unless baggage_available?
 
-      baggage = OpenTelemetry::Baggage.value(context: context)
+      baggage = OpenTelemetry::Baggage.values(context: context)
       return {} unless baggage.is_a?(Hash)
 
       attributes = {}
@@ -453,12 +442,12 @@ module Langfuse
       if key == "metadata" && value.is_a?(Hash)
         value.each do |k, v|
           entry_key = "#{baggage_key}_#{k}"
-          context = OpenTelemetry::Baggage.set_value(context: context, key: entry_key, value: v.to_s)
+          context = OpenTelemetry::Baggage.set_value(entry_key, v.to_s, context: context)
         end
       elsif key == "tags" && value.is_a?(Array)
-        context = OpenTelemetry::Baggage.set_value(context: context, key: baggage_key, value: value.join(","))
+        context = OpenTelemetry::Baggage.set_value(baggage_key, value.join(","), context: context)
       else
-        context = OpenTelemetry::Baggage.set_value(context: context, key: baggage_key, value: value.to_s)
+        context = OpenTelemetry::Baggage.set_value(baggage_key, value.to_s, context: context)
       end
       context
     rescue StandardError => e