smith-agents 0.7.0 → 0.8.0

data/lib/smith/tool/execution_batch_admission.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+module Smith
+  class Tool < RubyLLM::Tool
+    class ExecutionBatchAdmission
+      extend Dry::Initializer
+
+      option :calls
+      option :context
+
+      def call
+        return if calls.empty? || bounded_completion_admits_calls?
+
+        reservation = reserve
+        return reservation if reservation
+        return unless call_budget || workflow_budgeted?
+
+        raise BudgetExceeded, "agent tool_calls budget exceeded"
+      end
+
+      private
+
+      def reserve
+        case call_budget
+        when CallAllowance
+          call_budget.reserve_batch(requested_tool_names, ledger:)
+        when Hash
+          LegacyCallAllowance.reserve_batch(call_budget, calls.length, ledger:)
+        else
+          reserve_workflow_budget
+        end
+      end
+
+      def reserve_workflow_budget
+        return unless workflow_budgeted?
+
+        ledger_reservation = ledger.reserve!(:tool_calls, calls.length)
+        CallReservation.new(limit: calls.length, ledger:, ledger_reservation:)
+      end
+
+      def bounded_completion_admits_calls?
+        call_budget.is_a?(CallAllowance) && call_budget.complete_on_exhaustion?
+      end
+
+      def workflow_budgeted? = ledger&.limits&.key?(:tool_calls)
+
+      def requested_tool_names = calls.map { _1.name.to_s }
+
+      def call_budget = context.fetch(:current_tool_call_allowance)
+
+      def ledger = context.fetch(:current_ledger)
+    end
+  end
+end

