ruby_llm-agents 0.3.1 → 0.3.4

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.4"
   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.4
 platform: ruby
 authors:
 - adham90
@@ -65,20 +65,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.0'
-- !ruby/object:Gem::Dependency
-  name: chartkick
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '5.0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '5.0'
 - !ruby/object:Gem::Dependency
   name: csv
   requirement: !ruby/object:Gem::Requirement
@@ -104,7 +90,6 @@ extra_rdoc_files: []
 files:
 - LICENSE.txt
 - README.md
-- app/channels/ruby_llm/agents/executions_channel.rb
 - app/controllers/concerns/ruby_llm/agents/filterable.rb
 - app/controllers/concerns/ruby_llm/agents/paginatable.rb
 - app/controllers/ruby_llm/agents/agents_controller.rb
@@ -112,25 +97,24 @@ files:
 - app/controllers/ruby_llm/agents/executions_controller.rb
 - app/controllers/ruby_llm/agents/settings_controller.rb
 - app/helpers/ruby_llm/agents/application_helper.rb
-- app/javascript/ruby_llm/agents/controllers/filter_controller.js
-- app/javascript/ruby_llm/agents/controllers/index.js
-- app/javascript/ruby_llm/agents/controllers/refresh_controller.js
 - app/models/ruby_llm/agents/execution.rb
 - app/models/ruby_llm/agents/execution/analytics.rb
 - app/models/ruby_llm/agents/execution/metrics.rb
 - 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
 - app/views/rubyllm/agents/dashboard/_action_center.html.erb
+- app/views/rubyllm/agents/dashboard/_agent_comparison.html.erb
 - app/views/rubyllm/agents/dashboard/_alerts_feed.html.erb
 - app/views/rubyllm/agents/dashboard/_breaker_strip.html.erb
 - app/views/rubyllm/agents/dashboard/_budgets_bar.html.erb
 - app/views/rubyllm/agents/dashboard/_execution_item.html.erb
 - app/views/rubyllm/agents/dashboard/_now_strip.html.erb
-- app/views/rubyllm/agents/dashboard/_now_strip_values.html.erb
+- app/views/rubyllm/agents/dashboard/_top_errors.html.erb
 - app/views/rubyllm/agents/dashboard/index.html.erb
 - app/views/rubyllm/agents/executions/_execution.html.erb
 - app/views/rubyllm/agents/executions/_filters.html.erb
@@ -140,8 +124,10 @@ files:
 - app/views/rubyllm/agents/executions/index.turbo_stream.erb
 - app/views/rubyllm/agents/executions/show.html.erb
 - app/views/rubyllm/agents/settings/show.html.erb
+- app/views/rubyllm/agents/shared/_breadcrumbs.html.erb
 - app/views/rubyllm/agents/shared/_executions_table.html.erb
 - app/views/rubyllm/agents/shared/_filter_dropdown.html.erb
+- app/views/rubyllm/agents/shared/_nav_link.html.erb
 - app/views/rubyllm/agents/shared/_select_dropdown.html.erb
 - app/views/rubyllm/agents/shared/_stat_card.html.erb
 - app/views/rubyllm/agents/shared/_status_badge.html.erb
@@ -155,6 +141,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
@@ -166,6 +153,13 @@ files:
 - lib/ruby_llm/agents/alert_manager.rb
 - lib/ruby_llm/agents/attempt_tracker.rb
 - lib/ruby_llm/agents/base.rb
+- lib/ruby_llm/agents/base/caching.rb
+- lib/ruby_llm/agents/base/cost_calculation.rb
+- lib/ruby_llm/agents/base/dsl.rb
+- lib/ruby_llm/agents/base/execution.rb
+- lib/ruby_llm/agents/base/reliability_execution.rb
+- lib/ruby_llm/agents/base/response_building.rb
+- lib/ruby_llm/agents/base/tool_tracking.rb
 - lib/ruby_llm/agents/budget_tracker.rb
 - lib/ruby_llm/agents/circuit_breaker.rb
 - lib/ruby_llm/agents/configuration.rb
@@ -175,6 +169,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:

data/app/channels/ruby_llm/agents/executions_channel.rb

@@ -1,46 +0,0 @@
-# frozen_string_literal: true
-
-module RubyLLM
-  module Agents
-    # ActionCable channel for real-time execution updates
-    #
-    # Broadcasts execution create/update events to subscribed clients.
-    # Used by the dashboard to show live execution status changes.
-    #
-    # Inherits from the host app's ApplicationCable::Channel (note the :: prefix
-    # to reference the root namespace, not the engine's namespace).
-    #
-    # @example JavaScript subscription
-    #   import { createConsumer } from "@rails/actioncable"
-    #   const consumer = createConsumer()
-    #   consumer.subscriptions.create("RubyLLM::Agents::ExecutionsChannel", {
-    #     received(data) {
-    #       console.log("Execution update:", data)
-    #     }
-    #   })
-    #
-    # @see Execution#broadcast_execution Broadcast trigger
-    # @api private
-    class ExecutionsChannel < ::ApplicationCable::Channel
-      # Subscribes the client to the executions broadcast stream
-      #
-      # Called automatically when a client connects to this channel.
-      # Streams from the "ruby_llm_agents:executions" channel name.
-      #
-      # @return [void]
-      def subscribed
-        stream_from "ruby_llm_agents:executions"
-        logger.info "[RubyLLM::Agents] Client subscribed to executions channel"
-      end
-
-      # Cleans up when a client disconnects
-      #
-      # Called automatically when the WebSocket connection is closed.
-      #
-      # @return [void]
-      def unsubscribed
-        logger.info "[RubyLLM::Agents] Client unsubscribed from executions channel"
-      end
-    end
-  end
-end

