pocketrb 0.1.0 → 0.3.0

data/lib/pocketrb/providers/anthropic.rb

@@ -5,30 +5,60 @@ require "json"
 
 module Pocketrb
   module Providers
-    # Direct Anthropic Claude API provider
-    # Supports extended thinking and all Claude-specific features
+    # Direct Anthropic Claude API provider. Supports extended thinking and all Claude-specific features
     class Anthropic < Base
+      # Anthropic API base URL
       API_URL = "https://api.anthropic.com/v1"
+      # Anthropic API version header value
       API_VERSION = "2023-06-01"
 
+      # Supported Claude models with context and output token limits
       MODELS = {
-        "claude-opus-4-20250514" => { context: 200_000, output: 32_000 },
-        "claude-sonnet-4-20250514" => { context: 200_000, output: 64_000 },
-        "claude-3-5-haiku-20241022" => { context: 200_000, output: 8192 }
+        "claude-opus-5-5" => { context: 1_000_000, output: 128_000 },
+        "claude-sonnet-5-5" => { context: 1_000_000, output: 128_000 },
+        "claude-haiku-5-5" => { context: 1_000_000, output: 128_000 }
       }.freeze
 
+      # First [major, minor] version per Claude family that rejects temperature with HTTP 400
+      SAMPLING_REJECTED_SINCE = { "opus" => [4, 7], "sonnet" => [5, 0], "haiku" => [5, 0] }.freeze
+
+      # Claude families that reject temperature in every version
+      SAMPLING_REJECTED_FAMILIES = %w[fable mythos].freeze
+
+      # Provider name
+      # @return [Symbol]
       def name
         :anthropic
       end
 
+      # Get the context window size for a model
+      # @param model [String, nil] Model name (defaults to default_model)
+      # @return [Integer] Context window size in tokens
+      def context_window(model: nil)
+        model ||= default_model
+        MODELS.dig(model, :context) || super
+      end
+
+      # Default model to use
+      # @return [String]
       def default_model
-        "claude-sonnet-4-20250514"
+        "claude-sonnet-5-5"
       end
 
+      # List of available models
+      # @return [Array<String>]
       def available_models
         MODELS.keys
       end
 
+      # Send chat completion request
+      # @param messages [Array<Message>] Conversation messages
+      # @param tools [Array<Hash>, nil] Tool definitions
+      # @param model [String, nil] Model name (defaults to default_model)
+      # @param temperature [Float] Sampling temperature (0.0-1.0)
+      # @param max_tokens [Integer] Maximum tokens to generate
+      # @param thinking [Boolean] Whether to enable extended thinking mode
+      # @return [LLMResponse] Parsed response with content and tool calls
       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, thinking)
@@ -40,7 +70,15 @@ module Pocketrb
         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 (defaults to default_model)
+      # @param temperature [Float] Sampling temperature (0.0-1.0)
+      # @param max_tokens [Integer] Maximum tokens to generate
+      # @yieldparam chunk [Hash] Streamed response chunk
+      # @return [LLMResponse] Final response with accumulated content
+      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, false)
         body[:stream] = true
@@ -52,7 +90,7 @@ module Pocketrb
         client.post("/v1/messages") 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
 
@@ -66,10 +104,15 @@ module Pocketrb
 
       protected
 
+      # Supported provider features
+      # @return [Array<Symbol>]
       def supported_features
         %i[tools streaming thinking vision]
       end
 
+      # Validate that required API credentials are present
+      # @return [void]
+      # @raise [ConfigurationError] if no credentials are configured
       def validate_config!
         return if oauth_token
         return if api_key(:anthropic_api_key)
@@ -81,14 +124,19 @@ module Pocketrb
       private
 
       # Check for OAuth token (Max subscription via `claude setup-token`)
+      # @return [String, nil] OAuth token if configured
       def oauth_token
         @config[:anthropic_oauth_token] || ENV.fetch("ANTHROPIC_OAUTH_TOKEN", nil)
       end
 
+      # Whether OAuth authentication is being used
+      # @return [Boolean]
       def using_oauth?
         !oauth_token.nil?
       end
 
