ruby_llm-agents 0.3.0 → 0.3.3

data/lib/ruby_llm/agents/base.rb

@@ -50,6 +50,7 @@ module RubyLLM
         # @param kwargs [Hash] Named parameters for the agent
         # @option kwargs [Boolean] :dry_run Return prompt info without API call
         # @option kwargs [Boolean] :skip_cache Bypass caching even if enabled
+        # @option kwargs [String, Array<String>] :with Attachments (files, URLs) to send with the prompt
         # @yield [chunk] Yields chunks when streaming is enabled
         # @yieldparam chunk [RubyLLM::Chunk] A streaming chunk with content
         # @return [Object] The processed response from the agent
@@ -64,6 +65,10 @@ module RubyLLM
         #   ChatAgent.call(message: "Hello") do |chunk|
         #     print chunk.content
         #   end
+        #
+        # @example With attachments
+        #   VisionAgent.call(query: "Describe this image", with: "photo.jpg")
+        #   VisionAgent.call(query: "Compare these", with: ["a.png", "b.png"])
         def call(*args, **kwargs, &block)
           new(*args, **kwargs).call(&block)
         end
@@ -320,7 +325,9 @@ module RubyLLM
       #   @return [RubyLLM::Chat] The configured RubyLLM client
       # @!attribute [r] time_to_first_token_ms
       #   @return [Integer, nil] Time to first token in milliseconds (streaming only)
-      attr_reader :model, :temperature, :client, :time_to_first_token_ms
+      # @!attribute [r] accumulated_tool_calls
+      #   @return [Array<Hash>] Tool calls accumulated during execution
+      attr_reader :model, :temperature, :client, :time_to_first_token_ms, :accumulated_tool_calls
 
       # Creates a new agent instance
       #
@@ -332,6 +339,7 @@ module RubyLLM
         @model = model
         @temperature = temperature
         @options = options
+        @accumulated_tool_calls = []
         validate_required_params!
         @client = build_client
       end
@@ -419,20 +427,26 @@ module RubyLLM
 
       # Returns prompt info without making an API call (debug mode)
       #
-      # @return [Hash] Agent configuration and prompt info
+      # @return [Result] A Result with dry run configuration info
       def dry_run_response
-        {
-          dry_run: true,
-          agent: self.class.name,
-          model: model,
+        Result.new(
+          content: {
+            dry_run: true,
+            agent: self.class.name,
+            model: model,
+            temperature: temperature,
+            timeout: self.class.timeout,
+            system_prompt: system_prompt,
+            user_prompt: user_prompt,
+            attachments: @options[:with],
+            schema: schema&.class&.name,
+            streaming: self.class.streaming,
+            tools: self.class.tools.map { |t| t.respond_to?(:name) ? t.name : t.to_s }
+          },
+          model_id: model,
           temperature: temperature,
-          timeout: self.class.timeout,
-          system_prompt: system_prompt,
-          user_prompt: user_prompt,
-          schema: schema&.class&.name,
-          streaming: self.class.streaming,
-          tools: self.class.tools.map { |t| t.respond_to?(:name) ? t.name : t.to_s }
-        }
+          streaming: self.class.streaming
+        )
       end
 
       private
@@ -456,17 +470,20 @@ module RubyLLM
       #
       # @param model_override [String, nil] Optional model to use instead of default
       # @yield [chunk] Yields chunks when streaming is enabled
-      # @return [Object] The processed response
+      # @return [Result] A Result object with processed content and metadata
       def execute_single_attempt(model_override: nil, &block)
         current_client = model_override ? build_client_with_model(model_override) : client
         @execution_started_at ||= Time.current
+        reset_accumulated_tool_calls!
 
         Timeout.timeout(self.class.timeout) do
           if self.class.streaming && block_given?
             execute_with_streaming(current_client, &block)
           else
-            response = current_client.ask(user_prompt)
-            process_response(capture_response(response))
+            response = current_client.ask(user_prompt, **ask_options)
+            extract_tool_calls_from_client(current_client)
+            capture_response(response)
+            build_result(process_response(response), response)
           end
         end
       end
