smith-agents 0.4.0

data/lib/smith/tasks/doctor.rake

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+def smith_load_environment
+  Rake::Task[:environment].invoke if Rake::Task.task_defined?(:environment)
+  require "smith"
+  require "smith/doctor"
+end
+
+namespace :smith do
+  desc "Verify Smith integration (offline)"
+  task :doctor do
+    smith_load_environment
+    report = Smith::Doctor.run
+    exit report.exit_code unless report.passed?
+  end
+
+  namespace :doctor do
+    desc "Verify Smith integration with live provider call"
+    task :live do
+      smith_load_environment
+      report = Smith::Doctor.run(live: true)
+      exit report.exit_code unless report.passed?
+    end
+
+    desc "Verify Smith workflow durability"
+    task :durability do
+      smith_load_environment
+      report = Smith::Doctor.run(durability: true)
+      exit report.exit_code unless report.passed?
+    end
+  end
+
+  desc "Scaffold Smith configuration files"
+  task :install do
+    smith_load_environment
+    Smith::Doctor::Installer.run
+  end
+end

data/lib/smith/tool/budget_enforcement.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Smith
+  class Tool < RubyLLM::Tool
+    module BudgetEnforcement
+      private
+
+      def charge_tool_call!
+        allowance = self.class.current_tool_call_allowance
+        ledger = self.class.current_ledger
+        workflow_active = ledger&.limits&.key?(:tool_calls)
+
+        check_agent_tool_calls!(allowance)
+        commit_tool_call_charges!(ledger, allowance, workflow_active)
+      end
+
+      def check_agent_tool_calls!(allowance)
+        return unless allowance
+
+        raise BudgetExceeded, "agent tool_calls budget exceeded" if allowance[:remaining] <= 0
+      end
+
+      def commit_tool_call_charges!(ledger, allowance, workflow_active)
+        if workflow_active
+          ledger.reserve!(:tool_calls, 1)
+          ledger.reconcile!(:tool_calls, 1, 1)
+        end
+
+        allowance[:remaining] -= 1 if allowance
+      end
+    end
+  end
+end

data/lib/smith/tool/capability_builder.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Smith
+  class Tool < RubyLLM::Tool
+    class CapabilityBuilder
+      def initialize
+        @capabilities = {}
+      end
+
+      def sensitivity(value)  = @capabilities[:sensitivity] = value
+      def privilege(value)    = @capabilities[:privilege] = value
+      def network(value)      = @capabilities[:network] = value
+      def approval(value)     = @capabilities[:approval] = value
+      def data_volume(value)  = @capabilities[:data_volume] = value
+      def to_h                = @capabilities
+    end
+  end
+end

data/lib/smith/tool/capture.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Smith
+  class Tool < RubyLLM::Tool
+    module Capture
+      private
+
+      def capture_result_if_configured(kwargs, result)
+        block = self.class.capture_result
+        return unless block
+
+        collector = self.class.current_tool_result_collector
+        return unless collector
+
+        captured = block.call(kwargs, result)
+        collector.call({ tool: name.to_s, captured: captured }) if captured
+      rescue StandardError => e
+        Smith.config.logger&.warn("[Smith] capture_result failed for #{name}: #{e.message}")
+      end
+    end
+  end
+end

