ruby_llm-agents 3.8.0 → 3.9.0

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

@@ -107,6 +107,16 @@ module RubyLLM
       #   @return [Integer, nil] Database ID of the associated Execution record
       attr_reader :execution_id
 
+      # @!group Tracking
+      # @!attribute [r] agent_class_name
+      #   @return [String, nil] The agent class that produced this result
+      attr_reader :agent_class_name
+
+      # @!group Debug
+      # @!attribute [r] trace
+      #   @return [Array<Hash>, nil] Pipeline trace entries (when debug: true)
+      attr_reader :trace
+
       # Creates a new Result instance
       #
       # @param content [Hash, String] The processed response content
@@ -159,6 +169,16 @@ module RubyLLM
 
         # Execution record
         @execution_id = options[:execution_id]
+
+        # Tracking
+        @agent_class_name = options[:agent_class_name]
+
+        # Debug trace
+        @trace = options[:trace]
+
+        # Register with active tracker
+        tracker = Thread.current[:ruby_llm_agents_tracker]
+        tracker << self if tracker
       end
 
       # Loads the associated Execution record from the database
@@ -264,8 +284,10 @@ module RubyLLM
           thinking_text: thinking_text,
           thinking_signature: thinking_signature,
           thinking_tokens: thinking_tokens,
-          execution_id: execution_id
-        }
+          execution_id: execution_id,
+          agent_class_name: agent_class_name,
+          trace: trace
+        }.compact
       end
 
       # @!group Deprecated Hash Delegation

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

@@ -25,6 +25,8 @@ module RubyLLM
     #
     # @api public
     class EmbeddingResult
+      include Trackable
+
       # @!attribute [r] vectors
       #   @return [Array<Array<Float>>] The embedding vectors
       attr_reader :vectors
@@ -106,6 +108,8 @@ module RubyLLM
         @error_class = attributes[:error_class]
         @error_message = attributes[:error_message]
         @execution_id = attributes[:execution_id]
+        @agent_class_name = attributes[:agent_class_name]
+        register_with_tracker
       end
 
       # Loads the associated Execution record from the database

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

@@ -17,6 +17,8 @@ module RubyLLM
     #   result.success?     # => true
     #
     class ImageAnalysisResult
+      include Trackable
+
       attr_reader :image, :model_id, :analysis_type,
         :caption, :description, :tags, :objects, :colors, :text,
         :raw_response, :started_at, :completed_at, :tenant_id, :analyzer_class,
@@ -43,7 +45,7 @@ module RubyLLM
       # @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)
+        tenant_id:, analyzer_class:, error_class: nil, error_message: nil, agent_class_name: nil)
         @image = image
         @model_id = model_id
         @analysis_type = analysis_type
@@ -61,6 +63,10 @@ module RubyLLM
         @error_class = error_class
         @error_message = error_message
         @execution_id = nil
+
+        # Tracking
+        @agent_class_name = agent_class_name
+        register_with_tracker
       end
 
       # Loads the associated Execution record from the database

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

@@ -17,6 +17,8 @@ module RubyLLM
     #   result.success?  # => true
     #
     class ImageEditResult
+      include Trackable
+
       attr_reader :images, :source_image, :mask, :prompt, :model_id, :size,
         :started_at, :completed_at, :tenant_id, :editor_class,
         :error_class, :error_message
@@ -38,7 +40,7 @@ module RubyLLM
       # @param error_message [String, nil] Error message if failed
       def initialize(images:, source_image:, mask:, prompt:, model_id:, size:,
         started_at:, completed_at:, tenant_id:, editor_class:,
-        error_class: nil, error_message: nil)
+        error_class: nil, error_message: nil, agent_class_name: nil)
         @images = images
         @source_image = source_image
         @mask = mask
@@ -52,6 +54,10 @@ module RubyLLM
         @error_class = error_class
         @error_message = error_message
         @execution_id = nil
+
+        # Tracking
+        @agent_class_name = agent_class_name
+        register_with_tracker
       end
 
       # Loads the associated Execution record from the database

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

@@ -20,6 +20,8 @@ module RubyLLM
     #   result.save_all("./logos")
     #
     class ImageGenerationResult
+      include Trackable
+
       attr_reader :images, :prompt, :model_id, :size, :quality, :style,
         :started_at, :completed_at, :tenant_id, :generator_class,
         :error_class, :error_message, :execution_id
@@ -40,7 +42,7 @@ module RubyLLM
       # @param error_message [String, nil] Error message if failed
       def initialize(images:, prompt:, model_id:, size:, quality:, style:,
         started_at:, completed_at:, tenant_id:, generator_class:,
-        error_class: nil, error_message: nil, execution_id: nil)
+        error_class: nil, error_message: nil, execution_id: nil, agent_class_name: nil)
         @images = images
         @prompt = prompt
         @model_id = model_id
@@ -54,6 +56,10 @@ module RubyLLM
         @error_class = error_class
         @error_message = error_message
         @execution_id = execution_id
+
+        # Tracking
+        @agent_class_name = agent_class_name
+        register_with_tracker
       end
 
       # Loads the associated Execution record from the database

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

