ruby_llm-agents 3.8.0 → 3.9.0

data/lib/ruby_llm/agents/pipeline/context.rb

@@ -46,6 +46,9 @@ module RubyLLM
         # Response metadata
         attr_accessor :model_used, :finish_reason, :time_to_first_token_ms
 
+        # Debug trace (set when debug: true is passed)
+        attr_accessor :trace
+
         # Streaming support
         attr_accessor :stream_block, :skip_cache
 
@@ -85,6 +88,10 @@ module RubyLLM
           @skip_cache = skip_cache
           @stream_block = stream_block
 
+          # Debug trace
+          @trace = []
+          @trace_enabled = options[:debug] == true
+
           # Initialize tracking fields
           @attempt = 0
           @attempts_made = 0
@@ -108,6 +115,23 @@ module RubyLLM
           ((@completed_at - @started_at) * 1000).to_i
         end
 
+        # Is debug tracing enabled?
+        #
+        # @return [Boolean]
+        def trace_enabled?
+          @trace_enabled
+        end
+
+        # Adds a trace entry for a middleware execution
+        #
+        # @param middleware_name [String] Name of the middleware
+        # @param started_at [Time] When the middleware started
+        # @param duration_ms [Float] How long the middleware took in ms
+        # @param action [String, nil] Optional action description (e.g., "cache hit")
+        def add_trace(middleware_name, started_at:, duration_ms:, action: nil)
+          @trace << {middleware: middleware_name, started_at: started_at, duration_ms: duration_ms, action: action}.compact
+        end
+
         # Was the result served from cache?
         #
         # @return [Boolean]
@@ -230,6 +254,8 @@ module RubyLLM
           # Preserve execution hierarchy
           new_ctx.parent_execution_id = @parent_execution_id
           new_ctx.root_execution_id = @root_execution_id
+          # Preserve trace across retries
+          new_ctx.trace = @trace
           new_ctx
         end
 

data/lib/ruby_llm/agents/pipeline/middleware/base.rb

@@ -41,6 +41,8 @@ module RubyLLM
         # @abstract Subclass and implement {#call}
         #
         class Base
+          LOG_TAG = "[RubyLLM::Agents::Pipeline]"
+
           # @param app [#call] The next handler in the chain
           # @param agent_class [Class] The agent class (for reading DSL config)
           def initialize(app, agent_class)
@@ -100,22 +102,74 @@ module RubyLLM
             RubyLLM::Agents.configuration
           end
 
+          # Builds a log prefix with context from the execution
+          #
+          # Includes agent type, execution ID, and tenant when available
+          # so log messages can be traced through the full pipeline.
+          #
+          # @param context [Context, nil] The execution context
+          # @return [String] Formatted log prefix
+          def log_prefix(context = nil)
+            return LOG_TAG unless context
+
+            parts = [LOG_TAG]
+            parts << context.agent_class.name if context.agent_class
+            parts << "exec=#{context.execution_id}" if context.execution_id
+            parts << "tenant=#{context.tenant_id}" if context.tenant_id
+            parts.join(" ")
+          end
+
           # Log a debug message if Rails logger is available
           #
           # @param message [String] The message to log
-          def debug(message)
+          # @param context [Context, nil] Optional execution context for structured prefix
+          def debug(message, context = nil)
             return unless defined?(Rails) && Rails.logger
 
-            Rails.logger.debug("[RubyLLM::Agents::Pipeline] #{message}")
+            Rails.logger.debug("#{log_prefix(context)} #{message}")
           end
 
           # Log an error message if Rails logger is available
           #
           # @param message [String] The message to log
