langfuse-rb 0.9.0 → 0.10.1

data/lib/langfuse/api_client.rb

@@ -5,6 +5,8 @@ require "faraday/retry"
 require "base64"
 require "json"
 require "uri"
+require_relative "prompt_fetch_result"
+require_relative "prompt_cache_coordinator"
 
 module Langfuse
   # HTTP client for Langfuse API
@@ -22,6 +24,8 @@ module Langfuse
   #   )
   #
   class ApiClient # rubocop:disable Metrics/ClassLength
+    include PromptCacheEvents
+
     # @return [String] Langfuse public API key
     attr_reader :public_key
 
@@ -48,15 +52,24 @@ module Langfuse
     # @param timeout [Integer] HTTP request timeout in seconds
     # @param logger [Logger] Logger instance for debugging
     # @param cache [PromptCache, RailsCacheAdapter, nil] Optional cache for prompt responses
+    # @param cache_observer [#call, nil] Optional observer for prompt cache events
     # @return [ApiClient]
-    def initialize(public_key:, secret_key:, base_url:, timeout: 5, logger: nil, cache: nil)
+    # rubocop:disable Metrics/ParameterLists
+    def initialize(public_key:, secret_key:, base_url:, timeout: 5, logger: nil, cache: nil, cache_observer: nil)
       @public_key = public_key
       @secret_key = secret_key
       @base_url = base_url
       @timeout = timeout
       @logger = logger || Logger.new($stdout, level: Logger::WARN)
       @cache = cache
+      setup_prompt_cache_events(cache_observer: cache_observer)
+      @prompt_cache_coordinator = PromptCacheCoordinator.new(
+        cache: cache,
+        event_emitter: self,
+        fetch_prompt: ->(name, version:, label:) { fetch_prompt_from_api(name, version: version, label: label) }
+      )
     end
+    # rubocop:enable Metrics/ParameterLists
 
     # Get a Faraday connection
     #
@@ -89,15 +102,7 @@ module Langfuse
     #     puts "#{prompt['name']} (v#{prompt['version']})"
     #   end
     def list_prompts(page: nil, limit: nil)
-      with_faraday_error_handling do
-        params = { page: page, limit: limit }.compact
-
-        response = connection.get("/api/public/v2/prompts", params)
-        result = handle_response(response)
-
-        # API returns { data: [...], meta: {...} }
-        result["data"] || []
-      end
+      request(:get, "/api/public/v2/prompts", params: { page: page, limit: limit }.compact)["data"] || []
     end
 
     # Fetch a prompt from the Langfuse API
@@ -109,18 +114,102 @@ module Langfuse
     # @param name [String] The name of the prompt
     # @param version [Integer, nil] Optional specific version number
     # @param label [String, nil] Optional label (e.g., "production", "latest")
+    # @param cache_ttl [Integer, nil] Optional TTL override for this fetch
     # @return [Hash] The prompt data
     # @raise [ArgumentError] if both version and label are provided
     # @raise [NotFoundError] if the prompt is not found
     # @raise [UnauthorizedError] if authentication fails
     # @raise [ApiError] for other API errors
