smith-agents 0.12.1 → 0.12.3

data/lib/smith/interruptions.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Smith
+  # The errors a host names in Smith.config.interrupting_errors: the host
+  # could not do its part (its database or queue out of reach), so the step
+  # did not go wrong, it was cut short. A step that meets one stops where it
+  # is, as if its worker had stopped. Smith takes no failure route, makes no
+  # retry, records no failure and notifies no tool failure handler; the
+  # error reaches the caller of advance!, run!, resume! or expire_wait! as it
+  # was raised, even when Smith or the host wrapped it in another error on
+  # the way (its `cause`). Smith does not count interruptions: a step that
+  # meets one every time is the host's to bound. A persisted run's state is as the step left it: a
+  # lax run takes the step again when it is next advanced, a strict run
+  # finds it under way.
+  module Interruptions
+    CAUSE_DEPTH = 16
+
+    module_function
+
+    # The interrupting error that `error` is, or was raised from, or nil:
+    # the error, or one of its first CAUSE_DEPTH - 1 causes (so a chain of
+    # causes that loops ends too). A provider's own failure (RubyLLM's, or
+    # its HTTP client's) is the provider's, whatever it was raised from: it
+    # interrupts only when its own class is named.
+    def find(error)
+      classes = Smith.config.interrupting_errors
+      return nil if classes.empty?
+
+      current = error
+      CAUSE_DEPTH.times do
+        return nil if current.nil?
+        return current if classes.any? { current.is_a?(_1) }
+        return nil if provider_failure?(current)
+
+        current = current.cause
+      end
+      nil
+    end
+
+    def provider_failure?(error)
+      error.is_a?(RubyLLM::Error) || (defined?(Faraday::Error) && error.is_a?(Faraday::Error))
+    end
+
+    # Raises the interrupting error `error` is or was raised from, if any.
+    def pass!(error)
+      interruption = find(error)
+      raise interruption, cause: interruption.cause if interruption
+    end
+  end
+end

data/lib/smith/launchers/inline.rb

@@ -26,6 +26,7 @@ module Smith
 
         ChildRun.result(ref: child.ref, run_result: run)
       rescue StandardError => e
+        Interruptions.pass!(e)
         failed(child, nil, DiagnosticText.error_class_name(e))
       end
 

data/lib/smith/providers/request_holds.rb

@@ -57,7 +57,7 @@ module Smith
         exchange = BatchExchange.exchange_for(provider)
         return capture(provider, exchange, args, kwargs, block, &request) if exchange
 
-        ResponseMemo.round(provider, args.first) { send_held(provider, args, kwargs, block, &request) }
+        ResponseMemo.round(provider, args.first, kwargs) { send_held(provider, args, kwargs, block, &request) }
       end
 
       def send_held(provider, args, kwargs, block, &request)

data/lib/smith/providers/stream_facts.rb

@@ -32,13 +32,15 @@ module Smith
       MARK = :@smith_stream_facts_observer
       private_constant :HELD, :MARK
 
-      # The streams of one call: its provider (nil reads any) and the facts
-      # of each of its requests.
+      # The streams of one call: its provider (nil reads any), the facts of
+      # each of its requests, and how many of its replies came kept, before
+      # them, from a response memo (no request of its own answered those).
       class Collection
-        attr_reader :rounds
+        attr_reader :rounds, :kept
 
-        def initialize(provider)
+        def initialize(provider, kept = 0)
           @provider = provider
+          @kept = kept
           @rounds = []
         end
 
@@ -64,20 +66,36 @@ module Smith
 
       # Runs the block, given the collection, collecting the facts of the
       # streams `provider` reads; returns them, one bounded Hash per round.
-      def collect(provider)
+      def collect(provider, kept: 0)
         outer = Fiber[HELD]
-        collection = Fiber[HELD] = Collection.new(provider)
+        collection = Fiber[HELD] = Collection.new(provider, kept)
         yield collection
         collection.facts
       ensure
         Fiber[HELD] = outer
       end
 
