ruby_llm-agents 0.5.0 → 1.0.0.beta.1

data/lib/ruby_llm/agents/image/variator/dsl.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative "../concerns/image_operation_dsl"
+
+module RubyLLM
+  module Agents
+    class ImageVariator
+      # DSL for configuring image variators
+      #
+      # Provides class-level methods to configure model, size,
+      # variation strength, and other image variation parameters.
+      #
+      # @example
+      #   class LogoVariator < RubyLLM::Agents::ImageVariator
+      #     model "gpt-image-1"
+      #     size "1024x1024"
+      #     variation_strength 0.3
+      #     cache_for 1.hour
+      #   end
+      #
+      module DSL
+        include Concerns::ImageOperationDSL
+
+        # Set or get the output image size
+        #
+        # @param value [String, nil] Size (e.g., "1024x1024")
+        # @return [String] The size to use
+        def size(value = nil)
+          if value
+            @size = value
+          else
+            @size || inherited_or_default(:size, config.default_image_size)
+          end
+        end
+
+        # Set or get the variation strength
+        #
+        # Controls how different variations should be from the original.
+        # Higher values produce more diverse variations.
+        #
+        # @param value [Float, nil] Strength (0.0-1.0)
+        # @return [Float] The variation strength
+        def variation_strength(value = nil)
+          if value
+            unless value.is_a?(Numeric) && value.between?(0.0, 1.0)
+              raise ArgumentError, "Variation strength must be between 0.0 and 1.0"
+            end
+            @variation_strength = value.to_f
+          else
+            @variation_strength || inherited_or_default(:variation_strength, 0.5)
+          end
+        end
+
+        private
+
+        def default_model
+          config.default_variator_model || config.default_image_model
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/image/variator/execution.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require "digest"
+require_relative "../concerns/image_operation_execution"
+
+module RubyLLM
+  module Agents
+    class ImageVariator
+      # Execution logic for image variators
+      #
+      # Handles image validation, budget tracking, caching,
+      # variation generation, and result building.
+      #
+      module Execution
+        include Concerns::ImageOperationExecution
+
+        # Execute the image variation pipeline
+        #
+        # @return [ImageVariationResult] The result containing variation images
+        def execute
+          started_at = Time.current
+
+          resolve_tenant_context!
+          check_budget! if budget_tracking_enabled?
+          validate_image!
+
+          # Check cache
+          cached = check_cache(ImageVariationResult) if cache_enabled?
+          return cached if cached
+
+          # Generate variations
+          variations = generate_variations
+
+          # Build result
+          result = build_result(
+            images: variations,
+            started_at: started_at,
+            completed_at: Time.current
+          )
+
+          # Cache result
+          write_cache(result) if cache_enabled?
+
+          # Track execution
+          record_execution(result) if execution_tracking_enabled?
+
+          result
+        rescue StandardError => e
+          record_failed_execution(e, started_at) if execution_tracking_enabled?
+          build_error_result(e, started_at)
+        end
+
+        private
+
+        def execution_type
+          "image_variation"
+        end
+
+        def validate_image!
+          raise ArgumentError, "Image cannot be blank" if image.nil?
+
+          # Validate image exists if it's a path
+          if image.is_a?(String) && !image.start_with?("http")
+            unless File.exist?(image)
+              raise ArgumentError, "Image file does not exist: #{image}"
+            end
+          end
+        end
+
+        def generate_variations
+          count = resolve_count
+
+          # Generate variations using the underlying image API
+          # Note: The actual implementation depends on the provider
+          Array.new(count) do
+            generate_single_variation
+          end
+        end
+
+        def generate_single_variation
+          # Use RubyLLM's variation endpoint if available,
+          # otherwise use edit with the original image
+          if RubyLLM.respond_to?(:create_image_variation)
+            RubyLLM.create_image_variation(
+              image: image,
+              model: resolve_model,
+              size: resolve_size,
+              **build_variation_options
+            )
+          else
+            # Fallback: Use paint with image reference
+            # This approach works for models that support img2img
+            RubyLLM.paint(
+              "Create a variation of this image",
+              model: resolve_model,
+              size: resolve_size,
+              reference_image: image,
+              strength: resolve_variation_strength,
+              **build_variation_options
+            )
+          end
+        end
+
+        def build_variation_options
+          opts = {}
+          opts[:assume_model_exists] = true if options[:assume_model_exists]
+          opts
+        end
+
+        def build_result(images:, started_at:, completed_at:)
+          ImageVariationResult.new(
+            images: images,
+            source_image: image,
+            model_id: resolve_model,
+            size: resolve_size,
+            variation_strength: resolve_variation_strength,
+            started_at: started_at,
+            completed_at: completed_at,
+            tenant_id: @tenant_id,
+            variator_class: self.class.name
+          )
+        end
+
+        def build_error_result(error, started_at)
+          ImageVariationResult.new(
+            images: [],
+            source_image: image,
+            model_id: resolve_model,
+            size: resolve_size,
+            variation_strength: resolve_variation_strength,
+            started_at: started_at,
+            completed_at: Time.current,
+            tenant_id: @tenant_id,
+            variator_class: self.class.name,
+            error_class: error.class.name,
+            error_message: error.message
+          )
+        end
+
+        # Resolution methods
+
+        def resolve_size
+          options[:size] || self.class.size
+        end
+
+        def resolve_variation_strength
+          options[:variation_strength] || self.class.variation_strength
+        end
+
+        def resolve_count
+          options[:count] || 1
+        end
+
+        # Cache key components
+        def cache_key_components
+          [
+            "image_variator",
+            self.class.name,
+            self.class.version,
+            resolve_model,
+            resolve_size,
+            resolve_variation_strength.to_s,
+            Digest::SHA256.hexdigest(image_digest)
+          ]
+        end
+
+        def image_digest
+          if image.is_a?(String) && File.exist?(image)
+            File.read(image)
+          elsif image.respond_to?(:read)
+            content = image.read
+            image.rewind if image.respond_to?(:rewind)
+            content
+          else
+            image.to_s
+          end
+        end
+
+        def build_execution_metadata(result)
+          {
+            count: result.count,
+            size: result.size,
+            variation_strength: result.variation_strength
+          }
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/image/variator.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative "variator/dsl"
+require_relative "variator/execution"
+
+module RubyLLM
+  module Agents
+    # Image variator for generating variations of existing images
+    #
+    # Creates variations of an input image while maintaining the overall
+    # composition and style. Useful for exploring design alternatives
+    # or generating A/B test variants.
+    #
+    # @example Basic usage
+    #   result = RubyLLM::Agents::ImageVariator.call(image: "path/to/image.png")
+    #   result.urls # => ["https://...", ...]
+    #
+    # @example Custom variator class
+    #   class LogoVariator < RubyLLM::Agents::ImageVariator
+    #     model "gpt-image-1"
+    #     variation_strength 0.3
+    #     size "1024x1024"
+    #
+    #     description "Creates variations of logos"
+    #   end
+    #
+    #   result = LogoVariator.call(image: original_logo, count: 4)
+    #
+    class ImageVariator
+      extend DSL
+      include Execution
+
+      class << self
+        # Execute image variation with the given source image
+        #
+        # @param image [String, IO] Path, URL, or IO object of the source image
+        # @param options [Hash] Additional options (model, count, size, etc.)
+        # @return [ImageVariationResult] The result containing variation images
+        def call(image:, **options)
+          new(image: image, **options).call
+        end
+
+        # Ensure subclasses inherit DSL settings
+        def inherited(subclass)
+          super
+          subclass.instance_variable_set(:@model, @model)
+          subclass.instance_variable_set(:@size, @size)
+          subclass.instance_variable_set(:@variation_strength, @variation_strength)
+          subclass.instance_variable_set(:@version, @version)
+          subclass.instance_variable_set(:@description, @description)
+          subclass.instance_variable_set(:@cache_ttl, @cache_ttl)
+        end
+      end
+
+      attr_reader :image, :options, :tenant_id
+
+      # Initialize a new image variator instance
+      #
+      # @param image [String, IO] Source image (path, URL, or IO object)
+      # @param options [Hash] Additional options
+      # @option options [String] :model Model to use
+      # @option options [Integer] :count Number of variations to generate
+      # @option options [String] :size Output image size
+      # @option options [Float] :variation_strength How different variations should be (0.0-1.0)
+      # @option options [Object] :tenant Tenant for multi-tenancy
+      def initialize(image:, **options)
+        @image = image
+        @options = options
+        @tenant_id = nil
+      end
+
+      # Execute the image variation
+      #
+      # @return [ImageVariationResult] The result containing variation images
+      def call
+        execute
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/{alert_manager.rb → infrastructure/alert_manager.rb}

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
-require "faraday"
+require "net/http"
+require "uri"
 require "json"
 
 module RubyLLM
