pocketrb 0.1.0 → 0.3.0

data/lib/pocketrb/providers/claude_max_proxy.rb

@@ -6,38 +6,56 @@ require "uri"
 
 module Pocketrb
   module Providers
-    # Claude Max API Proxy provider
-    # Uses the claude-max-api-proxy which provides OpenAI-compatible API
-    # Install: npm install -g claude-max-api-proxy
-    # Start: claude-max-api (runs on localhost:3456)
+    # Claude Max API Proxy provider. Uses the claude-max-api-proxy which provides OpenAI-compatible API
+    # - Install: npm install -g claude-max-api-proxy
+    # - Start: claude-max-api (runs on localhost:3456)
     class ClaudeMaxProxy < Base
+      # Available model aliases mapped to full model names
       MODELS = {
         "opus" => "claude-opus-4",
         "sonnet" => "claude-sonnet-4",
         "haiku" => "claude-haiku-4"
       }.freeze
 
+      # Default model alias
       DEFAULT_MODEL = "sonnet"
+      # Default base URL for claude-max-api proxy
       DEFAULT_BASE_URL = "http://localhost:3456/v1"
 
+      # Initialize Claude Max Proxy provider
+      # @param config [Hash] Configuration options (base_url, etc.)
       def initialize(config = {})
         @config = config
         @base_url = config[:base_url] || ENV["CLAUDE_MAX_PROXY_URL"] || DEFAULT_BASE_URL
         validate_config!
       end
 
+      # Provider name
+      # @return [Symbol] Provider identifier
       def name
         :claude_max_proxy
       end
 
+      # Default model for this provider
+      # @return [String] Default model alias
       def default_model
         DEFAULT_MODEL
       end
 
+      # List of available model aliases
+      # @return [Array<String>] Model alias names
       def available_models
         MODELS.keys
       end
 
+      # Send a chat request
+      # @param messages [Array<Message>] Conversation history
+      # @param tools [Array<Hash>, nil] Available tools for the model to use
+      # @param model [String, nil] Model name (defaults to DEFAULT_MODEL)
+      # @param temperature [Float] Temperature for response randomness (0.0-1.0)
+      # @param max_tokens [Integer] Maximum tokens in response
+      # @param thinking [Boolean] Enable extended thinking mode (not used for this provider)
+      # @return [LLMResponse] Model response
       def chat(messages:, tools: nil, model: nil, temperature: 0.7, max_tokens: 4096, thinking: false)
         model ||= default_model
         model_id = MODELS[model] || model
@@ -55,6 +73,14 @@ module Pocketrb
         parse_response(response, model_id)
       end
 
+      # Send a streaming chat request
+      # @param messages [Array<Message>] Conversation history
+      # @param tools [Array<Hash>, nil] Available tools for the model to use
+      # @param model [String, nil] Model name (defaults to DEFAULT_MODEL)
+      # @param temperature [Float] Temperature for response randomness (0.0-1.0)
+      # @param max_tokens [Integer] Maximum tokens in response
+      # @yieldparam chunk [String] Text chunk from streaming response
+      # @return [LLMResponse] Final complete response
       def chat_stream(messages:, tools: nil, model: nil, temperature: 0.7, max_tokens: 4096, &)
         model ||= default_model
         model_id = MODELS[model] || model
@@ -72,6 +98,7 @@ module Pocketrb
       end
 
       # Check if proxy is running
+      # @return [Boolean] true if the proxy health endpoint responds
       def available?
         uri = URI.parse("#{@base_url.sub("/v1", "")}/health")
         http = Net::HTTP.new(uri.host, uri.port)
@@ -85,10 +112,14 @@ module Pocketrb
 
       protected
 
+      # Supported provider features
+      # @return [Array<Symbol>]
       def supported_features
         %i[tools streaming]
       end
 
