prompt_builder 0.4.0 → 0.5.0

data/lib/prompt_builder/session.rb

@@ -27,12 +27,6 @@ module PromptBuilder
     JSONIFY_FIELDS = %i[include tool_choice metadata text stream_options reasoning].freeze
     private_constant :JSONIFY_FIELDS
 
-    # Effort levels accepted by +think+. This is the union of the levels
-    # recognized across serializers; each serializer omits levels its target
-    # API does not support.
-    THINK_EFFORT_LEVELS = %w[minimal low medium high xhigh max].freeze
-    private_constant :THINK_EFFORT_LEVELS
-
     # All keyword options accepted by +initialize+.
     #
     # This constant is public API — unlike the private field-group constants
@@ -465,48 +459,72 @@ module PromptBuilder
     #   Open Responses (+reasoning.effort+)
     # - +budget_tokens+ — Messages (+thinking.budget_tokens+) and Gemini
     #   (+thinkingConfig.thinkingBudget+); ignored by effort-based APIs
-    # - Converse supports neither and warns once at serialization time
+    #   (Open Responses omits it from +reasoning+)
+    # - Converse sends both in +additionalModelRequestFields+ in the model
+    #   family's native format (Messages for Anthropic models, +reasoning+
+    #   for OpenAI models) and raises for other models
+    #
+    # Called with no depth control, it stores an empty configuration that
+    # leaves both whether and how much to reason to the target API's
+    # defaults. Only Messages has a switch for it, which it maps to adaptive
+    # thinking; Chat Completions and Gemini send no reasoning parameter, Open
+    # Responses sends an empty +reasoning+ object, and models that do not
+    # reason by default will not reason. Pass either
+    # +effort+ or +budget_tokens+, not both — providers reject requests that
+    # set both controls. An explicit token budget is only accepted by some
+    # models; +effort+ is the portable control. Direct
+    # +session.reasoning = {...}+ assignment keeps working for
+    # provider-specific keys.
     #
-    # Pass either +effort+ or +budget_tokens+, not both — providers reject
-    # requests that set both controls. Direct +session.reasoning = {...}+
-    # assignment keeps working for provider-specific keys.
+    # +think(false)+ turns reasoning off by storing
+    # <tt>{"type" => "disabled"}</tt>, which each serializer maps to its API's
+    # off switch: +thinking.type: "disabled"+ on Messages and Anthropic models
+    # on Converse, effort +none+ on Chat Completions, Open Responses, and
+    # OpenAI models on Converse, and +thinkingBudget: 0+ on Gemini. Models
+    # that cannot turn reasoning off reject these values. This differs from
+    # +session.reasoning = nil+, which sends no reasoning parameter and
+    # leaves the API's default in place; models that reason by default keep
+    # reasoning. An +effort+ can accompany +think(false)+ for the Messages
+    # API, where it limits overall token spend without thinking; APIs whose
+    # only reasoning control is effort ignore it so reasoning stays off.
     #
-    # @param enabled [Boolean] pass +false+ to clear the reasoning configuration
-    # @param effort [String, Symbol, nil] a portable effort level; one of
-    #   +minimal+, +low+, +medium+, +high+, +xhigh+, +max+ (unsupported levels
-    #   are omitted by serializers whose target API does not accept them)
+    # @param enabled [Boolean] pass +false+ to turn reasoning off
+    # @param effort [String, Symbol, nil] an effort level such as +minimal+,
+    #   +low+, +medium+, +high+, +xhigh+, or +max+. Any level is accepted, since
+    #   providers add new levels with new models; serializers forward it as is
+    #   and the target API rejects levels the model does not support
     # @param budget_tokens [Integer, nil] an explicit thinking token budget
-    # @return [Hash, nil] the resulting +reasoning+ configuration
-    # @raise [ArgumentError] if neither or both of +effort+ and +budget_tokens+
-    #   are given when enabling, or the values are invalid
+    # @return [Hash] the resulting +reasoning+ configuration
+    # @raise [ArgumentError] if both +effort+ and +budget_tokens+ are given
+    #   when enabling, +budget_tokens+ is given when disabling, or
+    #   +budget_tokens+ is not a positive integer
     # @example
