ruby-pi 0.1.6 → 0.1.9

data/lib/ruby_pi/context/compaction.rb

@@ -87,34 +87,22 @@ module RubyPi
         # call but keep the matching tool_result, the API rejects the
         # request with "tool_result without preceding tool_use".
         #
-        # The boundary between droppable and preserved can split a tool
-        # exchange in two ways:
-        #   (a) preserved starts with one or more :tool messages whose
-        #       matching assistant turn is in droppable. Strip those
-        #       orphan tool messages from the head of preserved (move
-        #       them into droppable so they are summarized, not sent).
-        #   (b) the last droppable message is an :assistant with tool_calls,
-        #       but its matching :tool result(s) are in preserved. Pull
-        #       that assistant message back into preserved so the pair
-        #       stays intact.
-        #
-        # We apply (a) first: it's the common case (preserve_last_n=4 cuts
-        # mid-pair, leaving a stranded tool message). Then (b) catches the
-        # mirror case.
-        while preserved.first && preserved.first[:role] == :tool
+        # When the boundary between droppable and preserved cuts mid-exchange,
+        # preserved can start with one or more orphan :tool messages whose
+        # matching assistant turn is in droppable. Strip those off the head of
+        # preserved and move them into droppable so they are summarized away
+        # rather than sent. Because the originating assistant message is older,
+        # it is already in droppable, so the pair stays together there — there
+        # is no mirror case to handle (once a tool result is moved across, its
+        # assistant is never left stranded on the preserved side).
+        while preserved.first && message_value(preserved.first, :role).to_s == "tool"
           droppable << preserved.shift
         end
 
-        if droppable.last &&
-           droppable.last[:role] == :assistant &&
-           droppable.last[:tool_calls].is_a?(Array) &&
-           !droppable.last[:tool_calls].empty? &&
-           preserved.first && preserved.first[:role] == :tool
-          preserved.unshift(droppable.pop)
-        end
-
-        # After the boundary fix-ups, droppable may have become empty.
-        return nil if droppable.empty?
+        # The orphan-strip only moves messages INTO droppable, so droppable
+        # cannot have shrunk; it is still non-empty here. preserved, however,
+        # may now be empty (the whole window was tool results) — the summary
+        # construction below handles that case.
 
         # Generate a summary of the dropped messages
         summary = summarize(droppable)
@@ -122,28 +110,43 @@ module RubyPi
         # Emit compaction event if an emitter is available
         @emitter&.emit(:compaction, dropped_count: droppable.size, summary: summary)
 
-        # Build the compacted history: summary message + preserved.
-        #
-        # The summary role MUST NOT be :system (that would overwrite the real
-        # system prompt on Anthropic, which extracts the last :system message
-        # as the top-level `system:` parameter).
-        #
-        # The summary role must also NOT match the role of the first preserved
-        # message — consecutive same-role messages are rejected by Anthropic.
-        # We pick :user when the next preserved message is :assistant, and
-        # :assistant otherwise (covers :user, :tool, and an empty preserved).
-        # On Anthropic, :tool messages become role :user with tool_result
-        # blocks, so :assistant is the safe choice when the next message is
-        # :tool too.
-        first_preserved_role = preserved.first&.dig(:role)
-        summary_role = first_preserved_role == :assistant ? :user : :assistant
-
-        summary_message = {
-          role: summary_role,
-          content: "[Conversation Summary]\n#{summary}"
-        }
-
-        [summary_message] + preserved
+        build_compacted_history(summary, preserved)
+      end
+
+      # Builds the compacted history: a summary message followed by the
+      # preserved tail.
+      #
+      # The summary becomes the FIRST message of the compacted history, so it
+      # must satisfy the strictest provider constraints (Anthropic):
+      #   1. The summary role MUST NOT be :system — that would overwrite the
+      #      real system prompt on Anthropic, which promotes the last :system
+      #      message to the top-level `system:` parameter.
+      #   2. The first message MUST use role :user.
+      #   3. Consecutive same-role messages are rejected.
+      #
+      # A :user summary satisfies (1) and (2). For (3): the orphan-strip above
+      # guarantees the first preserved message is :assistant, :user, or absent
+      # (never :tool). When it is :assistant or absent, a standalone :user
+      # summary alternates correctly. When it is :user, a separate :user
+      # summary would create two consecutive user messages, so we instead
+      # merge the summary text into that existing user message — keeping the
+      # first message a single :user message with no role collision.
+      #
+      # @param summary [String] the generated summary text
+      # @param preserved [Array<Hash>] the preserved tail of messages
+      # @return [Array<Hash>] the compacted history
+      def build_compacted_history(summary, preserved)
+        summary_text = "[Conversation Summary]\n#{summary}"
+        first_preserved = preserved.first
+
+        if first_preserved && message_value(first_preserved, :role).to_s == "user"
+          merged = first_preserved.dup
+          content_key = first_preserved.key?(:content) ? :content : "content"
+          merged[content_key] = "#{summary_text}\n\n#{message_value(first_preserved, :content)}"
+          [merged] + preserved.drop(1)
+        else
+          [{ role: :user, content: summary_text }] + preserved
+        end
       end
 
       # Estimates the total token count for a system prompt and message array