+      # Validate provider configuration (no API key needed for proxy)
+      # @return [void]
       def validate_config!
         # No API key needed - proxy uses CLI auth
         Pocketrb.logger.debug("Claude Max Proxy: #{@base_url}")
@@ -96,6 +127,14 @@ module Pocketrb
 
       private
 
+      # Build the OpenAI-compatible request body
+      # @param messages [Array<Message>] conversation messages
+      # @param model [String] model identifier
+      # @param tools [Array<Hash>, nil] tool definitions
+      # @param temperature [Float] sampling temperature
+      # @param max_tokens [Integer] maximum tokens to generate
+      # @param stream [Boolean] whether to enable streaming
+      # @return [Hash] request body
       def build_request_body(messages:, model:, tools:, temperature:, max_tokens:, stream:)
         body = {
           model: model,
@@ -113,6 +152,9 @@ module Pocketrb
         body
       end
 
+      # Format messages for the OpenAI-compatible proxy API
+      # @param messages [Array<Message>] conversation messages
+      # @return [Array<Hash>] formatted messages with role, content, and tool data
       def format_messages(messages)
         messages.map do |msg|
           formatted = { role: msg.role.to_s }
@@ -156,6 +198,9 @@ module Pocketrb
         end
       end
 
+      # Format a media object as an OpenAI image_url content block
+      # @param media [Media] image attachment to encode as a data URI or text fallback
+      # @return [Hash] image_url or text fallback content block
       def format_image_content(media)
         if media.data
           {
@@ -178,6 +223,9 @@ module Pocketrb
         end
       end
 
+      # Convert tool definitions to OpenAI function-calling format
+      # @param tools [Array<Hash>] tool definitions
+      # @return [Array<Hash>] OpenAI-formatted tool definitions
       def format_tools(tools)
         tools.map do |tool|
           func = tool[:function] || tool
@@ -192,6 +240,11 @@ module Pocketrb
         end
       end
 
+      # Make an HTTP POST request to the proxy
+      # @param endpoint [String] API endpoint path
+      # @param body [Hash] request body
+      # @return [Hash] parsed JSON response
+      # @raise [ProviderError] on non-200 response
       def make_request(endpoint, body)
         uri = URI.parse("#{@base_url}#{endpoint}")
         http = Net::HTTP.new(uri.host, uri.port)
@@ -218,6 +271,12 @@ module Pocketrb
         JSON.parse(response.body)
       end
 
+      # Make a streaming HTTP POST request, yielding text chunks
+      # @param endpoint [String] API endpoint path
+      # @param body [Hash] request body
+      # @param block [Proc] block to receive text chunks
+      # @return [LLMResponse] final accumulated response
+      # @raise [ProviderError] on non-200 response
       def stream_request(endpoint, body, &block)
         uri = URI.parse("#{@base_url}#{endpoint}")
         http = Net::HTTP.new(uri.host, uri.port)
@@ -277,7 +336,7 @@ module Pocketrb
         # Build final response
         parsed_tool_calls = tool_calls.compact.map do |tc|
           args = begin
-            JSON.parse(tc[:arguments])
+            JSON.parse(tc[:arguments], allow_duplicate_key: true)
           rescue JSON::ParserError
             {}
           end
@@ -297,6 +356,10 @@ module Pocketrb
         )
       end
 
+      # Parse the OpenAI-compatible response into an LLMResponse
+      # @param response [Hash] parsed JSON response
+      # @param model [String] model identifier used
+      # @return [LLMResponse] structured response
       def parse_response(response, model)
         choice = response.dig("choices", 0)
         message = choice&.dig("message") || {}
@@ -326,12 +389,15 @@ module Pocketrb
         )
       end
 
+      # Parse OpenAI-format tool calls into ToolCall objects
+      # @param tool_calls [Array<Hash>, nil] raw tool call data
+      # @return [Array<ToolCall>] parsed tool calls
       def parse_tool_calls(tool_calls)
         return [] unless tool_calls
 
         tool_calls.map do |tc|
           args = begin
-            JSON.parse(tc.dig("function", "arguments") || "{}")
+            JSON.parse(tc.dig("function", "arguments") || "{}", allow_duplicate_key: true)
           rescue JSON::ParserError
             {}
           end

data/lib/pocketrb/providers/openai_compatible.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Pocketrb
+  module Providers
+    # Provider for any server exposing the OpenAI chat completions API (vLLM, llama.cpp server,
+    # llamafile, LM Studio, Ollama, OpenAI itself)
+    class OpenAICompatible < OpenRouter
+      # Provider name
+      # @return [Symbol]
+      def name
+        :openai_compatible
+      end
+
+      # Default model, taken from the configuration
+      # @return [String, nil]
+      def default_model
+        @config[:model]
+      end
+
+      # Available models
+      # @return [Array<String>]
+      def available_models
+        [default_model].compact
+      end
+
+      protected
+
+      # Validate that an http(s) base URL is configured
+      # @return [void]
+      # @raise [ConfigurationError] if base URL is missing or invalid
+      def validate_config!
+        if base_url.to_s.empty?
+          raise ConfigurationError, "openai_compatible_base_url is required for #{self.class.name}"
+        end
+
+        return if http_url?(base_url)
+
+        raise ConfigurationError, "openai_compatible_base_url must be an http(s) URL, got #{base_url.inspect}"
+      end
+
+      private
+
+      # Base URL of the API, e.g. http://localhost:8000/v1
+      # @return [String, nil]
+      def base_url
+        @config[:openai_compatible_base_url] || ENV.fetch("OPENAI_COMPATIBLE_BASE_URL", nil)
+      end
+
+      # Check that a value is an http(s) URL with a host
+      # @param value [String] URL to check
+      # @return [Boolean]
+      def http_url?(value)
+        uri = URI.parse(value)
+        uri.is_a?(URI::HTTP) && !uri.host.to_s.empty?
+      rescue URI::InvalidURIError
+        false
+      end
+
+      # Provider label used in error messages
+      # @return [String]
+      def api_label
+        "OpenAI-compatible"
+      end
+
+      # Build Faraday HTTP client, sending the API key only when one is configured
+      # @return [Faraday::Connection]
+      def client
+        @client ||= Faraday.new(url: base_url) do |f|
+          f.headers["Content-Type"] = "application/json"
+          key = api_key(:openai_compatible_api_key)
+          f.headers["Authorization"] = "Bearer #{key}" if key
+          f.adapter Faraday.default_adapter
+        end
+      end
+    end
+  end
+end

data/lib/pocketrb/providers/openrouter.rb

@@ -5,57 +5,81 @@ require "json"
 
 module Pocketrb
   module Providers
-    # OpenRouter API provider for multi-model access
-    # Supports Claude, GPT-4, Llama, and many other models
+    # OpenRouter API provider for multi-model access. Supports Claude, GPT-4, Llama, and many other models
     class OpenRouter < Base
+      # OpenRouter API base URL
       API_URL = "https://openrouter.ai/api/v1"
 
+      # Popular models available through OpenRouter
       POPULAR_MODELS = %w[
-        anthropic/claude-sonnet-4
-        anthropic/claude-3.5-haiku
+        anthropic/claude-sonnet-5.5
+        anthropic/claude-haiku-5.5
+        anthropic/claude-opus-5.5
         openai/gpt-4o
         openai/gpt-4o-mini
-        google/gemini-pro-1.5
+        google/gemini-2.5-pro
         meta-llama/llama-3.1-70b-instruct
         mistralai/mistral-large
       ].freeze
 
+      # Provider name
+      # @return [Symbol]
       def name
         :openrouter
       end
 
+      # Default model
+      # @return [String]
       def default_model
-        "anthropic/claude-sonnet-4"
+        "anthropic/claude-sonnet-5.5"
       end
 