+    #   session.think                        # API defaults (adaptive thinking on Messages)
     #   session.think(effort: :medium)       # portable across serializers
     #   session.think(budget_tokens: 8_000)  # explicit where supported
-    #   session.think(false)                 # disable
+    #   session.think(false)                 # turn reasoning off
+    #   session.think(false, effort: :low)   # off, with a Messages effort level
+    #   session.reasoning = nil              # API defaults, no reasoning parameter
     def think(enabled = true, effort: nil, budget_tokens: nil)
       unless enabled
-        raise ArgumentError, "cannot combine think(false) with effort or budget_tokens" if effort || budget_tokens
+        raise ArgumentError, "cannot combine think(false) with budget_tokens" if budget_tokens
 
-        return self.reasoning = nil
+        disabled = {"type" => "disabled"}
+        disabled["effort"] = effort.to_s if effort
+        return self.reasoning = disabled
       end
 
-      if effort && budget_tokens
-        raise ArgumentError, "pass either effort or budget_tokens, not both"
-      elsif effort.nil? && budget_tokens.nil?
-        raise ArgumentError, "think requires effort: or budget_tokens:"
-      end
+      raise ArgumentError, "pass either effort or budget_tokens, not both" if effort && budget_tokens
 
       if effort
-        effort = effort.to_s
-        unless THINK_EFFORT_LEVELS.include?(effort)
-          raise ArgumentError, "effort must be one of: #{THINK_EFFORT_LEVELS.join(", ")}"
-        end
-        self.reasoning = {"effort" => effort}
-      else
+        self.reasoning = {"effort" => effort.to_s}
+      elsif budget_tokens
         budget_tokens = Integer(budget_tokens)
         raise ArgumentError, "budget_tokens must be positive" unless budget_tokens.positive?
 
         self.reasoning = {"budget_tokens" => budget_tokens}
+      else
+        self.reasoning = {}
       end
     end
 

