ruby_llm-agents 0.3.1 → 0.3.3

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/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.1"
+    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)
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm-agents
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.3
 platform: ruby
 authors:
 - adham90
@@ -121,6 +121,7 @@ files:
 - app/models/ruby_llm/agents/execution/scopes.rb
 - app/services/ruby_llm/agents/agent_registry.rb
 - app/views/layouts/rubyllm/agents/application.html.erb
+- app/views/rubyllm/agents/agents/_agent.html.erb
 - app/views/rubyllm/agents/agents/_version_comparison.html.erb
 - app/views/rubyllm/agents/agents/index.html.erb
 - app/views/rubyllm/agents/agents/show.html.erb
@@ -155,6 +156,7 @@ files:
 - lib/generators/ruby_llm_agents/templates/add_prompts_migration.rb.tt
 - lib/generators/ruby_llm_agents/templates/add_routing_migration.rb.tt
 - lib/generators/ruby_llm_agents/templates/add_streaming_migration.rb.tt
+- lib/generators/ruby_llm_agents/templates/add_tool_calls_migration.rb.tt
 - lib/generators/ruby_llm_agents/templates/add_tracing_migration.rb.tt
 - lib/generators/ruby_llm_agents/templates/agent.rb.tt
 - lib/generators/ruby_llm_agents/templates/application_agent.rb.tt
@@ -175,6 +177,7 @@ files:
 - lib/ruby_llm/agents/instrumentation.rb
 - lib/ruby_llm/agents/redactor.rb
 - lib/ruby_llm/agents/reliability.rb
+- lib/ruby_llm/agents/result.rb
 - lib/ruby_llm/agents/version.rb
 homepage: https://github.com/adham90/ruby_llm-agents
 licenses: