smith-agents 0.10.0 → 0.12.0

data/lib/smith/providers/stream_facts.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+require "ruby_llm"
+
+require_relative "response_facts"
+
+module Smith
+  module Providers
+    # The stop reason and message id of each response of a streamed call. A
+    # streamed RubyLLM message keeps no raw body for ResponseFacts to read,
+    # so the facts are read from the provider's stream events as RubyLLM
+    # turns them into chunks, each event recognized by its own markers:
+    #
+    #   Anthropic        "message_start" message.id; "message_delta" delta.stop_reason
+    #   OpenAI and kin   "choices" => [...]: id, choices[0].finish_reason, delta.refusal
+    #   Gemini           candidates[0].finishReason, responseId; promptFeedback.blockReason
+    #   Bedrock          stopReason, or messageStop.stopReason
+    #
+    # Only the call's own provider object is read (a tool's own RubyLLM call
+    # streams through another), and each provider request (a round of a
+    # tool loop) keeps facts of its own. The collection lives in fiber
+    # storage, which fibers and threads started inside the call inherit.
+    # Reading never raises.
+    #
+    # A streamed reply without a stop reason did not end as the provider
+    # ends a reply: it counts as cut off, as LIMIT_REACHED when its output
+    # tokens reached the request's limit, else as INCOMPLETE.
+    module StreamFacts
+      HELD = :smith_stream_facts
+      LIMIT_REACHED = "output_limit_reached"
+      INCOMPLETE = "stream_incomplete"
+      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.
+      class Collection
+        attr_reader :rounds
+
+        def initialize(provider)
+          @provider = provider
+          @rounds = []
+        end
+
+        def owns?(provider) = @provider.nil? || provider.equal?(@provider)
+
+        def open_round = @rounds << {}
+
+        def current
+          open_round if @rounds.empty?
+          @rounds.last
+        end
+
+        # Each round's facts, bounded.
+        def facts
+          @rounds.map do |round|
+            { stop_reason: ResponseFacts.bounded(round[:stop_reason]),
+              provider_message_id: ResponseFacts.bounded(round[:provider_message_id]) }.compact
+          end
+        end
+      end
+
+      module_function
+
+      # Runs the block, given the collection, collecting the facts of the
+      # streams `provider` reads; returns them, one bounded Hash per round.
+      def collect(provider)
+        outer = Fiber[HELD]
+        collection = Fiber[HELD] = Collection.new(provider)
+        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)
+        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) }
+        facts[-1] = settle(messages.last, aligned.last, output_limit)
+        facts
+      end
+
+      # A streamed response's facts: its stream's, over its raw body's (a
+      # path that does not stream keeps one); without a stop reason,
+      # LIMIT_REACHED or INCOMPLETE.
+      def settle(message, collected, output_limit)
+        facts = ResponseFacts.from_message(message).merge(collected)
+        return facts if facts[:stop_reason]
+
+        tokens = message.output_tokens if message.respond_to?(:output_tokens)
+        reached = output_limit.is_a?(Integer) && tokens.is_a?(Integer) && tokens >= output_limit
+        facts.merge(stop_reason: reached ? LIMIT_REACHED : INCOMPLETE)
+      end
+
+      # A request of the collecting call begins (RoundObserver).
+      def round(provider)
+        collection = Fiber[HELD]
+        collection.open_round if collection&.owns?(provider)
+      end
+
+      def observe(provider, data)
+        collection = Fiber[HELD]
+        record(collection.current, data) if collection&.owns?(provider) && data.is_a?(Hash)
+      rescue StandardError
+        nil
+      end
+
+      def record(facts, data)
+        if data["type"].is_a?(String) then anthropic(facts, data)
+        elsif data["choices"].is_a?(Array) then openai(facts, data)
+        elsif data.key?("candidates") || data.key?("promptFeedback") then gemini(facts, data)
+        else bedrock(facts, data)
+        end
+      end
+
+      def anthropic(facts, data)
+        case data["type"]
+        when "message_start"
+          facts.delete(:stop_reason)
+          facts[:provider_message_id] = data.dig("message", "id")
+        when "message_delta" then facts[:stop_reason] = data.dig("delta", "stop_reason") || facts[:stop_reason]
+        end
+      end
+
+      # A refusal streams as `delta.refusal` text before the finish reason.
+      def openai(facts, data)
+        facts[:provider_message_id] = data["id"] if data["id"]
+        choice = ResponseFacts.first_entry(data["choices"])
+        return unless choice
+
+        facts[:refused] = true if ResponseFacts.chat_refusal?("message" => choice["delta"])
+        reason = choice["finish_reason"]
+        facts[:stop_reason] = facts[:refused] ? ResponseFacts::REFUSAL : reason if reason
+      end
+
+      def gemini(facts, data)
+        facts[:provider_message_id] = data["responseId"] if data["responseId"]
+        candidate = ResponseFacts.first_entry(data["candidates"])
+        blocked = ResponseFacts::PROMPT_BLOCKED if data.dig("promptFeedback", "blockReason").is_a?(String)
+        reason = candidate ? candidate["finishReason"] : blocked
+        facts[:stop_reason] = reason if reason
+      end
+
+      def bedrock(facts, data)
+        reason = data["stopReason"] || data.dig("messageStop", "stopReason")
+        facts[:stop_reason] = reason if reason
+      end
+
+      # Prepended once on each of RubyLLM's streaming modules, with the
+      # visibility that module gives `build_chunk`: every event a provider
+      # turns into a chunk is read first.
+      def install(streaming)
+        return if streaming.ancestors.any? { observer?(_1) }
+
+        observer = Module.new do
+          define_method(:build_chunk) do |data|
+            StreamFacts.observe(self, data)
+            super(data)
+          end
+        end
+        observer.instance_variable_set(MARK, streaming.name)
+        observer.send(:private, :build_chunk) if streaming.private_method_defined?(:build_chunk)
+        streaming.prepend(observer)
+      end
+
+      def observer?(mod) = mod.instance_variable_defined?(MARK)
+
+      # Prepended on RubyLLM::Provider: each streamed request opens a round.
+      module RoundObserver
+        def complete(*args, **kwargs, &block)
+          StreamFacts.round(self) if block
+          super
+        end
+      end
+    end
+  end
+end
+
+# Installed at gem-require; the subclasses of these providers (DeepSeek,
+# Mistral, xAI, Vertex AI and other OpenAI- or Gemini-compatible ones)
+# inherit it.
+[
+  RubyLLM::Providers::Anthropic::Streaming, RubyLLM::Providers::OpenAI::Streaming,
+  RubyLLM::Providers::Gemini::Streaming, RubyLLM::Providers::OpenRouter::Streaming,
+  RubyLLM::Providers::Bedrock::Streaming
+].each { |streaming| Smith::Providers::StreamFacts.install(streaming) }
+RubyLLM::Provider.prepend(Smith::Providers::StreamFacts::RoundObserver)