-      # The facts of each response of a streamed call, in order: each
-      # round's over its raw body's, the last settled. Rounds and responses
-      # pair up in order; a round past the last response (a request that
-      # failed) has none.
-      def per_message(messages, rounds, output_limit)
+      # The facts of the request `provider` last streamed in the collecting
+      # call, bounded; empty when it streamed none.
+      def last_round(provider)
+        collection = Fiber[HELD]
+        return {} unless collection&.owns?(provider) && !collection.rounds.empty?
+
+        collection.facts.last
+      end
+
+      # The facts of each response of a streamed call, in order: the first
+      # `kept` (a response memo's) their own; each live one its round's over
+      # its raw body's, the last settled. Rounds and live responses pair up
+      # in order; a round past the last response (a request that failed) has
+      # none.
+      def per_message(messages, rounds, output_limit, kept: 0)
+        live = messages.drop(kept)
+        own = messages.first(kept).map { ResponseFacts.from_message(_1) }
+        live.empty? ? own : [*own, *live_facts(live, rounds, output_limit)]
+      end
+
+      def live_facts(messages, rounds, output_limit)
         missing = messages.length - rounds.length
         aligned = missing.positive? ? [*Array.new(missing, {}), *rounds] : rounds.first(messages.length)
         facts = messages.zip(aligned).map { |message, round| ResponseFacts.from_message(message).merge(round) }

data/lib/smith/response_memo.rb

@@ -14,29 +14,127 @@ module Smith
   # position, the key generation), the attempts it runs under (the step's,
   # and each enclosing run's for a nested workflow), its attempt index (its
   # model in the fallback chain, or a follow-up's place), its place among
-  # the attempt's calls, and a digest of its request (model, messages,
-  # tools, schema, params). A replay reaches the same key; a call whose
-  # request changed since (a deployed prompt, another model, a date in the
-  # prompt) misses and is sent, as a miss always may be.
+  # the attempt's calls, and a digest of its request (model, messages, tools
+  # with their descriptions and parameters, schema, params). A replay
+  # reaches the same key; a call whose request changed since (a deployed
+  # prompt or tool, another model, a date in the prompt) misses and is
+  # sent, as a miss always may be.
   #
-  # Its record, `{"version" => 1, "messages" => [...], "complete" => bool}`,
-  # holds the messages the call added (Budget::Continuation, with each
-  # response's usage and facts), stored after each round's tool results and
-  # when the call ends; a complete one ends with the model's reply. Replayed,
-  # a complete call sends nothing; an unfinished one continues from its
-  # tools' results. Either way the step counts its tools as run (a retry or
-  # fallback never runs them again). A call whose messages cannot be kept
-  # (an attachment, or too many bytes) is not stored, and is logged. A record
-  # Smith does not keep is ignored, and an error from `fetch` or `store` is
-  # logged by class: a memo never fails a step. Keeping records and dropping
-  # them is the host's.
+  # Its record, `{"version" => 1 | 2, "messages" => [...], "complete" =>
+  # bool}`, holds the messages the call added (Budget::Continuation, with
+  # each response's usage and facts). It is stored when a reply calling the
+  # tools its request offered comes (before they run; version 2, the only
+  # shape a Smith before 0.12.2 cannot read), before each later request (the
+  # tools' results included), and when the call ends in the model's reply (a
+  # call a tool halted keeps only its progress). Replayed, a complete call
+  # sends nothing; an unfinished one goes on from where it was kept: a reply
+  # whose tools had not run answers the call's first request without
+  # sending it, and its tools run again, under the same keys; kept tool
+  # results count as tools the step ran (charged to its tool-call
+  # allowances, and never run again by a retry or fallback). A call whose
+  # messages cannot be kept (an attachment, or too many bytes) is not
+  # stored, and is logged. A record Smith does not keep (its shape, or tool
+  # results that do not answer its replies' calls) is ignored, and an error
+  # from `fetch` or `store` is logged by class: a memo never fails a step.
+  # Keeping records and dropping them is the host's.
   module ResponseMemo
