ruby_llm-agents 3.5.4 → 3.6.0

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

@@ -51,36 +51,12 @@ module RubyLLM
         # @param context [Context] The execution context
         # @return [Context] The context with output set
         def call(context)
-          @agent.execute(context)
+          @agent.send(:execute, context)
           context
         end
       end
 
       # Lambda-based executor for simple cases
-      #
-      # Allows wrapping a lambda/proc as the core executor,
-      # useful for testing or simple agents.
-      #
-      # @example
-      #   executor = LambdaExecutor.new(->(ctx) {
-      #     ctx.output = "Hello, #{ctx.input}!"
-      #   })
-      #
-      class LambdaExecutor
-        # @param callable [#call] A lambda/proc that takes a context
-        def initialize(callable)
-          @callable = callable
-        end
-
-        # Execute the lambda with the context
-        #
-        # @param context [Context] The execution context
-        # @return [Context] The context (possibly modified by the lambda)
-        def call(context)
-          @callable.call(context)
-          context
-        end
-      end
     end
   end
 end

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

@@ -39,13 +39,35 @@ module RubyLLM
             @app.call(context)
 
             # Record spend after successful execution (if not cached)
-            record_spend!(context) if context.success? && !context.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
           end
 
           private
 
+          # Emits an AS::Notification for budget events
+          #
+          # @param event [String] The notification event name
+          # @param context [Context] The execution context
+          # @param extras [Hash] Additional payload fields
+          def emit_budget_notification(event, context, **extras)
+            ActiveSupport::Notifications.instrument(
+              event,
+              {
+                agent_type: context.agent_class&.name,
+                tenant_id: context.tenant_id
+              }.merge(extras)
+            )
+          rescue
+            # Never let notifications break execution
+          end
+
           # Returns whether budgets are enabled globally
           #
           # @return [Boolean]
@@ -63,6 +85,8 @@ module RubyLLM
           # @param context [Context] The execution context
           # @raise [BudgetExceededError] If budget exceeded with hard enforcement
           def check_budget!(context)
+            emit_budget_notification("ruby_llm_agents.budget.check", context)
+
             if context.tenant_id.present?
               tenant = RubyLLM::Agents::Tenant.find_by(tenant_id: context.tenant_id)
               if tenant
@@ -77,6 +101,7 @@ module RubyLLM
               tenant_id: context.tenant_id
             )
           rescue RubyLLM::Agents::Reliability::BudgetExceededError
+            emit_budget_notification("ruby_llm_agents.budget.exceeded", context)
             raise
           rescue => e
             error("Budget check failed: #{e.message}")

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

@@ -41,10 +41,13 @@ module RubyLLM
                 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
               end
             end
 
+            emit_cache_notification("ruby_llm_agents.cache.miss", cache_key)
+
             # Execute the chain
             @app.call(context)
 
@@ -52,6 +55,7 @@ module RubyLLM
             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)
             end
 
             context
@@ -59,6 +63,20 @@ module RubyLLM
 
           private
 
+          # Emits an AS::Notification for cache events
+          #
+          # @param event [String] The notification event name
+          # @param cache_key [String] The cache key involved
+          def emit_cache_notification(event, cache_key)
+            ActiveSupport::Notifications.instrument(
+              event,
+              agent_type: @agent_class&.name,
+              cache_key: cache_key
+            )
+          rescue
+            # Never let notifications break execution
+          end
+
           # Returns whether caching is enabled for this agent
           #
           # @return [Boolean]

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
@@ -202,6 +267,28 @@ module RubyLLM
               data[:tenant_id] = context.tenant_id
             end
 
+            # Include agent-defined metadata so it appears on the dashboard immediately
+            agent_meta = safe_agent_metadata(context)
+            if agent_meta.any?
+              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
 
@@ -222,12 +309,18 @@ module RubyLLM
               attempts_count: context.attempts_made
             }
 
-            # Store niche cache key in metadata
-            merged_metadata = begin
+            # Merge metadata: agent metadata (base) < middleware metadata (overlay)
+            agent_meta = safe_agent_metadata(context)
+            merged_metadata = agent_meta.transform_keys(&:to_s)
+
+            context_meta = begin
               context.metadata.dup
             rescue
               {}
             end
+            context_meta.transform_keys!(&:to_s)
+            merged_metadata.merge!(context_meta)
+
             if context.cached? && context[:cache_key]
               merged_metadata["response_cache_key"] = context[:cache_key]
             end
@@ -321,11 +414,18 @@ module RubyLLM
           # @param status [String] "success" or "error"
           # @return [Hash] Execution data
           def build_execution_data(context, status)
-            merged_metadata = begin
+            # Merge metadata: agent metadata (base) < middleware metadata (overlay)
+            agent_meta = safe_agent_metadata(context)
+            merged_metadata = agent_meta.transform_keys(&:to_s)
+
+            context_meta = begin
               context.metadata.dup
             rescue
               {}
             end
+            context_meta.transform_keys!(&:to_s)
+            merged_metadata.merge!(context_meta)
+
             if context.cached? && context[:cache_key]
               merged_metadata["response_cache_key"] = context[:cache_key]
             end
@@ -423,15 +523,42 @@ module RubyLLM
               params[key] = "[REDACTED]" if params.key?(key)
             end
 
+            INTERNAL_KEYS.each do |key|
+              params.delete(key)
+            end
+
             params
           end
 
+          # Safely retrieves custom metadata from the agent instance
+          #
+          # Returns an empty hash if the agent doesn't define metadata,
+          # the method raises, or the result isn't a Hash.
+          #
+          # @param context [Context] The execution context
+          # @return [Hash] Agent-defined metadata, or empty hash
+          def safe_agent_metadata(context)
+            return {} unless context.agent_instance
+            return {} unless context.agent_instance.respond_to?(:metadata)
+
+            result = context.agent_instance.metadata
+            result.is_a?(Hash) ? result : {}
+          rescue => e
+            debug("Failed to retrieve agent metadata: #{e.message}")
+            {}
+          end
+
           # Sensitive parameter keys that should be redacted
           SENSITIVE_KEYS = %w[
             password token api_key secret credential auth key
             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