@@ -156,7 +159,7 @@ module RubyPi
         total_chars = system_prompt.to_s.length
 
         messages.each do |msg|
-          total_chars += msg[:content].to_s.length
+          total_chars += message_value(msg, :content).to_s.length
           # Account for role and structural overhead (~10 tokens per message)
           total_chars += 40
         end
@@ -197,14 +200,20 @@ module RubyPi
       # @return [String] formatted prompt for summarization
       def build_summary_prompt(messages)
         transcript = messages.map do |msg|
-          role = msg[:role].to_s.capitalize
-          content = msg[:content].to_s
+          role = message_value(msg, :role).to_s.capitalize
+          content = message_value(msg, :content).to_s
           "#{role}: #{content}"
         end.join("\n\n")
 
         "Summarize the following conversation, preserving all key facts, " \
           "decisions, and tool call results:\n\n#{transcript}"
       end
+
+      # Reads normalized symbol-keyed messages and histories loaded from JSON,
+      # whose top-level keys are strings.
+      def message_value(message, key)
+        message[key] || message[key.to_s]
+      end
     end
   end
 end

data/lib/ruby_pi/llm/anthropic.rb

@@ -6,6 +6,8 @@
 # the Anthropic Messages API for both synchronous and streaming completions,
 # including tool_use block support.
 
+require "json"
+
 module RubyPi
   module LLM
     # Anthropic Claude provider implementation. Communicates with the Anthropic
@@ -338,7 +340,7 @@ module RubyPi
         end
 
         handle_error_response(response) unless response.success?
-        parse_response(JSON.parse(response.body))
+        parse_response(parse_json_response(response.body))
       end
 
       # Executes a streaming request to the Anthropic API, yielding events.
@@ -370,12 +372,19 @@ module RubyPi
         # process complete lines incrementally so that deltas reach the caller
         # as soon as each SSE event is fully received — not after the entire
         # response has been buffered.
-        sse_buffer = +""
+        #
+        # The buffer is BINARY because chunks arrive as ASCII-8BIT and may end
+        # mid-way through a multi-byte UTF-8 character; appending such a chunk
+        # to a UTF-8 buffer that already holds non-ASCII text raises
+        # Encoding::CompatibilityError. Each complete line is re-encoded to
+        # UTF-8 (and scrubbed) before parsing, so deltas reach the caller as
+        # valid UTF-8 strings.
+        sse_buffer = (+"").force_encoding(Encoding::BINARY)
         response_status = nil
 
         # Accumulate error response body separately so ApiError gets the
         # full body even though on_data consumed the chunks.
-        error_body = +""
+        error_body = (+"").force_encoding(Encoding::BINARY)
 
         response = with_transport_errors do
           conn.post("/v1/messages") do |req|
