ruby-pi 0.1.3 → 0.1.6

data/lib/ruby_pi/llm/anthropic.rb

@@ -37,7 +37,7 @@ module RubyPi
       # @param options [Hash] additional options passed to BaseProvider
       def initialize(model: nil, api_key: nil, max_tokens: DEFAULT_MAX_TOKENS, **options)
         super(**options)
-        config = RubyPi.configuration
+        config = @config
         @model = model || config.default_anthropic_model
         @api_key = api_key || config.anthropic_api_key
         @max_tokens = max_tokens
@@ -172,9 +172,23 @@ module RubyPi
         tool_use_id = msg[:tool_call_id] || msg["tool_call_id"]
         content = msg[:content] || msg["content"]
 
+        # Fail fast with a descriptive error instead of sending "unknown" as
+        # the tool_use_id. Anthropic requires tool_use_id to match a preceding
+        # tool_use block; sending "unknown" causes an opaque HTTP 400 with no
+        # useful error message. Raising here gives the developer a clear signal
+        # about what went wrong.
+        if tool_use_id.nil? || tool_use_id.to_s.strip.empty?
+          raise RubyPi::ProviderError.new(
+            "Missing tool_call_id in tool result message. Anthropic requires " \
+            "tool_use_id to match a preceding tool_use block. Ensure every tool " \
+            "result message includes a valid :tool_call_id.",
+            provider: :anthropic
+          )
+        end
+
         block = {
           type: "tool_result",
-          tool_use_id: tool_use_id || "unknown"
+          tool_use_id: tool_use_id
         }
 
         # Content can be a simple string or a structured content array.
@@ -225,10 +239,12 @@ module RubyPi
             tc_name = tc[:name] || tc["name"]
             tc_args = tc[:arguments] || tc["arguments"] || {}
 
-            # Ensure arguments is a Hash; parse JSON string if needed
+            # Ensure arguments is a Hash; parse JSON string if needed.
+            # Issue #12: Guard against empty strings — they are truthy but
+            # cause JSON::ParserError when parsed.
             tc_input = if tc_args.is_a?(Hash)
                          tc_args
-                       elsif tc_args.is_a?(String) && !tc_args.empty?
+                       elsif tc_args.is_a?(String) && !tc_args.strip.empty?
                          begin
                            JSON.parse(tc_args)
                          rescue JSON::ParserError
@@ -238,17 +254,32 @@ module RubyPi
                          {}
                        end
 
+            # Fail fast if tool call ID is missing rather than sending "unknown"
+            # which causes an opaque Anthropic API 400 error.
+            if tc_id.nil? || tc_id.to_s.strip.empty?
+              raise RubyPi::ProviderError.new(
+                "Missing tool call ID in assistant message tool_calls. Anthropic " \
+                "requires each tool_use block to have a unique ID that subsequent " \
+                "tool_result blocks reference. Ensure every tool call includes an :id.",
+                provider: :anthropic
+              )
+            end
+
             content_blocks << {
               type: "tool_use",
-              id: tc_id || "unknown",
+              id: tc_id,
               name: tc_name || "unknown",
               input: tc_input
             }
           end
         end
 
-        # If no content blocks were generated (edge case), add an empty text
-        # block to satisfy Anthropic's requirement for non-empty content.
+        # Anthropic requires every assistant message to have at least one
+        # content block. When an assistant turn contains only tool_use calls
+        # with no accompanying text (common in multi-tool responses), the
+        # content_blocks array may be empty after processing. Adding an empty
+        # text block satisfies the API's non-empty content constraint without
+        # altering the semantic content of the message.
         content_blocks << { type: "text", text: "" } if content_blocks.empty?
 
         { role: "assistant", content: content_blocks }
@@ -299,9 +330,11 @@ module RubyPi
           headers: default_headers
         )
 
-        response = conn.post("/v1/messages") do |req|
-          req.headers["Content-Type"] = "application/json"
-          req.body = JSON.generate(body)
+        response = with_transport_errors do
+          conn.post("/v1/messages") do |req|
+            req.headers["Content-Type"] = "application/json"
+            req.body = JSON.generate(body)
+          end
         end
 
         handle_error_response(response) unless response.success?
@@ -310,6 +343,11 @@ module RubyPi
 
       # Executes a streaming request to the Anthropic API, yielding events.
       #
+      # Issue #22: Wraps JSON.parse(current_tool_json) at content_block_stop
+      # in a rescue block. If the stream was truncated or the accumulated JSON
+      # is malformed, raises a typed ProviderError instead of letting
+      # JSON::ParserError propagate and abort the entire stream processing.
+      #
       # @param body [Hash] the request body
       # @yield [event] StreamEvent objects
       # @return [RubyPi::LLM::Response] final aggregated response