data/lib/prompt_builder/streaming/accumulator.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require "json"
+
+module PromptBuilder
+  module Streaming
+    # Base class for the per-format accumulators that reassemble a streamed
+    # response body into the Hash the non-streaming endpoint would have
+    # returned, so it can be parsed with +Response.parse+.
+    #
+    # Feed the raw body in chunks of any size with #feed (or #<<), then call
+    # #result. Only reassembly state is kept, not the raw body.
+    #
+    # A body that starts with +{+ or +[+ is not a stream (e.g. a JSON error
+    # envelope returned with a 4xx status, or a server that ignored the stream
+    # flag); it is buffered and returned parsed from #result, so +Response.parse+
+    # handles it as it would a non-streamed body.
+    #
+    # Once #feed or #result raises, the accumulator is spent: later calls raise
+    # the same error.
+    #
+    # Subclasses implement the private hooks +handle_event+ and +build_result+,
+    # and may override +new_decoder+ (an SSEParser by default) and
+    # +collapse_json+.
+    #
+    # @example
+    #   accumulator = PromptBuilder::Serializers::Messages.stream_accumulator
+    #   http_response.read_body { |chunk| accumulator << chunk }
+    #   PromptBuilder::Response.parse(accumulator.result, :messages)
+    class Accumulator
+      JSON_START = /[^\t\n\r ]/n
+      private_constant :JSON_START
+
+      def initialize
+        @leading = +"".b
+        @mode = nil
+        @decoder = nil
+        @json_body = nil
+        @finished = false
+        @result = nil
+        @error = nil
+      end
+
+      # Add the next chunk of the raw response body.
+      #
+      # @param chunk [String] the next chunk; may split events, lines, UTF-8
+      #   characters, or binary frames anywhere
+      # @return [self]
+      # @raise [ErrorResponseError] if the stream contains an error event
+      # @raise [ParseError] if the stream is malformed
+      # @raise [InvalidStateError] if called after #result
+      def feed(chunk)
+        raise @error if @error
+        raise InvalidStateError, "cannot feed a stream accumulator after calling result" if @finished
+        return self if chunk.nil? || chunk.empty?
+
+        capture_error do
+          chunk = chunk.b
+          case @mode
+          when :stream then decode(chunk)
+          when :json then @json_body << chunk
+          else detect_mode(chunk)
+          end
+        end
+        self
+      end
+      alias_method :<<, :feed
+
+      # Finish the stream and return the reassembled response. The result is
+      # computed once; later calls return the same Hash.
+      #
+      # @return [Hash, Array] the response the non-streaming endpoint would have
+      #   returned (or the parsed body if it was not a stream)
+      # @raise [IncompleteStreamError] if the stream ended before the format's
+      #   terminal event
+      # @raise [ErrorResponseError] if the stream contains an error event
+      # @raise [ParseError] if the stream is malformed
+      def result
+        raise @error if @error
+        return @result if @finished
+
+        @finished = true
+        capture_error { @result = finish_stream }
+      end
+
+      private
+
+      # Create the decoder for the stream framing. It must respond to
+      # +feed(chunk) { |event| }+ and +finish { |event| }+.
+      def new_decoder
+        SSEParser.new
+      end
+
+      # Process one decoded event (an SSEParser::Event or an
+      # EventStreamDecoder::Message).
+      def handle_event(_event)
+        raise NotImplementedError
+      end
+
+      # Build the non-streaming response Hash once the stream has ended.
+      def build_result
+        raise NotImplementedError
+      end
+
+      # Convert a body that was not a stream into the result.
+      def collapse_json(value)
+        value
+      end
+
+      # Parse a JSON event payload.
+      def parse_json(data)
+        JSON.parse(data.dup.force_encoding(Encoding::UTF_8))
+      rescue JSON::ParserError => e
+        raise ParseError, "streamed event is not valid JSON (#{e.message}): #{data.to_s[0, 200]}"
+      end
+
+      def raise_error_event!(message)
+        message = "unknown error" if message.nil? || message.empty?
+        raise ErrorResponseError, "the API returned an error: #{message}"
+      end
+
+      def incomplete!(message)
+        raise IncompleteStreamError, message
+      end
+
+      # Decide from the first non-whitespace byte whether the body is a stream
+      # or a plain JSON document. Leading whitespace is held until then.
+      def detect_mode(chunk)
+        @leading << chunk
+        index = @leading.index(JSON_START)
+        return unless index
+
+        body = @leading
+        @leading = nil
+        if body.getbyte(index) == 0x7B || body.getbyte(index) == 0x5B # "{" or "["
+          @mode = :json
+          @json_body = body
+        else
+          @mode = :stream
+          @decoder = new_decoder
+          decode(body)
+        end
+      end
+
+      def decode(chunk)
+        @decoder.feed(chunk) { |event| handle_event(event) }
+      end
+
+      def finish_stream
+        case @mode
+        when :stream
+          @decoder.finish { |event| handle_event(event) }
+          build_result
+        when :json
+          collapse_json(parse_json(@json_body))
+        else
+          incomplete!("the streamed response body was empty")
+        end
+      end
+
+      def capture_error
+        yield
+      rescue => e
+        @error = e
+        raise
+      end
+    end
+  end
+end

