smith-agents 0.4.0

data/lib/smith/events/bus.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Smith
+  module Events
+    class Scope
+      def initialize
+        @handles = []
+      end
+
+      def on(event_class, **, &)
+        handle = Events.on(event_class, **, &)
+        @handles << handle
+        handle
+      end
+
+      def cancel_all
+        @handles.each(&:cancel)
+      end
+    end
+
+    class << self
+      def subscriptions
+        @subscriptions ||= []
+      end
+
+      def on(event_class, **opts, &block)
+        sub = Subscription.new(event_class, handler: block, predicate: opts[:if])
+        subscriptions << sub
+        sub
+      end
+
+      def emit(event)
+        subscriptions.each { |sub| dispatch_to(sub, event) }
+      end
+
+      def within
+        scope = Scope.new
+        yield scope
+      ensure
+        scope&.cancel_all
+      end
+
+      def reset!
+        @subscriptions = []
+      end
+
+      private
+
+      def dispatch_to(sub, event)
+        return if sub.cancelled?
+        return unless event.is_a?(sub.event_class)
+        return if sub.predicate && !sub.predicate.call(event)
+
+        sub.handler.call(event)
+      rescue StandardError => e
+        Smith.config.logger&.error("Smith::Events handler error: #{e.message}")
+      end
+    end
+  end
+end

data/lib/smith/events/step_completed.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Smith
+  module Events
+    class StepCompleted < Smith::Event
+      attribute :transition, Types::Strict::Symbol
+      attribute :from, Types::Strict::Symbol.optional
+      attribute :to, Types::Strict::Symbol
+    end
+  end
+end

data/lib/smith/events/subscription.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Smith
+  module Events
+    class Subscription
+      attr_reader :event_class, :handler, :predicate
+
+      def initialize(event_class, handler:, predicate: nil)
+        @event_class = event_class
+        @handler = handler
+        @predicate = predicate
+        @cancelled = false
+      end
+
+      def cancel
+        @cancelled = true
+      end
+
+      def cancelled?
+        @cancelled
+      end
+    end
+  end
+end

data/lib/smith/events.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Smith
+  module Events; end
+end

data/lib/smith/guardrails/runner.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Smith
+  class Guardrails
+    module Runner
+      class << self
+        def run_inputs(guardrails_class, payload)
+          run_layer(guardrails_class, guardrails_class.input, payload, GuardrailFailed)
+        end
+
+        def run_outputs(guardrails_class, payload)
+          run_layer(guardrails_class, guardrails_class.output, payload, GuardrailFailed)
+        end
+
+        def run_tool(guardrails_class, tool_name, payload)
+          matching = guardrails_class.tool.select { |d| d[:on]&.include?(tool_name) }
+          run_layer(guardrails_class, matching, payload, ToolGuardrailFailed)
+        end
+
+        private
+
+        def run_layer(guardrails_class, declarations, payload, error_class)
+          instance = guardrails_class.new
+          declarations.each { |d| instance.send(d[:name], payload) }
+        rescue Smith::Error
+          raise
+        rescue StandardError => e
+          raise build_guardrail_error(error_class, e)
+        end
+
+        def build_guardrail_error(error_class, error)
+          return error_class.new(error.message, retryable: retryable_tool_guardrail?(error.message)) if error_class == ToolGuardrailFailed
+
+          error_class.new(error.message)
+        end
+
+        def retryable_tool_guardrail?(message)
+          text = message.to_s.downcase
+          text.include?("rate limit") || text.include?("malformed args")
+        end
+      end
+    end
+  end
+end

data/lib/smith/guardrails/url_verifier.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Smith
+  class Guardrails
+    class UrlVerifier; end
+  end
+end

data/lib/smith/guardrails.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Smith
+  class Guardrails
+    class << self
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@inputs, (@inputs || []).dup)
+        subclass.instance_variable_set(:@tools, (@tools || []).dup)
+        subclass.instance_variable_set(:@outputs, (@outputs || []).dup)
+      end
+
+      def input(name = nil, **)
+        return @inputs || [] if name.nil?
+
+        @inputs ||= []
+        @inputs << ({ name: name, ** })
+      end
+
+      def tool(name = nil, **)
+        return @tools || [] if name.nil?
+
+        @tools ||= []
+        @tools << ({ name: name, ** })
+      end
+
+      def output(name = nil, **)
+        return @outputs || [] if name.nil?
+
+        @outputs ||= []
+        @outputs << ({ name: name, ** })
+      end
+    end
+  end
+end