@@ -326,71 +364,107 @@ module RubyPi
         usage_data = {}
         finish_reason = nil
 
-        response = conn.post("/v1/messages") do |req|
-          req.headers["Content-Type"] = "application/json"
-          req.body = JSON.generate(body)
-        end
-
-        handle_error_response(response) unless response.success?
-
-        # Parse SSE events from the response body
-        parse_sse_events(response.body) do |data|
-          event_type = data["type"]
-
-          case event_type
-          when "content_block_start"
-            content_block = data["content_block"] || {}
-            if content_block["type"] == "tool_use"
-              current_tool_call = {
-                id: content_block["id"],
-                name: content_block["name"]
-              }
-              current_tool_json = +""
-            end
-
-          when "content_block_delta"
-            delta = data["delta"] || {}
-            if delta["type"] == "text_delta"
-              text = delta["text"] || ""
-              accumulated_text << text
-              block.call(StreamEvent.new(type: :text_delta, data: text))
-            elsif delta["type"] == "input_json_delta"
-              json_chunk = delta["partial_json"] || ""
-              current_tool_json << json_chunk
-              block.call(StreamEvent.new(type: :tool_call_delta, data: {
-                id: current_tool_call&.dig(:id),
-                partial_json: json_chunk
-              }))
+        # Buffer for incomplete SSE lines across on_data chunks. Faraday's
+        # on_data callback delivers raw bytes as they arrive from the network,
+        # 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 — not after the entire
+        # response has been buffered.
+        sse_buffer = +""
+        response_status = nil
+
+        # Accumulate error response body separately so ApiError gets the
+        # full body even though on_data consumed the chunks.
+        error_body = +""
+
+        response = with_transport_errors do
+          conn.post("/v1/messages") do |req|
+            req.headers["Content-Type"] = "application/json"
+            req.body = JSON.generate(body)
+
+            # Use Faraday's on_data callback for real incremental streaming.
+          # Without this, Faraday buffers the entire response body before
+          # returning, which means no deltas reach the caller until the model
+          # finishes generating (fake streaming).
+          req.options.on_data = proc do |chunk, overall_received_bytes, env|
+            response_status ||= env&.status
+
+            # If the HTTP status indicates an error, accumulate the body for
+            # the error handler instead of parsing it as SSE events. Faraday
+            # 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
+              next
             end
 
-          when "content_block_stop"
-            if current_tool_call
-              arguments = current_tool_json.empty? ? {} : JSON.parse(current_tool_json)
-              accumulated_tool_calls << ToolCall.new(
-                id: current_tool_call[:id],
-                name: current_tool_call[:name],
-                arguments: arguments
+            sse_buffer << chunk
+            # Process all complete lines in the buffer
+            while (line_end = sse_buffer.index("\n"))
+              line = sse_buffer.slice!(0, line_end + 1).strip
+              next if line.empty?
+              next unless line.start_with?("data: ")
+
+              data_str = line.sub(/\Adata: /, "")
+              next if data_str == "[DONE]"
+
+              begin
+                data = JSON.parse(data_str)
+              rescue JSON::ParserError
+                next
+              end
+
+              # --- process each SSE event exactly as before ---
+              # Process the SSE event and update mutable locals from the
+              # returned hash. This keeps all streaming state method-local,
+              # avoiding thread-unsafe instance variables.
+              stream_state = process_anthropic_stream_event(
+                data, accumulated_text, accumulated_tool_calls,
+                current_tool_call, current_tool_json, usage_data, finish_reason, block
               )
-              current_tool_call = nil
-              current_tool_json = +""
-            end
-
-          when "message_delta"
-            delta = data["delta"] || {}
-            finish_reason = delta["stop_reason"]
-            if data.key?("usage")
-              usage_info = data["usage"]
-              usage_data[:completion_tokens] = usage_info["output_tokens"]
+              current_tool_call = stream_state[:current_tool_call]
+              current_tool_json = stream_state[:current_tool_json]
+              finish_reason = stream_state[:finish_reason]
             end
+          end
+          end # conn.post
+        end # with_transport_errors
+
+        # Check for HTTP errors. When on_data was active, the response body
+        # was consumed by the callback, so we pass the accumulated error_body
+        # to handle_error_response for proper error messaging.
+        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
+          handle_error_response(error_response, override_body: error_body_str)
+        end
 
-          when "message_start"
-            if data.dig("message", "usage")
-              usage_info = data["message"]["usage"]
-              usage_data[:prompt_tokens] = usage_info["input_tokens"]
-            end
+        # Process any remaining data in the buffer after the connection closes
+        sse_buffer.each_line do |line|
+          line = line.strip
+          next if line.empty?
+          next unless line.start_with?("data: ")
+          data_str = line.sub(/\Adata: /, "")
+          next if data_str == "[DONE]"
+          begin
+            data = JSON.parse(data_str)
+          rescue JSON::ParserError
+            next
           end
+          stream_state = process_anthropic_stream_event(
+            data, accumulated_text, accumulated_tool_calls,
+            current_tool_call, current_tool_json, usage_data, finish_reason, block
+          )
+          current_tool_call = stream_state[:current_tool_call]
+          current_tool_json = stream_state[:current_tool_json]
+          finish_reason = stream_state[:finish_reason]
         end
 
+        # (Event processing is now handled incrementally by the on_data callback
+        # above, which calls process_anthropic_stream_event for each complete
+        # SSE event as it arrives from the network.)
+
         # Signal completion
         block.call(StreamEvent.new(type: :done))
 
@@ -407,6 +481,108 @@ module RubyPi
         )
       end
 