data/lib/prompt_builder/streaming/event_stream_decoder.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "zlib"
+
+module PromptBuilder
+  module Streaming
+    # Incremental decoder for the AWS event-stream binary framing
+    # (+application/vnd.amazon.eventstream+) used by Bedrock streaming APIs.
+    #
+    # Each message is a 12-byte prelude (total length, headers length, and a
+    # CRC32 of those 8 bytes), the typed headers, the payload, and a CRC32 of
+    # everything before it. Both checksums are verified. Chunks can split
+    # messages anywhere; only the bytes of the current incomplete message are
+    # kept between calls.
+    class EventStreamDecoder
+      # A decoded message.
+      #
+      # @!attribute [r] headers
+      #   @return [Hash{String => Object}] the message headers (e.g.
+      #     +":message-type"+, +":event-type"+, +":exception-type"+,
+      #     +":content-type"+) keyed by name
+      # @!attribute [r] payload
+      #   @return [String] the raw payload bytes (binary encoding)
+      Message = Struct.new(:headers, :payload)
+
+      PRELUDE_LENGTH = 12
+      private_constant :PRELUDE_LENGTH
+
+      CRC_LENGTH = 4
+      private_constant :CRC_LENGTH
+
+      def initialize
+        @buffer = +"".b
+      end
+
+      # Decode a chunk of the body, yielding each message it completes.
+      #
+      # @param chunk [String] the next chunk of the response body
+      # @yieldparam message [Message] a decoded message
+      # @return [self]
+      # @raise [ParseError] if a checksum does not match or a message is malformed
+      def feed(chunk, &block)
+        @buffer << chunk.b
+
+        messages = []
+        pos = 0
+        while @buffer.bytesize - pos >= PRELUDE_LENGTH
+          total_length, headers_length = read_prelude(pos)
+          break if @buffer.bytesize - pos < total_length
+
+          messages << decode_message(@buffer.byteslice(pos, total_length), headers_length)
+          pos += total_length
+        end
+        @buffer = @buffer.byteslice(pos, @buffer.bytesize - pos) if pos > 0
+
+        messages.each(&block)
+        self
+      end
+
+      # Signal the end of the body.
+      #
+      # @return [self]
+      # @raise [IncompleteStreamError] if the body ended in the middle of a message
+      def finish
+        unless @buffer.empty?
+          raise IncompleteStreamError,
+            "event stream ended in the middle of a message (#{@buffer.bytesize} bytes left over)"
+        end
+        self
+      end
+
+      private
+
+      def read_prelude(pos)
+        total_length, headers_length, prelude_crc = @buffer.byteslice(pos, PRELUDE_LENGTH).unpack("NNN")
+        actual_crc = Zlib.crc32(@buffer.byteslice(pos, 8))
+        unless actual_crc == prelude_crc
+          raise ParseError, "event stream prelude checksum mismatch (expected #{prelude_crc}, got #{actual_crc})"
+        end
+        if total_length < PRELUDE_LENGTH + CRC_LENGTH + headers_length
+          raise ParseError, "event stream message length #{total_length} is too short for #{headers_length} bytes of headers"
+        end
+
+        [total_length, headers_length]
+      end
+
+      def decode_message(bytes, headers_length)
+        expected_crc = bytes.byteslice(-CRC_LENGTH, CRC_LENGTH).unpack1("N")
+        actual_crc = Zlib.crc32(bytes.byteslice(0, bytes.bytesize - CRC_LENGTH))
+        unless actual_crc == expected_crc
+          raise ParseError, "event stream message checksum mismatch (expected #{expected_crc}, got #{actual_crc})"
+        end
+
+        payload_length = bytes.bytesize - PRELUDE_LENGTH - headers_length - CRC_LENGTH
+        Message.new(
+          decode_headers(bytes.byteslice(PRELUDE_LENGTH, headers_length)),
+          bytes.byteslice(PRELUDE_LENGTH + headers_length, payload_length)
+        )
+      end
+
+      def decode_headers(bytes)
+        headers = {}
+        pos = 0
+        take = lambda do |length|
+          raise ParseError, "event stream message headers are truncated" if pos + length > bytes.bytesize
+
+          value = bytes.byteslice(pos, length)
+          pos += length
+          value
+        end
+
+        while pos < bytes.bytesize
+          name = take.call(take.call(1).unpack1("C")).force_encoding(Encoding::UTF_8)
+          headers[name] = decode_header_value(take.call(1).unpack1("C"), take)
+        end
+        headers
+      end
+
+      def decode_header_value(type, take)
+        case type
+        when 0 then true
+        when 1 then false
+        when 2 then take.call(1).unpack1("c")
+        when 3 then take.call(2).unpack1("s>")
+        when 4 then take.call(4).unpack1("l>")
+        when 5 then take.call(8).unpack1("q>")
+        when 6 then take.call(take.call(2).unpack1("n"))
+        when 7 then take.call(take.call(2).unpack1("n")).force_encoding(Encoding::UTF_8)
+        when 8 then Time.at(0, take.call(8).unpack1("q>"), :millisecond).utc
+        when 9 then take.call(16).unpack1("H*").sub(/\A(.{8})(.{4})(.{4})(.{4})/, '\1-\2-\3-\4-')
+        else
+          raise ParseError, "unknown event stream header value type #{type}"
+        end
+      end
+    end
+  end
+end