-    VERSION = 1
+    VERSION = 2
     PROGRESS = :smith_response_memo
     INHERITED = :smith_inherited_memo_attempts
     private_constant :PROGRESS, :INHERITED
 
-    Recorder = Struct.new(:provider, :memo, :key, :start, :rounds, :busy)
+    # A provider call being recorded (`recording`): its messages from
+    # `start` are stored as its progress when a reply calling the tools its
+    # request offered comes (with the facts its stream gave), and before
+    # each later round (the round before's tool results included). A kept
+    # reply whose tools had not run (`pending`) answers its first request,
+    # and nothing is sent.
+    class Recorder
+      def initialize(provider, memo, key, start, pending)
+        @provider = provider
+        @memo = memo
+        @key = key
+        @start = start
+        @pending = pending
+        @rounds = 0
+        @busy = false
+        @facts = {}.compare_by_identity
+      end
+
+      # Whether a request `provider` is about to make is one of the call's
+      # rounds (not one made inside another, as OpenAI's hook inside the
+      # base class's).
+      def records?(provider) = provider.equal?(@provider) && !@busy
+
+      def round(messages, offered, &)
+        @rounds += 1
+        return @pending.tap { @pending = nil } if @pending
+
+        progress(messages.drop(@start)) if @rounds > 1
+        reply = busy(&)
+        return reply unless offered && ResponseMemo.calls_tools?(reply)
+
+        @facts[reply] = Providers::StreamFacts.last_round(@provider)
+        progress([*messages.drop(@start), reply])
+        reply
+      end
+
+      private
+
+      def progress(messages) = ResponseMemo.store(@memo, @key, messages, complete: false, facts: @facts)
+
+      def busy
+        @busy = true
+        yield
+      ensure
+        @busy = false
+      end
+    end
+
+    # The shape of a record Smith keeps, as JSON.
+    module Record
+      READ = [1, VERSION].freeze
+      private_constant :READ
+
+      module_function
+
+      def valid?(record)
+        record.is_a?(Hash) && record.keys.sort == %w[complete messages version] && READ.include?(record["version"]) &&
+          [true, false].include?(record["complete"]) && Budget::Continuation.valid?(record["messages"]) &&
+          paired?(record["messages"], record["complete"])
+      end
+
+      # Each tool result answers a call of the reply before it, and a reply
+      # comes only once the one before has all its results. A complete
+      # record ends with a reply calling nothing; an unfinished one with all
+      # of the last reply's results, or with that reply (its tools not run).
+      def paired?(messages, complete)
+        open = []
+        messages.each do |message|
+          if message["role"] == "tool"
+            return false unless open.delete(message["tool_call_id"])
+          else
+            return false unless open.empty?
+
+            open = Array(message["tool_calls"]).map { _1["id"] }
+          end
+        end
+        ends?(messages.last, open, complete)
+      end
+
+      def ends?(last, open, complete)
+        return reply?(last) if complete
+
+        last["role"] == "tool" ? open.empty? : last["role"] == "assistant" && !open.empty?
+      end
+
+      def reply?(entry) = entry["role"] == "assistant" && entry["tool_calls"].nil?
+
+      def version(entries, complete)
+        last = entries.last
+        !complete && last["tool_calls"] ? VERSION : 1
+      end
+    end
 
     module_function
 
@@ -51,7 +149,7 @@ module Smith
 
     def request_digest(chat)
       shape = [chat.model.id, chat.model.provider.to_s, chat.messages.map { message_shape(_1) },
-               chat.tools.keys.map(&:to_s).sort, chat.schema, chat.params]
+               tools_shape(chat.tools), chat.schema, CacheMarkers.strip_request(chat.params)]
       Digest::SHA256.hexdigest(JSON.generate(shape))
     rescue StandardError
       nil
@@ -60,7 +158,7 @@ module Smith
     def message_shape(message)
       content = message.content
       body = case content
