ruby_llm-agents 0.5.0 → 1.0.0.beta.1

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

@@ -0,0 +1,382 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module RubyLLM
+  module Agents
+    class ImagePipeline
+      # Execution logic for image pipelines
+      #
+      # Handles step execution, context passing between steps,
+      # error handling, caching, and execution tracking.
+      #
+      module Execution
+        private
+
+        def execute
+          @started_at = Time.current
+
+          resolve_tenant_context!
+          check_budget! if budget_tracking_enabled?
+
+          # Check cache for deterministic pipelines
+          if cache_enabled?
+            cached = check_cache
+            return cached if cached
+          end
+
+          # Run before callbacks
+          run_callbacks(:before)
+
+          # Execute pipeline steps
+          current_image = options[:image]
+          @step_results = []
+
+          self.class.steps.each do |step_def|
+            # Check if step should run
+            next unless should_run_step?(step_def)
+
+            result = execute_step(step_def, current_image)
+            @step_results << { name: step_def[:name], type: step_def[:type], result: result }
+
+            # Update context with result
+            @context[step_def[:name]] = result
+
+            if result.error?
+              break if self.class.stop_on_error?
+            else
+              # Pass image to next step (except for analyze steps which don't produce images)
+              current_image = extract_image_from_result(result) unless step_def[:type] == :analyzer
+            end
+          end
+
+          # Build result
+          result = build_result
+
+          # Run after callbacks
+          run_callbacks(:after, result)
+
+          # Cache successful results
+          write_cache(result) if cache_enabled? && result.success?
+
+          # Track execution
+          record_execution(result) if execution_tracking_enabled?
+
+          result
+        rescue StandardError => e
+          record_failed_execution(e) if execution_tracking_enabled?
+          build_error_result(e)
+        end
+
+        def should_run_step?(step_def)
+          config = step_def[:config]
+
+          # Check :if condition
+          if config[:if]
+            return false unless evaluate_condition(config[:if])
+          end
+
+          # Check :unless condition
+          if config[:unless]
+            return false if evaluate_condition(config[:unless])
+          end
+
+          true
+        end
+
+        def evaluate_condition(condition)
+          case condition
+          when Proc
+            condition.call(@context)
+          when Symbol
+            respond_to?(condition, true) ? send(condition) : @context[condition]
+          else
+            condition
+          end
+        end
+
+        def execute_step(step_def, current_image)
+          step_type = step_def[:type]
+          step_config = step_def[:config]
+          step_class = step_config[step_type]
+
+          # Build options for the step (exclude meta options)
+          step_options = step_config.except(:if, :unless, step_type)
+          step_options[:tenant] = options[:tenant] if options[:tenant]
+
+          case step_type
+          when :generator
+            execute_generator(step_class, step_options)
+          when :variator
+            execute_variator(step_class, current_image, step_options)
+          when :editor
+            execute_editor(step_class, current_image, step_options)
+          when :transformer
+            execute_transformer(step_class, current_image, step_options)
+          when :upscaler
+            execute_upscaler(step_class, current_image, step_options)
+          when :analyzer
+            execute_analyzer(step_class, current_image, step_options)
+          when :remover
+            execute_remover(step_class, current_image, step_options)
+          else
+            raise ArgumentError, "Unknown step type: #{step_type}"
+          end
+        end
+
+        def execute_generator(step_class, step_options)
+          prompt = step_options.delete(:prompt) || options[:prompt]
+          raise ArgumentError, "Generator step requires a prompt" unless prompt
+
+          step_class.call(prompt: prompt, **step_options)
+        end
+
+        def execute_variator(step_class, image, step_options)
+          raise ArgumentError, "Variator step requires an input image" unless image
+
+          step_class.call(image: image, **step_options)
+        end
+
+        def execute_editor(step_class, image, step_options)
+          raise ArgumentError, "Editor step requires an input image" unless image
+
+          mask = step_options.delete(:mask) || options[:mask]
+          prompt = step_options.delete(:prompt) || options[:edit_prompt]
+          raise ArgumentError, "Editor step requires a mask and prompt" unless mask && prompt
+
+          step_class.call(image: image, mask: mask, prompt: prompt, **step_options)
+        end
+
+        def execute_transformer(step_class, image, step_options)
+          raise ArgumentError, "Transformer step requires an input image" unless image
+
+          prompt = step_options.delete(:prompt) || options[:transform_prompt]
+          raise ArgumentError, "Transformer step requires a prompt" unless prompt
+
+          step_class.call(image: image, prompt: prompt, **step_options)
+        end
+
+        def execute_upscaler(step_class, image, step_options)
+          raise ArgumentError, "Upscaler step requires an input image" unless image
+
+          step_class.call(image: image, **step_options)
+        end
+
+        def execute_analyzer(step_class, image, step_options)
+          raise ArgumentError, "Analyzer step requires an input image" unless image
+
+          step_class.call(image: image, **step_options)
+        end
+
+        def execute_remover(step_class, image, step_options)
+          raise ArgumentError, "Remover step requires an input image" unless image
+
+          step_class.call(image: image, **step_options)
+        end
+
+        def extract_image_from_result(result)
+          # Try common methods for getting image data
+          if result.respond_to?(:url) && result.url
+            result.url
+          elsif result.respond_to?(:data) && result.data
+            result.data
+          elsif result.respond_to?(:to_blob)
+            result.to_blob
+          else
+            result
+          end
+        end
+
+        def build_result
+          ImagePipelineResult.new(
+            step_results: @step_results,
+            started_at: @started_at,
+            completed_at: Time.current,
+            tenant_id: @tenant_id,
+            pipeline_class: self.class.name,
+            context: @context
+          )
+        end
+
+        def build_error_result(error)
+          ImagePipelineResult.new(
+            step_results: @step_results || [],
+            started_at: @started_at || Time.current,
+            completed_at: Time.current,
+            tenant_id: @tenant_id,
+            pipeline_class: self.class.name,
+            context: @context || {},
+            error_class: error.class.name,
+            error_message: error.message
+          )
+        end
+
+        # Tenant resolution
+
+        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
+
+        # Budget tracking
+
+        def budget_tracking_enabled?
+          config.budgets_enabled? && defined?(BudgetTracker)
+        end
+
+        def check_budget!
+          BudgetTracker.check!(
+            agent_type: self.class.name,
+            tenant_id: @tenant_id,
+            execution_type: "image_pipeline"
+          )
+        end
+
+        # Caching
+
+        def cache_enabled?
+          self.class.cache_enabled? && !options[:skip_cache]
+        end
+
+        def cache_key
+          components = [
+            "ruby_llm_agents",
+            "image_pipeline",
+            self.class.name,
+            self.class.version,
+            Digest::SHA256.hexdigest(cache_key_input)
+          ]
+          components.join(":")
+        end
+
+        def cache_key_input
+          # Include relevant options and step configuration
+          {
+            prompt: options[:prompt],
+            image: options[:image].to_s,
+            steps: self.class.steps.map { |s| [s[:name], s[:type]] }
+          }.to_json
+        end
+
+        def check_cache
+          return nil unless defined?(Rails) && Rails.cache
+
+          cached_data = Rails.cache.read(cache_key)
+          return nil unless cached_data
+
+          ImagePipelineResult.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
+
+        # Callbacks
+
+        def run_callbacks(type, *args)
+          callbacks = self.class.callbacks[type] || []
+
+          callbacks.each do |callback|
+            case callback
+            when Symbol
+              send(callback, *args)
+            when Proc
+              instance_exec(*args, &callback)
+            end
+          end
+        end
+
+        # Execution tracking
+
+        def execution_tracking_enabled?
+          config.track_image_generation
+        end
+
+        def record_execution(result)
+          return unless defined?(RubyLLM::Agents::Execution)
+
+          execution_data = {
+            agent_type: self.class.name,
+            tenant_id: @tenant_id,
+            execution_type: "image_pipeline",
+            model_id: result.primary_model_id,
+            status: result.success? ? "success" : "error",
+            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: {
+              step_count: result.step_count,
+              successful_steps: result.successful_step_count,
+              failed_steps: result.failed_step_count
+            }
+          }
+
+          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 pipeline execution: #{e.message}") if defined?(Rails)
+        end
+
+        def record_failed_execution(error)
+          return unless defined?(RubyLLM::Agents::Execution)
+
+          execution_data = {
+            agent_type: self.class.name,
+            tenant_id: @tenant_id,
+            execution_type: "image_pipeline",
+            model_id: nil,
+            status: "error",
+            input_tokens: 0,
+            output_tokens: 0,
+            total_cost: calculate_partial_cost,
+            duration_ms: ((@started_at ? (Time.current - @started_at) : 0) * 1000).round,
+            started_at: @started_at || Time.current,
+            completed_at: Time.current,
+            error_class: error.class.name,
+            error_message: error.message.truncate(1000),
+            metadata: {
+              step_count: self.class.steps.size,
+              completed_steps: @step_results&.size || 0
+            }
+          }
+
+          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 pipeline execution: #{e.message}") if defined?(Rails)
+        end
+
+        def calculate_partial_cost
+          return 0 unless @step_results
+
+          @step_results.sum do |step|
+            step[:result]&.total_cost || 0
+          end
+        end
+
+        def config
+          RubyLLM::Agents.configuration
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require_relative "pipeline/dsl"
+require_relative "pipeline/execution"
+
+module RubyLLM
+  module Agents
+    # Image pipeline for chaining multiple image operations
+    #
+    # Orchestrates complex image workflows by chaining generators,
+    # transformers, upscalers, analyzers, and other image operations
+    # into a single pipeline with aggregated results and costs.
+    #
+    # @example Basic pipeline
+    #   class ProductPipeline < RubyLLM::Agents::ImagePipeline
+    #     step :generate, generator: ProductGenerator
+    #     step :upscale, upscaler: PhotoUpscaler
+    #     step :remove_background, remover: BackgroundRemover
+    #   end
+    #
+    #   result = ProductPipeline.call(prompt: "Professional laptop photo")
+    #   result.final_image   # => The processed image
+    #   result.total_cost    # => Combined cost of all steps
+    #
+    # @example Pipeline with analysis
+    #   class AnalysisPipeline < RubyLLM::Agents::ImagePipeline
+    #     step :generate, generator: ProductGenerator
+    #     step :analyze, analyzer: ProductAnalyzer
+    #
+    #     description "Generates and analyzes product images"
+    #   end
+    #
+    #   result = AnalysisPipeline.call(prompt: "Wireless earbuds")
+    #   result.analysis   # => ImageAnalysisResult from analyzer step
+    #
+    # @example Conditional pipeline
+    #   class SmartPipeline < RubyLLM::Agents::ImagePipeline
+    #     step :generate, generator: ProductGenerator
+    #     step :upscale, upscaler: PhotoUpscaler, if: ->(ctx) { ctx[:upscale] }
+    #     step :remove_background, remover: BackgroundRemover, if: ->(ctx) { ctx[:transparent] }
+    #   end
+    #
+    #   result = SmartPipeline.call(prompt: "...", upscale: true, transparent: false)
+    #
+    class ImagePipeline
+      extend DSL
+      include Execution
+
+      class << self
+        # Execute pipeline with the given options
+        #
+        # @param options [Hash] Pipeline options
+        # @option options [String] :prompt Prompt for generation steps
+        # @option options [String, IO] :image Input image for non-generation pipelines
+        # @option options [Object] :tenant Tenant for multi-tenancy
+        # @return [ImagePipelineResult] The combined result of all steps
+        def call(**options)
+          new(**options).call
+        end
+
+        # Ensure subclasses inherit DSL settings and steps
+        def inherited(subclass)
+          super
+          # Copy steps to subclass
+          subclass.instance_variable_set(:@steps, @steps&.dup || [])
+          subclass.instance_variable_set(:@callbacks, @callbacks&.dup || { before: [], after: [] })
+          subclass.instance_variable_set(:@version, @version)
+          subclass.instance_variable_set(:@description, @description)
+          subclass.instance_variable_set(:@cache_ttl, @cache_ttl)
+          subclass.instance_variable_set(:@stop_on_error, @stop_on_error)
+        end
+      end
+
+      attr_reader :options, :tenant_id, :step_results, :context
+
+      # Initialize a new pipeline instance
+      #
+      # @param options [Hash] Pipeline options
+      # @option options [String] :prompt Prompt for generation steps
+      # @option options [String, IO] :image Input image
+      # @option options [Object] :tenant Tenant for multi-tenancy
+      def initialize(**options)
+        @options = options
+        @tenant_id = nil
+        @step_results = []
+        @context = options.dup
+      end
+
+      # Execute the pipeline
+      #
+      # @return [ImagePipelineResult] The combined result of all steps
+      def call
+        execute
+      end
+    end
+  end
+end

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

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require_relative "../concerns/image_operation_dsl"
+require_relative "../generator/content_policy"
+
+module RubyLLM
+  module Agents
+    class ImageTransformer
+      # DSL for configuring image transformers
+      #
+      # Provides class-level methods to configure model, strength,
+      # and other image transformation parameters.
+      #
+      # @example
+      #   class AnimeTransformer < RubyLLM::Agents::ImageTransformer
+      #     model "sdxl"
+      #     strength 0.8
+      #     size "1024x1024"
+      #     template "anime style, {prompt}"
+      #   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 transformation strength
+        #
+        # Controls how much the image is transformed (0.0-1.0).
+        # Lower values preserve more of the original image.
+        # Higher values allow more creative freedom.
+        #
+        # @param value [Float, nil] Strength (0.0-1.0)
+        # @return [Float] The transformation strength
+        def strength(value = nil)
+          if value
+            unless value.is_a?(Numeric) && value.between?(0.0, 1.0)
+              raise ArgumentError, "Strength must be between 0.0 and 1.0"
+            end
+            @strength = value.to_f
+          else
+            @strength || inherited_or_default(:strength, 0.75)
+          end
+        end
+
+        # Set or get whether to preserve composition
+        #
+        # When true, maintains the overall structure and layout
+        # of the original image.
+        #
+        # @param value [Boolean, nil] Preserve composition flag
+        # @return [Boolean] Whether to preserve composition
+        def preserve_composition(value = nil)
+          if value.nil?
+            result = @preserve_composition
+            result = inherited_or_default(:preserve_composition, true) if result.nil?
+            result
+          else
+            @preserve_composition = value
+          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
+
+        # Set a prompt template (use {prompt} as placeholder)
+        #
+        # @param value [String, nil] Template string
+        # @return [String, nil] The template
+        def template(value = nil)
+          if value
+            @template_string = value
+          else
+            @template_string || inherited_or_default(:template_string, nil)
+          end
+        end
+
+        # Get the template string
+        #
+        # @return [String, nil] The template string
+        def template_string
+          @template_string || inherited_or_default(:template_string, nil)
+        end
+
+        # Set or get negative prompt
+        #
+        # @param value [String, nil] Negative prompt text
+        # @return [String, nil] The negative prompt
+        def negative_prompt(value = nil)
+          if value
+            @negative_prompt = value
+          else
+            @negative_prompt || inherited_or_default(:negative_prompt, nil)
+          end
+        end
+
+        # Set or get guidance scale (CFG scale)
+        #
+        # @param value [Float, nil] Guidance scale
+        # @return [Float, nil] The guidance scale
+        def guidance_scale(value = nil)
+          if value
+            @guidance_scale = value
+          else
+            @guidance_scale || inherited_or_default(:guidance_scale, nil)
+          end
+        end
+
+        # Set or get number of inference steps
+        #
+        # @param value [Integer, nil] Number of steps
+        # @return [Integer, nil] The steps
+        def steps(value = nil)
+          if value
+            @steps = value
+          else
+            @steps || inherited_or_default(:steps, nil)
+          end
+        end
+
+        private
+
+        def default_model
+          config.default_transformer_model || "sdxl"
+        end
+      end
+    end
+  end
+end