langfuse-rb 0.10.0 → 0.11.0

data/lib/langfuse/score_client.rb

@@ -2,6 +2,9 @@
 
 require "securerandom"
 require "opentelemetry/trace"
+require "json"
+require_relative "fork_safety"
+require_relative "pending_score_queue"
 
 module Langfuse
   # Client for creating and batching Langfuse scores
@@ -32,6 +35,9 @@ module Langfuse
     attr_reader :logger
 
     HEX_TRACE_ID_PATTERN = /\A[0-9a-f]{32}\z/
+    MAX_BATCH_PAYLOAD_BYTES = 2_500_000
+    EMPTY_BATCH_PAYLOAD_BYTES = JSON.generate(batch: []).bytesize
+    private_constant :MAX_BATCH_PAYLOAD_BYTES, :EMPTY_BATCH_PAYLOAD_BYTES
 
     # Initialize a new ScoreClient
     #
@@ -41,8 +47,9 @@ module Langfuse
       @api_client = api_client
       @config = config
       @logger = config.logger
-      @queue = Queue.new
-      @mutex = Mutex.new
+      @queue = PendingScoreQueue.new(capacity: config.score_queue_capacity)
+      @shutdown_mutex = Mutex.new
+      @flush_mutex = Mutex.new
       @flush_thread = nil
       @shutdown = false
       # Match the immutable tracing setup contract: once this client exists, later config
@@ -50,20 +57,21 @@ module Langfuse
       @score_sampler = Sampling.build_sampler(config.sample_rate)
 
       start_flush_timer
+      ForkSafety.register(self)
     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 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]
@@ -77,30 +85,95 @@ module Langfuse
     #
     # @example Categorical score
     #   create(name: "category", value: "high", trace_id: "abc123", data_type: :categorical)
+    #
+    # @example Text score (1 to 500 characters)
+    #   create(name: "reviewer_notes", value: "Helpful but verbose", trace_id: "abc123", data_type: :text)
+    #
+    # @example Corrected output (conventionally named "output")
+    #   create(name: "output", value: "The corrected output", trace_id: "abc123",
+    #          observation_id: "def456", data_type: :correction)
     # rubocop:disable Metrics/ParameterLists
     def create(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)
-      validate_name(name)
-      normalized_value = normalize_value(value, data_type)
-      data_type_str = Types::SCORE_DATA_TYPES[data_type] || raise(ArgumentError, "Invalid data_type: #{data_type}")
+      return unless config.telemetry_enabled?
 