data/lib/prompt_builder/streaming/sse_parser.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module PromptBuilder
+  module Streaming
+    # Incremental parser for a Server-Sent Events (text/event-stream) body.
+    #
+    # Chunks can split the body anywhere, including in the middle of a line, a
+    # CRLF pair, or a multi-byte UTF-8 character; only the current incomplete
+    # line and the current event's fields are kept between calls. Lines may end
+    # with LF, CRLF, or CR. Comment lines (starting with +:+) and unknown fields
+    # are ignored, multiple +data+ lines are joined with newlines, and a leading
+    # byte order mark is skipped. Unlike a browser EventSource, a final event
+    # that is not followed by a blank line is still dispatched by #finish, since
+    # some servers close the stream right after the last event.
+    class SSEParser
+      # A dispatched event.
+      #
+      # @!attribute [r] event
+      #   @return [String, nil] the +event+ field, or nil when the event has none
+      #     or an empty one (both mean the default +message+ event type)
+      # @!attribute [r] data
+      #   @return [String] the +data+ lines joined with newlines (UTF-8)
+      # @!attribute [r] id
+      #   @return [String, nil] the most recent +id+ field seen in the stream
+      Event = Struct.new(:event, :data, :id)
+
+      BOM = "\xEF\xBB\xBF".b.freeze
+      private_constant :BOM
+
+      LINE_BREAK = /[\r\n]/n
+      private_constant :LINE_BREAK
+
+      CR = 13
+      private_constant :CR
+
+      LF = 10
+      private_constant :LF
+
+      def initialize
+        @buffer = +"".b
+        # Where to resume searching for a line break, so an incomplete line
+        # held across chunks is not rescanned from the start on every chunk.
+        @scan_from = 0
+        @bom_checked = false
+        @event_type = nil
+        @data_lines = []
+        @last_event_id = nil
+      end
+
+      # Parse a chunk of the body, yielding each event it completes.
+      #
+      # @param chunk [String] the next chunk of the response body
+      # @yieldparam event [Event] a completed event
+      # @return [self]
+      def feed(chunk, &block)
+        @buffer << chunk.b
+        return self unless skip_bom
+
+        events = []
+        pos = 0
+        while (index = @buffer.index(LINE_BREAK, [pos, @scan_from].max))
+          next_pos = index + 1
+          if @buffer.getbyte(index) == CR
+            # A CR at the end of the buffer may be the first half of a CRLF
+            # split across chunks; wait for the next chunk to decide.
+            break if next_pos == @buffer.bytesize
+            next_pos += 1 if @buffer.getbyte(next_pos) == LF
+          end
+          process_line(@buffer.byteslice(pos, index - pos), events)
+          pos = next_pos
+        end
+        @buffer = @buffer.byteslice(pos, @buffer.bytesize - pos) if pos > 0
+        # The rest of the buffer has no line break, except possibly a trailing
+        # CR, so the next search only needs to start at the last byte.
+        @scan_from = [@buffer.bytesize - 1, 0].max
+
+        events.each(&block)
+        self
+      end
+
+      # Signal the end of the body, yielding the final event if it was not
+      # followed by a blank line.
+      #
+      # @yieldparam event [Event] the final event
+      # @return [self]
+      def finish(&block)
+        @bom_checked = true
+        events = []
+        unless @buffer.empty?
+          line = @buffer.end_with?("\r") ? @buffer.byteslice(0, @buffer.bytesize - 1) : @buffer
+          process_line(line, events)
+          @buffer = +"".b
+          @scan_from = 0
+        end
+        dispatch(events)
+
+        events.each(&block)
+        self
+      end
+
+      private
+
+      # Strip a byte order mark from the start of the stream. Returns false
+      # while the buffer is too short to tell whether it starts with one.
+      def skip_bom
+        return true if @bom_checked
+
+        if @buffer.bytesize < BOM.bytesize && BOM.start_with?(@buffer)
+          return false
+        end
+
+        @buffer = @buffer.byteslice(BOM.bytesize, @buffer.bytesize) if @buffer.start_with?(BOM)
+        @bom_checked = true
+      end
+
+      def process_line(line, events)
+        if line.empty?
+          dispatch(events)
+          return
+        end
+        return if line.start_with?(":")
+
+        field, value = line.split(":", 2)
+        value = value.to_s
+        value = value.byteslice(1, value.bytesize) if value.start_with?(" ")
+
+        case field
+        when "event"
+          # An empty event field means the default "message" type, the same
+          # as no event field at all.
+          @event_type = value.empty? ? nil : utf8(value)
+        when "data"
+          @data_lines << value
+        when "id"
+          @last_event_id = utf8(value) unless value.include?("\0")
+        end
+      end
+
+      def dispatch(events)
+        unless @data_lines.empty?
+          events << Event.new(@event_type, utf8(@data_lines.join("\n")), @last_event_id)
+        end
+        @event_type = nil
+        @data_lines = []
+      end
+
+      def utf8(value)
+        value.dup.force_encoding(Encoding::UTF_8)
+      end
+    end
+  end
+end