data/lib/smith/response_memo.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+module Smith
+  # A host's record of what a step's provider calls got
+  # (`Smith.config.response_memo`: `fetch(key)` and `store(key, record)`),
+  # so a step replayed after its process died reuses it instead of paying
+  # again.
+  #
+  # A call (one agent call, its tool loop included) is kept under a key of
+  # its position (IdempotencyKey: the run, the step, any branch or nested
+  # 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.
+  #
+  # 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.
+  module ResponseMemo
+    VERSION = 1
+    PROGRESS = :smith_response_memo
+    INHERITED = :smith_inherited_memo_attempts
+    private_constant :PROGRESS, :INHERITED
+
+    Recorder = Struct.new(:provider, :memo, :key, :start, :rounds, :busy)
+
+    module_function
+
+    # A step call's key, or nil outside a step or for a request it cannot
+    # digest.
+    def key(attempts, candidate, call, chat)
+      digest = request_digest(chat)
+      IdempotencyKey.current(["smith.response", attempts, candidate, call, digest]) if digest
+    rescue WorkflowError
+      nil
+    end
+
+    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]
+      Digest::SHA256.hexdigest(JSON.generate(shape))
+    rescue StandardError
+      nil
+    end
+
+    def message_shape(message)
+      content = message.content
+      body = case content
+             when RubyLLM::Content::Raw then content.value
+             when RubyLLM::Content
+               [content.text, content.attachments.map { [_1.filename, _1.mime_type, _1.content.to_s.bytesize] }]
+             else content
+             end
+      [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 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)
+
+      { messages: Budget::Continuation.load(record["messages"]), complete: 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))
+    end
+
+    def reply?(message) = message["role"] == "assistant" && message["tool_calls"].nil?
+
+    # 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
+
+      Smith.config.logger&.info("Smith response memo: a call not kept (an attachment, or past its byte limit)")
+      nil
+    rescue StandardError => e
+      Smith.config.logger&.error("Smith response memo store error: #{e.class}")
+      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)
+      outer = Fiber[PROGRESS]
+      Fiber[PROGRESS] = Recorder.new(provider, memo, key, start, 0, false)
+      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, &)
+      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, &)
+    end
+
+    def busy(recorder)
+      recorder.busy = true
+      yield
+    ensure
+      recorder.busy = false
+    end
+
+    # A nested workflow built in the block runs its calls under `attempts`
+    # too (the enclosing runs' attempts), so a retry of its parent's step is
+    # never answered from the attempt before.
+    def inheriting(attempts)
+      outer = Thread.current[INHERITED]
+      Thread.current[INHERITED] = attempts
+      yield
+    ensure
+      Thread.current[INHERITED] = outer
+    end
+
+    def take_inherited
+      attempts = Thread.current[INHERITED]
+      Thread.current[INHERITED] = nil
+      attempts || []
+    end
+  end
+end