@@ -177,34 +178,28 @@ module RubyLLM
           end
         end
 
-        # Posts JSON to a URL using Faraday
+        # Posts JSON to a URL using Net::HTTP
         #
         # @param url [String] The URL
         # @param payload [Hash] The payload
-        # @return [Faraday::Response]
+        # @return [Net::HTTPResponse]
         def post_json(url, payload)
-          response = http_client.post(url) do |req|
-            req.headers["Content-Type"] = "application/json"
-            req.body = payload.to_json
+          uri = URI.parse(url)
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = (uri.scheme == "https")
+          http.open_timeout = 5
+          http.read_timeout = 10
+
+          request = Net::HTTP::Post.new(uri.request_uri)
+          request["Content-Type"] = "application/json"
+          request.body = payload.to_json
+
+          response = http.request(request)
+          unless response.is_a?(Net::HTTPSuccess)
+            Rails.logger.warn("[RubyLLM::Agents::AlertManager] Webhook returned #{response.code}: #{response.body}")
           end
-
-          unless response.success?
-            Rails.logger.warn("[RubyLLM::Agents::AlertManager] Webhook returned #{response.status}: #{response.body}")
-          end
-
           response
         end
-
-        # Returns a configured Faraday HTTP client
-        #
-        # @return [Faraday::Connection]
-        def http_client
-          @http_client ||= Faraday.new do |conn|
-            conn.options.open_timeout = 5
-            conn.options.timeout = 10
-            conn.adapter Faraday.default_adapter
-          end
-        end
       end
     end
   end