+      # Build Faraday HTTP client with appropriate authentication headers
+      # @return [Faraday::Connection]
       def client
         @client ||= Faraday.new(url: API_URL) do |f|
           f.headers["Content-Type"] = "application/json"
@@ -108,6 +156,14 @@ module Pocketrb
         end
       end
 
+      # Build the API request body for Anthropic messages endpoint
+      # @param messages [Array<Message>] conversation messages
+      # @param tools [Array<Hash>, nil] tool definitions
+      # @param model [String] model name
+      # @param temperature [Float] sampling temperature
+      # @param max_tokens [Integer] maximum tokens to generate
+      # @param thinking [Boolean] whether to enable extended thinking
+      # @return [Hash] request body
       def build_request_body(messages, tools, model, temperature, max_tokens, thinking)
         system_message = extract_system_message(messages)
         conversation = format_messages(messages.reject { |m| m.role == Role::SYSTEM })
@@ -119,7 +175,7 @@ module Pocketrb
         }
 
         body[:system] = system_message if system_message
-        body[:temperature] = temperature unless thinking
+        body[:temperature] = temperature unless thinking || rejects_sampling?(model)
         body[:tools] = format_tools(tools) if tools&.any?
 
         body[:thinking] = { type: "enabled", budget_tokens: [max_tokens / 2, 10_000].min } if thinking
@@ -127,11 +183,31 @@ module Pocketrb
         body
       end
 
+      # Whether the model rejects temperature. Matches dated and unlisted IDs by family and version
+      # @param model [String] model name
+      # @return [Boolean]
+      def rejects_sampling?(model)
+        family, major, minor = model.match(/\Aclaude-([a-z]+)-(?:(\d+)(?:-(\d{1,2}))?(?:-|\z))?/)&.captures
+        return false unless family
+        return true if SAMPLING_REJECTED_FAMILIES.include?(family)
+
+        since = SAMPLING_REJECTED_SINCE[family]
+        return false unless since && major
+
+        ([major.to_i, minor.to_i] <=> since) >= 0
+      end
+
+      # Extract system message content from the message list
+      # @param messages [Array<Message>] conversation messages
+      # @return [String, nil] system message content
       def extract_system_message(messages)
         system_msg = messages.find { |m| m.role == Role::SYSTEM }
         system_msg&.content
       end
 
+      # Format a single message for the Anthropic API
+      # @param message [Message] conversation message with role, content, and optional tool data
+      # @return [Hash] Anthropic-formatted message
       def format_message(message)
         case message.role
         when Role::USER
@@ -153,6 +229,9 @@ module Pocketrb
         end
       end
 
+      # Format user message content, handling text and media blocks
+      # @param content [String, Array, Object] raw user content
+      # @return [String, Array<Hash>] formatted content blocks
       def format_user_content(content)
         return content if content.is_a?(String)
 
@@ -174,6 +253,9 @@ module Pocketrb
         end
       end
 
+      # Format a media attachment as an Anthropic image source block
+      # @param media [Media] attachment to convert to a base64 image source or text fallback
+      # @return [Hash] Anthropic image or text fallback block
       def format_media_block(media)
         return { type: "text", text: "[unsupported media]" } unless media
 
@@ -202,6 +284,9 @@ module Pocketrb
         }
       end
 
+      # Normalize content to a string or array
+      # @param content [String, Array, Object] raw message content to pass through or coerce to string
+      # @return [String, Array] normalized content
       def format_content(content)
         return content if content.is_a?(String)
         return content if content.is_a?(Array)
@@ -209,6 +294,9 @@ module Pocketrb
         content.to_s
       end
 
+      # Format assistant message content including tool use blocks
+      # @param message [Message] assistant message with optional tool calls
+      # @return [String, Array<Hash>] formatted content blocks
       def format_assistant_content(message)
         blocks = []
 
@@ -226,6 +314,9 @@ module Pocketrb
         blocks.empty? ? "" : blocks
       end
 
+      # Convert tool definitions to Anthropic format
+      # @param tools [Array<Hash>, nil] tool definitions (OpenAI or Anthropic format)
+      # @return [Array<Hash>, nil] Anthropic-formatted tool definitions
       def format_tools(tools)
         return nil if tools.nil? || tools.empty?
 
