ruby_llm-agents 3.11.0 → 3.13.0

data/lib/ruby_llm/agents/routing.rb

@@ -115,6 +115,15 @@ module RubyLLM
         @ask_message || options[:message] || super
       end
 
+      # Override call to capture the caller's stream block so it can be
+      # forwarded to the delegated agent. Without this, chunks from the
+      # delegated agent are swallowed because build_result has no access
+      # to the original block.
+      def call(&block)
+        @delegation_stream_block = block
+        super
+      end
+
       # Override process_response to parse the route from LLM output.
       def process_response(response)
         raw = response.content.to_s.strip.downcase.gsub(/[^a-z0-9_]/, "")
@@ -131,25 +140,39 @@ module RubyLLM
       end
 
       # Override build_result to return a RoutingResult.
-      # Auto-delegates to the mapped agent when the route has an `agent:` mapping.
+      # Auto-delegates to the mapped agent when the route has an `agent:` mapping,
+      # unless the caller opts out with `auto_delegate: false`.
       def build_result(content, response, context)
         base = super
 
-        # Auto-delegate to the mapped agent
         agent_class = content[:agent_class]
-        if agent_class
-          content[:delegated_result] = agent_class.call(**delegation_params)
+        if agent_class && auto_delegate?
+          content[:delegated_result] = if @delegation_stream_block
+            agent_class.call(**delegation_params, &@delegation_stream_block)
+          else
+            agent_class.call(**delegation_params)
+          end
         end
 
         RoutingResult.new(base_result: base, route_data: content)
       end
 
+      # Whether auto-delegation to the mapped agent is enabled for this call.
+      # Defaults to true. Pass `auto_delegate: false` to receive a
+      # classification-only RoutingResult with `delegated? == false` and
+      # `agent_class` set so the caller can invoke it manually.
+      #
+      # @return [Boolean]
+      def auto_delegate?
+        @options.fetch(:auto_delegate, true)
+      end
+
       # Builds params to forward to the delegated agent.
       # Forwards original message and custom params, excludes routing internals.
       #
       # @return [Hash] Params for the delegated agent
       def delegation_params
-        forward = @options.except(:dry_run, :skip_cache, :debug, :stream_events)
+        forward = @options.except(:dry_run, :skip_cache, :debug, :stream_events, :auto_delegate)
         forward[:_parent_execution_id] = @parent_execution_id if @parent_execution_id
         forward[:_root_execution_id] = @root_execution_id if @root_execution_id
         forward

data/lib/ruby_llm/agents/stream_event.rb

@@ -7,7 +7,7 @@ module RubyLLM
     # When `stream_events: true` is passed to an agent call, the stream
     # block receives StreamEvent objects instead of raw RubyLLM chunks.
     # This provides visibility into the full execution lifecycle —
-    # text chunks, tool invocations, agent delegations, and errors.
+    # text chunks, tool invocations, and errors.
     #
     # @example Basic usage
     #   MyAgent.call(query: "test", stream_events: true) do |event|
@@ -15,15 +15,12 @@ module RubyLLM
     #     when :chunk       then print event.data[:content]
     #     when :tool_start  then puts "Running #{event.data[:tool_name]}..."
     #     when :tool_end    then puts "Done (#{event.data[:duration_ms]}ms)"
-    #     when :agent_start then puts "Delegated to #{event.data[:agent_name]}"
-    #     when :agent_end   then puts "Agent done (#{event.data[:duration_ms]}ms)"
     #     when :error       then puts "Error: #{event.data[:message]}"
     #     end
     #   end
     #
     class StreamEvent
-      # @return [Symbol] Event type (:chunk, :tool_start, :tool_end,
-      #   :agent_start, :agent_end, :error)
+      # @return [Symbol] Event type (:chunk, :tool_start, :tool_end, :error)
       attr_reader :type
 
       # @return [Hash] Event-specific data
@@ -48,11 +45,6 @@ module RubyLLM
         @type == :tool_start || @type == :tool_end
       end
 
