langfuse-rb 0.1.0

data/lib/langfuse/cache_warmer.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+module Langfuse
+  # Cache warming utility for pre-loading prompts into cache
+  #
+  # Useful for deployment scenarios where you want to warm the cache
+  # before serving traffic, preventing cold-start API calls.
+  #
+  # @example Warm cache with specific prompts
+  #   warmer = Langfuse::CacheWarmer.new
+  #   results = warmer.warm(['greeting', 'conversation', 'rag-pipeline'])
+  #   puts "Cached #{results[:success].size} prompts"
+  #
+  # @example Warm cache with error handling
+  #   warmer = Langfuse::CacheWarmer.new(client: my_client)
+  #   results = warmer.warm(['greeting', 'conversation'])
+  #
+  #   results[:failed].each do |failure|
+  #     logger.warn "Failed to cache #{failure[:name]}: #{failure[:error]}"
+  #   end
+  #
+  class CacheWarmer
+    attr_reader :client
+
+    # Initialize a new cache warmer
+    #
+    # @param client [Client, nil] Optional Langfuse client (defaults to global client)
+    def initialize(client: nil)
+      @client = client || Langfuse.client
+    end
+
+    # Warm the cache with specified prompts
+    #
+    # Fetches each prompt and populates the cache. This is idempotent -
+    # safe to call multiple times.
+    #
+    # @param prompt_names [Array<String>] List of prompt names to cache
+    # @param versions [Hash<String, Integer>, nil] Optional version numbers per prompt
+    # @param labels [Hash<String, String>, nil] Optional labels per prompt
+    # @return [Hash] Results with :success and :failed arrays
+    #
+    # @example Basic warming
+    #   results = warmer.warm(['greeting', 'conversation'])
+    #   # => { success: ['greeting', 'conversation'], failed: [] }
+    #
+    # @example With specific versions
+    #   results = warmer.warm(
+    #     ['greeting', 'conversation'],
+    #     versions: { 'greeting' => 2, 'conversation' => 1 }
+    #   )
+    #
+    # @example With labels
+    #   results = warmer.warm(
+    #     ['greeting', 'conversation'],
+    #     labels: { 'greeting' => 'production' }
+    #   )
+    def warm(prompt_names, versions: {}, labels: {})
+      results = { success: [], failed: [] }
+
+      prompt_names.each do |name|
+        warm_single_prompt(name, results, versions, labels)
+      end
+
+      results
+    end
+
+    # Warm the cache with all prompts (auto-discovery)
+    #
+    # Automatically discovers all prompts in your Langfuse project via
+    # the list_prompts API and warms the cache with all of them.
+    # By default, fetches prompts with the "production" label.
+    # Useful for deployment scenarios where you want to ensure all prompts
+    # are cached without manually specifying them.
+    #
+    # @param default_label [String, nil] Label to use for all prompts (default: "production")
+    # @param versions [Hash<String, Integer>, nil] Optional version numbers per prompt
+    # @param labels [Hash<String, String>, nil] Optional labels per specific prompts (overrides default_label)
+    # @return [Hash] Results with :success and :failed arrays
+    #
+    # @example Auto-discover and warm all prompts with "production" label
+    #   results = warmer.warm_all
+    #   puts "Cached #{results[:success].size} prompts"
+    #
+    # @example Warm with a different default label
+    #   results = warmer.warm_all(default_label: "staging")
+    #
+    # @example Warm without any label (latest versions)
+    #   results = warmer.warm_all(default_label: nil)
+    #
+    # @example With specific versions for some prompts
+    #   results = warmer.warm_all(versions: { 'greeting' => 2 })
+    #
+    # @example Override label for specific prompts
+    #   results = warmer.warm_all(
+    #     default_label: "production",
+    #     labels: { 'greeting' => 'staging' }  # Use staging for this one
+    #   )
+    def warm_all(default_label: "production", versions: {}, labels: {})
+      prompt_list = client.list_prompts
+      prompt_names = prompt_list.map { |p| p["name"] }.uniq
+
+      # Build labels hash: apply default_label to all prompts, then merge overrides
+      # BUT: if a version is specified for a prompt, don't apply a label (version takes precedence)
+      final_labels = {}
+      if default_label
+        prompt_names.each do |name|
+          # Only apply default label if no version specified for this prompt
+          final_labels[name] = default_label unless versions[name]
+        end
+      end
+      final_labels.merge!(labels) # Specific label overrides win
+
+      warm(prompt_names, versions: versions, labels: final_labels)
+    end
+
+    # Warm the cache and raise on any failures
+    #
+    # Same as #warm but raises an error if any prompts fail to cache.
+    # Useful when you want to abort deployment if cache warming fails.
+    #
+    # @param prompt_names [Array<String>] List of prompt names to cache
+    # @param versions [Hash<String, Integer>, nil] Optional version numbers per prompt
+    # @param labels [Hash<String, String>, nil] Optional labels per prompt
+    # @return [Hash] Results with :success array
+    # @raise [CacheWarmingError] if any prompts fail to cache
+    #
+    # @example
+    #   begin
+    #     warmer.warm!(['greeting', 'conversation'])
+    #   rescue Langfuse::CacheWarmingError => e
+    #     abort "Cache warming failed: #{e.message}"
+    #   end
+    def warm!(prompt_names, versions: {}, labels: {})
+      results = warm(prompt_names, versions: versions, labels: labels)
+
+      if results[:failed].any?
+        failed_names = results[:failed].map { |f| f[:name] }.join(", ")
+        raise CacheWarmingError, "Failed to cache prompts: #{failed_names}"
+      end
+
+      results
+    end
+
+    # Check if cache warming is enabled
+    #
+    # Returns false if caching is disabled (cache_ttl = 0)
+    #
+    # @return [Boolean]
+    def cache_enabled?
+      cache = client.api_client.cache
+      return false if cache.nil?
+
+      cache.ttl&.positive? || false
+    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
+    end
+
+    private
+
+    # Warm a single prompt and update results
+    #
+    # @param name [String] Prompt name
+    # @param results [Hash] Results hash to update
+    # @param versions [Hash] Version numbers per prompt
+    # @param labels [Hash] Labels per prompt
+    # @return [void]
+    def warm_single_prompt(name, results, versions, labels)
+      options = build_prompt_options(name, versions, labels)
+
+      client.get_prompt(name, **options)
+      results[:success] << name
+    rescue NotFoundError
+      record_failure(results, name, "Not found")
+    rescue UnauthorizedError
+      record_failure(results, name, "Unauthorized")
+    rescue ApiError, StandardError => e
+      record_failure(results, name, e.message)
+    end
+
+    # Build options hash for get_prompt
+    #
+    # @param name [String] Prompt name
+    # @param versions [Hash] Version numbers per prompt
+    # @param labels [Hash] Labels per prompt
+    # @return [Hash] Options hash
+    def build_prompt_options(name, versions, labels)
+      options = {}
+      options[:version] = versions[name] if versions[name]
+      options[:label] = labels[name] if labels[name]
+      options
+    end
+
+    # Record a prompt failure
+    #
+    # @param results [Hash] Results hash to update
+    # @param name [String] Prompt name
+    # @param error [String] Error message
+    # @return [void]
+    def record_failure(results, name, error)
+      results[:failed] << { name: name, error: error }
+    end
+  end
+
+  # Error raised when cache warming fails with warm!
+  class CacheWarmingError < Error; end
+end