@@ -244,6 +335,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
@@ -258,6 +353,9 @@ module Pocketrb
         parse_response(data)
       end
 
+      # Parse Anthropic 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)
         content = ""
         thinking = nil
@@ -304,6 +402,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/base.rb

@@ -6,6 +6,8 @@ module Pocketrb
     class Base
       attr_reader :config
 
+      # Initialize provider
+      # @param config [Hash] Provider configuration options (defaults to empty hash)
       def initialize(config = {})
         @config = config
         validate_config!
@@ -13,8 +15,8 @@ module Pocketrb
 
       # Send a chat completion request
       # @param messages [Array<Message>] Conversation history
-      # @param tools [Array<Hash>|nil] Tool definitions
-      # @param model [String|nil] Model to use (defaults to provider default)
+      # @param tools [Array<Hash>, nil] Tool definitions
+      # @param model [String, nil] Model to use (defaults to provider default)
       # @param temperature [Float] Sampling temperature
       # @param max_tokens [Integer] Maximum tokens to generate
       # @param thinking [Boolean] Enable extended thinking (Claude only)
@@ -24,8 +26,14 @@ module Pocketrb
       end
 
       # Stream a chat completion request
-      # @yield [String|ToolCall] Chunks of content or tool calls
-      # @return [LLMResponse]
+      # @param messages [Array<Message>] Conversation history
+      # @param tools [Array<Hash>, nil] Tool definitions
+      # @param model [String, nil] Model to use (defaults to provider default)
+      # @param temperature [Float] Sampling temperature
+      # @param max_tokens [Integer] Maximum tokens to generate
+      # @param block [Proc] Block to receive streaming chunks
+      # @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, &block)
         raise NotImplementedError, "#{self.class}#chat_stream must be implemented"
       end
@@ -48,6 +56,13 @@ module Pocketrb
         raise NotImplementedError, "#{self.class}#name must be implemented"
       end
 
+      # Get the context window size for a model
+      # @param model [String, nil] Model name (defaults to default_model)
+      # @return [Integer] Context window size in tokens
+      def context_window(model: nil)
+        200_000
+      end
+
       # Check if provider supports a feature
       # @param feature [Symbol] :tools, :streaming, :thinking, :vision
       # @return [Boolean]
@@ -57,39 +72,59 @@ module Pocketrb
 
       protected
 
+      # Supported provider features
+      # @return [Array<Symbol>]
       def supported_features
         %i[tools streaming]
       end
 
+      # Validate provider configuration
+      # @return [void]
       def validate_config!
         # Override in subclasses to validate required config
       end
 
+      # Raise error if API key is missing from config and environment
+      # @param key_name [Symbol] configuration key name
+      # @return [void]
+      # @raise [ConfigurationError] if API key is not found
       def require_api_key!(key_name)
         return if @config[key_name] || ENV[key_name.to_s.upcase]
 
         raise ConfigurationError, "#{key_name} is required for #{self.class.name}"
       end
 
+      # Fetch API key from config or environment
+      # @param key_name [Symbol] configuration key name
+      # @return [String, nil] API key value
       def api_key(key_name)
         @config[key_name] || ENV.fetch(key_name.to_s.upcase, nil)
       end
 
       # Convert internal message format to provider-specific format
+      # @param messages [Array<Message>] conversation history to convert for the provider API
+      # @return [Array<Hash>] provider-formatted messages
       def format_messages(messages)
         messages.map { |msg| format_message(msg) }
       end
 
+      # Format a single message for the provider
+      # @param message [Message] conversation message with role, content, and optional tool data
+      # @return [Hash] provider-formatted message
       def format_message(message)
         raise NotImplementedError
       end
 
       # Convert provider response to internal format
+      # @param response [Hash] raw provider response
+      # @return [LLMResponse] parsed response
       def parse_response(response)
         raise NotImplementedError
       end
 
       # Convert tool definitions to provider-specific format
+      # @param tools [Array<Hash>] tool definitions
+      # @return [Array<Hash>] provider-formatted tools
       def format_tools(tools)
         tools
       end