data/lib/prompt_builder/streaming.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module PromptBuilder
+  # Building blocks for reassembling streamed API responses into the body the
+  # non-streaming endpoint would have returned. Each serializer defines a
+  # +StreamAccumulator+ subclass of Streaming::Accumulator for its format;
+  # use +Serializers::Base.stream_accumulator+, +Serializers::Base.collapse_stream+,
+  # or +Response.parse_stream+ rather than these classes directly.
+  module Streaming
+    autoload :Accumulator, File.expand_path("streaming/accumulator", __dir__)
+    autoload :EventStreamDecoder, File.expand_path("streaming/event_stream_decoder", __dir__)
+    autoload :SSEParser, File.expand_path("streaming/sse_parser", __dir__)
+  end
+end

data/lib/prompt_builder.rb

@@ -12,6 +12,7 @@ module PromptBuilder
   autoload :ToolRegistry, "prompt_builder/tool_registry"
   autoload :Usage, "prompt_builder/usage"
   autoload :Serializers, "prompt_builder/serializers"
+  autoload :Streaming, "prompt_builder/streaming"
   autoload :Tools, "prompt_builder/tools"
 
   VERSION = File.read(File.join(__dir__, "../VERSION")).strip

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: prompt_builder
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Brian Durand
@@ -46,19 +46,28 @@ files:
 - lib/prompt_builder/serializers/chat_completion.rb
 - lib/prompt_builder/serializers/chat_completion/request.rb
 - lib/prompt_builder/serializers/chat_completion/response.rb
+- lib/prompt_builder/serializers/chat_completion/stream_accumulator.rb
 - lib/prompt_builder/serializers/converse.rb
 - lib/prompt_builder/serializers/converse/request.rb
 - lib/prompt_builder/serializers/converse/response.rb
+- lib/prompt_builder/serializers/converse/stream_accumulator.rb
 - lib/prompt_builder/serializers/gemini.rb
 - lib/prompt_builder/serializers/gemini/request.rb
 - lib/prompt_builder/serializers/gemini/response.rb
+- lib/prompt_builder/serializers/gemini/stream_accumulator.rb
 - lib/prompt_builder/serializers/messages.rb
 - lib/prompt_builder/serializers/messages/request.rb
 - lib/prompt_builder/serializers/messages/response.rb
+- lib/prompt_builder/serializers/messages/stream_accumulator.rb
 - lib/prompt_builder/serializers/open_responses.rb
 - lib/prompt_builder/serializers/open_responses/request.rb
 - lib/prompt_builder/serializers/open_responses/response.rb
+- lib/prompt_builder/serializers/open_responses/stream_accumulator.rb
 - lib/prompt_builder/session.rb
+- lib/prompt_builder/streaming.rb
+- lib/prompt_builder/streaming/accumulator.rb
+- lib/prompt_builder/streaming/event_stream_decoder.rb
+- lib/prompt_builder/streaming/sse_parser.rb
 - lib/prompt_builder/tool_registry.rb
 - lib/prompt_builder/tools.rb
 - lib/prompt_builder/tools/definition.rb