data/lib/langfuse/chat_prompt_client.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "mustache"
+
+module Langfuse
+  # Chat prompt client for compiling chat prompts with variable substitution
+  #
+  # Handles chat-based prompts from Langfuse, providing Mustache templating
+  # for variable substitution in role-based messages.
+  #
+  # @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" })
+  #   # => [{ role: "system", content: "You are a support agent..." }, ...]
+  #
+  # @example Accessing metadata
+  #   chat_prompt.name      # => "support_chat"
+  #   chat_prompt.version   # => 1
+  #   chat_prompt.labels    # => ["production"]
+  #
+  class ChatPromptClient
+    attr_reader :name, :version, :labels, :tags, :config, :prompt
+
+    # Initialize a new chat prompt client
+    #
+    # @param prompt_data [Hash] The prompt data from the API
+    # @raise [ArgumentError] if prompt data is invalid
+    def initialize(prompt_data)
+      validate_prompt_data!(prompt_data)
+
+      @name = prompt_data["name"]
+      @version = prompt_data["version"]
+      @prompt = prompt_data["prompt"]
+      @labels = prompt_data["labels"] || []
+      @tags = prompt_data["tags"] || []
+      @config = prompt_data["config"] || {}
+    end
+
+    # Compile the chat prompt with variable substitution
+    #
+    # 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.
+    #
+    # @param kwargs [Hash] Variables to substitute in message templates (as keyword arguments)
+    # @return [Array<Hash>] Array of compiled messages with :role and :content keys
+    #
+    # @example
+    #   chat_prompt.compile(name: "Alice", topic: "Ruby")
+    #   # => [
+    #   #   { role: :system, content: "You are a helpful assistant." },
+    #   #   { role: :user, content: "Hello Alice, let's discuss Ruby!" }
+    #   # ]
+    def compile(**kwargs)
+      prompt.map do |message|
+        compile_message(message, kwargs)
+      end
+    end
+
+    private
+
+    # Validate prompt data structure
+    #
+    # @param prompt_data [Hash] The prompt data to validate
+    # @raise [ArgumentError] if validation fails
+    def validate_prompt_data!(prompt_data)
+      raise ArgumentError, "prompt_data must be a Hash" unless prompt_data.is_a?(Hash)
+      raise ArgumentError, "prompt_data must include 'prompt' field" unless prompt_data.key?("prompt")
+      raise ArgumentError, "prompt_data must include 'name' field" unless prompt_data.key?("name")
+      raise ArgumentError, "prompt_data must include 'version' field" unless prompt_data.key?("version")
+      raise ArgumentError, "prompt must be an Array" unless prompt_data["prompt"].is_a?(Array)
+    end
+
+    # Compile a single message with variable substitution
+    #
+    # @param message [Hash] The message with role and content
+    # @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
+      }
+    end
+
+    # Normalize role to symbol
+    #
+    # @param role [String, Symbol] The role
+    # @return [Symbol] Normalized role as symbol
+    def normalize_role(role)
+      role.to_s.downcase.to_sym
+    end
+  end
+end