data/lib/smith/models/inference.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+module Smith
+  module Models
+    # Pattern-based provider capability rules. Library-level knowledge
+    # about how PROVIDER FAMILIES shape their API payloads — independent
+    # of specific model ids or downstream applications.
+    #
+    # Smith ships ZERO specific model_id declarations. Each rule matches
+    # a regex or version-aware predicate against the resolved model_id
+    # at runtime. New model releases that fit existing patterns work
+    # automatically (e.g., a future claude-opus-4-9 matches the Opus 4.7+
+    # adaptive-thinking rule).
+    #
+    # Rule order matters: most specific patterns first. Hosts that need
+    # to ADD provider knowledge (a new provider Smith doesn't ship rules
+    # for, or a custom finetune) can `prepend_rule` at runtime.
+    #
+    # The rules array is mutable for runtime extension; tests must use
+    # the `with_rules(*rules) { ... }` block helper to avoid test-suite
+    # leakage of `prepend_rule` mutations.
+    module Inference
+      # A single rule maps a model_id matcher to capability values.
+      # The matcher is a Proc[String -> Boolean] — regex match OR
+      # version-aware predicate (e.g., Opus 4.7+).
+      Rule = Data.define(
+        :provider,
+        :matcher,
+        :thinking_shape,
+        :accepts_temperature,
+        :tools_with_thinking_native,
+        :tools_with_thinking_route
+      ) do
+        def matches?(model_id)
+          matcher.call(model_id.to_s)
+        end
+
+        def to_profile(model_id)
+          Profile.new(
+            model_id: model_id.to_s,
+            provider: provider,
+            thinking_shape: thinking_shape,
+            accepts_temperature: accepts_temperature,
+            tools_with_thinking_native: tools_with_thinking_native,
+            tools_with_thinking_route: tools_with_thinking_route
+          )
+        end
+      end
+
+      def self.rules
+        @_rules
+      end
+
+      def self.prepend_rule(rule)
+        rules.unshift(rule)
+      end
+
+      def self.reset!
+        @_rules = default_rules.dup
+      end
+
+      # Block-form test helper. Yields with the given rules INSTEAD of
+      # the default set; restores afterward even if the block raises.
+      # Prevents test-suite leakage of `prepend_rule` mutations.
+      def self.with_rules(*overrides)
+        previous = @_rules
+        @_rules = overrides.flatten
+        yield
+      ensure
+        @_rules = previous
+      end
+
+      def self.profile_for(model_id)
+        rule = rules.find { |r| r.matches?(model_id) }
+        rule&.to_profile(model_id)
+      end
+
+      # Library-shipped pattern rules. Order: most specific first per
+      # provider; provider families in declaration order. NO specific
+      # model_id strings — only PROVIDER FAMILY and version-range patterns.
+      def self.default_rules
+        [
+          # ----- Anthropic -----
+
+          # Opus 4.7+: adaptive thinking, no temperature accepted.
+          Rule.new(
+            provider: :anthropic,
+            matcher: lambda { |id|
+              m = id.match(/\Aclaude-opus-4-(\d+)/)
+              m && m[1].to_i >= 7
+            },
+            thinking_shape: :adaptive,
+            accepts_temperature: false,
+            tools_with_thinking_native: true,
+            tools_with_thinking_route: nil
+          ),
+          # Opus/Sonnet/Haiku 4.0-4.6: budget_tokens thinking.
+          Rule.new(
+            provider: :anthropic,
+            matcher: lambda { |id|
+              m = id.match(/\Aclaude-(?:opus|sonnet|haiku)-4-(\d+)/)
+              m && m[1].to_i <= 6
+            },
+            thinking_shape: :budget_tokens,
+            accepts_temperature: true,
+            tools_with_thinking_native: true,
+            tools_with_thinking_route: nil
+          ),
+          # Claude 3.7 Sonnet introduced extended thinking via budget_tokens.
+          # Claude 3.5 and earlier DON'T have thinking — handled by the
+          # safe-default Anthropic rule below.
+          Rule.new(
+            provider: :anthropic,
+            matcher: ->(id) { id.match?(/\Aclaude-3-7/) },
+            thinking_shape: :budget_tokens,
+            accepts_temperature: true,
+            tools_with_thinking_native: true,
+            tools_with_thinking_route: nil
+          ),
+          # Any other Claude (3.5, 3.0, 2.x): safe default — no thinking,
+          # accepts temperature, tools work normally on chat-completions.
+          Rule.new(
+            provider: :anthropic,
+            matcher: ->(id) { id.match?(/\Aclaude-/) },
+            thinking_shape: nil,
+            accepts_temperature: true,
+            tools_with_thinking_native: false,
+            tools_with_thinking_route: nil
+          ),
+
+          # ----- OpenAI -----
+
+          # gpt-5 family + o-series reasoning models: reasoning_effort,
+          # no temperature, needs /v1/responses for tools+thinking combo
+          # (chat-completions rejects the combination).
+          Rule.new(
+            provider: :openai,
+            matcher: ->(id) { id.match?(/\A(gpt-5|o\d)/) },
+            thinking_shape: :reasoning_effort,
+            accepts_temperature: false,
+            tools_with_thinking_native: false,
+            tools_with_thinking_route: :responses
+          ),
+          # gpt-4.x: no thinking, accepts temperature.
+          Rule.new(
+            provider: :openai,
+            matcher: ->(id) { id.match?(/\Agpt-4/) },
+            thinking_shape: nil,
+            accepts_temperature: true,
+            tools_with_thinking_native: false,
+            tools_with_thinking_route: nil
+          ),
+          # Older OpenAI: no thinking, accepts temperature.
+          Rule.new(
+            provider: :openai,
+            matcher: ->(id) { id.match?(/\A(gpt-3|text-)/) },
+            thinking_shape: nil,
+            accepts_temperature: true,
+            tools_with_thinking_native: false,
+            tools_with_thinking_route: nil
+          ),
+
+          # ----- Gemini -----
+
+          # Gemini 2.5+ (all variants, including Flash) supports thinking
+          # via budget_tokens. Earlier Gemini (1.x, 2.0) does not.
+          Rule.new(
+            provider: :gemini,
+            matcher: lambda { |id|
+              m = id.match(/\Agemini-(\d+)\.(\d+)/)
+              m && (m[1].to_i > 2 || (m[1].to_i == 2 && m[2].to_i >= 5))
+            },
+            thinking_shape: :budget_tokens,
+            accepts_temperature: true,
+            tools_with_thinking_native: true,
+            tools_with_thinking_route: nil
+          ),
+          # Any other Gemini (1.x, 2.0): no thinking.
+          Rule.new(
+            provider: :gemini,
+            matcher: ->(id) { id.match?(/\Agemini-/) },
+            thinking_shape: nil,
+            accepts_temperature: true,
+            tools_with_thinking_native: false,
+            tools_with_thinking_route: nil
+          )
+        ].freeze
+      end
+
+      # Eagerly initialized at module load (after default_rules is
+      # defined) so concurrent first-callers cannot race the `||=`
+      # lazy-init and end up holding references to separate Array
+      # instances. Host calls to `prepend_rule` / `reset!` / `with_rules`
+      # are still expected to fire only at setup time on the main
+      # thread; concurrent mutation after boot is unsupported.
+      @_rules = default_rules.dup
+    end
+  end
+end