@@ -21,6 +21,8 @@ module RubyLLM
     #   result.analysis          # => Shortcut to analyzer step result
     #
     class ImagePipelineResult
+      include Trackable
+
       attr_reader :step_results, :started_at, :completed_at, :tenant_id,
         :pipeline_class, :context, :error_class, :error_message
       attr_accessor :execution_id
@@ -36,7 +38,7 @@ module RubyLLM
       # @param error_class [String, nil] Error class name if failed
       # @param error_message [String, nil] Error message if failed
       def initialize(step_results:, started_at:, completed_at:, tenant_id:,
-        pipeline_class:, context:, error_class: nil, error_message: nil)
+        pipeline_class:, context:, error_class: nil, error_message: nil, agent_class_name: nil)
         @step_results = step_results
         @started_at = started_at
         @completed_at = completed_at
@@ -46,6 +48,10 @@ module RubyLLM
         @error_class = error_class
         @error_message = error_message
         @execution_id = nil
+
+        # Tracking
+        @agent_class_name = agent_class_name
+        register_with_tracker
       end
 
       # Loads the associated Execution record from the database

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

@@ -17,6 +17,8 @@ module RubyLLM
     #   result.success?  # => true
     #
     class ImageTransformResult
+      include Trackable
+
       attr_reader :images, :source_image, :prompt, :model_id, :size, :strength,
         :started_at, :completed_at, :tenant_id, :transformer_class,
         :error_class, :error_message
@@ -38,7 +40,7 @@ module RubyLLM
       # @param error_message [String, nil] Error message if failed
       def initialize(images:, source_image:, prompt:, model_id:, size:, strength:,
         started_at:, completed_at:, tenant_id:, transformer_class:,
-        error_class: nil, error_message: nil)
+        error_class: nil, error_message: nil, agent_class_name: nil)
         @images = images
         @source_image = source_image
         @prompt = prompt
@@ -52,6 +54,10 @@ module RubyLLM
         @error_class = error_class
         @error_message = error_message
         @execution_id = nil
+
+        # Tracking
+        @agent_class_name = agent_class_name
+        register_with_tracker
       end
 
       # Loads the associated Execution record from the database

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

@@ -15,6 +15,8 @@ module RubyLLM
     #   result.success?     # => true
     #
     class ImageUpscaleResult
+      include Trackable
+
       attr_reader :image, :source_image, :model_id, :scale, :output_size, :face_enhance,
         :started_at, :completed_at, :tenant_id, :upscaler_class,
         :error_class, :error_message
@@ -36,7 +38,7 @@ module RubyLLM
       # @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)
+        error_class: nil, error_message: nil, agent_class_name: nil)
         @image = image
         @source_image = source_image
         @model_id = model_id
@@ -50,6 +52,10 @@ module RubyLLM
         @error_class = error_class
         @error_message = error_message
         @execution_id = nil
+
+        # Tracking
+        @agent_class_name = agent_class_name
+        register_with_tracker
       end
 
       # Loads the associated Execution record from the database

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

@@ -14,6 +14,8 @@ module RubyLLM
     #   result.success?  # => true
     #
     class ImageVariationResult
+      include Trackable
+
       attr_reader :images, :source_image, :model_id, :size, :variation_strength,
         :started_at, :completed_at, :tenant_id, :variator_class,
         :error_class, :error_message
@@ -34,7 +36,7 @@ module RubyLLM
       # @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)
+        error_class: nil, error_message: nil, agent_class_name: nil)
         @images = images
         @source_image = source_image
         @model_id = model_id
@@ -47,6 +49,10 @@ module RubyLLM
         @error_class = error_class
         @error_message = error_message
         @execution_id = nil
+
+        # Tracking
+        @agent_class_name = agent_class_name
+        register_with_tracker
       end
 
       # Loads the associated Execution record from the database

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

@@ -23,6 +23,8 @@ module RubyLLM
     #
     # @api public
     class SpeechResult
+      include Trackable
+
       # @!group Audio Content
 
       # @!attribute [r] audio
@@ -229,6 +231,10 @@ module RubyLLM
 
         # Execution record
         @execution_id = attributes[:execution_id]
+
+        # Tracking
+        @agent_class_name = attributes[:agent_class_name]
+        register_with_tracker
       end
 
       # Loads the associated Execution record from the database

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    # Mixin that registers a result object with the active Tracker.
+    #
+    # Included in every result class so that RubyLLM::Agents.track
+    # can collect results automatically.
+    #
+    # @api private
+    module Trackable
+      def self.included(base)
+        base.attr_reader :agent_class_name unless base.method_defined?(:agent_class_name)
+      end
+
+      private
+
+      # Call from the end of initialize to register with the active tracker
+      def register_with_tracker
+        tracker = Thread.current[:ruby_llm_agents_tracker]
+        tracker << self if tracker
+      end
+    end
+  end
+end

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

@@ -26,6 +26,8 @@ module RubyLLM
     #
     # @api public
     class TranscriptionResult
