ruby_llm-agents 0.3.3 → 0.3.5

data/lib/ruby_llm/agents/cache_helper.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    # Shared cache utilities for RubyLLM::Agents
+    #
+    # Provides consistent cache key generation and store access across
+    # BudgetTracker, CircuitBreaker, and Base caching modules.
+    #
+    # @example Using in a class method context
+    #   extend CacheHelper
+    #   cache_store.read(cache_key("budget", "global", "2024-01"))
+    #
+    # @example Using in an instance method context
+    #   include CacheHelper
+    #   cache_store.write(cache_key("agent", agent_type), data, expires_in: 1.hour)
+    #
+    # @api private
+    module CacheHelper
+      # Cache key namespace prefix
+      NAMESPACE = "ruby_llm_agents"
+
+      # Returns the configured cache store
+      #
+      # @return [ActiveSupport::Cache::Store]
+      def cache_store
+        RubyLLM::Agents.configuration.cache_store
+      end
+
+      # Generates a namespaced cache key from the given parts
+      #
+      # @param parts [Array<String, Symbol>] Key components to join
+      # @return [String] Namespaced cache key
+      # @example
+      #   cache_key("budget", "global", "2024-01")
+      #   # => "ruby_llm_agents:budget:global:2024-01"
+      def cache_key(*parts)
+        ([NAMESPACE] + parts.map(&:to_s)).join(":")
+      end
+
+      # Reads a value from the cache
+      #
+      # @param key [String] The cache key
+      # @return [Object, nil] The cached value or nil
+      def cache_read(key)
+        cache_store.read(key)
+      end
+
+      # Writes a value to the cache
+      #
+      # @param key [String] The cache key
+      # @param value [Object] The value to cache
+      # @param options [Hash] Options passed to cache store (e.g., expires_in:)
+      # @return [Boolean] Whether the write succeeded
+      def cache_write(key, value, **options)
+        cache_store.write(key, value, **options)
+      end
+
+      # Checks if a key exists in the cache
+      #
+      # @param key [String] The cache key
+      # @return [Boolean] True if the key exists
+      def cache_exist?(key)
+        cache_store.exist?(key)
+      end
+
+      # Deletes a key from the cache
+      #
+      # @param key [String] The cache key
+      # @return [Boolean] Whether the delete succeeded
+      def cache_delete(key)
+        cache_store.delete(key)
+      end
+
+      # Increments a numeric value in the cache
+      #
+      # Falls back to read-modify-write if the cache store doesn't support increment.
+      #
+      # @param key [String] The cache key
+      # @param amount [Numeric] The amount to increment by (default: 1)
+      # @param expires_in [ActiveSupport::Duration, nil] Optional TTL for the key
+      # @return [Numeric] The new value
+      def cache_increment(key, amount = 1, expires_in: nil)
+        if cache_store.respond_to?(:increment)
+          # Ensure key exists with TTL
+          cache_store.write(key, 0, expires_in: expires_in, unless_exist: true) if expires_in
+          cache_store.increment(key, amount)
+        else
+          # Fallback for cache stores without atomic increment
+          current = (cache_store.read(key) || 0).to_f
+          new_value = current + amount
+          cache_store.write(key, new_value, expires_in: expires_in)
+          new_value
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/circuit_breaker.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "cache_helper"
+
 module RubyLLM
   module Agents
     # Cache-based circuit breaker for protecting against cascading failures
@@ -10,6 +12,9 @@ module RubyLLM
     # - Stays open for a cooldown period
     # - Automatically closes after cooldown expires
     #
+    # In multi-tenant mode, circuit breakers are isolated per tenant,
+    # so one tenant's failures don't affect other tenants.
+    #
     # @example Basic usage
     #   breaker = CircuitBreaker.new("MyAgent", "gpt-4o", errors: 10, within: 60, cooldown: 300)
     #   breaker.open?         # => false
@@ -17,19 +22,26 @@ module RubyLLM
     #   # ... after 10 failures within 60 seconds ...
     #   breaker.open?         # => true
     #
+    # @example Multi-tenant usage
+    #   breaker = CircuitBreaker.new("MyAgent", "gpt-4o", tenant_id: "acme", errors: 10)
+    #   breaker.open?  # Isolated to "acme" tenant
+    #
     # @see RubyLLM::Agents::Reliability
     # @api public
     class CircuitBreaker