-             when RubyLLM::Content::Raw then content.value
+             when RubyLLM::Content::Raw then CacheMarkers.strip_blocks(content.value)
              when RubyLLM::Content
                [content.text, content.attachments.map { [_1.filename, _1.mime_type, _1.content.to_s.bytesize] }]
              else content
@@ -68,33 +166,44 @@ module Smith
       [message.role.to_s, body, message.tool_calls&.keys, message.tool_call_id]
     end
 
-    # The call's kept messages and whether it ended, or nil.
+    def tools_shape(tools)
+      tools.map { |name, tool| [name.to_s, tool.description, tool.params_schema] }.sort_by(&:first)
+    end
+
+    # The call's kept messages, whether it ended, and its reply whose tools
+    # had not run (`pending`, taken off the messages), or nil.
     def fetch(memo, key)
       record = memo.fetch(key)
       return unless record
 
       record = JSON.parse(JSON.generate(record))
-      raise ArgumentError, "not a response memo record" unless record?(record)
+      raise ArgumentError, "not a response memo record" unless Record.valid?(record)
 
-      { messages: Budget::Continuation.load(record["messages"]), complete: record["complete"] }
+      kept(Budget::Continuation.load(record["messages"]), record["complete"])
     rescue StandardError => e
       Smith.config.logger&.error("Smith response memo fetch error: #{e.class}")
       nil
     end
 
-    def record?(record)
-      record.is_a?(Hash) && record.keys.sort == %w[complete messages version] && record["version"] == VERSION &&
-        [true, false].include?(record["complete"]) && Budget::Continuation.valid?(record["messages"]) &&
-        (!record["complete"] || reply?(record["messages"].last))
+    def kept(messages, complete)
+      pending = messages.pop if !complete && calls_tools?(messages.last)
+      { messages:, complete:, pending: }
     end
 
-    def reply?(message) = message["role"] == "assistant" && message["tool_calls"].nil?
+    def calls_tools?(message) = message.is_a?(RubyLLM::Message) && message.role == :assistant && message.tool_call?
+
+    # Whether the message is the model's reply calling nothing, as a call
+    # ends.
+    def answer?(message) = message.is_a?(RubyLLM::Message) && message.role == :assistant && !message.tool_call?
 
     # Stores the call's messages (`facts`: a streamed reply's, by message),
     # unless they cannot be kept.
     def store(memo, key, messages, complete:, facts: {})
       dumped = Budget::Continuation.dump(nil, messages, usage: true, facts:)
-      return memo.store(key, { "version" => VERSION, "messages" => dumped, "complete" => complete }) if dumped
+      if dumped
+        return memo.store(key, { "version" => Record.version(dumped, complete), "messages" => dumped,
+                                 "complete" => complete })
+      end
 
       Smith.config.logger&.info("Smith response memo: a call not kept (an attachment, or past its byte limit)")
       nil
@@ -103,33 +212,29 @@ module Smith
       nil
     end
 
-    # Runs the block with the provider's call recorded: before each of its
-    # later rounds, its messages from `start` (the round before's tool
-    # results included) are stored as its progress.
-    def recording(provider, memo, key, start)
+    # Runs the block with the provider's call recorded (Recorder) from
+    # `start`, its first request answered by `pending` if given.
+    def recording(provider, memo, key, start, pending = nil)
       outer = Fiber[PROGRESS]
-      Fiber[PROGRESS] = Recorder.new(provider, memo, key, start, 0, false)
+      Fiber[PROGRESS] = Recorder.new(provider, memo, key, start, pending)
       yield
     ensure
       Fiber[PROGRESS] = outer
     end
 
     # A request the provider is about to make, from RubyLLM's
-    # `Provider#complete` (`messages`, its chat's).
-    def round(provider, messages, &)
+    # `Provider#complete` (`messages`, its chat's, and the request's
+    # `options`), and its reply.
+    def round(provider, messages, options = {}, &)
       recorder = Fiber[PROGRESS]