data/lib/pocketrb/providers/claude_cli.rb

@@ -4,20 +4,27 @@ require "json"
 require "open3"
 
 module Pocketrb
+  # LLM provider implementations
   module Providers
     # Claude CLI provider - uses the `claude` command as a subprocess
     # This allows using Claude Max/Pro subscription authentication
     class ClaudeCLI < Base
+      # Supported model aliases mapped to full model names
       MODELS = {
-        "opus" => "claude-opus-4-20250514",
-        "sonnet" => "claude-sonnet-4-20250514",
-        "haiku" => "claude-3-5-haiku-20241022"
+        "opus" => "claude-opus-5-5",
+        "sonnet" => "claude-sonnet-5-5",
+        "haiku" => "claude-haiku-5-5"
       }.freeze
 
+      # Default model to use when none specified
       DEFAULT_MODEL = "sonnet"
+      # Read timeout for CLI responses in seconds
       READ_TIMEOUT = 60
+      # Total timeout for CLI operations in seconds
       TOTAL_TIMEOUT = 300
 
+      # Initialize Claude CLI provider
+      # @param config [Hash] Configuration options
       def initialize(config = {})
         @config = config
         @stdin = nil
@@ -29,18 +36,32 @@ module Pocketrb
         validate_config!
       end
 
+      # Provider name
+      # @return [Symbol]
       def name
         :claude_cli
       end
 
+      # Default model
+      # @return [String]
       def default_model
         DEFAULT_MODEL
       end
 
+      # Available models
+      # @return [Array<String>]
       def available_models
         MODELS.keys
       end
 
+      # Send chat completion request
+      # @param messages [Array<Message>] Conversation messages
+      # @param tools [Array<Hash>, nil] Tool definitions
+      # @param model [String, nil] Model alias (opus, sonnet, haiku)
+      # @param temperature [Float] Sampling temperature
+      # @param max_tokens [Integer] Maximum tokens to generate
+      # @param thinking [Boolean] Enable extended thinking (not supported in CLI)
+      # @return [LLMResponse] Parsed response
       def chat(messages:, tools: nil, model: nil, temperature: 0.7, max_tokens: 4096, thinking: false)
         model ||= default_model
 
@@ -58,7 +79,15 @@ module Pocketrb
         raise ProviderError, "Claude CLI error: #{e.message}"
       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 alias
+      # @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
 
         @mutex.synchronize do
@@ -66,7 +95,7 @@ module Pocketrb
 
           prompt = build_prompt(messages, tools)
           send_message(prompt)
-          response = read_response_streaming(&block)
+          response = read_response_streaming(&)
 
           parse_cli_response(response, model)
         end
@@ -75,6 +104,8 @@ module Pocketrb
         raise ProviderError, "Claude CLI error: #{e.message}"
       end
 
+      # Start the Claude CLI subprocess
+      # @return [void]
       def start!
         return if running?
 
@@ -115,6 +146,8 @@ module Pocketrb
         end
       end
 
+      # Check if autonomous mode is enabled
+      # @return [Boolean] True if autonomous mode is enabled via config or env
       def autonomous_mode?
         @config[:autonomous] ||
           @config[:dangerously_skip_permissions] ||
@@ -122,6 +155,8 @@ module Pocketrb
           ENV["POCKETRB_AUTONOMOUS"] == "true"
       end
 
+      # Stop the Claude CLI subprocess
+      # @return [void]
       def stop!
         @stdin&.close
         @stdout&.close
@@ -131,16 +166,23 @@ module Pocketrb
         @stdin = @stdout = @stderr = @wait_thread = @stderr_thread = nil
       end
 
+      # Check if CLI subprocess is running
+      # @return [Boolean] True if subprocess is alive
       def running?
         @wait_thread&.alive? || false
       end
 
       protected
 
+      # Supported provider features
+      # @return [Array<Symbol>]
       def supported_features
         %i[tools streaming thinking]
       end
 
+      # Validate that the claude CLI binary is available
+      # @return [void]
+      # @raise [ConfigurationError] if claude CLI is not found
       def validate_config!
         # Check if claude CLI is available
         return if system("which claude > /dev/null 2>&1")