@@ -479,11 +496,11 @@ module RubyLLM
       # @param current_client [RubyLLM::Chat] The configured client
       # @yield [chunk] Yields each chunk as it arrives
       # @yieldparam chunk [RubyLLM::Chunk] A streaming chunk
-      # @return [Object] The processed response
+      # @return [Result] A Result object with processed content and metadata
       def execute_with_streaming(current_client, &block)
         first_chunk_at = nil
 
-        response = current_client.ask(user_prompt) do |chunk|
+        response = current_client.ask(user_prompt, **ask_options) do |chunk|
           first_chunk_at ||= Time.current
           yield chunk if block_given?
         end
@@ -492,7 +509,9 @@ module RubyLLM
           @time_to_first_token_ms = ((first_chunk_at - @execution_started_at) * 1000).to_i
         end
 
-        process_response(capture_response(response))
+        extract_tool_calls_from_client(current_client)
+        capture_response(response)
+        build_result(process_response(response), response)
       end
 
       # Executes the agent with retry/fallback/circuit breaker support
@@ -692,7 +711,18 @@ module RubyLLM
       #
       # @return [Hash] Data to hash for cache key
       def cache_key_data
-        @options.except(:skip_cache, :dry_run)
+        @options.except(:skip_cache, :dry_run, :with)
+      end
+
+      # Returns options to pass to the ask method
+      #
+      # Currently supports :with for attachments (images, PDFs, etc.)
+      #
+      # @return [Hash] Options for the ask call
+      def ask_options
+        opts = {}
+        opts[:with] = @options[:with] if @options[:with]
+        opts
       end
 
       # Validates that all required parameters are present
@@ -734,6 +764,183 @@ module RubyLLM
           client.with_message(message[:role], message[:content])
         end
       end