data/lib/ruby_llm/agents/infrastructure/budget/budget_query.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require_relative "../cache_helper"
+
+module RubyLLM
+  module Agents
+    module Budget
+      # Query methods for current spend, remaining budget, and status
+      #
+      # @api private
+      module BudgetQuery
+        extend CacheHelper
+
+        class << self
+          # Returns the current spend for a scope and period
+          #
+          # @param scope [Symbol] :global or :agent
+          # @param period [Symbol] :daily or :monthly
+          # @param agent_type [String, nil] Required when scope is :agent
+          # @param tenant_id [String, nil] The tenant identifier
+          # @return [Float] Current spend in USD
+          def current_spend(scope, period, agent_type: nil, tenant_id: nil)
+            key = SpendRecorder.budget_cache_key(scope, period, agent_type: agent_type, tenant_id: tenant_id)
+            (BudgetQuery.cache_read(key) || 0).to_f
+          end
+
+          # Returns the current token usage for a period (global only)
+          #
+          # @param period [Symbol] :daily or :monthly
+          # @param tenant_id [String, nil] The tenant identifier
+          # @return [Integer] Current token usage
+          def current_tokens(period, tenant_id: nil)
+            key = SpendRecorder.token_cache_key(period, tenant_id: tenant_id)
+            (BudgetQuery.cache_read(key) || 0).to_i
+          end
+
+          # Returns the remaining budget for a scope and period
+          #
+          # @param scope [Symbol] :global or :agent
+          # @param period [Symbol] :daily or :monthly
+          # @param agent_type [String, nil] Required when scope is :agent
+          # @param tenant_id [String, nil] The tenant identifier
+          # @param budget_config [Hash] Budget configuration
+          # @return [Float, nil] Remaining budget in USD, or nil if no limit configured
+          def remaining_budget(scope, period, agent_type: nil, tenant_id: nil, budget_config:)
+            limit = case [scope, period]
+            when [:global, :daily]
+              budget_config[:global_daily]
+            when [:global, :monthly]
+              budget_config[:global_monthly]
+            when [:agent, :daily]
+              budget_config[:per_agent_daily]&.dig(agent_type)
+            when [:agent, :monthly]
+              budget_config[:per_agent_monthly]&.dig(agent_type)
+            end
+
+            return nil unless limit
+
+            [limit - current_spend(scope, period, agent_type: agent_type, tenant_id: tenant_id), 0].max
+          end
+
+          # Returns the remaining token budget for a period (global only)
+          #
+          # @param period [Symbol] :daily or :monthly
+          # @param tenant_id [String, nil] The tenant identifier
+          # @param budget_config [Hash] Budget configuration
+          # @return [Integer, nil] Remaining token budget, or nil if no limit configured
+          def remaining_token_budget(period, tenant_id: nil, budget_config:)
+            limit = case period
+            when :daily
+              budget_config[:global_daily_tokens]
+            when :monthly
+              budget_config[:global_monthly_tokens]
+            end
+
+            return nil unless limit
+
+            [limit - current_tokens(period, tenant_id: tenant_id), 0].max
+          end
+
+          # Returns a summary of all budget statuses
+          #
+          # @param agent_type [String, nil] Optional agent type for per-agent budgets
+          # @param tenant_id [String, nil] The tenant identifier
+          # @param budget_config [Hash] Budget configuration
+          # @return [Hash] Budget status information
+          def status(agent_type: nil, tenant_id: nil, budget_config:)
+            {
+              tenant_id: tenant_id,
+              enabled: budget_config[:enabled],
+              enforcement: budget_config[:enforcement],
+              # Cost budgets
+              global_daily: budget_status(:global, :daily, budget_config[:global_daily], tenant_id: tenant_id),
+              global_monthly: budget_status(:global, :monthly, budget_config[:global_monthly], tenant_id: tenant_id),
+              per_agent_daily: agent_type ? budget_status(:agent, :daily, budget_config[:per_agent_daily]&.dig(agent_type), agent_type: agent_type, tenant_id: tenant_id) : nil,
+              per_agent_monthly: agent_type ? budget_status(:agent, :monthly, budget_config[:per_agent_monthly]&.dig(agent_type), agent_type: agent_type, tenant_id: tenant_id) : nil,
+              # Token budgets (global only)
+              global_daily_tokens: token_status(:daily, budget_config[:global_daily_tokens], tenant_id: tenant_id),
+              global_monthly_tokens: token_status(:monthly, budget_config[:global_monthly_tokens], tenant_id: tenant_id),
+              forecast: Forecaster.calculate_forecast(tenant_id: tenant_id, budget_config: budget_config)
+            }.compact
+          end
+
+          # Returns budget status for a scope/period
+          #
+          # @param scope [Symbol] :global or :agent
+          # @param period [Symbol] :daily or :monthly
+          # @param limit [Float, nil] The budget limit
+          # @param agent_type [String, nil] Required when scope is :agent
+          # @param tenant_id [String, nil] The tenant identifier
+          # @return [Hash, nil] Status hash or nil if no limit
+          def budget_status(scope, period, limit, agent_type: nil, tenant_id: nil)
+            return nil unless limit
+
+            current = current_spend(scope, period, agent_type: agent_type, tenant_id: tenant_id)
+            {
+              limit: limit,
+              current: current.round(6),
+              remaining: [limit - current, 0].max.round(6),
+              percentage_used: ((current / limit) * 100).round(2)
+            }
+          end
+
+          # Returns token status for a period
+          #
+          # @param period [Symbol] :daily or :monthly
+          # @param limit [Integer, nil] The token limit
+          # @param tenant_id [String, nil] The tenant identifier
+          # @return [Hash, nil] Status hash or nil if no limit
+          def token_status(period, limit, tenant_id: nil)
+            return nil unless limit
+
+            current = current_tokens(period, tenant_id: tenant_id)
+            {
+              limit: limit,
+              current: current,
+              remaining: [limit - current, 0].max,
+              percentage_used: ((current.to_f / limit) * 100).round(2)
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/infrastructure/budget/config_resolver.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    module Budget
+      # Resolves budget configuration for tenants and global settings
+      #
+      # Handles the resolution priority chain:
+      # 1. Runtime config passed to run()
+      # 2. tenant_config_resolver lambda
+      # 3. TenantBudget database record
+      # 4. Global configuration
+      #
+      # @api private
+      module ConfigResolver
+        class << self
+          # Resolves the current tenant ID
+          #
+          # @param explicit_tenant_id [String, nil] Explicitly passed tenant ID
+          # @return [String, nil] Resolved tenant ID or nil if multi-tenancy disabled
+          def resolve_tenant_id(explicit_tenant_id)
+            config = RubyLLM::Agents.configuration
+
+            # Ignore tenant_id entirely when multi-tenancy is disabled
+            return nil unless config.multi_tenancy_enabled?
+
+            # Use explicit tenant_id if provided, otherwise use resolver
+            return explicit_tenant_id if explicit_tenant_id.present?
+
+            config.tenant_resolver&.call
+          end
+
+          # Resolves budget configuration for a tenant
+          #
+          # Priority order:
+          # 1. runtime_config (passed to run())
+          # 2. tenant_config_resolver (configured lambda)
+          # 3. TenantBudget database record
+          # 4. Global configuration
+          #
+          # @param tenant_id [String, nil] The tenant identifier
+          # @param runtime_config [Hash, nil] Runtime config passed to run()
+          # @return [Hash] Budget configuration
+          def resolve_budget_config(tenant_id, runtime_config: nil)
+            config = RubyLLM::Agents.configuration
+
+            # Priority 1: Runtime config passed directly to run()
+            if runtime_config.present?
+              return normalize_budget_config(runtime_config, config)
+            end
+
+            # If multi-tenancy is disabled or no tenant, use global config
+            if tenant_id.nil? || !config.multi_tenancy_enabled?
+              return global_budget_config(config)
+            end
+
+            # Priority 2: tenant_config_resolver lambda
+            if config.tenant_config_resolver.present?
+              resolved_config = config.tenant_config_resolver.call(tenant_id)
+              if resolved_config.present?
+                return normalize_budget_config(resolved_config, config)
+              end
+            end
+
+            # Priority 3: Look up tenant-specific budget from database
+            tenant_budget = lookup_tenant_budget(tenant_id)
+
+            if tenant_budget
+              tenant_budget.to_budget_config
+            else
+              # Priority 4: Fall back to global config for unknown tenants
+              global_budget_config(config)
+            end
+          end
+
+          # Builds global budget config from configuration
+          #
+          # @param config [Configuration] The configuration object
+          # @return [Hash] Budget configuration
+          def global_budget_config(config)
+            {
+              enabled: config.budgets_enabled?,
+              enforcement: config.budget_enforcement,
+              global_daily: config.budgets&.dig(:global_daily),
+              global_monthly: config.budgets&.dig(:global_monthly),
+              per_agent_daily: config.budgets&.dig(:per_agent_daily),
+              per_agent_monthly: config.budgets&.dig(:per_agent_monthly),
+              global_daily_tokens: config.budgets&.dig(:global_daily_tokens),
+              global_monthly_tokens: config.budgets&.dig(:global_monthly_tokens)
+            }
+          end
+
+          # Normalizes runtime/resolver config to standard budget config format
+          #
+          # @param raw_config [Hash] Raw config from runtime or resolver
+          # @param global_config [Configuration] Global config for fallbacks
+          # @return [Hash] Normalized budget configuration
+          def normalize_budget_config(raw_config, global_config)
+            enforcement = raw_config[:enforcement]&.to_sym || global_config.budget_enforcement
+
+            {
+              enabled: enforcement != :none,
+              enforcement: enforcement,
+              # Cost/budget limits (USD)
+              global_daily: raw_config[:daily_budget_limit],
+              global_monthly: raw_config[:monthly_budget_limit],
+              per_agent_daily: raw_config[:per_agent_daily] || {},
+              per_agent_monthly: raw_config[:per_agent_monthly] || {},
+              # Token limits
+              global_daily_tokens: raw_config[:daily_token_limit],
+              global_monthly_tokens: raw_config[:monthly_token_limit]
+            }
+          end
+
+          # Safely looks up tenant budget, handling missing table
+          #
+          # @param tenant_id [String] The tenant identifier
+          # @return [TenantBudget, nil] The tenant budget or nil
+          def lookup_tenant_budget(tenant_id)
+            return nil unless tenant_budget_table_exists?
+
+            TenantBudget.for_tenant(tenant_id)
+          rescue StandardError => e
+            Rails.logger.warn("[RubyLLM::Agents] Failed to lookup tenant budget: #{e.message}")
+            nil
+          end
+
+          # Checks if the tenant_budgets table exists
+          #
+          # @return [Boolean] true if table exists
+          def tenant_budget_table_exists?
+            return @tenant_budget_table_exists if defined?(@tenant_budget_table_exists)
+
+            @tenant_budget_table_exists = ::ActiveRecord::Base.connection.table_exists?(:ruby_llm_agents_tenant_budgets)
+          rescue StandardError
+            @tenant_budget_table_exists = false
+          end
+
+          # Resets the memoized tenant budget table existence check (useful for testing)
+          #
+          # @return [void]
+          def reset_tenant_budget_table_check!
+            remove_instance_variable(:@tenant_budget_table_exists) if defined?(@tenant_budget_table_exists)
+          end
+        end
+      end
+    end
+  end
+end