ruby_llm-agents 3.7.2 → 3.8.0

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

@@ -170,7 +170,8 @@ module RubyLLM
           # @return [Array<Hash>] Middleware entries
           def global_middleware_entries
             RubyLLM::Agents.configuration.middleware_stack
-          rescue
+          rescue => e
+            Rails.logger.debug("[RubyLLM::Agents::Pipeline] Failed to load global middleware: #{e.message}") if defined?(Rails) && Rails.logger
             []
           end
 
@@ -182,7 +183,8 @@ module RubyLLM
             return [] unless agent_class&.respond_to?(:agent_middleware)
 
             agent_class.agent_middleware
-          rescue
+          rescue => e
+            Rails.logger.debug("[RubyLLM::Agents::Pipeline] Failed to load agent middleware: #{e.message}") if defined?(Rails) && Rails.logger
             []
           end
 
@@ -207,7 +209,8 @@ module RubyLLM
           # @return [Boolean]
           def budgets_enabled?
             RubyLLM::Agents.configuration.budgets_enabled?
-          rescue
+          rescue => e
+            Rails.logger.debug("[RubyLLM::Agents::Pipeline] Failed to check budgets_enabled: #{e.message}") if defined?(Rails) && Rails.logger
             false
           end
 
@@ -248,7 +251,8 @@ module RubyLLM
 
             (retries.is_a?(Integer) && retries.positive?) ||
               (fallbacks.is_a?(Array) && fallbacks.any?)
-          rescue
+          rescue => e
+            Rails.logger.debug("[RubyLLM::Agents::Pipeline] Failed to check reliability_enabled: #{e.message}") if defined?(Rails) && Rails.logger
             false
           end
         end

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

@@ -136,6 +136,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
@@ -217,6 +235,24 @@ module RubyLLM
 
         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 +263,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/budget.rb

@@ -64,8 +64,8 @@ module RubyLLM
                 tenant_id: context.tenant_id
               }.merge(extras)
             )
-          rescue
-            # Never let notifications break execution
+          rescue => e
+            debug("Budget notification failed: #{e.message}")
           end
 
           # Returns whether budgets are enabled globally
@@ -73,7 +73,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 +105,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}")
           end
 
           # Records spend after execution

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

@@ -73,8 +73,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 +89,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 +149,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
 

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

@@ -176,8 +176,8 @@ module RubyLLM
               else
                 RubyLLM::Agents::ExecutionDetail.create!(detail_attrs.merge(execution_id: execution.id))
               end
-            rescue
-              # Non-critical
+            rescue => e
+              debug("Failed to store error detail: #{e.message}")
             end
           rescue => e
             error("CRITICAL: Failed emergency status update for execution #{execution&.id}: #{e.message}")
@@ -205,8 +205,8 @@ module RubyLLM
               tenant_id: context.tenant_id,
               execution_id: context.execution_id
             )
-          rescue
-            # Never let notifications break execution
+          rescue => e
+            debug("Start notification failed: #{e.message}")
           end
 
           # Emits an AS::Notification for execution completion or error
@@ -242,8 +242,8 @@ module RubyLLM
               error_class: context.error&.class&.name,
               error_message: context.error&.message
             )
-          rescue
-            # Never let notifications break execution
+          rescue => e
+            debug("Complete notification failed: #{e.message}")
           end
 
           # Builds data for initial running execution record
@@ -321,7 +321,8 @@ module RubyLLM
 
             context_meta = begin
               context.metadata.dup
-            rescue
+            rescue => e
+              debug("Failed to read context metadata: #{e.message}")
               {}
             end
             context_meta.transform_keys!(&:to_s)
@@ -414,72 +415,19 @@ module RubyLLM
             error("Failed to record execution: #{e.message}")
           end
 
-          # Builds execution data hash
+          # Builds execution data hash for the legacy single-step persistence path.
+          #
+          # Composes from build_running_execution_data and build_completion_data
+          # to avoid duplication.
           #
           # @param context [Context] The execution context
           # @param status [String] "success" or "error"
-          # @return [Hash] Execution data
+          # @return [Hash] Execution data with _detail_data for detail record
           def build_execution_data(context, status)