-    def get_prompt(name, version: nil, label: nil)
-      raise ArgumentError, "Cannot specify both version and label" if version && label
-      return fetch_prompt_from_api(name, version: version, label: label) if cache.nil?
+    def get_prompt(name, version: nil, label: nil, cache_ttl: nil)
+      get_prompt_result(name, version: version, label: label, cache_ttl: cache_ttl).prompt
+    end
+
+    # Fetch a prompt and include cache metadata.
+    #
+    # @param name [String] The name of the prompt
+    # @param version [Integer, nil] Optional specific version number
+    # @param label [String, nil] Optional label (e.g., "production", "latest")
+    # @param cache_ttl [Integer, nil] Optional TTL override for this fetch
+    # @return [PromptFetchResult] Prompt data plus cache metadata
+    # @raise [ArgumentError] if both version and label are provided
+    # @raise [ArgumentError] if cache_ttl is negative
+    # @raise [NotFoundError] if the prompt is not found
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] for other API errors
+    def get_prompt_result(name, version: nil, label: nil, cache_ttl: nil)
+      @prompt_cache_coordinator.get_prompt_result(name, version: version, label: label, cache_ttl: cache_ttl)
+    end
+
+    # Refresh a prompt from the API, optionally writing through to cache.
+    #
+    # @param name [String] The name of the prompt
+    # @param version [Integer, nil] Optional specific version number
+    # @param label [String, nil] Optional label
+    # @param cache_ttl [Integer, nil] Optional TTL override for this refresh
+    # @return [PromptFetchResult] Prompt data plus cache metadata
+    # @raise [ArgumentError] if both version and label are provided
+    # @raise [ArgumentError] if cache_ttl is negative
+    # @raise [NotFoundError] if the prompt is not found
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] for other API errors
+    def refresh_prompt(name, version: nil, label: nil, cache_ttl: nil)
+      @prompt_cache_coordinator.refresh_prompt(name, version: version, label: label, cache_ttl: cache_ttl)
+    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
+    # @raise [ArgumentError] if both version and label are provided
+    def prompt_cache_key(name, version: nil, label: nil)
+      @prompt_cache_coordinator.prompt_cache_key(name, version: version, label: label)
+    end
 
-      cache_key = PromptCache.build_key(name, version: version, label: label)
-      fetch_with_appropriate_caching_strategy(cache_key, name, version, label)
+    # 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
+    # @raise [ArgumentError] if both version and label are provided
+    def invalidate_prompt_cache(name, version: nil, label: nil)
+      @prompt_cache_coordinator.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)
+      @prompt_cache_coordinator.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
+      @prompt_cache_coordinator.clear_prompt_cache
+    end
+
+    # Return prompt cache statistics.
+    #
+    # @return [Hash] Cache statistics
+    def prompt_cache_stats
+      @prompt_cache_coordinator.prompt_cache_stats
+    end
+
+    # Validate the configured prompt cache backend.
+    #
+    # @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!
+      @cache&.validate!
+      true
     end
+    # rubocop:enable Naming/PredicateMethod
 
     # Create a new prompt (or new version if prompt with same name exists)
     #
@@ -145,21 +234,12 @@ module Langfuse
     #
     # rubocop:disable Metrics/ParameterLists
     def create_prompt(name:, prompt:, type:, config: {}, labels: [], tags: [], commit_message: nil)
-      with_faraday_error_handling do
-        path = "/api/public/v2/prompts"
-        payload = {
-          name: name,
-          prompt: prompt,
-          type: type,
-          config: config,
-          labels: labels,
-          tags: tags
-        }
-        payload[:commitMessage] = commit_message if commit_message
-
-        response = connection.post(path, payload)
-        handle_response(response)
-      end
+      payload = {
+        name: name, prompt: prompt, type: type, config: config,
+        labels: labels, tags: tags, commitMessage: commit_message
+      }.compact
+      request(:post, "/api/public/v2/prompts", body: payload)
+        .tap { @prompt_cache_coordinator.invalidate_after_mutation(name) }
     end
     # rubocop:enable Metrics/ParameterLists
 
@@ -183,13 +263,9 @@ module Langfuse
     def update_prompt(name:, version:, labels:)
       raise ArgumentError, "labels must be an array" unless labels.is_a?(Array)
 
-      with_faraday_error_handling do
-        path = "/api/public/v2/prompts/#{URI.encode_uri_component(name)}/versions/#{version}"
-        payload = { newLabels: labels }
-
-        response = connection.patch(path, payload)
-        handle_response(response)
-      end
+      path = "/api/public/v2/prompts/#{URI.encode_uri_component(name)}/versions/#{version}"
+      request(:patch, path, body: { newLabels: labels })
+        .tap { @prompt_cache_coordinator.invalidate_after_mutation(name) }
     end
 
     # Send a batch of events to the Langfuse ingestion API
