ruby_llm-agents 3.10.0 → 3.12.0

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

@@ -72,8 +72,13 @@ module RubyLLM
       # @param context [Pipeline::Context] The execution context
       # @return [void] Sets context.output with the result
       def execute(context)
+        @context = context
         @execution_started_at = context.started_at || Time.current
 
+        # Make context available to Tool instances during tool execution
+        previous_context = Thread.current[:ruby_llm_agents_caller_context]
+        Thread.current[:ruby_llm_agents_caller_context] = context
+
         # Run before_call callbacks
         run_callbacks(:before, context)
 
@@ -87,10 +92,14 @@ module RubyLLM
         run_callbacks(:after, context, response)
 
         context.output = build_result(processed_content, response, context)
+      rescue RubyLLM::Agents::CancelledError
+        context.output = Result.new(content: nil, cancelled: true)
       rescue RubyLLM::UnauthorizedError, RubyLLM::ForbiddenError => e
         raise_with_setup_hint(e, context)
       rescue RubyLLM::ModelNotFoundError => e
         raise_with_model_hint(e, context)
+      ensure
+        Thread.current[:ruby_llm_agents_caller_context] = previous_context
       end
 
       # Returns the resolved tenant ID for tracking

data/lib/ruby_llm/agents/core/configuration.rb

@@ -448,7 +448,8 @@ module RubyLLM
         :helicone_pricing_enabled,
         :helicone_pricing_url,
         :llmpricing_enabled,
-        :llmpricing_url
+        :llmpricing_url,
+        :knowledge_path
 
       # Attributes with validation (readers only, custom setters below)
       attr_reader :default_temperature,
@@ -752,6 +753,9 @@ module RubyLLM
         @elevenlabs_base_cost_per_1k = nil
         # ElevenLabs models cache TTL in seconds (6 hours)
         @elevenlabs_models_cache_ttl = 21_600
+
+        # Knowledge defaults
+        @knowledge_path = "app/agents/knowledge"
       end
 
       # Returns the configured cache store, falling back to Rails.cache

data/lib/ruby_llm/agents/core/version.rb

@@ -4,6 +4,6 @@ module RubyLLM
   module Agents
     # Current version of the RubyLLM::Agents gem
     # @return [String] Semantic version string
-    VERSION = "3.10.0"
+    VERSION = "3.12.0"
   end
 end

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

@@ -43,6 +43,13 @@ module RubyLLM
       #
       #   RubyExpert.ask("What is metaprogramming?")
       #
+      # @example Dashboard-overridable settings
+      #   class SupportAgent < RubyLLM::Agents::BaseAgent
+      #     model "gpt-4o", overridable: true        # can be changed from the dashboard
+      #     temperature 0.7, overridable: true        # can be changed from the dashboard
+      #     timeout 30                                # locked to code value
+      #   end
+      #
       # @example Dynamic prompts with method overrides
       #   class SmartAgent < RubyLLM::Agents::BaseAgent
       #     def system_prompt
@@ -63,12 +70,18 @@ module RubyLLM
         # Sets or returns the LLM model for this agent class
         #
         # @param value [String, nil] The model identifier to set
+        # @param overridable [Boolean, nil] When true, this field can be changed from the dashboard
         # @return [String] The current model setting
         # @example
         #   model "gpt-4o"
-        def model(value = nil)
+        # @example Dashboard-overridable
+        #   model "gpt-4o", overridable: true
+        def model(value = nil, overridable: nil)
           @model = value if value
-          @model || inherited_or_default(:model, default_model)
+          register_overridable(:model) if overridable
+          base = @model || inherited_or_default(:model, default_model)
+
+          apply_override(:model, base)
         end
 
         # Sets the user prompt template
@@ -206,12 +219,45 @@ module RubyLLM
         # Sets or returns the timeout in seconds for LLM requests
         #
         # @param value [Integer, nil] Timeout in seconds
+        # @param overridable [Boolean, nil] When true, this field can be changed from the dashboard
         # @return [Integer] The current timeout setting
         # @example
         #   timeout 30
-        def timeout(value = nil)
+        # @example Dashboard-overridable
+        #   timeout 30, overridable: true
+        def timeout(value = nil, overridable: nil)
           @timeout = value if value
-          @timeout || inherited_or_default(:timeout, default_timeout)
+          register_overridable(:timeout) if overridable
+          base = @timeout || inherited_or_default(:timeout, default_timeout)
+
+          apply_override(:timeout, base)
+        end
+
+        # Enables Anthropic prompt caching for this agent
+        #
+        # When enabled, adds cache_control breakpoints to the system prompt
+        # and the last tool definition so Anthropic caches them across
+        # multi-turn agent loops. This reduces input token costs by ~90%
+        # on subsequent calls within the same cache window (~5 minutes).
+        #
+        # Only takes effect when the resolved model is served by Anthropic.
+        # Non-Anthropic models silently ignore this setting.
+        #
+        # @param value [Boolean, nil] Whether to enable prompt caching
+        # @return [Boolean] The current setting
+        #
+        # @example
+        #   class BuildAgent < ApplicationAgent
+        #     cache_prompts true
+        #     system "You are a build assistant."
+        #     tools BuildTool, TestTool, DeployTool
+        #   end
+        #
+        def cache_prompts(value = nil)
+          @cache_prompts = value unless value.nil?
+          return @cache_prompts if defined?(@cache_prompts) && !@cache_prompts.nil?
+
+          inherited_or_default(:cache_prompts, false)
         end
 
         # Sets or returns the response schema for structured output
