ruby_llm-agents 3.7.2 → 3.9.0

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]
@@ -136,6 +160,24 @@ module RubyLLM
           (@input_tokens || 0) + (@output_tokens || 0)
         end
 
+        # Returns a RubyLLM interface scoped to tenant API keys when present.
+        #
+        # When tenant API keys are stored on this context (by the Tenant middleware),
+        # returns a RubyLLM::Context with a cloned config that has tenant-specific
+        # keys applied. This avoids mutating global RubyLLM configuration, making
+        # multi-tenant LLM calls thread-safe.
+        #
+        # When no tenant API keys are present, returns the RubyLLM module directly
+        # (which uses the global configuration).
+        #
+        # @return [RubyLLM::Context, RubyLLM] Scoped context or global module
+        def llm
+          api_keys = self[:tenant_api_keys]
+          return RubyLLM if api_keys.nil? || api_keys.empty?
+
+          @llm_context ||= build_llm_context(api_keys)
+        end
+
         # Custom metadata storage - read
         #
         # @param key [Symbol, String] The metadata key
@@ -212,11 +254,31 @@ 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
 
         private
 
+        # Builds a RubyLLM::Context with tenant-specific API keys
+        #
+        # Clones the global RubyLLM config and overlays tenant API keys,
+        # then wraps it in a RubyLLM::Context for thread-safe per-request use.
+        #
+        # @param api_keys [Hash] Provider => key mappings (e.g., {openai: "sk-..."})
+        # @return [RubyLLM::Context] Context with tenant-scoped configuration
+        def build_llm_context(api_keys)
+          config = RubyLLM.config.dup
+          api_keys.each do |provider, key|
+            next if key.nil? || (key.respond_to?(:empty?) && key.empty?)
+
+            setter = "#{provider}_api_key="
+            config.public_send(setter, key) if config.respond_to?(setter)
+          end
+          RubyLLM::Context.new(config)
+        end
+
         # Extracts agent_type from the agent class
         #
         # @param agent_class [Class] The agent class
@@ -227,7 +289,13 @@ module RubyLLM
           if agent_class.respond_to?(:agent_type)
             agent_class.agent_type
           else
-            # Infer from class name as fallback
+            if defined?(RubyLLM::Agents::Deprecations)
+              RubyLLM::Agents::Deprecations.warn(
+                "#{agent_class.name || agent_class} does not define `agent_type`. " \
+                "Guessing from class name. Define `self.agent_type` to silence this warning.",
+                caller
+              )
+            end
             infer_agent_type(agent_class)
           end
         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
@@ -64,8 +66,8 @@ module RubyLLM
                 tenant_id: context.tenant_id
               }.merge(extras)
             )
-          rescue
-            # Never let notifications break execution
+          rescue => e
+            debug("Budget notification failed: #{e.message}", context)
           end
 
           # Returns whether budgets are enabled globally
@@ -73,7 +75,8 @@ module RubyLLM
           # @return [Boolean]
           def budgets_enabled?
             global_config.budgets_enabled?
-          rescue
+          rescue => e
+            debug("Failed to check budgets_enabled config: #{e.message}")
             false
           end
 
@@ -104,7 +107,8 @@ module RubyLLM
             emit_budget_notification("ruby_llm_agents.budget.exceeded", context)
             raise
           rescue => e
-            error("Budget check failed: #{e.message}")
+            # Log at error level so unexpected failures are visible in logs
+            error("Budget check failed: #{e.class}: #{e.message}", context)
           end
 
           # Records spend after execution
@@ -143,7 +147,7 @@ module RubyLLM
               )
             end
           rescue => e
-            error("Failed to record spend: #{e.message}")
+            error("Failed to record spend: #{e.message}", context)
           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)
+
+              # 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
 
-            # Execute the chain
-            @app.call(context)
+              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
@@ -73,8 +85,8 @@ module RubyLLM
               agent_type: @agent_class&.name,
               cache_key: cache_key
             )
-          rescue
-            # Never let notifications break execution
+          rescue => e
+            debug("Cache notification failed: #{e.message}")
           end
 
           # Returns whether caching is enabled for this agent
@@ -89,7 +101,8 @@ module RubyLLM
           # @return [ActiveSupport::Cache::Store, nil]
           def cache_store
             global_config.cache_store
-          rescue
+          rescue => e
+            debug("Failed to access cache_store config: #{e.message}")
             nil
           end
 
@@ -148,7 +161,8 @@ module RubyLLM
             else
               input.to_json
             end
-          rescue
+          rescue => e
+            debug("Failed to serialize input for cache key: #{e.message}")
             input.to_s
           end