-            # Merge metadata: agent metadata (base) < middleware metadata (overlay)
-            agent_meta = safe_agent_metadata(context)
-            merged_metadata = agent_meta.transform_keys(&:to_s)
-
-            context_meta = begin
-              context.metadata.dup
-            rescue
-              {}
-            end
-            context_meta.transform_keys!(&:to_s)
-            merged_metadata.merge!(context_meta)
-
-            if context.cached? && context[:cache_key]
-              merged_metadata["response_cache_key"] = context[:cache_key]
-            end
-
-            data = {
-              agent_type: context.agent_class&.name,
-              model_id: context.model,
-              status: determine_status(context, status),
-              duration_ms: context.duration_ms,
-              started_at: context.started_at,
-              completed_at: context.completed_at,
-              cache_hit: context.cached?,
-              input_tokens: context.input_tokens || 0,
-              output_tokens: context.output_tokens || 0,
-              total_cost: context.total_cost || 0,
-              attempts_count: context.attempts_made,
-              metadata: merged_metadata
-            }
-
-            # Extract tracing fields from agent metadata to dedicated columns
-            if agent_meta.any?
-              data[:trace_id] = agent_meta[:trace_id] if agent_meta[:trace_id]
-              data[:request_id] = agent_meta[:request_id] if agent_meta[:request_id]
-              data[:parent_execution_id] = agent_meta[:parent_execution_id] if agent_meta[:parent_execution_id]
-              data[:root_execution_id] = agent_meta[:root_execution_id] if agent_meta[:root_execution_id]
-            end
-
-            # Add tenant_id only if multi-tenancy is enabled and tenant is set
-            if global_config.multi_tenancy_enabled? && context.tenant_id.present?
-              data[:tenant_id] = context.tenant_id
-            end
-
-            # Error class on execution
-            if context.error
-              data[:error_class] = context.error.class.name
-            end
-
-            # Tool calls count on execution
-            if context[:tool_calls].present?
-              data[:tool_calls_count] = context[:tool_calls].size
-            end
-
-            # Attempts count on execution
-            if context[:reliability_attempts].present?
-              data[:attempts_count] = context[:reliability_attempts].size
-            end
+            data = build_running_execution_data(context)
+              .merge(build_completion_data(context, determine_status(context, status)))
 
-            # Store detail data for separate creation
+            # Build detail data for separate creation
             detail_data = {parameters: sanitize_parameters(context)}
             if global_config.persist_prompts
               exec_opts = context.options[:options] || {}
@@ -494,11 +442,9 @@ module RubyLLM
               detail_data[:response] = serialize_response(context)
             end
 
-            # Persist audio data for Speaker executions
             maybe_persist_audio_response(context, detail_data)
 
             data[:_detail_data] = detail_data
-
             data
           end
 
@@ -527,7 +473,8 @@ module RubyLLM
 
             params = begin
               context.agent_instance.send(:options)
-            rescue
+            rescue => e
+              debug("Failed to extract agent options: #{e.message}")
               {}
             end
             params = params.dup
@@ -689,7 +636,8 @@ module RubyLLM
             else
               cfg.track_executions
             end
-          rescue
+          rescue => e
+            debug("Failed to check tracking config: #{e.message}")
             false
           end
 
@@ -698,7 +646,8 @@ module RubyLLM
           # @return [Boolean]
           def track_cache_hits?
             global_config.respond_to?(:track_cache_hits) && global_config.track_cache_hits
-          rescue
+          rescue => e
+            debug("Failed to check track_cache_hits config: #{e.message}")
             false
           end
 
@@ -707,7 +656,8 @@ module RubyLLM
           # @return [Boolean]
           def async_logging?
             global_config.async_logging && defined?(Infrastructure::ExecutionLoggerJob)
-          rescue
+          rescue => e
+            debug("Failed to check async_logging config: #{e.message}")
             false
           end
 
@@ -722,7 +672,8 @@ module RubyLLM
             @_assistant_prompt_column_exists = begin
               defined?(RubyLLM::Agents::ExecutionDetail) &&
                 RubyLLM::Agents::ExecutionDetail.column_names.include?("assistant_prompt")
-            rescue
+            rescue => e
+              debug("Failed to check assistant_prompt column: #{e.message}")
               false
             end
           end

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

@@ -237,7 +237,7 @@ module RubyLLM
             return false if attempt_index >= max_retries
             return false if total_deadline && Time.current > total_deadline
             # Don't retry if fallback models are available — move to next model instead
-            return false if has_fallback_models?(config)
+            return false if fallback_models?(config)
 
             retryable_error?(error, config)
           end
@@ -256,7 +256,7 @@ module RubyLLM
           #
           # @param config [Hash] The reliability configuration
           # @return [Boolean]