@@ -394,14 +403,17 @@ module RubyPi
             # calls on_data for error responses too, which would otherwise
             # consume the body and leave response.body empty.
             if response_status && response_status >= 400
-              error_body << chunk
+              error_body << chunk.b
               next
             end
 
-            sse_buffer << chunk
-            # Process all complete lines in the buffer
+            sse_buffer << chunk.b
+            # Process all complete lines in the buffer. A complete line holds
+            # complete UTF-8 sequences (multi-byte characters split across
+            # chunks are repaired by the buffering), so re-encode it to UTF-8
+            # here; scrub guards against a server sending invalid bytes.
             while (line_end = sse_buffer.index("\n"))
-              line = sse_buffer.slice!(0, line_end + 1).strip
+              line = sse_buffer.slice!(0, line_end + 1).force_encoding(Encoding::UTF_8).scrub.strip
               next if line.empty?
               next unless line.start_with?("data: ")
 
@@ -436,12 +448,12 @@ module RubyPi
         unless response.success?
           # Reconstruct the response body from what on_data accumulated
           error_response = response
-          error_body_str = error_body.empty? ? response.body : error_body
+          error_body_str = error_body.empty? ? response.body : error_body.force_encoding(Encoding::UTF_8).scrub
           handle_error_response(error_response, override_body: error_body_str)
         end
 
         # Process any remaining data in the buffer after the connection closes
-        sse_buffer.each_line do |line|
+        sse_buffer.force_encoding(Encoding::UTF_8).scrub.each_line do |line|
           line = line.strip
           next if line.empty?
           next unless line.start_with?("data: ")
@@ -562,7 +574,12 @@ module RubyPi
 
         when "message_delta"
           delta = data["delta"] || {}
-          finish_reason = delta["stop_reason"]
+          # Only overwrite finish_reason when this delta actually carries a
+          # stop_reason. Anthropic emits the stop_reason on a single
+          # message_delta near the end of the stream; a later message_delta
+          # without one must not clobber the captured value back to nil
+          # (which would yield a Response with no finish_reason).
+          finish_reason = delta["stop_reason"] if delta["stop_reason"]
           if data.key?("usage")
             usage_info = data["usage"]
             usage_data[:completion_tokens] = usage_info["output_tokens"]

data/lib/ruby_pi/llm/base_provider.rb

@@ -7,6 +7,9 @@
 # providers (Gemini, Anthropic, OpenAI) must subclass this and implement the
 # abstract methods.
 
+require "json"
+require "time"
+
 module RubyPi
   module LLM
     # Abstract base class that defines the contract every LLM provider must
@@ -53,6 +56,8 @@ module RubyPi
         @max_retries = max_retries || @config.max_retries
         @retry_base_delay = retry_base_delay || @config.retry_base_delay
         @retry_max_delay = retry_max_delay || @config.retry_max_delay
+
+        validate_retry_configuration!
       end
 
       # Sends a completion request to the LLM provider with automatic retry
@@ -71,22 +76,53 @@ module RubyPi
       # @raise [RubyPi::TimeoutError] on request timeouts
       def complete(messages:, tools: [], stream: false, &block)
         attempt = 0
+        partial_chars = 0
+
+        attempt_block = if stream && block
+                          proc do |event|
+                            partial_chars += event.data.to_s.length if event.text_delta?
+                            block.call(event)
+                          end
+                        else
+                          block
+                        end
 
         begin
           attempt += 1
-          perform_complete(messages: messages, tools: tools, stream: stream, &block)
+          perform_complete(messages: messages, tools: tools, stream: stream, &attempt_block)
         rescue RubyPi::AuthenticationError
           # Authentication errors are not retryable — raise immediately
           raise
