ruby_llm-agents 3.10.0 → 3.12.0

data/app/views/ruby_llm/agents/tenants/show.html.erb

@@ -34,6 +34,11 @@
           <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M11 5H6a2 2 0 00-2 2v11a2 2 0 002 2h11a2 2 0 002-2v-5m-1.414-9.414a2 2 0 112.828 2.828L11.828 15H9v-2.828l8.586-8.586z" />
         </svg>
       <% end %>
+      <%= button_to refresh_counters_tenant_path(@tenant), method: :post, class: "text-gray-400 dark:text-gray-500 hover:text-gray-600 dark:hover:text-gray-300 transition-colors", title: "Refresh budget counters", form: { style: "display:inline" } do %>
+        <svg class="w-3.5 h-3.5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 4v5h.582m15.356 2A8.001 8.001 0 004.582 9m0 0H9m11 11v-5h-.581m0 0a8.003 8.003 0 01-15.357-2m15.357 2H15" />
+        </svg>
+      <% end %>
       <%= render "ruby_llm/agents/shared/doc_link" %>
     </div>
     <div class="font-mono text-xs text-gray-400 dark:text-gray-500 flex items-center gap-1.5 flex-wrap">
@@ -70,6 +75,153 @@
 </div>
 <div class="border-t border-gray-200 dark:border-gray-800 mb-2"></div>
 