data/lib/smith/tool/execution_batch_builder.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Smith
+  class Tool < RubyLLM::Tool
+    class ExecutionBatchBuilder
+      def initialize
+        @default_sequence = InvocationSequence.new
+        @invocations = ExecutionBatchInvocations.new
+      end
+
+      def call(entries:, tools:, context:, call_admissions:)
+        sources = ExecutionBatchSources.new(entries).call
+        sources_by_call = index_sources(sources)
+        source_targets = build_targets(sources, tools)
+        source_requests = build_requests(source_targets, sources_by_call, context)
+        dispatch_calls = build_dispatch_calls(source_requests, sources_by_call)
+        attributes = batch_attributes(sources, source_targets, source_requests, dispatch_calls, context)
+        inherited = call_admissions && remap(call_admissions, dispatch_calls)
+        build_batch(attributes, inherited)
+      end
+
+      private
+
+      def build_requests(targets, sources_by_call, context)
+        sequence = context.fetch(:current_invocation_sequence) || @default_sequence
+        target_sources = targets.each_key.map { sources_by_call.fetch(_1) }
+        invocations = @invocations.call(sources: target_sources, sequence:)
+        arguments = target_sources.each_with_object({}.compare_by_identity) do |source, indexed|
+          indexed[source.tool_call] = source.arguments
+        end.freeze
+        ExecutionBatchRequests.new(targets:, invocations:, arguments:).call
+      end
+
+      def batch_attributes(sources, targets, requests, dispatch_calls, context)
+        {
+          context:,
+          tool_calls: build_tool_calls(sources, dispatch_calls),
+          source_calls: sources.map(&:tool_call).freeze,
+          dispatch_calls:,
+          source_calls_by_dispatch: invert(dispatch_calls),
+          requests: remap(requests, dispatch_calls),
+          targets: remap(targets, dispatch_calls)
+        }
+      end
+
+      def build_batch(attributes, inherited_admissions)
+        tool_calls = attributes.fetch(:tool_calls)
+        reservation = ExecutionBatchAdmission.new(
+          calls: tool_calls.values.freeze,
+          context: attributes.fetch(:context)
+        ).call
+        ExecutionBatch.new(
+          **attributes,
+          call_reservation: reservation,
+          call_admissions: build_call_admissions(attributes.fetch(:targets), reservation, inherited_admissions)
+        )
+      rescue Exception # rubocop:disable Lint/RescueException
+        reservation&.settle!
+        raise
+      end
+
+      def build_dispatch_calls(requests, sources_by_call)
+        requests.each_with_object({}.compare_by_identity) do |(source_call, request), dispatch_calls|
+          invocation = request.invocation
+          source = sources_by_call.fetch(source_call)
+          dispatch_calls[source_call] = RubyLLM::ToolCall.new(
+            id: invocation.tool_call_id,
+            name: source.name,
+            arguments: request.arguments,
+            thought_signature: source.thought_signature
+          )
+        end.freeze
+      end
+
+      def build_tool_calls(sources, dispatch_calls)
+        sources.to_h { |source| [source.key, dispatch_calls.fetch(source.tool_call, source.tool_call)] }.freeze
+      end
+
+      def remap(source_values, dispatch_calls)
+        source_values.each_with_object({}.compare_by_identity) do |(source_call, value), mapped|
+          mapped[dispatch_calls.fetch(source_call)] = value
+        end.freeze
+      end
+
+      def invert(source)
+        source.each_with_object({}.compare_by_identity) do |(key, value), inverted|
+          inverted[value] = key
+        end.freeze
+      end
+
+      def index_sources(sources)
+        sources.each_with_object({}.compare_by_identity) { |source, indexed| indexed[source.tool_call] = source }.freeze
+      end
+
+      def build_targets(sources, tools)
+        sources.each_with_object({}.compare_by_identity) do |source, targets|
+          tool = tools[source.name.to_sym]
+          targets[source.tool_call] = tool if tool.is_a?(Smith::Tool)
+        end.freeze
+      end
+
+      def build_call_admissions(targets, reservation, inherited)
+        if reservation
+          raise Error, "tool call has overlapping admission owners" if inherited&.any?
+
+          return targets.each_with_object({}.compare_by_identity) do |(tool_call, tool), admissions|
+            admissions[tool_call] = CallAdmission.new(tool:, reservation:)
+          end.freeze
+        end
+        return {}.compare_by_identity.freeze unless inherited
+
+        validate_inherited_admissions!(targets, inherited)
+        inherited
+      end
+
+      def validate_inherited_admissions!(targets, inherited)
+        complete = targets.length == inherited.length && targets.each_key.all? { inherited.key?(_1) }
+        raise Error, "inherited tool admissions do not cover the immutable Smith batch" unless complete
+      end
+    end
+  end
+end

data/lib/smith/tool/execution_batch_collection.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Smith
+  class Tool < RubyLLM::Tool
+    class ExecutionBatchCollection
+      MAX_CALLS = 100
+
+      HASH_MATCH = Module.instance_method(:===)
+      HASH_LENGTH = Hash.instance_method(:length)
+      HASH_EACH_PAIR = Hash.instance_method(:each_pair)
+      HASH_INITIALIZE_COPY = Hash.instance_method(:initialize_copy)
+      OBJECT_RESPOND_TO = Object.instance_method(:respond_to?)
+      REQUIRED_CALL_READERS = %i[name arguments].freeze
+      private_constant :HASH_MATCH, :HASH_LENGTH, :HASH_EACH_PAIR, :HASH_INITIALIZE_COPY, :OBJECT_RESPOND_TO,
+                       :REQUIRED_CALL_READERS
+
+      def self.capture(tool_calls)
+        size = admitted_size(tool_calls)
+        captured = owned_copy(tool_calls)
+        validate_copy_size!(captured, size)
+        indexed_calls(captured)
+      end
+
+      def self.admitted_size(tool_calls)
+        raise Error, "unsupported RubyLLM tool-call collection" unless HASH_MATCH.bind_call(Hash, tool_calls)
+
+        size = HASH_LENGTH.bind_call(tool_calls)
+        return size if size.positive? && size <= MAX_CALLS
+
+        raise Error, "provider tool batch must contain between 1 and #{MAX_CALLS} calls"
+      end
+      private_class_method :admitted_size
+
+      def self.owned_copy(tool_calls)
+        Hash.allocate.tap do |copy|
+          HASH_INITIALIZE_COPY.bind_call(copy, tool_calls)
+          copy.freeze
+        end
+      end
+      private_class_method :owned_copy
+
+      def self.validate_copy_size!(captured, expected_size)
+        return if HASH_LENGTH.bind_call(captured) == expected_size
+
+        raise Error, "provider tool batch changed while it was being captured"
+      end
+      private_class_method :validate_copy_size!
+
+      def self.indexed_calls(captured)
+        snapshot = {}
+        HASH_EACH_PAIR.bind_call(captured) do |_key, tool_call|
+          validate_call!(tool_call)
+          snapshot[snapshot.length] = tool_call
+        end
+        snapshot.freeze
+      end
+      private_class_method :indexed_calls
+
+      def self.validate_call!(tool_call)
+        supported = REQUIRED_CALL_READERS.all? do |reader|
+          OBJECT_RESPOND_TO.bind_call(tool_call, reader)
+        rescue TypeError
+          false
+        end
+        raise Error, "provider tool batch contains an unsupported call" unless supported
+      end
+      private_class_method :validate_call!
+    end
+  end
+end

