smith-agents 0.7.0 → 0.8.0

data/lib/smith/doctor/checks/models_registry.rb

@@ -15,7 +15,12 @@ module Smith
         module_function
 
         def run(report)
-          uncovered = uncovered_models
+          uncovered, ambiguous = classified_model_references
+          report_ambiguous_models(report, ambiguous)
+          report_model_coverage(report, uncovered)
+        end
+
+        def report_model_coverage(report, uncovered)
           if uncovered.empty?
             report.add(
               name: "models.coverage",
@@ -36,23 +41,65 @@ module Smith
           end
         end
 
+        # An unqualified agent model id registered under more than one
+        # provider cannot resolve to a single profile: chat construction
+        # fails closed with AmbiguousProfileError. Doctor must report that
+        # configuration instead of crashing on it.
+        def report_ambiguous_models(report, ambiguous)
+          return if ambiguous.empty?
+
+          descriptions = ambiguous.map { |reference| ambiguous_reference_description(reference) }
+          report.add(
+            name: "models.ambiguity",
+            status: :fail,
+            message: "#{ambiguous.size} agent model id(s) match profiles from multiple registered providers",
+            detail: "Ambiguous: #{descriptions.join("; ")}. Chat construction fails closed for " \
+                    "these agents until each declares an explicit provider (for example " \
+                    "model \"gpt-5\", provider: :openai) selecting exactly one registered profile."
+          )
+        end
+
+        def ambiguous_reference_description(reference)
+          "#{reference.model_id} (providers: #{registered_providers_for(reference).join(", ")})"
+        end
+
+        def registered_providers_for(reference)
+          Smith::Models.all
+                       .select { |profile| profile.model_id == reference.model_id }
+                       .map { |profile| profile.provider.to_s }
+        end
+
         # Walk Smith::Agent::Registry. For each agent, extract every static
         # model id Smith can know at boot: the primary `model "..."` value and
         # any static fallback models. Block-form primary models are skipped
         # because they resolve per-attempt, but their static fallbacks still
         # need coverage checks.
         # Check whether find_or_infer returns a custom (non-default)
-        # Profile — meaning either an explicit override or an inference
-        # rule matched.
-        def uncovered_models
-          return [] unless defined?(Smith::Agent::Registry)
+        # Profile, meaning either an explicit override or an inference
+        # rule matched. Returns [uncovered, ambiguous] reference lists.
+        def classified_model_references
+          return [[], []] unless defined?(Smith::Agent::Registry)
 
-          static_model_ids.uniq.reject { |model_id| covered_model?(model_id) }
+          uncovered = []
+          ambiguous = []
+          static_model_references.uniq(&:key).each do |reference|
+            case model_coverage(reference)
+            when :uncovered then uncovered << reference
+            when :ambiguous then ambiguous << reference
+            end
+          end
+          [uncovered, ambiguous]
+        end
+
+        def model_coverage(reference)
+          covered_model?(reference) ? :covered : :uncovered
+        rescue Smith::Models::AmbiguousProfileError
+          :ambiguous
         end
 
-        def static_model_ids
-          Smith::Agent::Registry.each.with_object([]) do |(_key, agent), ids|
-            ids.concat(static_model_ids_for(agent)) if inspectable_agent?(agent)
+        def static_model_references
+          Smith::Agent::Registry.each.with_object([]) do |(_key, agent), references|
+            references.concat(static_model_references_for(agent)) if inspectable_agent?(agent)
           end
         end
 
@@ -60,16 +107,27 @@ module Smith
           agent.is_a?(Class) && agent.respond_to?(:chat_kwargs)
         end
 
-        def static_model_ids_for(agent)
-          [
-            agent.chat_kwargs[:model],
-            *(agent.respond_to?(:fallback_models) ? agent.fallback_models : nil)
-          ].compact
+        def static_model_references_for(agent)
+          primary = agent.chat_kwargs[:model]
+          references = Array(agent.respond_to?(:fallback_models) ? agent.fallback_models : nil).dup
+          if primary
+            references.unshift(
+              Smith::Agent::ModelReference.coerce(primary, provider: agent.chat_kwargs[:provider])
+            )
+          end
+          references
+        end
+
+        def covered_model?(reference)
+          Smith::Models.find(reference.model_id, provider: reference.provider) ||
+            inferred_profile_matches?(reference)
         end
 
-        def covered_model?(model_id)
-          Smith::Models.find(model_id) ||
-            (defined?(Smith::Models::Inference) && Smith::Models::Inference.profile_for(model_id))
+        def inferred_profile_matches?(reference)
+          return false unless defined?(Smith::Models::Inference)
+
+          profile = Smith::Models::Inference.profile_for(reference.model_id)
+          profile && (reference.provider.nil? || profile.provider.to_sym == reference.provider)
         end
       end
     end

data/lib/smith/errors.rb

@@ -1,12 +1,21 @@
 # frozen_string_literal: true
 
 require_relative "error"
+require_relative "persisted_failure_invalid"
+require_relative "pricing_configuration_error"
+require_relative "provider_permanent_failure"
+require_relative "tool_capture_failed"
+require_relative "tool_execution_not_admitted"
+require_relative "tool_failure_notification_failed"
 
 module Smith
   # Classification surface for host retry policies. Smith owns the
   # answer to "should the workflow attempt be retried?" so consumers
   # don't reimplement the case statement in every Execution / Job.
   module Errors
+    MODULE_MATCH = Module.instance_method(:===)
+    private_constant :MODULE_MATCH
+
     # Returns true when the host should retry the workflow attempt.
     # AgentError + DeadlineExceeded are always retryable.
     # DeterministicStepFailure + ToolGuardrailFailed honor their
@@ -16,7 +25,7 @@ module Smith
       return false if error.nil?
 
       composite_failure = defined?(Smith::Workflow::Composite::BranchFailure) &&
-                          error.is_a?(Smith::Workflow::Composite::BranchFailure)
+                          MODULE_MATCH.bind_call(Smith::Workflow::Composite::BranchFailure, error)
       return false if composite_failure
 
       case error
@@ -29,6 +38,27 @@ module Smith
       end
     end
 
+    def self.retry_forbidden?(error)
+      return false if error.nil?
+
+      retry_forbidden_classes.any? { |error_class| MODULE_MATCH.bind_call(error_class, error) }
+    end
+
+    def self.retry_forbidden_class?(error_class)
+      retry_forbidden_classes.any? { |forbidden| error_class <= forbidden }
+    end
+
+    def self.retry_forbidden_classes
+      @retry_forbidden_classes ||= [
+        Smith::ToolCaptureFailed,
+        Smith::ToolOutcomeUncertain,
+        Smith::ToolExecutionNotAdmitted,
+        Smith::ToolFailureNotificationFailed,
+        Smith::BoundedCompletionError,
+        Smith::PersistedFailureInvalid
+      ].freeze
+    end
+
     # Always-retryable error classes for explicit ActiveJob retry_on
     # allow-lists. Excludes the retryable-bearing families because
     # their retryability is per-raise, not per-class.
@@ -52,6 +82,9 @@ module Smith
   end
 
   class ToolPolicyDenied < Error; end
+  class ToolDispatchRejected < Error; end
+  class BoundedCompletionError < Error; end
+  class ToolOutcomeUncertain < Error; end
   class AgentError < Error; end
 
   class BlankAgentOutputError < AgentError

data/lib/smith/models/ambiguous_profile_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "../error"
+
+module Smith
+  module Models
+    class AmbiguousProfileError < Smith::Error; end
+  end
+end

data/lib/smith/models/collision_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "../error"
+
+module Smith
+  module Models
+    class CollisionError < Smith::Error; end
+  end
+end

data/lib/smith/models/inference.rb

@@ -82,6 +82,20 @@ module Smith
         [
           # ----- Anthropic -----
 
+          # Claude 5+ families (Fable/Mythos/Opus/Sonnet/Haiku): adaptive
+          # thinking, no temperature accepted (the API rejects an explicit
+          # temperature with a 400).
+          Rule.new(
+            provider: :anthropic,
+            matcher: lambda { |id|
+              m = id.match(/\Aclaude-(?:fable|mythos|opus|sonnet|haiku)-(\d+)/)
+              m && m[1].to_i >= 5
+            },
+            thinking_shape: :adaptive,
+            accepts_temperature: false,
+            tools_with_thinking_native: true,
+            tools_with_thinking_route: nil
+          ),
           # Opus 4.7+: adaptive thinking, no temperature accepted.
           Rule.new(
             provider: :anthropic,

data/lib/smith/models/normalizer.rb

@@ -2,6 +2,8 @@
 
 require "dry-initializer"
 
+require_relative "tool_routing"
+
 module Smith
   module Models
     # Per-chat-construction request shaper. Mutates a RubyLLM::Chat
@@ -96,73 +98,11 @@ module Smith
       end
 
       def normalize_tools_routing
-        # Stubbed chat objects in tests may not implement .tools; gracefully
-        # skip rather than crash on respond_to? check.
-        return unless chat.respond_to?(:tools)
-
-        tools = chat.tools.values
-        return if tools.empty?
-        return unless thinking_active?
-
-        return if profile.tools_with_thinking_native
-
-        if profile.tools_with_thinking_route == :responses &&
-           Smith.config.openai_api_mode == :auto
-          merge_params(openai_api_mode: :responses)
-          @decisions << Decision.new(kind: :routed_via_responses, model_id: profile.model_id, detail: nil)
-          return
-        end
-
-        drop_incompatible_tools(tools)
-      end
-
-      def thinking_active?
-        thinking = chat.instance_variable_get(:@thinking)
-        return true if thinking&.enabled?
-
-        # Also active if we already translated to adaptive (in which case
-        # @thinking is nil but params carry the thinking spec).
-        params = chat.instance_variable_get(:@params) || {}
-        params.key?(:thinking) || params.key?(:reasoning) || params.key?(:reasoning_effort)
-      end
-
-      def drop_incompatible_tools(tools)
-        effective_endpoint = effective_endpoint_for_compatibility
-        incompatible = tools.reject do |tool|
-          spec = tool.class.respond_to?(:compatible_with_spec) ? tool.class.compatible_with_spec : nil
-          if defined?(Smith::Tool::Compatibility)
-            Smith::Tool::Compatibility.allows?(spec, profile, effective_endpoint: effective_endpoint)
-          else
-            true
-          end
-        end
-        return if incompatible.empty?
-
-        retained = tools - incompatible
-        chat.with_tools(*retained, replace: true)
-
-        incompatible.each do |tool|
-          @decisions << Decision.new(
-            kind: :tool_dropped,
-            model_id: profile.model_id,
-            detail: { tool: tool.class.name }
-          )
-        end
-      end
-
-      # Profile.endpoint_mode reports the INTENDED endpoint (per the
-      # inference rule). Smith.config.openai_api_mode policy can downgrade
-      # the EFFECTIVE endpoint — e.g., a profile with route :responses
-      # actually uses :chat_completions when openai_api_mode is :off.
-      # The compatibility check needs the effective endpoint to make
-      # the right drop/keep decision.
-      def effective_endpoint_for_compatibility
-        if profile.tools_with_thinking_route == :responses &&
-           Smith.config.openai_api_mode != :auto
-          :chat_completions
-        else
-          profile.endpoint_mode
-        end
+        ToolRouting.new(
+          chat: chat,
+          profile: profile,
+          decision_recorder: method(:record_decision)
+        ).call
       end
 
       # with_params REPLACES @params in RubyLLM (chat.rb:96), so the
@@ -173,6 +113,10 @@ module Smith
         chat.with_params(**existing, **new_params)
       end
 
+      def record_decision(kind, model_id, detail)
+        @decisions << Decision.new(kind: kind, model_id: model_id, detail: detail)
+      end
+
       def emit_trace
         return if @decisions.empty?
         return unless defined?(Smith::Trace)

data/lib/smith/models/provider_qualified_registry.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module Smith
+  module Models
+    module ProviderQualifiedRegistry
+      def self.extended(registry)
+        registry.instance_variable_set(:@registry_monitor, Monitor.new)
+        registry.instance_variable_set(:@registry_index, {})
+      end
+
+      def find(model_id, provider: nil)
+        registry_monitor.synchronize do
+          registered_keys = registered_keys_for(model_id, provider:)
+          return nil if registered_keys.empty?
+
+          reject_ambiguous_lookup!(model_id, registered_keys)
+          resolve(registered_keys.first)
+        end
+      end
+
+      def register(profile)
+        registry_monitor.synchronize do
+          profile = normalized_profile(profile)
+          key = registry_key(profile.model_id, profile.provider)
+          existing = key?(key) ? resolve(key) : nil
+
+          return profile if existing == profile
+
+          raise_collision!(key, existing, profile) if existing
+
+          super(key, profile)
+          index_profile(profile, key)
+          profile
+        end
+      end
+
+      def all
+        registry_monitor.synchronize do
+          keys.map { |key| resolve(key) }.sort_by do |profile|
+            [profile.model_id, profile.provider.to_s]
+          end
+        end
+      end
+
+      def clear!
+        registry_monitor.synchronize do
+          @_container&.clear
+          @registry_index = {}
+        end
+      end
+
+      private
+
+      attr_reader :registry_monitor, :registry_index
+
+      def registered_keys_for(model_id, provider:)
+        normalized_id = normalize_key(model_id)
+        return registry_index.fetch(normalized_id, []) unless provider
+
+        key = registry_key(normalized_id, provider)
+        key?(key) ? [key] : []
+      end
+
+      def registry_key(model_id, provider)
+        [provider.to_sym, normalize_key(model_id)]
+      end
+
+      def reject_ambiguous_lookup!(model_id, registered_keys)
+        return unless registered_keys.length > 1
+
+        providers = registered_keys.map { |key| resolve(key).provider.to_s }.sort
+        raise AmbiguousProfileError,
+              "model #{normalize_key(model_id).inspect} has profiles for multiple providers: " \
+              "#{providers.join(", ")}; pass provider:"
+      end
+
+      def index_profile(profile, key)
+        model_id = normalize_key(profile.model_id)
+        registry_index[model_id] = [*registry_index.fetch(model_id, []), key].uniq.freeze
+      end
+
+      def normalized_profile(profile)
+        Profile.new(
+          **profile.to_h,
+          model_id: normalize_key(profile.model_id).freeze,
+          provider: profile.provider.to_sym
+        )
+      rescue NoMethodError, TypeError
+        raise ArgumentError, "model profile must expose model_id, provider, and profile attributes"
+      end
+
+      def raise_collision!(key, existing, replacement)
+        raise CollisionError,
+              "model profile collision for #{key.inspect}: existing #{existing.inspect}, " \
+              "replacement #{replacement.inspect}"
+      end
+    end
+  end
+end

data/lib/smith/models/tool_routing.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+module Smith
+  module Models
+    class ToolRouting
+      TOOL_ENDPOINTS = %i[chat_completions responses].freeze
+
+      private_constant :TOOL_ENDPOINTS
+
+      extend Dry::Initializer
+
+      option :chat
+      option :profile
+      option :decision_recorder
+
+      def call
+        return unless chat.respond_to?(:tools)
+
+        tools = chat.tools.values
+        return if tools.empty?
+
+        route_tools_with_thinking if thinking_active?
+        route_tools_for_compatibility(tools)
+        drop_incompatible_tools(tools)
+      end
+
+      private
+
+      def route_tools_with_thinking
+        return unless profile.provider == :openai
+        return if profile.tools_with_thinking_native
+        return unless profile.tools_with_thinking_route == :responses
+        return unless Smith.config.openai_api_mode == :auto
+
+        route_via_responses
+      end
+
+      def route_tools_for_compatibility(tools)
+        return unless profile.provider == :openai
+        return unless Smith.config.openai_api_mode == :auto
+        return if responses_routed?
+
+        forced_endpoint = forced_tool_endpoint(tools)
+        return if forced_endpoint == :chat_completions
+        return unless forced_endpoint == :responses ||
+                      compatible_tool_count(tools, :responses) > compatible_tool_count(tools, :chat_completions)
+
+        route_via_responses
+      end
+
+      def route_via_responses
+        return if responses_routed?
+
+        merge_params(openai_api_mode: :responses)
+        record(:routed_via_responses)
+      end
+
+      def drop_incompatible_tools(tools)
+        endpoint = responses_routed? ? :responses : :chat_completions
+        incompatible = tools.reject { |tool| tool_compatible_with?(tool, endpoint) }
+        return if incompatible.empty?
+
+        remaining = tools - incompatible
+        forced_choice = reset_invalid_tool_choice(remaining)
+        chat.with_tools(*remaining, replace: true)
+        incompatible.each_with_index do |tool, index|
+          record(:tool_dropped, dropped_tool_detail(tool, forced_choice, first: index.zero?))
+        end
+      end
+
+      def dropped_tool_detail(tool, forced_choice, first:)
+        detail = { tool: tool.class.name }
+        if forced_choice && (tool.name.to_sym == forced_choice.to_sym || (forced_choice == :required && first))
+          detail[:forced_choice_reset] = forced_choice
+        end
+        detail
+      end
+
+      def forced_tool_endpoint(tools)
+        choice = chat.tool_prefs[:choice]&.to_sym
+        return if %i[auto none required].include?(choice)
+
+        tool = tools.find { |candidate| candidate.name.to_sym == choice }
+        return unless tool
+
+        compatible_endpoints = TOOL_ENDPOINTS.select { |endpoint| tool_compatible_with?(tool, endpoint) }
+        compatible_endpoints.first if compatible_endpoints.one?
+      end
+
+      def reset_invalid_tool_choice(remaining)
+        choice = chat.tool_prefs[:choice]
+        return unless choice
+        return if %i[auto none].include?(choice)
+        return if choice == :required && remaining.any?
+        return if remaining.any? { |tool| tool.name.to_sym == choice.to_sym }
+
+        chat.tool_prefs[:choice] = nil
+        choice
+      end
+
+      def compatible_tool_count(tools, endpoint)
+        tools.count { |tool| tool_compatible_with?(tool, endpoint) }
+      end
+
+      def tool_compatible_with?(tool, endpoint)
+        return true unless defined?(Smith::Tool::Compatibility)
+
+        spec = tool.class.respond_to?(:compatible_with_spec) ? tool.class.compatible_with_spec : nil
+        Smith::Tool::Compatibility.allows?(spec, profile, effective_endpoint: endpoint)
+      end
+
+      def thinking_active?
+        thinking = chat.instance_variable_get(:@thinking)
+        return true if thinking&.enabled?
+
+        current_params.key?(:thinking) || current_params.key?(:reasoning) ||
+          current_params.key?(:reasoning_effort)
+      end
+
+      def responses_routed?
+        mode = current_params[:openai_api_mode] || current_params["openai_api_mode"]
+        mode.to_s == "responses"
+      end
+
+      def current_params
+        chat.instance_variable_get(:@params) || {}
+      end
+
+      def merge_params(**new_params)
+        chat.with_params(**current_params, **new_params)
+      end
+
+      def record(kind, detail = nil)
+        decision_recorder.call(kind, profile.model_id, detail)
+      end
+    end
+  end
+end