data/lib/smith/tool/compatibility.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Smith
+  class Tool
+    # Compatibility spec for a Tool class. Built by Tool.compatible_with(...)
+    # and consulted by Smith::Models::Normalizer when deciding whether
+    # to route, drop, or pass through a tool.
+    #
+    # Spec shape (frozen Hash):
+    #   providers: Set[Symbol]?,            # allowlist; nil = all allowed
+    #   endpoints: Hash[Symbol => Set],     # per-provider endpoint constraints
+    #   except:    Hash[Symbol => Set]?     # exception list (overrides allow)
+    #
+    # Tools that don't declare compatible_with are universally compatible
+    # — Compatibility.allows?(nil, profile) returns true.
+    module Compatibility
+      module_function
+
+      # Parses the DSL invocation:
+      #   compatible_with :anthropic
+      #   compatible_with :anthropic, :gemini, openai: :responses
+      #   compatible_with except: { openai: :chat_completions }
+      def parse(positional, except:, **provider_endpoints)
+        providers_arg = positional + provider_endpoints.keys
+        providers = if providers_arg.empty?
+                      nil
+                    else
+                      providers_arg.map(&:to_sym).to_set
+                    end
+        endpoints = provider_endpoints.transform_values { |v| Array(v).map(&:to_sym).to_set }
+        except_set = except&.transform_values { |v| Array(v).map(&:to_sym).to_set }
+
+        {
+          providers: providers,
+          endpoints: endpoints,
+          except: except_set
+        }.freeze
+      end
+
+      # Returns true if the (provider, endpoint) combination is allowed
+      # by spec. `effective_endpoint` defaults to profile.endpoint_mode
+      # but callers (e.g., Smith::Models::Normalizer) can override when
+      # user policy downgrades the endpoint — e.g., a profile with
+      # tools_with_thinking_route: :responses still has its tools checked
+      # against :chat_completions when Smith.config.openai_api_mode is
+      # :off (no routing).
+      #
+      # spec == nil => universally compatible (no compatible_with declared).
+      def allows?(spec, profile, effective_endpoint: nil)
+        return true if spec.nil?
+
+        provider = profile.provider
+        endpoint = effective_endpoint || profile.endpoint_mode
+
+        # exception list: explicit deny wins
+        if (excluded = spec[:except]&.[](provider)) && excluded.include?(endpoint)
+          return false
+        end
+
+        # allowlist by provider (nil = all allowed)
+        return false if spec[:providers] && !spec[:providers].include?(provider)
+
+        # endpoint constraint when present for the matched provider
+        if (allowed_endpoints = spec[:endpoints][provider])
+          return allowed_endpoints.include?(endpoint)
+        end
+
+        true
+      end
+    end
+  end
+end

data/lib/smith/tool/policy.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Smith
+  class Tool < RubyLLM::Tool
+    module Policy
+      private
+
+      def check_privilege!(kwargs)
+        privilege = self.class.capabilities&.dig(:privilege)
+        return if privilege.nil? || privilege == :none
+
+        context = kwargs[:context] || {}
+        enforce_privilege!(privilege, context)
+      end
+
+      def enforce_privilege!(privilege, context)
+        require_authenticated!(context) if %i[authenticated elevated].include?(privilege)
+        require_elevated!(context) if privilege == :elevated
+      end
+
+      def require_authenticated!(context)
+        raise ToolPolicyDenied, "privilege requires context[:user]" unless context[:user]
+      end
+
+      def require_elevated!(context)
+        return if context[:role] == :elevated
+
+        raise ToolPolicyDenied, "privilege :elevated requires context[:role] == :elevated"
+      end
+
+      def check_authorization!(kwargs)
+        authorizer = self.class.authorize
+        return unless authorizer
+
+        context = kwargs[:context]
+        raise ToolPolicyDenied unless authorizer.call(context)
+      end
+    end
+  end
+end