data/lib/smith/models/normalizer.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+module Smith
+  module Models
+    # Per-chat-construction request shaper. Mutates a RubyLLM::Chat
+    # in place to fit the resolved model's capability profile, using
+    # RubyLLM's public `with_*` API where it covers the case and
+    # scoped instance-variable nulling where no public API exists
+    # (RubyLLM has no `without_temperature` / `without_thinking`).
+    #
+    # Lifetime: built fresh inside Smith::Agent.chat per construction.
+    # Never crosses threads. Never cached.
+    #
+    # Runs OUTSIDE any workflow context — does NOT access:
+    #   - Smith.scoped_artifacts (thread-local, set only inside workflows)
+    #   - Tool.current_ledger / Tool.current_tool_result_collector
+    #   - Thread.current[:smith_last_agent_result]
+    # Smith::Trace.record is the ONLY observability surface the normalizer
+    # touches; it's safe outside workflow scope.
+    class Normalizer
+      extend Dry::Initializer
+
+      # Decision record emitted as a :normalizer_decision trace event.
+      # The Decision.kind value space is exhaustively documented in the
+      # plan; adding a new kind requires updating the trace CONFIG_MAP.
+      Decision = Data.define(:kind, :model_id, :detail)
+
+      # No type predicate on options — Smith's existing Dry::Initializer
+      # call sites trust internal callers and don't enforce option types.
+      option :chat
+      option :profile
+
+      # Returns Array<Decision> of mutations performed. The chat is
+      # mutated in place; callers usually ignore the return value
+      # except in tests.
+      def self.apply!(chat, profile:)
+        return [] if profile.nil?
+
+        new(chat: chat, profile: profile).apply!
+      end
+
+      def apply!
+        @decisions = []
+        normalize_temperature
+        normalize_thinking
+        normalize_tools_routing
+        emit_trace
+        @decisions
+      end
+
+      private
+
+      def normalize_temperature
+        return if profile.accepts_temperature
+        return if chat.instance_variable_get(:@temperature).nil?
+
+        # No public `without_temperature` in RubyLLM 1.15 — direct ivar
+        # nulling is the only path. Scoped: only @temperature, only on
+        # models that explicitly reject it. Add `RubyLLM::Chat#without_temperature`
+        # upstream and Smith retires this line (see UPSTREAM_PROPOSAL.md).
+        chat.instance_variable_set(:@temperature, nil)
+        @decisions << Decision.new(kind: :temperature_dropped, model_id: profile.model_id, detail: nil)
+      end
+
+      def normalize_thinking
+        thinking = chat.instance_variable_get(:@thinking)
+        return if thinking.nil? || !thinking.enabled?
+
+        case profile.thinking_shape
+        when nil
+          chat.instance_variable_set(:@thinking, nil)
+          @decisions << Decision.new(kind: :thinking_dropped, model_id: profile.model_id, detail: nil)
+        when :budget_tokens, :reasoning_effort
+          # RubyLLM's provider renderers already emit the right shape.
+          # Leave @thinking unchanged.
+        when :adaptive
+          translate_thinking_to_adaptive(thinking)
+        end
+      end
+
+      def translate_thinking_to_adaptive(thinking)
+        effort = thinking.respond_to?(:effort) && thinking.effort ? thinking.effort : "high"
+        merge_params(thinking: { type: "adaptive" }, output_config: { effort: effort })
+
+        # Null @thinking so RubyLLM's render_payload doesn't ALSO emit
+        # the budget_tokens shape that would conflict with our adaptive
+        # injection at deep_merge time.
+        chat.instance_variable_set(:@thinking, nil)
+        @decisions << Decision.new(
+          kind: :thinking_translated_to_adaptive,
+          model_id: profile.model_id,
+          detail: { effort: effort }
+        )
+      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
+      end
+
+      # with_params REPLACES @params in RubyLLM (chat.rb:96), so the
+      # normalizer always reads existing + merges + writes back to
+      # preserve prior user calls to with_params.
+      def merge_params(**new_params)
+        existing = chat.instance_variable_get(:@params) || {}
+        chat.with_params(**existing, **new_params)
+      end
+
+      def emit_trace
+        return if @decisions.empty?
+        return unless defined?(Smith::Trace)
+
+        @decisions.each do |decision|
+          Smith::Trace.record(type: :normalizer_decision, data: decision.to_h)
+        end
+      end
+    end
+  end
+end