+<!-- ── period comparison ──────────────── -->
+<% if @period_comparison %>
+  <%
+    pc = @period_comparison
+    tm = pc[:this_month]
+    lm = pc[:last_month]
+  %>
+  <div class="flex items-center gap-3 mt-6 mb-3">
+    <span class="text-[10px] font-medium text-gray-400 dark:text-gray-600 uppercase tracking-widest font-mono">this month vs last month</span>
+    <div class="flex-1 border-t border-gray-200 dark:border-gray-800"></div>
+  </div>
+
+  <div class="grid grid-cols-2 sm:grid-cols-4 gap-4 font-mono text-xs">
+    <% [
+      ["cost", tm[:cost], lm[:cost], pc[:cost_change], "$"],
+      ["avg cost/run", pc[:avg_cost_this], pc[:avg_cost_last], pc[:avg_cost_change], "$"],
+      ["runs", tm[:executions], lm[:executions], pc[:executions_change], ""],
+      ["tokens", tm[:tokens], lm[:tokens], pc[:tokens_change], ""]
+    ].each do |label, current, previous, change, prefix| %>
+      <div class="space-y-0.5">
+        <div class="text-[10px] text-gray-400 dark:text-gray-600 uppercase tracking-wider"><%= label %></div>
+        <div class="text-gray-900 dark:text-gray-200">
+          <% if prefix == "$" %>
+            $<%= number_with_precision(current, precision: 4) %>
+          <% else %>
+            <%= number_with_delimiter(current) %>
+          <% end %>
+        </div>
+        <div class="flex items-center gap-1">
+          <% if change != 0 %>
+            <span class="<%= change > 0 ? 'text-red-500' : 'text-green-500' %>">
+              <%= change > 0 ? "+" : "" %><%= change %>%
+            </span>
+          <% else %>
+            <span class="text-gray-400 dark:text-gray-600">—</span>
+          <% end %>
+          <span class="text-gray-400 dark:text-gray-600">
+            vs
+            <% if prefix == "$" %>
+              $<%= number_with_precision(previous, precision: 4) %>
+            <% else %>
+              <%= number_with_delimiter(previous) %>
+            <% end %>
+          </span>
+        </div>
+      </div>
+    <% end %>
+  </div>
+
+  <% if @error_count > 0 %>
+    <div class="mt-3 font-mono text-xs text-gray-500 dark:text-gray-400">
+      <span class="text-red-500">$<%= number_with_precision(@error_cost, precision: 4) %></span>
+      wasted on <span class="text-red-500"><%= number_with_delimiter(@error_count) %></span> failed executions
+      <% error_pct = total_cost.to_f > 0 ? (@error_cost.to_f / total_cost * 100).round(1) : 0 %>
+      <% if error_pct > 0 %>
+        (<%= error_pct %>% of total cost)
+      <% end %>
+    </div>
+  <% end %>
+<% end %>
+
+<!-- ── 30d cost trend ──────────────── -->
+<% if @daily_trend.present? %>
+  <div class="flex items-center gap-3 mt-6 mb-2">
+    <span class="text-[10px] font-medium text-gray-400 dark:text-gray-600 uppercase tracking-widest font-mono">last 30 days</span>
+    <div class="flex-1 border-t border-gray-200 dark:border-gray-800"></div>
+  </div>
+  <div id="tenant-trend-chart" style="width: 100%; height: 160px;"></div>
+  <script>
+  (function() {
+    const trendData = <%= raw @daily_trend.map { |date, stats|
+      { date: date.to_s, cost: (stats[:cost] || 0).to_f.round(6),
+        tokens: (stats[:tokens] || 0).to_i, count: (stats[:count] || 0).to_i }
+    }.to_json %>;
+
+    const costData = trendData.map(d => [new Date(d.date).getTime(), d.cost]);
+    const countData = trendData.map(d => [new Date(d.date).getTime(), d.count]);
+
+    function renderChart() {
+      window.__initHighchartsDefaults && window.__initHighchartsDefaults();
+      Highcharts.chart('tenant-trend-chart', {
+        chart: { backgroundColor: 'transparent', spacing: [5, 0, 0, 0] },
+        title: { text: null },
+        xAxis: {
+          type: 'datetime',
+          labels: { style: { color: chartColor('#6B7280', '#928374'), fontSize: '9px', fontFamily: 'ui-monospace, monospace' }, format: '{value:%b %d}' },
+          lineColor: 'transparent', tickLength: 0, gridLineWidth: 0
+        },
+        yAxis: [
+          {
+            title: { text: null }, min: 0,
+            labels: { style: { color: chartColor('#6B7280', '#928374'), fontSize: '9px', fontFamily: 'ui-monospace, monospace' }, format: '${value}' },
+            gridLineColor: chartColorAlpha('rgba(107, 114, 128, 0.08)', 146, 131, 116, 0.08)
+          },
+          {
+            title: { text: null }, min: 0, opposite: true, allowDecimals: false,
+            labels: { style: { color: chartColor('#6B7280', '#928374'), fontSize: '9px', fontFamily: 'ui-monospace, monospace' } },
+            gridLineWidth: 0
+          }
+        ],
+        legend: { enabled: false },
+        credits: { enabled: false },
+        tooltip: {
+          backgroundColor: chartColorAlpha('rgba(0, 0, 0, 0.85)', 40, 40, 40, 0.95),
+          borderColor: 'transparent', borderRadius: 3,
+          style: { color: chartColor('#E5E7EB', '#ebdbb2'), fontSize: '10px', fontFamily: 'ui-monospace, monospace' },
+          shared: true,
+          formatter: function() {
+            let html = '<span style="color:' + chartColor('#9CA3AF', '#bdae93') + '">' + Highcharts.dateFormat('%b %d', this.x) + '</span>';
+            let d = trendData.find(d => new Date(d.date).getTime() === this.x);
+            if (d) {
+              html += '<br/>cost: <b>$' + d.cost.toFixed(4) + '</b>';
+              html += '<br/>runs: <b>' + d.count + '</b>';
+              html += '<br/>tokens: <b>' + d.tokens.toLocaleString() + '</b>';
+            }
+            return html;
+          }
+        },
+        series: [
+          {
+            name: 'cost', type: 'areaspline', yAxis: 0, data: costData,
+            color: chartColor('#8B5CF6', '#d3869b'),
+            lineWidth: 1.5, marker: { enabled: false, states: { hover: { enabled: true, radius: 2 } } },
+            fillColor: { linearGradient: { x1: 0, y1: 0, x2: 0, y2: 1 },
+              stops: [[0, chartColorAlpha('rgba(139, 92, 246, 0.12)', 211, 134, 155, 0.12)], [1, chartColorAlpha('rgba(139, 92, 246, 0)', 211, 134, 155, 0)]] }
+          },
+          {
+            name: 'runs', type: 'column', yAxis: 1, data: countData,
+            color: chartColorAlpha('rgba(107, 114, 128, 0.15)', 146, 131, 116, 0.15),
+            borderWidth: 0, pointPadding: 0.1, groupPadding: 0
+          }
+        ]
+      });
+    }
+
+    function waitForHighcharts(attempts) {
+      if (typeof Highcharts !== 'undefined') { renderChart(); }
+      else if (attempts > 0) { setTimeout(function() { waitForHighcharts(attempts - 1); }, 100); }
+    }
+
+    document.readyState === 'loading'
+      ? document.addEventListener('DOMContentLoaded', function() { waitForHighcharts(50); })
+      : waitForHighcharts(50);
+  })();
+  </script>
+<% end %>
+
 <% if has_any_limit %>
   <!-- ── budget ──────────────────────── -->
   <div class="flex items-center gap-3 mt-6 mb-3">
