ruby_llm-agents 3.8.0 → 3.10.0

data/lib/ruby_llm/agents/base_agent.rb

@@ -332,6 +332,14 @@ module RubyLLM
       # @param temperature [Float] Override the class-level temperature
       # @param options [Hash] Agent parameters defined via the param DSL
       def initialize(model: self.class.model, temperature: self.class.temperature, **options)
+        # Merge tracker defaults (shared options like tenant) — explicit opts win
+        tracker = Thread.current[:ruby_llm_agents_tracker]
+        if tracker
+          options = tracker.defaults.merge(options)
+          @_track_request_id = tracker.request_id
+          @_track_tags = tracker.tags
+        end
+
         @ask_message = options.delete(:_ask_message)
         @parent_execution_id = options.delete(:_parent_execution_id)
         @root_execution_id = options.delete(:_root_execution_id)
@@ -506,6 +514,7 @@ module RubyLLM
           stream_block: (block if streaming_enabled?),
           parent_execution_id: @parent_execution_id,
           root_execution_id: @root_execution_id,
+          debug: @options[:debug],
           options: execution_options
         )
       end
@@ -721,6 +730,12 @@ module RubyLLM
         capture_response(response, context)
         result = build_result(process_response(response), response, context)
         context.output = result
+      rescue RubyLLM::Agents::CancelledError
+        context.output = Result.new(content: nil, cancelled: true)
+      rescue RubyLLM::UnauthorizedError, RubyLLM::ForbiddenError => e
+        raise_with_setup_hint(e, context)
+      rescue RubyLLM::ModelNotFoundError => e
+        raise_with_model_hint(e, context)
       ensure
         Thread.current[:ruby_llm_agents_caller_context] = previous_context
       end
@@ -733,12 +748,16 @@ module RubyLLM
         effective_model = context&.model || model
         chat_opts = {model: effective_model}
 
-        # Pass scoped RubyLLM context for thread-safe per-tenant API keys
+        # Use scoped RubyLLM::Context for thread-safe per-tenant API keys.
+        # RubyLLM::Context#chat creates a Chat with the scoped config,
+        # so we call .chat on the context instead of RubyLLM.chat.
         llm_ctx = context&.llm
-        chat_opts[:context] = llm_ctx if llm_ctx.is_a?(RubyLLM::Context)
-
-        client = RubyLLM.chat(**chat_opts)
-          .with_temperature(temperature)
+        client = if llm_ctx.is_a?(RubyLLM::Context)
+          llm_ctx.chat(**chat_opts)
+        else
+          RubyLLM.chat(**chat_opts)
+        end
+        client = client.with_temperature(temperature)
 
         client = client.with_instructions(system_prompt) if system_prompt
         client = client.with_schema(schema) if schema
@@ -889,8 +908,9 @@ module RubyLLM
       # @param context [Pipeline::Context] The context
       # @return [Result] The result object
       def build_result(content, response, context)
-        Result.new(
+        result_opts = {
           content: content,
+          agent_class_name: self.class.name,
           input_tokens: context.input_tokens,
           output_tokens: context.output_tokens,
           input_cost: context.input_cost,
@@ -907,7 +927,12 @@ module RubyLLM
           streaming: streaming_enabled?,
           attempts_count: context.attempts_made || 1,
           execution_id: context.execution_id
-        )
+        }
+
+        # Attach pipeline trace when debug mode is enabled
+        result_opts[:trace] = context.trace if context.trace_enabled? && context.trace.any?
+
+        Result.new(**result_opts)
       end
 
       # Extracts thinking data from a response for inclusion in Result
@@ -1077,6 +1102,44 @@ module RubyLLM
           tool_call[key] || tool_call[key.to_s]
         end
       end