@@ -218,13 +294,9 @@ module Langfuse
       raise ArgumentError, "events must be an array" unless events.is_a?(Array)
       raise ArgumentError, "events array cannot be empty" if events.empty?
 
-      path = "/api/public/ingestion"
-      payload = { batch: events }
-
-      response = connection.post(path, payload)
+      response = connection.post("/api/public/ingestion", { batch: events })
       handle_batch_response(response)
     rescue Faraday::RetriableResponse => e
-      # Retry middleware exhausted all retries - handle the final response
       logger.error("Langfuse batch send failed: Retries exhausted - #{e.response.status}")
       handle_batch_response(e.response)
     rescue Faraday::Error => e
@@ -248,16 +320,12 @@ module Langfuse
     #   api_client.create_dataset_run_item(dataset_item_id: "item-123", run_name: "eval-v1", trace_id: "trace-abc")
     def create_dataset_run_item(dataset_item_id:, run_name:, trace_id: nil,
                                 observation_id: nil, metadata: nil, run_description: nil)
-      with_faraday_error_handling do
-        payload = { datasetItemId: dataset_item_id, runName: run_name }
-        payload[:traceId] = trace_id if trace_id
-        payload[:observationId] = observation_id if observation_id
-        payload[:metadata] = metadata if metadata
-        payload[:runDescription] = run_description if run_description
-
-        response = connection.post("/api/public/dataset-run-items", payload)
-        handle_response(response)
-      end
+      payload = {
+        datasetItemId: dataset_item_id, runName: run_name,
+        traceId: trace_id, observationId: observation_id,
+        metadata: metadata, runDescription: run_description
+      }.compact
+      request(:post, "/api/public/dataset-run-items", body: payload)
     end
 
     # Fetch a dataset run by dataset and run name
@@ -269,10 +337,7 @@ module Langfuse
     # @raise [UnauthorizedError] if authentication fails
     # @raise [ApiError] for other API errors
     def get_dataset_run(dataset_name:, run_name:)
-      with_faraday_error_handling do
-        response = connection.get(dataset_run_path(dataset_name: dataset_name, run_name: run_name))
-        handle_response(response)
-      end
+      request(:get, dataset_run_path(dataset_name: dataset_name, run_name: run_name))
     end
 
     # List dataset runs in a dataset
@@ -284,8 +349,7 @@ module Langfuse
     # @raise [UnauthorizedError] if authentication fails
     # @raise [ApiError] for other API errors
     def list_dataset_runs(dataset_name:, page: nil, limit: nil)
-      result = list_dataset_runs_paginated(dataset_name: dataset_name, page: page, limit: limit)
-      result["data"] || []
+      list_dataset_runs_paginated(dataset_name: dataset_name, page: page, limit: limit)["data"] || []
     end
 
     # Full paginated response including "meta" for internal pagination use
@@ -293,10 +357,7 @@ module Langfuse
     # @api private
     # @return [Hash] Full response hash with "data" array and "meta" pagination info
     def list_dataset_runs_paginated(dataset_name:, page: nil, limit: nil)
-      with_faraday_error_handling do
-        response = connection.get(dataset_runs_path(dataset_name), build_dataset_runs_params(page: page, limit: limit))
-        handle_response(response)
-      end
+      request(:get, dataset_runs_path(dataset_name), params: { page: page, limit: limit }.compact)
     end
 
     # Delete a dataset run by name
@@ -325,19 +386,16 @@ module Langfuse
     #   data = api_client.get_projects
     #   project_id = data["data"][0]["id"]
     def get_projects # rubocop:disable Naming/AccessorMethodName
