ruby_llm-agents 3.5.5 → 3.7.0

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

@@ -42,6 +42,7 @@ module RubyLLM
             # 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
 
@@ -55,6 +56,8 @@ module RubyLLM
               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
@@ -67,6 +70,7 @@ module RubyLLM
                 # Let ensure block handle via mark_execution_failed!
               end
 
+              emit_complete_notification(context, determine_error_status(e))
               raise
             ensure
               # Emergency fallback if update failed
@@ -93,6 +97,12 @@ module RubyLLM
             data = build_running_execution_data(context)
             execution = Execution.create!(data)
 
+            # Root executions point root_execution_id at themselves
+            if execution.parent_execution_id.nil? && execution.root_execution_id.nil?
+              execution.update_column(:root_execution_id, execution.id)
+            end
+            context.root_execution_id = execution.root_execution_id || execution.id
+
             # Create detail record with parameters
             params = sanitize_parameters(context)
             if params.present? && params != {}
@@ -181,6 +191,61 @@ module RubyLLM
             error.is_a?(Timeout::Error) ? "timeout" : "error"
           end
 
+          # Emits an AS::Notification for execution start
+          #
+          # Fires even when DB tracking is disabled — observability should
+          # work independently of persistence.
+          #
+          # @param context [Context] The execution context
+          def emit_start_notification(context)
+            ActiveSupport::Notifications.instrument(
+              "ruby_llm_agents.execution.start",
+              agent_type: context.agent_class&.name,
+              model: context.model,
+              tenant_id: context.tenant_id,
+              execution_id: context.execution_id
+            )
+          rescue
+            # Never let notifications break execution
+          end
+
+          # Emits an AS::Notification for execution completion or error
+          #
+          # Uses execution.complete for success, execution.error for failures.
+          # Fires even when DB tracking is disabled.
+          #
+          # @param context [Context] The execution context
+          # @param status [String] "success", "error", or "timeout"
+          def emit_complete_notification(context, status)
+            event = (status == "success") ? "ruby_llm_agents.execution.complete" : "ruby_llm_agents.execution.error"
+
+            ActiveSupport::Notifications.instrument(
+              event,
+              agent_type: context.agent_class&.name,
+              agent_type_symbol: context.agent_type,
+              execution_id: context.execution_id,
+              model: context.model,
+              model_used: context.model_used,
+              tenant_id: context.tenant_id,
+              status: status,
+              duration_ms: context.duration_ms,
+              input_tokens: context.input_tokens,
+              output_tokens: context.output_tokens,
+              total_tokens: context.total_tokens,
+              input_cost: context.input_cost,
+              output_cost: context.output_cost,
+              total_cost: context.total_cost,
+              cached: context.cached?,
+              attempts_made: context.attempts_made,
+              finish_reason: context.finish_reason,
+              time_to_first_token_ms: context.time_to_first_token_ms,
+              error_class: context.error&.class&.name,
+              error_message: context.error&.message
+            )
+          rescue
+            # Never let notifications break execution
+          end
+
           # Builds data for initial running execution record
           #
           # @param context [Context] The execution context
@@ -208,6 +273,22 @@ module RubyLLM
               data[:metadata] = agent_meta.transform_keys(&:to_s)
             end
 
+            # Track replay source if this is a replayed execution
+            replay_source_id = begin
+              context.agent_instance&.send(:options)&.dig(:_replay_source_id)
+            rescue
+              nil
+            end
+            if replay_source_id
+              data[:metadata] = (data[:metadata] || {}).merge("replay_source_id" => replay_source_id.to_s)
+            end
+
+            # Execution hierarchy (agent-as-tool)
+            if context.parent_execution_id.present?
+              data[:parent_execution_id] = context.parent_execution_id
+              data[:root_execution_id] = context.root_execution_id || context.parent_execution_id
+            end
+
             data
           end
 
@@ -442,6 +523,10 @@ module RubyLLM
               params[key] = "[REDACTED]" if params.key?(key)
             end
 
+            INTERNAL_KEYS.each do |key|
+              params.delete(key)
+            end
+
             params
           end
 
