ruby_llm-agents 1.0.0 → 1.2.0

data/app/models/ruby_llm/agents/tenant/budgetable.rb

@@ -0,0 +1,277 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    class Tenant
+      # Handles budget limits and enforcement for tenants.
+      #
+      # Supports three types of limits:
+      # - Cost limits (USD): daily_limit, monthly_limit
+      # - Token limits: daily_token_limit, monthly_token_limit
+      # - Execution limits: daily_execution_limit, monthly_execution_limit
+      #
+      # Enforcement modes:
+      # - :none - No enforcement, tracking only
+      # - :soft - Log warnings when limits exceeded
+      # - :hard - Block execution when limits exceeded
+      #
+      # @example Setting limits
+      #   tenant.daily_limit = 100.0
+      #   tenant.monthly_limit = 1000.0
+      #   tenant.enforcement = "hard"
+      #
+      # @example Checking budget
+      #   tenant.within_budget?                    # => true
+      #   tenant.within_budget?(type: :monthly_cost)
+      #   tenant.remaining_budget(type: :daily_tokens)
+      #
+      # @see BudgetTracker
+      # @api public
+      module Budgetable
+        extend ActiveSupport::Concern
+
+        # Valid enforcement modes
+        ENFORCEMENT_MODES = %w[none soft hard].freeze
+
+        included do
+          # Validations
+          validates :enforcement, inclusion: { in: ENFORCEMENT_MODES }, allow_nil: true
+          validates :daily_limit, :monthly_limit,
+                    numericality: { greater_than_or_equal_to: 0 }, allow_nil: true
+          validates :daily_token_limit, :monthly_token_limit,
+                    numericality: { greater_than_or_equal_to: 0, only_integer: true }, allow_nil: true
+          validates :daily_execution_limit, :monthly_execution_limit,
+                    numericality: { greater_than_or_equal_to: 0, only_integer: true }, allow_nil: true
+
+          # Scopes
+          scope :with_budgets, -> { where.not(daily_limit: nil).or(where.not(monthly_limit: nil)) }
+          scope :with_enforcement, ->(mode) { where(enforcement: mode) }
+          scope :hard_enforcement, -> { where(enforcement: "hard") }
+          scope :soft_enforcement, -> { where(enforcement: "soft") }
+          scope :no_enforcement, -> { where(enforcement: "none") }
+        end
+
+        # Effective limits (considering inheritance from global config)
+
+        # Returns the effective daily cost limit
+        #
+        # @return [Float, nil] The daily limit or nil if not set
+        def effective_daily_limit
+          return daily_limit if daily_limit.present?
+          return nil unless inherit_global_defaults
+
+          global_config&.dig(:global_daily)
+        end
+
+        # Returns the effective monthly cost limit
+        #
+        # @return [Float, nil] The monthly limit or nil if not set
+        def effective_monthly_limit
+          return monthly_limit if monthly_limit.present?
+          return nil unless inherit_global_defaults
+
+          global_config&.dig(:global_monthly)
+        end
+
+        # Returns the effective daily token limit
+        #
+        # @return [Integer, nil] The daily token limit or nil if not set
+        def effective_daily_token_limit
+          return daily_token_limit if daily_token_limit.present?
+          return nil unless inherit_global_defaults
+
+          global_config&.dig(:global_daily_tokens)
+        end
+
+        # Returns the effective monthly token limit
+        #
+        # @return [Integer, nil] The monthly token limit or nil if not set
+        def effective_monthly_token_limit
+          return monthly_token_limit if monthly_token_limit.present?
+          return nil unless inherit_global_defaults
+
+          global_config&.dig(:global_monthly_tokens)
+        end
+
+        # Returns the effective daily execution limit
+        #
+        # @return [Integer, nil] The daily execution limit or nil if not set
+        def effective_daily_execution_limit
+          return daily_execution_limit if daily_execution_limit.present?
+          return nil unless inherit_global_defaults
+
+          global_config&.dig(:global_daily_executions)
+        end
+
+        # Returns the effective monthly execution limit
+        #
+        # @return [Integer, nil] The monthly execution limit or nil if not set
+        def effective_monthly_execution_limit
+          return monthly_execution_limit if monthly_execution_limit.present?
+          return nil unless inherit_global_defaults
+
+          global_config&.dig(:global_monthly_executions)
+        end
+
+        # Returns the effective enforcement mode
+        #
+        # @return [Symbol] :none, :soft, or :hard
+        def effective_enforcement
+          return enforcement.to_sym if enforcement.present?
+          return :soft unless inherit_global_defaults
+
+          RubyLLM::Agents.configuration.budget_enforcement
+        end
+
+        # Returns the effective per-agent daily limit
+        #
+        # @param agent_type [String] The agent class name
+        # @return [Float, nil] The limit or nil if not set
+        def effective_per_agent_daily(agent_type)
+          limit = per_agent_daily&.dig(agent_type)
+          return limit if limit.present?
+          return nil unless inherit_global_defaults
+
+          global_config&.dig(:per_agent_daily, agent_type)
+        end
+
+        # Returns the effective per-agent monthly limit
+        #
+        # @param agent_type [String] The agent class name
+        # @return [Float, nil] The limit or nil if not set
+        def effective_per_agent_monthly(agent_type)
+          limit = per_agent_monthly&.dig(agent_type)
+          return limit if limit.present?
+          return nil unless inherit_global_defaults
+
+          global_config&.dig(:per_agent_monthly, agent_type)
+        end
+
+        # Budget status checks
+
+        # Checks if budget enforcement is enabled
+        #
+        # @return [Boolean] true if enforcement is :soft or :hard
+        def budgets_enabled?
+          effective_enforcement != :none
+        end
+
+        # Checks if hard enforcement is enabled
+        #
+        # @return [Boolean]
+        def hard_enforcement?
+          effective_enforcement == :hard
+        end
+
+        # Checks if soft enforcement is enabled
+        #
+        # @return [Boolean]
+        def soft_enforcement?
+          effective_enforcement == :soft
+        end
+
+        # Check if within budget for a specific type
+        #
+        # @param type [Symbol] :daily_cost, :monthly_cost, :daily_tokens,
+        #   :monthly_tokens, :daily_executions, :monthly_executions
+        # @return [Boolean]
+        def within_budget?(type: :daily_cost)
+          status = budget_status
+          return true unless status[:enabled]
+
+          key = budget_status_key(type)
+          (status.dig(key, :percentage_used) || 0) < 100
+        end
+
+        # Get remaining budget for a specific type
+        #
+        # @param type [Symbol] Budget type (see #within_budget?)
+        # @return [Numeric, nil]
+        def remaining_budget(type: :daily_cost)
+          status = budget_status
+          key = budget_status_key(type)
+          status.dig(key, :remaining)
+        end
+
+        # Check budget and raise if exceeded (for hard enforcement)
+        #
+        # @param agent_type [String] The agent class name
+        # @raise [BudgetExceededError] If hard enforcement and over budget
+        def check_budget!(agent_type = nil)
+          BudgetTracker.check_budget!(agent_type || "Unknown", tenant_id: tenant_id)
+        end
+
+        # Get full budget status from BudgetTracker
+        #
+        # @return [Hash] Budget status with usage information
+        def budget_status
+          BudgetTracker.status(tenant_id: tenant_id)
+        end
+
+        # Convert to config hash for BudgetTracker
+        #
+        # @return [Hash] Budget configuration hash
+        def to_budget_config
+          {
+            enabled: budgets_enabled?,
+            enforcement: effective_enforcement,
+            # Cost limits
+            global_daily: effective_daily_limit,
+            global_monthly: effective_monthly_limit,
+            per_agent_daily: merged_per_agent_daily,
+            per_agent_monthly: merged_per_agent_monthly,
+            # Token limits
+            global_daily_tokens: effective_daily_token_limit,
+            global_monthly_tokens: effective_monthly_token_limit,
+            # Execution limits
+            global_daily_executions: effective_daily_execution_limit,
+            global_monthly_executions: effective_monthly_execution_limit
+          }
+        end
+
+        private
+
+        # Returns the global budgets configuration
+        #
+        # @return [Hash, nil]
+        def global_config
+          RubyLLM::Agents.configuration.budgets
+        end
+
+        # Merges per-agent daily limits with global defaults
+        #
+        # @return [Hash]
+        def merged_per_agent_daily
+          return per_agent_daily || {} unless inherit_global_defaults
+
+          (global_config&.dig(:per_agent_daily) || {}).merge(per_agent_daily || {})
+        end
+
+        # Merges per-agent monthly limits with global defaults
+        #
+        # @return [Hash]
+        def merged_per_agent_monthly
+          return per_agent_monthly || {} unless inherit_global_defaults
+
+          (global_config&.dig(:per_agent_monthly) || {}).merge(per_agent_monthly || {})
+        end
+
+        # Maps budget type to status key
+        #
+        # @param type [Symbol]
+        # @return [Symbol]
+        def budget_status_key(type)
+          case type
+          when :daily_cost then :global_daily
+          when :monthly_cost then :global_monthly
+          when :daily_tokens then :global_daily_tokens
+          when :monthly_tokens then :global_monthly_tokens
+          when :daily_executions then :global_daily_executions
+          when :monthly_executions then :global_monthly_executions
+          else :global_daily
+          end
+        end
+      end
+    end
+  end
+end