-      # @return [Boolean] Whether this is an agent lifecycle event
-      def agent_event?
-        @type == :agent_start || @type == :agent_end
-      end
-
       # @return [Boolean] Whether this is an error event
       def error?
         @type == :error

data/lib/ruby_llm/agents/tool.rb

@@ -31,7 +31,7 @@ module RubyLLM
     # @example Using with an agent
     #   class CodingAgent < ApplicationAgent
     #     param :container_id, required: true
-    #     tools [BashTool]
+    #     tools BashTool
     #   end
     #
     #   CodingAgent.call(query: "list files", container_id: "abc123")

data/lib/ruby_llm/agents.rb

@@ -23,9 +23,6 @@ require_relative "agents/dsl"
 # BaseAgent - new middleware-based agent architecture
 require_relative "agents/base_agent"
 
-# Agent-as-Tool adapter
-require_relative "agents/agent_tool"
-
 # Streaming events
 require_relative "agents/stream_event"
 
@@ -99,6 +96,7 @@ if defined?(Rails)
   require_relative "agents/core/inflections"
   require_relative "agents/core/instrumentation"
   require_relative "agents/infrastructure/execution_logger_job"
+  require_relative "agents/infrastructure/retention_job"
 end
 require_relative "agents/rails/engine" if defined?(Rails::Engine)
 

data/lib/tasks/ruby_llm_agents.rake

@@ -7,6 +7,13 @@ namespace :ruby_llm_agents do
     RubyLlmAgents::DoctorGenerator.start([])
   end
 
+  desc "Run the retention job synchronously (soft + hard purges per configuration)"
+  task purge: :environment do
+    result = RubyLLM::Agents::RetentionJob.new.perform
+    puts "Soft purged: #{result[:soft_purged]} executions (details destroyed)"
+    puts "Hard purged: #{result[:hard_purged]} executions (rows destroyed)"
+  end
+
   desc "Rename an agent type in execution records. Usage: rake ruby_llm_agents:rename_agent FROM=OldName TO=NewName [DRY_RUN=1]"
   task rename_agent: :environment do
     from = ENV["FROM"]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm-agents
 version: !ruby/object:Gem::Version
-  version: 3.11.0
+  version: 3.13.0
 platform: ruby
 authors:
 - adham90
@@ -29,14 +29,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.12.0
+        version: 1.14.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.12.0
+        version: 1.14.1
 - !ruby/object:Gem::Dependency
   name: csv
   requirement: !ruby/object:Gem::Requirement
@@ -80,12 +80,14 @@ files:
 - app/controllers/concerns/ruby_llm/agents/paginatable.rb
 - app/controllers/concerns/ruby_llm/agents/sortable.rb
 - app/controllers/ruby_llm/agents/agents_controller.rb
+- app/controllers/ruby_llm/agents/analytics_controller.rb
 - app/controllers/ruby_llm/agents/dashboard_controller.rb
 - app/controllers/ruby_llm/agents/executions_controller.rb
 - app/controllers/ruby_llm/agents/requests_controller.rb
 - app/controllers/ruby_llm/agents/system_config_controller.rb
 - app/controllers/ruby_llm/agents/tenants_controller.rb
 - app/helpers/ruby_llm/agents/application_helper.rb
+- app/models/ruby_llm/agents/agent_override.rb
 - app/models/ruby_llm/agents/execution.rb
 - app/models/ruby_llm/agents/execution/analytics.rb
 - app/models/ruby_llm/agents/execution/metrics.rb
@@ -112,6 +114,7 @@ files:
 - app/views/ruby_llm/agents/agents/_sortable_header.html.erb
 - app/views/ruby_llm/agents/agents/index.html.erb
 - app/views/ruby_llm/agents/agents/show.html.erb
+- app/views/ruby_llm/agents/analytics/index.html.erb
 - app/views/ruby_llm/agents/dashboard/_action_center.html.erb
 - app/views/ruby_llm/agents/dashboard/_tenant_budget.html.erb
 - app/views/ruby_llm/agents/dashboard/_top_tenants.html.erb
