prompt_builder 0.3.0 → 0.5.0

data/lib/prompt_builder/serializers/open_responses/request.rb

@@ -7,6 +7,14 @@ module PromptBuilder
       #
       # Required session fields (an UnsupportedFormatError is raised when missing):
       # - +model+
+      #
+      # Partially supported session fields:
+      # - +reasoning+ — forwarded as is, except that the +budget_tokens+,
+      #   +display+, and +type+ keys used by other serializers are omitted
+      #   since they are not part of the Open Responses schema.
+      #   +type: "disabled"+ (Session#think(false)) is sent as
+      #   +effort: "none"+ in place of any effort, and models that cannot
+      #   turn reasoning off reject it
       class Request < Base
         # Content extra keys that are part of the Open Responses API schema and
         # must survive extra-stripping (the canonical content classes have no
@@ -17,6 +25,11 @@ module PromptBuilder
         }.freeze
         private_constant :CANONICAL_EXTRA_KEYS
 
+        # Reasoning keys that only other serializers understand. The Open
+        # Responses API rejects unknown reasoning parameters.
+        NON_CANONICAL_REASONING_KEYS = ["budget_tokens", "display", "type"].freeze
+        private_constant :NON_CANONICAL_REASONING_KEYS
+
         class << self
           # Export a session to Open Responses API request payload.
           #
@@ -33,6 +46,7 @@ module PromptBuilder
             normalize_content_urls!(payload)
             strip_non_replayable_reasoning!(payload)
             strip_output_only_fields!(payload)
+            strip_non_canonical_reasoning_keys!(payload)
             normalize_and_validate_input_images!(payload)
             normalize_text_format!(payload)
             payload
@@ -251,6 +265,17 @@ module PromptBuilder
             end
           end
 
+          def strip_non_canonical_reasoning_keys!(payload)
+            reasoning = payload["reasoning"]
+            return unless reasoning.is_a?(Hash)
+
+            canonical = reasoning.except(*NON_CANONICAL_REASONING_KEYS)
+            # Effort is the only reasoning control, so turning reasoning off
+            # overrides any effort set alongside it.
+            canonical["effort"] = "none" if reasoning_disabled?(reasoning)
+            payload["reasoning"] = canonical
+          end
+
           def normalize_optional_string(value)
             return value unless value.is_a?(String)
 

data/lib/prompt_builder/serializers/open_responses/stream_accumulator.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module PromptBuilder
+  module Serializers
+    class OpenResponses < Base
+      # Reassembles an Open Responses SSE stream into the response object the
+      # non-streaming endpoint would have returned.
+      #
+      # The terminal events +response.completed+, +response.incomplete+, and
+      # +response.failed+ each carry the full response object, so the result is
+      # taken from that event rather than rebuilt from the deltas, and the
+      # other events are ignored. An +error+ event raises an
+      # ErrorResponseError.
+      class StreamAccumulator < Streaming::Accumulator
+        TERMINAL_EVENTS = %w[response.completed response.incomplete response.failed].freeze
+        private_constant :TERMINAL_EVENTS
+
+        def initialize
+          super
+          @response = nil
+        end
+
+        private
+
+        def handle_event(event)
+          type = event.event
+          # Only the terminal and error events need parsing. Events without a
+          # specific SSE event name are parsed to read the type from the data.
+          return unless type.nil? || type == "message" || type == "error" || TERMINAL_EVENTS.include?(type)
+
+          data = parse_json(event.data)
+          return unless data.is_a?(Hash)
+
+          type = data["type"] || type
+          if TERMINAL_EVENTS.include?(type)
+            @response = data["response"]
+          elsif type == "error"
+            # The error fields are either on the event itself or nested under
+            # an "error" object.
+            error = data["error"].is_a?(Hash) ? data["error"] : data.except("type")
+            raise_error_event!([error["code"] || error["type"], error["message"]].compact.join(": "))
+          end
+        end
+
+        def build_result
+          unless @response.is_a?(Hash)
+            incomplete!("Open Responses stream ended without a response.completed, response.incomplete, or response.failed event")
+          end
+
+          @response
+        end
+      end
+    end
+  end
+end

data/lib/prompt_builder/serializers/open_responses.rb

@@ -7,6 +7,7 @@ module PromptBuilder
     class OpenResponses < Base
       autoload :Request, File.expand_path("open_responses/request", __dir__)
       autoload :Response, File.expand_path("open_responses/response", __dir__)
+      autoload :StreamAccumulator, File.expand_path("open_responses/stream_accumulator", __dir__)
 
       class << self
         # Export a session to Open Responses API request payload.
@@ -16,14 +17,6 @@ module PromptBuilder
         def request_payload(session)
           Request.request_payload(session)
         end
-
-        # Parse an Open Responses response into an PromptBuilder::Response.
-        #
-        # @param hash [Hash] the response hash in Open Responses format
-        # @return [PromptBuilder::Response] the parsed response
-        def parse_response(hash)
-          Response.parse_response(hash)
-        end
       end
     end
   end

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