ruby_llm-agents 0.5.0 → 1.0.0

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

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+require "digest"
+require_relative "../concerns/image_operation_execution"
+
+module RubyLLM
+  module Agents
+    class ImageEditor
+      # Execution logic for image editors
+      #
+      # Handles image/mask validation, content policy checks,
+      # budget tracking, caching, image editing, and result building.
+      #
+      module Execution
+        include Concerns::ImageOperationExecution
+
+        # Execute the image editing pipeline
+        #
+        # @return [ImageEditResult] The result containing edited 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(ImageEditResult) if cache_enabled?
+          return cached if cached
+
+          # Edit image(s)
+          edited_images = edit_images
+
+          # Build result
+          result = build_result(
+            images: edited_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_edit"
+        end
+
+        def validate_inputs!
+          raise ArgumentError, "Image cannot be blank" if image.nil?
+          raise ArgumentError, "Mask cannot be blank" if mask.nil?
+          raise ArgumentError, "Prompt cannot be blank" if prompt.nil? || prompt.strip.empty?
+
+          # Validate image exists if it's a path
+          validate_file_exists!(image, "Image")
+          validate_file_exists!(mask, "Mask")
+
+          # 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_file_exists!(file, name)
+          return unless file.is_a?(String) && !file.start_with?("http")
+
+          unless File.exist?(file)
+            raise ArgumentError, "#{name} file does not exist: #{file}"
+          end
+        end
+
+        def validate_content_policy!
+          policy = self.class.content_policy
+          return if policy == :none || policy == :standard
+
+          ImageGenerator::ContentPolicy.validate!(prompt, policy)
+        end
+
+        def edit_images
+          count = resolve_count
+
+          Array.new(count) do
+            edit_single_image
+          end
+        end
+
+        def edit_single_image
+          # Use RubyLLM's edit endpoint if available
+          if RubyLLM.respond_to?(:edit_image)
+            RubyLLM.edit_image(
+              image: image,
+              mask: mask,
+              prompt: prompt,
+              model: resolve_model,
+              size: resolve_size,
+              **build_edit_options
+            )
+          else
+            # Fallback: Some providers may use paint with mask support
+            RubyLLM.paint(
+              prompt,
+              model: resolve_model,
+              size: resolve_size,
+              image: image,
+              mask: mask,
+              **build_edit_options
+            )
+          end
+        end
+
+        def build_edit_options
+          opts = {}
+          opts[:assume_model_exists] = true if options[:assume_model_exists]
+          opts
+        end
+
+        def build_result(images:, started_at:, completed_at:)
+          ImageEditResult.new(
+            images: images,
+            source_image: image,
+            mask: mask,
+            prompt: prompt,
+            model_id: resolve_model,
+            size: resolve_size,
+            started_at: started_at,
+            completed_at: completed_at,
+            tenant_id: @tenant_id,
+            editor_class: self.class.name
+          )
+        end
+
+        def build_error_result(error, started_at)
+          ImageEditResult.new(
+            images: [],
+            source_image: image,
+            mask: mask,
+            prompt: prompt,
+            model_id: resolve_model,
+            size: resolve_size,
+            started_at: started_at,
+            completed_at: Time.current,
+            tenant_id: @tenant_id,
+            editor_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_count
+          options[:count] || 1
+        end
+
+        # Cache key components
+        def cache_key_components
+          [
+            "image_editor",
+            self.class.name,
+            self.class.version,
+            resolve_model,
+            resolve_size,
+            Digest::SHA256.hexdigest(prompt),
+            Digest::SHA256.hexdigest(image_digest(image)),
+            Digest::SHA256.hexdigest(image_digest(mask))
+          ]
+        end
+
+        def image_digest(file)
+          if file.is_a?(String) && File.exist?(file)
+            File.read(file)
+          elsif file.respond_to?(:read)
+            content = file.read
+            file.rewind if file.respond_to?(:rewind)
+            content
+          else
+            file.to_s
+          end
+        end
+
+        def build_execution_metadata(result)
+          {
+            count: result.count,
+            size: result.size,
+            prompt_length: prompt.length
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require_relative "editor/dsl"
+require_relative "editor/execution"
+
+module RubyLLM
+  module Agents
+    # Image editor for inpainting and image editing
+    #
+    # Allows editing specific regions of an image using a mask.
+    # The mask indicates which parts of the image should be modified.
+    # White areas in the mask are edited, black areas are preserved.
+    #
+    # @example Basic usage
+    #   result = RubyLLM::Agents::ImageEditor.call(
+    #     image: "path/to/image.png",
+    #     mask: "path/to/mask.png",
+    #     prompt: "Replace with a red car"
+    #   )
+    #   result.url # => "https://..."
+    #
+    # @example Custom editor class
+    #   class ProductEditor < RubyLLM::Agents::ImageEditor
+    #     model "gpt-image-1"
+    #     size "1024x1024"
+    #
+    #     description "Edits product images"
+    #   end
+    #
+    #   result = ProductEditor.call(
+    #     image: product_photo,
+    #     mask: background_mask,
+    #     prompt: "Professional studio background"
+    #   )
+    #
+    class ImageEditor
+      extend DSL
+      include Execution
+
+      class << self
+        # Execute image editing with the given source image, mask, and prompt
+        #
+        # @param image [String, IO] Path, URL, or IO object of the source image
+        # @param mask [String, IO] Path, URL, or IO object of the mask image
+        # @param prompt [String] Description of the desired edit
+        # @param options [Hash] Additional options (model, size, etc.)
+        # @return [ImageEditResult] The result containing edited image
+        def call(image:, mask:, prompt:, **options)
+          new(image: image, mask: mask, 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(:@version, @version)
+          subclass.instance_variable_set(:@description, @description)
+          subclass.instance_variable_set(:@cache_ttl, @cache_ttl)
+          subclass.instance_variable_set(:@content_policy, @content_policy)
+        end
+      end
+
+      attr_reader :image, :mask, :prompt, :options, :tenant_id
+
+      # Initialize a new image editor instance
+      #
+      # @param image [String, IO] Source image (path, URL, or IO object)
+      # @param mask [String, IO] Mask image (path, URL, or IO object)
+      # @param prompt [String] Description of the desired edit
+      # @param options [Hash] Additional options
+      # @option options [String] :model Model to use
+      # @option options [String] :size Output image size
+      # @option options [Integer] :count Number of edits to generate
+      # @option options [Object] :tenant Tenant for multi-tenancy
+      def initialize(image:, mask:, prompt:, **options)
+        @image = image
+        @mask = mask
+        @prompt = prompt
+        @options = options
+        @tenant_id = nil
+      end
+
+      # Execute the image edit
+      #
+      # @return [ImageEditResult] The result containing edited image
+      def call
+        execute
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/image/generator/active_storage_support.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    class ImageGenerator
+      # ActiveStorage integration for image generators
+      #
+      # Provides convenience methods for generating images and directly
+      # attaching them to ActiveStorage attachments.
+      #
+      # @example Attaching to a model
+      #   class Product < ApplicationRecord
+      #     has_one_attached :hero_image
+      #   end
+      #
+      #   class ProductImageGenerator < RubyLLM::Agents::ImageGenerator
+      #     include RubyLLM::Agents::ImageGenerator::ActiveStorageSupport
+      #
+      #     model "gpt-image-1"
+      #     size "1024x1024"
+      #   end
+      #
+      #   product = Product.find(1)
+      #   result = ProductImageGenerator.generate_and_attach(
+      #     prompt: "Professional product photo of a red sneaker",
+      #     record: product,
+      #     attachment_name: :hero_image
+      #   )
+      #
+      module ActiveStorageSupport
+        extend ActiveSupport::Concern
+
+        class_methods do
+          # Generate an image and attach it to a record
+          #
+          # @param prompt [String] The generation prompt
+          # @param record [ActiveRecord::Base] The record to attach to
+          # @param attachment_name [Symbol] Name of the attachment (e.g., :avatar)
+          # @param options [Hash] Additional options for generation
+          # @return [ImageGenerationResult] The generation result
+          def generate_and_attach(prompt:, record:, attachment_name:, **options)
+            result = call(prompt: prompt, **options)
+
+            return result unless result.success?
+
+            attach_result_to_record(result, record, attachment_name, options)
+
+            result
+          end
+
+          # Generate multiple images and attach them to a has_many_attached
+          #
+          # @param prompt [String] The generation prompt
+          # @param record [ActiveRecord::Base] The record to attach to
+          # @param attachment_name [Symbol] Name of the attachment (e.g., :photos)
+          # @param count [Integer] Number of images to generate
+          # @param options [Hash] Additional options for generation
+          # @return [ImageGenerationResult] The generation result
+          def generate_and_attach_multiple(prompt:, record:, attachment_name:, count: 1, **options)
+            result = call(prompt: prompt, count: count, **options)
+
+            return result unless result.success?
+
+            attachment = record.public_send(attachment_name)
+
+            result.images.each_with_index do |image, idx|
+              attach_image_to_collection(image, attachment, idx, result)
+            end
+
+            result
+          end
+
+          private
+
+          def attach_result_to_record(result, record, attachment_name, options)
+            attachment = record.public_send(attachment_name)
+            filename = options[:filename] || generate_filename
+
+            if result.base64?
+              attachment.attach(
+                io: StringIO.new(result.to_blob),
+                filename: filename,
+                content_type: result.mime_type || "image/png"
+              )
+            else
+              attach_from_url(attachment, result.url, filename)
+            end
+          end
+
+          def attach_image_to_collection(image, attachment, index, result)
+            filename = generate_filename(index)
+
+            if image.respond_to?(:data) && image.data
+              attachment.attach(
+                io: StringIO.new(image.to_blob),
+                filename: filename,
+                content_type: image.mime_type || "image/png"
+              )
+            elsif image.respond_to?(:url) && image.url
+              attach_from_url(attachment, image.url, filename)
+            end
+          end
+
+          def attach_from_url(attachment, url, filename)
+            require "open-uri"
+
+            downloaded = URI.parse(url).open
+            attachment.attach(
+              io: downloaded,
+              filename: filename,
+              content_type: "image/png"
+            )
+          end
+
+          def generate_filename(index = nil)
+            timestamp = Time.current.to_i
+            if index
+              "generated_#{timestamp}_#{index + 1}.png"
+            else
+              "generated_#{timestamp}.png"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/image/generator/content_policy.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    class ImageGenerator
+      # Content policy enforcement for image generation prompts
+      #
+      # Validates prompts against configurable policy levels to prevent
+      # generation of inappropriate content.
+      #
+      # @example Using content policy in a generator
+      #   class SafeImageGenerator < RubyLLM::Agents::ImageGenerator
+      #     content_policy :strict
+      #   end
+      #
+      # @example Manual validation
+      #   ContentPolicy.validate!("A beautiful sunset", :moderate)
+      #   # => nil (passes)
+      #
+      #   ContentPolicy.validate!("Violent scene", :strict)
+      #   # => raises ContentPolicyViolation
+      #
+      module ContentPolicy
+        # Blocked patterns by policy level
+        #
+        # :strict   - Blocks violence, nudity, hate, weapons, drugs
+        # :moderate - Blocks explicit content, gore, hate speech
+        # :standard - No blocking (relies on model's built-in filters)
+        # :none     - No validation at all
+        #
+        BLOCKED_PATTERNS = {
+          strict: [
+            /\b(violence|violent|gore|blood|death|kill|murder)\b/i,
+            /\b(nude|naked|nsfw|explicit|sexual|porn)\b/i,
+            /\b(hate|racist|discrimination|slur)\b/i,
+            /\b(weapon|gun|knife|bomb|explosive)\b/i,
+            /\b(drug|cocaine|heroin|meth)\b/i
+          ],
+          moderate: [
+            /\b(nude|naked|nsfw|explicit|sexual|porn)\b/i,
+            /\b(gore|graphic.?violence)\b/i,
+            /\b(hate.?speech|slur)\b/i
+          ],
+          standard: [],
+          none: []
+        }.freeze
+
+        class << self
+          # Validate a prompt against a policy level
+          #
+          # @param prompt [String] The prompt to validate
+          # @param level [Symbol] Policy level (:none, :standard, :moderate, :strict)
+          # @raise [ContentPolicyViolation] If prompt violates the policy
+          def validate!(prompt, level)
+            return if level == :none || level.nil?
+
+            patterns = BLOCKED_PATTERNS[level.to_sym] || BLOCKED_PATTERNS[:standard]
+
+            patterns.each do |pattern|
+              if prompt.match?(pattern)
+                raise ContentPolicyViolation,
+                      "Prompt contains content blocked by #{level} policy"
+              end
+            end
+          end
+
+          # Check if a prompt passes the policy (non-raising version)
+          #
+          # @param prompt [String] The prompt to check
+          # @param level [Symbol] Policy level
+          # @return [Boolean] true if prompt passes
+          def valid?(prompt, level)
+            validate!(prompt, level)
+            true
+          rescue ContentPolicyViolation
+            false
+          end
+
+          # Get the matched pattern for a violation (for debugging)
+          #
+          # @param prompt [String] The prompt to check
+          # @param level [Symbol] Policy level
+          # @return [Regexp, nil] The matched pattern or nil
+          def matched_pattern(prompt, level)
+            patterns = BLOCKED_PATTERNS[level.to_sym] || []
+            patterns.find { |pattern| prompt.match?(pattern) }
+          end
+        end
+      end
+
+      # Exception raised when a prompt violates content policy
+      class ContentPolicyViolation < StandardError; end
+    end
+  end
+end