-        rescue RubyPi::RateLimitError, RubyPi::ApiError, RubyPi::TimeoutError, RubyPi::ProviderError => e
+        rescue RubyPi::RateLimitError, RubyPi::ApiError, RubyPi::TimeoutError => e
+          # NOTE: RubyPi::ProviderError is intentionally NOT retried. Provider
+          # errors are overwhelmingly deterministic request-construction
+          # failures (missing tool_call_id, invalid tool-argument JSON, missing
+          # tool name) raised by build_request_body BEFORE any HTTP call. They
+          # produce the identical error on every attempt, so retrying only
+          # burns the backoff schedule before surfacing the same failure.
+          # Fallback wrappers still rescue RubyPi::Error (the ProviderError
+          # superclass), so provider failover is unaffected.
+          #
           # Retry up to max_retries times AFTER the initial attempt.
           # With max_retries: 3, attempt goes 1 (initial), 2, 3, 4 — the condition
           # `attempt <= @max_retries` allows retries on attempts 1..3, so we get
           # 3 retries + 1 initial = 4 total attempts. Previously used `< @max_retries`
           # which was off-by-one (only 2 retries with max_retries: 3).
-          if attempt <= @max_retries
-            delay = calculate_backoff(attempt)
+          if retryable_error?(e) && attempt <= @max_retries
+            delay = retry_delay_for(e, attempt)
             log_retry(attempt, delay, e)
+
+            if stream && block
+              block.call(StreamEvent.new(type: :retry_start, data: {
+                provider: provider_name,
+                error: e.message,
+                attempt: attempt + 1,
+                partial_output: partial_chars.positive?,
+                partial_chars: partial_chars
+              }))
+              partial_chars = 0
+            end
+
             sleep(delay)
             retry
           else
@@ -127,6 +163,40 @@ module RubyPi
         raise RubyPi::AbstractMethodError, :perform_complete
       end
 
+      # Maximum delay (seconds) honored from a server-provided Retry-After
+      # header. Caps pathological or misconfigured server values so a single
+      # 429 cannot stall the client indefinitely.
+      RETRY_AFTER_CEILING = 60.0
+
+      # Picks the delay before the next retry. A server-provided Retry-After
+      # on a 429 takes precedence over the local exponential backoff: the
+      # server knows its own cooldown window, and retrying earlier just burns
+      # the retry budget against guaranteed 429s. Retry-After parsed from an
+      # HTTP-date (rather than delta-seconds) arrives as 0.0 and falls through
+      # to the computed backoff.
+      #
+      # @param error [Exception] the error that triggered the retry
+      # @param attempt [Integer] the current attempt number (1-based)
+      # @return [Float] delay in seconds
+      def retry_delay_for(error, attempt)
+        if error.is_a?(RubyPi::RateLimitError) && error.retry_after&.positive?
+          [error.retry_after, RETRY_AFTER_CEILING].min
+        else
+          calculate_backoff(attempt)
+        end
+      end
+
+      # Only transient failures should be retried. Deterministic client errors
+      # (400, 404, 422, etc.) cannot improve on an identical retry and merely
+      # waste quota and add the full backoff delay.
+      def retryable_error?(error)
+        return true if error.is_a?(RubyPi::RateLimitError) || error.is_a?(RubyPi::TimeoutError)
+        return false unless error.is_a?(RubyPi::ApiError)
+
+        status = error.status_code
+        status.nil? || status == 408 || status == 409 || status == 425 || status >= 500
+      end
+
       # Calculates the backoff delay for a given retry attempt using
       # exponential backoff with jitter.
       #
@@ -138,6 +208,27 @@ module RubyPi
         [base + jitter, @retry_max_delay].min
       end
 
+      # Validates constructor-level overrides. Configuration's writers perform
+      # the same checks, but provider keyword overrides bypass those writers.
+      # In particular, an infinite max_retries value makes the retry loop run
+      # forever because every finite attempt is <= Infinity.
+      def validate_retry_configuration!
+        unless @max_retries.is_a?(Integer) && @max_retries >= 0
+          raise ArgumentError,
+                "max_retries must be a non-negative integer, got #{@max_retries.inspect}"
+        end
+
+        {
+          retry_base_delay: @retry_base_delay,
+          retry_max_delay: @retry_max_delay
+        }.each do |name, value|
+          next if value.is_a?(Numeric) && !value.is_a?(Complex) && value.finite? && value >= 0
+
+          raise ArgumentError,
+                "#{name} must be a finite non-negative number, got #{value.inspect}"
+        end
+      end
+
       # Logs a retry attempt if a logger is configured.
       #
       # @param attempt [Integer] current attempt number