+
+      # @!group Result Building
+
+      # Builds a Result object from processed content and response metadata
+      #
+      # @param content [Hash, String] The processed response content
+      # @param response [RubyLLM::Message] The raw LLM response
+      # @return [Result] A Result object with full execution metadata
+      def build_result(content, response)
+        completed_at = Time.current
+        input_tokens = result_response_value(response, :input_tokens)
+        output_tokens = result_response_value(response, :output_tokens)
+        response_model_id = result_response_value(response, :model_id)
+
+        Result.new(
+          content: content,
+          input_tokens: input_tokens,
+          output_tokens: output_tokens,
+          cached_tokens: result_response_value(response, :cached_tokens, 0),
+          cache_creation_tokens: result_response_value(response, :cache_creation_tokens, 0),
+          model_id: model,
+          chosen_model_id: response_model_id || model,
+          temperature: temperature,
+          started_at: @execution_started_at,
+          completed_at: completed_at,
+          duration_ms: result_duration_ms(completed_at),
+          time_to_first_token_ms: @time_to_first_token_ms,
+          finish_reason: result_finish_reason(response),
+          streaming: self.class.streaming,
+          input_cost: result_input_cost(input_tokens, response_model_id),
+          output_cost: result_output_cost(output_tokens, response_model_id),
+          total_cost: result_total_cost(input_tokens, output_tokens, response_model_id),
+          tool_calls: @accumulated_tool_calls,
+          tool_calls_count: @accumulated_tool_calls.size
+        )
+      end
+
+      # Safely extracts a value from the response object
+      #
+      # @param response [Object] The response object
+      # @param method [Symbol] The method to call
+      # @param default [Object] Default value if method doesn't exist
+      # @return [Object] The extracted value or default
+      def result_response_value(response, method, default = nil)
+        return default unless response.respond_to?(method)
+        response.send(method) || default
+      end
+
+      # Calculates execution duration in milliseconds
+      #
+      # @param completed_at [Time] When execution completed
+      # @return [Integer, nil] Duration in ms or nil
+      def result_duration_ms(completed_at)
+        return nil unless @execution_started_at
+        ((completed_at - @execution_started_at) * 1000).to_i
+      end
+
+      # Extracts finish reason from response
+      #
+      # @param response [Object] The response object
+      # @return [String, nil] Normalized finish reason
+      def result_finish_reason(response)
+        reason = result_response_value(response, :finish_reason) ||
+                 result_response_value(response, :stop_reason)
+        return nil unless reason
+
+        # Normalize to standard values
+        case reason.to_s.downcase
+        when "stop", "end_turn" then "stop"
+        when "length", "max_tokens" then "length"
+        when "content_filter", "safety" then "content_filter"
+        when "tool_calls", "tool_use" then "tool_calls"
+        else "other"
+        end
+      end
+
+      # Calculates input cost from tokens
+      #
+      # @param input_tokens [Integer, nil] Number of input tokens
+      # @param response_model_id [String, nil] Model that responded
+      # @return [Float, nil] Input cost in USD
+      def result_input_cost(input_tokens, response_model_id)
+        return nil unless input_tokens
+        model_info = result_model_info(response_model_id)
+        return nil unless model_info&.pricing
+        price = model_info.pricing.text_tokens&.input || 0
+        (input_tokens / 1_000_000.0 * price).round(6)
+      end
+
+      # Calculates output cost from tokens
+      #
+      # @param output_tokens [Integer, nil] Number of output tokens
+      # @param response_model_id [String, nil] Model that responded
+      # @return [Float, nil] Output cost in USD
+      def result_output_cost(output_tokens, response_model_id)
+        return nil unless output_tokens
+        model_info = result_model_info(response_model_id)
+        return nil unless model_info&.pricing
+        price = model_info.pricing.text_tokens&.output || 0
+        (output_tokens / 1_000_000.0 * price).round(6)
+      end
+
+      # Calculates total cost from tokens
+      #
+      # @param input_tokens [Integer, nil] Number of input tokens
+      # @param output_tokens [Integer, nil] Number of output tokens
+      # @param response_model_id [String, nil] Model that responded
+      # @return [Float, nil] Total cost in USD
+      def result_total_cost(input_tokens, output_tokens, response_model_id)
+        input_cost = result_input_cost(input_tokens, response_model_id)
+        output_cost = result_output_cost(output_tokens, response_model_id)
+        return nil unless input_cost || output_cost
+        ((input_cost || 0) + (output_cost || 0)).round(6)
+      end
+
+      # Resolves model info for cost calculation
+      #
+      # @param response_model_id [String, nil] Model ID from response
+      # @return [Object, nil] Model info or nil
+      def result_model_info(response_model_id)
+        lookup_id = response_model_id || model
+        return nil unless lookup_id
+        model_obj, _provider = RubyLLM::Models.resolve(lookup_id)
+        model_obj
+      rescue StandardError
+        nil
+      end
+
+      # @!endgroup
+
+      # @!group Tool Call Tracking
+
+      # Resets accumulated tool calls for a new execution
+      #
+      # @return [void]
+      def reset_accumulated_tool_calls!
+        @accumulated_tool_calls = []
+      end
+
+      # Extracts tool calls from all assistant messages in the conversation
+      #
+      # RubyLLM handles tool call loops internally. After ask() completes,
+      # the conversation history contains all intermediate assistant messages
+      # that had tool_calls. This method extracts those tool calls.
+      #
+      # @param client [RubyLLM::Chat] The chat client with conversation history
+      # @return [void]
+      def extract_tool_calls_from_client(client)
+        return unless client.respond_to?(:messages)
+
+        client.messages.each do |message|
+          next unless message.role == :assistant
+          next unless message.respond_to?(:tool_calls) && message.tool_calls.present?
+
+          message.tool_calls.each_value do |tool_call|
+            @accumulated_tool_calls << serialize_tool_call(tool_call)
+          end
+        end
+      end
+
+      # Serializes a single tool call to a hash
+      #
+      # @param tool_call [Object] The tool call object
+      # @return [Hash] Serialized tool call
+      def serialize_tool_call(tool_call)
+        if tool_call.respond_to?(:to_h)
+          tool_call.to_h.transform_keys(&:to_s)
+        else
+          {
+            "id" => tool_call.id,
+            "name" => tool_call.name,
+            "arguments" => tool_call.arguments
+          }
+        end
+      end
+
+      # @!endgroup
     end
   end
 end