data/lib/smith/setting_constructors.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Smith
+  # Constructors that check Smith.config's settings as they are set.
+  module SettingConstructors
+    module_function
+
+    def positive_integer(name)
+      lambda do |value|
+        unless value.is_a?(Integer) && value.positive?
+          raise ArgumentError, "Smith.config.#{name} must be a positive integer, got #{value.inspect}"
+        end
+
+        value
+      end
+    end
+
+    def optional_positive_integer(name)
+      lambda do |value|
+        next value if value.nil? || (value.is_a?(Integer) && value.positive?)
+
+        raise ArgumentError, "Smith.config.#{name} must be nil or a positive Integer, got #{value.inspect}"
+      end
+    end
+
+    def bounded_positive_integer(name, maximum)
+      lambda do |value|
+        unless value.is_a?(Integer) && value.positive? && value <= maximum
+          message = "Smith.config.#{name} must be a positive integer no greater than #{maximum}"
+          raise ArgumentError, "#{message}, got #{value.inspect}"
+        end
+
+        value
+      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)
+      lambda do |value|
+        next value if value.nil? || calls.keys.all? { value.respond_to?(_1) }
+
+        raise ArgumentError, "Smith.config.#{name} must respond to #{calls.values.join(" and ")}"
+      end
+    end
+  end
+end

