ruby-pi 0.1.0

data/lib/ruby_pi/llm/anthropic.rb

@@ -0,0 +1,314 @@
+# frozen_string_literal: true
+
+# lib/ruby_pi/llm/anthropic.rb
+#
+# LLM provider for Anthropic Claude. Implements the BaseProvider interface using
+# the Anthropic Messages API for both synchronous and streaming completions,
+# including tool_use block support.
+
+module RubyPi
+  module LLM
+    # Anthropic Claude provider implementation. Communicates with the Anthropic
+    # Messages API to generate text completions, handle tool_use blocks, and
+    # stream responses via Server-Sent Events.
+    #
+    # @example Basic usage
+    #   provider = RubyPi::LLM::Anthropic.new(
+    #     model: "claude-sonnet-4-20250514",
+    #     api_key: ENV["ANTHROPIC_API_KEY"]
+    #   )
+    #   response = provider.complete(messages: [{ role: "user", content: "Hello!" }])
+    #   puts response.content
+    class Anthropic < BaseProvider
+      # Base URL for the Anthropic Messages API.
+      BASE_URL = "https://api.anthropic.com"
+
+      # Anthropic API version header value.
+      API_VERSION = "2023-06-01"
+
+      # Default maximum tokens for a response.
+      DEFAULT_MAX_TOKENS = 4096
+
+      # Creates a new Anthropic provider instance.
+      #
+      # @param model [String] the Claude model identifier (e.g., "claude-sonnet-4-20250514")
+      # @param api_key [String, nil] Anthropic API key (falls back to global config)
+      # @param max_tokens [Integer] maximum tokens to generate (default: 4096)
+      # @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
+        @model = model || config.default_anthropic_model
+        @api_key = api_key || config.anthropic_api_key
+        @max_tokens = max_tokens
+      end
+
+      # Returns the Claude model identifier.
+      #
+      # @return [String]
+      def model_name
+        @model
+      end
+
+      # Returns :anthropic as the provider identifier.
+      #
+      # @return [Symbol]
+      def provider_name
+        :anthropic
+      end
+
+      private
+
+      # Performs the completion request against the Anthropic API.
+      #
+      # @param messages [Array<Hash>] conversation messages
+      # @param tools [Array<Hash>] tool definitions
+      # @param stream [Boolean] whether to use streaming
+      # @yield [event] streaming events if stream is true
+      # @return [RubyPi::LLM::Response]
+      def perform_complete(messages:, tools:, stream:, &block)
+        body = build_request_body(messages, tools, stream)
+
+        if stream && block_given?
+          perform_streaming_request(body, &block)
+        else
+          perform_standard_request(body)
+        end
+      end
+
+      # Builds the Anthropic API request body from messages and tools.
+      #
+      # @param messages [Array<Hash>] conversation messages
+      # @param tools [Array<Hash>] tool definitions
+      # @param stream [Boolean] whether streaming is enabled
+      # @return [Hash] the request body
+      def build_request_body(messages, tools, stream)
+        # Separate system message from conversation messages
+        system_message = nil
+        conversation = []
+
+        messages.each do |msg|
+          role = (msg[:role] || msg["role"]).to_s
+          content = msg[:content] || msg["content"]
+
+          if role == "system"
+            system_message = content.to_s
+          else
+            conversation << { role: role, content: content.to_s }
+          end
+        end
+
+        body = {
+          model: @model,
+          max_tokens: @max_tokens,
+          messages: conversation
+        }
+
+        body[:system] = system_message if system_message
+        body[:stream] = true if stream
+
+        unless tools.empty?
+          body[:tools] = tools.map { |t| format_tool(t) }
+        end
+
+        body
+      end
+
+      # Converts a tool definition to Anthropic's tool format.
+      # Accepts either a RubyPi::Tools::Definition or a plain Hash.
+      #
+      # @param tool [RubyPi::Tools::Definition, Hash] tool definition
+      # @return [Hash] Anthropic tool definition
+      def format_tool(tool)
+        return tool.to_anthropic_format if tool.respond_to?(:to_anthropic_format)
+
+        {
+          name: tool[:name] || tool["name"],
+          description: tool[:description] || tool["description"] || "",
+          input_schema: tool[:parameters] || tool["parameters"] || { type: "object", properties: {} }
+        }
+      end
+
+      # Executes a standard (non-streaming) request to the Anthropic API.
+      #
+      # @param body [Hash] the request body
+      # @return [RubyPi::LLM::Response]
+      def perform_standard_request(body)
+        conn = build_connection(
+          base_url: BASE_URL,
+          headers: default_headers
+        )
+
+        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_response(JSON.parse(response.body))
+      end
+
+      # Executes a streaming request to the Anthropic API, yielding events.
+      #
+      # @param body [Hash] the request body
+      # @yield [event] StreamEvent objects
+      # @return [RubyPi::LLM::Response] final aggregated response
+      def perform_streaming_request(body, &block)
+        conn = build_connection(
+          base_url: BASE_URL,
+          headers: default_headers
+        )
+
+        accumulated_text = +""
+        accumulated_tool_calls = []
+        current_tool_call = nil
+        current_tool_json = +""
+        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
+              }))
+            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
+              )
+              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
+        end
+
+        # Signal completion
+        block.call(StreamEvent.new(type: :done))
+
+        # Calculate total tokens
+        if usage_data[:prompt_tokens] && usage_data[:completion_tokens]
+          usage_data[:total_tokens] = usage_data[:prompt_tokens] + usage_data[:completion_tokens]
+        end
+
+        Response.new(
+          content: accumulated_text.empty? ? nil : accumulated_text,
+          tool_calls: accumulated_tool_calls,
+          usage: usage_data,
+          finish_reason: normalize_finish_reason(finish_reason)
+        )
+      end
+
+      # Returns the default HTTP headers required by the Anthropic API.
+      #
+      # @return [Hash] headers hash
+      def default_headers
+        {
+          "x-api-key" => @api_key.to_s,
+          "anthropic-version" => API_VERSION
+        }
+      end
+
+      # Parses an Anthropic API response hash into a normalized Response object.
+      #
+      # @param data [Hash] parsed JSON response from Anthropic
+      # @return [RubyPi::LLM::Response]
+      def parse_response(data)
+        content = nil
+        tool_calls = []
+
+        (data["content"] || []).each do |block|
+          case block["type"]
+          when "text"
+            content = (content || +"") << block["text"]
+          when "tool_use"
+            tool_calls << ToolCall.new(
+              id: block["id"],
+              name: block["name"],
+              arguments: block["input"] || {}
+            )
+          end
+        end
+
+        # Extract usage
+        usage = {}
+        if data.key?("usage")
+          usage_info = data["usage"]
+          usage = {
+            prompt_tokens: usage_info["input_tokens"],
+            completion_tokens: usage_info["output_tokens"],
+            total_tokens: (usage_info["input_tokens"] || 0) + (usage_info["output_tokens"] || 0)
+          }
+        end
+
+        Response.new(
+          content: content,
+          tool_calls: tool_calls,
+          usage: usage,
+          finish_reason: normalize_finish_reason(data["stop_reason"])
+        )
+      end
+
+      # Normalizes Anthropic-specific finish reasons to common values.
+      #
+      # @param reason [String, nil] Anthropic stop reason
+      # @return [String, nil] normalized finish reason
+      def normalize_finish_reason(reason)
+        case reason
+        when "end_turn" then "stop"
+        when "tool_use" then "tool_calls"
+        when "max_tokens" then "max_tokens"
+        else reason
+        end
+      end
+    end
+  end
+end