@@ -237,7 +328,7 @@ module RubyPi
             response_body: body
           )
         when 429
-          retry_after = response.headers["retry-after"]&.to_f
+          retry_after = parse_retry_after(response.headers["retry-after"])
           raise RubyPi::RateLimitError.new(
             "#{provider_name} rate limit exceeded (HTTP 429)",
             retry_after: retry_after,
@@ -252,6 +343,36 @@ module RubyPi
         end
       end
 
+      # Parses a successful JSON response into a Hash while preserving the
+      # provider error contract. A proxy can truncate a nominal HTTP 200 body;
+      # treating that as a transient ApiError allows retry/fallback instead of
+      # leaking JSON::ParserError or accepting an empty response.
+      def parse_json_response(body)
+        JSON.parse(body)
+      rescue JSON::ParserError => e
+        raise RubyPi::ApiError.new(
+          "#{provider_name} returned malformed JSON: #{e.message}",
+          status_code: nil,
+          response_body: body
+        )
+      end
+
+      # Parses both Retry-After forms allowed by HTTP: delta-seconds and an
+      # HTTP-date. Fractional seconds are retained for compatibility with API
+      # providers and fast test environments. Invalid or past dates return nil
+      # so the normal exponential backoff policy applies.
+      def parse_retry_after(value)
+        return nil if value.nil? || value.to_s.strip.empty?
+
+        seconds = Float(value, exception: false)
+        return seconds if seconds&.finite? && seconds.positive?
+
+        delay = Time.httpdate(value.to_s) - Time.now
+        delay.positive? ? delay : nil
+      rescue ArgumentError
+        nil
+      end
+
     end
   end
 end

data/lib/ruby_pi/llm/fallback.rb

@@ -16,11 +16,14 @@ module RubyPi
     # Authentication errors are NOT retried with the fallback since they
     # indicate a configuration problem rather than a transient failure.
     #
-    # Issue #23: When streaming, the Fallback now buffers deltas from the
-    # primary provider. If the primary fails mid-stream, the buffered deltas
-    # are discarded and the fallback provider streams fresh from the start.
-    # This prevents the consumer from seeing partial output from the primary
-    # concatenated with the complete output from the fallback.
+    # Issue #23 + Issue #12: When streaming, events flow from the primary
+    # provider directly to the consumer in real time (no buffering), preserving
+    # the streaming UX on the happy path. If the primary fails mid-stream, a
+    # :fallback_start StreamEvent is emitted before the fallback takes over, so
+    # the consumer can discard any partial output already rendered from the
+    # failed primary. (The agent loop translates :fallback_start into a
+    # :provider_fallback event; raw Fallback consumers should handle
+    # :fallback_start themselves.)
     #
     # @example Setting up a fallback chain
     #   primary  = RubyPi::LLM.model(:gemini, "gemini-2.0-flash")
@@ -146,6 +149,25 @@ module RubyPi
       # @yield [event] the consumer's streaming block
       # @return [RubyPi::LLM::Response]
       def perform_complete_with_streaming_fallback(messages:, tools:, &block)
+        # Count the characters of text already delivered to the consumer from
+        # the primary. If the primary fails mid-stream AFTER yielding text,
+        # the fallback streams a complete fresh response — a consumer that
+        # merely appends deltas would render the primary's partial text
+        # followed by the full fallback text. The :fallback_start payload
+        # carries partial_output/partial_chars so consumers can deterministically
+        # truncate what they already rendered.
+        partial_chars = 0
+        counting_block = proc do |event|
+          if event.retry_start?
+            # The provider tells consumers to discard its previous attempt,
+            # so only count text from the current attempt for a later fallback.
+            partial_chars = 0
+          elsif event.text_delta?
+            partial_chars += event.data.to_s.length
+          end
+          block.call(event)
+        end
+
         begin
           # Stream primary events directly to the consumer for real-time UX.
           # No buffering — tokens appear immediately as they arrive.
@@ -153,7 +175,7 @@ module RubyPi
             messages: messages,
             tools: tools,
             stream: true,
-            &block
+            &counting_block
           )
 
           response