+
+      # Processes a single Anthropic SSE event during streaming. Called by the
+      # on_data callback for each complete SSE event. Updates the mutable
+      # accumulator variables and yields deltas to the caller's block.
+      #
+      # Returns a hash with updated :current_tool_call, :current_tool_json,
+      # and :finish_reason values. The caller updates its own local variables
+      # from this hash, keeping all streaming state method-scoped and
+      # thread-safe.
+      #
+      # @param data [Hash] parsed SSE event payload
+      # @param accumulated_text [String] mutable text accumulator
+      # @param accumulated_tool_calls [Array] mutable tool call accumulator
+      # @param current_tool_call [Hash, nil] current in-progress tool call
+      # @param current_tool_json [String] current tool call JSON accumulator
+      # @param usage_data [Hash] mutable usage data accumulator
+      # @param finish_reason [String, nil] current finish reason
+      # @param block [Proc] the caller's streaming block
+      # @return [Hash] updated streaming state with :current_tool_call, :current_tool_json, :finish_reason
+      def process_anthropic_stream_event(data, accumulated_text, accumulated_tool_calls,
+                                          current_tool_call, current_tool_json,
+                                          usage_data, finish_reason, block)
+        event_type = data["type"]
+
+        case event_type
+        when "content_block_start"
+          content_block = data["content_block"] || {}
+          if content_block["type"] == "tool_use"
+            current_tool_call = {
+              id: content_block["id"],
+              name: content_block["name"]
+            }
+            current_tool_json = +""
+          end
+
+        when "content_block_delta"
+          delta = data["delta"] || {}
+          if delta["type"] == "text_delta"
+            text = delta["text"] || ""
+            accumulated_text << text
+            block.call(StreamEvent.new(type: :text_delta, data: text))
+          elsif delta["type"] == "input_json_delta"
+            json_chunk = delta["partial_json"] || ""
+            current_tool_json << json_chunk
+            block.call(StreamEvent.new(type: :tool_call_delta, data: {
+              id: current_tool_call&.dig(:id),
+              partial_json: json_chunk
+            }))
+          end
+
+        when "content_block_stop"
+          if current_tool_call
+            # Issue #22: Guard JSON.parse against truncated/malformed JSON.
+            # If the stream was interrupted mid-tool-call, the accumulated
+            # JSON may be incomplete. Rescue JSON::ParserError and raise a
+            # typed ProviderError with context about what failed.
+            arguments = if current_tool_json.strip.empty?
+                          {}
+                        else
+                          begin
+                            JSON.parse(current_tool_json)
+                          rescue JSON::ParserError => e
+                            raise RubyPi::ProviderError.new(
+                              "Failed to parse streaming tool call arguments for " \
+                              "'#{current_tool_call[:name]}': #{e.message} " \
+                              "(accumulated JSON: #{current_tool_json.inspect})",
+                              provider: :anthropic
+                            )
+                          end
+                        end
+            accumulated_tool_calls << ToolCall.new(
+              id: current_tool_call[:id],
+              name: current_tool_call[:name],
+              arguments: arguments
+            )
+            current_tool_call = nil
+            current_tool_json = +""
+          end
+
+        when "message_delta"
+          delta = data["delta"] || {}
+          finish_reason = delta["stop_reason"]
+          if data.key?("usage")
+            usage_info = data["usage"]
+            usage_data[:completion_tokens] = usage_info["output_tokens"]
+          end
+
+        when "message_start"
+          if data.dig("message", "usage")
+            usage_info = data["message"]["usage"]
+            usage_data[:prompt_tokens] = usage_info["input_tokens"]
+          end
+        end
+
+        # Return mutable state as a hash so the caller can update its locals.
+        # This avoids thread-unsafe instance variables that would leak state
+        # across concurrent requests on the same provider instance.
+        { current_tool_call: current_tool_call,
+          current_tool_json: current_tool_json,
+          finish_reason: finish_reason }
+      end
+
       # Returns the default HTTP headers required by the Anthropic API.
       #
       # @return [Hash] headers hash