data/lib/ruby_pi/llm/base_provider.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+# lib/ruby_pi/llm/base_provider.rb
+#
+# Abstract base class for all LLM providers. Implements shared concerns such as
+# retry logic with exponential backoff and a consistent public interface. Concrete
+# providers (Gemini, Anthropic, OpenAI) must subclass this and implement the
+# abstract methods.
+
+module RubyPi
+  module LLM
+    # Abstract base class that defines the contract every LLM provider must
+    # fulfill. Provides built-in retry logic with exponential backoff for
+    # transient errors and a unified #complete interface for both synchronous
+    # and streaming completions.
+    #
+    # Subclasses MUST implement:
+    # - #perform_complete(messages:, tools:, stream:, &block)
+    # - #model_name
+    # - #provider_name
+    #
+    # @example Subclass implementation
+    #   class MyProvider < RubyPi::LLM::BaseProvider
+    #     def model_name = "my-model"
+    #     def provider_name = :my_provider
+    #
+    #     private
+    #     def perform_complete(messages:, tools:, stream:, &block)
+    #       # Make HTTP request and return RubyPi::LLM::Response
+    #     end
+    #   end
+    class BaseProvider
+      # @return [Integer] maximum number of retry attempts
+      attr_reader :max_retries
+
+      # @return [Float] base delay in seconds for exponential backoff
+      attr_reader :retry_base_delay
+
+      # @return [Float] maximum delay in seconds between retries
+      attr_reader :retry_max_delay
+
+      # 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
+      end
+
+      # Sends a completion request to the LLM provider with automatic retry
+      # logic for transient errors. When stream is true and a block is given,
+      # yields StreamEvent objects incrementally as they arrive.
+      #
+      # @param messages [Array<Hash>] conversation messages, each with :role and :content
+      # @param tools [Array<Hash>] tool/function definitions for the model
+      # @param stream [Boolean] whether to enable streaming mode
+      # @yield [event] yields StreamEvent objects when streaming
+      # @yieldparam event [RubyPi::LLM::StreamEvent] a stream event
+      # @return [RubyPi::LLM::Response] the normalized response
+      # @raise [RubyPi::AuthenticationError] on 401/403 responses
+      # @raise [RubyPi::RateLimitError] on 429 responses (after retries exhausted)
+      # @raise [RubyPi::ApiError] on other HTTP errors (after retries exhausted)
+      # @raise [RubyPi::TimeoutError] on request timeouts
+      def complete(messages:, tools: [], stream: false, &block)
+        attempt = 0
+
+        begin
+          attempt += 1
+          perform_complete(messages: messages, tools: tools, stream: stream, &block)
+        rescue RubyPi::AuthenticationError
+          # Authentication errors are not retryable — raise immediately
+          raise
+        rescue RubyPi::RateLimitError, RubyPi::ApiError, RubyPi::TimeoutError => e
+          if attempt < @max_retries
+            delay = calculate_backoff(attempt)
+            log_retry(attempt, delay, e)
+            sleep(delay)
+            retry
+          else
+            raise
+          end
+        end
+      end
+
+      # Returns the model name used by this provider instance.
+      # Subclasses MUST override this method.
+      #
+      # @return [String] the model identifier
+      # @raise [RubyPi::NotImplementedError] if not overridden
+      def model_name
+        raise RubyPi::NotImplementedError, :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
+      def provider_name
+        raise RubyPi::NotImplementedError, :provider_name
+      end
+
+      private
+
+      # Performs the actual completion request. Subclasses MUST implement this
+      # method with provider-specific HTTP logic.
+      #
+      # @param messages [Array<Hash>] conversation messages
+      # @param tools [Array<Hash>] tool definitions
+      # @param stream [Boolean] streaming mode flag
+      # @yield [event] optional block for streaming events
+      # @return [RubyPi::LLM::Response]
+      def perform_complete(messages:, tools:, stream:, &block)
+        raise RubyPi::NotImplementedError, :perform_complete
+      end
+
+      # Calculates the backoff delay for a given retry attempt using
+      # exponential backoff with jitter.
+      #
+      # @param attempt [Integer] the current attempt number (1-based)
+      # @return [Float] delay in seconds
+      def calculate_backoff(attempt)
+        base = @retry_base_delay * (2**(attempt - 1))
+        jitter = rand * @retry_base_delay * 0.5
+        [base + jitter, @retry_max_delay].min
+      end
+
+      # Logs a retry attempt if a logger is configured.
+      #
+      # @param attempt [Integer] current attempt number
+      # @param delay [Float] delay before next retry
+      # @param error [Exception] the error that triggered the retry
+      # @return [void]
+      def log_retry(attempt, delay, error)
+        logger = RubyPi.configuration.logger
+        return unless logger
+
+        logger.warn(
+          "[RubyPi::#{provider_name}] Retry #{attempt}/#{@max_retries} " \
+          "after #{delay.round(2)}s — #{error.class}: #{error.message}"
+        )
+      end
+
+      # Builds a Faraday connection with retry middleware and standard settings.
+      #
+      # @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
+
+        Faraday.new(url: base_url) do |conn|
+          conn.headers.update(headers)
+          conn.options.timeout = config.request_timeout
+          conn.options.open_timeout = config.open_timeout
+          conn.adapter :net_http
+        end
+      end
+
+      # Handles HTTP error responses by raising the appropriate RubyPi error.
+      #
+      # @param response [Faraday::Response] the HTTP response
+      # @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)
+        case response.status
+        when 401, 403
+          raise RubyPi::AuthenticationError.new(
+            "#{provider_name} authentication failed (HTTP #{response.status})",
+            response_body: response.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
+          )
+        else
+          raise RubyPi::ApiError.new(
+            "#{provider_name} API error (HTTP #{response.status})",
+            status_code: response.status,
+            response_body: response.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

data/lib/ruby_pi/llm/fallback.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+# lib/ruby_pi/llm/fallback.rb
+#
+# Provides automatic failover between LLM providers. Wraps a primary provider
+# with one or more fallback providers. If the primary fails with a retryable
+# error, the Fallback wrapper automatically routes the request to the next
+# available provider.
+
+module RubyPi
+  module LLM
+    # A resilient provider wrapper that tries a primary provider first and
+    # automatically falls back to an alternative provider on failure. Both
+    # providers must conform to the BaseProvider interface.
+    #
+    # Authentication errors are NOT retried with the fallback since they
+    # indicate a configuration problem rather than a transient failure.
+    #
+    # @example Setting up a fallback chain
+    #   primary  = RubyPi::LLM.model(:gemini, "gemini-2.0-flash")
+    #   backup   = RubyPi::LLM.model(:openai, "gpt-4o")
+    #   provider = RubyPi::LLM::Fallback.new(primary: primary, fallback: backup)
+    #
+    #   # If Gemini fails, automatically retries with OpenAI
+    #   response = provider.complete(messages: messages)
+    class Fallback < BaseProvider
+      # @return [RubyPi::LLM::BaseProvider] the primary provider
+      attr_reader :primary
+
+      # @return [RubyPi::LLM::BaseProvider] the fallback provider
+      attr_reader :fallback
+
+      # Creates a new Fallback wrapper with a primary and fallback provider.
+      #
+      # @param primary [RubyPi::LLM::BaseProvider] the preferred provider
+      # @param fallback [RubyPi::LLM::BaseProvider] the backup provider
+      # @param options [Hash] additional options passed to BaseProvider
+      def initialize(primary:, fallback:, **options)
+        super(**options)
+        @primary = primary
+        @fallback = fallback
+      end
+
+      # Returns the model name of the primary provider.
+      #
+      # @return [String]
+      def model_name
+        @primary.model_name
+      end
+
+      # Returns :fallback as the provider identifier.
+      #
+      # @return [Symbol]
+      def provider_name
+        :fallback
+      end
+
+      private
+
+      # Attempts the completion with the primary provider. If it fails with
+      # a retryable error (ApiError, RateLimitError, TimeoutError, ProviderError),
+      # the request is retried with the fallback provider. Authentication errors
+      # propagate immediately since they indicate misconfiguration.
+      #
+      # @param messages [Array<Hash>] conversation messages
+      # @param tools [Array<Hash>] tool definitions
+      # @param stream [Boolean] streaming mode flag
+      # @yield [event] optional block for streaming events
+      # @return [RubyPi::LLM::Response]
+      def perform_complete(messages:, tools:, stream:, &block)
+        @primary.complete(messages: messages, tools: tools, stream: stream, &block)
+      rescue RubyPi::AuthenticationError
+        # Configuration errors should not trigger fallback
+        raise
+      rescue RubyPi::Error => e
+        log_fallback(e)
+        @fallback.complete(messages: messages, tools: tools, stream: stream, &block)
+      end
+
+      # Logs the fallback event if a logger is configured.
+      #
+      # @param error [Exception] the error that triggered the fallback
+      # @return [void]
+      def log_fallback(error)
+        logger = RubyPi.configuration.logger
+        return unless logger
+
+        logger.warn(
+          "[RubyPi::Fallback] Primary provider (#{@primary.provider_name}/#{@primary.model_name}) " \
+          "failed with #{error.class}: #{error.message}. " \
+          "Falling back to #{@fallback.provider_name}/#{@fallback.model_name}."
+        )
+      end
+    end
+  end
+end