@@ -469,6 +554,11 @@ module RubyLLM
             access_token refresh_token private_key secret_key
           ].freeze
 
+          # Internal keys that should be stripped from persisted parameters
+          INTERNAL_KEYS = %w[
+            _replay_source_id _ask_message _parent_execution_id _root_execution_id
+          ].freeze
+
           # Truncates error message to prevent database issues
           #
           # @param message [String] The error message

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

@@ -120,6 +120,17 @@ module RubyLLM
 
               if result
                 context[:reliability_attempts] = tracker.to_json_array
+
+                # Emit fallback_used if a non-primary model succeeded
+                if current_model != models_to_try.first
+                  emit_reliability_notification(
+                    "ruby_llm_agents.reliability.fallback_used",
+                    primary_model: models_to_try.first,
+                    used_model: current_model,
+                    attempts_made: context.attempts_made
+                  )
+                end
+
                 return result
               end
 
@@ -131,6 +142,11 @@ module RubyLLM
             context[:reliability_attempts] = tracker.to_json_array
 
             # All models exhausted
+            emit_reliability_notification(
+              "ruby_llm_agents.reliability.all_models_exhausted",
+              models_tried: models_to_try
+            )
+
             raise Agents::Reliability::AllModelsExhaustedError.new(
               models_to_try, last_error,
               attempts: tracker.to_json_array
@@ -292,6 +308,19 @@ module RubyLLM
             )
           end
 
+          # Emits an AS::Notification for reliability events
+          #
+          # @param event [String] The notification event name
+          # @param extras [Hash] Additional payload fields
+          def emit_reliability_notification(event, **extras)
+            ActiveSupport::Notifications.instrument(
+              event,
+              {agent_type: @agent_class&.name}.merge(extras)
+            )
+          rescue
+            # Never let notifications break execution
+          end
+
           # Sleeps without blocking other fibers when in async context
           #
           # @param seconds [Numeric] Duration to sleep

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

@@ -59,10 +59,17 @@ module RubyLLM
             case tenant_value
             when nil
               # No explicit tenant - fall back to configured tenant_resolver
-              resolved_id = RubyLLM::Agents.configuration.current_tenant_id
-              context.tenant_id = resolved_id&.to_s
-              context.tenant_object = nil
-              context.tenant_config = nil
+              resolved_value = RubyLLM::Agents.configuration.current_tenant_id
+
+              if resolved_value.respond_to?(:llm_tenant_id)
+                context.tenant_id = resolved_value.llm_tenant_id&.to_s
+                context.tenant_object = resolved_value
+                context.tenant_config = extract_tenant_config(resolved_value)
+              else
+                context.tenant_id = resolved_value&.to_s
+                context.tenant_object = nil
+                context.tenant_config = nil
+              end
 
             when Hash
               # Hash format: { id: "tenant_id", object: tenant, ... }

data/lib/ruby_llm/agents/pipeline.rb

@@ -40,98 +40,6 @@ require_relative "pipeline/middleware/reliability"
 module RubyLLM
   module Agents
     module Pipeline
-      # Represents an error result from a failed step
-      #
-      # Used to track errors that occurred during step execution while
-      # allowing the workflow to continue (for optional steps).
-      #
-      # @api public
-      class ErrorResult
-        attr_reader :step_name, :error_class, :error_message
-
-        def initialize(step_name:, error_class:, error_message:)
-          @step_name = step_name
-          @error_class = error_class
-          @error_message = error_message
-        end
-
-        def content
-          nil
-        end
-
-        def success?
-          false
-        end
-
-        def error?
-          true
-        end
-
-        def skipped?
-          false
-        end
-
-        def input_tokens
-          0
-        end
-
-        def output_tokens
-          0
-        end
-
-        def total_tokens
-          0
-        end
-
-        def cached_tokens
-          0
-        end
-
-        def input_cost
-          0.0
-        end
-
-        def output_cost
-          0.0
-        end
-
-        def total_cost
-          0.0
-        end
-
-        def to_h
-          {
-            error: true,
-            step_name: step_name,
-            error_class: error_class,
-            error_message: error_message
-          }
-        end
-      end
-
-      class << self
-        # Build a pipeline for an agent class with default middleware
-        #
-        # This is a convenience method that combines Builder.for with build.
-        #
-        # @param agent_class [Class] The agent class
-        # @param executor [#call] The core executor
-        # @return [#call] The complete pipeline
-        def build(agent_class, executor)
-          Builder.for(agent_class).build(executor)
-        end
-
-        # Build an empty pipeline (no middleware)
-        #
-        # Useful for testing or when you want direct execution.
-        #
-        # @param agent_class [Class] The agent class
-        # @param executor [#call] The core executor
-        # @return [#call] The executor (no middleware wrapping)
-        def build_empty(agent_class, executor)
-          Builder.empty(agent_class).build(executor)
-        end
-      end
     end
   end
 end

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

