ruby_llm-agents 0.5.0 → 1.0.0

data/lib/ruby_llm/agents/{result.rb → results/base.rb}

@@ -93,6 +93,24 @@ module RubyLLM
       #   @return [Integer] Number of tool calls made
       attr_reader :tool_calls, :tool_calls_count
 
+      # @!group Thinking
+      # @!attribute [r] thinking_text
+      #   @return [String, nil] The reasoning/thinking content from the model
+      # @!attribute [r] thinking_signature
+      #   @return [String, nil] Signature for multi-turn thinking continuity (Claude)
+      # @!attribute [r] thinking_tokens
+      #   @return [Integer, nil] Number of tokens used for thinking
+      attr_reader :thinking_text, :thinking_signature, :thinking_tokens
+
+      # @!group Moderation
+      # @!attribute [r] status
+      #   @return [Symbol, nil] Result status (:success, :input_moderation_blocked, :output_moderation_blocked)
+      # @!attribute [r] moderation_result
+      #   @return [Object, nil] The raw moderation result from RubyLLM
+      # @!attribute [r] moderation_phase
+      #   @return [Symbol, nil] The phase where moderation blocked (:input or :output)
+      attr_reader :status, :moderation_result, :moderation_phase
+
       # Creates a new Result instance
       #
       # @param content [Hash, String] The processed response content
@@ -137,6 +155,17 @@ module RubyLLM
         # Tool calls
         @tool_calls = options[:tool_calls] || []
         @tool_calls_count = options[:tool_calls_count] || 0
+
+        # Thinking
+        @thinking_text = options[:thinking_text]
+        @thinking_signature = options[:thinking_signature]
+        @thinking_tokens = options[:thinking_tokens]
+
+        # Moderation
+        @status = options[:status] || :success
+        @moderation_flagged = options[:moderation_flagged] || false
+        @moderation_result = options[:moderation_result]
+        @moderation_phase = options[:moderation_phase]
       end
 
       # Returns total tokens (input + output)
@@ -188,6 +217,41 @@ module RubyLLM
         tool_calls_count.to_i > 0
       end
 
+      # Returns whether thinking data is present in the result
+      #
+      # @return [Boolean] true if thinking_text is present
+      def has_thinking?
+        thinking_text.present?
+      end
+
+      # Returns whether content was flagged by moderation
+      #
+      # @return [Boolean] true if moderation flagged the content
+      def moderation_flagged?
+        @moderation_flagged == true
+      end
+
+      # Returns whether content passed moderation
+      #
+      # @return [Boolean] true if content was not flagged
+      def moderation_passed?
+        !moderation_flagged?
+      end
+
+      # Returns the categories flagged by moderation
+      #
+      # @return [Array<String, Symbol>] Flagged category names
+      def moderation_categories
+        @moderation_result&.flagged_categories || []
+      end
+
+      # Returns the moderation category scores
+      #
+      # @return [Hash{String, Symbol => Float}] Category to score mapping
+      def moderation_scores
+        @moderation_result&.category_scores || {}
+      end
+
       # Converts the result to a hash
       #
       # @return [Hash] All result data as a hash
@@ -216,7 +280,15 @@ module RubyLLM
           attempts_count: attempts_count,
           attempts: attempts,
           tool_calls: tool_calls,