data/lib/ruby_llm/agents/instrumentation.rb

@@ -385,6 +385,12 @@ module RubyLLM
           update_data[:response] = redacted_response(@last_response)
         end
 
+        # Add tool calls from accumulated_tool_calls (captured from all responses)
+        if respond_to?(:accumulated_tool_calls) && accumulated_tool_calls.present?
+          update_data[:tool_calls] = accumulated_tool_calls
+          update_data[:tool_calls_count] = accumulated_tool_calls.size
+        end
+
         # Add error data if failed
         if error
           update_data.merge!(
@@ -566,7 +572,11 @@ module RubyLLM
       # @param response [RubyLLM::Message, nil] The LLM response
       # @return [Hash] Extracted response data (empty if response invalid)
       def safe_extract_response_data(response)
-        return {} unless response.is_a?(RubyLLM::Message)
+        return {} unless response.respond_to?(:input_tokens)
+
+        # Use accumulated_tool_calls which captures tool calls from ALL responses
+        # during multi-turn conversations (when tools are used)
+        tool_calls_data = respond_to?(:accumulated_tool_calls) ? accumulated_tool_calls : []
 
         {
           input_tokens: safe_response_value(response, :input_tokens),
@@ -575,7 +585,9 @@ module RubyLLM
           cache_creation_tokens: safe_response_value(response, :cache_creation_tokens, 0),
           model_id: safe_response_value(response, :model_id),
           finish_reason: safe_extract_finish_reason(response),
-          response: safe_serialize_response(response)
+          response: safe_serialize_response(response),
+          tool_calls: tool_calls_data || [],
+          tool_calls_count: tool_calls_data&.size || 0
         }.compact
       end
 
@@ -689,16 +701,37 @@ module RubyLLM
       # @param response [RubyLLM::Message] The LLM response
       # @return [Hash] Serialized response data
       def safe_serialize_response(response)
+        # Use accumulated_tool_calls which captures tool calls from ALL responses
+        tool_calls_data = respond_to?(:accumulated_tool_calls) ? accumulated_tool_calls : nil
+
         {
           content: safe_response_value(response, :content),
           model_id: safe_response_value(response, :model_id),
           input_tokens: safe_response_value(response, :input_tokens),
           output_tokens: safe_response_value(response, :output_tokens),
           cached_tokens: safe_response_value(response, :cached_tokens, 0),
-          cache_creation_tokens: safe_response_value(response, :cache_creation_tokens, 0)
+          cache_creation_tokens: safe_response_value(response, :cache_creation_tokens, 0),
+          tool_calls: tool_calls_data.presence
         }.compact
       end
 
+      # Serializes tool calls to an array of hashes for storage
+      #
+      # @param response [RubyLLM::Message] The LLM response
+      # @return [Array<Hash>, nil] Serialized tool calls or nil if none
+      def serialize_tool_calls(response)
+        tool_calls = safe_response_value(response, :tool_calls)
+        return nil if tool_calls.nil? || tool_calls.empty?
+
+        tool_calls.map do |id, tool_call|
+          if tool_call.respond_to?(:to_h)
+            tool_call.to_h
+          else
+            { id: id, name: tool_call[:name], arguments: tool_call[:arguments] }
+          end
+        end
+      end
+
       # Emergency fallback to mark execution as failed
       #
       # Uses update_all to bypass ActiveRecord callbacks and validations,

data/lib/ruby_llm/agents/redactor.rb

@@ -108,7 +108,7 @@ module RubyLLM
             redact_string(value, config)
           when defined?(ActiveRecord::Base) && ActiveRecord::Base
             # Convert ActiveRecord objects to safe references
-            { id: value.id, type: value.class.name }
+            { id: value&.id, type: value&.class&.name }
           else
             value
           end

data/lib/ruby_llm/agents/result.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    # Wrapper for agent execution results with full metadata
+    #
+    # Provides access to the response content along with execution details
+    # like token usage, cost, timing, and model information.
+    #
+    # @example Basic usage
+    #   result = MyAgent.call(query: "test")
+    #   result.content        # => processed response
+    #   result.input_tokens   # => 150
+    #   result.total_cost     # => 0.00025
+    #
+    # @example Backward compatible hash access
+    #   result[:key]          # delegates to result.content[:key]
+    #   result.dig(:nested, :key)
+    #
+    # @api public
+    class Result
+      extend ActiveSupport::Delegation
+
+      # @!attribute [r] content
+      #   @return [Hash, String] The processed response content
+      attr_reader :content
+
+      # @!group Token Usage
+      # @!attribute [r] input_tokens
+      #   @return [Integer, nil] Number of input tokens consumed
+      # @!attribute [r] output_tokens
+      #   @return [Integer, nil] Number of output tokens generated
+      # @!attribute [r] cached_tokens
+      #   @return [Integer] Number of tokens served from cache
+      # @!attribute [r] cache_creation_tokens
+      #   @return [Integer] Number of tokens used to create cache
+      attr_reader :input_tokens, :output_tokens, :cached_tokens, :cache_creation_tokens
+
+      # @!group Cost
+      # @!attribute [r] input_cost
+      #   @return [Float, nil] Cost of input tokens in USD
+      # @!attribute [r] output_cost
+      #   @return [Float, nil] Cost of output tokens in USD
+      # @!attribute [r] total_cost
+      #   @return [Float, nil] Total cost in USD
+      attr_reader :input_cost, :output_cost, :total_cost
+
+      # @!group Model Info
+      # @!attribute [r] model_id
+      #   @return [String, nil] The model that was requested
+      # @!attribute [r] chosen_model_id
+      #   @return [String, nil] The model that actually responded (may differ if fallback used)
+      # @!attribute [r] temperature
+      #   @return [Float, nil] Temperature setting used
+      attr_reader :model_id, :chosen_model_id, :temperature
+
+      # @!group Timing
+      # @!attribute [r] started_at
+      #   @return [Time, nil] When execution started
+      # @!attribute [r] completed_at
+      #   @return [Time, nil] When execution completed
+      # @!attribute [r] duration_ms
+      #   @return [Integer, nil] Execution duration in milliseconds
+      # @!attribute [r] time_to_first_token_ms
+      #   @return [Integer, nil] Time to first token (streaming only)
+      attr_reader :started_at, :completed_at, :duration_ms, :time_to_first_token_ms
+
+      # @!group Status
+      # @!attribute [r] finish_reason
+      #   @return [String, nil] Why generation stopped (stop, length, tool_calls, etc.)
+      # @!attribute [r] streaming
+      #   @return [Boolean] Whether streaming was enabled
+      attr_reader :finish_reason, :streaming
+
+      # @!group Error Info
+      # @!attribute [r] error_class
+      #   @return [String, nil] Exception class name if failed
+      # @!attribute [r] error_message
+      #   @return [String, nil] Exception message if failed
+      attr_reader :error_class, :error_message
+
+      # @!group Reliability
+      # @!attribute [r] attempts
+      #   @return [Array<Hash>] Details of each attempt (for retries/fallbacks)
+      # @!attribute [r] attempts_count
+      #   @return [Integer] Number of attempts made
+      attr_reader :attempts, :attempts_count
+
+      # @!group Tool Calls
+      # @!attribute [r] tool_calls
+      #   @return [Array<Hash>] Tool calls made during execution
+      # @!attribute [r] tool_calls_count
+      #   @return [Integer] Number of tool calls made
+      attr_reader :tool_calls, :tool_calls_count
+
+      # Creates a new Result instance
+      #
+      # @param content [Hash, String] The processed response content
+      # @param options [Hash] Execution metadata
+      def initialize(content:, **options)
+        @content = content
+
+        # Token usage
+        @input_tokens = options[:input_tokens]
+        @output_tokens = options[:output_tokens]
+        @cached_tokens = options[:cached_tokens] || 0
+        @cache_creation_tokens = options[:cache_creation_tokens] || 0
+
+        # Cost
+        @input_cost = options[:input_cost]
+        @output_cost = options[:output_cost]
+        @total_cost = options[:total_cost]
+
+        # Model info
+        @model_id = options[:model_id]
+        @chosen_model_id = options[:chosen_model_id] || options[:model_id]
+        @temperature = options[:temperature]
+
+        # Timing
+        @started_at = options[:started_at]
+        @completed_at = options[:completed_at]
+        @duration_ms = options[:duration_ms]
+        @time_to_first_token_ms = options[:time_to_first_token_ms]
+
+        # Status
+        @finish_reason = options[:finish_reason]
+        @streaming = options[:streaming] || false
+
+        # Error
+        @error_class = options[:error_class]
+        @error_message = options[:error_message]
+
+        # Reliability
+        @attempts = options[:attempts] || []
+        @attempts_count = options[:attempts_count] || 1
+
+        # Tool calls
+        @tool_calls = options[:tool_calls] || []
+        @tool_calls_count = options[:tool_calls_count] || 0
+      end
+
+      # Returns total tokens (input + output)
+      #
+      # @return [Integer] Total token count
+      def total_tokens
+        (input_tokens || 0) + (output_tokens || 0)
+      end
+
+      # Returns whether streaming was enabled
+      #
+      # @return [Boolean] true if streaming was used
+      def streaming?
+        streaming == true
+      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
+
+      # Returns whether a fallback model was used
+      #
+      # @return [Boolean] true if chosen_model_id differs from model_id
+      def used_fallback?
+        chosen_model_id.present? && chosen_model_id != model_id
+      end
+
+      # Returns whether the response was truncated due to max tokens
+      #
+      # @return [Boolean] true if finish_reason is "length"
+      def truncated?
+        finish_reason == "length"
+      end
+
+      # Returns whether tool calls were made during execution
+      #
+      # @return [Boolean] true if tool_calls_count > 0
+      def has_tool_calls?
+        tool_calls_count.to_i > 0
+      end
+
+      # Converts the result to a hash
+      #
+      # @return [Hash] All result data as a hash
+      def to_h
+        {
+          content: content,
+          input_tokens: input_tokens,
+          output_tokens: output_tokens,
+          total_tokens: total_tokens,
+          cached_tokens: cached_tokens,
+          cache_creation_tokens: cache_creation_tokens,
+          input_cost: input_cost,
+          output_cost: output_cost,
+          total_cost: total_cost,
+          model_id: model_id,
+          chosen_model_id: chosen_model_id,
+          temperature: temperature,
+          started_at: started_at,
+          completed_at: completed_at,
+          duration_ms: duration_ms,
+          time_to_first_token_ms: time_to_first_token_ms,
+          finish_reason: finish_reason,
+          streaming: streaming,
+          error_class: error_class,
+          error_message: error_message,
+          attempts_count: attempts_count,
+          attempts: attempts,
+          tool_calls: tool_calls,
+          tool_calls_count: tool_calls_count
+        }
+      end
+
+      # Delegate hash methods to content for backward compatibility
+      delegate :[], :dig, :keys, :values, :each, :map, to: :content, allow_nil: true
+
+      # Custom to_json that returns content as JSON for backward compatibility
+      #
+      # @param args [Array] Arguments passed to to_json
+      # @return [String] JSON representation
+      def to_json(*args)
+        content.to_json(*args)
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/version.rb

@@ -4,6 +4,6 @@ module RubyLLM
   module Agents
     # Current version of the RubyLLM::Agents gem
     # @return [String] Semantic version string
-    VERSION = "0.3.0"
+    VERSION = "0.3.3"
   end
 end

data/lib/ruby_llm/agents.rb

@@ -10,6 +10,7 @@ require_relative "agents/circuit_breaker"
 require_relative "agents/budget_tracker"
 require_relative "agents/alert_manager"
 require_relative "agents/attempt_tracker"
+require_relative "agents/result"
 require_relative "agents/inflections" if defined?(Rails)
 require_relative "agents/engine" if defined?(Rails::Engine)