data/lib/smith/tool/execution_batch_invocations.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Smith
+  class Tool < RubyLLM::Tool
+    class ExecutionBatchInvocations
+      def call(sources:, sequence:)
+        return {}.compare_by_identity.freeze if sources.empty?
+
+        first_ordinal = sequence.reserve(sources.length)
+        sources.each_with_index.with_object({}.compare_by_identity) do |(source, index), invocations|
+          invocations[source.tool_call] = build_invocation(source, index, first_ordinal, sources.length)
+        end.freeze
+      end
+
+      private
+
+      def build_invocation(source, index, first_ordinal, batch_size)
+        Invocation.new(
+          tool_call_id: source.tool_call_id,
+          tool_name: source.canonical_name,
+          ordinal: first_ordinal + index,
+          batch_ordinal: index + 1,
+          batch_size:
+        )
+      end
+    end
+  end
+end

data/lib/smith/tool/execution_batch_lifecycle.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "English"
+
+module Smith
+  class Tool < RubyLLM::Tool
+    module ExecutionBatchLifecycle
+      private
+
+      def smith_tool_execution_batches = @smith_tool_execution_batches ||= ExecutionBatchRegistry.new
+
+      def handle_sequential_tool_calls(tool_calls, ...)
+        batch = execution_batch_context(tool_calls)
+        admit_execution_batch(batch)
+        super(batch.tool_calls, ...)
+      rescue StandardError => e
+        notify_unsettled_batch_failures(batch, e)
+        raise
+      ensure
+        settle_execution_batch(batch, active_error: $ERROR_INFO)
+      end
+
+      def execute_tools_concurrently(tool_calls, ...)
+        batch = execution_batch_context(tool_calls)
+        admit_execution_batch(batch)
+        super(batch.tool_calls, ...)
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        raise unless e.is_a?(StandardError)
+
+        begin
+          notify_unsettled_batch_failures(batch, e)
+        rescue ToolFailureNotificationFailed => notification_failure
+          record_batch_failure(batch, notification_failure)
+        end
+        raise(prioritized_batch_failure(batch) || e)
+      ensure
+        settle_execution_batch(batch, active_error: $ERROR_INFO)
+      end
+
+      def execution_batch_context(tool_calls)
+        smith_tool_execution_batches.build_and_register(
+          tool_calls:,
+          tools:,
+          context: Tool::ScopedContext.capture,
+          admission_resolver: method(:smith_tool_call_admissions)
+        )
+      end
+
+      def admit_execution_batch(batch)
+        requests = batch.requests.values.freeze
+        admitter = batch.context.fetch(:current_invocation_batch_admitter)
+        return unless admitter && requests.any?
+
+        Thread.handle_interrupt(Exception => :never) do
+          admitter.call(requests:)
+          batch.mark_host_admitted!
+        end
+      end
+
+      def execution_batch(tool_call) = smith_tool_execution_batches.fetch(tool_call)
+
+      def settle_execution_batch(batch, active_error:)
+        return unless batch
+
+        settlement_error = nil
+        Thread.handle_interrupt(Exception => :never) do
+          begin
+            batch.settle!
+          rescue Exception => e # rubocop:disable Lint/RescueException
+            settlement_error = e
+          end
+        ensure
+          smith_tool_execution_batches.unregister(batch)
+        end
+        return unless settlement_error
+        raise settlement_error unless active_error
+
+        log_preserved_settlement_failure(active_error, settlement_error)
+      end
+
+      def log_preserved_settlement_failure(active_error, settlement_error)
+        Smith.config.logger&.error(
+          "Smith tool batch settlement failed while preserving " \
+          "#{active_error.class}: #{settlement_error.class}: #{settlement_error.message}"
+        )
+      rescue Exception # rubocop:disable Lint/RescueException
+        nil
+      end
+    end
+  end
+end