@@ -166,6 +318,79 @@
   </div>
 <% end %>
 
+<% if @usage_by_agent.present? %>
+  <!-- ── usage by agent ──────────────────── -->
+  <div class="flex items-center gap-3 mt-6 mb-3">
+    <span class="text-[10px] font-medium text-gray-400 dark:text-gray-600 uppercase tracking-widest font-mono">usage by agent</span>
+    <div class="flex-1 border-t border-gray-200 dark:border-gray-800"></div>
+  </div>
+
+  <!-- Column headers -->
+  <div class="flex items-center gap-3 px-2 -mx-2 font-mono text-[10px] text-gray-400 dark:text-gray-600 uppercase tracking-wider mb-1">
+    <span class="flex-[2] min-w-0">agent</span>
+    <span class="w-16 flex-shrink-0 text-right">runs</span>
+    <span class="w-24 flex-shrink-0 text-right">cost</span>
+    <span class="w-20 flex-shrink-0 text-right">avg cost</span>
+    <span class="w-24 flex-shrink-0 text-right">tokens</span>
+    <span class="w-20 flex-shrink-0 text-right">avg tokens</span>
+  </div>
+
+  <div class="font-mono text-xs space-y-px">
+    <% @usage_by_agent.sort_by { |_, v| -v[:cost] }.each do |agent_type, stats| %>
+      <%
+        avg_cost = stats[:count] > 0 ? (stats[:cost].to_f / stats[:count]) : 0
+        avg_tokens = stats[:count] > 0 ? (stats[:tokens].to_f / stats[:count]).round : 0
+      %>
+      <div class="flex items-center gap-3 py-1 px-2 -mx-2 rounded hover:bg-gray-100 dark:hover:bg-gray-800/50">
+        <span class="flex-[2] min-w-0 truncate">
+          <%= link_to agent_type.to_s.demodulize, ruby_llm_agents.agent_path(agent_type),
+              class: "text-gray-900 dark:text-gray-200 hover:text-gray-600 dark:hover:text-gray-400" %>
+        </span>
+        <span class="w-16 flex-shrink-0 text-right text-gray-500 dark:text-gray-400"><%= number_with_delimiter(stats[:count]) %></span>
+        <span class="w-24 flex-shrink-0 text-right text-gray-800 dark:text-gray-200">$<%= number_with_precision(stats[:cost], precision: 4) %></span>
+        <span class="w-20 flex-shrink-0 text-right text-gray-500 dark:text-gray-400">$<%= number_with_precision(avg_cost, precision: 4) %></span>
+        <span class="w-24 flex-shrink-0 text-right text-gray-600 dark:text-gray-400"><%= number_with_delimiter(stats[:tokens]) %></span>
+        <span class="w-20 flex-shrink-0 text-right text-gray-500 dark:text-gray-400"><%= number_with_delimiter(avg_tokens) %></span>
+      </div>
+    <% end %>
+  </div>
+<% end %>
+
+<% if @usage_by_model.present? %>
+  <!-- ── usage by model ──────────────────── -->
+  <div class="flex items-center gap-3 mt-6 mb-3">
+    <span class="text-[10px] font-medium text-gray-400 dark:text-gray-600 uppercase tracking-widest font-mono">usage by model</span>
+    <div class="flex-1 border-t border-gray-200 dark:border-gray-800"></div>
+  </div>
+
+  <!-- Column headers -->
+  <div class="flex items-center gap-3 px-2 -mx-2 font-mono text-[10px] text-gray-400 dark:text-gray-600 uppercase tracking-wider mb-1">
+    <span class="flex-[2] min-w-0">model</span>
+    <span class="w-16 flex-shrink-0 text-right">runs</span>
+    <span class="w-24 flex-shrink-0 text-right">cost</span>
+    <span class="w-20 flex-shrink-0 text-right">avg cost</span>
+    <span class="w-24 flex-shrink-0 text-right">tokens</span>
+    <span class="w-16 flex-shrink-0 text-right">% of cost</span>
+  </div>
+
+  <div class="font-mono text-xs space-y-px">
+    <% @usage_by_model.sort_by { |_, v| -v[:cost] }.each do |model_id, stats| %>
+      <%
+        avg_cost = stats[:count] > 0 ? (stats[:cost].to_f / stats[:count]) : 0
+        cost_pct = total_cost.to_f > 0 ? (stats[:cost].to_f / total_cost * 100).round(1) : 0
+      %>
+      <div class="flex items-center gap-3 py-1 px-2 -mx-2 rounded hover:bg-gray-100 dark:hover:bg-gray-800/50">
+        <span class="flex-[2] min-w-0 truncate text-gray-900 dark:text-gray-200"><%= model_id %></span>
+        <span class="w-16 flex-shrink-0 text-right text-gray-500 dark:text-gray-400"><%= number_with_delimiter(stats[:count]) %></span>
+        <span class="w-24 flex-shrink-0 text-right text-gray-800 dark:text-gray-200">$<%= number_with_precision(stats[:cost], precision: 4) %></span>
+        <span class="w-20 flex-shrink-0 text-right text-gray-500 dark:text-gray-400">$<%= number_with_precision(avg_cost, precision: 4) %></span>
+        <span class="w-24 flex-shrink-0 text-right text-gray-600 dark:text-gray-400"><%= number_with_delimiter(stats[:tokens]) %></span>
+        <span class="w-16 flex-shrink-0 text-right text-gray-400 dark:text-gray-600"><%= cost_pct %>%</span>
+      </div>
+    <% end %>
+  </div>
+<% end %>
+
 <!-- ── recent executions ──────────────────── -->
 <div class="flex items-center gap-3 mt-6 mb-3">
   <span class="text-[10px] font-medium text-gray-400 dark:text-gray-600 uppercase tracking-widest font-mono">recent executions</span>