+
+      # Re-raises auth errors with actionable setup guidance
+      def raise_with_setup_hint(error, context)
+        effective_model = context&.model || model
+        provider = detect_provider(effective_model)
+
+        hint = "#{self.class.name} failed: #{error.message}\n\n" \
+               "The API key for #{provider || "your provider"} is missing or invalid.\n" \
+               "Fix: Set the key in config/initializers/ruby_llm_agents.rb\n" \
+               "     or run: rails ruby_llm_agents:doctor"
+
+        raise RubyLLM::Agents::ConfigurationError, hint
+      end
+
+      # Re-raises model errors with actionable guidance
+      def raise_with_model_hint(error, context)
+        effective_model = context&.model || model
+
+        hint = "#{self.class.name} failed: #{error.message}\n\n" \
+               "Model '#{effective_model}' was not found.\n" \
+               "Fix: Check the model name or set a default in your initializer:\n" \
+               "     config.default_model = \"gpt-4o\""
+
+        raise RubyLLM::Agents::ConfigurationError, hint
+      end
+
+      # Best-effort provider detection from model name
+      def detect_provider(model_id)
+        return nil unless model_id
+
+        case model_id.to_s
+        when /gpt|o[1-9]|dall-e|whisper|tts/i then "OpenAI"
+        when /claude/i then "Anthropic"
+        when /gemini|gemma/i then "Google (Gemini)"
+        when /deepseek/i then "DeepSeek"
+        when /mistral|mixtral/i then "Mistral"
+        end
+      end
     end
   end
 end

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

@@ -87,6 +87,10 @@ module RubyLLM
         run_callbacks(:after, context, response)
 
         context.output = build_result(processed_content, response, context)
+      rescue RubyLLM::UnauthorizedError, RubyLLM::ForbiddenError => e
+        raise_with_setup_hint(e, context)
+      rescue RubyLLM::ModelNotFoundError => e
+        raise_with_model_hint(e, context)
       end
 
       # Returns the resolved tenant ID for tracking

data/lib/ruby_llm/agents/core/configuration.rb

@@ -387,6 +387,7 @@ module RubyLLM
         :default_total_timeout,
         :default_streaming,
         :default_tools,
+        :default_tool_timeout,
         :default_thinking,
         :on_alert,
         :persist_prompts,
@@ -639,6 +640,7 @@ module RubyLLM
         # Streaming, tools, and thinking defaults
         @default_streaming = false
         @default_tools = []
+        @default_tool_timeout = nil
         @default_thinking = nil
 
         # Governance defaults
@@ -819,6 +821,16 @@ module RubyLLM
         tenant_resolver&.call
       end
 
+      # Returns a concise string representation for debugging
+      #
+      # @return [String] Summary of key configuration values
+      def inspect
+        "#<#{self.class} model=#{default_model.inspect} temperature=#{default_temperature} " \
+          "timeout=#{default_timeout} streaming=#{default_streaming} " \
+          "multi_tenancy=#{multi_tenancy_enabled} async_logging=#{async_logging} " \
+          "track_executions=#{track_executions}>"
+      end
+
       # Returns whether the async gem is available
       #
       # @return [Boolean] true if async gem is loaded

data/lib/ruby_llm/agents/core/errors.rb

@@ -29,6 +29,9 @@ module RubyLLM
     # Raised when an execution cannot be replayed
     class ReplayError < Error; end
 
+    # Raised when an agent execution is cancelled via on_cancelled
+    class CancelledError < Error; end
+
     # Raised when the TTS API returns an error response
     class SpeechApiError < Error
       attr_reader :status, :response_body

data/lib/ruby_llm/agents/core/version.rb

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

data/lib/ruby_llm/agents/pipeline/context.rb

@@ -46,6 +46,9 @@ module RubyLLM
         # Response metadata
         attr_accessor :model_used, :finish_reason, :time_to_first_token_ms
 
+        # Debug trace (set when debug: true is passed)
+        attr_accessor :trace
+
         # Streaming support
         attr_accessor :stream_block, :skip_cache
 
@@ -85,6 +88,10 @@ module RubyLLM
           @skip_cache = skip_cache
           @stream_block = stream_block
 
+          # Debug trace
+          @trace = []
+          @trace_enabled = options[:debug] == true
+
           # Initialize tracking fields
           @attempt = 0
           @attempts_made = 0
@@ -108,6 +115,23 @@ module RubyLLM
           ((@completed_at - @started_at) * 1000).to_i
         end
 