-          def has_fallback_models?(config)
+          def fallback_models?(config)
             fallbacks = config[:fallback_models]
             fallbacks.is_a?(Array) && fallbacks.any?
           end
@@ -317,8 +317,8 @@ module RubyLLM
               event,
               {agent_type: @agent_class&.name}.merge(extras)
             )
-          rescue
-            # Never let notifications break execution
+          rescue => e
+            debug("Reliability notification failed: #{e.message}")
           end
 
           # Sleeps without blocking other fibers when in async context
@@ -333,8 +333,8 @@ module RubyLLM
             else
               sleep(seconds)
             end
-          rescue
-            # Fall back to regular sleep if async detection fails
+          rescue => e
+            debug("Async sleep failed, falling back to regular sleep: #{e.message}")
             sleep(seconds)
           end
         end

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

@@ -112,7 +112,7 @@ module RubyLLM
               ensure_tenant_for_model!(tenant_object)
             else
               # For hash-based or string tenants, ensure a minimal record exists
-              RubyLLM::Agents::Tenant.find_or_create_by!(tenant_id: context.tenant_id)
+              find_or_create_tenant!(context.tenant_id)
             end
           rescue => e
             # Don't fail the execution if tenant record creation fails
@@ -145,6 +145,18 @@ module RubyLLM
               enforcement: options[:enforcement]&.to_s || "soft",
               inherit_global_defaults: options.fetch(:inherit_global, true)
             )
+          rescue ActiveRecord::RecordNotUnique
+            # Race condition: another thread created the record — safe to ignore
+          end
+
+          # Finds or creates a tenant record, handling race conditions
+          #
+          # @param tenant_id [String] The tenant identifier
+          def find_or_create_tenant!(tenant_id)
+            RubyLLM::Agents::Tenant.find_or_create_by!(tenant_id: tenant_id)
+          rescue ActiveRecord::RecordNotUnique
+            # Another thread/process created the record — just find it
+            RubyLLM::Agents::Tenant.find_by!(tenant_id: tenant_id)
           end
 
           # Checks if the tenants table exists (memoized)
@@ -154,7 +166,8 @@ module RubyLLM
             return @tenant_table_exists if defined?(@tenant_table_exists)
 
             @tenant_table_exists = ::ActiveRecord::Base.connection.table_exists?(:ruby_llm_agents_tenants)
-          rescue
+          rescue => e
+            debug("Failed to check tenant table existence: #{e.message}")
             @tenant_table_exists = false
           end
 
@@ -178,7 +191,11 @@ module RubyLLM
             apply_tenant_object_api_keys!(context)
           end
 
-          # Applies API keys from tenant object's llm_api_keys method
+          # Stores tenant API keys on the context for thread-safe per-request use.
+          #
+          # Instead of mutating the global RubyLLM configuration (which is not
+          # thread-safe), keys are stored on the context. The Pipeline::Context#llm
+          # method creates a scoped RubyLLM::Context with these keys when needed.
           #
           # @param context [Context] The execution context
           def apply_tenant_object_api_keys!(context)
@@ -188,34 +205,12 @@ module RubyLLM
             api_keys = tenant_object.llm_api_keys
             return if api_keys.blank?
 
-            apply_api_keys_to_ruby_llm(api_keys)
+            context[:tenant_api_keys] = api_keys
           rescue => e
             # Log but don't fail if API key extraction fails
             warn_api_key_error("tenant object", e)
           end
 
-          # Applies a hash of API keys to RubyLLM configuration
-          #
-          # @param api_keys [Hash] Hash of provider => key mappings
-          def apply_api_keys_to_ruby_llm(api_keys)
-            RubyLLM.configure do |config|
-              api_keys.each do |provider, key|
-                next if key.blank?
-
-                setter = api_key_setter_for(provider)
-                config.public_send(setter, key) if config.respond_to?(setter)
-              end
-            end
-          end
-
-          # Returns the setter method name for a provider's API key
-          #
-          # @param provider [Symbol, String] Provider name (e.g., :openai, :anthropic)
-          # @return [String] Setter method name (e.g., "openai_api_key=")
-          def api_key_setter_for(provider)
-            "#{provider}_api_key="
-          end
-
           # Logs a warning about API key resolution failure
           #
           # @param source [String] Source that failed
@@ -236,7 +231,8 @@ module RubyLLM
             return nil unless tenant.respond_to?(:llm_config)
 
             tenant.llm_config