-          def error(message)
+          # @param context [Context, nil] Optional execution context for structured prefix
+          def error(message, context = nil)
+            return unless defined?(Rails) && Rails.logger
+
+            Rails.logger.error("#{log_prefix(context)} #{message}")
+          end
+
+          # Traces middleware execution when debug mode is enabled.
+          #
+          # Wraps a block with timing instrumentation. When tracing is not
+          # enabled, yields directly with zero overhead.
+          #
+          # @param context [Context] The execution context
+          # @param action [String, nil] Optional action description
+          # @yield The block to trace
+          # @return [Object] The block's return value
+          def trace(context, action: nil)
+            unless context.trace_enabled?
+              return yield
+            end
+
+            middleware_name = self.class.name&.split("::")&.last || self.class.to_s
+            started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            result = yield
+            duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000).round(2)
+            context.add_trace(middleware_name, started_at: Time.current, duration_ms: duration_ms, action: action)
+            debug("#{middleware_name} completed in #{duration_ms}ms#{" (#{action})" if action}", context)
+            result
+          end
+
+          # Log a warning message if Rails logger is available
+          #
+          # @param message [String] The message to log
+          # @param context [Context, nil] Optional execution context for structured prefix
+          def warn(message, context = nil)
             return unless defined?(Rails) && Rails.logger
 
-            Rails.logger.error("[RubyLLM::Agents::Pipeline] #{message}")
+            Rails.logger.warn("#{log_prefix(context)} #{message}")
           end
         end
       end

data/lib/ruby_llm/agents/pipeline/middleware/budget.rb

@@ -32,21 +32,23 @@ module RubyLLM
           def call(context)
             return @app.call(context) unless budgets_enabled?
 
-            # Check budget before execution
-            check_budget!(context)
+            trace(context) do
+              # Check budget before execution
+              check_budget!(context)
 
-            # Execute the chain
-            @app.call(context)
+              # Execute the chain
+              @app.call(context)
 
-            # Record spend after successful execution (if not cached)
-            if context.success? && !context.cached?
-              record_spend!(context)
-              emit_budget_notification("ruby_llm_agents.budget.record", context,
-                total_cost: context.total_cost,
-                total_tokens: context.total_tokens)
-            end
+              # Record spend after successful execution (if not cached)
+              if context.success? && !context.cached?
+                record_spend!(context)
+                emit_budget_notification("ruby_llm_agents.budget.record", context,
+                  total_cost: context.total_cost,
+                  total_tokens: context.total_tokens)
+              end
 
-            context
+              context
+            end
           end
 
           private
@@ -65,7 +67,7 @@ module RubyLLM
               }.merge(extras)
             )
           rescue => e
-            debug("Budget notification failed: #{e.message}")
+            debug("Budget notification failed: #{e.message}", context)
           end
 
           # Returns whether budgets are enabled globally
@@ -106,7 +108,7 @@ module RubyLLM
             raise
           rescue => e
             # Log at error level so unexpected failures are visible in logs
-            error("Budget check failed: #{e.class}: #{e.message}")
+            error("Budget check failed: #{e.class}: #{e.message}", context)
           end
 
           # Records spend after execution
@@ -145,7 +147,7 @@ module RubyLLM
               )
             end
           rescue => e
-            error("Failed to record spend: #{e.message}")
+            error("Failed to record spend: #{e.message}", context)
           end
         end
       end

data/lib/ruby_llm/agents/pipeline/middleware/cache.rb

@@ -31,34 +31,46 @@ module RubyLLM
           def call(context)
             return @app.call(context) unless cache_enabled?
 
-            cache_key = generate_cache_key(context)
-
-            # Skip cache read if skip_cache is true
-            unless context.skip_cache
-              # Try to read from cache
-              if (cached = cache_read(cache_key))
-                context.output = cached
-                context.cached = true
-                context[:cache_key] = cache_key
-                debug("Cache hit for #{cache_key}")
-                emit_cache_notification("ruby_llm_agents.cache.hit", cache_key)
-                return context
+            cache_action = nil
+            result = trace(context, action: "cache") do
+              cache_key = generate_cache_key(context)
+
+              # Skip cache read if skip_cache is true
+              unless context.skip_cache
+                # Try to read from cache
+                if (cached = cache_read(cache_key))
+                  context.output = cached
+                  context.cached = true
+                  context[:cache_key] = cache_key
+                  cache_action = "hit"
+                  debug("Cache hit for #{cache_key}", context)
+                  emit_cache_notification("ruby_llm_agents.cache.hit", cache_key)
+                  next context
+                end
               end
-            end
 
-            emit_cache_notification("ruby_llm_agents.cache.miss", cache_key)
+              cache_action = "miss"
+              emit_cache_notification("ruby_llm_agents.cache.miss", cache_key)
+
+              # Execute the chain
+              @app.call(context)
 
-            # Execute the chain
-            @app.call(context)
+              # Cache successful results
+              if context.success?
+                cache_write(cache_key, context.output)
+                debug("Cache write for #{cache_key}", context)
+                emit_cache_notification("ruby_llm_agents.cache.write", cache_key)
+              end
+
+              context
+            end
 
-            # Cache successful results
-            if context.success?
-              cache_write(cache_key, context.output)
-              debug("Cache write for #{cache_key}")
-              emit_cache_notification("ruby_llm_agents.cache.write", cache_key)
+            # Update the last trace entry with the specific cache action
+            if context.trace_enabled? && cache_action && context.trace.last
+              context.trace.last[:action] = cache_action
             end
 