@@ -19,6 +19,7 @@ module RubyLLM
         :alpha_matting, :refine_edges,
         :started_at, :completed_at, :tenant_id, :remover_class,
         :error_class, :error_message
+      attr_accessor :execution_id
 
       # Initialize a new result
       #
@@ -51,6 +52,14 @@ module RubyLLM
         @remover_class = remover_class
         @error_class = error_class
         @error_message = error_message
+        @execution_id = nil
+      end
+
+      # Loads the associated Execution record from the database
+      #
+      # @return [RubyLLM::Agents::Execution, nil] The execution record, or nil
+      def execution
+        @execution ||= RubyLLM::Agents::Execution.find_by(id: execution_id) if execution_id
       end
 
       # Status helpers
@@ -196,7 +205,8 @@ module RubyLLM
           tenant_id: tenant_id,
           remover_class: remover_class,
           error_class: error_class,
-          error_message: error_message
+          error_message: error_message,
+          execution_id: execution_id
         }
       end
 

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

@@ -102,6 +102,11 @@ module RubyLLM
       #   @return [Integer, nil] Number of tokens used for thinking
       attr_reader :thinking_text, :thinking_signature, :thinking_tokens
 
+      # @!group Execution Record
+      # @!attribute [r] execution_id
+      #   @return [Integer, nil] Database ID of the associated Execution record
+      attr_reader :execution_id
+
       # Creates a new Result instance
       #
       # @param content [Hash, String] The processed response content
@@ -151,6 +156,22 @@ module RubyLLM
         @thinking_text = options[:thinking_text]
         @thinking_signature = options[:thinking_signature]
         @thinking_tokens = options[:thinking_tokens]
+
+        # Execution record
+        @execution_id = options[:execution_id]
+      end
+
+      # Loads the associated Execution record from the database
+      #
+      # Useful for debugging in the Rails console to inspect the full
+      # execution record after an agent call.
+      #
+      # @return [RubyLLM::Agents::Execution, nil] The execution record, or nil
+      # @example
+      #   result = MyAgent.call(query: "test")
+      #   result.execution  # => #<RubyLLM::Agents::Execution id: 42, ...>
+      def execution
+        @execution ||= Execution.find_by(id: execution_id) if execution_id
       end
 
       # Returns total tokens (input + output)
@@ -240,7 +261,8 @@ module RubyLLM
           tool_calls_count: tool_calls_count,
           thinking_text: thinking_text,
           thinking_signature: thinking_signature,
-          thinking_tokens: thinking_tokens
+          thinking_tokens: thinking_tokens,
+          execution_id: execution_id
         }
       end
 

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

@@ -73,6 +73,10 @@ module RubyLLM
       #   @return [String, nil] Exception message if failed
       attr_reader :error_message
 
+      # @!attribute [r] execution_id
+      #   @return [Integer, nil] Database ID of the associated Execution record
+      attr_reader :execution_id
+
       # Creates a new EmbeddingResult instance
       #
       # @param attributes [Hash] Result attributes
@@ -101,6 +105,14 @@ module RubyLLM
         @tenant_id = attributes[:tenant_id]
         @error_class = attributes[:error_class]
         @error_message = attributes[:error_message]
