ruby_llm-agents 0.5.0 → 1.0.0.beta.1

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

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+require "digest"
+require_relative "../concerns/image_operation_execution"
+
+module RubyLLM
+  module Agents
+    class BackgroundRemover
+      # Execution logic for background removers
+      #
+      # Handles image validation, budget tracking, caching,
+      # background removal execution, and result building.
+      #
+      module Execution
+        include Concerns::ImageOperationExecution
+
+        # Execute the background removal pipeline
+        #
+        # @return [BackgroundRemovalResult] The result containing extracted subject
+        def execute
+          started_at = Time.current
+
+          resolve_tenant_context!
+          check_budget! if budget_tracking_enabled?
+          validate_image!
+
+          # Check cache
+          cached = check_cache(BackgroundRemovalResult) if cache_enabled?
+          return cached if cached
+
+          # Remove background
+          removal_result = remove_background
+
+          # Build result
+          result = build_result(
+            foreground: removal_result[:foreground],
+            mask: removal_result[:mask],
+            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
+          "background_removal"
+        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 remove_background
+          # Try different approaches based on available capabilities
+          if RubyLLM.respond_to?(:remove_background)
+            remove_via_ruby_llm
+          else
+            remove_via_provider
+          end
+        end
+
+        def remove_via_ruby_llm
+          result = RubyLLM.remove_background(
+            image: image,
+            model: resolve_model,
+            **build_removal_options
+          )
+
+          {
+            foreground: result,
+            mask: result.respond_to?(:mask) ? result.mask : nil
+          }
+        end
+
+        def remove_via_provider
+          # Use the model through RubyLLM's paint with segmentation/removal mode
+          # This handles models like segment-anything, rembg, etc.
+          foreground = RubyLLM.paint(
+            "Remove background from this image",
+            model: resolve_model,
+            image: image,
+            mode: "background_removal",
+            **build_removal_options
+          )
+
+          mask = nil
+          if resolve_return_mask
+            # Request mask separately if needed
+            begin
+              mask = RubyLLM.paint(
+                "Generate segmentation mask for this image",
+                model: resolve_model,
+                image: image,
+                mode: "segmentation_mask",
+                **build_removal_options
+              )
+            rescue StandardError
+              # Mask generation failed, continue without it
+              mask = nil
+            end
+          end
+
+          { foreground: foreground, mask: mask }
+        end
+
+        def build_removal_options
+          opts = {}
+          opts[:output_format] = resolve_output_format
+          opts[:refine_edges] = resolve_refine_edges if resolve_refine_edges
+          opts[:alpha_matting] = resolve_alpha_matting if resolve_alpha_matting
+          opts[:foreground_threshold] = resolve_foreground_threshold
+          opts[:background_threshold] = resolve_background_threshold
+          opts[:erode_size] = resolve_erode_size if resolve_erode_size > 0
+          opts[:return_mask] = resolve_return_mask if resolve_return_mask
+          opts[:assume_model_exists] = true if options[:assume_model_exists]
+          opts
+        end
+
+        def build_result(foreground:, mask:, started_at:, completed_at:)
+          BackgroundRemovalResult.new(
+            foreground: foreground,
+            mask: mask,
+            source_image: image,
+            model_id: resolve_model,
+            output_format: resolve_output_format,
+            alpha_matting: resolve_alpha_matting,
+            refine_edges: resolve_refine_edges,
+            started_at: started_at,
+            completed_at: completed_at,
+            tenant_id: @tenant_id,
+            remover_class: self.class.name
+          )
+        end
+
+        def build_error_result(error, started_at)
+          BackgroundRemovalResult.new(
+            foreground: nil,
+            mask: nil,
+            source_image: image,
+            model_id: resolve_model,
+            output_format: resolve_output_format,
+            alpha_matting: resolve_alpha_matting,
+            refine_edges: resolve_refine_edges,
+            started_at: started_at,
+            completed_at: Time.current,
+            tenant_id: @tenant_id,
+            remover_class: self.class.name,
+            error_class: error.class.name,
+            error_message: error.message
+          )
+        end
+
+        # Resolution methods
+
+        def resolve_output_format
+          options[:output_format] || self.class.output_format
+        end
+
+        def resolve_refine_edges
+          options.fetch(:refine_edges, self.class.refine_edges)
+        end
+
+        def resolve_alpha_matting
+          options.fetch(:alpha_matting, self.class.alpha_matting)
+        end
+
+        def resolve_foreground_threshold
+          options[:foreground_threshold] || self.class.foreground_threshold
+        end
+
+        def resolve_background_threshold
+          options[:background_threshold] || self.class.background_threshold
+        end
+
+        def resolve_erode_size
+          options[:erode_size] || self.class.erode_size
+        end
+
+        def resolve_return_mask
+          options.fetch(:return_mask, self.class.return_mask)
+        end
+
+        # Cache key components
+        def cache_key_components
+          [
+            "background_remover",
+            self.class.name,
+            self.class.version,
+            resolve_model,
+            resolve_output_format.to_s,
+            resolve_alpha_matting.to_s,
+            resolve_refine_edges.to_s,
+            resolve_foreground_threshold.to_s,
+            resolve_background_threshold.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)
+          {
+            output_format: result.output_format,
+            alpha_matting: result.alpha_matting,
+            refine_edges: result.refine_edges,
+            has_mask: result.mask?
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require_relative "background_remover/dsl"
+require_relative "background_remover/execution"
+
+module RubyLLM
+  module Agents
+    # Background remover for subject extraction
+    #
+    # Removes backgrounds from images using segmentation models,
+    # producing transparent PNGs or masked outputs.
+    #
+    # @example Basic usage
+    #   result = RubyLLM::Agents::BackgroundRemover.call(image: "path/to/photo.jpg")
+    #   result.url       # => "https://..." (transparent PNG)
+    #   result.has_alpha? # => true
+    #
+    # @example Custom remover class
+    #   class ProductBackgroundRemover < RubyLLM::Agents::BackgroundRemover
+    #     model "segment-anything"
+    #     output_format :png
+    #     refine_edges true
+    #     alpha_matting true
+    #
+    #     description "Removes backgrounds from product photos"
+    #   end
+    #
+    #   result = ProductBackgroundRemover.call(image: product_photo)
+    #   result.foreground # => The extracted subject
+    #   result.mask       # => Segmentation mask
+    #
+    class BackgroundRemover
+      extend DSL
+      include Execution
+
+      class << self
+        # Execute background removal
+        #
+        # @param image [String, IO] Path, URL, or IO object of the source image
+        # @param options [Hash] Additional options (model, output_format, etc.)
+        # @return [BackgroundRemovalResult] The result containing extracted subject
+        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(:@output_format, @output_format)
+          subclass.instance_variable_set(:@refine_edges, @refine_edges)
+          subclass.instance_variable_set(:@alpha_matting, @alpha_matting)
+          subclass.instance_variable_set(:@foreground_threshold, @foreground_threshold)
+          subclass.instance_variable_set(:@background_threshold, @background_threshold)
+          subclass.instance_variable_set(:@erode_size, @erode_size)
+          subclass.instance_variable_set(:@return_mask, @return_mask)
+          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 background remover 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 [Symbol] :output_format Output format (:png, :webp)
+      # @option options [Boolean] :refine_edges Enable edge refinement
+      # @option options [Boolean] :alpha_matting Enable alpha matting for better edges
+      # @option options [Boolean] :return_mask Also return the segmentation mask
+      # @option options [Object] :tenant Tenant for multi-tenancy
+      def initialize(image:, **options)
+        @image = image
+        @options = options
+        @tenant_id = nil
+      end
+
+      # Execute the background removal
+      #
+      # @return [BackgroundRemovalResult] The result containing extracted subject
+      def call
+        execute
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/image/concerns/image_operation_dsl.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    module Concerns
+      # Shared DSL methods for all image operation classes
+      #
+      # Provides common configuration options like model, version,
+      # description, and caching that are shared across ImageVariator,
+      # ImageEditor, ImageTransformer, and ImageUpscaler.
+      #
+      module ImageOperationDSL
+        # Set or get the model
+        #
+        # @param value [String, nil] Model identifier
+        # @return [String] The model to use
+        def model(value = nil)
+          if value
+            @model = value
+          else
+            @model || inherited_or_default(:model, default_model)
+          end
+        end
+
+        # Set or get the version
+        #
+        # @param value [String, nil] Version identifier
+        # @return [String] The version
+        def version(value = nil)
+          if value
+            @version = value
+          else
+            @version || inherited_or_default(:version, "v1")
+          end
+        end
+
+        # Set or get the description
+        #
+        # @param value [String, nil] Description
+        # @return [String, nil] The description
+        def description(value = nil)
+          if value
+            @description = value
+          else
+            @description || inherited_or_default(:description, nil)
+          end
+        end
+
+        # Enable caching with the given TTL
+        #
+        # @param ttl [ActiveSupport::Duration, Integer] Cache duration
+        def cache_for(ttl)
+          @cache_ttl = ttl
+        end
+
+        # Get the cache TTL
+        #
+        # @return [ActiveSupport::Duration, Integer, nil] The cache TTL
+        def cache_ttl
+          @cache_ttl || inherited_or_default(:cache_ttl, nil)
+        end
+
+        # Check if caching is enabled
+        #
+        # @return [Boolean] true if caching is enabled
+        def cache_enabled?
+          !cache_ttl.nil?
+        end
+
+        private
+
+        def config
+          RubyLLM::Agents.configuration
+        end
+
+        def inherited_or_default(attribute, default)
+          if superclass.respond_to?(attribute)
+            superclass.public_send(attribute)
+          else
+            default
+          end
+        end
+
+        # Override in submodules to provide default model
+        def default_model
+          config.default_image_model
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/image/concerns/image_operation_execution.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module RubyLLM
+  module Agents
+    module Concerns
+      # Shared execution logic for all image operation classes
+      #
+      # Provides common functionality like tenant resolution, budget tracking,
+      # caching, and execution recording that are shared across ImageVariator,
+      # ImageEditor, ImageTransformer, and ImageUpscaler.
+      #
+      module ImageOperationExecution
+        private
+
+        # Resolve tenant from options
+        def resolve_tenant_context!
+          tenant = options[:tenant]
+          return unless tenant
+
+          @tenant_id = case tenant
+                       when Hash then tenant[:id]
+                       when Integer, String then tenant
+                       else
+                         tenant.try(:llm_tenant_id) || tenant.try(:id)
+                       end
+        end
+
+        # Check budget before execution
+        def check_budget!
+          BudgetTracker.check!(
+            agent_type: self.class.name,
+            tenant_id: @tenant_id,
+            execution_type: execution_type
+          )
+        end
+
+        # Override in subclasses to specify execution type
+        def execution_type
+          raise NotImplementedError, "Subclasses must implement #execution_type"
+        end
+
+        # Caching support
+
+        def cache_enabled?
+          self.class.cache_enabled? && !options[:skip_cache]
+        end
+
+        def cache_key_components
+          raise NotImplementedError, "Subclasses must implement #cache_key_components"
+        end
+
+        def cache_key
+          components = ["ruby_llm_agents"] + cache_key_components
+          components.join(":")
+        end
+
+        def check_cache(result_class)
+          return nil unless defined?(Rails) && Rails.cache
+
+          cached_data = Rails.cache.read(cache_key)
+          return nil unless cached_data
+
+          result_class.from_cache(cached_data)
+        end
+
+        def write_cache(result)
+          return unless defined?(Rails) && Rails.cache
+          return unless result.success?
+
+          Rails.cache.write(cache_key, result.to_cache, expires_in: self.class.cache_ttl)
+        end
+
+        # Execution tracking
+
+        def execution_tracking_enabled?
+          config.track_image_generation
+        end
+
+        def record_execution(result)
+          return unless defined?(RubyLLM::Agents::Execution)
+
+          execution_data = build_execution_data(result)
+
+          if config.async_logging && defined?(ExecutionLoggerJob)
+            ExecutionLoggerJob.perform_later(execution_data)
+          else
+            RubyLLM::Agents::Execution.create!(execution_data)
+          end
+        rescue StandardError => e
+          Rails.logger.error("[RubyLLM::Agents] Failed to record #{execution_type} execution: #{e.message}") if defined?(Rails)
+        end
+
+        def record_failed_execution(error, started_at)
+          return unless defined?(RubyLLM::Agents::Execution)
+
+          execution_data = build_failed_execution_data(error, started_at)
+
+          if config.async_logging && defined?(ExecutionLoggerJob)
+            ExecutionLoggerJob.perform_later(execution_data)
+          else
+            RubyLLM::Agents::Execution.create!(execution_data)
+          end
+        rescue StandardError => e
+          Rails.logger.error("[RubyLLM::Agents] Failed to record failed #{execution_type} execution: #{e.message}") if defined?(Rails)
+        end
+
+        def build_execution_data(result)
+          {
+            agent_type: self.class.name,
+            tenant_id: @tenant_id,
+            execution_type: execution_type,
+            model_id: result.model_id,
+            status: "success",
+            input_tokens: 0,
+            output_tokens: 0,
+            total_cost: result.total_cost,
+            duration_ms: result.duration_ms,
+            started_at: result.started_at,
+            completed_at: result.completed_at,
+            metadata: build_execution_metadata(result)
+          }
+        end
+
+        def build_failed_execution_data(error, started_at)
+          {
+            agent_type: self.class.name,
+            tenant_id: @tenant_id,
+            execution_type: execution_type,
+            model_id: resolve_model,
+            status: "error",
+            input_tokens: 0,
+            output_tokens: 0,
+            total_cost: 0,
+            duration_ms: ((Time.current - started_at) * 1000).round,
+            started_at: started_at,
+            completed_at: Time.current,
+            error_class: error.class.name,
+            error_message: error.message.truncate(1000),
+            metadata: {}
+          }
+        end
+
+        def build_execution_metadata(result)
+          { count: result.count }
+        end
+
+        def budget_tracking_enabled?
+          config.budgets_enabled? && defined?(BudgetTracker)
+        end
+
+        def config
+          RubyLLM::Agents.configuration
+        end
+
+        # Model resolution with alias support
+        def resolve_model
+          model = options[:model] || self.class.model
+          config.image_model_aliases&.dig(model.to_sym) || model
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "../concerns/image_operation_dsl"
+require_relative "../generator/content_policy"
+
+module RubyLLM
+  module Agents
+    class ImageEditor
+      # DSL for configuring image editors
+      #
+      # Provides class-level methods to configure model, size,
+      # and other image editing parameters.
+      #
+      # @example
+      #   class ProductEditor < RubyLLM::Agents::ImageEditor
+      #     model "gpt-image-1"
+      #     size "1024x1024"
+      #     content_policy :strict
+      #   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 content policy level
+        #
+        # @param level [Symbol, nil] Policy level (:none, :standard, :moderate, :strict)
+        # @return [Symbol] The content policy level
+        def content_policy(level = nil)
+          if level
+            @content_policy = level
+          else
+            @content_policy || inherited_or_default(:content_policy, :standard)
+          end
+        end
+
+        private
+
+        def default_model
+          config.default_editor_model || config.default_image_model
+        end
+      end
+    end
+  end
+end