ruby_llm-agents 3.10.0 → 3.12.0

data/lib/ruby_llm/agents/routing/result.rb

@@ -5,15 +5,23 @@ module RubyLLM
     module Routing
       # Wraps a standard Result with routing-specific accessors.
       #
-      # Delegates all standard Result methods (tokens, cost, timing, etc.)
-      # to the underlying result, adding only the route-specific interface.
+      # When the route has an `agent:` mapping, the router auto-delegates
+      # to that agent. The delegated result is available via `delegated_result`,
+      # and `content` returns the delegated agent's content.
       #
-      # @example
+      # @example Classification only (no agent mapping)
       #   result = SupportRouter.call(message: "I was charged twice")
       #   result.route        # => :billing
-      #   result.agent_class  # => BillingAgent (if mapped)
-      #   result.success?     # => true
-      #   result.total_cost   # => 0.0001
+      #   result.delegated?   # => false
+      #
+      # @example Auto-delegation (with agent mapping)
+      #   result = SupportRouter.call(message: "I was charged twice")
+      #   result.route            # => :billing
+      #   result.delegated?       # => true
+      #   result.delegated_to     # => BillingAgent
+      #   result.content          # => BillingAgent's response content
+      #   result.routing_cost     # => cost of classification step
+      #   result.total_cost       # => classification + delegation
       #
       class RoutingResult < Result
         # @return [Symbol] The classified route name
@@ -25,6 +33,9 @@ module RubyLLM
         # @return [String] The raw text response from the LLM
         attr_reader :raw_response
 
+        # @return [Result, nil] The result from the delegated agent (if auto-delegated)
+        attr_reader :delegated_result
+
         # Creates a new RoutingResult by wrapping a base Result with route data.
         #
         # @param base_result [Result] The standard Result from BaseAgent execution
@@ -32,14 +43,32 @@ module RubyLLM
         # @option route_data [Symbol] :route The classified route name
         # @option route_data [Class, nil] :agent_class Mapped agent class
         # @option route_data [String] :raw_response Raw LLM text
+        # @option route_data [Result, nil] :delegated_result Result from auto-delegation
         def initialize(base_result:, route_data:)
+          @delegated_result = route_data[:delegated_result]
+          @routing_cost = base_result.total_cost
+
+          # When delegated, merge costs from both classification and delegation
+          total = if @delegated_result
+            (base_result.total_cost || 0) + (@delegated_result.respond_to?(:total_cost) ? @delegated_result.total_cost || 0 : 0)
+          else
+            base_result.total_cost
+          end
+
+          # Use delegated content when available
+          effective_content = if @delegated_result
+            @delegated_result.respond_to?(:content) ? @delegated_result.content : route_data
+          else
+            route_data
+          end
+
           super(
-            content: route_data,
+            content: effective_content,
             input_tokens: base_result.input_tokens,
             output_tokens: base_result.output_tokens,
             input_cost: base_result.input_cost,
             output_cost: base_result.output_cost,
-            total_cost: base_result.total_cost,
+            total_cost: total,
             model_id: base_result.model_id,
             chosen_model_id: base_result.chosen_model_id,
             temperature: base_result.temperature,
@@ -58,6 +87,27 @@ module RubyLLM
           @raw_response = route_data[:raw_response]
         end
 
+        # Whether the router auto-delegated to a mapped agent
+        #
+        # @return [Boolean]
+        def delegated?
+          !@delegated_result.nil?
+        end
+
+        # The agent class that was auto-invoked (alias for agent_class)
+        #
+        # @return [Class, nil]
+        def delegated_to
+          @agent_class if delegated?
+        end
+
+        # Cost of the classification step only (excluding delegation)
+        #
+        # @return [Float]
+        def routing_cost
+          @routing_cost || 0
+        end
+
         # Converts the result to a hash including routing fields.
         #
         # @return [Hash] All result data plus route, agent_class, raw_response
@@ -65,7 +115,8 @@ module RubyLLM
           super.merge(
             route: route,
             agent_class: agent_class&.name,
-            raw_response: raw_response
+            raw_response: raw_response,
+            delegated: delegated?
           )
         end
       end

data/lib/ruby_llm/agents/routing.rb

@@ -131,10 +131,29 @@ module RubyLLM
       end
 
       # Override build_result to return a RoutingResult.
+      # Auto-delegates to the mapped agent when the route has an `agent:` mapping.
       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)
+        end
+
         RoutingResult.new(base_result: base, route_data: content)
       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[:_parent_execution_id] = @parent_execution_id if @parent_execution_id
+        forward[:_root_execution_id] = @root_execution_id if @root_execution_id
+        forward
+      end
     end
   end
 end

data/lib/ruby_llm/agents/stream_event.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    # Typed event emitted during streaming execution.
+    #
+    # 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, and errors.
+    #
+    # @example Basic usage
+    #   MyAgent.call(query: "test", stream_events: true) do |event|
+    #     case event.type
+    #     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 :error       then puts "Error: #{event.data[:message]}"
+    #     end
+    #   end
+    #
+    class StreamEvent
+      # @return [Symbol] Event type (:chunk, :tool_start, :tool_end, :error)
+      attr_reader :type
+
+      # @return [Hash] Event-specific data
+      attr_reader :data
+
+      # Creates a new StreamEvent
+      #
+      # @param type [Symbol] The event type
+      # @param data [Hash] Event-specific data
+      def initialize(type, data = {})
+        @type = type
+        @data = data
+      end
+
+      # @return [Boolean] Whether this is a text chunk event
+      def chunk?
+        @type == :chunk
+      end
+
+      # @return [Boolean] Whether this is a tool lifecycle event
+      def tool_event?
+        @type == :tool_start || @type == :tool_end
+      end
+
+      # @return [Boolean] Whether this is an error event
+      def error?
+        @type == :error
+      end
+
+      def to_h
+        {type: @type, data: @data}
+      end
+    end
+  end
+end

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,8 +23,8 @@ 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"
 
 # Tool base class and context for coding agents
 require_relative "agents/tool_context"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm-agents
 version: !ruby/object:Gem::Version
-  version: 3.10.0
+  version: 3.12.0
 platform: ruby
 authors:
 - adham90
@@ -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
@@ -242,6 +245,7 @@ files:
 - lib/ruby_llm/agents/dsl.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
@@ -326,6 +330,7 @@ files:
 - lib/ruby_llm/agents/routing.rb
 - lib/ruby_llm/agents/routing/class_methods.rb
 - lib/ruby_llm/agents/routing/result.rb
+- lib/ruby_llm/agents/stream_event.rb
 - lib/ruby_llm/agents/text/embedder.rb
 - lib/ruby_llm/agents/tool.rb
 - lib/ruby_llm/agents/tool_context.rb

data/lib/ruby_llm/agents/agent_tool.rb

@@ -1,125 +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
-      # @return [Class] An anonymous RubyLLM::Tool subclass
-      def self.for(agent_class)
-        tool_name = derive_tool_name(agent_class)
-        tool_desc = agent_class.respond_to?(:description) ? agent_class.description : nil
-        agent_params = agent_class.respond_to?(:params) ? agent_class.params : {}
-        captured_agent_class = agent_class
-
-        Class.new(RubyLLM::Tool) do
-          description tool_desc if tool_desc
-
-          # Map agent params to tool params
-          agent_params.each do |name, config|
-            next if name.to_s.start_with?("_")
-
-            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 }
-
-          # 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)
-            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