-      return yield unless recorder&.provider.equal?(provider) && !recorder.busy
-
-      recorder.rounds += 1
-      store(recorder.memo, recorder.key, messages.drop(recorder.start), complete: false) if recorder.rounds > 1
-      busy(recorder, &)
+      recorder&.records?(provider) ? recorder.round(messages, tools_offered?(options), &) : yield
     end
 
-    def busy(recorder)
-      recorder.busy = true
-      yield
-    ensure
-      recorder.busy = false
+    # Whether the request offered the model tools (a finalization that took
+    # them away did not, and its reply's calls never run).
+    def tools_offered?(options)
+      tools = options[:tools]
+      tools.respond_to?(:empty?) && !tools.empty?
     end
 
     # A nested workflow built in the block runs its calls under `attempts`

data/lib/smith/setting_constructors.rb

@@ -34,6 +34,20 @@ module Smith
       end
     end
 
+    # A list of StandardError subclasses, frozen; nil is none. StandardError
+    # itself would match every error, and an error outside it never reaches
+    # a step's rescue.
+    def error_classes(name)
+      lambda do |value|
+        classes = Array(value)
+        unless classes.all? { _1.is_a?(Class) && _1 < StandardError }
+          raise ArgumentError, "Smith.config.#{name} must list subclasses of StandardError, got #{value.inspect}"
+        end
+
+        classes.uniq.freeze
+      end
+    end
+
     # A host adapter: nil, or an object that answers `calls` (each named
     # with its arguments, as the message says).
     def adapter(name, calls)

data/lib/smith/tool/chat_execution_callbacks.rb

@@ -39,7 +39,7 @@ module Smith
       def handle_managed_callback_failure(batch, dispatch_call, claim, error)
         record_batch_failure(batch, error)
         raise error unless claim
-        raise error if error.is_a?(ToolFailureNotificationFailed)
+        raise error if error.is_a?(ToolFailureNotificationFailed) || Interruptions.find(error)
 
         failure = invocation_dispatch_failure(batch, dispatch_call, error)
         notify_invocation_failure(batch, dispatch_call, failure)

data/lib/smith/tool/execution_batch.rb

@@ -75,6 +75,11 @@ module Smith
 
       def settle! = call_reservation&.settle!
 
+      # One of its calls met an interruption (Smith::Interruptions).
+      def interrupted! = @interrupted = true
+
+      def interrupted? = @interrupted == true
+
       private
 
       def initialize_failure_queues

data/lib/smith/tool/execution_failure_handling.rb

@@ -16,14 +16,19 @@ module Smith
         batch.complete_failure_notification!(tool_call)
       rescue StandardError => e
         batch.release_failure_notification!(tool_call, state)
+        pass_interruption!(batch, e)
         raise ToolFailureNotificationFailed.new(
           dispatch_error: error,
           notification_error: e
         ), cause: e
       end
 
+      # An interruption settles nothing, as a process that died settles
+      # nothing: the host reconciles the batch's unsettled requests, whichever
+      # of its calls' errors reached here first.
       def notify_unsettled_batch_failures(batch, error)
         return unless batch&.host_admitted?
+        return if Interruptions.find(error) || batch.interrupted?
 
         handler = batch.context.fetch(:current_invocation_failure_handler)
         handler_error = notify_unsettled_requests(batch, error, handler)
@@ -40,6 +45,7 @@ module Smith
             batch.complete_failure_notification!(tool_call)
           rescue StandardError => e
             batch.release_failure_notification!(tool_call, state)