+      # Available models
+      # @return [Array<String>]
       def available_models
         # Could fetch from API, but use popular models for now
         POPULAR_MODELS
       end
 
+      # Send chat completion request
+      # @param messages [Array<Message>] Conversation messages
+      # @param tools [Array<Hash>, nil] Tool definitions
+      # @param model [String, nil] Model name (e.g., "anthropic/claude-sonnet-5.5")
+      # @param temperature [Float] Sampling temperature
+      # @param max_tokens [Integer] Maximum tokens to generate
+      # @param thinking [Boolean] Enable extended thinking (model-dependent)
+      # @return [LLMResponse] Parsed response
       def chat(messages:, tools: nil, model: nil, temperature: 0.7, max_tokens: 4096, thinking: false)
         model ||= default_model
         body = build_request_body(messages, tools, model, temperature, max_tokens)
 
-        response = client.post("/api/v1/chat/completions") do |req|
+        response = client.post("chat/completions") do |req|
           req.body = body.to_json
         end
 
         handle_response(response)
       end
 
-      def chat_stream(messages:, tools: nil, model: nil, temperature: 0.7, max_tokens: 4096, &block)
+      # Send streaming chat completion request
+      # @param messages [Array<Message>] Conversation messages
+      # @param tools [Array<Hash>, nil] Tool definitions
+      # @param model [String, nil] Model name
+      # @param temperature [Float] Sampling temperature
+      # @param max_tokens [Integer] Maximum tokens to generate
+      # @yieldparam chunk [String] Streamed text chunk
+      # @return [LLMResponse] Final response
+      def chat_stream(messages:, tools: nil, model: nil, temperature: 0.7, max_tokens: 4096, &)
         model ||= default_model
         body = build_request_body(messages, tools, model, temperature, max_tokens)
         body[:stream] = true
 
-        accumulated_content = ""
+        accumulated_content = +""
         accumulated_tool_calls = []
 
-        client.post("/api/v1/chat/completions") do |req|
+        client.post("chat/completions") do |req|
           req.body = body.to_json
           req.options.on_data = proc do |chunk, _|
-            process_stream_chunk(chunk, accumulated_content, accumulated_tool_calls, &block)
+            process_stream_chunk(chunk, accumulated_content, accumulated_tool_calls, &)
           end
         end
 
@@ -68,16 +92,29 @@ module Pocketrb
 
       protected
 
+      # Supported provider features
+      # @return [Array<Symbol>]
       def supported_features
         %i[tools streaming]
       end
 
+      # Validate that an OpenRouter API key is configured
+      # @return [void]
+      # @raise [ConfigurationError] if API key is missing
       def validate_config!
         require_api_key!(:openrouter_api_key)
       end
 
       private
 
+      # Provider label used in error messages
+      # @return [String]
+      def api_label
+        "OpenRouter"
+      end
+
+      # Build Faraday HTTP client with OpenRouter headers
+      # @return [Faraday::Connection]
       def client
         @client ||= Faraday.new(url: API_URL) do |f|
           f.headers["Content-Type"] = "application/json"
@@ -88,6 +125,13 @@ module Pocketrb
         end
       end
 