data/lib/smith/tool.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require "ruby_llm"
+
+require_relative "tool/capability_builder"
+require_relative "tool/policy"
+require_relative "tool/budget_enforcement"
+require_relative "tool/capture"
+require_relative "tool/compatibility"
+
+module Smith
+  class Tool < RubyLLM::Tool
+    include Policy
+    include BudgetEnforcement
+    include Capture
+
+    class << self
+      # Tool subclasses inherit the parent's compatible_with spec by
+      # reference (the spec is a frozen Hash; immutability makes shared
+      # references safe). Subclasses can override by calling
+      # `compatible_with` again — assigns a NEW frozen Hash to its own
+      # @compatible_with_spec, leaving the parent untouched.
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@compatible_with_spec, @compatible_with_spec)
+      end
+
+      # Declarative compatibility DSL. Examples:
+      #   compatible_with :anthropic, :gemini
+      #   compatible_with :anthropic, :gemini, openai: :responses
+      #   compatible_with except: { openai: :chat_completions }
+      #
+      # Tools that NEVER declare compatible_with are universally compatible.
+      # Consumed by Smith::Models::Normalizer.drop_incompatible_tools when
+      # the resolved model rejects the (tools + thinking) combo and no
+      # routing fallback (e.g., openai_api_mode :auto) is available.
+      def compatible_with(*providers, except: nil, **provider_endpoints)
+        @compatible_with_spec = Compatibility.parse(providers, except: except, **provider_endpoints)
+      end
+
+      attr_reader :compatible_with_spec
+
+      def current_guardrails
+        Thread.current[:smith_tool_guardrails]
+      end
+
+      def current_guardrails=(value)
+        Thread.current[:smith_tool_guardrails] = value
+      end
+
+      def current_deadline
+        Thread.current[:smith_tool_deadline]
+      end
+
+      def current_deadline=(value)
+        Thread.current[:smith_tool_deadline] = value
+      end
+
+      def current_ledger
+        Thread.current[:smith_tool_ledger]
+      end
+
+      def current_ledger=(value)
+        Thread.current[:smith_tool_ledger] = value
+      end
+
+      def current_tool_call_allowance
+        Thread.current[:smith_tool_call_allowance]
+      end
+
+      def current_tool_call_allowance=(value)
+        Thread.current[:smith_tool_call_allowance] = value
+      end
+
+      def current_tool_result_collector
+        Thread.current[:smith_tool_result_collector]
+      end
+
+      def current_tool_result_collector=(value)
+        Thread.current[:smith_tool_result_collector] = value
+      end
+
+      def category(value = nil)
+        return @category if value.nil?
+
+        @category = value
+      end
+
+      def capabilities(&)
+        return @capabilities unless block_given?
+
+        builder = CapabilityBuilder.new
+        builder.instance_eval(&)
+        @capabilities = builder.to_h
+      end
+
+      def authorize(&block)
+        return @authorize unless block_given?
+
+        @authorize = block
+      end
+
+      def before_execute(&block)
+        return @before_execute unless block_given?
+
+        @before_execute = block
+      end
+
+      def capture_result(&block)
+        return @capture_result unless block_given?
+
+        @capture_result = block
+      end
+    end
+
+    def execute(**kwargs)
+      run_before_execute_hook!(kwargs)
+      check_tool_deadline!
+      check_privilege!(kwargs)
+      check_authorization!(kwargs)
+      run_tool_guardrails!(kwargs)
+      check_tool_deadline!
+      charge_tool_call!
+
+      start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      result = perform(**kwargs)
+      duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
+
+      emit_tool_trace(kwargs, result, duration)
+      capture_result_if_configured(kwargs, result)
+      result
+    end
+
+    private
+
+    def run_before_execute_hook!(kwargs)
+      hook = self.class.before_execute
+      return unless hook
+
+      hook.call(self, kwargs)
+    end
+
+    def run_tool_guardrails!(kwargs)
+      guardrails_classes = self.class.current_guardrails
+      return unless guardrails_classes
+
+      Array(guardrails_classes).each do |guardrails_class|
+        Guardrails::Runner.run_tool(guardrails_class, name.to_sym, kwargs)
+      end
+    end
+
+    def emit_tool_trace(kwargs, result, duration)
+      Smith::Trace.record(
+        type: :tool_call,
+        data: { tool: name, args: kwargs, result: result, duration: duration },
+        sensitivity: self.class.capabilities&.dig(:sensitivity) || :low
+      )
+    end
+
+    def check_tool_deadline!
+      deadline = self.class.current_deadline
+      return unless deadline
+
+      raise DeadlineExceeded, "wall_clock deadline exceeded during tool execution" if Time.now.utc >= deadline
+    end
+
+    def perform(**kwargs)
+      raise NotImplementedError, "#{self.class} must implement #perform"
+    end
+  end
+end

data/lib/smith/tools/think.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Smith
+  module Tools
+    class Think < Smith::Tool
+      description "Think through your approach between steps. " \
+                  "Plan what to do next, evaluate progress, and identify gaps."
+      category :computation
+
+      # Compatible with Anthropic (extended thinking is native), Gemini
+      # (thinking is the default request shape), and OpenAI BUT ONLY on
+      # /v1/responses — chat-completions rejects function tools combined
+      # with reasoning_effort for the gpt-5 family. The normalizer uses
+      # this spec when deciding whether to drop Think on a model whose
+      # profile rejects (tools + thinking) AND no routing fallback exists.
+      compatible_with :anthropic, :gemini, openai: :responses
+
+      param :thought, type: :string, required: true
+
+      def perform(thought:) # rubocop:disable Lint/UnusedMethodArgument
+        { acknowledged: true }
+      end
+    end
+  end
+end

data/lib/smith/tools/url_fetcher.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Smith
+  module Tools
+    class UrlFetcher < Smith::Tool
+      description "Fetch the content of a specific URL"
+      category :data_access
+
+      param :url, type: :string, required: true
+
+      def perform(url:)
+        raise NotImplementedError, "#{self.class} requires a host-app implementation"
+      end
+    end
+  end
+end

