langfuse-rb 0.10.1 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 06f62784113cec51196e77ba4604d8a056b0cd2fbeaccc950af44311cf428ae2
-  data.tar.gz: 96c3b104d313ed20a17ce199b7999cd91d4cf5a9f34482e7ef4d1a8508a00f0e
+  metadata.gz: cdad4b4c1edea98dac2e1929430a30fd8cf7b8831a6603b41192055f20f76516
+  data.tar.gz: 526062c59b48af70225ee68a44ef70ef127cb2cf83ba33f5f5e314597e680d9a
 SHA512:
-  metadata.gz: a5516b70bf74c36dd05c9766b5105d7ba9d249743b3b77f7136f73c7f4a2fe554cad109424ef4afc381f71cf5353d28248a97cce2e526c3cd8918a9a877250b8
-  data.tar.gz: 5eb592bf72abb6634413d7bb5de38cf188dac7cfae59cebbc7ee3810c875cdb4e2bbd037fca73165fa2e4b72ac966bf302b0629feabebd80adf128a04e7af7c7
+  metadata.gz: 4bf11c145c2c13a2ed6af21a8c0936781034c66516084896d22dc4510537da26234a4bd8f3ff070472e42f13aba88d94efabbfa753bb9dd837e0cf978a1d8fb5
+  data.tar.gz: 2ef511ee676296bdfb78523a04b345e3ea6705e3c82bed4102bfd49722775929a651c5059572b76f9b49ee3308962d8b562abbab2b99b4dfc839cd6af414e075

data/CHANGELOG.md