+      # Build the OpenAI-compatible request body for OpenRouter
+      # @param messages [Array<Message>] conversation messages
+      # @param tools [Array<Hash>, nil] tool definitions
+      # @param model [String] model identifier
+      # @param temperature [Float] sampling temperature
+      # @param max_tokens [Integer] maximum tokens to generate
+      # @return [Hash] request body
       def build_request_body(messages, tools, model, temperature, max_tokens)
         body = {
           model: model,
@@ -101,6 +145,9 @@ module Pocketrb
         body
       end
 
+      # Format a single message for the OpenAI-compatible API
+      # @param message [Message] conversation message with role, content, and optional tool data
+      # @return [Hash] formatted message with role and content
       def format_message(message)
         case message.role
         when Role::SYSTEM
@@ -130,6 +177,10 @@ module Pocketrb
         end
       end
 
+      # Handle HTTP response, raising on errors
+      # @param response [Faraday::Response] HTTP response
+      # @return [LLMResponse] parsed response
+      # @raise [ProviderError] on non-success HTTP status
       def handle_response(response)
         unless response.success?
           error_body = begin
@@ -137,13 +188,16 @@ module Pocketrb
           rescue StandardError
             { "error" => response.body }
           end
-          raise ProviderError, "OpenRouter API error: #{error_body["error"]}"
+          raise ProviderError, "#{api_label} API error: #{error_body["error"]}"
         end
 
         data = JSON.parse(response.body)
         parse_response(data)
       end
 
+      # Parse OpenRouter API response into an LLMResponse
+      # @param data [Hash] parsed JSON response body
+      # @return [LLMResponse] structured response with content, tool calls, and usage
       def parse_response(data)
         choice = data.dig("choices", 0)
         return LLMResponse.new(content: nil) unless choice
@@ -181,6 +235,12 @@ module Pocketrb
         )
       end
 
+      # Process a single SSE chunk from the streaming response
+      # @param chunk [String] raw SSE data chunk
+      # @param accumulated_content [String] buffer for accumulated text content
+      # @param _accumulated_tool_calls [Array<ToolCall>] buffer for tool calls (unused)
+      # @param block [Proc] callback receiving each text delta
+      # @return [void]
       def process_stream_chunk(chunk, accumulated_content, _accumulated_tool_calls, &block)
         chunk.split("\n").each do |line|
           next unless line.start_with?("data: ")

data/lib/pocketrb/providers/registry.rb

@@ -5,34 +5,54 @@ module Pocketrb
     # Registry for LLM providers
     class Registry
       class << self
+        # Get registry singleton instance
+        # @return [Registry] Registry instance
         def instance
           @instance ||= new
         end
 
+        # Register a provider (class method)
+        # @param name [String, Symbol] Provider name
+        # @param klass [Class] Provider class
+        # @return [void]
         def register(name, klass)
           instance.register(name, klass)
         end
 
+        # Get a provider instance (class method)
+        # @param name [String, Symbol] Provider name
+        # @param config [Hash] Provider configuration (defaults to empty hash)
+        # @return [Base] Provider instance
         def get(name, config = {})
           instance.get(name, config)
         end
 
+        # Get list of available provider names (class method)
+        # @return [Array<Symbol>] Provider names
         def available
           instance.available
         end
       end
 
+      # Initialize registry with default providers
       def initialize
         @providers = {}
         register_defaults
       end
 
       # Register a provider class
+      # @param name [String, Symbol] Provider name
+      # @param klass [Class] Provider class
+      # @return [void]
       def register(name, klass)
         @providers[name.to_sym] = klass
       end
 
       # Get an instance of a provider
+      # @param name [String, Symbol] Provider name
+      # @param config [Hash] Provider configuration (defaults to empty hash)
+      # @return [Base] Provider instance
+      # @raise [ConfigurationError] if provider is not registered
       def get(name, config = {})
         klass = @providers[name.to_sym]
         raise ConfigurationError, "Unknown provider: #{name}" unless klass
@@ -41,15 +61,19 @@ module Pocketrb
       end
 
       # List available provider names
+      # @return [Array<Symbol>]
       def available
         @providers.keys
       end
 
       private
 
+      # Register all built-in provider classes
+      # @return [void]
       def register_defaults
         register(:anthropic, Anthropic)
         register(:openrouter, OpenRouter)
+        register(:openai_compatible, OpenAICompatible)
         register(:ruby_llm, RubyLLMProvider)
         register(:claude_cli, ClaudeCLI)
         register(:claude_max_proxy, ClaudeMaxProxy)