ruby_llm-agents 3.11.0 → 3.13.0

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,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/image/concerns/image_operation_execution.rb

@@ -95,12 +95,13 @@ module RubyLLM
         def record_failed_execution(error, started_at)
           return unless defined?(RubyLLM::Agents::Execution)
 
-          execution_data = build_failed_execution_data(error, started_at)
+          execution_data, detail_data = build_failed_execution_data(error, started_at)
 
           if config.async_logging && defined?(ExecutionLoggerJob)
-            ExecutionLoggerJob.perform_later(execution_data)
+            ExecutionLoggerJob.perform_later(execution_data.merge(_detail_data: detail_data))
           else
-            RubyLLM::Agents::Execution.create!(execution_data)
+            execution = RubyLLM::Agents::Execution.create!(execution_data)
+            execution.create_detail!(detail_data) if detail_data.present?
           end
         rescue => e
           Rails.logger.error("[RubyLLM::Agents] Failed to record failed #{execution_type} execution: #{e.message}") if defined?(Rails)
@@ -124,7 +125,7 @@ module RubyLLM
         end
 
         def build_failed_execution_data(error, started_at)
-          {
+          execution_data = {
             agent_type: self.class.name,
             tenant_id: @tenant_id,
             execution_type: execution_type,
@@ -137,9 +138,12 @@ module RubyLLM
             started_at: started_at,
             completed_at: Time.current,
             error_class: error.class.name,
-            error_message: error.message.truncate(1000),
             metadata: {}
           }
+
+          detail_data = {error_message: error.message.to_s.truncate(1000)}
+
+          [execution_data, detail_data]
         end
 
         def build_metadata(result)

data/lib/ruby_llm/agents/infrastructure/retention_job.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    # Background job that enforces two-tier data retention on execution records.
+    #
+    # Soft pass: for executions older than {Configuration#soft_purge_after},
+    # destroys the associated execution_details and tool_executions rows,
+    # preserves a truncated copy of error_message in metadata, and stamps
+    # metadata["soft_purged_at"] so the dashboard can surface the state and
+    # the pass stays idempotent.
+    #
+    # Hard pass: for executions older than {Configuration#hard_purge_after},
+    # destroys the executions row itself. The foreign-key cascade removes
+    # any remaining details or tool_executions.
+    #
+    # Either tier may be set to nil in configuration to skip that pass.
+    #
+    # @example Enqueue manually
+    #   RubyLLM::Agents::RetentionJob.perform_later
+    #
+    # @example Schedule daily (whenever gem)
+    #   every 1.day, at: "3:00 am" do
+    #     runner "RubyLLM::Agents::RetentionJob.perform_later"
+    #   end
+    #
+    # @api public
+    class RetentionJob < ActiveJob::Base
+      queue_as :default
+
+      ERROR_MESSAGE_MAX_LENGTH = 500
+      BATCH_SIZE = 500
+
+      # Runs the soft and hard retention passes based on current configuration.
+      #
+      # @return [Hash] counts of rows affected in each pass
+      def perform
+        {
+          soft_purged: soft_purge,
+          hard_purged: hard_purge
+        }
+      end
+
+      private
+
+      # Destroys detail + tool_execution rows for executions older than the
+      # soft-purge window that have not already been soft-purged. Stamps
+      # metadata with the purge timestamp and preserves a truncated
+      # error_message for long-term error-rate analytics.
+      #
+      # The "already purged" filter runs in Ruby rather than SQL because
+      # JSON key-exists operators differ across SQLite/Postgres/MySQL; this
+      # keeps the job adapter-agnostic. We batch to bound memory.
+      def soft_purge
+        window = RubyLLM::Agents.configuration.soft_purge_after
+        return 0 if window.nil?
+
+        cutoff = window.ago
+        count = 0
+
+        Execution
+          .where("created_at < ?", cutoff)
+          .includes(:detail)
+          .find_in_batches(batch_size: BATCH_SIZE) do |batch|
+            batch.each do |execution|
+              next if execution.soft_purged?
+
+              purge_one(execution)
+              count += 1
+            end
+          end
+
+        count
+      end
+
+      # Destroys executions (and everything cascaded from them) older than
+      # the hard-purge window.
+      def hard_purge
+        window = RubyLLM::Agents.configuration.hard_purge_after
+        return 0 if window.nil?
+
+        cutoff = window.ago
+        total = 0
+
+        Execution.where("created_at < ?", cutoff).in_batches(of: BATCH_SIZE) do |batch|
+          total += batch.destroy_all.size
+        end
+
+        total
+      end
+
+      # Performs the soft purge for a single execution.
+      def purge_one(execution)
+        preserved_error = preserved_error_message(execution)
+
+        Execution.transaction do
+          execution.detail&.destroy
+          execution.tool_executions.destroy_all
+
+          new_metadata = (execution.metadata || {}).merge(
+            "soft_purged_at" => Time.current.iso8601
+          )
+          new_metadata["error_message"] = preserved_error if preserved_error
+
+          execution.update_columns(metadata: new_metadata)
+        end
+      end
+
+      # Returns a truncated copy of the detail's error_message, or nil.
+      def preserved_error_message(execution)
+        raw = execution.detail&.error_message
+        return nil if raw.blank?
+
+        raw.to_s.truncate(ERROR_MESSAGE_MAX_LENGTH)
+      end
+    end
+  end
+end

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/rails/engine.rb

@@ -33,6 +33,7 @@ module RubyLLM
       # @api private
       config.to_prepare do
         require_relative "../infrastructure/execution_logger_job"
+        require_relative "../infrastructure/retention_job"
         require_relative "../core/instrumentation"
         require_relative "../core/base"
 
@@ -153,18 +154,33 @@ module RubyLLM
           end
           helper_method :tenant_scoped_executions
 
-          # Returns list of available tenants for filtering dropdown
+          # Returns the list of tenants for the dropdown as label/value pairs.
           #
-          # @return [Array<String>] Unique tenant IDs from executions
+          # Tenants that have a matching row in ruby_llm_agents_tenants get their
+          # configured name; legacy or string-only tenants fall back to the raw
+          # tenant_id so nothing disappears from the filter.
+          #
+          # Two queries total — one DISTINCT pluck on executions, one pluck on
+          # tenants — regardless of how many tenant_ids exist.
+          #
+          # @return [Array<Hash>] Entries shaped as { value:, label: }
           # @api public
           def available_tenants
             return @available_tenants if defined?(@available_tenants)
 
-            @available_tenants = RubyLLM::Agents::Execution
+            tenant_ids = RubyLLM::Agents::Execution
               .where.not(tenant_id: nil)
               .distinct
               .pluck(:tenant_id)
-              .sort
+
+            names_by_id = RubyLLM::Agents::Tenant
+              .where(tenant_id: tenant_ids)
+              .pluck(:tenant_id, :name)
+              .to_h
+
+            @available_tenants = tenant_ids
+              .map { |id| {value: id, label: (names_by_id[id].presence || id).to_s} }
+              .sort_by { |t| t[:label].downcase }
           end
           helper_method :available_tenants
         end)