data/config/routes.rb

@@ -4,7 +4,11 @@ RubyLLM::Agents::Engine.routes.draw do
   root to: "dashboard#index"
   get "chart_data", to: "dashboard#chart_data"
 
-  resources :agents, only: [:index, :show]
+  resources :agents, only: [:index, :show, :update] do
+    member do
+      delete :reset_overrides
+    end
+  end
 
   resources :executions, only: [:index, :show] do
     collection do
@@ -15,9 +19,13 @@ RubyLLM::Agents::Engine.routes.draw do
 
   resources :requests, only: [:index, :show]
 
-  resources :tenants, only: [:index, :show, :edit, :update]
+  resources :tenants, only: [:index, :show, :edit, :update] do
+    member do
+      post :refresh_counters
+    end
+  end
 
-  # Redirect old analytics route to dashboard
-  get "analytics", to: redirect("/")
+  get "analytics", to: "analytics#index", as: :analytics
+  get "analytics/chart_data", to: "analytics#chart_data", as: :analytics_chart_data
   resource :system_config, only: [:show], controller: "system_config"
 end

data/lib/generators/ruby_llm_agents/templates/create_overrides_migration.rb.tt

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# Migration to create the agent overrides table for dashboard-managed settings
+#
+# This table stores per-agent setting overrides that are managed through
+# the dashboard UI. Only fields declared as `overridable: true` in the
+# agent DSL can be overridden.
+#
+# Run with: rails db:migrate
+class CreateRubyLLMAgentsOverrides < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :ruby_llm_agents_overrides do |t|
+      # The agent class name (e.g., "SupportAgent")
+      t.string :agent_type, null: false
+
+      # JSON hash of overridden settings
+      # Format: { "model" => "gpt-4o-mini", "temperature" => 0.5 }
+      t.json :settings, null: false, default: {}
+
+      # Who last changed the override (optional audit trail)
+      t.string :updated_by
+
+      t.timestamps
+    end
+
+    add_index :ruby_llm_agents_overrides, :agent_type, unique: true
+  end
+end

data/lib/generators/ruby_llm_agents/templates/skills/AGENTS.md.tt

@@ -110,7 +110,7 @@ streaming true  # Enable streaming by default
 ### Tools
 
 ```ruby
-tools [SearchTool, CalculatorTool]  # Make tools available to agent
+tools SearchTool, CalculatorTool  # Make tools available to agent
 ```
 
 ### Extended Thinking

data/lib/generators/ruby_llm_agents/templates/skills/TOOLS.md.tt

@@ -72,7 +72,7 @@ module Agents
   class ResearchAgent < ApplicationAgent
     model "gpt-4o"
 