@@ -7,6 +7,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.11.0] - 2026-08-19
+
+> [!NOTE]
+> **Contributor acknowledgment:** Thank you to [Alan Marx](https://github.com/Alan-Marx) for contributions in #98, #99, #100, and #102.
+
+### Added
+- Read current observations, metrics, and typed scores through the client API (#95).
+- Create and read text and correction scores (#97, #102).
+- Create scores synchronously and receive the created score ID (#102).
+- Check global client readiness locally with `Langfuse.configured?` (#98).
+- Send OpenTelemetry batch processor metrics to an application reporter (#99).
+- Inject an OpenTelemetry span exporter into the Langfuse tracing pipeline (#100).
+- Inspect referenced Mustache variables in source order (#111).
+- Disable Langfuse tracing and scoring with one configuration switch (#110).
+
+### Changed
+- Export traces through direct Langfuse v4 OTLP ingestion (#103).
+- Read timeout, batch, flush interval, and debug defaults from environment variables (#106).
+- Bound the asynchronous score queue and split large batch payloads (#109).
+- Reject invalid batch settings during client construction (#109).
+- Require non-empty API keys and an absolute HTTP or HTTPS base URL (#98).
+- Use a null logger when `Config#logger` is `nil` (#98).
+- Use a no-op tracer for implicit observations when tracing configuration is invalid (#98).
+
+### Fixed
+- Mask third-party OpenTelemetry spans without changing spans for other exporters (#96).
+- Reset SDK queues and workers after Ruby `fork` (#107).
+- Flush pending spans and scores during normal process exit (#108).
+- Apply the configured environment to scores without an explicit override (#105).
+- Report invalid numeric, cache, and tracing settings as `ConfigurationError` (#98).
+- Validate tracing batch and sampling settings before processor creation (#98).
+- Reject explicit Rails cache configuration when `Rails.cache` is unavailable (#98).
+
+### Documentation
+- Organize the SDK guides by task and add data-access verification guidance (#113).
+
 ## [0.10.1] - 2026-05-05
 
 ### Changed
@@ -129,7 +165,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Migrated from legacy ingestion API to OTLP endpoint
 - Removed `tracing_enabled` configuration flag (#2)
 
-[Unreleased]: https://github.com/simplepractice/langfuse-rb/compare/v0.10.1...HEAD
+[Unreleased]: https://github.com/simplepractice/langfuse-rb/compare/v0.11.0...HEAD
+[0.11.0]: https://github.com/simplepractice/langfuse-rb/compare/v0.10.1...v0.11.0
 [0.10.1]: https://github.com/simplepractice/langfuse-rb/compare/v0.10.0...v0.10.1
 [0.10.0]: https://github.com/simplepractice/langfuse-rb/compare/v0.9.0...v0.10.0
 [0.9.0]: https://github.com/simplepractice/langfuse-rb/compare/v0.8.0...v0.9.0

data/lib/langfuse/api_client.rb

@@ -7,6 +7,7 @@ require "json"
 require "uri"
 require_relative "prompt_fetch_result"
 require_relative "prompt_cache_coordinator"
+require_relative "read_api"
 
 module Langfuse
   # HTTP client for Langfuse API
@@ -25,6 +26,7 @@ module Langfuse
   #
   class ApiClient # rubocop:disable Metrics/ClassLength
     include PromptCacheEvents
+    include ReadApi
 
     # @return [String] Langfuse public API key
     attr_reader :public_key
@@ -301,7 +303,21 @@ module Langfuse
       handle_batch_response(e.response)
     rescue Faraday::Error => e
       logger.error("Langfuse batch send failed: #{e.message}")
-      raise ApiError, "Batch send failed: #{e.message}"
+      raise BatchDeliveryError.new("Batch send failed: #{e.message}", retryable: true)
+    end
+
+    # Create a score through the synchronous Scores API.
+    #
+    # @param payload [Hash] Validated score attributes in API format
+    # @return [String] ID of the created score
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] if the API request fails or omits the created score ID
+    def create_score(payload:)
+      response = request(:post, "/api/public/scores", body: payload)
+      score_id = response["id"]
+      return score_id if score_id.is_a?(String) && !score_id.empty?
+
+      raise ApiError, "Score creation response did not include an id"
     end
 
     # Create a dataset run item (link a trace to a dataset item within a run)
@@ -625,10 +641,14 @@ module Langfuse
     # @param path [String] Request path
     # @param params [Hash, nil] Query string params (GET/DELETE)
     # @param body [Hash, nil] JSON body (POST/PATCH)
+    # @param params_encoder [Object, nil] Faraday query encoder for this request
     # @return [Hash] Parsed response body
-    def request(verb, path, params: nil, body: nil)
+    def request(verb, path, params: nil, body: nil, params_encoder: nil)
       with_faraday_error_handling do
-        handle_response(connection.public_send(verb, path, body || params))
+        response = connection.public_send(verb, path, body || params) do |faraday_request|
+          faraday_request.options.params_encoder = params_encoder if params_encoder
+        end
+        handle_response(response)
       end
     end
 
@@ -689,7 +709,7 @@ module Langfuse
     # - Max 2 retries (3 total attempts)
     # - Exponential backoff (0.05s * 2^retry_count)
     # - Retries GET, PATCH, and DELETE requests (idempotent operations)
-    # - Retries POST requests to batch endpoint (idempotent due to event UUIDs)
+    # - Retries ingestion batches and score creation (both include stable IDs)
     # - Note: POST to create_prompt is NOT idempotent; retries may create duplicate versions
     # - Retries on: 429 (rate limit), 503 (service unavailable), 504 (gateway timeout)
     # - Does NOT retry on: 4xx errors (except 429), 5xx errors (except 503, 504)
@@ -780,38 +800,77 @@ module Langfuse
 
     # Handle HTTP response for batch requests
     #
+    # Per-event input errors can arrive with HTTP 207 instead of a 4xx response.
+    # The `errors` array reports rejected events, so HTTP status alone cannot
+    # identify a batch with rejected events. An empty array confirms only that
+    # the response reported no rejection; it does not prove downstream
+    # processing or immediate read visibility.
+    #
     # @param response [Faraday::Response] The HTTP response
     # @return [void]
     # @raise [UnauthorizedError] if status is 401
-    # @raise [ApiError] for other error statuses
+    # @raise [ApiError] for other error statuses, or if the body lists rejected events
     def handle_batch_response(response)
       case response.status
       when 200, 201, 204, 207
-        nil
+        raise_on_batch_errors(response)
       when 401
         raise UnauthorizedError, "Authentication failed. Check your API keys."
       else
         error_message = extract_error_message(response)
-        raise ApiError, "Batch send failed (#{response.status}): #{error_message}"
+        raise BatchDeliveryError.new(
+          "Batch send failed (#{response.status}): #{error_message}",
+          retryable: retryable_batch_status?(response.status)
+        )
       end
     end
 
+    # @param response [Faraday::Response] The HTTP response
+    # @return [void]
+    # @raise [ApiError] if the response body's `errors` array is non-empty
+    def raise_on_batch_errors(response)
+      errors = Array(parse_response_body(response)["errors"])
+      return if errors.empty?
+
+      messages = errors.filter_map { |e| e["message"] || e["error"] }
+      summary = messages.empty? ? "#{errors.size} event(s) rejected" : messages.join("; ")
+      raise BatchDeliveryError.new(
+        "Batch send failed: #{summary}",
+        retryable: retryable_batch_errors?(errors)
+      )
+    end
+
+    def retryable_batch_errors?(errors)
+      statuses = errors.filter_map { |error| Integer(error["status"], exception: false) }
+      statuses.length == errors.length && statuses.all? { |status| retryable_batch_status?(status) }
+    end
+
+    def retryable_batch_status?(status)
+      status == 429 || status >= 500
+    end
+
     # Extract error message from response body
     #
     # @param response [Faraday::Response] The HTTP response
     # @return [String] The error message
     def extract_error_message(response)
-      body_hash = case response.body
-                  in Hash => h then h
-                  in String => s then begin
-                    JSON.parse(s)
-                  rescue StandardError
-                    {}
-                  end
-                  else {}
-                  end
+      body_hash = parse_response_body(response)
 
       %w[message error].filter_map { |key| body_hash[key] }.first || "Unknown error"
     end
+
+    # @param response [Faraday::Response] The HTTP response
+    # @return [Hash] The parsed JSON body, or {} if absent/unparsable
+    def parse_response_body(response)
+      case response.body
+      in Hash => h then h
+      in String => s then begin
+        JSON.parse(s)
+      rescue StandardError
+        {}
+      end
+      else {}
+      end
+    end
   end
 end

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/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
@@ -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.

data/lib/langfuse/client.rb

@@ -29,8 +29,13 @@ module Langfuse
     # @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.
@@ -44,6 +49,9 @@ module Langfuse
     # @!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(**)
@@ -57,6 +65,9 @@ module Langfuse
                    :validate_prompt_cache_backend!,
                    :list_traces,
                    :get_trace,
+                   :list_observations,
+                   :query_metrics,
+                   :list_scores,
                    :list_datasets,
                    :get_dataset_run,
                    :create_dataset_run_item
@@ -67,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
@@ -347,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]
@@ -368,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,
@@ -396,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
     #
@@ -405,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,
@@ -422,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
     #
@@ -431,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,
@@ -449,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
@@ -458,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
@@ -660,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
@@ -790,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