+        # Is debug tracing enabled?
+        #
+        # @return [Boolean]
+        def trace_enabled?
+          @trace_enabled
+        end
+
+        # Adds a trace entry for a middleware execution
+        #
+        # @param middleware_name [String] Name of the middleware
+        # @param started_at [Time] When the middleware started
+        # @param duration_ms [Float] How long the middleware took in ms
+        # @param action [String, nil] Optional action description (e.g., "cache hit")
+        def add_trace(middleware_name, started_at:, duration_ms:, action: nil)
+          @trace << {middleware: middleware_name, started_at: started_at, duration_ms: duration_ms, action: action}.compact
+        end
+
         # Was the result served from cache?
         #
         # @return [Boolean]
@@ -230,6 +254,8 @@ module RubyLLM
           # Preserve execution hierarchy
           new_ctx.parent_execution_id = @parent_execution_id
           new_ctx.root_execution_id = @root_execution_id
+          # Preserve trace across retries
+          new_ctx.trace = @trace
           new_ctx
         end
 

data/lib/ruby_llm/agents/pipeline/middleware/base.rb

@@ -41,6 +41,8 @@ module RubyLLM
         # @abstract Subclass and implement {#call}
         #
         class Base
+          LOG_TAG = "[RubyLLM::Agents::Pipeline]"
+
           # @param app [#call] The next handler in the chain
           # @param agent_class [Class] The agent class (for reading DSL config)
           def initialize(app, agent_class)
@@ -100,22 +102,74 @@ module RubyLLM
             RubyLLM::Agents.configuration
           end
 
+          # Builds a log prefix with context from the execution
+          #
+          # Includes agent type, execution ID, and tenant when available
+          # so log messages can be traced through the full pipeline.
+          #
+          # @param context [Context, nil] The execution context
+          # @return [String] Formatted log prefix
+          def log_prefix(context = nil)
+            return LOG_TAG unless context
+
+            parts = [LOG_TAG]
+            parts << context.agent_class.name if context.agent_class
+            parts << "exec=#{context.execution_id}" if context.execution_id
+            parts << "tenant=#{context.tenant_id}" if context.tenant_id
+            parts.join(" ")
+          end
+
           # Log a debug message if Rails logger is available
           #
           # @param message [String] The message to log
-          def debug(message)
+          # @param context [Context, nil] Optional execution context for structured prefix
+          def debug(message, context = nil)
             return unless defined?(Rails) && Rails.logger
 
-            Rails.logger.debug("[RubyLLM::Agents::Pipeline] #{message}")
+            Rails.logger.debug("#{log_prefix(context)} #{message}")
           end
 
           # Log an error message if Rails logger is available
           #
           # @param message [String] The message to log
-          def error(message)
+          # @param context [Context, nil] Optional execution context for structured prefix
+          def error(message, context = nil)
+            return unless defined?(Rails) && Rails.logger
+
+            Rails.logger.error("#{log_prefix(context)} #{message}")
+          end
+
+          # Traces middleware execution when debug mode is enabled.
+          #
+          # Wraps a block with timing instrumentation. When tracing is not
+          # enabled, yields directly with zero overhead.
+          #
+          # @param context [Context] The execution context
+          # @param action [String, nil] Optional action description
+          # @yield The block to trace
+          # @return [Object] The block's return value
+          def trace(context, action: nil)
+            unless context.trace_enabled?
+              return yield
+            end
+
+            middleware_name = self.class.name&.split("::")&.last || self.class.to_s
+            started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            result = yield
+            duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000).round(2)
+            context.add_trace(middleware_name, started_at: Time.current, duration_ms: duration_ms, action: action)
+            debug("#{middleware_name} completed in #{duration_ms}ms#{" (#{action})" if action}", context)
+            result
+          end
+
+          # Log a warning message if Rails logger is available
+          #
+          # @param message [String] The message to log
+          # @param context [Context, nil] Optional execution context for structured prefix
+          def warn(message, context = nil)
             return unless defined?(Rails) && Rails.logger
 
-            Rails.logger.error("[RubyLLM::Agents::Pipeline] #{message}")
+            Rails.logger.warn("#{log_prefix(context)} #{message}")
           end
         end
       end

data/lib/ruby_llm/agents/pipeline/middleware/budget.rb

@@ -32,21 +32,23 @@ module RubyLLM
           def call(context)
             return @app.call(context) unless budgets_enabled?
 
-            # Check budget before execution
-            check_budget!(context)
+            trace(context) do
+              # Check budget before execution
+              check_budget!(context)
 
-            # Execute the chain
-            @app.call(context)
+              # Execute the chain
+              @app.call(context)
 
-            # Record spend after successful execution (if not cached)
-            if context.success? && !context.cached?
-              record_spend!(context)
-              emit_budget_notification("ruby_llm_agents.budget.record", context,
-                total_cost: context.total_cost,
-                total_tokens: context.total_tokens)
-            end
+              # Record spend after successful execution (if not cached)
+              if context.success? && !context.cached?
+                record_spend!(context)
+                emit_budget_notification("ruby_llm_agents.budget.record", context,
+                  total_cost: context.total_cost,
+                  total_tokens: context.total_tokens)
+              end
 
-            context
+              context
+            end
           end
 
           private
@@ -65,7 +67,7 @@ module RubyLLM
               }.merge(extras)
             )
           rescue => e