data/app/javascript/ruby_llm/agents/controllers/filter_controller.js

@@ -1,56 +0,0 @@
-import { Controller } from "@hotwired/stimulus"
-
-// Filter controller for live filtering of executions
-//
-// Usage:
-//   <form data-controller="filter">
-//     <select data-action="change->filter#submit">...</select>
-//   </form>
-//
-export default class extends Controller {
-  static targets = ["form"]
-  static values = {
-    debounce: { type: Number, default: 300 }
-  }
-
-  connect() {
-    this.timeout = null
-  }
-
-  disconnect() {
-    if (this.timeout) {
-      clearTimeout(this.timeout)
-    }
-  }
-
-  // Submit the form with debouncing
-  submit(event) {
-    if (this.timeout) {
-      clearTimeout(this.timeout)
-    }
-
-    this.timeout = setTimeout(() => {
-      this.element.requestSubmit()
-    }, this.debounceValue)
-  }
-
-  // Submit immediately without debounce
-  submitNow(event) {
-    this.element.requestSubmit()
-  }
-
-  // Update URL with current filter state
-  updateUrl() {
-    const formData = new FormData(this.element)
-    const params = new URLSearchParams()
-
-    for (const [key, value] of formData) {
-      if (value) {
-        params.set(key, value)
-      }
-    }
-
-    const newUrl = `${window.location.pathname}?${params.toString()}`
-    window.history.pushState({}, "", newUrl)
-  }
-}

data/app/javascript/ruby_llm/agents/controllers/index.js

@@ -1,12 +0,0 @@
-// Entry point for RubyLLM::Agents Stimulus controllers
-// Import and register controllers with your Stimulus application
-
-import FilterController from "./filter_controller"
-import RefreshController from "./refresh_controller"
-
-export { FilterController, RefreshController }
-
-export function registerControllers(application) {
-  application.register("filter", FilterController)
-  application.register("refresh", RefreshController)
-}

data/app/javascript/ruby_llm/agents/controllers/refresh_controller.js

@@ -1,83 +0,0 @@
-import { Controller } from "@hotwired/stimulus"
-
-// Auto-refresh controller for dashboard with toggle support
-//
-// Usage:
-//   <div data-controller="refresh"
-//        data-refresh-interval-value="30000"
-//        data-refresh-enabled-value="false">
-//     <button data-action="refresh#toggle" data-refresh-target="button">
-//       Live Poll: Off
-//     </button>
-//   </div>
-//
-export default class extends Controller {
-  static values = {
-    interval: { type: Number, default: 30000 },
-    enabled: { type: Boolean, default: false }
-  }
-
-  static targets = ["button", "indicator"]
-
-  connect() {
-    this.updateUI()
-    if (this.enabledValue) {
-      this.startRefresh()
-    }
-  }
-
-  disconnect() {
-    this.stopRefresh()
-  }
-
-  toggle() {
-    this.enabledValue = !this.enabledValue
-
-    if (this.enabledValue) {
-      this.startRefresh()
-      this.refresh() // Immediate refresh when enabled
-    } else {
-      this.stopRefresh()
-    }
-
-    this.updateUI()
-  }
-
-  startRefresh() {
-    if (this.intervalValue > 0 && !this.timer) {
-      this.timer = setInterval(() => this.refresh(), this.intervalValue)
-    }
-  }
-
-  stopRefresh() {
-    if (this.timer) {
-      clearInterval(this.timer)
-      this.timer = null
-    }
-  }
-
-  refresh() {
-    const frame = this.element.closest("turbo-frame") ||
-                  this.element.querySelector("turbo-frame")
-
-    if (frame && typeof frame.reload === "function") {
-      frame.reload()
-    }
-  }
-
-  updateUI() {
-    if (this.hasButtonTarget) {
-      if (this.enabledValue) {
-        this.buttonTarget.classList.remove("bg-gray-100", "text-gray-600")
-        this.buttonTarget.classList.add("bg-green-100", "text-green-700")
-      } else {
-        this.buttonTarget.classList.remove("bg-green-100", "text-green-700")
-        this.buttonTarget.classList.add("bg-gray-100", "text-gray-600")
-      }
-    }
-
-    if (this.hasIndicatorTarget) {
-      this.indicatorTarget.textContent = this.enabledValue ? "On" : "Off"
-    }
-  }
-}