ruby_llm-agents 0.5.0 → 1.0.0

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

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+require "digest"
+require_relative "../concerns/image_operation_execution"
+
+module RubyLLM
+  module Agents
+    class ImageTransformer
+      # Execution logic for image transformers
+      #
+      # Handles image validation, content policy checks, budget tracking,
+      # caching, image transformation, and result building.
+      #
+      module Execution
+        include Concerns::ImageOperationExecution
+
+        # Execute the image transformation pipeline
+        #
+        # @return [ImageTransformResult] The result containing transformed image
+        def execute
+          started_at = Time.current
+
+          resolve_tenant_context!
+          check_budget! if budget_tracking_enabled?
+          validate_inputs!
+          validate_content_policy!
+
+          # Check cache
+          cached = check_cache(ImageTransformResult) if cache_enabled?
+          return cached if cached
+
+          # Transform image(s)
+          transformed_images = transform_images
+
+          # Build result
+          result = build_result(
+            images: transformed_images,
+            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_transform"
+        end
+
+        def validate_inputs!
+          raise ArgumentError, "Image cannot be blank" if image.nil?
+          raise ArgumentError, "Prompt cannot be blank" if prompt.nil? || prompt.strip.empty?
+
+          # 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
+
+          # Validate prompt length
+          max_length = config.max_image_prompt_length || 4000
+          if prompt.length > max_length
+            raise ArgumentError, "Prompt exceeds maximum length of #{max_length} characters"
+          end
+        end
+
+        def validate_content_policy!
+          policy = self.class.content_policy
+          return if policy == :none || policy == :standard
+
+          ImageGenerator::ContentPolicy.validate!(prompt, policy)
+        end
+
+        def transform_images
+          count = resolve_count
+
+          Array.new(count) do
+            transform_single_image
+          end
+        end
+
+        def transform_single_image
+          final_prompt = apply_template(prompt)
+
+          # Use img2img/transformation API
+          RubyLLM.paint(
+            final_prompt,
+            model: resolve_model,
+            size: resolve_size,
+            image: image,
+            strength: resolve_strength,
+            **build_transform_options
+          )
+        end
+
+        def apply_template(text)
+          template = self.class.template_string
+          return text unless template
+
+          template.gsub("{prompt}", text)
+        end
+
+        def build_transform_options
+          opts = {}
+          opts[:negative_prompt] = resolve_negative_prompt if resolve_negative_prompt
+          opts[:guidance_scale] = resolve_guidance_scale if resolve_guidance_scale
+          opts[:steps] = resolve_steps if resolve_steps
+          opts[:preserve_composition] = resolve_preserve_composition
+          opts[:assume_model_exists] = true if options[:assume_model_exists]
+          opts
+        end
+
+        def build_result(images:, started_at:, completed_at:)
+          ImageTransformResult.new(
+            images: images,
+            source_image: image,
+            prompt: prompt,
+            model_id: resolve_model,
+            size: resolve_size,
+            strength: resolve_strength,
+            started_at: started_at,
+            completed_at: completed_at,
+            tenant_id: @tenant_id,
+            transformer_class: self.class.name
+          )
+        end
+
+        def build_error_result(error, started_at)
+          ImageTransformResult.new(
+            images: [],
+            source_image: image,
+            prompt: prompt,
+            model_id: resolve_model,
+            size: resolve_size,
+            strength: resolve_strength,
+            started_at: started_at,
+            completed_at: Time.current,
+            tenant_id: @tenant_id,
+            transformer_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_strength
+          options[:strength] || self.class.strength
+        end
+
+        def resolve_preserve_composition
+          options.fetch(:preserve_composition, self.class.preserve_composition)
+        end
+
+        def resolve_negative_prompt
+          options[:negative_prompt] || self.class.negative_prompt
+        end
+
+        def resolve_guidance_scale
+          options[:guidance_scale] || self.class.guidance_scale
+        end
+
+        def resolve_steps
+          options[:steps] || self.class.steps
+        end
+
+        def resolve_count
+          options[:count] || 1
+        end
+
+        # Cache key components
+        def cache_key_components
+          [
+            "image_transformer",
+            self.class.name,
+            self.class.version,
+            resolve_model,
+            resolve_size,
+            resolve_strength.to_s,
+            Digest::SHA256.hexdigest(prompt),
+            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,
+            strength: result.strength,
+            prompt_length: prompt.length
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require_relative "transformer/dsl"
+require_relative "transformer/execution"
+
+module RubyLLM
+  module Agents
+    # Image transformer for style transfer and image-to-image generation
+    #
+    # Transforms an existing image based on a text prompt while
+    # maintaining the overall structure. The strength parameter
+    # controls how much the image is transformed.
+    #
+    # @example Basic usage
+    #   result = RubyLLM::Agents::ImageTransformer.call(
+    #     image: "path/to/photo.jpg",
+    #     prompt: "Convert to watercolor painting style"
+    #   )
+    #   result.url # => "https://..."
+    #
+    # @example Custom transformer class
+    #   class AnimeTransformer < RubyLLM::Agents::ImageTransformer
+    #     model "sdxl"
+    #     strength 0.8
+    #     template "anime style, studio ghibli, {prompt}"
+    #
+    #     description "Transforms photos into anime style"
+    #   end
+    #
+    #   result = AnimeTransformer.call(
+    #     image: user_photo,
+    #     prompt: "portrait of a person"
+    #   )
+    #
+    class ImageTransformer
+      extend DSL
+      include Execution
+
+      class << self
+        # Execute image transformation
+        #
+        # @param image [String, IO] Path, URL, or IO object of the source image
+        # @param prompt [String] Description of the desired transformation
+        # @param options [Hash] Additional options (model, strength, size, etc.)
+        # @return [ImageTransformResult] The result containing transformed image
+        def call(image:, prompt:, **options)
+          new(image: image, prompt: prompt, **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(:@strength, @strength)
+          subclass.instance_variable_set(:@preserve_composition, @preserve_composition)
+          subclass.instance_variable_set(:@version, @version)
+          subclass.instance_variable_set(:@description, @description)
+          subclass.instance_variable_set(:@cache_ttl, @cache_ttl)
+          subclass.instance_variable_set(:@content_policy, @content_policy)
+          subclass.instance_variable_set(:@template_string, @template_string)
+          subclass.instance_variable_set(:@negative_prompt, @negative_prompt)
+          subclass.instance_variable_set(:@guidance_scale, @guidance_scale)
+          subclass.instance_variable_set(:@steps, @steps)
+        end
+      end
+
+      attr_reader :image, :prompt, :options, :tenant_id
+
+      # Initialize a new image transformer instance
+      #
+      # @param image [String, IO] Source image (path, URL, or IO object)
+      # @param prompt [String] Description of the desired transformation
+      # @param options [Hash] Additional options
+      # @option options [String] :model Model to use
+      # @option options [String] :size Output image size
+      # @option options [Float] :strength Transformation strength (0.0-1.0)
+      # @option options [Integer] :count Number of transformations to generate
+      # @option options [Object] :tenant Tenant for multi-tenancy
+      def initialize(image:, prompt:, **options)
+        @image = image
+        @prompt = prompt
+        @options = options
+        @tenant_id = nil
+      end
+
+      # Execute the image transformation
+      #
+      # @return [ImageTransformResult] The result containing transformed image
+      def call
+        execute
+      end
+    end
+  end
+end

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

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require_relative "../concerns/image_operation_dsl"
+
+module RubyLLM
+  module Agents
+    class ImageUpscaler
+      # DSL for configuring image upscalers
+      #
+      # Provides class-level methods to configure model, scale factor,
+      # and other upscaling parameters.
+      #
+      # @example
+      #   class PhotoUpscaler < RubyLLM::Agents::ImageUpscaler
+      #     model "real-esrgan"
+      #     scale 4
+      #     face_enhance true
+      #   end
+      #
+      module DSL
+        include Concerns::ImageOperationDSL
+
+        VALID_SCALES = [2, 4, 8].freeze
+
+        # Set or get the upscale factor
+        #
+        # @param value [Integer, nil] Scale factor (2, 4, or 8)
+        # @return [Integer] The scale factor
+        def scale(value = nil)
+          if value
+            unless VALID_SCALES.include?(value)
+              raise ArgumentError, "Scale must be one of: #{VALID_SCALES.join(', ')}"
+            end
+            @scale = value
+          else
+            @scale || inherited_or_default(:scale, 4)
+          end
+        end
+
+        # Set or get face enhancement
+        #
+        # When enabled, applies additional enhancement to detected faces.
+        # Uses models like GFPGAN for face restoration.
+        #
+        # @param value [Boolean, nil] Enable face enhancement
+        # @return [Boolean] Whether face enhancement is enabled
+        def face_enhance(value = nil)
+          if value.nil?
+            result = @face_enhance
+            result = inherited_or_default(:face_enhance, false) if result.nil?
+            result
+          else
+            @face_enhance = value
+          end
+        end
+
+        # Set or get denoise strength
+        #
+        # Controls how much noise reduction is applied.
+        # Higher values remove more noise but may lose detail.
+        #
+        # @param value [Float, nil] Denoise strength (0.0-1.0)
+        # @return [Float] The denoise strength
+        def denoise_strength(value = nil)
+          if value
+            unless value.is_a?(Numeric) && value.between?(0.0, 1.0)
+              raise ArgumentError, "Denoise strength must be between 0.0 and 1.0"
+            end
+            @denoise_strength = value.to_f
+          else
+            @denoise_strength || inherited_or_default(:denoise_strength, 0.5)
+          end
+        end
+
+        private
+
+        def default_model
+          config.default_upscaler_model || "real-esrgan"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+require "digest"
+require_relative "../concerns/image_operation_execution"
+
+module RubyLLM
+  module Agents
+    class ImageUpscaler
+      # Execution logic for image upscalers
+      #
+      # Handles image validation, budget tracking, caching,
+      # upscaling execution, and result building.
+      #
+      module Execution
+        include Concerns::ImageOperationExecution
+
+        # Execute the image upscaling pipeline
+        #
+        # @return [ImageUpscaleResult] The result containing upscaled image
+        def execute
+          started_at = Time.current
+
+          resolve_tenant_context!
+          check_budget! if budget_tracking_enabled?
+          validate_image!
+
+          # Check cache
+          cached = check_cache(ImageUpscaleResult) if cache_enabled?
+          return cached if cached
+
+          # Upscale image
+          upscaled_image = upscale_image
+
+          # Build result
+          result = build_result(
+            image: upscaled_image,
+            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_upscale"
+        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 upscale_image
+          # Use RubyLLM's upscale endpoint if available
+          if RubyLLM.respond_to?(:upscale_image)
+            RubyLLM.upscale_image(
+              image: image,
+              model: resolve_model,
+              scale: resolve_scale,
+              **build_upscale_options
+            )
+          else
+            # For models that support upscaling through custom endpoints
+            # This would typically be handled by a Replicate or custom provider
+            upscale_via_provider
+          end
+        end
+
+        def upscale_via_provider
+          # Attempt to use the model through RubyLLM's paint with upscale mode
+          # This is a fallback for when direct upscale isn't supported
+          RubyLLM.paint(
+            "Upscale this image",
+            model: resolve_model,
+            image: image,
+            upscale_factor: resolve_scale,
+            face_enhance: resolve_face_enhance,
+            denoise_strength: resolve_denoise_strength,
+            **build_upscale_options
+          )
+        end
+
+        def build_upscale_options
+          opts = {}
+          opts[:face_enhance] = resolve_face_enhance if resolve_face_enhance
+          opts[:denoise_strength] = resolve_denoise_strength if resolve_denoise_strength
+          opts[:assume_model_exists] = true if options[:assume_model_exists]
+          opts
+        end
+
+        def build_result(image:, started_at:, completed_at:)
+          # Calculate output size based on scale
+          output_size = calculate_output_size
+
+          ImageUpscaleResult.new(
+            image: image,
+            source_image: self.image,
+            model_id: resolve_model,
+            scale: resolve_scale,
+            output_size: output_size,
+            face_enhance: resolve_face_enhance,
+            started_at: started_at,
+            completed_at: completed_at,
+            tenant_id: @tenant_id,
+            upscaler_class: self.class.name
+          )
+        end
+
+        def build_error_result(error, started_at)
+          ImageUpscaleResult.new(
+            image: nil,
+            source_image: self.image,
+            model_id: resolve_model,
+            scale: resolve_scale,
+            output_size: nil,
+            face_enhance: resolve_face_enhance,
+            started_at: started_at,
+            completed_at: Time.current,
+            tenant_id: @tenant_id,
+            upscaler_class: self.class.name,
+            error_class: error.class.name,
+            error_message: error.message
+          )
+        end
+
+        def calculate_output_size
+          input_size = get_input_image_size
+          return nil unless input_size
+
+          width, height = input_size
+          scale = resolve_scale
+          "#{width * scale}x#{height * scale}"
+        end
+
+        def get_input_image_size
+          return nil unless image.is_a?(String) && File.exist?(image)
+
+          # Try to get image dimensions
+          # This requires an image processing library like MiniMagick or ImageMagick
+          if defined?(MiniMagick)
+            img = MiniMagick::Image.open(image)
+            [img.width, img.height]
+          elsif defined?(Vips)
+            img = Vips::Image.new_from_file(image)
+            [img.width, img.height]
+          else
+            nil
+          end
+        rescue StandardError
+          nil
+        end
+
+        # Resolution methods
+
+        def resolve_scale
+          options[:scale] || self.class.scale
+        end
+
+        def resolve_face_enhance
+          options.fetch(:face_enhance, self.class.face_enhance)
+        end
+
+        def resolve_denoise_strength
+          options[:denoise_strength] || self.class.denoise_strength
+        end
+
+        # Cache key components
+        def cache_key_components
+          [
+            "image_upscaler",
+            self.class.name,
+            self.class.version,
+            resolve_model,
+            resolve_scale.to_s,
+            resolve_face_enhance.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)
+          {
+            scale: result.scale,
+            output_size: result.output_size,
+            face_enhance: result.face_enhance
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require_relative "upscaler/dsl"
+require_relative "upscaler/execution"
+
+module RubyLLM
+  module Agents
+    # Image upscaler for resolution enhancement
+    #
+    # Increases the resolution of images using AI upscaling models.
+    # Supports 2x, 4x, and 8x upscaling with optional face enhancement.
+    #
+    # @example Basic usage
+    #   result = RubyLLM::Agents::ImageUpscaler.call(image: "path/to/low_res.jpg")
+    #   result.url # => "https://..." (high resolution version)
+    #
+    # @example Custom upscaler class
+    #   class PhotoUpscaler < RubyLLM::Agents::ImageUpscaler
+    #     model "real-esrgan"
+    #     scale 4
+    #     face_enhance true
+    #
+    #     description "Upscales photos with face enhancement"
+    #   end
+    #
+    #   result = PhotoUpscaler.call(image: portrait_photo)
+    #   result.size # => "4096x4096" (if input was 1024x1024)
+    #
+    class ImageUpscaler
+      extend DSL
+      include Execution
+
+      class << self
+        # Execute image upscaling
+        #
+        # @param image [String, IO] Path, URL, or IO object of the source image
+        # @param options [Hash] Additional options (model, scale, etc.)
+        # @return [ImageUpscaleResult] The result containing upscaled image
+        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(:@scale, @scale)
+          subclass.instance_variable_set(:@face_enhance, @face_enhance)
+          subclass.instance_variable_set(:@denoise_strength, @denoise_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 upscaler 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] :scale Upscale factor (2, 4, or 8)
+      # @option options [Boolean] :face_enhance Enable face enhancement
+      # @option options [Float] :denoise_strength Denoising strength (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 upscaling
+      #
+      # @return [ImageUpscaleResult] The result containing upscaled image
+      def call
+        execute
+      end
+    end
+  end
+end