ruby_llm-agents 3.11.0 → 3.12.0

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

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    module DSL
+      # Knowledge DSL for declaring domain knowledge to inject into system prompts.
+      #
+      # Supports two modes:
+      # - Static: `knows :name` loads from a file resolved via `knowledge_path`
+      # - Dynamic: `knows(:name) { ... }` evaluates a block at call time via instance_exec
+      #
+      # Optional `if:` condition gates inclusion without forcing static content into blocks.
+      #
+      # @example Static knowledge from files
+      #   class MyAgent < RubyLLM::Agents::Base
+      #     knowledge_path "knowledge"
+      #     knows :refund_policy
+      #     knows :pricing
+      #   end
+      #
+      # @example Dynamic knowledge
+      #   class MyAgent < RubyLLM::Agents::Base
+      #     knows :recent_tickets do
+      #       Ticket.recent.pluck(:summary)
+      #     end
+      #   end
+      #
+      # @example Conditional knowledge
+      #   class MyAgent < RubyLLM::Agents::Base
+      #     param :region, required: true
+      #     knows :hipaa, if: -> { region == "us" }
+      #   end
+      #
+      module Knowledge
+        # Registers one or more knowledge entries.
+        #
+        # @overload knows(name, **options, &block)
+        #   Register a single entry (static or dynamic)
+        #   @param name [Symbol] Identifier for this knowledge entry
+        #   @param options [Hash] Options including `if:` condition lambda
+        #   @param block [Proc] Optional block for dynamic knowledge (evaluated via instance_exec)
+        #
+        # @overload knows(name, *more_names)
+        #   Register multiple static entries at once
+        #   @param name [Symbol] First entry name
+        #   @param more_names [Array<Symbol>] Additional entry names
+        def knows(name, *more_names, **options, &block)
+          if more_names.any?
+            # Multi-arg form: knows :a, :b, :c — all static, no block/options
+            [name, *more_names].each do |n|
+              knowledge_entries.reject! { |e| e[:name] == n }
+              knowledge_entries << {name: n, loader: nil, options: {}}
+            end
+          else
+            knowledge_entries.reject! { |e| e[:name] == name }
+            knowledge_entries << {
+              name: name,
+              loader: block,
+              options: options
+            }
+          end
+        end
+
+        # Sets or returns the base path for static knowledge files.
+        #
+        # @param path [String, nil] Path to set, or nil to read
+        # @return [String, nil] The resolved knowledge path
+        def knowledge_path(path = nil)
+          if path
+            @knowledge_path = path
+          else
+            @knowledge_path ||
+              inherited_or_default(:knowledge_path, nil) ||
+              RubyLLM::Agents.configuration.knowledge_path
+          end
+        end
+
+        # Returns the list of registered knowledge entries, inheriting from superclass.
+        #
+        # @return [Array<Hash>] Knowledge entries
+        def knowledge_entries
+          @knowledge_entries ||= if superclass.respond_to?(:knowledge_entries)
+            superclass.knowledge_entries.dup
+          else
+            []
+          end
+        end
+
+        # Instance methods mixed into agent instances via include.
+        module InstanceMethods
+          # Compiles all knowledge entries into a single string with headings and separators.
+          #
+          # @return [String] Compiled knowledge (empty string if no entries resolve)
+          def compiled_knowledge
+            self.class.knowledge_entries.filter_map { |entry|
+              content = resolve_knowledge(entry)
+              next if content.blank?
+
+              heading = entry[:name].to_s.tr("_", " ").gsub(/\b\w/, &:upcase)
+              "## #{heading}\n\n#{content}"
+            }.join("\n\n---\n\n")
+          end
+
+          private
+
+          def resolve_knowledge(entry)
+            if (condition = entry[:options][:if])
+              return nil unless instance_exec(&condition)
+            end
+
+            if entry[:loader]
+              resolve_dynamic_knowledge(entry)
+            else
+              resolve_static_knowledge(entry)
+            end
+          end
+
+          def resolve_dynamic_knowledge(entry)
+            result = instance_exec(&entry[:loader])
+            case result
+            when Array
+              result.map { |r| "- #{r}" }.join("\n")
+            when String
+              result
+            when nil
+              nil
+            else
+              result.to_s
+            end
+          end
+
+          def resolve_static_knowledge(entry)
+            path = find_knowledge_file(entry[:name])
+            return nil unless path && File.exist?(path)
+            File.read(path)
+          end
+
+          def find_knowledge_file(name)
+            base_path = self.class.knowledge_path
+            return nil unless base_path
+
+            candidates = [
+              File.join(base_path, "#{name}.md"),
+              File.join(base_path, name.to_s)
+            ]
+
+            if defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+              candidates.map! { |c| Rails.root.join(c).to_s }
+            end
+
+            candidates.find { |c| File.exist?(c) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/dsl.rb

@@ -4,7 +4,7 @@ require_relative "dsl/base"
 require_relative "dsl/reliability"
 require_relative "dsl/caching"
 require_relative "dsl/queryable"
-require_relative "dsl/agents"
+require_relative "dsl/knowledge"
 
 module RubyLLM
   module Agents

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

@@ -33,15 +33,18 @@ module RubyLLM
             return @app.call(context) unless budgets_enabled?
 
             trace(context) do
+              # Resolve tenant once for both check and record
+              tenant = resolve_tenant(context)
+
               # Check budget before execution
-              check_budget!(context)
+              check_budget!(context, tenant)
 
               # Execute the chain
               @app.call(context)
 
               # Record spend after successful execution (if not cached)
               if context.success? && !context.cached?
-                record_spend!(context)
+                record_spend!(context, tenant)
                 emit_budget_notification("ruby_llm_agents.budget.record", context,
                   total_cost: context.total_cost,
                   total_tokens: context.total_tokens)
@@ -80,22 +83,33 @@ module RubyLLM
             false
           end
 
+          # Resolves the tenant record once for reuse across check and record
+          #
+          # @param context [Context] The execution context
+          # @return [Tenant, nil] The tenant record or nil
+          def resolve_tenant(context)
+            return nil unless context.tenant_id.present?
+
+            RubyLLM::Agents::Tenant.find_by(tenant_id: context.tenant_id)
+          rescue => e
+            debug("Tenant lookup failed: #{e.message}", context)
+            nil
+          end
+
           # Checks budget before execution
           #
           # For tenants, checks budget via counter columns on the tenant model.
           # For non-tenant usage, falls back to BudgetTracker (cache-based).
           #
           # @param context [Context] The execution context
+          # @param tenant [Tenant, nil] Pre-resolved tenant record
           # @raise [BudgetExceededError] If budget exceeded with hard enforcement
-          def check_budget!(context)
+          def check_budget!(context, tenant = nil)
             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
-                tenant.check_budget!(context.agent_class&.name)
-                return
-              end
+            if tenant
+              tenant.check_budget!(context.agent_class&.name)
+              return
             end
 
             # Fallback to cache-based checking (non-tenant or no tenant record)
@@ -117,17 +131,15 @@ module RubyLLM
           # For non-tenant usage, falls back to BudgetTracker (cache-based).
           #
           # @param context [Context] The execution context
-          def record_spend!(context)
-            if context.tenant_id.present?
-              tenant = RubyLLM::Agents::Tenant.find_by(tenant_id: context.tenant_id)
-              if tenant
-                tenant.record_execution!(
-                  cost: context.total_cost || 0,
-                  tokens: context.total_tokens || 0,
-                  error: context.failed?
-                )
-                return
-              end
+          # @param tenant [Tenant, nil] Pre-resolved tenant record
+          def record_spend!(context, tenant = nil)
+            if tenant
+              tenant.record_execution!(
+                cost: context.total_cost || 0,
+                tokens: context.total_tokens || 0,
+                error: context.failed?
+              )
+              return
             end
 
             # Fallback for non-tenant usage

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

@@ -278,6 +278,7 @@ module RubyLLM
             data = {
               agent_type: context.agent_class&.name,
               model_id: context.model,
+              model_provider: resolve_model_provider(context.model),
               status: "running",
               started_at: context.started_at,
               input_tokens: 0,
@@ -339,7 +340,9 @@ module RubyLLM
               input_tokens: context.input_tokens || 0,
               output_tokens: context.output_tokens || 0,
               total_cost: context.total_cost || 0,
-              attempts_count: context.attempts_made
+              attempts_count: context.attempts_made,
+              chosen_model_id: context.model_used,
+              finish_reason: context.finish_reason
             }
 
             # Merge metadata: agent metadata (base) < middleware metadata (overlay)
@@ -536,6 +539,24 @@ module RubyLLM
             {}
           end
 
+          # Resolves the provider name for a given model ID
+          #
+          # Uses RubyLLM::Models.find which is an in-process registry lookup
+          # (no API keys or network calls needed).
+          #
+          # @param model_id [String, nil] The model identifier
+          # @return [String, nil] Provider name (e.g., "openai", "anthropic") or nil
+          def resolve_model_provider(model_id)
+            return nil unless model_id
+            return nil unless defined?(RubyLLM::Models)
+
+            model_info = RubyLLM::Models.find(model_id)
+            provider = model_info&.provider
+            provider&.to_s.presence
+          rescue
+            nil
+          end
+
           # Injects tracker request_id and tags into execution data
           #
           # Reads @_track_request_id and @_track_tags from the agent instance,

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

@@ -223,7 +223,7 @@ module RubyLLM
             return unless deadline && Time.current > deadline
 
             elapsed = Time.current - started_at
-            timeout_value = deadline - started_at + elapsed
+            timeout_value = deadline - started_at
             raise Agents::Reliability::TotalTimeoutError.new(timeout_value, elapsed)
           end
 

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"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm-agents
 version: !ruby/object:Gem::Version
-  version: 3.11.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
@@ -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

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