data/lib/smith/tool/execution_batch_registry.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Smith
+  class Tool < RubyLLM::Tool
+    class ExecutionBatchRegistry
+      PENDING_BATCH = Object.new.freeze
+      private_constant :PENDING_BATCH
+
+      def initialize
+        @batches = {}.compare_by_identity
+        @builder = ExecutionBatchBuilder.new
+        @mutex = Mutex.new
+      end
+
+      def build_and_register(tool_calls:, tools:, context:, admission_resolver:)
+        captured_calls = ExecutionBatchCollection.capture(tool_calls)
+        entries = captured_calls.each_pair.map { |key, tool_call| [key, tool_call].freeze }.freeze
+        source_calls = entries.map(&:last).freeze
+        reserve_calls!(source_calls)
+        call_admissions = admission_resolver.call(source_calls)
+        batch = @builder.call(entries:, tools:, context:, call_admissions:)
+        publish_batch!(source_calls, batch)
+        batch
+      rescue Exception # rubocop:disable Lint/RescueException
+        rollback_registration(source_calls, batch)
+        raise
+      end
+
+      def unregister(batch)
+        return unless batch
+
+        @mutex.synchronize do
+          unregister_calls(batch.source_calls, batch)
+          unregister_calls(batch.tool_calls.each_value, batch)
+        end
+      end
+
+      def fetch(tool_call)
+        @mutex.synchronize do
+          batch = @batches[tool_call]
+          raise Error, "tool call batch registration is incomplete" if batch.equal?(PENDING_BATCH)
+
+          batch
+        end
+      end
+
+      private
+
+      def reserve_calls!(calls)
+        @mutex.synchronize do
+          validate_inactive_calls!(calls)
+          calls.each { @batches[_1] = PENDING_BATCH }
+        end
+      end
+
+      def publish_batch!(calls, batch)
+        @mutex.synchronize do
+          unless calls.all? { @batches[_1].equal?(PENDING_BATCH) }
+            raise Error, "tool call batch registration changed before publication"
+          end
+
+          calls.each { @batches[_1] = batch }
+          batch.tool_calls.each_value { @batches[_1] = batch }
+        end
+      end
+
+      def unregister_calls(calls, batch)
+        calls.each { @batches.delete(_1) if @batches[_1].equal?(batch) }
+      end
+
+      def release_calls!(calls)
+        return unless calls
+
+        @mutex.synchronize do
+          calls.each { @batches.delete(_1) if @batches[_1].equal?(PENDING_BATCH) }
+        end
+      end
+
+      def rollback_registration(source_calls, batch)
+        Thread.handle_interrupt(Exception => :never) do
+          batch&.settle!
+        ensure
+          unregister(batch)
+          release_calls!(source_calls)
+        end
+      end
+
+      def validate_inactive_calls!(calls)
+        seen = {}.compare_by_identity
+        calls.each do |tool_call|
+          raise Error, "tool call appears more than once in one provider batch" if seen.key?(tool_call)
+          raise Error, "tool call is already active on this chat" if @batches.key?(tool_call)
+
+          seen[tool_call] = true
+        end
+      end
+    end
+  end
+end