-      with_faraday_error_handling do
-        response = connection.get("/api/public/projects")
-        handle_response(response)
-      end
+      request(:get, "/api/public/projects")
     end
 
     # Shut down the API client and release resources
     #
-    # Shuts down the cache if it supports shutdown (e.g., SWR thread pool).
+    # Shuts down the cache backend's SWR thread pool when present.
     #
     # @return [void]
     def shutdown
-      cache.shutdown if cache.respond_to?(:shutdown)
+      @cache&.shutdown
     end
 
     # List traces in the project
@@ -367,14 +425,13 @@ module Langfuse
                     from_timestamp: nil, to_timestamp: nil, order_by: nil,
                     tags: nil, version: nil, release: nil, environment: nil,
                     fields: nil, filter: nil)
-      result = list_traces_paginated(
+      list_traces_paginated(
         page: page, limit: limit, user_id: user_id, name: name,
         session_id: session_id, from_timestamp: from_timestamp,
         to_timestamp: to_timestamp, order_by: order_by, tags: tags,
         version: version, release: release, environment: environment,
         fields: fields, filter: filter
-      )
-      result["data"] || []
+      )["data"] || []
     end
     # rubocop:enable Metrics/ParameterLists
 
@@ -387,17 +444,14 @@ module Langfuse
                               from_timestamp: nil, to_timestamp: nil, order_by: nil,
                               tags: nil, version: nil, release: nil, environment: nil,
                               fields: nil, filter: nil)
-      with_faraday_error_handling do
-        params = build_traces_params(
-          page: page, limit: limit, user_id: user_id, name: name,
-          session_id: session_id, from_timestamp: from_timestamp,
-          to_timestamp: to_timestamp, order_by: order_by, tags: tags,
-          version: version, release: release, environment: environment,
-          fields: fields, filter: filter
-        )
-        response = connection.get("/api/public/traces", params)
-        handle_response(response)
-      end
+      params = build_traces_params(
+        page: page, limit: limit, user_id: user_id, name: name,
+        session_id: session_id, from_timestamp: from_timestamp,
+        to_timestamp: to_timestamp, order_by: order_by, tags: tags,
+        version: version, release: release, environment: environment,
+        fields: fields, filter: filter
+      )
+      request(:get, "/api/public/traces", params: params)
     end
     # rubocop:enable Metrics/ParameterLists
 
@@ -412,11 +466,7 @@ module Langfuse
     # @example
     #   trace = api_client.get_trace("trace-uuid-123")
     def get_trace(id)
-      with_faraday_error_handling do
-        encoded_id = URI.encode_uri_component(id)
-        response = connection.get("/api/public/traces/#{encoded_id}")
-        handle_response(response)
-      end
+      request(:get, "/api/public/traces/#{URI.encode_uri_component(id)}")
     end
 
     # List all datasets in the project
@@ -430,13 +480,7 @@ module Langfuse
     # @example
     #   datasets = api_client.list_datasets(page: 1, limit: 10)
     def list_datasets(page: nil, limit: nil)
-      with_faraday_error_handling do
-        params = { page: page, limit: limit }.compact
-
-        response = connection.get("/api/public/v2/datasets", params)
-        result = handle_response(response)
-        result["data"] || []
-      end
+      request(:get, "/api/public/v2/datasets", params: { page: page, limit: limit }.compact)["data"] || []
     end
 
     # Fetch a dataset by name
@@ -450,11 +494,7 @@ module Langfuse
     # @example
     #   data = api_client.get_dataset("my-dataset")
     def get_dataset(name)
-      with_faraday_error_handling do
-        encoded_name = URI.encode_uri_component(name)
-        response = connection.get("/api/public/v2/datasets/#{encoded_name}")
-        handle_response(response)
-      end
+      request(:get, "/api/public/v2/datasets/#{URI.encode_uri_component(name)}")
     end
 
     # Create a new dataset