-    tools [SearchTool, CalculatorTool, WebFetchTool]
+    tools SearchTool, CalculatorTool, WebFetchTool
 
     param :question, required: true
 

data/lib/generators/ruby_llm_agents/upgrade_generator.rb

@@ -117,6 +117,20 @@ module RubyLlmAgents
       )
     end
 
+    # Create overrides table for dashboard-managed agent settings
+    def create_overrides_migration
+      if table_exists?(:ruby_llm_agents_overrides)
+        say_status :skip, "ruby_llm_agents_overrides table already exists", :yellow
+        return
+      end
+
+      say_status :upgrade, "Creating agent overrides table", :blue
+      migration_template(
+        "create_overrides_migration.rb.tt",
+        File.join(db_migrate_path, "create_ruby_llm_agents_overrides.rb")
+      )
+    end
+
     def suggest_config_consolidation
       ruby_llm_initializer = File.join(destination_root, "config/initializers/ruby_llm.rb")
       agents_initializer = File.join(destination_root, "config/initializers/ruby_llm_agents.rb")

data/lib/ruby_llm/agents/base_agent.rb

@@ -47,6 +47,8 @@ module RubyLLM
       extend DSL::Reliability
       extend DSL::Caching
       extend DSL::Queryable
+      extend DSL::Knowledge
+      include DSL::Knowledge::InstanceMethods
       include CacheHelper
 
       class << self
@@ -170,6 +172,7 @@ module RubyLLM
             tools: tools.map { |t| t.respond_to?(:name) ? t.name : t.to_s },
             parameters: params.transform_values { |v| v.slice(:type, :required, :default, :desc) },
             thinking: thinking_config,
+            cache_prompts: cache_prompts || nil,
             caching: caching_config,
             reliability: reliability_configured? ? reliability_config : nil
           }.compact
@@ -232,12 +235,18 @@ module RubyLLM
         # Enables or returns streaming mode for this agent
         #
         # @param value [Boolean, nil] Whether to enable streaming
+        # @param overridable [Boolean, nil] When true, this field can be changed from the dashboard
         # @return [Boolean] The current streaming setting
-        def streaming(value = nil)
+        def streaming(value = nil, overridable: nil)
           @streaming = value unless value.nil?
-          return @streaming unless @streaming.nil?
+          register_overridable(:streaming) if overridable
+          base = if @streaming.nil?
+            superclass.respond_to?(:streaming) ? superclass.streaming : default_streaming
+          else
+            @streaming
+          end
 
-          superclass.respond_to?(:streaming) ? superclass.streaming : default_streaming
+          apply_override(:streaming, base)
         end
 
         # @!endgroup
@@ -246,10 +255,10 @@ module RubyLLM
 
         # Sets or returns the tools available to this agent
         #
-        # @param tool_classes [Array<Class>] Tool classes to make available
+        # @param tool_classes [Class, Array<Class>] Tool classes to make available
         # @return [Array<Class>] The current tools
-        def tools(tool_classes = nil)
-          @tools = Array(tool_classes) if tool_classes
+        def tools(*tool_classes)
+          @tools = tool_classes.flatten if tool_classes.any?
           @tools || (superclass.respond_to?(:tools) ? superclass.tools : [])
         end
 
@@ -260,10 +269,14 @@ module RubyLLM
         # Sets or returns the temperature for LLM responses
         #
         # @param value [Float, nil] Temperature value (0.0-2.0)
+        # @param overridable [Boolean, nil] When true, this field can be changed from the dashboard
         # @return [Float] The current temperature setting
-        def temperature(value = nil)
+        def temperature(value = nil, overridable: nil)
           @temperature = value if value
-          @temperature || (superclass.respond_to?(:temperature) ? superclass.temperature : default_temperature)
+          register_overridable(:temperature) if overridable
+          base = @temperature || (superclass.respond_to?(:temperature) ? superclass.temperature : default_temperature)
+
+          apply_override(:temperature, base)
         end
 
         # @!endgroup
@@ -387,14 +400,19 @@ module RubyLLM
       # System prompt for LLM instructions
       #
       # If a class-level `system` DSL is defined, it will be used.
-      # Otherwise returns nil.
+      # Knowledge entries declared via `knows` are auto-appended.
       #
       # @return [String, nil] System instructions, or nil for none
       def system_prompt
         system_config = self.class.system_config