@@ -185,6 +188,7 @@ files:
 - lib/generators/ruby_llm_agents/templates/application_transcriber.rb.tt
 - lib/generators/ruby_llm_agents/templates/background_remover.rb.tt
 - lib/generators/ruby_llm_agents/templates/create_execution_details_migration.rb.tt
+- lib/generators/ruby_llm_agents/templates/create_overrides_migration.rb.tt
 - lib/generators/ruby_llm_agents/templates/create_tenant_budgets_migration.rb.tt
 - lib/generators/ruby_llm_agents/templates/create_tenants_migration.rb.tt
 - lib/generators/ruby_llm_agents/templates/embedder.rb.tt
@@ -221,7 +225,6 @@ files:
 - lib/generators/ruby_llm_agents/upgrade_generator.rb
 - lib/ruby_llm-agents.rb
 - lib/ruby_llm/agents.rb
-- lib/ruby_llm/agents/agent_tool.rb
 - lib/ruby_llm/agents/audio/elevenlabs/model_registry.rb
 - lib/ruby_llm/agents/audio/speaker.rb
 - lib/ruby_llm/agents/audio/speaker/active_storage_support.rb
@@ -240,9 +243,9 @@ files:
 - lib/ruby_llm/agents/core/llm_tenant.rb
 - lib/ruby_llm/agents/core/version.rb
 - lib/ruby_llm/agents/dsl.rb
-- lib/ruby_llm/agents/dsl/agents.rb
 - lib/ruby_llm/agents/dsl/base.rb
 - lib/ruby_llm/agents/dsl/caching.rb
+- lib/ruby_llm/agents/dsl/knowledge.rb
 - lib/ruby_llm/agents/dsl/queryable.rb
 - lib/ruby_llm/agents/dsl/reliability.rb
 - lib/ruby_llm/agents/eval.rb
@@ -287,6 +290,7 @@ files:
 - lib/ruby_llm/agents/infrastructure/circuit_breaker.rb
 - lib/ruby_llm/agents/infrastructure/execution_logger_job.rb
 - lib/ruby_llm/agents/infrastructure/reliability.rb
+- lib/ruby_llm/agents/infrastructure/retention_job.rb
 - lib/ruby_llm/agents/pipeline.rb
 - lib/ruby_llm/agents/pipeline/builder.rb
 - lib/ruby_llm/agents/pipeline/context.rb

data/lib/ruby_llm/agents/agent_tool.rb