+            pass_interruption!(batch, e)
             first_error ||= ToolFailureNotificationFailed.new(
               dispatch_error: failure,
               notification_error: e
@@ -49,6 +55,15 @@ module Smith
         first_error
       end
 
+      # A failure handler that met an interruption stops the batch with it, as
+      # it was raised; what it had not settled stays unsettled for the host.
+      def pass_interruption!(batch, error)
+        return unless Interruptions.find(error)
+
+        record_batch_failure(batch, error)
+        Interruptions.pass!(error)
+      end
+
       def batch_dispatch_failure(error, state)
         return error.dispatch_error if error.is_a?(ToolFailureNotificationFailed)
         return error if state == :started || exact_dispatch_failure?(error)
@@ -68,15 +83,18 @@ module Smith
       end
 
       def record_batch_failure(batch, error)
-        if !error.is_a?(StandardError)
-          batch.fatal_failures.push(error)
-        elsif error.is_a?(ToolFailureNotificationFailed)
-          batch.notification_failures.push(error)
-        elsif error.is_a?(ToolCaptureFailed)
-          batch.capture_failures.push(error)
-        elsif Smith::Errors.retry_forbidden?(error)
-          batch.terminal_failures.push(error)
-        end
+        interrupted = Interruptions.find(error)
+        batch.interrupted! if interrupted
+        batch_failure_queue(batch, error, interrupted)&.push(error)
+      end
+
+      # An interruption counts as process-fatal: nothing else is raised over it.
+      def batch_failure_queue(batch, error, interrupted)
+        return batch.fatal_failures if interrupted || !error.is_a?(StandardError)
+        return batch.notification_failures if error.is_a?(ToolFailureNotificationFailed)
+        return batch.capture_failures if error.is_a?(ToolCaptureFailed)
+
+        batch.terminal_failures if Smith::Errors.retry_forbidden?(error)
       end
 
       def prioritized_batch_failure(batch)

data/lib/smith/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Smith
-  VERSION = "0.12.1"
+  VERSION = "0.12.3"
   EXECUTION_SEMANTICS_VERSION = "7"
 end

data/lib/smith/workflow/deterministic_execution.rb

@@ -13,7 +13,11 @@ module Smith
         finish_deterministic_step!(transition, step)
         nil
       rescue StandardError => e
-        emit_deterministic_trace(transition, outcome: :failed, failure: deterministic_failure_fields(transition, e))
+        if Interruptions.find(e)
+          emit_deterministic_trace(transition, outcome: :interrupted)
+        else
+          emit_deterministic_trace(transition, outcome: :failed, failure: deterministic_failure_fields(transition, e))
+        end
         raise
       end
 

data/lib/smith/workflow/parallel.rb

@@ -39,6 +39,7 @@ module Smith
       def self.preferred_error(reasons)
         errors = Array(reasons).compact
         process_fatal_error(errors) ||
+          interruption(errors) ||
           notification_failure(errors) ||
           terminal_execution_error(errors) ||
           ordinary_error(errors) ||
@@ -47,13 +48,16 @@ module Smith
 
       def self.process_fatal_error(errors) = errors.find { !_1.is_a?(StandardError) }
 
+      def self.interruption(errors) = errors.find { Interruptions.find(_1) }
+
       def self.notification_failure(errors) = errors.find { _1.is_a?(ToolFailureNotificationFailed) }
 
       def self.terminal_execution_error(errors) = errors.find { Smith::Errors.retry_forbidden?(_1) }
 
       def self.ordinary_error(errors) = errors.find { !_1.is_a?(Cancellation) }
 
-      private_class_method :process_fatal_error, :notification_failure, :terminal_execution_error, :ordinary_error
+      private_class_method :process_fatal_error, :interruption, :notification_failure, :terminal_execution_error,
+                           :ordinary_error
     end
   end
 end

data/lib/smith/workflow/persistence.rb

@@ -228,13 +228,16 @@ module Smith
         validate_step_in_progress!(fields.to_h { |field| [field, state[field] || state[field.to_s]] })
       end
 
+      # A digest Smith before 0.12.3 took, its parts' cache flags included.
+      def flagged_seed_digest?(messages, stored) = compute_seed_digest(messages, cache_flags: true) == stored
+
       def validate_seed_digest!(normalized)
         stored_digest = normalized[:seed_digest]
         return if stored_digest.nil?
 
         current_messages = compute_seed_messages
         current_digest = compute_seed_digest(current_messages)
-        return if current_digest == stored_digest
+        return if current_digest == stored_digest || flagged_seed_digest?(current_messages, stored_digest)
 
         case self.class.seed_validation
         when :strict