-            context
+            result
           end
 
           private

data/lib/ruby_llm/agents/pipeline/middleware/instrumentation.rb

@@ -39,45 +39,47 @@ module RubyLLM
           def call(context)
             context.started_at = Time.current
 
-            # Create "running" record immediately (SYNC - must appear on dashboard)
-            execution = create_running_execution(context)
-            context.execution_id = execution&.id
-            emit_start_notification(context)
-            status_update_completed = false
-            raised_exception = nil
-
-            begin
-              @app.call(context)
-              context.completed_at = Time.current
-
-              begin
-                complete_execution(execution, context, status: "success")
-                status_update_completed = true
-              rescue
-                # Let ensure block handle via mark_execution_failed!
-              end
-
-              emit_complete_notification(context, "success")
-            rescue => e
-              context.completed_at = Time.current
-              context.error = e
-              raised_exception = e
+            trace(context) do
+              # Create "running" record immediately (SYNC - must appear on dashboard)
+              execution = create_running_execution(context)
+              context.execution_id = execution&.id
+              emit_start_notification(context)
+              status_update_completed = false
+              raised_exception = nil
 
               begin
-                complete_execution(execution, context, status: determine_error_status(e))
-                status_update_completed = true
-              rescue
-                # Let ensure block handle via mark_execution_failed!
+                @app.call(context)
+                context.completed_at = Time.current
+
+                begin
+                  complete_execution(execution, context, status: "success")
+                  status_update_completed = true
+                rescue
+                  # Let ensure block handle via mark_execution_failed!
+                end
+
+                emit_complete_notification(context, "success")
+              rescue => e
+                context.completed_at = Time.current
+                context.error = e
+                raised_exception = e
+
+                begin
+                  complete_execution(execution, context, status: determine_error_status(e))
+                  status_update_completed = true
+                rescue
+                  # Let ensure block handle via mark_execution_failed!
+                end
+
+                emit_complete_notification(context, determine_error_status(e))
+                raise
+              ensure
+                # Emergency fallback if update failed
+                mark_execution_failed!(execution, error: raised_exception || $!) unless status_update_completed
               end
 
-              emit_complete_notification(context, determine_error_status(e))
-              raise
-            ensure
-              # Emergency fallback if update failed
-              mark_execution_failed!(execution, error: raised_exception || $!) unless status_update_completed
+              context
             end
-
-            context
           end
 
           private
@@ -111,7 +113,7 @@ module RubyLLM
 
             execution
           rescue => e
-            error("Failed to create running execution record: #{e.message}")
+            error("Failed to create running execution record: #{e.message}", context)
             nil
           end
 
@@ -142,7 +144,7 @@ module RubyLLM
             # Save detail data (prompts, responses, tool calls, etc.)
             save_execution_details(execution, context, status)
           rescue => e
-            error("Failed to complete execution record: #{e.message}")
+            error("Failed to complete execution record: #{e.message}", context)
             raise # Re-raise for ensure block to handle via mark_execution_failed!
           end
 
@@ -158,7 +160,7 @@ module RubyLLM
             return unless execution&.id
             return unless execution.status == "running"
 
-            error_message = error ? "#{error.class}: #{error.message}".truncate(1000) : "Unknown error"
+            error_message = build_error_message(error)
 
             update_data = {
               status: "error",
@@ -183,6 +185,28 @@ module RubyLLM
             error("CRITICAL: Failed emergency status update for execution #{execution&.id}: #{e.message}")
           end
 
+          # Builds an informative error message including backtrace context
+          #
+          # Preserves the error class, message, and the most relevant
+          # backtrace frames (up to 10) so developers can trace the
+          # failure origin without needing to reproduce it.
+          #
+          # @param error [Exception, nil] The exception
+          # @return [String] Formatted error message with backtrace
+          def build_error_message(error)
+            return "Unknown error" unless error
+
+            parts = ["#{error.class}: #{error.message}"]
+
+            if error.backtrace&.any?
+              relevant_frames = error.backtrace.first(10)
+              parts << "Backtrace (first #{relevant_frames.size} frames):"
+              parts.concat(relevant_frames.map { |frame| "  #{frame}" })
+            end
+
+            parts.join("\n").truncate(5000)
+          end
+
           # Determines the status based on error type
           #
           # @param error [Exception] The exception that occurred
@@ -206,7 +230,7 @@ module RubyLLM
               execution_id: context.execution_id
             )
           rescue => e