+        @execution_id = attributes[:execution_id]
+      end
+
+      # Loads the associated Execution record from the database
+      #
+      # @return [RubyLLM::Agents::Execution, nil] The execution record, or nil
+      def execution
+        @execution ||= RubyLLM::Agents::Execution.find_by(id: execution_id) if execution_id
       end
 
       # Returns whether this result contains a single embedding
@@ -215,7 +227,8 @@ module RubyLLM
           completed_at: completed_at,
           tenant_id: tenant_id,
           error_class: error_class,
-          error_message: error_message
+          error_message: error_message,
+          execution_id: execution_id
         }
       end
 

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

@@ -21,6 +21,7 @@ module RubyLLM
         :caption, :description, :tags, :objects, :colors, :text,
         :raw_response, :started_at, :completed_at, :tenant_id, :analyzer_class,
         :error_class, :error_message
+      attr_accessor :execution_id
 
       # Initialize a new result
       #
@@ -59,6 +60,14 @@ module RubyLLM
         @analyzer_class = analyzer_class
         @error_class = error_class
         @error_message = error_message
+        @execution_id = nil
+      end
+
+      # Loads the associated Execution record from the database
+      #
+      # @return [RubyLLM::Agents::Execution, nil] The execution record, or nil
+      def execution
+        @execution ||= RubyLLM::Agents::Execution.find_by(id: execution_id) if execution_id
       end
 
       # Status helpers
@@ -205,7 +214,8 @@ module RubyLLM
           tenant_id: tenant_id,
           analyzer_class: analyzer_class,
           error_class: error_class,
-          error_message: error_message
+          error_message: error_message,
+          execution_id: execution_id
         }
       end
 

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

@@ -20,6 +20,7 @@ module RubyLLM
       attr_reader :images, :source_image, :mask, :prompt, :model_id, :size,
         :started_at, :completed_at, :tenant_id, :editor_class,
         :error_class, :error_message
+      attr_accessor :execution_id
 
       # Initialize a new result
       #
@@ -50,6 +51,14 @@ module RubyLLM
         @editor_class = editor_class
         @error_class = error_class
         @error_message = error_message
+        @execution_id = nil
+      end
+
+      # Loads the associated Execution record from the database
+      #
+      # @return [RubyLLM::Agents::Execution, nil] The execution record, or nil
+      def execution
+        @execution ||= RubyLLM::Agents::Execution.find_by(id: execution_id) if execution_id
       end
 
       # Status helpers
@@ -175,7 +184,8 @@ module RubyLLM
           tenant_id: tenant_id,
           editor_class: editor_class,
           error_class: error_class,
-          error_message: error_message
+          error_message: error_message,
+          execution_id: execution_id
         }
       end
 

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

@@ -22,7 +22,7 @@ module RubyLLM
     class ImageGenerationResult
       attr_reader :images, :prompt, :model_id, :size, :quality, :style,
         :started_at, :completed_at, :tenant_id, :generator_class,
-        :error_class, :error_message
+        :error_class, :error_message, :execution_id
 
       # Initialize a new result
       #
@@ -40,7 +40,7 @@ module RubyLLM
       # @param error_message [String, nil] Error message if failed
       def initialize(images:, prompt:, model_id:, size:, quality:, style:,
         started_at:, completed_at:, tenant_id:, generator_class:,
-        error_class: nil, error_message: nil)
+        error_class: nil, error_message: nil, execution_id: nil)
         @images = images
         @prompt = prompt
         @model_id = model_id
@@ -53,6 +53,14 @@ module RubyLLM
         @generator_class = generator_class
         @error_class = error_class
         @error_message = error_message
+        @execution_id = execution_id
+      end
+
+      # Loads the associated Execution record from the database
+      #
+      # @return [RubyLLM::Agents::Execution, nil] The execution record, or nil
+      def execution
+        @execution ||= RubyLLM::Agents::Execution.find_by(id: execution_id) if execution_id
       end
 
       # Status helpers
@@ -257,7 +265,8 @@ module RubyLLM
           tenant_id: tenant_id,
           generator_class: generator_class,
           error_class: error_class,
-          error_message: error_message
+          error_message: error_message,
+          execution_id: execution_id
         }
       end
 

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