data/lib/smith/tools/web_search.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Smith
+  module Tools
+    class WebSearch < Smith::Tool
+      description "Search the web for current information on a topic"
+      category :data_access
+
+      param :query, type: :string, required: true
+      param :max_results, type: :integer, required: false
+
+      def perform(query:, max_results: 5)
+        raise NotImplementedError, "#{self.class} requires a host-app implementation"
+      end
+    end
+  end
+end

data/lib/smith/tools.rb

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

data/lib/smith/trace/logger.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Smith
+  module Trace
+    class Logger
+      CONFIG_MAP = {
+        transition: :trace_transitions,
+        tool_call: :trace_tool_calls,
+        token_usage: :trace_token_usage,
+        cost: :trace_cost,
+        normalizer_decision: :trace_normalizer
+      }.freeze
+
+      CONTENT_KEYS = %i[content prompt response args result].freeze
+
+      def record(type:, data:)
+        return unless type_enabled?(type)
+
+        logger = Smith.config.logger
+        return unless logger
+
+        logger.info("[Smith::Trace] #{type}: #{filter_content(data).inspect}")
+      end
+
+      private
+
+      def type_enabled?(type)
+        config_key = CONFIG_MAP[type]
+        return true unless config_key
+
+        Smith.config.send(config_key) != false
+      end
+
+      def filter_content(data)
+        case Smith.config.trace_content
+        when true
+          data
+        when :redacted
+          data.transform_values { |v| v.is_a?(String) ? "[REDACTED]" : v }
+        else
+          data.except(*CONTENT_KEYS)
+        end
+      end
+    end
+  end
+end

data/lib/smith/trace/memory.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Smith
+  module Trace
+    class Memory
+      CONFIG_MAP = {
+        transition: :trace_transitions,
+        tool_call: :trace_tool_calls,
+        token_usage: :trace_token_usage,
+        cost: :trace_cost,
+        normalizer_decision: :trace_normalizer
+      }.freeze
+
+      CONTENT_KEYS = %i[content prompt response args result].freeze
+
+      attr_reader :traces
+
+      def initialize
+        @traces = []
+      end
+
+      def record(type:, data:)
+        return unless type_enabled?(type)
+
+        @traces << { type: type, data: filter_content(data) }
+      end
+
+      def clear!
+        @traces = []
+      end
+
+      private
+
+      def type_enabled?(type)
+        config_key = CONFIG_MAP[type]
+        return true unless config_key
+
+        Smith.config.send(config_key) != false
+      end
+
+      def filter_content(data)
+        case Smith.config.trace_content
+        when true
+          data
+        when :redacted
+          data.transform_values { |v| v.is_a?(String) ? "[REDACTED]" : v }
+        else
+          data.except(*CONTENT_KEYS)
+        end
+      end
+    end
+  end
+end

data/lib/smith/trace/open_telemetry.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Smith
+  module Trace
+    class OpenTelemetry
+      CONFIG_MAP = {
+        transition: :trace_transitions,
+        tool_call: :trace_tool_calls,
+        token_usage: :trace_token_usage,
+        cost: :trace_cost
+      }.freeze
+
+      CONTENT_KEYS = %i[content prompt response args result].freeze
+
+      def initialize
+        require "opentelemetry-api"
+        @tracer = ::OpenTelemetry.tracer_provider.tracer("smith", Smith::VERSION)
+      rescue LoadError
+        @tracer = nil
+        Smith.config.logger&.warn(
+          "Smith::Trace::OpenTelemetry requires the opentelemetry-api gem. " \
+          "Add it to your Gemfile to enable OpenTelemetry tracing."
+        )
+      end
+
+      def record(type:, data:)
+        return unless @tracer
+        return unless type_enabled?(type)
+
+        filtered = filter_content(data)
+        @tracer.in_span("smith.#{type}") do |span|
+          filtered.each { |key, value| span.set_attribute("smith.#{key}", value.to_s) }
+        end
+      end
+
+      private
+
+      def type_enabled?(type)
+        config_key = CONFIG_MAP[type]
+        return true unless config_key
+
+        Smith.config.send(config_key) != false
+      end
+
+      def filter_content(data)
+        case Smith.config.trace_content
+        when true
+          data
+        when :redacted
+          data.transform_values { |v| v.is_a?(String) ? "[REDACTED]" : v }
+        else
+          data.except(*CONTENT_KEYS)
+        end
+      end
+    end
+  end
+end