langfuse-rb 0.10.0 → 0.11.0

data/lib/langfuse/client.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "forwardable"
+
 module Langfuse
   # Main client for Langfuse SDK
   #
@@ -19,14 +21,56 @@ module Langfuse
   #
   # rubocop:disable Metrics/ClassLength
   class Client
+    extend Forwardable
+
     # @return [Integer] Default page size when fetching all dataset items
     DATASET_ITEMS_PAGE_SIZE = 50
 
     # @return [Config] The client configuration
     attr_reader :config
 
+    # Return the underlying API client, building it on first non-telemetry use.
+    #
     # @return [ApiClient] The underlying API client
-    attr_reader :api_client
+    # @raise [ConfigurationError] if the full client configuration is invalid
+    def api_client
+      @api_client || @api_client_mutex.synchronize { @api_client ||= build_validated_api_client }
+    end
+
+    # Pure pass-throughs to {ApiClient}. See {ApiClient} for parameter and
+    # return-value documentation; the public surface here is identical.
+    #
+    # @!method list_prompts(page: nil, limit: nil)
+    # @!method invalidate_prompt_cache(name, version: nil, label: nil)
+    # @!method invalidate_prompt_cache_by_name(name)
+    # @!method clear_prompt_cache
+    # @!method prompt_cache_stats
+    # @!method prompt_cache_key(name, version: nil, label: nil)
+    # @!method validate_prompt_cache_backend!
+    # @!method list_traces(**options)
+    # @!method get_trace(id)
+    # @!method list_observations(**options)
+    # @!method query_metrics(query:)
+    # @!method list_scores(**options)
+    # @!method list_datasets(page: nil, limit: nil)
+    # @!method get_dataset_run(dataset_name:, run_name:)
+    # @!method create_dataset_run_item(**)
+    def_delegators :api_client,
+                   :list_prompts,
+                   :invalidate_prompt_cache,
+                   :invalidate_prompt_cache_by_name,
+                   :clear_prompt_cache,
+                   :prompt_cache_stats,
+                   :prompt_cache_key,
+                   :validate_prompt_cache_backend!,
+                   :list_traces,
+                   :get_trace,
+                   :list_observations,
+                   :query_metrics,
+                   :list_scores,
+                   :list_datasets,
+                   :get_dataset_run,
+                   :create_dataset_run_item
 
     # Initialize a new Langfuse client
     #
@@ -34,29 +78,19 @@ module Langfuse
     # @return [Client]
     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,
-        cache_observer: config.prompt_cache_observer
-      )
-
+      @api_client_mutex = Mutex.new
+      @score_client_mutex = Mutex.new
       @project_id = nil
       # One-shot lookup: avoids repeated blocking API calls in URL helpers
       # (trace_url, dataset_url, dataset_run_url) when the project endpoint is down.
       @project_id_fetched = false
-
-      # Initialize score client for batching score events
-      @score_client = ScoreClient.new(api_client: @api_client, config: config)
+      if telemetry_enabled?
+        config.validate!
+        @api_client = build_api_client
+        @score_client = build_score_client
+      else
+        config.validate_telemetry_disabled!
+      end
     end
 
     # Fetch a prompt and return the appropriate client
@@ -134,79 +168,6 @@ module Langfuse
       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.
-    # 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.
@@ -387,14 +348,14 @@ module Langfuse
     #
     # @param name [String] Score name (required)
     # @param value [Numeric, Integer, String] Score value (type depends on data_type)
-    # @param id [String, nil] Score ID
+    # @param id [String, nil] Score ID; use a stable value as an idempotency key
     # @param trace_id [String, nil] Trace ID to associate with the score
     # @param session_id [String, nil] Session 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 environment [String, nil] Optional environment