@@ -259,6 +305,47 @@ module RubyLLM
 
         # @!endgroup
 
+        # @!group Dashboard Override Support
+
+        # Returns which fields are overridable for this agent
+        #
+        # @return [Array<Symbol>] The list of overridable field names
+        def overridable_fields
+          own = @overridable_fields || []
+          inherited = superclass.respond_to?(:overridable_fields) ? superclass.overridable_fields : []
+          (own + inherited).uniq
+        end
+
+        # Returns true if any field is overridable from the dashboard
+        #
+        # @return [Boolean]
+        def overridable?
+          overridable_fields.any?
+        end
+
+        # Returns the currently active dashboard overrides for this agent
+        #
+        # Only returns overrides for fields that are declared overridable.
+        #
+        # @return [Hash{String => Object}] Active override values
+        def active_overrides
+          return {} unless overridable?
+
+          raw = load_overrides
+          raw.select { |field, _| overridable_fields.include?(field.to_sym) }
+        end
+
+        # Clears the in-memory override cache so the next access reloads from DB
+        #
+        # Called automatically by AgentOverride after_save/after_destroy callbacks.
+        #
+        # @return [void]
+        def clear_override_cache!
+          @_override_cache = nil
+        end
+
+        # @!endgroup
+
         private
 
         # Auto-registers parameters found in prompt template placeholders
@@ -310,6 +397,46 @@ module RubyLLM
         rescue
           120
         end
+
+        # Registers a field as overridable from the dashboard
+        #
+        # @param field [Symbol] The field name
+        # @return [void]
+        def register_overridable(field)
+          @overridable_fields = (@overridable_fields || []) | [field]
+        end
+
+        # Applies a dashboard override if the field is overridable and an override exists
+        #
+        # @param field [Symbol] The field name
+        # @param base [Object] The code-defined value to use as fallback
+        # @return [Object] The override value, or the base value
+        def apply_override(field, base)
+          return base unless overridable_fields.include?(field)
+
+          override = resolve_override(field)
+          override.nil? ? base : override
+        end
+
+        # Fetches the override value for a single field from the cached override hash
+        #
+        # @param field [Symbol] The field name
+        # @return [Object, nil] The override value, or nil
+        def resolve_override(field)
+          @_override_cache = load_overrides unless defined?(@_override_cache) && @_override_cache
+          @_override_cache[field.to_s]
+        end
+
+        # Loads all overrides for this agent from the database
+        #
+        # @return [Hash{String => Object}] The override settings hash
+        def load_overrides
+          return {} unless defined?(RubyLLM::Agents::AgentOverride)
+
+          RubyLLM::Agents::AgentOverride.find_by(agent_type: name)&.settings || {}
+        rescue
+          {}
+        end
       end
     end
   end

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,6 +4,7 @@ require_relative "dsl/base"
 require_relative "dsl/reliability"
 require_relative "dsl/caching"
 require_relative "dsl/queryable"
+require_relative "dsl/knowledge"
 
 module RubyLLM
   module Agents

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

@@ -50,7 +50,7 @@ module RubyLLM
         attr_accessor :trace
 
         # Streaming support
-        attr_accessor :stream_block, :skip_cache
+        attr_accessor :stream_block, :skip_cache, :stream_events
 
         # Agent metadata
         attr_reader :agent_class, :agent_type
@@ -65,7 +65,7 @@ module RubyLLM
         # @param skip_cache [Boolean] Whether to skip caching
         # @param stream_block [Proc, nil] Block for streaming
         # @param options [Hash] Additional options passed to the agent
-        def initialize(input:, agent_class:, agent_instance: nil, model: nil, tenant: nil, skip_cache: false, stream_block: nil, parent_execution_id: nil, root_execution_id: nil, **options)
+        def initialize(input:, agent_class:, agent_instance: nil, model: nil, tenant: nil, skip_cache: false, stream_block: nil, stream_events: false, parent_execution_id: nil, root_execution_id: nil, **options)
           @input = input
           @agent_class = agent_class
           @agent_instance = agent_instance
@@ -87,6 +87,7 @@ module RubyLLM
           # Execution options
           @skip_cache = skip_cache
           @stream_block = stream_block
+          @stream_events = stream_events
 
           # Debug trace
           @trace = []
@@ -132,6 +133,13 @@ module RubyLLM
           @trace << {middleware: middleware_name, started_at: started_at, duration_ms: duration_ms, action: action}.compact
         end
 
+        # Are stream events enabled?
+        #
+        # @return [Boolean]
+        def stream_events?
+          @stream_events == true
+        end
+
         # Was the result served from cache?
         #
         # @return [Boolean]
@@ -243,6 +251,7 @@ module RubyLLM
             model: @model,
             skip_cache: @skip_cache,
             stream_block: @stream_block,
+            stream_events: @stream_events,
             **opts_without_tenant
           )
           # Preserve resolved tenant state

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