-      attr_reader :agent_type, :model_id, :errors_threshold, :window_seconds, :cooldown_seconds
+      include CacheHelper
+      attr_reader :agent_type, :model_id, :tenant_id, :errors_threshold, :window_seconds, :cooldown_seconds
 
       # @param agent_type [String] The agent class name
       # @param model_id [String] The model identifier
+      # @param tenant_id [String, nil] Optional tenant identifier for multi-tenant isolation
       # @param errors [Integer] Number of errors to trigger open state (default: 10)
       # @param within [Integer] Rolling window in seconds (default: 60)
       # @param cooldown [Integer] Cooldown period in seconds when open (default: 300)
-      def initialize(agent_type, model_id, errors: 10, within: 60, cooldown: 300)
+      def initialize(agent_type, model_id, tenant_id: nil, errors: 10, within: 60, cooldown: 300)
         @agent_type = agent_type
         @model_id = model_id
+        @tenant_id = resolve_tenant_id(tenant_id)
         @errors_threshold = errors
         @window_seconds = within
         @cooldown_seconds = cooldown
@@ -40,13 +52,15 @@ module RubyLLM
       # @param agent_type [String] The agent class name
       # @param model_id [String] The model identifier
       # @param config [Hash] Configuration with :errors, :within, :cooldown keys
+      # @param tenant_id [String, nil] Optional tenant identifier
       # @return [CircuitBreaker] A new circuit breaker instance