data/lib/smith/tool/execution_batch_requests.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+module Smith
+  class Tool < RubyLLM::Tool
+    class ExecutionBatchRequests
+      MAX_NODES = ArgumentSnapshot::MAX_NODES
+      MAX_BYTES = ArgumentSnapshot::MAX_BYTES
+      MAX_CALLS = ExecutionBatchCollection::MAX_CALLS
+
+      extend Dry::Initializer
+
+      option :targets
+      option :invocations
+      option :arguments
+
+      def call
+        raise Error, "tool batch exceeds #{MAX_CALLS} Smith tool calls" if targets.length > MAX_CALLS
+
+        totals = [0, 0]
+        targets.each_with_object({}.compare_by_identity) do |(tool_call, tool), requests|
+          append_request!(requests, tool_call, tool, totals)
+        end
+          .freeze
+      end
+
+      private
+
+      def validate_bounds!(node_count, byte_count)
+        raise Error, "tool batch arguments exceed #{MAX_NODES} values" if node_count > MAX_NODES
+        raise Error, "tool batch arguments exceed #{MAX_BYTES} bytes" if byte_count > MAX_BYTES
+      end
+
+      def append_request!(requests, tool_call, tool, totals)
+        request = build_request(tool_call, tool)
+        totals[0] += request.argument_node_count
+        totals[1] += request.argument_byte_count
+        validate_bounds!(*totals)
+        requests[tool_call] = request
+      end
+
+      def build_request(tool_call, tool)
+        InvocationRequest.new(
+          invocation: invocations.fetch(tool_call),
+          tool_class: tool.class,
+          arguments: normalized_arguments(arguments.fetch(tool_call))
+        )
+      end
+
+      def normalized_arguments(value)
+        return {} if value.nil?
+        return value if value.is_a?(Hash)
+
+        raise Error, "tool call arguments must be an object"
+      end
+    end
+  end
+end

data/lib/smith/tool/execution_batch_source_call.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "dry-struct"
+
+require_relative "../types"
+require_relative "execution_batch_source_metadata"
+
+module Smith
+  class Tool < RubyLLM::Tool
+    class ExecutionBatchSourceCall < Dry::Struct
+      MAX_NAME_BYTES = ExecutionBatchSourceMetadata::MAX_NAME_BYTES
+      MAX_METADATA_BYTES = ExecutionBatchSourceMetadata::MAX_METADATA_BYTES
+
+      Name = Types.Instance(String) | Types.Instance(Symbol)
+      private_constant :Name
+
+      attribute :key, Types::Any
+      attribute :tool_call, Types::Any
+      attribute :tool_call_id, Types::String.optional
+      attribute :name, Name
+      attribute :canonical_name, Types::String.constrained(min_size: 1)
+      attribute :arguments, Types::Any
+      attribute :thought_signature, Types::String.optional
+      attribute :metadata_byte_count, Types::Integer.constrained(gteq: 1)
+
+      def self.capture(key:, tool_call:)
+        ExecutionBatchSourceMetadata.capture(key:, tool_call:).to_source_call
+      end
+
+      def initialize(...)
+        super
+        freeze
+      end
+    end
+  end
+end