@@ -164,12 +186,17 @@ module RubyPi
           log_fallback(e)
 
           # Signal the consumer that the primary failed mid-stream and a
-          # fallback provider is taking over. Consumers should use this event
-          # to clear any partial output from the failed primary.
+          # fallback provider is taking over. Consumers MUST use this event
+          # to clear any partial output from the failed primary:
+          #   partial_output — true when the primary yielded any text deltas
+          #   partial_chars  — how many characters were yielded (truncate by
+          #                    this amount if appending to a shared buffer)
           block.call(StreamEvent.new(type: :fallback_start, data: {
             failed_provider: @primary.provider_name,
             error: e.message,
-            fallback_provider: @fallback.provider_name
+            fallback_provider: @fallback.provider_name,
+            partial_output: partial_chars.positive?,
+            partial_chars: partial_chars
           }))
 
           # Stream directly from the fallback to the consumer's block.

data/lib/ruby_pi/llm/gemini.rb

@@ -6,6 +6,7 @@
 # the Gemini REST API for both synchronous and streaming completions, including
 # tool/function calling support.
 
+require "json"
 require "securerandom"
 
 module RubyPi
@@ -280,7 +281,7 @@ module RubyPi
         end
 
         handle_error_response(response) unless response.success?
-        parse_response(JSON.parse(response.body))
+        parse_response(parse_json_response(response.body))
       end
 
       # Executes a streaming request to the Gemini API, yielding events.
@@ -305,9 +306,14 @@ module RubyPi
         # which may split SSE events mid-line. We accumulate a line buffer and
         # process complete lines incrementally so that deltas reach the caller
         # as soon as each SSE event is fully received.
-        sse_buffer = +""
+        # BINARY buffer: chunks arrive as ASCII-8BIT and may end mid-way
+        # through a multi-byte UTF-8 character; appending such a chunk to a
+        # UTF-8 buffer holding non-ASCII text raises
+        # Encoding::CompatibilityError. Complete lines are re-encoded to
+        # UTF-8 (and scrubbed) before parsing.
+        sse_buffer = (+"").force_encoding(Encoding::BINARY)
         response_status = nil
-        error_body = +""
+        error_body = (+"").force_encoding(Encoding::BINARY)
 
         response = with_transport_errors do
           conn.post(url) do |req|
@@ -324,14 +330,17 @@ module RubyPi
             # If the HTTP status indicates an error, accumulate the body for
             # the error handler instead of parsing it as SSE events.
             if response_status && response_status >= 400
-              error_body << chunk
+              error_body << chunk.b
               next
             end
 
-            sse_buffer << chunk
-            # Process all complete lines in the buffer
+            sse_buffer << chunk.b
+            # Process all complete lines in the buffer. A complete line holds
+            # complete UTF-8 sequences (multi-byte characters split across
+            # chunks are repaired by the buffering), so re-encode it to UTF-8
+            # here; scrub guards against a server sending invalid bytes.
             while (line_end = sse_buffer.index("\n"))
-              line = sse_buffer.slice!(0, line_end + 1).strip
+              line = sse_buffer.slice!(0, line_end + 1).force_encoding(Encoding::UTF_8).scrub.strip
               next if line.empty?
               next unless line.start_with?("data: ")
 
@@ -375,8 +384,11 @@ module RubyPi
               # Parse the actual finish reason from the streaming response
               # instead of hardcoding "stop". Gemini sends finishReason in
               # the candidate object (e.g., "STOP", "MAX_TOKENS", "SAFETY").
+              # Coerce via to_s before downcase so a non-String payload can
+              # never raise NoMethodError mid-stream (mirrors the &.to_s in
+              # the non-streaming parse path).
               if candidate["finishReason"]