@@ -1,143 +0,0 @@
-# frozen_string_literal: true
-
-module RubyLLM
-  module Agents
-    # Wraps an agent class as a RubyLLM::Tool so it can be used
-    # in another agent's `tools` list. The LLM sees the sub-agent
-    # as a callable tool and can invoke it with the agent's declared params.
-    module AgentTool
-      MAX_AGENT_TOOL_DEPTH = 5
-
-      # Wraps an agent class as a RubyLLM::Tool subclass.
-      #
-      # @param agent_class [Class] A BaseAgent subclass
-      # @param forwarded_params [Array<Symbol>] Params auto-injected from parent (excluded from LLM schema)
-      # @param description_override [String, nil] Custom description for the tool
-      # @param delegate [Boolean] Whether this tool represents an agent delegate (from `agents` DSL)
-      # @return [Class] An anonymous RubyLLM::Tool subclass
-      def self.for(agent_class, forwarded_params: [], description_override: nil, delegate: false)
-        tool_name = derive_tool_name(agent_class)
-        tool_desc = description_override || (agent_class.respond_to?(:description) ? agent_class.description : nil)
-        agent_params = agent_class.respond_to?(:params) ? agent_class.params : {}
-        captured_agent_class = agent_class
-        captured_forwarded = Array(forwarded_params).map(&:to_sym)
-        is_delegate = delegate
-
-        Class.new(RubyLLM::Tool) do
-          description tool_desc if tool_desc
-
-          # Map agent params to tool params, excluding forwarded ones
-          agent_params.each do |name, config|
-            next if name.to_s.start_with?("_")
-            next if captured_forwarded.include?(name.to_sym)
-
-            param name,
-              desc: config[:desc] || "#{name} parameter",
-              required: config[:required] == true,
-              type: AgentTool.map_type(config[:type])
-          end
-
-          # Store references on the class
-          define_singleton_method(:agent_class) { captured_agent_class }
-          define_singleton_method(:tool_name) { tool_name }
-          define_singleton_method(:agent_delegate?) { is_delegate }
-          define_singleton_method(:forwarded_params) { captured_forwarded }
-
-          # Instance #name returns the derived tool name
-          define_method(:name) { tool_name }
-
-          define_method(:execute) do |**kwargs|
-            depth = (Thread.current[:ruby_llm_agents_tool_depth] || 0) + 1
-            if depth > MAX_AGENT_TOOL_DEPTH
-              return "Error calling #{captured_agent_class.name}: Agent tool depth exceeded (max #{MAX_AGENT_TOOL_DEPTH})"
-            end
-
-            Thread.current[:ruby_llm_agents_tool_depth] = depth
-
-            # Inject hierarchy context from thread-local (set by calling agent)
-            caller_ctx = Thread.current[:ruby_llm_agents_caller_context]
-
-            call_kwargs = kwargs.dup
-            if caller_ctx
-              call_kwargs[:_parent_execution_id] = caller_ctx.execution_id
-              call_kwargs[:_root_execution_id] = caller_ctx.root_execution_id || caller_ctx.execution_id
-              call_kwargs[:tenant] = caller_ctx.tenant_object if caller_ctx.tenant_id && !call_kwargs.key?(:tenant)
-
-              # Inject forwarded params from the parent agent instance
-              if captured_forwarded.any? && caller_ctx.agent_instance
-                captured_forwarded.each do |param_name|
-                  next if call_kwargs.key?(param_name)
-                  if caller_ctx.agent_instance.respond_to?(param_name)
-                    call_kwargs[param_name] = caller_ctx.agent_instance.send(param_name)
-                  end
-                end
-              end
-            end
-
-            result = captured_agent_class.call(**call_kwargs)
-            content = result.respond_to?(:content) ? result.content : result
-            case content
-            when String then content
-            when Hash then content.to_json
-            when nil then "(no response)"
-            else content.to_s
-            end
-          rescue => e
-            "Error calling #{captured_agent_class.name}: #{e.message}"
-          ensure
-            Thread.current[:ruby_llm_agents_tool_depth] = depth - 1
-          end
-        end
-      end
-
-      # Converts agent class name to tool name.
-      #
-      # @example
-      #   ResearchAgent    -> "research"
-      #   CodeReviewAgent  -> "code_review"
-      #
-      # @param agent_class [Class] The agent class
-      # @return [String] Snake-cased tool name
-      def self.derive_tool_name(agent_class)
-        raw = agent_class.name.to_s.split("::").last
-        raw.gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
-          .gsub(/([a-z\d])([A-Z])/, '\1_\2')
-          .downcase
-          .sub(/_agent$/, "")
-      end
-
-      # Maps Ruby types to JSON Schema types for tool parameters.
-      #
-      # @param type [Class, Symbol, nil] Ruby type
-      # @return [Symbol] JSON Schema type
-      def self.map_type(type)
-        case type
-        when :integer then :integer
-        when :number, :float then :number
-        when :boolean then :boolean
-        when :array then :array
-        when :object then :object
-        else
-          # Handle class objects (Integer, Float, Array, Hash, etc.)
-          if type.is_a?(Class)
-            if type <= Integer
-              :integer
-            elsif type <= Float
-              :number
-            elsif type <= Array
-              :array
-            elsif type <= Hash
-              :object
-            elsif type == TrueClass || type == FalseClass
-              :boolean
-            else
-              :string
-            end
-          else
-            :string
-          end
-        end
-      end
-    end
-  end
-end