@@ -150,6 +192,10 @@ module Pocketrb
 
       private
 
+      # Build a prompt string or content blocks from messages and tools
+      # @param messages [Array<Message>] conversation messages
+      # @param tools [Array<Hash>, nil] tool definitions
+      # @return [String, Array<Hash>] prompt text or content blocks with images
       def build_prompt(messages, tools)
         # Build content blocks from messages, preserving images
         content_blocks = []
@@ -215,6 +261,9 @@ module Pocketrb
         end
       end
 
+      # Format a media object as a base64 image block for the CLI
+      # @param media [Media] image attachment to encode as base64 for the CLI protocol
+      # @return [Hash, nil] image content block or nil if unavailable
       def format_image_for_cli(media)
         return nil unless media&.image?
 
@@ -238,6 +287,9 @@ module Pocketrb
         }
       end
 
+      # Send a message to the CLI subprocess via stdin
+      # @param content [String, Array<Hash>] message content to send
+      # @return [void]
       def send_message(content)
         message = {
           type: "user",
@@ -247,6 +299,8 @@ module Pocketrb
         @stdin.flush
       end
 
+      # Read a complete response from the CLI subprocess
+      # @return [Hash] response with :content and :usage keys
       def read_response
         result_text = ""
         usage_data = {}
@@ -288,6 +342,9 @@ module Pocketrb
         { content: result_text, usage: usage_data }
       end
 
+      # Read response from CLI subprocess, yielding chunks as they arrive
+      # @param block [Proc] block to receive text chunks
+      # @return [Hash] response with :content and :usage keys
       def read_response_streaming(&block)
         result_text = ""
         usage_data = {}
@@ -319,12 +376,17 @@ module Pocketrb
         { content: result_text, usage: usage_data }
       end
 
+      # Read a single line from stdout with a timeout
+      # @return [String, nil] line read or nil on timeout
       def read_line_with_timeout
         Timeout.timeout(READ_TIMEOUT) { @stdout.gets }
       rescue Timeout::Error
         nil
       end
 
+      # Parse a JSON event line from the CLI output
+      # @param line [String, nil] raw JSON line
+      # @return [Hash, nil] parsed event or nil on parse failure
       def parse_event(line)
         return nil if line.nil? || line.strip.empty?
 
@@ -333,6 +395,9 @@ module Pocketrb
         nil
       end
 
+      # Extract text content from a CLI assistant event
+      # @param event [Hash] parsed CLI event
+      # @return [String] extracted text content
       def extract_text_from_event(event)
         text = ""
         if event.dig("message", "content")
@@ -343,6 +408,10 @@ module Pocketrb
         text
       end
 
+      # Parse the CLI response hash into an LLMResponse
+      # @param response [Hash] raw response with :content and :usage
+      # @param model [String] model alias used for the request
+      # @return [LLMResponse] structured response
       def parse_cli_response(response, model)
         content = response[:content]
         usage_data = response[:usage] || {}
@@ -370,6 +439,9 @@ module Pocketrb
         )
       end
 
+      # Extract tool call JSON blocks from response text
+      # @param text [String, nil] response text possibly containing tool call JSON
+      # @return [Array<ToolCall>] parsed tool calls
       def extract_tool_calls(text)
         return [] unless text
 
@@ -377,7 +449,7 @@ module Pocketrb
 
         # Look for JSON tool calls in code blocks
         text.scan(/```json\s*(\{.*?"tool".*?\})\s*```/m) do |match|
-          parsed = JSON.parse(match[0])
+          parsed = JSON.parse(match[0], allow_duplicate_key: true)
           if parsed["tool"]
             tool_calls << ToolCall.new(
               id: "cli_#{SecureRandom.hex(8)}",
@@ -392,7 +464,7 @@ module Pocketrb
         # Also try inline JSON
         if tool_calls.empty?
           text.scan(/\{"tool"\s*:\s*"\w+"[^}]*\}/m) do |match|
-            parsed = JSON.parse(match)
+            parsed = JSON.parse(match, allow_duplicate_key: true)
             if parsed["tool"]
               tool_calls << ToolCall.new(
                 id: "cli_#{SecureRandom.hex(8)}",