-      def self.from_config(agent_type, model_id, config)
+      def self.from_config(agent_type, model_id, config, tenant_id: nil)
         return nil unless config.is_a?(Hash)
 
         new(
           agent_type,
           model_id,
+          tenant_id: tenant_id,
           errors: config[:errors] || 10,
           within: config[:within] || 60,
           cooldown: config[:cooldown] || 300
@@ -57,7 +71,7 @@ module RubyLLM
       #
       # @return [Boolean] true if the breaker is open and requests should be blocked
       def open?
-        cache_store.exist?(open_key)
+        cache_exist?(open_key)
       end
 
       # Records a failed attempt and potentially opens the breaker
@@ -86,7 +100,7 @@ module RubyLLM
       # @param reset_counter [Boolean] Whether to reset the failure counter (default: true)
       # @return [void]
       def record_success!(reset_counter: true)
-        cache_store.delete(count_key) if reset_counter
+        cache_delete(count_key) if reset_counter
       end
 
       # Manually resets the circuit breaker
@@ -95,15 +109,15 @@ module RubyLLM
       #
       # @return [void]
       def reset!
-        cache_store.delete(open_key)
-        cache_store.delete(count_key)
+        cache_delete(open_key)
+        cache_delete(count_key)
       end
 
       # Returns the current failure count
       #
       # @return [Integer] The current failure count in the rolling window
       def failure_count
-        cache_store.read(count_key).to_i
+        cache_read(count_key).to_i
       end
 
       # Returns the time remaining until the breaker closes
@@ -124,6 +138,7 @@ module RubyLLM
         {
           agent_type: agent_type,
           model_id: model_id,
+          tenant_id: tenant_id,
           open: open?,
           failure_count: failure_count,
           errors_threshold: errors_threshold,
@@ -134,29 +149,30 @@ module RubyLLM
 
       private
 
+      # Resolves the current tenant ID
+      #
+      # @param explicit_tenant_id [String, nil] Explicitly passed tenant ID
+      # @return [String, nil] Resolved tenant ID or nil
+      def resolve_tenant_id(explicit_tenant_id)
+        config = RubyLLM::Agents.configuration
+        return nil unless config.multi_tenancy_enabled?
+        return explicit_tenant_id if explicit_tenant_id.present?
+
+        config.tenant_resolver&.call
+      end
+
       # Increments the failure counter with TTL
       #
       # @return [Integer] The new failure count
       def increment_failure_count
-        # Use increment if available (atomic), otherwise read-modify-write
-        if cache_store.respond_to?(:increment)
-          # First write if doesn't exist
-          cache_store.write(count_key, 0, expires_in: window_seconds, unless_exist: true)
-          cache_store.increment(count_key)
-        else
-          # Fallback for cache stores without increment
-          current = cache_store.read(count_key).to_i
-          new_count = current + 1
-          cache_store.write(count_key, new_count, expires_in: window_seconds)
-          new_count
-        end
+        cache_increment(count_key, 1, expires_in: window_seconds)
       end
 
       # Opens the circuit breaker
       #
       # @return [void]
       def open_breaker!
-        cache_store.write(open_key, Time.current.to_s, expires_in: cooldown_seconds)
+        cache_write(open_key, Time.current.to_s, expires_in: cooldown_seconds)
 
         # Fire alert if configured
         if RubyLLM::Agents.configuration.alerts_enabled? &&
@@ -164,6 +180,7 @@ module RubyLLM
           AlertManager.notify(:breaker_open, {
             agent_type: agent_type,
             model_id: model_id,
+            tenant_id: tenant_id,
             errors: errors_threshold,
             within: window_seconds,
             cooldown: cooldown_seconds,
@@ -176,21 +193,22 @@ module RubyLLM
       #
       # @return [String] Cache key
       def count_key
-        "ruby_llm_agents:cb:count:#{agent_type}:#{model_id}"
+        if tenant_id.present?
+          cache_key("cb", "tenant", tenant_id, "count", agent_type, model_id)
+        else
+          cache_key("cb", "count", agent_type, model_id)
+        end
       end
 
       # Returns the cache key for the open flag
       #
       # @return [String] Cache key
       def open_key
-        "ruby_llm_agents:cb:open:#{agent_type}:#{model_id}"
-      end
-
-      # Returns the cache store
-      #
-      # @return [ActiveSupport::Cache::Store] The cache store
-      def cache_store
-        RubyLLM::Agents.configuration.cache_store
+        if tenant_id.present?
+          cache_key("cb", "tenant", tenant_id, "open", agent_type, model_id)
+        else
+          cache_key("cb", "open", agent_type, model_id)
+        end
       end
     end
   end

data/lib/ruby_llm/agents/configuration.rb

@@ -178,6 +178,23 @@ module RubyLLM
       #       max_value_length: 5000
       #     }
 
+      # @!attribute [rw] multi_tenancy_enabled
+      #   Whether multi-tenancy features are enabled.
+      #   When false, the gem behaves exactly as before (backward compatible).
+      #   @return [Boolean] Enable multi-tenancy (default: false)
+      #   @example
+      #     config.multi_tenancy_enabled = true
+
+      # @!attribute [rw] tenant_resolver
+      #   Lambda that returns the current tenant identifier.
+      #   Called whenever tenant context is needed for budget tracking,
+      #   circuit breakers, and execution recording.
+      #   @return [Proc] Tenant resolution lambda (default: -> { nil })
+      #   @example Using Rails CurrentAttributes
+      #     config.tenant_resolver = -> { Current.tenant&.id }
+      #   @example Using request store
+      #     config.tenant_resolver = -> { RequestStore[:tenant_id] }
+
       attr_accessor :default_model,
                     :default_temperature,
                     :default_timeout,
@@ -201,7 +218,9 @@ module RubyLLM
                     :alerts,
                     :persist_prompts,
                     :persist_responses,
-                    :redaction
+                    :redaction,
+                    :multi_tenancy_enabled,
+                    :tenant_resolver
 
       attr_writer :cache_store
 
@@ -241,6 +260,10 @@ module RubyLLM
         @persist_prompts = true
         @persist_responses = true
         @redaction = nil
+
+        # Multi-tenancy defaults (disabled for backward compatibility)
+        @multi_tenancy_enabled = false
+        @tenant_resolver = -> { nil }
       end
 
       # Returns the configured cache store, falling back to Rails.cache
@@ -313,6 +336,22 @@ module RubyLLM
       def redaction_max_value_length
         redaction&.dig(:max_value_length)
       end
+
+      # Returns whether multi-tenancy is enabled
+      #
+      # @return [Boolean] true if multi-tenancy is enabled
+      def multi_tenancy_enabled?
+        @multi_tenancy_enabled == true
+      end
+
+      # Returns the current tenant ID from the resolver
+      #
+      # @return [String, nil] Current tenant identifier or nil
+      def current_tenant_id
+        return nil unless multi_tenancy_enabled?
+
+        tenant_resolver&.call
+      end
     end
   end
 end

data/lib/ruby_llm/agents/engine.rb

@@ -35,6 +35,7 @@ module RubyLLM
         require_relative "execution_logger_job"
         require_relative "instrumentation"
         require_relative "base"
+        require_relative "workflow"
 
         # Resolve the parent controller class from configuration
         # Default is ActionController::Base, but can be set to inherit from app controllers
@@ -46,7 +47,10 @@ module RubyLLM
 
         # Define the ApplicationController dynamically with the configured parent
         RubyLLM::Agents.const_set(:ApplicationController, Class.new(parent_class) do
-          layout "rubyllm/agents/application"
+          # Prepend the engine's view path so templates are found correctly
+          prepend_view_path RubyLLM::Agents::Engine.root.join("app/views")
+
+          layout "ruby_llm/agents/application"
           helper RubyLLM::Agents::ApplicationHelper
           before_action :authenticate_dashboard!
 
@@ -93,6 +97,66 @@ module RubyLLM
                 ActiveSupport::SecurityUtils.secure_compare(password, config.basic_auth_password)
             end
           end
+
+          # Returns whether multi-tenancy filtering is enabled
+          #
+          # @return [Boolean] true if multi-tenancy is enabled
+          # @api public
+          def tenant_filter_enabled?
+            RubyLLM::Agents.configuration.multi_tenancy_enabled?
+          end
+          helper_method :tenant_filter_enabled?
+
+          # Returns the current tenant ID for filtering
+          #
+          # Priority:
+          # 1. Explicit tenant_id param (for admin filtering)
+          # 2. Resolved from tenant_resolver
+          #
+          # @return [String, nil] Current tenant identifier
+          # @api public
+          def current_tenant_id
+            return @current_tenant_id if defined?(@current_tenant_id)
+
+            @current_tenant_id = if params[:tenant_id].present?
+              params[:tenant_id]
+            else
+              RubyLLM::Agents.configuration.current_tenant_id
+            end
+          end
+          helper_method :current_tenant_id
+
+          # Returns a tenant-scoped base query for executions
+          #
+          # If multi-tenancy is enabled and a tenant is selected,
+          # returns executions filtered by that tenant.
+          # Otherwise returns all executions.
+          #
+          # @return [ActiveRecord::Relation] Scoped executions
+          # @api public
+          def tenant_scoped_executions
+            if tenant_filter_enabled? && current_tenant_id.present?
+              RubyLLM::Agents::Execution.by_tenant(current_tenant_id)
+            else
+              RubyLLM::Agents::Execution.all
+            end
+          end
+          helper_method :tenant_scoped_executions
+
+          # Returns list of available tenants for filtering dropdown
+          #
+          # @return [Array<String>] Unique tenant IDs from executions
+          # @api public
+          def available_tenants
+            return @available_tenants if defined?(@available_tenants)
+
+            @available_tenants = RubyLLM::Agents::Execution
+              .where.not(tenant_id: nil)
+              .distinct
+              .pluck(:tenant_id)
+              .sort
+          end
+          helper_method :available_tenants
         end)
       end
 

data/lib/ruby_llm/agents/inflections.rb

@@ -12,10 +12,24 @@
 # @api private
 
 # Register "LLM" as an acronym for ActiveSupport inflector
+# and add custom underscore rule for RubyLLM -> ruby_llm
 ActiveSupport::Inflector.inflections(:en) do |inflect|
   inflect.acronym "LLM"
+  # Ensure RubyLLM underscores correctly to ruby_llm (not rubyllm)
+  inflect.uncountable "ruby_llm"
 end
 
+# Override underscore behavior for RubyLLM specifically
+# This ensures view paths resolve correctly (ruby_llm/agents/... not rubyllm/agents/...)
+module RubyLLMInflectionFix
+  def underscore
+    result = super
+    result.gsub("rubyllm", "ruby_llm")
+  end
+end
+
+String.prepend(RubyLLMInflectionFix)
+
 # Configure Zeitwerk to map directory names correctly
 ActiveSupport.on_load(:before_configuration) do
   Rails.autoloaders.each do |autoloader|

data/lib/ruby_llm/agents/instrumentation.rb

@@ -262,6 +262,11 @@ module RubyLLM
           execution_data[:attempts_count] = 0
         end
 
+        # Add tenant_id if multi-tenancy is enabled
+        if config.multi_tenancy_enabled?
+          execution_data[:tenant_id] = config.current_tenant_id
+        end
+
         RubyLLM::Agents::Execution.create!(execution_data)
       rescue StandardError => e
         # Log error but don't fail the agent execution itself
@@ -732,6 +737,67 @@ module RubyLLM
         end
       end
 
+      # Records an execution for a cache hit
+      #
+      # Creates a minimal execution record with cache_hit: true, 0 tokens,
+      # and 0 cost. This allows tracking cache hits in the dashboard.
+      #
+      # @param cache_key [String] The cache key that was hit
+      # @param cached_result [Object] The cached result returned
+      # @param started_at [Time] When the cache lookup started
+      # @return [void]
+      def record_cache_hit_execution(cache_key, cached_result, started_at)
+        config = RubyLLM::Agents.configuration
+        completed_at = Time.current
+        duration_ms = ((completed_at - started_at) * 1000).round
+
+        execution_data = {
+          agent_type: self.class.name,
+          agent_version: self.class.version,
+          model_id: model,
+          temperature: temperature,
+          status: "success",
+          cache_hit: true,
+          response_cache_key: cache_key,
+          cached_at: completed_at,
+          started_at: started_at,
+          completed_at: completed_at,
+          duration_ms: duration_ms,
+          input_tokens: 0,
+          output_tokens: 0,
+          cached_tokens: 0,
+          cache_creation_tokens: 0,
+          total_tokens: 0,
+          input_cost: 0,
+          output_cost: 0,
+          total_cost: 0,
+          parameters: redacted_parameters,
+          metadata: execution_metadata,
+          streaming: self.class.streaming
+        }
+
+        # Add tracing fields from metadata if present
+        metadata = execution_metadata
+        execution_data[:request_id] = metadata[:request_id] if metadata[:request_id]
+        execution_data[:trace_id] = metadata[:trace_id] if metadata[:trace_id]
+        execution_data[:span_id] = metadata[:span_id] if metadata[:span_id]
+        execution_data[:parent_execution_id] = metadata[:parent_execution_id] if metadata[:parent_execution_id]
+        execution_data[:root_execution_id] = metadata[:root_execution_id] if metadata[:root_execution_id]
+
+        # Add tenant_id if multi-tenancy is enabled
+        if config.multi_tenancy_enabled?
+          execution_data[:tenant_id] = config.current_tenant_id
+        end
+
+        if config.async_logging
+          RubyLLM::Agents::ExecutionLoggerJob.perform_later(execution_data)
+        else
+          RubyLLM::Agents::Execution.create!(execution_data)
+        end
+      rescue StandardError => e
+        Rails.logger.error("[RubyLLM::Agents] Failed to record cache hit execution: #{e.message}")
+      end
+
       # Emergency fallback to mark execution as failed
       #
       # Uses update_all to bypass ActiveRecord callbacks and validations,

data/lib/ruby_llm/agents/reliability.rb

@@ -42,21 +42,27 @@ module RubyLLM
       # @example
       #   raise BudgetExceededError.new(:global_daily, 25.0, 27.5)
       #
+      # @example With tenant
+      #   raise BudgetExceededError.new(:global_daily, 25.0, 27.5, tenant_id: "acme")
+      #
       # @api public
       class BudgetExceededError < Error
-        attr_reader :scope, :limit, :current
+        attr_reader :scope, :limit, :current, :agent_type, :tenant_id
 
         # @param scope [Symbol] The budget scope (:global_daily, :global_monthly, :per_agent_daily, etc.)
         # @param limit [Float] The budget limit in USD
         # @param current [Float] The current spend in USD
         # @param agent_type [String, nil] The agent type for per-agent budgets
-        def initialize(scope, limit, current, agent_type: nil)
+        # @param tenant_id [String, nil] The tenant identifier for multi-tenant budgets
+        def initialize(scope, limit, current, agent_type: nil, tenant_id: nil)
           @scope = scope
           @limit = limit
           @current = current
           @agent_type = agent_type
+          @tenant_id = tenant_id
 
           message = "Budget exceeded for #{scope}"
+          message += " (tenant: #{tenant_id})" if tenant_id
           message += " (#{agent_type})" if agent_type
           message += ": limit $#{limit}, current $#{current}"
           super(message)

data/lib/ruby_llm/agents/version.rb

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