-                finish_reason = candidate["finishReason"].downcase
+                finish_reason = candidate["finishReason"].to_s.downcase
               end
 
               # Capture usage metadata if present
@@ -397,7 +409,7 @@ module RubyPi
         # callback. Pass the accumulated error_body so ApiError carries the
         # full server message instead of an empty body.
         unless response.success?
-          error_body_str = error_body.empty? ? response.body : error_body
+          error_body_str = error_body.empty? ? response.body : error_body.force_encoding(Encoding::UTF_8).scrub
           handle_error_response(response, override_body: error_body_str)
         end
 
@@ -450,8 +462,10 @@ module RubyPi
           }
         end
 
-        # Map Gemini finish reason to normalized string
-        finish_reason = candidate["finishReason"]&.downcase
+        # Map Gemini finish reason to normalized string. to_s guards against
+        # a non-String payload (mirrors the streaming path); &. keeps a
+        # missing finishReason as nil.
+        finish_reason = candidate["finishReason"]&.to_s&.downcase
 
         Response.new(
           content: content,

data/lib/ruby_pi/llm/openai.rb

@@ -6,6 +6,8 @@
 # OpenAI Chat Completions API for both synchronous and streaming completions,
 # including function/tool calling support.
 
+require "json"
+
 module RubyPi
   module LLM
     # OpenAI provider implementation. Communicates with the OpenAI Chat
@@ -289,7 +291,7 @@ module RubyPi
         end
 
         handle_error_response(response) unless response.success?
-        parse_response(JSON.parse(response.body))
+        parse_response(parse_json_response(response.body))
       end
 
       # Executes a streaming request to the OpenAI API, yielding events.
@@ -318,9 +320,14 @@ module RubyPi
         # which may split SSE events mid-line. We accumulate a line buffer and
         # process complete lines incrementally so that deltas reach the caller
         # as soon as each SSE event is fully received.
-        sse_buffer = +""
+        # BINARY buffer: chunks arrive as ASCII-8BIT and may end mid-way
+        # through a multi-byte UTF-8 character; appending such a chunk to a
+        # UTF-8 buffer holding non-ASCII text raises
+        # Encoding::CompatibilityError. Complete lines are re-encoded to
+        # UTF-8 (and scrubbed) before parsing.
+        sse_buffer = (+"").force_encoding(Encoding::BINARY)
         response_status = nil
-        error_body = +""
+        error_body = (+"").force_encoding(Encoding::BINARY)
 
         response = with_transport_errors do
           conn.post("/v1/chat/completions") do |req|
@@ -337,14 +344,17 @@ module RubyPi
             # If the HTTP status indicates an error, accumulate the body for
             # the error handler instead of parsing it as SSE events.
             if response_status && response_status >= 400
-              error_body << chunk
+              error_body << chunk.b
               next
             end
 
-            sse_buffer << chunk
-            # Process all complete lines in the buffer
+            sse_buffer << chunk.b
+            # Process all complete lines in the buffer. A complete line holds
+            # complete UTF-8 sequences (multi-byte characters split across
+            # chunks are repaired by the buffering), so re-encode it to UTF-8
+            # here; scrub guards against a server sending invalid bytes.
             while (line_end = sse_buffer.index("\n"))
-              line = sse_buffer.slice!(0, line_end + 1).strip
+              line = sse_buffer.slice!(0, line_end + 1).force_encoding(Encoding::UTF_8).scrub.strip
               next if line.empty?
               next unless line.start_with?("data: ")
 
@@ -419,7 +429,7 @@ module RubyPi
         # callback. Pass the accumulated error_body so ApiError carries the
         # full server message instead of an empty body.
         unless response.success?
-          error_body_str = error_body.empty? ? response.body : error_body
+          error_body_str = error_body.empty? ? response.body : error_body.force_encoding(Encoding::UTF_8).scrub
           handle_error_response(response, override_body: error_body_str)
         end