-          tool_calls_count: tool_calls_count
+          tool_calls_count: tool_calls_count,
+          thinking_text: thinking_text,
+          thinking_signature: thinking_signature,
+          thinking_tokens: thinking_tokens,
+          status: status,
+          moderation_flagged: moderation_flagged?,
+          moderation_phase: moderation_phase,
+          moderation_categories: moderation_categories,
+          moderation_scores: moderation_scores
         }
       end
 

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

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    # Result object for embedding operations
+    #
+    # Wraps embedding vectors with metadata about the operation including
+    # token usage, cost, timing, and utility methods for similarity calculations.
+    #
+    # @example Single text embedding
+    #   result = MyEmbedder.call(text: "Hello world")
+    #   result.vector        # => [0.123, -0.456, ...]
+    #   result.dimensions    # => 1536
+    #   result.input_tokens  # => 2
+    #
+    # @example Batch embedding
+    #   result = MyEmbedder.call(texts: ["Hello", "World"])
+    #   result.vectors       # => [[...], [...]]
+    #   result.count         # => 2
+    #
+    # @example Similarity comparison
+    #   result1 = MyEmbedder.call(text: "Ruby programming")
+    #   result2 = MyEmbedder.call(text: "Python programming")
+    #   result1.similarity(result2)  # => 0.85
+    #
+    # @api public
+    class EmbeddingResult
+      # @!attribute [r] vectors
+      #   @return [Array<Array<Float>>] The embedding vectors
+      attr_reader :vectors
+
+      # @!attribute [r] model_id
+      #   @return [String, nil] The embedding model used
+      attr_reader :model_id
+
+      # @!attribute [r] dimensions
+      #   @return [Integer, nil] The dimensionality of the vectors
+      attr_reader :dimensions
+
+      # @!attribute [r] input_tokens
+      #   @return [Integer, nil] Number of input tokens consumed
+      attr_reader :input_tokens
+
+      # @!attribute [r] total_cost
+      #   @return [Float, nil] Total cost in USD
+      attr_reader :total_cost
+
+      # @!attribute [r] duration_ms
+      #   @return [Integer, nil] Execution duration in milliseconds
+      attr_reader :duration_ms
+
+      # @!attribute [r] count
+      #   @return [Integer] Number of texts embedded
+      attr_reader :count
+
+      # @!attribute [r] started_at
+      #   @return [Time, nil] When execution started
+      attr_reader :started_at
+
+      # @!attribute [r] completed_at
+      #   @return [Time, nil] When execution completed
+      attr_reader :completed_at
+
+      # @!attribute [r] tenant_id
+      #   @return [String, nil] Tenant identifier if multi-tenancy enabled
+      attr_reader :tenant_id
+
+      # @!attribute [r] error_class
+      #   @return [String, nil] Exception class name if failed
+      attr_reader :error_class
+
+      # @!attribute [r] error_message
+      #   @return [String, nil] Exception message if failed
+      attr_reader :error_message
+
+      # Creates a new EmbeddingResult instance
+      #
+      # @param attributes [Hash] Result attributes
+      # @option attributes [Array<Array<Float>>] :vectors The embedding vectors
+      # @option attributes [String] :model_id The model used
+      # @option attributes [Integer] :dimensions Vector dimensionality
+      # @option attributes [Integer] :input_tokens Tokens consumed
+      # @option attributes [Float] :total_cost Cost in USD
+      # @option attributes [Integer] :duration_ms Duration in milliseconds
+      # @option attributes [Integer] :count Number of texts
+      # @option attributes [Time] :started_at Start time
+      # @option attributes [Time] :completed_at Completion time
+      # @option attributes [String] :tenant_id Tenant identifier
+      # @option attributes [String] :error_class Error class name
+      # @option attributes [String] :error_message Error message
+      def initialize(attributes = {})
+        @vectors = attributes[:vectors] || []
+        @model_id = attributes[:model_id]
+        @dimensions = attributes[:dimensions]
+        @input_tokens = attributes[:input_tokens]
+        @total_cost = attributes[:total_cost]
+        @duration_ms = attributes[:duration_ms]
+        @count = attributes[:count] || @vectors.size
+        @started_at = attributes[:started_at]
+        @completed_at = attributes[:completed_at]
+        @tenant_id = attributes[:tenant_id]
+        @error_class = attributes[:error_class]
+        @error_message = attributes[:error_message]
+      end
+
+      # Returns whether this result contains a single embedding
+      #
+      # @return [Boolean] true if count is 1
+      def single?
+        count == 1
+      end
+
+      # Returns whether this result contains multiple embeddings
+      #
+      # @return [Boolean] true if count > 1
+      def batch?
+        count > 1
+      end
+
+      # Returns the first (or only) embedding vector
+      #
+      # Convenience method for single-text embeddings.
+      #
+      # @return [Array<Float>, nil] The embedding vector or nil if batch
+      def vector
+        vectors.first
+      end
+
+      # Returns whether the execution succeeded
+      #
+      # @return [Boolean] true if no error occurred
+      def success?
+        error_class.nil?
+      end
+
+      # Returns whether the execution failed
+      #
+      # @return [Boolean] true if an error occurred
+      def error?
+        !success?
+      end
+
+      # Calculates cosine similarity between this embedding and another
+      #
+      # @param other [EmbeddingResult, Array<Float>] Another embedding or vector
+      # @param index [Integer] Index of the vector to compare (for batch results)
+      # @return [Float] Cosine similarity score (-1.0 to 1.0)
+      # @example Compare two results
+      #   result1.similarity(result2)  # => 0.85
+      # @example Compare with raw vector
+      #   result.similarity([0.1, 0.2, 0.3])
+      # @example Compare specific vector from batch
+      #   batch_result.similarity(other, index: 2)
+      def similarity(other, index: 0)
+        v1 = vectors[index]
+        return nil if v1.nil?
+
+        v2 = case other
+             when EmbeddingResult
+               other.vector
+             when Array
+               other
+             else
+               raise ArgumentError, "other must be EmbeddingResult or Array, got #{other.class}"
+             end
+
+        return nil if v2.nil?
+
+        cosine_similarity(v1, v2)
+      end
+
+      # Finds the most similar vectors from a collection
+      #
+      # @param others [Array<EmbeddingResult, Array<Float>>] Collection to search
+      # @param limit [Integer] Maximum results to return
+      # @param index [Integer] Index of the source vector (for batch results)
+      # @return [Array<Hash>] Sorted results with :index and :similarity keys
+      # @example Find top 5 similar
+      #   result.most_similar(document_embeddings, limit: 5)
+      def most_similar(others, limit: 10, index: 0)
+        v1 = vectors[index]
+        return [] if v1.nil?
+
+        similarities = others.each_with_index.map do |other, idx|
+          v2 = case other
+               when EmbeddingResult
+                 other.vector
+               when Array
+                 other
+               else
+                 next nil
+               end
+
+          next nil if v2.nil?
+
+          { index: idx, similarity: cosine_similarity(v1, v2) }
+        end.compact
+
+        similarities.sort_by { |s| -s[:similarity] }.first(limit)
+      end
+
+      # Converts the result to a hash
+      #
+      # @return [Hash] All result data as a hash
+      def to_h
+        {
+          vectors: vectors,
+          model_id: model_id,
+          dimensions: dimensions,
+          input_tokens: input_tokens,
+          total_cost: total_cost,
+          duration_ms: duration_ms,
+          count: count,
+          started_at: started_at,
+          completed_at: completed_at,
+          tenant_id: tenant_id,
+          error_class: error_class,
+          error_message: error_message
+        }
+      end
+
+      private
+
+      # Calculates cosine similarity between two vectors
+      #
+      # @param a [Array<Float>] First vector
+      # @param b [Array<Float>] Second vector
+      # @return [Float] Cosine similarity (-1.0 to 1.0)
+      def cosine_similarity(a, b)
+        return 0.0 if a.empty? || b.empty?
+        return 0.0 if a.size != b.size
+
+        dot_product = a.zip(b).sum { |x, y| x * y }
+        magnitude_a = Math.sqrt(a.sum { |x| x * x })
+        magnitude_b = Math.sqrt(b.sum { |x| x * x })
+
+        return 0.0 if magnitude_a.zero? || magnitude_b.zero?
+
+        dot_product / (magnitude_a * magnitude_b)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,314 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    # Result wrapper for image analysis operations
+    #
+    # Provides a consistent interface for accessing analysis data
+    # including captions, tags, objects, colors, and extracted text.
+    #
+    # @example Accessing analysis data
+    #   result = ImageAnalyzer.call(image: "photo.jpg")
+    #   result.caption      # => "A sunset over mountains"
+    #   result.tags         # => ["sunset", "mountains", "nature"]
+    #   result.objects      # => [{name: "mountain", location: "center", confidence: "high"}]
+    #   result.colors       # => [{hex: "#FF6B35", name: "orange", percentage: 30}]
+    #   result.description  # => "A detailed description..."
+    #   result.success?     # => true
+    #
+    class ImageAnalysisResult
+      attr_reader :image, :model_id, :analysis_type,
+                  :caption, :description, :tags, :objects, :colors, :text,
+                  :raw_response, :started_at, :completed_at, :tenant_id, :analyzer_class,
+                  :error_class, :error_message
+
+      # Initialize a new result
+      #
+      # @param image [String] The analyzed image path or URL
+      # @param model_id [String] Model used for analysis
+      # @param analysis_type [Symbol] Type of analysis performed
+      # @param caption [String, nil] Brief caption of the image
+      # @param description [String, nil] Detailed description
+      # @param tags [Array<String>] Tags/keywords for the image
+      # @param objects [Array<Hash>] Detected objects with metadata
+      # @param colors [Array<Hash>] Dominant colors with hex, name, percentage
+      # @param text [String, nil] Extracted text (OCR)
+      # @param raw_response [Hash, String, nil] Raw response from the model
+      # @param started_at [Time] When analysis started
+      # @param completed_at [Time] When analysis completed
+      # @param tenant_id [String, nil] Tenant identifier
+      # @param analyzer_class [String] Name of the analyzer class
+      # @param error_class [String, nil] Error class name if failed
+      # @param error_message [String, nil] Error message if failed
+      def initialize(image:, model_id:, analysis_type:, caption:, description:, tags:,
+                     objects:, colors:, text:, raw_response:, started_at:, completed_at:,
+                     tenant_id:, analyzer_class:, error_class: nil, error_message: nil)
+        @image = image
+        @model_id = model_id
+        @analysis_type = analysis_type
+        @caption = caption
+        @description = description
+        @tags = tags || []
+        @objects = objects || []
+        @colors = colors || []
+        @text = text
+        @raw_response = raw_response
+        @started_at = started_at
+        @completed_at = completed_at
+        @tenant_id = tenant_id
+        @analyzer_class = analyzer_class
+        @error_class = error_class
+        @error_message = error_message
+      end
+
+      # Status helpers
+
+      def success?
+        error_class.nil? && (caption.present? || description.present? || tags.any?)
+      end
+
+      def error?
+        !success?
+      end
+
+      # Analysis is always single
+      def single?
+        true
+      end
+
+      def batch?
+        false
+      end
+
+      # Count (always 1 for analysis)
+      def count
+        success? ? 1 : 0
+      end
+
+      # Data access helpers
+
+      # Check if the result has a caption
+      def caption?
+        caption.present?
+      end
+
+      # Check if the result has a description
+      def description?
+        description.present?
+      end
+
+      # Check if the result has tags
+      def tags?
+        tags.any?
+      end
+
+      # Check if the result has detected objects
+      def objects?
+        objects.any?
+      end
+
+      # Check if the result has color information
+      def colors?
+        colors.any?
+      end
+
+      # Check if text was extracted
+      def text?
+        text.present?
+      end
+
+      # Get tags as symbols
+      #
+      # @return [Array<Symbol>] Tags as symbols
+      def tag_symbols
+        tags.map { |t| t.to_s.downcase.gsub(/\s+/, "_").to_sym }
+      end
+
+      # Get the dominant color (highest percentage)
+      #
+      # @return [Hash, nil] The dominant color or nil
+      def dominant_color
+        return nil unless colors?
+
+        colors.max_by { |c| c[:percentage] || 0 }
+      end
+
+      # Get objects by confidence level
+      #
+      # @param confidence [String] Confidence level ("high", "medium", "low")
+      # @return [Array<Hash>] Objects with matching confidence
+      def objects_with_confidence(confidence)
+        objects.select { |obj| obj[:confidence]&.downcase == confidence.to_s.downcase }
+      end
+
+      # Get high-confidence objects
+      #
+      # @return [Array<Hash>] High-confidence objects
+      def high_confidence_objects
+        objects_with_confidence("high")
+      end
+
+      # Check if a specific object was detected
+      #
+      # @param name [String] Object name to search for
+      # @return [Boolean] Whether the object was detected
+      def has_object?(name)
+        objects.any? { |obj| obj[:name]&.downcase&.include?(name.to_s.downcase) }
+      end
+
+      # Check if a specific tag is present
+      #
+      # @param tag [String] Tag to search for
+      # @return [Boolean] Whether the tag is present
+      def has_tag?(tag)
+        tags.any? { |t| t.downcase == tag.to_s.downcase }
+      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?
+
+        # Analysis typically uses vision model pricing
+        # Estimate based on model and image size
+        ImageGenerator::Pricing.calculate_cost(
+          model_id: model_id,
+          count: 1
+        )
+      end
+
+      # Serialization
+
+      def to_h
+        {
+          success: success?,
+          image: image,
+          model_id: model_id,
+          analysis_type: analysis_type,
+          caption: caption,
+          description: description,
+          tags: tags,
+          objects: objects,
+          colors: colors,
+          text: text,
+          total_cost: total_cost,
+          duration_ms: duration_ms,
+          started_at: started_at&.iso8601,
+          completed_at: completed_at&.iso8601,
+          tenant_id: tenant_id,
+          analyzer_class: analyzer_class,
+          error_class: error_class,
+          error_message: error_message
+        }
+      end
+
+      # Caching
+
+      def to_cache
+        {
+          image: image,
+          model_id: model_id,
+          analysis_type: analysis_type,
+          caption: caption,
+          description: description,
+          tags: tags,
+          objects: objects,
+          colors: colors,
+          text: text,
+          total_cost: total_cost,
+          cached_at: Time.current.iso8601
+        }
+      end
+
+      def self.from_cache(data)
+        CachedImageAnalysisResult.new(data)
+      end
+    end
+
+    # Lightweight result for cached analyses
+    class CachedImageAnalysisResult
+      attr_reader :image, :model_id, :analysis_type,
+                  :caption, :description, :tags, :objects, :colors, :text,
+                  :total_cost, :cached_at
+
+      def initialize(data)
+        @image = data[:image]
+        @model_id = data[:model_id]
+        @analysis_type = data[:analysis_type]
+        @caption = data[:caption]
+        @description = data[:description]
+        @tags = data[:tags] || []
+        @objects = data[:objects] || []
+        @colors = data[:colors] || []
+        @text = data[:text]
+        @total_cost = data[:total_cost]
+        @cached_at = data[:cached_at]
+      end
+
+      def success?
+        caption.present? || description.present? || tags.any?
+      end
+
+      def error?
+        !success?
+      end
+
+      def cached?
+        true
+      end
+
+      def count
+        success? ? 1 : 0
+      end
+
+      def single?
+        true
+      end
+
+      def batch?
+        false
+      end
+
+      def caption?
+        caption.present?
+      end
+
+      def description?
+        description.present?
+      end
+
+      def tags?
+        tags.any?
+      end
+
+      def objects?
+        objects.any?
+      end
+
+      def colors?
+        colors.any?
+      end
+
+      def text?
+        text.present?
+      end
+
+      def tag_symbols
+        tags.map { |t| t.to_s.downcase.gsub(/\s+/, "_").to_sym }
+      end
+
+      def dominant_color
+        return nil unless colors?
+
+        colors.max_by { |c| c[:percentage] || 0 }
+      end
+    end
+  end
+end