-            debug("Budget notification failed: #{e.message}")
+            debug("Budget notification failed: #{e.message}", context)
           end
 
           # Returns whether budgets are enabled globally
@@ -106,7 +108,7 @@ module RubyLLM
             raise
           rescue => e
             # Log at error level so unexpected failures are visible in logs
-            error("Budget check failed: #{e.class}: #{e.message}")
+            error("Budget check failed: #{e.class}: #{e.message}", context)
           end
 
           # Records spend after execution
@@ -122,7 +124,7 @@ module RubyLLM
                 tenant.record_execution!(
                   cost: context.total_cost || 0,
                   tokens: context.total_tokens || 0,
-                  error: context.error?
+                  error: context.failed?
                 )
                 return
               end
@@ -144,8 +146,6 @@ module RubyLLM
                 tenant_id: context.tenant_id
               )
             end
-          rescue => e
-            error("Failed to record spend: #{e.message}")
           end
         end
       end

data/lib/ruby_llm/agents/pipeline/middleware/cache.rb

@@ -31,34 +31,46 @@ module RubyLLM
           def call(context)
             return @app.call(context) unless cache_enabled?
 
-            cache_key = generate_cache_key(context)
-
-            # Skip cache read if skip_cache is true
-            unless context.skip_cache
-              # Try to read from cache
-              if (cached = cache_read(cache_key))
-                context.output = cached
-                context.cached = true
-                context[:cache_key] = cache_key
-                debug("Cache hit for #{cache_key}")
-                emit_cache_notification("ruby_llm_agents.cache.hit", cache_key)
-                return context
+            cache_action = nil
+            result = trace(context, action: "cache") do
+              cache_key = generate_cache_key(context)
+
+              # Skip cache read if skip_cache is true
+              unless context.skip_cache
+                # Try to read from cache
+                if (cached = cache_read(cache_key))
+                  context.output = cached
+                  context.cached = true
+                  context[:cache_key] = cache_key
+                  cache_action = "hit"
+                  debug("Cache hit for #{cache_key}", context)
+                  emit_cache_notification("ruby_llm_agents.cache.hit", cache_key)
+                  next context
+                end
               end
-            end
 
-            emit_cache_notification("ruby_llm_agents.cache.miss", cache_key)
+              cache_action = "miss"
+              emit_cache_notification("ruby_llm_agents.cache.miss", cache_key)
+
+              # Execute the chain
+              @app.call(context)
 
-            # Execute the chain
-            @app.call(context)
+              # Cache successful results
+              if context.success?
+                cache_write(cache_key, context.output)
+                debug("Cache write for #{cache_key}", context)
+                emit_cache_notification("ruby_llm_agents.cache.write", cache_key)
+              end
+
+              context
+            end
 
-            # Cache successful results
-            if context.success?
-              cache_write(cache_key, context.output)
-              debug("Cache write for #{cache_key}")
-              emit_cache_notification("ruby_llm_agents.cache.write", cache_key)
+            # Update the last trace entry with the specific cache action
+            if context.trace_enabled? && cache_action && context.trace.last
+              context.trace.last[:action] = cache_action
             end
 
-            context
+            result
           end
 
           private