data/lib/smith/streaming/json_field.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require_relative "json_string"
+
+module Smith
+  module Streaming
+    # The growing value of one top-level string field of a JSON object
+    # that arrives as text in pieces (a step with an output schema streams
+    # its JSON):
+    #
+    #   field = Smith::Streaming::JsonField.new(:reply)
+    #   def delta(text) = (piece = field.push(text)) && screen.append(piece)
+    #   def reset(_reason) = field.reset || screen.clear
+    #
+    # `push` returns the text the piece added to the field, unescaped, or
+    # nil when it added none; `value` is the field's text so far. Text before
+    # the object (a code fence) is skipped. The field is read from the first
+    # top-level object only (keys unescaped as JSON reads them), from the
+    # first member of that name whose value is a string: a later duplicate,
+    # which `JSON.parse` would take, comes after the text already streamed.
+    # Work and memory are linear in the text pushed.
+    class JsonField
+      WHITESPACE = " \t\n\r"
+      private_constant :WHITESPACE
+
+      def initialize(name)
+        unless (name.is_a?(Symbol) || name.is_a?(String)) && !name.to_s.empty?
+          raise ArgumentError, "a JsonField is named by a Symbol or String"
+        end
+
+        @name = name.to_s.freeze
+        reset
+      end
+
+      def push(text)
+        before = @string.text.bytesize
+        text.to_s.each_char { |char| step(char) }
+        @string.text.byteslice(before..).freeze if @string.text.bytesize > before
+      end
+
+      def value = @string.text.dup.freeze
+
+      # Starts over, for text that replaces what was pushed.
+      def reset
+        @state = :outside
+        @depth = 0
+        @in_string = @escape = @expect_key = @armed = false
+        @key = @last_key = nil
+        @string = JsonString.new
+        nil
+      end
+
+      private
+
+      def step(char)
+        case @state
+        when :outside then enter_object if char == "{"
+        when :scan then @in_string ? scan_string(char) : scan(char)
+        when :capture then capture(char)
+        end
+      end
+
+      def enter_object
+        @state = :scan
+        @depth = 1
+        @expect_key = true
+      end
+
+      def scan(char)
+        return if WHITESPACE.include?(char)
+        return value_start(char) if @armed
+
+        case char
+        when '"' then open_string
+        when "{", "[" then @depth += 1
+        when "}", "]" then close_container
+        else separator(char) if @depth == 1
+        end
+      end
+
+      # The first character of the value after the field's key.
+      def value_start(char)
+        @armed = false
+        return @state = :capture if char == '"'
+
+        scan(char)
+      end
+
+      def open_string
+        @in_string = true
+        @key = JsonString.new(limit: @name.length) if @expect_key
+      end
+
+      def close_container
+        @depth -= 1
+        @state = :done if @depth.zero?
+      end
+
+      # A member's `:` after its key, or the `,` before the next member.
+      def separator(char)
+        if char == ":"
+          @expect_key = false
+          @armed = @last_key == @name
+        elsif char == ","
+          @expect_key = true
+        end
+      end
+
+      # Inside a string that is not the field's value: a key is read as JSON
+      # reads it, up to the length of the field's name; any other string is
+      # skipped to its closing quote.
+      def scan_string(char)
+        return key_string(char) if @key
+
+        if @escape then @escape = false
+        elsif char == "\\" then @escape = true
+        elsif char == '"' then @in_string = false
+        end
+      end
+
+      def key_string(char)
+        @key.add(char)
+        return unless @key.closed?
+
+        @in_string = false
+        @last_key = @key.overflowed? ? nil : @key.text
+        @key = nil
+      end
+
+      def capture(char)
+        @string.add(char)
+        @state = :done if @string.closed?
+      end
+    end
+  end
+end