data/lib/ruby_pi/llm/base_provider.rb

@@ -41,14 +41,18 @@ module RubyPi
 
       # Initializes the base provider with retry configuration.
       #
-      # @param max_retries [Integer, nil] override max retries (defaults to global config)
-      # @param retry_base_delay [Float, nil] override base delay (defaults to global config)
-      # @param retry_max_delay [Float, nil] override max delay (defaults to global config)
-      def initialize(max_retries: nil, retry_base_delay: nil, retry_max_delay: nil)
-        config = RubyPi.configuration
-        @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
+      # @param config [RubyPi::Configuration, nil] optional per-agent config override.
+      #   When provided, the provider uses this config instead of the global
+      #   RubyPi.configuration singleton. This enables per-agent API keys,
+      #   timeouts, and retry settings.
+      # @param max_retries [Integer, nil] override max retries (defaults to config)
+      # @param retry_base_delay [Float, nil] override base delay (defaults to config)
+      # @param retry_max_delay [Float, nil] override max delay (defaults to config)
+      def initialize(config: nil, max_retries: nil, retry_base_delay: nil, retry_max_delay: nil)
+        @config = config || RubyPi.configuration
+        @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
       end
 
       # Sends a completion request to the LLM provider with automatic retry
@@ -74,8 +78,13 @@ module RubyPi
         rescue RubyPi::AuthenticationError
           # Authentication errors are not retryable — raise immediately
           raise
-        rescue RubyPi::RateLimitError, RubyPi::ApiError, RubyPi::TimeoutError => e
-          if attempt < @max_retries
+        rescue RubyPi::RateLimitError, RubyPi::ApiError, RubyPi::TimeoutError, RubyPi::ProviderError => e
+          # 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)
             log_retry(attempt, delay, e)
             sleep(delay)
@@ -90,18 +99,18 @@ module RubyPi
       # Subclasses MUST override this method.
       #
       # @return [String] the model identifier
-      # @raise [RubyPi::NotImplementedError] if not overridden
+      # @raise [RubyPi::AbstractMethodError] if not overridden
       def model_name
-        raise RubyPi::NotImplementedError, :model_name
+        raise RubyPi::AbstractMethodError, :model_name
       end
 
       # Returns the provider identifier.
       # Subclasses MUST override this method.
       #
       # @return [Symbol] the provider identifier (e.g., :gemini, :anthropic, :openai)
-      # @raise [RubyPi::NotImplementedError] if not overridden
+      # @raise [RubyPi::AbstractMethodError] if not overridden
       def provider_name
-        raise RubyPi::NotImplementedError, :provider_name
+        raise RubyPi::AbstractMethodError, :provider_name
       end
 
       private
@@ -115,7 +124,7 @@ module RubyPi
       # @yield [event] optional block for streaming events
       # @return [RubyPi::LLM::Response]
       def perform_complete(messages:, tools:, stream:, &block)
-        raise RubyPi::NotImplementedError, :perform_complete
+        raise RubyPi::AbstractMethodError, :perform_complete
       end
 
       # Calculates the backoff delay for a given retry attempt using
@@ -136,7 +145,7 @@ module RubyPi
       # @param error [Exception] the error that triggered the retry
       # @return [void]
       def log_retry(attempt, delay, error)
-        logger = RubyPi.configuration.logger
+        logger = @config.logger
         return unless logger
 
         logger.warn(
@@ -145,13 +154,21 @@ module RubyPi
         )
       end
 
-      # Builds a Faraday connection with retry middleware and standard settings.
+      # Builds a Faraday connection with standard settings.
+      #
+      # Issue #20: Removed incorrect retry-middleware claim from the
+      # docstring. The faraday-retry gem was listed as a dependency but never
+      # wired into the connection builder. Since retry logic is already
+      # implemented in BaseProvider#complete with exponential backoff (see
+      # the begin/rescue/retry block), the Faraday-level retry middleware is
+      # not needed and would cause confusing double-retry behavior. The
+      # faraday-retry dependency has been removed from the gemspec.
       #
       # @param base_url [String] the base URL for the API
       # @param headers [Hash] default headers for all requests
       # @return [Faraday::Connection]
       def build_connection(base_url:, headers: {})