+      include Trackable
+
       # @!group Content
 
       # @!attribute [r] text
@@ -250,6 +252,10 @@ module RubyLLM
 
         # Execution record
         @execution_id = attributes[:execution_id]
+
+        # Tracking
+        @agent_class_name = attributes[:agent_class_name]
+        register_with_tracker
       end
 
       # Loads the associated Execution record from the database

data/lib/ruby_llm/agents/text/embedder.rb

@@ -337,11 +337,14 @@ module RubyLLM
         embed_options = {model: context&.model || resolved_model}
         embed_options[:dimensions] = resolved_dimensions if resolved_dimensions
 
-        # Pass scoped RubyLLM context for thread-safe per-tenant API keys
+        # Use scoped RubyLLM::Context for thread-safe per-tenant API keys.
+        # RubyLLM::Context#embed creates an Embedding with the scoped config.
         llm_ctx = context&.llm
-        embed_options[:context] = llm_ctx if llm_ctx.is_a?(RubyLLM::Context)
-
-        response = RubyLLM.embed(preprocessed, **embed_options)
+        response = if llm_ctx.is_a?(RubyLLM::Context)
+          llm_ctx.embed(preprocessed, **embed_options)
+        else
+          RubyLLM.embed(preprocessed, **embed_options)
+        end
 
         # ruby_llm returns vectors as an array (even for single text)
         vectors = response.vectors

data/lib/ruby_llm/agents/track_report.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    # Aggregated read-only report returned by RubyLLM::Agents.track.
+    #
+    # Provides totals and breakdowns across all agent calls made
+    # inside the tracked block.
+    #
+    # @example
+    #   report = RubyLLM::Agents.track do
+    #     TranscribeAgent.call(with: audio_path)
+    #     ChatAgent.call(message: "hello")
+    #   end
+    #   report.total_cost   # => 0.0078
+    #   report.call_count   # => 2
+    #
+    # @api public
+    class TrackReport
+      attr_reader :value, :error, :results, :request_id
+      attr_reader :started_at, :completed_at
+
+      def initialize(value:, error:, results:, request_id:, started_at:, completed_at:)
+        @value = value
+        @error = error
+        @results = results.freeze
+        @request_id = request_id
+        @started_at = started_at
+        @completed_at = completed_at
+      end
+
+      def successful?
+        @error.nil?
+      end
+
+      def failed?
+        !successful?
+      end
+
+      def call_count
+        @results.size
+      end
+
+      def total_cost
+        @results.sum { |r| r.total_cost || 0 }
+      end
+
+      def input_cost
+        @results.sum { |r| r.input_cost || 0 }
+      end
+
+      def output_cost
+        @results.sum { |r| r.output_cost || 0 }
+      end
+
+      def total_tokens
+        @results.sum { |r| r.total_tokens }
+      end
+
+      def input_tokens
+        @results.sum { |r| r.input_tokens || 0 }
+      end
+
+      def output_tokens
+        @results.sum { |r| r.output_tokens || 0 }
+      end
+
+      def duration_ms
+        return nil unless @started_at && @completed_at
+        ((@completed_at - @started_at) * 1000).to_i
+      end
+
+      def all_successful?
+        @results.all?(&:success?)
+      end
+
+      def any_errors?
+        @results.any?(&:error?)
+      end
+
+      def errors
+        @results.select(&:error?)
+      end
+
+      def successful
+        @results.select(&:success?)
+      end
+
+      def models_used
+        @results.filter_map(&:chosen_model_id).uniq
+      end
+
+      def cost_breakdown
+        @results.map do |r|
+          {
+            agent: r.respond_to?(:agent_class_name) ? r.agent_class_name : nil,
+            model: r.chosen_model_id,
+            cost: r.total_cost || 0,
+            tokens: r.total_tokens,
+            duration_ms: r.duration_ms
+          }
+        end
+      end
+
+      def to_h
+        {
+          successful: successful?,
+          value: value,
+          error: error&.message,
+          request_id: request_id,
+          call_count: call_count,
+          total_cost: total_cost,
+          input_cost: input_cost,
+          output_cost: output_cost,
+          total_tokens: total_tokens,
+          input_tokens: input_tokens,
+          output_tokens: output_tokens,
+          duration_ms: duration_ms,
+          started_at: started_at,
+          completed_at: completed_at,
+          models_used: models_used,
+          cost_breakdown: cost_breakdown
+        }
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/tracker.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    # Internal collector used by RubyLLM::Agents.track to accumulate
+    # Result objects produced during a tracked block.
+    #
+    # Not part of the public API — users interact with TrackReport instead.
+    #
+    # @api private
+    class Tracker
+      attr_reader :results, :defaults, :request_id, :tags
+
+      def initialize(defaults: {}, request_id: nil, tags: {})
+        @results = []
+        @defaults = defaults
+        @request_id = request_id || generate_request_id
+        @tags = tags
+      end
+
+      def <<(result)
+        @results << result
+      end
+
+      private
+
+      def generate_request_id
+        "track_#{SecureRandom.hex(8)}"
+      end
+    end
+  end
+end