-    # @param data_type [Symbol] Data type (:numeric, :boolean, :categorical)
+    # @param environment [String, nil] Optional per-score environment override
+    # @param data_type [Symbol] Data type (:numeric, :boolean, :categorical, :text, :correction)
     # @param dataset_run_id [String, nil] Optional dataset run ID to associate with the score
     # @param config_id [String, nil] Optional score config ID
     # @return [void]
@@ -408,10 +369,59 @@ module Langfuse
     #
     # @example Categorical score
     #   client.create_score(name: "category", value: "high", trace_id: "abc123", data_type: :categorical)
+    #
+    # @example Text score (1 to 500 characters)
+    #   client.create_score(name: "reviewer_notes", value: "Helpful but verbose",
+    #                       trace_id: "abc123", data_type: :text)
+    #
+    # @example Corrected output (conventionally named "output")
+    #   client.create_score(name: "output", value: "The corrected output", trace_id: "abc123",
+    #                       observation_id: "def456", data_type: :correction)
     # rubocop:disable Metrics/ParameterLists
     def create_score(name:, value:, id: nil, trace_id: nil, session_id: nil, observation_id: nil, comment: nil,
                      metadata: nil, environment: nil, data_type: :numeric, dataset_run_id: nil, config_id: nil)
-      @score_client.create(
+      active_score_client&.create(
+        name: name,
+        value: value,
+        id: id,
+        trace_id: trace_id,
+        session_id: session_id,
+        observation_id: observation_id,
+        comment: comment,
+        metadata: metadata,
+        environment: environment,
+        data_type: data_type,
+        dataset_run_id: dataset_run_id,
+        config_id: config_id
+      )
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    # Create a score immediately through the Scores API. See {ScoreClient#create!}.
+    #
+    # @param name [String] Score name (required)
+    # @param value [Numeric, Integer, String] Score value (type depends on data_type)
+    # @param id [String, nil] Score ID; use a stable value as an idempotency key
+    # @param trace_id [String, nil] Trace ID to associate with the score
+    # @param session_id [String, nil] Session 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 environment [String, nil] Optional per-score environment override
+    # @param data_type [Symbol] Data type (:numeric, :boolean, :categorical, :text, :correction)
+    # @param dataset_run_id [String, nil] Optional dataset run ID to associate with the score
+    # @param config_id [String, nil] Optional score config ID
+    # @return [String, nil] ID of the created score, or nil when telemetry is disabled
+    # @raise [ArgumentError] if validation fails
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] if the API request fails
+    #
+    # @example Create a score with an idempotency key
+    #   client.create_score!(id: "feedback-abc123", name: "quality", value: 0.85, trace_id: "abc123")
+    # rubocop:disable Metrics/ParameterLists
+    def create_score!(name:, value:, id: nil, trace_id: nil, session_id: nil, observation_id: nil, comment: nil,
+                      metadata: nil, environment: nil, data_type: :numeric, dataset_run_id: nil, config_id: nil)
+      active_score_client&.create!(
         name: name,
         value: value,
         id: id,
@@ -436,7 +446,7 @@ module Langfuse
     # @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)
+    # @param data_type [Symbol] Data type (:numeric, :boolean, :categorical, :text, :correction)
     # @return [void]
     # @raise [ArgumentError] if no active span or validation fails
     #
@@ -445,7 +455,7 @@ module Langfuse
     #     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(
+      active_score_client&.score_active_observation(
         name: name,
         value: value,
         comment: comment,
@@ -462,7 +472,7 @@ module Langfuse
     # @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)
+    # @param data_type [Symbol] Data type (:numeric, :boolean, :categorical, :text, :correction)
     # @return [void]
     # @raise [ArgumentError] if no active span or validation fails
     #
@@ -471,7 +481,7 @@ module Langfuse
     #     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(
+      active_score_client&.score_active_trace(
         name: name,
         value: value,
         comment: comment,
@@ -489,7 +499,7 @@ module Langfuse
     # @example
     #   client.flush_scores
     def flush_scores
-      @score_client.flush
+      active_score_client&.flush
     end
 
     # Shutdown the client and flush any pending scores
@@ -498,8 +508,8 @@ module Langfuse
     #
     # @return [void]
     def shutdown
-      @score_client.shutdown
-      @api_client.shutdown
+      @score_client&.shutdown
+      @api_client_mutex.synchronize { @api_client }&.shutdown
     end
 
     # Create a new dataset
@@ -533,49 +543,6 @@ module Langfuse
       DatasetClient.new(data, client: self)
     end
 
-    # List all datasets in the project
-    #
-    # @param page [Integer, nil] Optional page number for pagination
-    # @param limit [Integer, nil] Optional limit per page
-    # @return [Array<Hash>] Array of dataset metadata hashes
-    # @raise [UnauthorizedError] if authentication fails
-    # @raise [ApiError] for other API errors
-    #
-    # @example
-    #   datasets = client.list_datasets(page: 1, limit: 10)
-    def list_datasets(page: nil, limit: nil)
-      api_client.list_datasets(page: page, limit: limit)
-    end
-
-    # List traces in the project
-    #
-    # @param page [Integer, nil] Optional page number for pagination
-    # @param limit [Integer, nil] Optional limit per page
-    # @param filters [Hash] Additional filters (user_id, name, session_id, etc.)
-    # @return [Array<Hash>] Array of trace hashes
-    # @raise [UnauthorizedError] if authentication fails
-    # @raise [ApiError] for other API errors
-    #
-    # @example
-    #   traces = client.list_traces(page: 1, limit: 10, name: "my-trace")
-    def list_traces(page: nil, limit: nil, **filters)
-      api_client.list_traces(page: page, limit: limit, **filters)
-    end
-
-    # Fetch a trace by ID
-    #
-    # @param id [String] Trace ID
-    # @return [Hash] The trace data
-    # @raise [NotFoundError] if the trace is not found
-    # @raise [UnauthorizedError] if authentication fails
-    # @raise [ApiError] for other API errors
-    #
-    # @example
-    #   trace = client.get_trace("trace-uuid-123")
-    def get_trace(id)
-      api_client.get_trace(id)
-    end
-
     # Create a new dataset item
     #
     # @param dataset_name [String] Name of the dataset to add item to (required)
@@ -669,39 +636,6 @@ module Langfuse
       nil
     end
 
-    # Create a dataset run item (link a trace to a dataset item)
-    #
-    # @param dataset_item_id [String] Dataset item ID (required)
-    # @param run_name [String] Run name (required)
-    # @param trace_id [String, nil] Trace ID
-    # @param observation_id [String, nil] Observation ID
-    # @param metadata [Hash, nil] Optional metadata
-    # @param run_description [String, nil] Optional run description
-    # @return [Hash] The created dataset run item data
-    def create_dataset_run_item(dataset_item_id:, run_name:, trace_id: nil,
-                                observation_id: nil, metadata: nil, run_description: nil)
-      api_client.create_dataset_run_item(
-        dataset_item_id: dataset_item_id,
-        run_name: run_name,
-        trace_id: trace_id,
-        observation_id: observation_id,
-        metadata: metadata,
-        run_description: run_description
-      )
-    end
-
-    # Fetch a dataset run by dataset and run name
-    #
-    # @param dataset_name [String] Dataset name (required)
-    # @param run_name [String] Run name (required)
-    # @return [Hash] The dataset run data, including linked run items
-    # @raise [NotFoundError] if the dataset run is not found
-    # @raise [UnauthorizedError] if authentication fails
-    # @raise [ApiError] for other API errors
-    def get_dataset_run(dataset_name:, run_name:)
-      api_client.get_dataset_run(dataset_name: dataset_name, run_name: run_name)
-    end
-
     # List dataset runs for a dataset
     #
     # When page is nil (default), auto-paginates to fetch all runs.
@@ -776,6 +710,38 @@ module Langfuse
 
     private
 
+    def build_validated_api_client
+      config.validate!
+      build_api_client
+    end
+
+    def build_api_client
+      cache = create_cache if cache_enabled?
+      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,
+        cache_observer: config.prompt_cache_observer
+      )
+    end
+
+    def telemetry_enabled?
+      config.telemetry_enabled?
+    end
+
+    def active_score_client
+      return unless telemetry_enabled?
+
+      @score_client_mutex.synchronize { @score_client ||= build_score_client }
+    end
+
+    def build_score_client
+      ScoreClient.new(api_client: api_client, config: config)
+    end
+
     attr_reader :score_client
 
     # Build a project-scoped URL, returning nil if project ID is unavailable
@@ -877,7 +843,7 @@ module Langfuse
 
     def fallback_cache_status(cache_ttl)
       return CacheStatus::BYPASS if cache_ttl&.zero?
-      return CacheStatus::DISABLED unless api_client.cache
+      return CacheStatus::DISABLED unless api_client.prompt_cache_stats[:enabled]
 
       CacheStatus::MISS
     end
@@ -906,7 +872,7 @@ module Langfuse
     end
 
     def rails_cache_available?
-      defined?(Rails) && Rails.respond_to?(:cache) && Rails.cache
+      RailsCacheAdapter.available?
     end
 
     # Create in-memory cache with SWR support if enabled
@@ -932,21 +898,22 @@ module Langfuse
       )
     end
 
+    VALID_PROMPT_TYPES = %i[text chat].freeze
+    private_constant :VALID_PROMPT_TYPES
+
     # 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
+    def build_prompt_client(prompt_data, is_fallback: false)
+      case prompt_data["type"]
       when "text"
-        TextPromptClient.new(prompt_data)
+        TextPromptClient.new(prompt_data, is_fallback: is_fallback)
       when "chat"
-        ChatPromptClient.new(prompt_data)
+        ChatPromptClient.new(prompt_data, is_fallback: is_fallback)
       else
-        raise ApiError, "Unknown prompt type: #{type}"
+        raise ApiError, "Unknown prompt type: #{prompt_data['type']}"
       end
     end
 
@@ -959,24 +926,18 @@ module Langfuse
     # @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,
-        "version" => 0,
-        "type" => type.to_s,
-        "prompt" => fallback,
-        "labels" => [],
-        "tags" => ["fallback"],
-        "config" => {}
-      }
-
-      case type
-      when :text
-        TextPromptClient.new(prompt_data, is_fallback: true)
-      when :chat
-        ChatPromptClient.new(prompt_data, is_fallback: true)
-      end
+      build_prompt_client(
+        {
+          "name" => name,
+          "version" => 0,
+          "type" => type.to_s,
+          "prompt" => fallback,
+          "labels" => [],
+          "tags" => ["fallback"],
+          "config" => {}
+        },
+        is_fallback: true
+      )
     end
 
     # Validate prompt type parameter
@@ -984,8 +945,7 @@ module Langfuse
     # @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)
+      return if VALID_PROMPT_TYPES.include?(type)
 
       raise ArgumentError, "Invalid type: #{type}. Must be :text or :chat"
     end
@@ -1015,30 +975,15 @@ module Langfuse
     def normalize_prompt_content(prompt, type)
       return prompt if type == :text
 
-      # Normalize chat messages to use string keys
       prompt.map do |message|
         normalized = message.transform_keys(&:to_s)
-        next placeholder_prompt_content(normalized) if normalized["type"] == ChatPromptClient::PLACEHOLDER_TYPE
-
-        normalize_chat_message_content(normalized)
+        if normalized["type"] == ChatPromptClient::PLACEHOLDER_TYPE
+          { "type" => ChatPromptClient::PLACEHOLDER_TYPE, "name" => normalized["name"].to_s }
+        else
+          normalized.merge("role" => normalized["role"]&.to_s, "content" => normalized["content"])
+        end
       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