data/lib/ruby_llm/agents/dsl/agents.rb

@@ -1,141 +0,0 @@
-# frozen_string_literal: true
-
-module RubyLLM
-  module Agents
-    module DSL
-      # DSL module for declaring sub-agents on an agent class.
-      #
-      # Provides two forms — simple list for common cases, block for
-      # per-agent configuration:
-      #
-      # @example Simple form
-      #   agents [ModelsAgent, ViewsAgent], forward: [:workspace_path]
-      #
-      # @example Block form
-      #   agents do
-      #     use ModelsAgent, timeout: 180, description: "Build models"
-      #     use ViewsAgent
-      #     forward :workspace_path, :project_id
-      #     parallel true
-      #   end
-      #
-      module Agents
-        # Declares sub-agents for this agent class.
-        #
-        # @param list [Array<Class>, nil] Agent classes (simple form)
-        # @param options [Hash] Global options (simple form)
-        # @yield Configuration block (block form)
-        # @return [Array<Hash>] Agent entries
-        def agents(list = nil, **options, &block)
-          if block
-            config = AgentsConfig.new
-            config.instance_eval(&block)
-            @agents_config = config
-          elsif list
-            config = AgentsConfig.new
-            Array(list).each { |a| config.use(a) }
-            options.each { |k, v| config.send(k, *Array(v)) }
-            @agents_config = config
-          end
-          @agents_config&.agent_entries || []
-        end
-
-        # Returns the agents configuration object.
-        #
-        # @return [AgentsConfig] Configuration (empty if no agents declared)
-        def agents_config
-          @agents_config ||
-            (superclass.respond_to?(:agents_config) ? superclass.agents_config : nil) ||
-            AgentsConfig.new
-        end
-      end
-    end
-
-    # Configuration object for the `agents` DSL.
-    #
-    # Holds the list of agent entries and global options like
-    # `parallel`, `forward`, `max_depth`, and `instructions`.
-    #
-    class AgentsConfig
-      attr_reader :agent_entries
-
-      def initialize
-        @agent_entries = []
-        @options = {
-          parallel: true,
-          timeout: nil,
-          max_depth: 5,
-          forward: [],
-          instructions: nil
-        }
-      end
-
-      # Registers an agent class with optional per-agent overrides.
-      #
-      # @param agent_class [Class] A BaseAgent subclass
-      # @param timeout [Integer, nil] Per-agent timeout override
-      # @param description [String, nil] Per-agent description override
-      def use(agent_class, timeout: nil, description: nil)
-        @agent_entries << {
-          agent_class: agent_class,
-          timeout: timeout,
-          description: description
-        }
-      end
-
-      # @!group Global Options
-
-      def parallel(value = true)
-        @options[:parallel] = value
-      end
-
-      def timeout(seconds)
-        @options[:timeout] = seconds
-      end
-
-      def max_depth(depth)
-        @options[:max_depth] = depth
-      end
-
-      def instructions(text)
-        @options[:instructions] = text
-      end
-
-      def forward(*params)
-        @options[:forward] = params.flatten
-      end
-
-      # @!endgroup
-
-      # @!group Query Methods
-
-      def parallel?
-        @options[:parallel]
-      end
-
-      def timeout_for(agent_class)
-        entry = @agent_entries.find { |e| e[:agent_class] == agent_class }
-        entry&.dig(:timeout) || @options[:timeout]
-      end
-
-      def forwarded_params
-        @options[:forward]
-      end
-
-      def max_depth_value
-        @options[:max_depth]
-      end
-
-      def instructions_text
-        @options[:instructions]
-      end
-
-      def description_for(agent_class)
-        entry = @agent_entries.find { |e| e[:agent_class] == agent_class }
-        entry&.dig(:description)
-      end
-
-      # @!endgroup
-    end
-  end
-end