data/lib/smith/models/profile.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Smith
+  module Models
+    # Immutable capability record for a model id. Holds only inherent
+    # provider/model properties — never pricing, never API keys, never
+    # request-specific data. Library-shipped rules live in
+    # Smith::Models::Inference (pattern-based).
+    #
+    # Fields:
+    #   model_id                   — canonical id ("claude-opus-4-7")
+    #   provider                   — :anthropic | :openai | :gemini | :xai | ...
+    #   thinking_shape             — nil | :budget_tokens | :reasoning_effort | :adaptive
+    #     nil               — model has no thinking concept (don't send thinking)
+    #     :budget_tokens    — RubyLLM's default Anthropic shape (Opus 4.6, Sonnet 4.x)
+    #     :reasoning_effort — OpenAI-style reasoning_effort string
+    #     :adaptive         — Opus 4.7+ adaptive shape (output_config.effort)
+    #   accepts_temperature        — false → normalizer strips @temperature
+    #   tools_with_thinking_native — true → tools + thinking on default endpoint OK
+    #   tools_with_thinking_route  — nil | :responses (which endpoint to route to
+    #                                when both tools + thinking are present and
+    #                                native combo is unsupported)
+    Profile = Data.define(
+      :model_id,
+      :provider,
+      :thinking_shape,
+      :accepts_temperature,
+      :tools_with_thinking_native,
+      :tools_with_thinking_route
+    ) do
+      # Derived from tools_with_thinking_route. Exposed on Profile (not on
+      # Tool::Compatibility) so the Profile is a self-contained capability
+      # record without cross-namespace dependency.
+      def endpoint_mode
+        tools_with_thinking_route == :responses ? :responses : :chat_completions
+      end
+    end
+  end
+end