-            debug("Start notification failed: #{e.message}")
+            debug("Start notification failed: #{e.message}", context)
           end
 
           # Emits an AS::Notification for execution completion or error
@@ -243,7 +267,7 @@ module RubyLLM
               error_message: context.error&.message
             )
           rescue => e
-            debug("Complete notification failed: #{e.message}")
+            debug("Complete notification failed: #{e.message}", context)
           end
 
           # Builds data for initial running execution record
@@ -295,6 +319,9 @@ module RubyLLM
               data[:root_execution_id] = context.root_execution_id || context.parent_execution_id
             end
 
+            # Inject tracker request_id and tags
+            inject_tracker_data(context, data)
+
             data
           end
 
@@ -322,7 +349,7 @@ module RubyLLM
             context_meta = begin
               context.metadata.dup
             rescue => e
-              debug("Failed to read context metadata: #{e.message}")
+              debug("Failed to read context metadata: #{e.message}", context)
               {}
             end
             context_meta.transform_keys!(&:to_s)
@@ -365,7 +392,7 @@ module RubyLLM
             end
 
             if context.error
-              detail_data[:error_message] = truncate_error_message(context.error.message)
+              detail_data[:error_message] = build_error_message(context.error)
             end
 
             if context[:tool_calls].present?
@@ -392,7 +419,7 @@ module RubyLLM
               execution.create_detail!(detail_data)
             end
           rescue => e
-            error("Failed to save execution details: #{e.message}")
+            error("Failed to save execution details: #{e.message}", context)
           end
 
           # Persists execution data to database (legacy fallback)
@@ -412,7 +439,7 @@ module RubyLLM
               create_execution_record(data)
             end
           rescue => e
-            error("Failed to record execution: #{e.message}")
+            error("Failed to record execution: #{e.message}", context)
           end
 
           # Builds execution data hash for the legacy single-step persistence path.
@@ -435,7 +462,7 @@ module RubyLLM
               detail_data[:user_prompt] = context.input.to_s.presence
               detail_data[:assistant_prompt] = exec_opts[:assistant_prefill] if assistant_prompt_column_exists?
             end
-            detail_data[:error_message] = truncate_error_message(context.error.message) if context.error
+            detail_data[:error_message] = build_error_message(context.error) if context.error
             detail_data[:tool_calls] = context[:tool_calls] if context[:tool_calls].present?
             detail_data[:attempts] = context[:reliability_attempts] if context[:reliability_attempts].present?
             if global_config.persist_responses && context.output.respond_to?(:content)
@@ -474,7 +501,7 @@ module RubyLLM
             params = begin
               context.agent_instance.send(:options)
             rescue => e
-              debug("Failed to extract agent options: #{e.message}")
+              debug("Failed to extract agent options: #{e.message}", context)
               {}
             end
             params = params.dup
@@ -505,10 +532,38 @@ module RubyLLM
             result = context.agent_instance.metadata
             result.is_a?(Hash) ? result : {}
           rescue => e
-            debug("Failed to retrieve agent metadata: #{e.message}")
+            debug("Failed to retrieve agent metadata: #{e.message}", context)
             {}
           end
 