data/lib/langfuse/client.rb

@@ -0,0 +1,338 @@
+# frozen_string_literal: true
+
+module Langfuse
+  # Main client for Langfuse SDK
+  #
+  # Provides a unified interface for interacting with the Langfuse API.
+  # Handles prompt fetching and returns the appropriate prompt client
+  # (TextPromptClient or ChatPromptClient) based on the prompt type.
+  #
+  # @example
+  #   config = Langfuse::Config.new(
+  #     public_key: "pk_...",
+  #     secret_key: "sk_...",
+  #     cache_ttl: 120
+  #   )
+  #   client = Langfuse::Client.new(config)
+  #   prompt = client.get_prompt("greeting")
+  #   compiled = prompt.compile(name: "Alice")
+  #
+  class Client
+    attr_reader :config, :api_client
+
+    # Initialize a new Langfuse client
+    #
+    # @param config [Config] Configuration object
+    def initialize(config)
+      @config = config
+      @config.validate!
+
+      # Create cache if enabled
+      cache = create_cache if cache_enabled?
+
+      # Create API client with cache
+      @api_client = ApiClient.new(
+        public_key: config.public_key,
+        secret_key: config.secret_key,
+        base_url: config.base_url,
+        timeout: config.timeout,
+        logger: config.logger,
+        cache: cache
+      )
+
+      # Initialize score client for batching score events
+      @score_client = ScoreClient.new(api_client: @api_client, config: config)
+    end
+
+    # Fetch a prompt and return the appropriate client
+    #
+    # Fetches the prompt from the Langfuse API and returns either a
+    # TextPromptClient or ChatPromptClient based on the prompt type.
+    #
+    # @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)
+    # @return [TextPromptClient, ChatPromptClient] The prompt client
+    # @raise [ArgumentError] if both version and label are provided
+    # @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
+    #
+    # @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
+
+      # Try to fetch from API
+      prompt_data = api_client.get_prompt(name, version: version, label: label)
+      build_prompt_client(prompt_data)
+    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)
+    end
+
+    # List all prompts in the Langfuse project
+    #
+    # Fetches a list of all prompt names available in your project.
+    # Returns metadata only, not full prompt content.
+    #
+    # @param page [Integer, nil] Optional page number for pagination
+    # @param limit [Integer, nil] Optional limit per page
+    # @return [Array<Hash>] Array of prompt metadata hashes
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] for other API errors
+    #
+    # @example
+    #   prompts = client.list_prompts
+    #   prompts.each do |prompt|
+    #     puts "#{prompt['name']} (v#{prompt['version']})"
+    #   end
+    def list_prompts(page: nil, limit: nil)
+      api_client.list_prompts(page: page, limit: limit)
+    end
+
+    # Convenience method: fetch and compile a prompt in one call
+    #
+    # This is a shorthand for calling get_prompt followed by compile.
+    # Returns the compiled prompt ready to use with your LLM.
+    #
+    # @param name [String] The name of the prompt
+    # @param variables [Hash] Variables to substitute in 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)
+    # @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
+    # @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
+    #
+    # @example Compile a text prompt
+    #   text = client.compile_prompt("greeting", variables: { name: "Alice" })
+    #   # => "Hello Alice!"
+    #
+    # @example Compile a chat prompt
+    #   messages = client.compile_prompt("support-bot", variables: { company: "Acme" })
+    #   # => [{ role: :system, content: "You are a support agent for Acme" }]
+    #
+    # @example With fallback
+    #   text = client.compile_prompt(
+    #     "greeting",
+    #     variables: { name: "Alice" },
+    #     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)
+      prompt.compile(**variables)
+    end
+
+    # Generate URL for viewing a trace in Langfuse UI
+    #
+    # @param trace_id [String] The trace ID (hex-encoded, 32 characters)
+    # @return [String] URL to view the trace
+    #
+    # @example
+    #   url = client.trace_url("abc123...")
+    #   puts "View trace at: #{url}"
+    def trace_url(trace_id)
+      "#{config.base_url}/traces/#{trace_id}"
+    end
+
+    # Create a score event and queue it for batching
+    #
+    # @param name [String] Score name (required)
+    # @param value [Numeric, Integer, String] Score value (type depends on data_type)
+    # @param trace_id [String, nil] Trace ID to associate with the score
+    # @param observation_id [String, nil] Observation ID to associate with the score
+    # @param comment [String, nil] Optional comment
+    # @param metadata [Hash, nil] Optional metadata hash
+    # @param data_type [Symbol] Data type (:numeric, :boolean, :categorical)
+    # @return [void]
+    # @raise [ArgumentError] if validation fails
+    #
+    # @example Numeric score
+    #   client.create_score(name: "quality", value: 0.85, trace_id: "abc123")
+    #
+    # @example Boolean score
+    #   client.create_score(name: "passed", value: true, trace_id: "abc123", data_type: :boolean)
+    #
+    # @example Categorical score
+    #   client.create_score(name: "category", value: "high", trace_id: "abc123", data_type: :categorical)
+    # rubocop:disable Metrics/ParameterLists
+    def create_score(name:, value:, trace_id: nil, observation_id: nil, comment: nil, metadata: nil,
+                     data_type: :numeric)
+      @score_client.create(
+        name: name,
+        value: value,
+        trace_id: trace_id,
+        observation_id: observation_id,
+        comment: comment,
+        metadata: metadata,
+        data_type: data_type
+      )
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    # Create a score for the currently active observation (from OTel span)
+    #
+    # Extracts observation_id and trace_id from the active OpenTelemetry span.
+    #
+    # @param name [String] Score name (required)
+    # @param value [Numeric, Integer, String] Score value
+    # @param comment [String, nil] Optional comment
+    # @param metadata [Hash, nil] Optional metadata hash
+    # @param data_type [Symbol] Data type (:numeric, :boolean, :categorical)
+    # @return [void]
+    # @raise [ArgumentError] if no active span or validation fails
+    #
+    # @example
+    #   Langfuse.observe("operation") do |obs|
+    #     client.score_active_observation(name: "accuracy", value: 0.92)
+    #   end
+    def score_active_observation(name:, value:, comment: nil, metadata: nil, data_type: :numeric)
+      @score_client.score_active_observation(
+        name: name,
+        value: value,
+        comment: comment,
+        metadata: metadata,
+        data_type: data_type
+      )
+    end
+
+    # Create a score for the currently active trace (from OTel span)
+    #
+    # Extracts trace_id from the active OpenTelemetry span.
+    #
+    # @param name [String] Score name (required)
+    # @param value [Numeric, Integer, String] Score value
+    # @param comment [String, nil] Optional comment
+    # @param metadata [Hash, nil] Optional metadata hash
+    # @param data_type [Symbol] Data type (:numeric, :boolean, :categorical)
+    # @return [void]
+    # @raise [ArgumentError] if no active span or validation fails
+    #
+    # @example
+    #   Langfuse.observe("operation") do |obs|
+    #     client.score_active_trace(name: "overall_quality", value: 5)
+    #   end
+    def score_active_trace(name:, value:, comment: nil, metadata: nil, data_type: :numeric)
+      @score_client.score_active_trace(
+        name: name,
+        value: value,
+        comment: comment,
+        metadata: metadata,
+        data_type: data_type
+      )
+    end
+
+    # Force flush all queued score events
+    #
+    # Sends all queued score events to the API immediately.
+    #
+    # @return [void]
+    #
+    # @example
+    #   client.flush_scores
+    def flush_scores
+      @score_client.flush
+    end
+
+    # Shutdown the client and flush any pending scores
+    #
+    # @return [void]
+    def shutdown
+      @score_client.shutdown
+    end
+
+    private
+
+    attr_reader :score_client
+
+    # Check if caching is enabled in configuration
+    #
+    # @return [Boolean]
+    def cache_enabled?
+      config.cache_ttl&.positive?
+    end
+
+    # Create a cache instance based on configuration
+    #
+    # @return [PromptCache, RailsCacheAdapter]
+    def create_cache
+      case config.cache_backend
+      when :memory
+        PromptCache.new(
+          ttl: config.cache_ttl,
+          max_size: config.cache_max_size
+        )
+      when :rails
+        RailsCacheAdapter.new(
+          ttl: config.cache_ttl,
+          lock_timeout: config.cache_lock_timeout
+        )
+      else
+        raise ConfigurationError, "Unknown cache backend: #{config.cache_backend}"
+      end
+    end
+
+    # Build the appropriate prompt client based on prompt type
+    #
+    # @param prompt_data [Hash] The prompt data from API
+    # @return [TextPromptClient, ChatPromptClient]
+    # @raise [ApiError] if prompt type is unknown
+    def build_prompt_client(prompt_data)
+      type = prompt_data["type"]
+
+      case type
+      when "text"
+        TextPromptClient.new(prompt_data)
+      when "chat"
+        ChatPromptClient.new(prompt_data)
+      else
+        raise ApiError, "Unknown prompt type: #{type}"
+      end
+    end
+
+    # Build a fallback prompt client from fallback data
+    #
+    # @param name [String] The prompt name
+    # @param fallback [String, Array] The fallback prompt content
+    # @param type [Symbol] The prompt type (:text or :chat)
+    # @return [TextPromptClient, ChatPromptClient]
+    # @raise [ArgumentError] if type is invalid
+    def build_fallback_prompt_client(name, fallback, type)
+      # Create minimal prompt data structure
+      prompt_data = {
+        "name" => name,
+        "version" => 0,
+        "type" => type.to_s,
+        "prompt" => fallback,
+        "labels" => [],
+        "tags" => ["fallback"],
+        "config" => {}
+      }
+
+      case type
+      when :text
+        TextPromptClient.new(prompt_data)
+      when :chat
+        ChatPromptClient.new(prompt_data)
+      else
+        raise ArgumentError, "Invalid type: #{type}. Must be :text or :chat"
+      end
+    end
+  end
+end