-        config = RubyPi.configuration
+        config = @config
 
         Faraday.new(url: base_url) do |conn|
           conn.headers.update(headers)
@@ -161,60 +178,80 @@ module RubyPi
         end
       end
 
+      # Wraps an HTTP block, translating Faraday transport-level exceptions
+      # (DNS failures, connection resets, TLS handshakes, read/write timeouts)
+      # into the RubyPi typed-error hierarchy so callers and the retry loop
+      # can rescue them uniformly.
+      #
+      # Without this wrapper, a `Faraday::TimeoutError` or
+      # `Faraday::ConnectionFailed` would propagate out of the provider as
+      # the raw Faraday class. That breaks two contracts:
+      #   1. The documented retry policy (BaseProvider#complete) only rescues
+      #      RubyPi errors, so transport failures would not be retried —
+      #      exactly the case retries exist for.
+      #   2. Callers `rescue RubyPi::TimeoutError` per the documented error
+      #      hierarchy and would not catch real network timeouts.
+      #
+      # @yield the HTTP call to wrap
+      # @return [Object] whatever the block returns
+      # @raise [RubyPi::TimeoutError] on Faraday::TimeoutError
+      # @raise [RubyPi::ApiError] on connection failures, SSL errors, or
+      #   any other Faraday::Error not otherwise classified
+      def with_transport_errors
+        yield
+      rescue Faraday::TimeoutError => e
+        raise RubyPi::TimeoutError, "#{provider_name} request timed out: #{e.message}"
+      rescue Faraday::ConnectionFailed, Faraday::SSLError => e
+        raise RubyPi::ApiError.new(
+          "#{provider_name} transport error: #{e.class}: #{e.message}",
+          status_code: nil,
+          response_body: nil
+        )
+      rescue Faraday::Error => e
+        # Catch-all for any other Faraday-level failure (parsing, adapter
+        # issues, etc.) so transport problems never leak provider internals.
+        raise RubyPi::ApiError.new(
+          "#{provider_name} HTTP client error: #{e.class}: #{e.message}",
+          status_code: nil,
+          response_body: nil
+        )
+      end
+
       # Handles HTTP error responses by raising the appropriate RubyPi error.
+      # When streaming with on_data, the response body is consumed by the
+      # callback and response.body may be empty. Pass override_body with the
+      # accumulated error chunks so the raised error contains the full body.
       #
       # @param response [Faraday::Response] the HTTP response
+      # @param override_body [String, nil] optional body to use instead of response.body
+      #   (used when on_data consumed the body during streaming)
       # @raise [RubyPi::AuthenticationError] on 401 or 403
       # @raise [RubyPi::RateLimitError] on 429
       # @raise [RubyPi::ApiError] on other error status codes
-      def handle_error_response(response)
+      def handle_error_response(response, override_body: nil)
+        body = override_body || response.body
         case response.status
         when 401, 403
           raise RubyPi::AuthenticationError.new(
             "#{provider_name} authentication failed (HTTP #{response.status})",
-            response_body: response.body
+            response_body: body
           )
         when 429
           retry_after = response.headers["retry-after"]&.to_f
           raise RubyPi::RateLimitError.new(
             "#{provider_name} rate limit exceeded (HTTP 429)",
             retry_after: retry_after,
-            response_body: response.body
+            response_body: body
           )
         else
           raise RubyPi::ApiError.new(
             "#{provider_name} API error (HTTP #{response.status})",
             status_code: response.status,
-            response_body: response.body
+            response_body: body
           )
         end
       end
 
-      # Processes a streaming response body line by line, parsing SSE events.
-      # Yields parsed data hashes to the provided block.
-      #
-      # @param response_body [String] the raw SSE response body
-      # @yield [data] parsed SSE event data
-      # @yieldparam data [Hash] a parsed JSON event payload
-      # @return [void]
-      def parse_sse_events(response_body, &block)
-        response_body.each_line do |line|
-          line = line.strip
-          next if line.empty?
-          next unless line.start_with?("data: ")
-
-          data_str = line.sub(/\Adata: /, "")
-          next if data_str == "[DONE]"
-
-          begin
-            data = JSON.parse(data_str)
-            block.call(data)
-          rescue JSON::ParserError
-            # Skip malformed SSE data lines
-            next
-          end
-        end
-      end
     end
   end
 end