-          rescue
+          rescue => e
+            debug("Failed to extract tenant config: #{e.message}")
             nil
           end
         end

data/lib/ruby_llm/agents/providers/inception/capabilities.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    module Providers
+      class Inception
+        # Determines capabilities and pricing for Inception Mercury models.
+        #
+        # Mercury models are diffusion LLMs with text-only I/O.
+        # Pricing is per million tokens.
+        #
+        # Models:
+        # - mercury-2: Reasoning dLLM, function calling, structured output
+        # - mercury: Base chat dLLM, function calling, structured output
+        # - mercury-coder-small: Fast coding model
+        # - mercury-edit: Code editing/FIM model
+        module Capabilities
+          module_function
+
+          REASONING_MODELS = %w[mercury-2].freeze
+          CODER_MODELS = %w[mercury-coder-small mercury-edit].freeze
+          FUNCTION_CALLING_MODELS = %w[mercury-2 mercury].freeze
+
+          def context_window_for(_model_id)
+            128_000
+          end
+
+          def max_tokens_for(_model_id)
+            32_000
+          end
+
+          def input_price_for(_model_id)
+            0.25
+          end
+
+          def output_price_for(model_id)
+            if CODER_MODELS.include?(model_id)
+              1.00
+            else
+              0.75
+            end
+          end
+
+          def supports_vision?(_model_id)
+            false
+          end
+
+          def supports_functions?(model_id)
+            FUNCTION_CALLING_MODELS.include?(model_id)
+          end
+
+          def supports_json_mode?(model_id)
+            FUNCTION_CALLING_MODELS.include?(model_id)
+          end
+
+          def format_display_name(model_id)
+            case model_id
+            when "mercury-2" then "Mercury 2"
+            when "mercury" then "Mercury"
+            when "mercury-coder-small" then "Mercury Coder Small"
+            when "mercury-edit" then "Mercury Edit"
+            else
+              model_id.split("-").map(&:capitalize).join(" ")
+            end
+          end
+
+          def model_type(model_id)
+            if CODER_MODELS.include?(model_id)
+              "code"
+            else
+              "chat"
+            end
+          end
+
+          def model_family(_model_id)
+            :mercury
+          end
+
+          def modalities_for(_model_id)
+            {input: ["text"], output: ["text"]}
+          end
+
+          def capabilities_for(model_id)
+            caps = ["streaming"]
+            if FUNCTION_CALLING_MODELS.include?(model_id)
+              caps << "function_calling"
+              caps << "structured_output"
+            end
+            caps << "reasoning" if REASONING_MODELS.include?(model_id)
+            caps
+          end
+
+          def pricing_for(model_id)
+            {
+              text_tokens: {
+                standard: {
+                  input_per_million: input_price_for(model_id),
+                  output_per_million: output_price_for(model_id)
+                }
+              }
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/providers/inception/chat.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    module Providers
+      class Inception
+        # Chat methods for Inception Mercury API.
+        # Mercury uses standard OpenAI chat format.
+        module Chat
+          def format_role(role)
+            role.to_s
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/providers/inception/configuration.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# Extends RubyLLM::Configuration with Inception API key support.
+# This allows users to configure: config.inception_api_key = ENV['INCEPTION_API_KEY']
+module RubyLLM
+  class Configuration
+    attr_accessor :inception_api_key unless method_defined?(:inception_api_key)
+  end
+end

data/lib/ruby_llm/agents/providers/inception/models.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    module Providers
+      class Inception
+        # Parses model metadata from the Inception /models API endpoint.
+        # Response format is OpenAI-compatible.
+        module Models
+          module_function
+
+          def parse_list_models_response(response, slug, capabilities)
+            Array(response.body["data"]).map do |model_data|
+              model_id = model_data["id"]
+
+              ::RubyLLM::Model::Info.new(
+                id: model_id,
+                name: capabilities.format_display_name(model_id),
+                provider: slug,
+                family: "mercury",
+                created_at: model_data["created"] ? Time.at(model_data["created"]) : nil,
+                context_window: capabilities.context_window_for(model_id),
+                max_output_tokens: capabilities.max_tokens_for(model_id),
+                modalities: capabilities.modalities_for(model_id),
+                capabilities: capabilities.capabilities_for(model_id),
+                pricing: capabilities.pricing_for(model_id),
+                metadata: {
+                  object: model_data["object"],
+                  owned_by: model_data["owned_by"]
+                }.compact
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end