data/lib/smith/tool/execution_batch_source_metadata.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "dry-struct"
+
+require_relative "../types"
+
+module Smith
+  class Tool < RubyLLM::Tool
+    class ExecutionBatchSourceMetadata < Dry::Struct
+      MAX_NAME_BYTES = 256
+      MAX_METADATA_BYTES = ArgumentSnapshot::MAX_BYTES
+
+      MODULE_MATCH = Module.instance_method(:===)
+      STRING_BYTESIZE = String.instance_method(:bytesize)
+      STRING_VALID_ENCODING = String.instance_method(:valid_encoding?)
+      SYMBOL_TO_S = Symbol.instance_method(:to_s)
+      private_constant :MODULE_MATCH, :STRING_BYTESIZE, :STRING_VALID_ENCODING, :SYMBOL_TO_S
+
+      Name = Types.Instance(String) | Types.Instance(Symbol)
+      private_constant :Name
+
+      attribute :key, Types::Any
+      attribute :tool_call, Types::Any
+      attribute :tool_call_id, Types::String.optional
+      attribute :name, Name
+      attribute :canonical_name, Types::String.constrained(min_size: 1)
+      attribute :thought_signature, Types::String.optional
+      attribute :metadata_byte_count, Types::Integer.constrained(gteq: 1)
+
+      def self.capture(key:, tool_call:)
+        name, canonical_name = owned_name(tool_call.name)
+        tool_call_id = owned_id(tool_call)
+        thought_signature = owned_thought_signature(tool_call)
+        new(
+          key:,
+          tool_call:,
+          tool_call_id:,
+          name:,
+          canonical_name:,
+          thought_signature:,
+          metadata_byte_count: string_bytes(canonical_name) + string_bytes(tool_call_id) +
+                               string_bytes(thought_signature)
+        )
+      end
+
+      def initialize(...)
+        super
+        freeze
+      end
+
+      def to_source_call
+        ExecutionBatchSourceCall.new(
+          **to_h,
+          arguments: tool_call.arguments
+        )
+      end
+
+      def self.owned_id(tool_call)
+        return unless tool_call.respond_to?(:id)
+
+        value = tool_call.id
+        value && owned_string(value, "tool call id")
+      end
+      private_class_method :owned_id
+
+      def self.owned_thought_signature(tool_call)
+        return unless tool_call.respond_to?(:thought_signature)
+
+        value = tool_call.thought_signature
+        value && owned_string(value, "tool call thought signature")
+      end
+      private_class_method :owned_thought_signature
+
+      def self.owned_name(value)
+        raise Error, "tool call name must be a string or symbol" unless string?(value) || symbol?(value)
+
+        source = symbol?(value) ? SYMBOL_TO_S.bind_call(value) : value
+        canonical = owned_string(source, "tool call name", max_bytes: MAX_NAME_BYTES)
+        raise Error, "tool call name must be a bounded non-empty value" if canonical.empty?
+
+        [symbol?(value) ? canonical.to_sym : canonical, canonical]
+      end
+      private_class_method :owned_name
+
+      def self.owned_string(value, label, max_bytes: MAX_METADATA_BYTES)
+        raise Error, "#{label} must be a string" unless string?(value)
+        raise Error, "#{label} must contain valid encoded text" unless STRING_VALID_ENCODING.bind_call(value)
+        raise Error, "#{label} exceeds #{max_bytes} bytes" if STRING_BYTESIZE.bind_call(value) > max_bytes
+
+        normalized = String.new(value).encode(Encoding::UTF_8)
+        raise Error, "#{label} exceeds #{max_bytes} bytes" if STRING_BYTESIZE.bind_call(normalized) > max_bytes
+
+        normalized.freeze
+      rescue EncodingError
+        raise Error, "#{label} must contain valid UTF-8 text"
+      end
+
+      def self.string_bytes(value) = value ? STRING_BYTESIZE.bind_call(value) : 0
+
+      def self.string?(value) = MODULE_MATCH.bind_call(String, value)
+
+      def self.symbol?(value) = MODULE_MATCH.bind_call(Symbol, value)
+
+      private_class_method :owned_string, :string_bytes, :string?, :symbol?
+    end
+  end
+end