-        return resolve_prompt_from_config(system_config) if system_config
+        base = system_config ? resolve_prompt_from_config(system_config) : nil
 
-        nil
+        knowledge = compiled_knowledge
+        if knowledge.present?
+          base ? "#{base}\n\n#{knowledge}" : knowledge
+        else
+          base
+        end
       end
 
       # Assistant prefill to prime the model's response
@@ -512,6 +530,7 @@ module RubyLLM
           tenant: resolve_tenant,
           skip_cache: @options[:skip_cache],
           stream_block: (block if streaming_enabled?),
+          stream_events: @options[:stream_events] == true,
           parent_execution_id: @parent_execution_id,
           root_execution_id: @root_execution_id,
           debug: @options[:debug],
@@ -552,36 +571,33 @@ module RubyLLM
         end
       end
 
-      # Resolves tools for this execution
+      # Returns the description for a tool class
       #
-      # Agent classes in the tools list are automatically wrapped as
-      # RubyLLM::Tool subclasses via AgentTool.for. Regular tool classes
-      # pass through unchanged.
+      # @param tool [Class] A tool class
+      # @return [String] The tool's description
+      def tool_description_for(tool)
+        if tool.respond_to?(:description) && tool.description
+          tool.description
+        elsif tool.is_a?(Class) && tool < RubyLLM::Tool
+          tool.new.respond_to?(:description) ? tool.new.description : tool.name.to_s
+        else
+          tool.name.to_s
+        end
+      end
+
+      # Resolves tools for this execution
       #
       # @return [Array<Class>] Tool classes to use
       # @raise [ArgumentError] If duplicate tool names are detected
       def resolved_tools
-        raw = if self.class.method_defined?(:tools, false)
+        all_tools = if self.class.method_defined?(:tools, false)
           tools
         else
           self.class.tools
         end
 
-        wrapped = raw.map { |tool_class| wrap_if_agent(tool_class) }
-        detect_duplicate_tool_names!(wrapped)
-        wrapped
-      end
-
-      # Wraps an agent class as a tool, or returns the tool class as-is.
-      #
-      # @param tool_class [Class] A tool or agent class
-      # @return [Class] The original or wrapped class
-      def wrap_if_agent(tool_class)
-        if tool_class.respond_to?(:ancestors) && tool_class.ancestors.include?(RubyLLM::Agents::BaseAgent)
-          AgentTool.for(tool_class)
-        else
-          tool_class
-        end
+        detect_duplicate_tool_names!(all_tools)
+        all_tools
       end
 
       # Raises if two tools resolve to the same name.
@@ -720,9 +736,10 @@ module RubyLLM
       # @param context [Pipeline::Context] The execution context
       # @return [void] Sets context.output with the result
       def execute(context)
+        @context = context
         client = build_client(context)
 
-        # Make context available to AgentTool instances during tool execution
+        # Make context available to Tool instances during tool execution
         previous_context = Thread.current[:ruby_llm_agents_caller_context]
         Thread.current[:ruby_llm_agents_caller_context] = context
 
@@ -759,9 +776,20 @@ module RubyLLM
         end
         client = client.with_temperature(temperature)
 
-        client = client.with_instructions(system_prompt) if system_prompt
+        use_prompt_caching = self.class.cache_prompts && anthropic_model?(effective_model)
+
+        if system_prompt
+          sys_content = if use_prompt_caching
+            RubyLLM::Providers::Anthropic::Content.new(system_prompt, cache: true)
+          else
+            system_prompt
+          end
+          client = client.with_instructions(sys_content)
+        end
+
         client = client.with_schema(schema) if schema
         client = client.with_tools(*resolved_tools) if resolved_tools.any?
+        apply_tool_prompt_caching(client) if use_prompt_caching && resolved_tools.any?
         client = setup_tool_tracking(client) if resolved_tools.any?
         client = apply_messages(client, resolved_messages) if resolved_messages.any?
         client = client.with_thinking(**resolved_thinking) if resolved_thinking
@@ -817,7 +845,11 @@ module RubyLLM
 
           response = client.complete do |chunk|
             first_chunk_at ||= Time.current
-            context.stream_block.call(chunk)
+            if context.stream_events?
+              context.stream_block.call(StreamEvent.new(:chunk, {content: chunk.content}))
+            else
+              context.stream_block.call(chunk)
+            end
           end
 
           if first_chunk_at
