ruby_llm-agents 0.5.0 → 1.0.0

data/lib/ruby_llm/agents/results/image_upscale_result.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    # Result wrapper for image upscaling operations
+    #
+    # Provides a consistent interface for accessing upscaled images,
+    # metadata, timing, and cost information.
+    #
+    # @example Accessing upscaled image
+    #   result = ImageUpscaler.call(image: "low_res.jpg", scale: 4)
+    #   result.url          # => "https://..."
+    #   result.scale        # => 4
+    #   result.output_size  # => "4096x4096"
+    #   result.success?     # => true
+    #
+    class ImageUpscaleResult
+      attr_reader :image, :source_image, :model_id, :scale, :output_size, :face_enhance,
+                  :started_at, :completed_at, :tenant_id, :upscaler_class,
+                  :error_class, :error_message
+
+      # Initialize a new result
+      #
+      # @param image [Object] The upscaled image object
+      # @param source_image [String] The original source image
+      # @param model_id [String] Model used for upscaling
+      # @param scale [Integer] Upscale factor used
+      # @param output_size [String] Output image dimensions
+      # @param face_enhance [Boolean] Whether face enhancement was used
+      # @param started_at [Time] When upscaling started
+      # @param completed_at [Time] When upscaling completed
+      # @param tenant_id [String, nil] Tenant identifier
+      # @param upscaler_class [String] Name of the upscaler class
+      # @param error_class [String, nil] Error class name if failed
+      # @param error_message [String, nil] Error message if failed
+      def initialize(image:, source_image:, model_id:, scale:, output_size:, face_enhance:,
+                     started_at:, completed_at:, tenant_id:, upscaler_class:,
+                     error_class: nil, error_message: nil)
+        @image = image
+        @source_image = source_image
+        @model_id = model_id
+        @scale = scale
+        @output_size = output_size
+        @face_enhance = face_enhance
+        @started_at = started_at
+        @completed_at = completed_at
+        @tenant_id = tenant_id
+        @upscaler_class = upscaler_class
+        @error_class = error_class
+        @error_message = error_message
+      end
+
+      # Status helpers
+
+      def success?
+        error_class.nil? && !image.nil?
+      end
+
+      def error?
+        !success?
+      end
+
+      # Always single image for upscaling
+      def single?
+        true
+      end
+
+      def batch?
+        false
+      end
+
+      # Image access
+
+      def url
+        image&.url
+      end
+
+      def urls
+        success? ? [url].compact : []
+      end
+
+      def data
+        image&.data
+      end
+
+      def datas
+        success? ? [data].compact : []
+      end
+
+      def base64?
+        image&.base64? || false
+      end
+
+      def mime_type
+        image&.mime_type
+      end
+
+      # Count (always 1 for upscaling)
+
+      def count
+        success? ? 1 : 0
+      end
+
+      # Size helpers
+
+      def size
+        output_size
+      end
+
+      def output_width
+        return nil unless output_size
+        output_size.split("x").first.to_i
+      end
+
+      def output_height
+        return nil unless output_size
+        output_size.split("x").last.to_i
+      end
+
+      # Timing
+
+      def duration_ms
+        return 0 unless started_at && completed_at
+        ((completed_at - started_at) * 1000).round
+      end
+
+      # Cost estimation
+
+      def total_cost
+        return 0 if error?
+
+        # Upscaling typically has fixed per-image cost
+        ImageGenerator::Pricing.calculate_cost(
+          model_id: model_id,
+          count: 1
+        )
+      end
+
+      # File operations
+
+      def save(path)
+        raise "No image to save" unless image
+        image.save(path)
+      end
+
+      def to_blob
+        image&.to_blob
+      end
+
+      def blobs
+        success? ? [to_blob].compact : []
+      end
+
+      # Serialization
+
+      def to_h
+        {
+          success: success?,
+          url: url,
+          base64: base64?,
+          mime_type: mime_type,
+          source_image: source_image,
+          model_id: model_id,
+          scale: scale,
+          output_size: output_size,
+          face_enhance: face_enhance,
+          total_cost: total_cost,
+          duration_ms: duration_ms,
+          started_at: started_at&.iso8601,
+          completed_at: completed_at&.iso8601,
+          tenant_id: tenant_id,
+          upscaler_class: upscaler_class,
+          error_class: error_class,
+          error_message: error_message
+        }
+      end
+
+      # Caching
+
+      def to_cache
+        {
+          url: url,
+          data: data,
+          mime_type: mime_type,
+          model_id: model_id,
+          scale: scale,
+          output_size: output_size,
+          total_cost: total_cost,
+          cached_at: Time.current.iso8601
+        }
+      end
+
+      def self.from_cache(data)
+        CachedImageUpscaleResult.new(data)
+      end
+    end
+
+    # Lightweight result for cached upscales
+    class CachedImageUpscaleResult
+      attr_reader :url, :data, :mime_type, :model_id, :scale, :output_size,
+                  :total_cost, :cached_at
+
+      def initialize(data)
+        @url = data[:url]
+        @data = data[:data]
+        @mime_type = data[:mime_type]
+        @model_id = data[:model_id]
+        @scale = data[:scale]
+        @output_size = data[:output_size]
+        @total_cost = data[:total_cost]
+        @cached_at = data[:cached_at]
+      end
+
+      def success?
+        !url.nil? || !data.nil?
+      end
+
+      def error?
+        !success?
+      end
+
+      def cached?
+        true
+      end
+
+      def urls
+        success? ? [url].compact : []
+      end
+
+      def datas
+        success? ? [data].compact : []
+      end
+
+      def base64?
+        !data.nil?
+      end
+
+      def count
+        success? ? 1 : 0
+      end
+
+      def single?
+        true
+      end
+
+      def batch?
+        false
+      end
+
+      def size
+        output_size
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/results/image_variation_result.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    # Result wrapper for image variation operations
+    #
+    # Provides a consistent interface for accessing variation images,
+    # metadata, timing, and cost information.
+    #
+    # @example Accessing variations
+    #   result = ImageVariator.call(image: "logo.png", count: 4)
+    #   result.urls      # => ["https://...", ...]
+    #   result.count     # => 4
+    #   result.success?  # => true
+    #
+    class ImageVariationResult
+      attr_reader :images, :source_image, :model_id, :size, :variation_strength,
+                  :started_at, :completed_at, :tenant_id, :variator_class,
+                  :error_class, :error_message
+
+      # Initialize a new result
+      #
+      # @param images [Array<Object>] Array of variation image objects
+      # @param source_image [String] The original source image
+      # @param model_id [String] Model used for variation
+      # @param size [String] Image size
+      # @param variation_strength [Float] Variation strength used
+      # @param started_at [Time] When variation started
+      # @param completed_at [Time] When variation completed
+      # @param tenant_id [String, nil] Tenant identifier
+      # @param variator_class [String] Name of the variator class
+      # @param error_class [String, nil] Error class name if failed
+      # @param error_message [String, nil] Error message if failed
+      def initialize(images:, source_image:, model_id:, size:, variation_strength:,
+                     started_at:, completed_at:, tenant_id:, variator_class:,
+                     error_class: nil, error_message: nil)
+        @images = images
+        @source_image = source_image
+        @model_id = model_id
+        @size = size
+        @variation_strength = variation_strength
+        @started_at = started_at
+        @completed_at = completed_at
+        @tenant_id = tenant_id
+        @variator_class = variator_class
+        @error_class = error_class
+        @error_message = error_message
+      end
+
+      # Status helpers
+
+      def success?
+        error_class.nil? && images.any?
+      end
+
+      def error?
+        !success?
+      end
+
+      def single?
+        count == 1
+      end
+
+      def batch?
+        count > 1
+      end
+
+      # Image access
+
+      def image
+        images.first
+      end
+
+      def url
+        image&.url
+      end
+
+      def urls
+        images.map(&:url).compact
+      end
+
+      def data
+        image&.data
+      end
+
+      def datas
+        images.map(&:data).compact
+      end
+
+      def base64?
+        image&.base64? || false
+      end
+
+      def mime_type
+        image&.mime_type
+      end
+
+      # Count
+
+      def count
+        images.size
+      end
+
+      # Timing
+
+      def duration_ms
+        return 0 unless started_at && completed_at
+        ((completed_at - started_at) * 1000).round
+      end
+
+      # Cost estimation
+
+      def total_cost
+        return 0 if error?
+
+        ImageGenerator::Pricing.calculate_cost(
+          model_id: model_id,
+          size: size,
+          count: count
+        )
+      end
+
+      # File operations
+
+      def save(path)
+        raise "No image to save" unless image
+        image.save(path)
+      end
+
+      def save_all(directory, prefix: "variation")
+        images.each_with_index do |img, idx|
+          filename = "#{prefix}_#{idx + 1}.png"
+          img.save(File.join(directory, filename))
+        end
+      end
+
+      def to_blob
+        image&.to_blob
+      end
+
+      def blobs
+        images.map(&:to_blob)
+      end
+
+      # Serialization
+
+      def to_h
+        {
+          success: success?,
+          count: count,
+          urls: urls,
+          base64: base64?,
+          mime_type: mime_type,
+          source_image: source_image,
+          model_id: model_id,
+          size: size,
+          variation_strength: variation_strength,
+          total_cost: total_cost,
+          duration_ms: duration_ms,
+          started_at: started_at&.iso8601,
+          completed_at: completed_at&.iso8601,
+          tenant_id: tenant_id,
+          variator_class: variator_class,
+          error_class: error_class,
+          error_message: error_message
+        }
+      end
+
+      # Caching
+
+      def to_cache
+        {
+          urls: urls,
+          datas: datas,
+          mime_type: mime_type,
+          model_id: model_id,
+          total_cost: total_cost,
+          cached_at: Time.current.iso8601
+        }
+      end
+
+      def self.from_cache(data)
+        CachedImageVariationResult.new(data)
+      end
+    end
+
+    # Lightweight result for cached variations
+    class CachedImageVariationResult
+      attr_reader :urls, :datas, :mime_type, :model_id, :total_cost, :cached_at
+
+      def initialize(data)
+        @urls = data[:urls] || []
+        @datas = data[:datas] || []
+        @mime_type = data[:mime_type]
+        @model_id = data[:model_id]
+        @total_cost = data[:total_cost]
+        @cached_at = data[:cached_at]
+      end
+
+      def success?
+        urls.any? || datas.any?
+      end
+
+      def error?
+        !success?
+      end
+
+      def cached?
+        true
+      end
+
+      def url
+        urls.first
+      end
+
+      def data
+        datas.first
+      end
+
+      def base64?
+        datas.any?
+      end
+
+      def count
+        [urls.size, datas.size].max
+      end
+
+      def single?
+        count == 1
+      end
+
+      def batch?
+        count > 1
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/results/moderation_result.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    # Wrapper for moderation results with threshold and category filtering
+    #
+    # Provides a filtered view of moderation results based on configured
+    # thresholds and category filters. The raw result is still accessible
+    # for full details.
+    #
+    # @example Basic usage
+    #   result = ModerationResult.new(
+    #     result: raw_moderation,
+    #     threshold: 0.8,
+    #     categories: [:hate, :violence]
+    #   )
+    #
+    #   result.flagged?  # Only true if score >= 0.8 AND category is hate or violence
+    #   result.passed?   # Opposite of flagged?
+    #
+    # @api public
+    class ModerationResult
+      # @return [Object] The raw moderation result from RubyLLM
+      attr_reader :raw_result
+
+      # @return [Float, nil] Configured threshold for flagging
+      attr_reader :threshold
+
+      # @return [Array<Symbol>, nil] Categories to filter on
+      attr_reader :filter_categories
+
+      # Creates a new ModerationResult
+      #
+      # @param result [Object] Raw moderation result from RubyLLM
+      # @param threshold [Float, nil] Score threshold (0.0-1.0)
+      # @param categories [Array<Symbol>, nil] Categories to check
+      def initialize(result:, threshold: nil, categories: nil)
+        @raw_result = result
+        @threshold = threshold
+        @filter_categories = categories&.map(&:to_sym)
+      end
+
+      # Returns whether the content should be flagged
+      #
+      # Considers both threshold and category filters if configured.
+      # Content is flagged only if:
+      # - Raw result is flagged AND
+      # - Score meets threshold (if configured) AND
+      # - Category matches filter (if configured)
+      #
+      # @return [Boolean] true if content should be flagged
+      def flagged?
+        return false unless raw_result.flagged?
+
+        passes_threshold? && passes_category_filter?
+      end
+
+      # Returns whether the content passed moderation
+      #
+      # @return [Boolean] true if content is not flagged
+      def passed?
+        !flagged?
+      end
+
+      # Returns the flagged categories, filtered by configuration
+      #
+      # @return [Array<String, Symbol>] Categories that triggered flagging
+      def flagged_categories
+        cats = raw_result.flagged_categories || []
+        return cats unless filter_categories&.any?
+
+        cats.select { |c| filter_categories.include?(normalize_category(c)) }
+      end
+
+      # Returns all category scores from the raw result
+      #
+      # @return [Hash{String, Symbol => Float}] Category to score mapping
+      def category_scores
+        raw_result.category_scores || {}
+      end
+
+      # Returns the moderation result ID
+      #
+      # @return [String, nil] Result identifier
+      def id
+        raw_result.id
+      end
+
+      # Returns the model used for moderation
+      #
+      # @return [String, nil] Model identifier
+      def model
+        raw_result.model
+      end
+
+      # Returns the maximum score across all categories
+      #
+      # @return [Float] Highest category score
+      def max_score
+        scores = category_scores.values
+        scores.any? ? scores.max : 0.0
+      end
+
+      # Returns whether the raw result was flagged (ignoring filters)
+      #
+      # @return [Boolean] true if raw result was flagged
+      def raw_flagged?
+        raw_result.flagged?
+      end
+
+      # Converts the result to a hash
+      #
+      # @return [Hash] Result data as a hash
+      def to_h
+        {
+          flagged: flagged?,
+          raw_flagged: raw_flagged?,
+          flagged_categories: flagged_categories,
+          category_scores: category_scores,
+          max_score: max_score,
+          threshold: threshold,
+          filter_categories: filter_categories,
+          model: model,
+          id: id
+        }
+      end
+
+      private
+
+      # Checks if the max score meets the threshold
+      #
+      # @return [Boolean] true if threshold is met or not configured
+      def passes_threshold?
+        return true unless threshold
+
+        max_score >= threshold
+      end
+
+      # Checks if any flagged categories match the filter
+      #
+      # @return [Boolean] true if categories match or no filter configured
+      def passes_category_filter?
+        return true unless filter_categories&.any?
+
+        normalized_flagged = (raw_result.flagged_categories || []).map { |c| normalize_category(c) }
+        (normalized_flagged & filter_categories).any?
+      end
+
+      # Normalizes category names for comparison
+      #
+      # @param category [String, Symbol] Category name
+      # @return [Symbol] Normalized category symbol
+      def normalize_category(category)
+        category.to_s.tr("/", "_").tr("-", "_").downcase.to_sym
+      end
+    end
+  end
+end