prompt_builder 0.3.0 → 0.5.0

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.3.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