data/app/models/ruby_llm/agents/tenant/configurable.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module RubyLLM
+  module Agents
+    class Tenant
+      # Manages API configuration for a tenant.
+      #
+      # Links to the ApiConfiguration model to provide per-tenant API keys
+      # and settings. Supports inheritance from global configuration when
+      # tenant-specific settings are not defined.
+      #
+      # @example Accessing tenant API keys
+      #   tenant = Tenant.for("acme_corp")
+      #   tenant.api_key_for(:openai)  # => "sk-..."
+      #   tenant.has_custom_api_keys?  # => true
+      #
+      # @example Getting effective configuration
+      #   config = tenant.effective_api_configuration
+      #   config.apply_to_ruby_llm!
+      #
+      # @see ApiConfiguration
+      # @api public
+      module Configurable
+        extend ActiveSupport::Concern
+
+        included do
+          # Link to tenant-specific API configuration
+          has_one :api_configuration,
+                  -> { where(scope_type: "tenant") },
+                  class_name: "RubyLLM::Agents::ApiConfiguration",
+                  foreign_key: :scope_id,
+                  primary_key: :tenant_id,
+                  dependent: :destroy
+        end
+
+        # Get API key for a specific provider
+        #
+        # @param provider [Symbol] Provider name (:openai, :anthropic, :gemini, etc.)
+        # @return [String, nil] The API key or nil if not configured
+        #
+        # @example
+        #   tenant.api_key_for(:openai)     # => "sk-abc123..."
+        #   tenant.api_key_for(:anthropic)  # => "sk-ant-xyz..."
+        def api_key_for(provider)
+          attr_name = "#{provider}_api_key"
+          api_configuration&.send(attr_name) if api_configuration&.respond_to?(attr_name)
+        end
+
+        # Check if tenant has custom API keys configured
+        #
+        # @return [Boolean] true if tenant has an ApiConfiguration record
+        def has_custom_api_keys?
+          api_configuration.present?
+        end
+
+        # Get effective API configuration for this tenant
+        #
+        # Returns the resolved configuration that combines tenant-specific
+        # settings with global defaults.
+        #
+        # @return [ResolvedConfig] The resolved configuration
+        #
+        # @example
+        #   config = tenant.effective_api_configuration
+        #   config.openai_api_key  # Tenant's key or global fallback
+        def effective_api_configuration
+          ApiConfiguration.resolve(tenant_id: tenant_id)
+        end
+
+        # Get or create the API configuration for this tenant
+        #
+        # @return [ApiConfiguration] The tenant's API configuration record
+        def api_configuration!
+          api_configuration || create_api_configuration!(
+            scope_type: "tenant",
+            scope_id: tenant_id
+          )
+        end
+
+        # Configure API settings for this tenant
+        #
+        # @yield [config] Block to configure the API settings
+        # @yieldparam config [ApiConfiguration] The configuration to modify
+        # @return [ApiConfiguration] The saved configuration
+        #
+        # @example
+        #   tenant.configure_api do |config|
+        #     config.openai_api_key = "sk-..."
+        #     config.default_model = "gpt-4o"
+        #   end
+        def configure_api(&block)
+          config = api_configuration!
+          yield(config) if block_given?
+          config.save!
+          config
+        end
+
+        # Check if a specific provider is configured for this tenant
+        #
+        # @param provider [Symbol] Provider name
+        # @return [Boolean] true if the provider has an API key set
+        def provider_configured?(provider)
+          api_key_for(provider).present?
+        end
+
+        # Get all configured providers for this tenant
+        #
+        # @return [Array<Symbol>] List of configured provider symbols
+        def configured_providers
+          return [] unless api_configuration
+
+          ApiConfiguration::PROVIDERS.keys.select do |provider|
+            provider_configured?(provider)
+          end
+        end
+
+        # Get the default model for this tenant
+        #
+        # @return [String, nil] The default model or nil
+        def default_model
+          api_configuration&.default_model
+        end
+
+        # Get the default embedding model for this tenant
+        #
+        # @return [String, nil] The default embedding model or nil
+        def default_embedding_model
+          api_configuration&.default_embedding_model
+        end
+      end
+    end
+  end
+end