@@ -843,7 +875,11 @@ module RubyLLM
 
         response = client.ask(user_prompt, **ask_opts) do |chunk|
           first_chunk_at ||= Time.current
-          context.stream_block.call(chunk)
+          if context.stream_events?
+            context.stream_block.call(StreamEvent.new(:chunk, {content: chunk.content}))
+          else
+            context.stream_block.call(chunk)
+          end
         end
 
         if first_chunk_at
@@ -867,6 +903,14 @@ module RubyLLM
         # Store tracked tool calls in context for instrumentation
         context[:tool_calls] = @tracked_tool_calls if @tracked_tool_calls.any?
 
+        # Capture Anthropic prompt caching metrics
+        if response.respond_to?(:cached_tokens) && response.cached_tokens&.positive?
+          context[:cached_tokens] = response.cached_tokens
+        end
+        if response.respond_to?(:cache_creation_tokens) && response.cache_creation_tokens&.positive?
+          context[:cache_creation_tokens] = response.cache_creation_tokens
+        end
+
         calculate_costs(response, context) if context.input_tokens
       end
 
@@ -901,6 +945,37 @@ module RubyLLM
         nil
       end
 
+      # Checks whether the given model is served by Anthropic
+      #
+      # Looks up the model's provider in the registry, falling back to
+      # model ID pattern matching when the registry is unavailable.
+      #
+      # @param model_id [String] The model ID
+      # @return [Boolean]
+      def anthropic_model?(model_id)
+        info = find_model_info(model_id)
+        return info.provider.to_s == "anthropic" if info&.provider
+
+        # Fallback: match common Anthropic model ID patterns
+        model_id.to_s.match?(/\Aclaude/i)
+      end
+
+      # Adds cache_control to the last tool so Anthropic caches all tool definitions
+      #
+      # Uses a singleton method override on the last tool instance so the
+      # cache_control is merged into the API payload by RubyLLM's
+      # Tools.function_for without mutating the tool class.
+      #
+      # @param client [RubyLLM::Chat] The chat client with tools already added
+      def apply_tool_prompt_caching(client)
+        last_tool = client.tools.values.last
+        return unless last_tool
+
+        last_tool.define_singleton_method(:provider_params) do
+          super().merge(cache_control: {type: "ephemeral"})
+        end
+      end
+
       # Builds a Result object from the response
       #
       # @param content [Object] The processed content
@@ -993,8 +1068,54 @@ module RubyLLM
       # @return [RubyLLM::Chat] Client with tracking callbacks
       def setup_tool_tracking(client)
         client
-          .on_tool_call { |tool_call| start_tracking_tool_call(tool_call) }
-          .on_tool_result { |result| complete_tool_call_tracking(result) }
+          .on_tool_call do |tool_call|
+            start_tracking_tool_call(tool_call)
+            emit_stream_event(:tool_start, tool_call_start_data(tool_call))
+          end
+          .on_tool_result do |result|
+            end_data = tool_call_end_data(result)
+            complete_tool_call_tracking(result)
+            emit_stream_event(:tool_end, end_data)
+          end
+      end
+
+      # Emits a StreamEvent to the caller's stream block when stream_events is enabled
+      #
+      # @param type [Symbol] Event type (:chunk, :tool_start, :tool_end, :error)
+      # @param data [Hash] Event-specific data
+      def emit_stream_event(type, data)
+        return unless @context&.stream_block && @context.stream_events?
+
+        @context.stream_block.call(StreamEvent.new(type, data))
+      end
+
+      # Builds data hash for a tool_start event
+      #
+      # @param tool_call [Object] The tool call object from RubyLLM
+      # @return [Hash] Event data
+      def tool_call_start_data(tool_call)
+        {
+          tool_name: extract_tool_call_value(tool_call, :name),
+          input: extract_tool_call_value(tool_call, :arguments) || {}
+        }.compact
+      end
+
+      # Builds data hash for a tool_end event from the pending tool call
+      #
+      # @param result [Object] The tool result
+      # @return [Hash] Event data
+      def tool_call_end_data(result)
+        return {} unless @pending_tool_call
+
+        started_at = @pending_tool_call[:started_at]
+        duration_ms = started_at ? ((Time.current - started_at) * 1000).to_i : nil
+        result_data = extract_tool_result(result)
+
+        {
+          tool_name: @pending_tool_call[:name],
+          status: result_data[:status],
+          duration_ms: duration_ms
+        }.compact
       end
 
       # Starts tracking a tool call