@@ -469,12 +509,8 @@ module Langfuse
     # @example
     #   data = api_client.create_dataset(name: "my-dataset", description: "QA evaluation set")
     def create_dataset(name:, description: nil, metadata: nil)
-      with_faraday_error_handling do
-        payload = { name: name, description: description, metadata: metadata }.compact
-
-        response = connection.post("/api/public/v2/datasets", payload)
-        handle_response(response)
-      end
+      request(:post, "/api/public/v2/datasets",
+              body: { name: name, description: description, metadata: metadata }.compact)
     end
 
     # Create a new dataset item (or upsert if id is provided)
@@ -501,16 +537,13 @@ module Langfuse
     def create_dataset_item(dataset_name:, input: nil, expected_output: nil,
                             metadata: nil, id: nil, source_trace_id: nil,
                             source_observation_id: nil, status: nil)
-      with_faraday_error_handling do
-        payload = build_dataset_item_payload(
-          dataset_name: dataset_name, input: input, expected_output: expected_output,
-          metadata: metadata, id: id, source_trace_id: source_trace_id,
-          source_observation_id: source_observation_id, status: status
-        )
-
-        response = connection.post("/api/public/dataset-items", payload)
-        handle_response(response)
-      end
+      payload = {
+        datasetName: dataset_name, id: id, input: input,
+        expectedOutput: expected_output, metadata: metadata,
+        sourceTraceId: source_trace_id, sourceObservationId: source_observation_id,
+        status: status&.to_s&.upcase
+      }.compact
+      request(:post, "/api/public/dataset-items", body: payload)
     end
     # rubocop:enable Metrics/ParameterLists
 
@@ -525,11 +558,7 @@ module Langfuse
     # @example
     #   data = api_client.get_dataset_item("item-uuid-123")
     def get_dataset_item(id)
-      with_faraday_error_handling do
-        encoded_id = URI.encode_uri_component(id)
-        response = connection.get("/api/public/dataset-items/#{encoded_id}")
-        handle_response(response)
-      end
+      request(:get, "/api/public/dataset-items/#{URI.encode_uri_component(id)}")
     end
 
     # List items in a dataset with optional filters
@@ -545,13 +574,8 @@ module Langfuse
     #
     # @example
     #   items = api_client.list_dataset_items(dataset_name: "my-dataset", limit: 50)
-    def list_dataset_items(dataset_name:, page: nil, limit: nil,
-                           source_trace_id: nil, source_observation_id: nil)
-      result = list_dataset_items_paginated(
-        dataset_name: dataset_name, page: page, limit: limit,
-        source_trace_id: source_trace_id, source_observation_id: source_observation_id
-      )
-      result["data"] || []
+    def list_dataset_items(**)
+      list_dataset_items_paginated(**)["data"] || []
     end
 
     # Full paginated response including "meta" for internal pagination use
@@ -560,15 +584,11 @@ module Langfuse
     # @return [Hash] Full response hash with "data" array and "meta" pagination info
     def list_dataset_items_paginated(dataset_name:, page: nil, limit: nil,
                                      source_trace_id: nil, source_observation_id: nil)
-      with_faraday_error_handling do
-        params = build_dataset_items_params(
-          dataset_name: dataset_name, page: page, limit: limit,
-          source_trace_id: source_trace_id, source_observation_id: source_observation_id
-        )
-
-        response = connection.get("/api/public/dataset-items", params)
-        handle_response(response)
-      end
+      params = {
+        datasetName: dataset_name, page: page, limit: limit,
+        sourceTraceId: source_trace_id, sourceObservationId: source_observation_id
+      }.compact
+      request(:get, "/api/public/dataset-items", params: params)
     end
 
     # Delete a dataset item by ID
@@ -582,8 +602,7 @@ module Langfuse
     # @example
     #   api_client.delete_dataset_item("item-uuid-123")
     def delete_dataset_item(id)