data/lib/smith/streaming/json_string.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Smith
+  module Streaming
+    # A JSON string's characters after its opening quote, given one at a
+    # time and unescaped as they come (JsonField). A UTF-16 surrogate pair
+    # (two escapes) is one character; half of one alone, or a `\u` escape
+    # that is not four hex digits, is the replacement character. With a
+    # `limit`, text past that many characters is dropped and the string is
+    # `overflowed?`.
+    class JsonString
+      ESCAPES = { '"' => '"', "\\" => "\\", "/" => "/", "b" => "\b", "f" => "\f", "n" => "\n", "r" => "\r",
+                  "t" => "\t" }.freeze
+      REPLACEMENT = "\uFFFD"
+      private_constant :ESCAPES, :REPLACEMENT
+
+      attr_reader :text
+
+      def initialize(limit: nil)
+        @text = String.new(encoding: Encoding::UTF_8)
+        @limit = limit
+        @length = 0
+        @escape = @overflowed = false
+        @unicode = @high = nil
+        @closed = false
+      end
+
+      def closed? = @closed
+
+      def overflowed? = @overflowed
+
+      def add(char)
+        return unicode_digit(char) if @unicode
+        return escaped(char) if @escape
+
+        case char
+        when "\\" then @escape = true
+        when '"' then close
+        else append(char)
+        end
+      end
+
+      private
+
+      def escaped(char)
+        @escape = false
+        char == "u" ? @unicode = +"" : append(ESCAPES.fetch(char, char))
+      end
+
+      def unicode_digit(char)
+        @unicode << char
+        return if @unicode.length < 4
+
+        digits = @unicode
+        @unicode = nil
+        digits.match?(/\A\h{4}\z/) ? append_code(digits.hex) : append(REPLACEMENT)
+      end
+
+      def append_code(code)
+        high = @high
+        @high = nil
+        return keep((0x10000 + ((high - 0xD800) << 10) + (code - 0xDC00)).chr(Encoding::UTF_8)) if
+          high && code.between?(0xDC00, 0xDFFF)
+
+        keep(REPLACEMENT) if high
+        if code.between?(0xD800, 0xDBFF) then @high = code
+        else keep(code.between?(0xDC00, 0xDFFF) ? REPLACEMENT : code.chr(Encoding::UTF_8))
+        end
+      end
+
+      def append(text)
+        keep(REPLACEMENT) if @high
+        @high = nil
+        keep(text) unless text.empty?
+      end
+
+      # One character more, unless past the limit.
+      def keep(char)
+        return @overflowed = true if @limit && @length >= @limit
+
+        @length += 1
+        @text << char
+      end
+
+      def close
+        append("")
+        @closed = true
+      end
+    end
+  end
+end

data/lib/smith/streaming/session.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Smith
+  module Streaming
+    # One step execution's stream, from the step's start to its outcome.
+    # Each provider call opens with `start(info)`, info being the step's
+    # (the stream's name, the run's execution key, the transition) with the
+    # step attempt (from 1), the model and its provider. `delta(text)` follows with each text
+    # chunk of the reply (tool calls and thinking are not sent; a tool
+    # loop's rounds are sent one after another). Before a call that
+    # replaces the text sent, that text is withdrawn with `reset(reason)`:
+    #
+    #   :retry        the step is attempted again (`retry_on`)
+    #   :fallback     another model answers (a provider failure, or a refusal)
+    #   :truncation   the reply was cut off and is asked for again
+    #   :repair       the reply could not be the output and is asked for again
+    #   :retry_wait   the step waits out a durable retry's backoff
+    #
+    # The step then ends with `finish(output)`, the output it accepted
+    # (after guardrails, the output contract and `output_to:`, once the step
+    # is stored), `fail(error_class)`, or `reset(:retry_wait)`, after which
+    # the attempt that resumes it streams to a new sink. A sink that raises
+    # (a ScriptError such as NotImplementedError included) is logged and the
+    # step goes on.
+    class Session
+      def initialize(sink, info)
+        @sink = sink
+        @info = info
+        @open = false
+        @settled = false
+      end
+
+      def start(attempt:, model:, provider:)
+        return if @settled
+
+        @open = true
+        notify(:start, @info.merge(attempt:, model:, provider:).freeze)
+      end
+
+      def delta(text)
+        notify(:delta, text) if @open && text.is_a?(String) && !text.empty?
+      end
+
+      # Withdraws the text sent since the last start, if any.
+      def withdraw(reason)
+        return unless @open
+
+        @open = false
+        notify(:reset, reason)
+      end
+
+      def finish(output) = settle(:finish, output)
+
+      def fail(error_class) = settle(:fail, error_class)
+
+      # The step waits out a durable retry's backoff: the sink's last word,
+      # whether or not text was sent.
+      def suspend = settle(:reset, :retry_wait)
+
+      private
+
+      def settle(method, value)
+        return if @settled
+
+        @settled = true
+        @open = false
+        notify(method, value)
+      end
+
+      def notify(method, value)
+        @sink.public_send(method, value) if @sink.respond_to?(method)
+      rescue StandardError, ScriptError => e
+        Smith.config.logger&.error("Smith stream sink #{@info[:stream].inspect} #{method} error: #{e.class}")
+      end
+    end
+  end
+end