-      return unless enqueue_trace_linked_score?(trace_id)
-
-      event = build_score_event(
-        name: name, value: normalized_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_str,
-        dataset_run_id: dataset_run_id, config_id: config_id
+      score = build_score_body(
+        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
       )
 
-      @queue << event
-      flush if @queue.size >= config.batch_size
+      return unless enqueue_trace_linked_score?(trace_id)
+
+      enqueue_score_event(build_score_event(score))
     rescue StandardError => e
       logger.error("Langfuse score creation failed: #{e.message}")
       raise
     end
     # rubocop:enable Metrics/ParameterLists
 
+    # Create a score immediately through the Scores API.
+    #
+    # {#create} is fire-and-forget — it queues the event and reports nothing
+    # about whether it was actually delivered, matching how this SDK's
+    # tracing already works. That fits scoring inline from a still-open span
+    # (see {#score_active_observation}/{#score_active_trace}), but not a
+    # standalone verdict arriving out-of-band (e.g. user feedback landing in
+    # a request unrelated to the turn it's scoring). Pass a stable +id+ when
+    # the caller may retry after an ambiguous network failure.
+    #
+    # @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
+    #   score_client.create!(id: "feedback-abc123", name: "quality", value: 0.85, trace_id: "abc123")
+    # rubocop:disable Metrics/ParameterLists
+    def create!(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)
+      return unless config.telemetry_enabled?
+
+      score = build_score_body(
+        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
+      )
+
+      api_client.create_score(payload: score)
+    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.
@@ -109,7 +182,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
     #
@@ -140,7 +213,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
     #
@@ -168,19 +241,9 @@ module Langfuse
     #
     # @return [void]
     def flush
-      return if @queue.empty?
+      return unless config.telemetry_enabled?
 
-      events = []
-      @queue.size.times do
-        events << @queue.pop(true)
-      rescue StandardError
-        nil
-      end
-      events.compact!
-
-      return if events.empty?
-
-      send_batch(events)
+      @flush_mutex.synchronize { flush_pending_batches }
     rescue StandardError => e
       logger.error("Langfuse score flush failed: #{e.message}")
       # Don't raise - silent error handling for batch operations
@@ -192,7 +255,7 @@ module Langfuse
     #
     # @return [void]
     def shutdown
-      @mutex.synchronize do
+      @shutdown_mutex.synchronize do
         return if @shutdown
 
         @shutdown = true
@@ -203,10 +266,60 @@ module Langfuse
 
     private
 
-    # Build a score event hash for ingestion API
+    # Discard parent-owned queued work and restore the child process timer.
+    def reset_after_fork
+      inherited_shutdown = @shutdown
+      @queue = PendingScoreQueue.new(capacity: config.score_queue_capacity)
+      @shutdown_mutex = Mutex.new
+      @flush_mutex = Mutex.new
+      @flush_thread = nil
+      @shutdown = inherited_shutdown
+      start_flush_timer unless @shutdown
+    end
+
+    def enqueue_score_event(event)
+      unless @queue.push(event)
+        logger.error(
+          "Langfuse score queue is full (capacity=#{@queue.capacity}); dropping new asynchronous score"
+        )
+        return
+      end
+
+      flush if @queue.size >= config.batch_size
+    end
+
+    def flush_pending_batches
+      loop do
+        batch = next_batch
+        break if batch.empty?
+
+        delivery = send_batch(batch)
+        break if delivery == :retry
+
+        @queue.remove_prefix(batch.length)
+      end
+    end
+
+    def next_batch
+      batch = []
+      payload_bytes = EMPTY_BATCH_PAYLOAD_BYTES
+
+      @queue.first(config.batch_size).each do |event|
+        event_json = JSON.generate(event)
+        additional_bytes = event_json.bytesize + (batch.empty? ? 0 : 1)
+        break if batch.any? && payload_bytes + additional_bytes > MAX_BATCH_PAYLOAD_BYTES
+
+        batch << event
+        payload_bytes += additional_bytes
+      end
+
+      batch
+    end
+
+    # Validate score inputs and build the canonical API body.
     #
     # @param name [String] Score name
-    # @param value [Object] Normalized score value
+    # @param value [Numeric, Integer, String] Raw score value (type depends on data_type)
     # @param id [String, nil] Score ID
     # @param trace_id [String, nil] Trace ID
     # @param session_id [String, nil] Session ID
@@ -214,66 +327,54 @@ module Langfuse
     # @param comment [String, nil] Comment
     # @param metadata [Hash, nil] Metadata
     # @param environment [String, nil] Environment
-    # @param data_type [String] Data type string (NUMERIC, BOOLEAN, CATEGORICAL)
-    # @return [Hash] Event hash
-    # rubocop:disable Metrics/ParameterLists, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
-    def build_score_event(name:, value:, id:, trace_id:, session_id:, observation_id:, comment:, metadata:,
-                          environment:, data_type:, dataset_run_id: nil, config_id: nil)
-      body = {
+    # @param data_type [Symbol] Data type (:numeric, :boolean, :categorical, :text, :correction)
+    # @param dataset_run_id [String, nil] Dataset run ID
+    # @param config_id [String, nil] Score config ID
+    # @return [Hash] Score attributes in API format
+    # @raise [ArgumentError] if validation fails
+    # rubocop:disable Metrics/ParameterLists
+    def build_score_body(name:, value:, id:, trace_id:, session_id:, observation_id:, comment:, metadata:,
+                         environment:, data_type:, dataset_run_id: nil, config_id: nil)
+      validate_name(name)
+      normalized_value = ScoreValue.normalize(value, data_type)
+      data_type_str = Types::SCORE_DATA_TYPES[data_type] || raise(ArgumentError, "Invalid data_type: #{data_type}")
+      validate_correction_subject!(data_type:, trace_id:, session_id:, dataset_run_id:, config_id:)
+
+      snapshot_score_body(
         id: id || SecureRandom.uuid,
         name: name,
-        value: value,
-        dataType: data_type
-      }
-      body[:traceId] = trace_id if trace_id
-      body[:sessionId] = session_id if session_id
-      body[:observationId] = observation_id if observation_id
-      body[:comment] = comment if comment
-      body[:metadata] = metadata if metadata
-      body[:environment] = environment if environment
-      body[:datasetRunId] = dataset_run_id if dataset_run_id
-      body[:configId] = config_id if config_id
+        value: normalized_value,
+        dataType: data_type_str,
+        traceId: trace_id,
+        sessionId: session_id,
+        observationId: observation_id,
+        comment: comment,
+        metadata: metadata,
+        environment: environment || config.environment,
+        datasetRunId: dataset_run_id,
+        configId: config_id
+      )
+    end
+    # rubocop:enable Metrics/ParameterLists
 
-      {
-        id: SecureRandom.uuid,
-        type: "score-create",
-        timestamp: Time.now.utc.iso8601(3),
-        body: body
-      }
+    # Snapshot the wire body so caller mutation cannot poison the pending queue.
+    def snapshot_score_body(attributes)
+      JSON.parse(JSON.generate(attributes.compact), symbolize_names: true)
+    rescue JSON::JSONError => e
+      raise ArgumentError, "Score data must be JSON-serializable: #{e.message}"
     end
-    # rubocop:enable Metrics/ParameterLists, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
-    # Normalize and validate score value based on data type
-    #
-    # @param value [Object] Raw score value
-    # @param data_type [Symbol] Data type symbol
-    # @return [Object] Normalized value
-    # @raise [ArgumentError] if value doesn't match data type
-    # rubocop:disable Metrics/CyclomaticComplexity
-    def normalize_value(value, data_type)
-      case data_type
-      when :numeric
-        raise ArgumentError, "Numeric value must be Numeric, got #{value.class}" unless value.is_a?(Numeric)
-
-        value
-      when :boolean
-        case value
-        when true, 1
-          1
-        when false, 0
-          0
-        else
-          raise ArgumentError, "Boolean value must be true/false or 0/1, got #{value.inspect}"
-        end
-      when :categorical
-        raise ArgumentError, "Categorical value must be a String, got #{value.class}" unless value.is_a?(String)
+    def build_score_event(score)
+      { id: SecureRandom.uuid, type: "score-create", timestamp: Time.now.utc.iso8601(3), body: score }
+    end
 
-        value
-      else
-        raise ArgumentError, "Invalid data_type: #{data_type}"
-      end
+    def validate_correction_subject!(data_type:, trace_id:, session_id:, dataset_run_id:, config_id:)
+      return unless data_type == :correction
+      return if trace_id.is_a?(String) && !trace_id.empty? && !session_id && !dataset_run_id && !config_id
+
+      raise ArgumentError,
+            "Correction scores require trace_id and cannot use session_id, dataset_run_id, or config_id"
     end
-    # rubocop:enable Metrics/CyclomaticComplexity
 
     # Validate score name
     #
@@ -330,12 +431,31 @@ module Langfuse
     # Send a batch of events to the API
     #
     # @param events [Array<Hash>] Array of event hashes
-    # @return [void]
+    # @return [Symbol] :delivered, :discarded, or :retry
     def send_batch(events)
       api_client.send_batch(events)
+      :delivered
+    rescue BatchDeliveryError => e
+      return retry_batch(e) if e.retryable?
+
+      discard_batch(events, e)
+    rescue UnauthorizedError => e
+      retry_batch(e)
     rescue StandardError => e
       logger.error("Langfuse score batch send failed: #{e.message}")
-      # Don't raise - silent error handling
+      :retry
+    end
+
+    def retry_batch(error)
+      logger.error("Langfuse score batch send failed and will retry: #{error.message}")
+      :retry
+    end
+
+    def discard_batch(events, error)
+      logger.error(
+        "Langfuse dropped #{events.length} score event(s) after a permanent batch failure: #{error.message}"
+      )
+      :discarded
     end
 
     # Start the background flush timer thread

data/lib/langfuse/score_value.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Langfuse
+  # Normalizes score values to the wire representation expected by Langfuse.
+  # @api private
+  module ScoreValue
+    TEXT_LENGTH_RANGE = (1..500)
+    private_constant :TEXT_LENGTH_RANGE
+
+    # @param value [Object] raw score value
+    # @param data_type [Symbol] score data type
+    # @return [Numeric, String] normalized score value
+    # @raise [ArgumentError] if the value does not match the data type
+    def self.normalize(value, data_type)
+      case data_type
+      when :numeric then numeric(value)
+      when :boolean then boolean(value)
+      when :categorical then string(value, "Categorical")
+      when :text then text(value)
+      when :correction then string(value, "Correction")
+      else raise ArgumentError, "Invalid data_type: #{data_type}"
+      end
+    end
+
+    def self.numeric(value)
+      raise ArgumentError, "Numeric value must be Numeric, got #{value.class}" unless value.is_a?(Numeric)
+
+      value
+    end
+    private_class_method :numeric
+
+    def self.boolean(value)
+      case value
+      when true, 1 then 1
+      when false, 0 then 0
+      else raise ArgumentError, "Boolean value must be true/false or 0/1, got #{value.inspect}"
+      end
+    end
+    private_class_method :boolean
+
+    def self.text(value)
+      string(value, "Text")
+      unless TEXT_LENGTH_RANGE.cover?(value.length)
+        raise ArgumentError, "Text value must contain 1 to 500 characters, got #{value.length}"
+      end
+
+      value
+    end
+    private_class_method :text
+
+    def self.string(value, label)
+      raise ArgumentError, "#{label} value must be a String, got #{value.class}" unless value.is_a?(String)
+
+      value
+    end
+    private_class_method :string
+  end
+end

data/lib/langfuse/span_processor.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "opentelemetry/sdk"
+require_relative "resilient_metrics_reporter"
 
 module Langfuse
   # Batch span processor that owns Langfuse's enrichment and export filtering.
@@ -13,12 +14,14 @@ module Langfuse
       @logger = config.logger
       @default_trace_attributes = build_default_trace_attributes(config).freeze
       @should_export_span = config.should_export_span || Langfuse.method(:default_export_span?)
+      @app_root_tracker = AppRootTracking::Tracker.new
 
       super(
         exporter,
         max_queue_size: config.batch_size * 2,
         schedule_delay: schedule_delay_for(config),
-        max_export_batch_size: config.batch_size
+        max_export_batch_size: config.batch_size,
+        metrics_reporter: ResilientMetricsReporter.wrap(config.metrics_reporter, logger: config.logger)
       )
     end
 
@@ -32,6 +35,7 @@ module Langfuse
 
       apply_attributes(span, @default_trace_attributes)
       apply_attributes(span, propagated_attributes(parent_context))
+      remember_app_root_state(span, parent_context)
     end
 
     # Drop spans when the export filter rejects them or raises.
@@ -39,9 +43,8 @@ module Langfuse
     # @param span [OpenTelemetry::SDK::Trace::Span] The span that ended
     # @return [void]
     def on_finish(span)
-      return unless should_export_span?(span)
-
-      super
+      ready_spans = @app_root_tracker.finish(span, exportable: should_export_span?(span))
+      ready_spans.each { |ready_span| super(copy_with_app_root(ready_span)) }
     end
 
     private
@@ -51,6 +54,23 @@ module Langfuse
     SYNC_SCHEDULE_DELAY_MS = 60_000
     private_constant :SYNC_SCHEDULE_DELAY_MS
 
+    ExportSpan = Struct.new(:span, :attributes, keyword_init: true) do
+      def context
+        span.context
+      end
+
+      def to_span_data
+        span.to_span_data.tap do |span_data|
+          span_data.attributes = attributes
+          span_data.total_recorded_attributes = [
+            span_data.total_recorded_attributes,
+            attributes.size
+          ].max
+        end
+      end
+    end
+    private_constant :ExportSpan
+
     def schedule_delay_for(config)
       config.tracing_async ? config.flush_interval * 1000 : SYNC_SCHEDULE_DELAY_MS
     end
@@ -71,6 +91,35 @@ module Langfuse
       attributes.each { |key, value| span.set_attribute(key, value) }
     end
 
+    def remember_app_root_state(span, parent_context)
+      propagated_trace_id = Propagation._get_langfuse_trace_id_from_baggage(parent_context)
+      trace_claimed = propagated_trace_id == span.context.trace_id.unpack1("H*")
+      @app_root_tracker.remember(
+        span,
+        trace_claimed: trace_claimed,
+        untracked_parent_root_eligible: AppRootTracking.eligible_without_tracked_parent?(span)
+      )
+    rescue StandardError => e
+      @logger.error(
+        "Langfuse app-root tracking failed for span '#{span.name}'. The span will not export: " \
+        "#{e.class}: #{e.message}"
+      )
+    end
+
+    def copy_with_app_root(ready_span)
+      span = ready_span.span
+      attributes = span.attributes || {}
+      return span if (attributes[OtelAttributes::IS_APP_ROOT] == true) == ready_span.app_root
+
+      copied_attributes = attributes.dup
+      if ready_span.app_root
+        copied_attributes[OtelAttributes::IS_APP_ROOT] = true
+      else
+        copied_attributes.delete(OtelAttributes::IS_APP_ROOT)
+      end
+      ExportSpan.new(span: span, attributes: copied_attributes.freeze)
+    end
+
     def should_export_span?(span)
       @should_export_span.call(span)
     rescue StandardError => e

data/lib/langfuse/stale_while_revalidate.rb

@@ -174,13 +174,12 @@ module Langfuse
     # @param key [String] Cache key
     # @yield Block to execute to fetch fresh data
     # @return [void]
-    # rubocop:disable Naming/PredicateMethod
     def schedule_refresh(key, ttl: nil, stale_ttl: nil, on_success: nil, on_failure: nil, &block)
       # Prevent duplicate refreshes
       lock_key = build_lock_key(key)
       return false unless acquire_lock(lock_key)
 
-      @thread_pool.post do
+      scheduled = @thread_pool.post do
         value = block.call
         set_cache_entry(key, value, ttl: ttl, stale_ttl: stale_ttl)
         on_success&.call(value)
@@ -191,9 +190,9 @@ module Langfuse
         release_lock(lock_key)
       end
 
-      true
+      release_lock(lock_key) unless scheduled
+      scheduled
     end
-    # rubocop:enable Naming/PredicateMethod
 
     # Fetch data and cache it with SWR metadata
     #

data/lib/langfuse/text_prompt_client.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "prompt_renderer"
+require_relative "prompt_variables"
 
 module Langfuse
   # Text prompt client for compiling text prompts with variable substitution
@@ -11,7 +12,7 @@ module Langfuse
   # @example Basic usage
   #   prompt_data = api_client.get_prompt("greeting")
   #   text_prompt = Langfuse::TextPromptClient.new(prompt_data)
-  #   text_prompt.compile(variables: { name: "Alice" })
+  #   text_prompt.compile(name: "Alice")
   #   # => "Hello Alice!"
   #
   # @example Accessing metadata
@@ -35,7 +36,7 @@ module Langfuse
     # @return [Hash] Prompt configuration
     attr_reader :config
 
-    # @return [String] Raw prompt template string
+    # @return [String] Raw prompt template
     attr_reader :prompt
 
     # @return [String, nil] Optional commit message for this prompt version
@@ -71,10 +72,22 @@ module Langfuse
       "text"
     end
 
+    # Return the unique variables referenced by the prompt template
+    #
+    # Section names are included because callers must provide their values.
+    # Variables inside sections include the full section path.
+    #
+    # @return [Array<String>] Referenced variable names in source order
+    # @raise [Mustache::Parser::SyntaxError] if the prompt contains invalid Mustache syntax
+    def variables
+      PromptVariables.extract(prompt)
+    end
+
     # Compile the prompt with variable substitution
     #
     # @param kwargs [Hash] Variables to substitute in the template (as keyword arguments)
     # @return [String] The compiled prompt text
+    # @raise [ArgumentError] if variables cannot be rendered
     #
     # @example
     #   text_prompt.compile(name: "Alice", greeting: "Hi")
@@ -87,10 +100,6 @@ module Langfuse
 
     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")