-      encoded_id = URI.encode_uri_component(id)
-      response = connection.delete("/api/public/dataset-items/#{encoded_id}")
+      response = connection.delete("/api/public/dataset-items/#{URI.encode_uri_component(id)}")
       handle_delete_dataset_item_response(response, id)
     rescue Faraday::RetriableResponse => e
       logger.error("Faraday error: Retries exhausted - #{e.response.status}")
@@ -595,126 +614,42 @@ module Langfuse
 
     private
 
-    # Fetch prompt using the most appropriate caching strategy available
-    #
-    # @param cache_key [String] The cache key for this prompt
-    # @param name [String] The name of the prompt
-    # @param version [Integer, nil] Optional specific version number
-    # @param label [String, nil] Optional label
-    # @return [Hash] The prompt data
-    def fetch_with_appropriate_caching_strategy(cache_key, name, version, label)
-      if swr_cache_available?
-        fetch_with_swr_cache(cache_key, name, version, label)
-      elsif distributed_cache_available?
-        fetch_with_distributed_cache(cache_key, name, version, label)
-      else
-        fetch_with_simple_cache(cache_key, name, version, label)
-      end
-    end
-
-    # Check if SWR cache is available
-    def swr_cache_available?
-      cache.respond_to?(:swr_enabled?) && cache.swr_enabled?
+    def cache_backend_name
+      @prompt_cache_coordinator.backend_name
     end
 
-    # Check if distributed cache is available
-    def distributed_cache_available?
-      cache.respond_to?(:fetch_with_lock)
-    end
-
-    # Build payload for create_dataset_item
-    # rubocop:disable Metrics/ParameterLists
-    def build_dataset_item_payload(dataset_name:, input:, expected_output:,
-                                   metadata:, id:, source_trace_id:,
-                                   source_observation_id:, status:)
-      { datasetName: dataset_name }.tap do |payload|
-        add_optional_dataset_item_fields(payload, input, expected_output, metadata, id)
-        add_optional_source_fields(payload, source_trace_id, source_observation_id, status)
+    # Issue an HTTP request, raise on Faraday errors, parse the response.
+    #
+    # @api private
+    # @param verb [Symbol] HTTP verb (:get, :post, :patch, :delete)
+    # @param path [String] Request path
+    # @param params [Hash, nil] Query string params (GET/DELETE)
+    # @param body [Hash, nil] JSON body (POST/PATCH)
+    # @return [Hash] Parsed response body
+    def request(verb, path, params: nil, body: nil)
+      with_faraday_error_handling do
+        handle_response(connection.public_send(verb, path, body || params))
       end
     end
-    # rubocop:enable Metrics/ParameterLists
-
-    def add_optional_dataset_item_fields(payload, input, expected_output, metadata, id)
-      payload[:id] = id if id
-      payload[:input] = input if input
-      payload[:expectedOutput] = expected_output if expected_output
-      payload[:metadata] = metadata if metadata
-    end
 
-    def add_optional_source_fields(payload, source_trace_id, source_observation_id, status)
-      payload[:sourceTraceId] = source_trace_id if source_trace_id
-      payload[:sourceObservationId] = source_observation_id if source_observation_id
-      payload[:status] = status.to_s.upcase if status
-    end
-
-    # Build params for list_dataset_items
-    def build_dataset_items_params(dataset_name:, page:, limit:,
-                                   source_trace_id:, source_observation_id:)
+    def build_traces_params(**options)
       {
-        datasetName: dataset_name,
-        page: page,
-        limit: limit,
-        sourceTraceId: source_trace_id,
-        sourceObservationId: source_observation_id
+        page: options[:page], limit: options[:limit], userId: options[:user_id], name: options[:name],
+        sessionId: options[:session_id],
+        fromTimestamp: options[:from_timestamp]&.iso8601,
+        toTimestamp: options[:to_timestamp]&.iso8601,
+        orderBy: options[:order_by], tags: options[:tags], version: options[:version],
+        release: options[:release], environment: options[:environment], fields: options[:fields],
+        filter: options[:filter]
       }.compact
     end
 