+          # Injects tracker request_id and tags into execution data
+          #
+          # Reads @_track_request_id and @_track_tags from the agent instance,
+          # which are set by BaseAgent#initialize when a Tracker is active.
+          #
+          # @param context [Context] The execution context
+          # @param data [Hash] The execution data hash to modify
+          def inject_tracker_data(context, data)
+            agent = context.agent_instance
+            return unless agent
+
+            # Inject request_id
+            track_request_id = agent.instance_variable_get(:@_track_request_id)
+            if track_request_id && data[:request_id].blank?
+              data[:request_id] = track_request_id
+            end
+
+            # Merge tracker tags into metadata
+            track_tags = agent.instance_variable_get(:@_track_tags)
+            if track_tags.is_a?(Hash) && track_tags.any?
+              data[:metadata] = (data[:metadata] || {}).merge(
+                "tags" => track_tags.transform_keys(&:to_s)
+              )
+            end
+          rescue
+            # Never let tracker data injection break execution
+          end
+
           # Sensitive parameter keys that should be redacted
           SENSITIVE_KEYS = %w[
             password token api_key secret credential auth key
@@ -527,7 +582,7 @@ module RubyLLM
           def truncate_error_message(message)
             return "" if message.nil?
 
-            message.to_s.truncate(1000)
+            message.to_s.truncate(5000)
           rescue
             message.to_s[0, 1000]
           end
@@ -554,7 +609,7 @@ module RubyLLM
 
             response_data
           rescue => e
-            error("Failed to serialize response: #{e.message}")
+            error("Failed to serialize response: #{e.message}", context)
             nil
           end
 
@@ -581,7 +636,7 @@ module RubyLLM
 
             detail_data[:response] = serialize_audio_response(context.output)
           rescue => e
-            error("Failed to persist audio response: #{e.message}")
+            error("Failed to persist audio response: #{e.message}", context)
           end
 
           # Serializes a SpeechResult into a hash for the response column
@@ -637,7 +692,7 @@ module RubyLLM
               cfg.track_executions
             end
           rescue => e
-            debug("Failed to check tracking config: #{e.message}")
+            debug("Failed to check tracking config: #{e.message}", context)
             false
           end
 

data/lib/ruby_llm/agents/pipeline/middleware/reliability.rb

@@ -41,11 +41,13 @@ module RubyLLM
           def call(context)
             return @app.call(context) unless reliability_enabled?
 
-            config = reliability_config
-            models_to_try = build_models_list(context, config)
-            total_deadline = calculate_deadline(config)
+            trace(context) do
+              config = reliability_config
+              models_to_try = build_models_list(context, config)
+              total_deadline = calculate_deadline(config)
 
-            execute_with_reliability(context, models_to_try, config, total_deadline)
+              execute_with_reliability(context, models_to_try, config, total_deadline)
+            end
           end
 
           private
@@ -103,7 +105,7 @@ module RubyLLM
               # Check circuit breaker for this model
               breaker = get_circuit_breaker(current_model, context)
               if breaker&.open?
-                debug("Circuit breaker open for #{current_model}, skipping")
+                debug("Circuit breaker open for #{current_model}, skipping", context)
                 tracker.record_short_circuit(current_model)
                 next
               end

data/lib/ruby_llm/agents/pipeline/middleware/tenant.rb

@@ -41,10 +41,12 @@ module RubyLLM
           # @param context [Context] The execution context
           # @return [Context] The context with tenant fields populated
           def call(context)
-            resolve_tenant!(context)
-            ensure_tenant_record!(context)
-            apply_api_configuration!(context)
-            @app.call(context)
+            trace(context) do
+              resolve_tenant!(context)
+              ensure_tenant_record!(context)
+              apply_api_configuration!(context)
+              @app.call(context)
+            end
           end
 
           private

data/lib/ruby_llm/agents/rails/engine.rb

@@ -53,6 +53,17 @@ module RubyLLM
           helper RubyLLM::Agents::ApplicationHelper
           before_action :authenticate_dashboard!
 
+          rescue_from ::ActiveRecord::StatementInvalid do |e|
+            if e.message.include?("ruby_llm_agents_")
+              render plain: "RubyLLM::Agents migrations are pending.\n\n" \
+                           "Run: rails db:migrate\n" \
+                           "Or:  rails ruby_llm_agents:doctor",
+                status: :service_unavailable
+            else
+              raise
+            end
+          end
+
           private
 
           # Authenticates dashboard access using configured method

data/lib/ruby_llm/agents/results/background_removal_result.rb

@@ -15,6 +15,8 @@ module RubyLLM
     #   result.success?   # => true
     #
     class BackgroundRemovalResult
+      include Trackable
+
       attr_reader :foreground, :mask, :source_image, :model_id, :output_format,
         :alpha_matting, :refine_edges,
         :started_at, :completed_at, :tenant_id, :remover_class,
@@ -38,7 +40,7 @@ module RubyLLM
       # @param error_message [String, nil] Error message if failed
       def initialize(foreground:, mask:, source_image:, model_id:, output_format:,
         alpha_matting:, refine_edges:, started_at:, completed_at:,
-        tenant_id:, remover_class:, error_class: nil, error_message: nil)
+        tenant_id:, remover_class:, error_class: nil, error_message: nil, agent_class_name: nil)
         @foreground = foreground
         @mask = mask
         @source_image = source_image
@@ -53,6 +55,10 @@ module RubyLLM
         @error_class = error_class
         @error_message = error_message
         @execution_id = nil
+
+        # Tracking
+        @agent_class_name = agent_class_name
+        register_with_tracker
       end
 
       # Loads the associated Execution record from the database