@@ -23,6 +23,7 @@ module RubyLLM
     class ImagePipelineResult
       attr_reader :step_results, :started_at, :completed_at, :tenant_id,
         :pipeline_class, :context, :error_class, :error_message
+      attr_accessor :execution_id
 
       # Initialize a new pipeline result
       #
@@ -44,6 +45,14 @@ module RubyLLM
         @context = context
         @error_class = error_class
         @error_message = error_message
+        @execution_id = nil
+      end
+
+      # Loads the associated Execution record from the database
+      #
+      # @return [RubyLLM::Agents::Execution, nil] The execution record, or nil
+      def execution
+        @execution ||= RubyLLM::Agents::Execution.find_by(id: execution_id) if execution_id
       end
 
       # Status helpers
@@ -315,7 +324,8 @@ module RubyLLM
           tenant_id: tenant_id,
           pipeline_class: pipeline_class,
           error_class: error_class,
-          error_message: error_message
+          error_message: error_message,
+          execution_id: execution_id
         }
       end
 

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

@@ -20,6 +20,7 @@ module RubyLLM
       attr_reader :images, :source_image, :prompt, :model_id, :size, :strength,
         :started_at, :completed_at, :tenant_id, :transformer_class,
         :error_class, :error_message
+      attr_accessor :execution_id
 
       # Initialize a new result
       #
@@ -50,6 +51,14 @@ module RubyLLM
         @transformer_class = transformer_class
         @error_class = error_class
         @error_message = error_message
+        @execution_id = nil
+      end
+
+      # Loads the associated Execution record from the database
+      #
+      # @return [RubyLLM::Agents::Execution, nil] The execution record, or nil
+      def execution
+        @execution ||= RubyLLM::Agents::Execution.find_by(id: execution_id) if execution_id
       end
 
       # Status helpers
@@ -176,7 +185,8 @@ module RubyLLM
           tenant_id: tenant_id,
           transformer_class: transformer_class,
           error_class: error_class,
-          error_message: error_message
+          error_message: error_message,
+          execution_id: execution_id
         }
       end
 

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

@@ -18,6 +18,7 @@ module RubyLLM
       attr_reader :image, :source_image, :model_id, :scale, :output_size, :face_enhance,
         :started_at, :completed_at, :tenant_id, :upscaler_class,
         :error_class, :error_message
+      attr_accessor :execution_id
 
       # Initialize a new result
       #
@@ -48,6 +49,14 @@ module RubyLLM
         @upscaler_class = upscaler_class
         @error_class = error_class
         @error_message = error_message
+        @execution_id = nil
+      end
+
+      # Loads the associated Execution record from the database
+      #
+      # @return [RubyLLM::Agents::Execution, nil] The execution record, or nil
+      def execution
+        @execution ||= RubyLLM::Agents::Execution.find_by(id: execution_id) if execution_id
       end
 
       # Status helpers
@@ -171,7 +180,8 @@ module RubyLLM
           tenant_id: tenant_id,
           upscaler_class: upscaler_class,
           error_class: error_class,
-          error_message: error_message
+          error_message: error_message,
+          execution_id: execution_id
         }
       end
 

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

@@ -17,6 +17,7 @@ module RubyLLM
       attr_reader :images, :source_image, :model_id, :size, :variation_strength,
         :started_at, :completed_at, :tenant_id, :variator_class,
         :error_class, :error_message
+      attr_accessor :execution_id
 
       # Initialize a new result
       #
@@ -45,6 +46,14 @@ module RubyLLM
         @variator_class = variator_class
         @error_class = error_class
         @error_message = error_message
+        @execution_id = nil
+      end
+
+      # Loads the associated Execution record from the database
+      #
+      # @return [RubyLLM::Agents::Execution, nil] The execution record, or nil
+      def execution
+        @execution ||= RubyLLM::Agents::Execution.find_by(id: execution_id) if execution_id
       end
 
       # Status helpers
@@ -162,7 +171,8 @@ module RubyLLM
           tenant_id: tenant_id,
           variator_class: variator_class,
           error_class: error_class,
-          error_message: error_message
+          error_message: error_message,
+          execution_id: execution_id
         }
       end