-    # Build params for list_dataset_runs
-    def build_dataset_runs_params(page:, limit:)
-      { page: page, limit: limit }.compact
-    end
-
-    # Build endpoint path for dataset runs
     def dataset_runs_path(dataset_name)
-      encoded_name = URI.encode_uri_component(dataset_name)
-      "/api/public/datasets/#{encoded_name}/runs"
+      "/api/public/datasets/#{URI.encode_uri_component(dataset_name)}/runs"
     end
 
-    # Build endpoint path for a specific dataset run
     def dataset_run_path(dataset_name:, run_name:)
-      encoded_run_name = URI.encode_uri_component(run_name)
-      "#{dataset_runs_path(dataset_name)}/#{encoded_run_name}"
-    end
-
-    # Build query params for list_traces, mapping snake_case to camelCase
-    # rubocop:disable Metrics/ParameterLists
-    def build_traces_params(page:, limit:, user_id:, name:, session_id:,
-                            from_timestamp:, to_timestamp:, order_by:,
-                            tags:, version:, release:, environment:, fields:, filter:)
-      {
-        page: page, limit: limit, userId: user_id, name: name,
-        sessionId: session_id,
-        fromTimestamp: from_timestamp&.iso8601,
-        toTimestamp: to_timestamp&.iso8601,
-        orderBy: order_by, tags: tags, version: version,
-        release: release, environment: environment, fields: fields,
-        filter: filter
-      }.compact
-    end
-    # rubocop:enable Metrics/ParameterLists
-
-    # Fetch with SWR cache
-    def fetch_with_swr_cache(cache_key, name, version, label)
-      cache.fetch_with_stale_while_revalidate(cache_key) do
-        fetch_prompt_from_api(name, version: version, label: label)
-      end
-    end
-
-    # Fetch with distributed cache (Rails.cache with stampede protection)
-    def fetch_with_distributed_cache(cache_key, name, version, label)
-      cache.fetch_with_lock(cache_key) do
-        fetch_prompt_from_api(name, version: version, label: label)
-      end
-    end
-
-    # Fetch with simple cache (in-memory cache)
-    def fetch_with_simple_cache(cache_key, name, version, label)
-      cached_data = cache.get(cache_key)
-      return cached_data if cached_data
-
-      prompt_data = fetch_prompt_from_api(name, version: version, label: label)
-      cache.set(cache_key, prompt_data)
-      prompt_data
+      "#{dataset_runs_path(dataset_name)}/#{URI.encode_uri_component(run_name)}"
     end
 
     # Fetch a prompt from the API (without caching)
@@ -727,13 +662,8 @@ module Langfuse
     # @raise [UnauthorizedError] if authentication fails
     # @raise [ApiError] for other API errors
     def fetch_prompt_from_api(name, version: nil, label: nil)
-      with_faraday_error_handling do
-        params = build_prompt_params(version: version, label: label)
-        path = "/api/public/v2/prompts/#{URI.encode_uri_component(name)}"
-
-        response = connection.get(path, params)
-        handle_response(response)
-      end
+      path = "/api/public/v2/prompts/#{URI.encode_uri_component(name)}"
+      request(:get, path, params: { version: version, label: label }.compact)
     end
 
     # Build a new Faraday connection
@@ -802,15 +732,6 @@ module Langfuse
       "langfuse-rb/#{Langfuse::VERSION}"
     end
 
-    # Build query parameters for prompt request
-    #
-    # @param version [Integer, nil] Optional version number
-    # @param label [String, nil] Optional label
-    # @return [Hash] Query parameters
-    def build_prompt_params(version: nil, label: nil)
-      { version: version, label: label }.compact
-    end
-
     # Wrap a block with standard Faraday error handling.
     #
     # Catches RetriableResponse (retries exhausted) and generic Faraday errors,