pocketrb 0.1.0 → 0.3.0

data/lib/pocketrb/providers/ruby_llm_provider.rb

@@ -2,58 +2,58 @@
 
 module Pocketrb
   module Providers
-    # Provider using the RubyLLM gem for multi-model support
-    # This is an alternative to direct API calls
+    # Provider using the RubyLLM gem for multi-model support. This is an alternative to direct API calls
     class RubyLLMProvider < Base
+      # Provider name
+      # @return [Symbol]
       def name
         :ruby_llm
       end
 
+      # Default model
+      # @return [String]
       def default_model
-        "claude-sonnet-4-20250514"
+        "claude-sonnet-5-5"
       end
 
+      # Available models
+      # @return [Array<String>]
       def available_models
         return [] unless ruby_llm_available?
 
         RubyLLM.models.map(&:id)
       end
 
+      # Send 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
+      # @param thinking [Boolean] Enable extended thinking
+      # @return [LLMResponse] Parsed response
       def chat(messages:, tools: nil, model: nil, temperature: 0.7, max_tokens: 4096, thinking: false)
-        ensure_ruby_llm!
-
         model ||= default_model
-        chat_instance = RubyLLM.chat(model: model)
-
-        # Add tools if provided
-        tools&.each do |tool|
-          chat_instance.with_tool(build_ruby_llm_tool(tool))
-        end
-
-        # Configure and send
-        messages.each { |msg| add_message_to_chat(chat_instance, msg) }
+        chat_instance = build_chat(messages, tools, model, temperature, max_tokens, thinking)
 
-        response = chat_instance.complete
-
-        parse_ruby_llm_response(response, model)
+        parse_ruby_llm_response(chat_instance.generate, model)
       end
 
+      # 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
+      # @param block [Proc] Block to receive streaming chunks
+      # @yieldparam chunk [String] Streamed text chunk
+      # @return [LLMResponse] Final response
       def chat_stream(messages:, tools: nil, model: nil, temperature: 0.7, max_tokens: 4096, &block)
-        ensure_ruby_llm!
-
         model ||= default_model
-        chat_instance = RubyLLM.chat(model: model)
-
-        tools&.each do |tool|
-          chat_instance.with_tool(build_ruby_llm_tool(tool))
-        end
-
-        messages.each { |msg| add_message_to_chat(chat_instance, msg) }
+        chat_instance = build_chat(messages, tools, model, temperature, max_tokens, false)
 
-        accumulated = ""
-        response = chat_instance.stream do |chunk|
-          accumulated << chunk.content if chunk.content
-          block&.call(chunk.content)
+        response = chat_instance.generate do |chunk|
+          block&.call(chunk.content) if chunk.content && !chunk.content.empty?
         end
 
         parse_ruby_llm_response(response, model)
@@ -61,76 +61,190 @@ module Pocketrb
 
       protected
 
+      # Supported provider features
+      # @return [Array<Symbol>]
       def supported_features
         %i[tools streaming]
       end
 
+      # Validate provider configuration (delegated to RubyLLM)
+      # @return [void]
       def validate_config!
         # RubyLLM handles API key validation internally
       end
 
       private
 
+      # Check if the RubyLLM gem is loaded
+      # @return [Boolean]
       def ruby_llm_available?
         defined?(RubyLLM)
       end
 
+      # Ensure RubyLLM is loaded, attempting to require it if needed
+      # @return [void]
+      # @raise [ConfigurationError] if the gem is not installed
       def ensure_ruby_llm!
         return if ruby_llm_available?
 
-        begin
-          require "ruby_llm"
-          configure_ruby_llm
-        rescue LoadError
-          raise ConfigurationError, "ruby_llm gem is not installed. Add it to your Gemfile."
-        end
+        require "ruby_llm"
+      rescue LoadError
+        raise ConfigurationError, "ruby_llm gem is not installed. Add it to your Gemfile."
       end
 
-      def configure_ruby_llm
-        RubyLLM.configure do |c|
+      # RubyLLM context holding this provider's API keys, leaving the global RubyLLM config untouched
+      # @return [RubyLLM::Context]
+      def ruby_llm_context
+        ensure_ruby_llm!
+
+        @ruby_llm_context ||= RubyLLM.context do |c|
           c.anthropic_api_key = api_key(:anthropic_api_key) if api_key(:anthropic_api_key)
           c.openai_api_key = api_key(:openai_api_key) if api_key(:openai_api_key)
         end
       end
 
+      # Build a RubyLLM chat loaded with the conversation, without sending a request
+      # @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] enable extended thinking
+      # @return [RubyLLM::Chat] configured chat instance
+      def build_chat(messages, tools, model, temperature, max_tokens, thinking)
+        chat = ruby_llm_context.chat(model: model)
+        chat.with_max_output_tokens(max_tokens)
+        chat.with_temperature(temperature) unless thinking || chat.model.metadata[:temperature] == false
+        chat.with_thinking if thinking
+        tools&.each { |tool| chat.with_tools(build_ruby_llm_tool(tool)) }
+        messages.each { |msg| add_message_to_chat(chat, msg) }
+        chat
+      end
+
+      # Wrap a tool definition as a RubyLLM tool. Pocketrb runs tools itself, so it is never executed here
+      # @param tool [Hash] tool definition with optional :function key
+      # @return [Class<RubyLLM::Tool>] RubyLLM tool class with the definition's name and schema
       def build_ruby_llm_tool(tool)
-        tool[:function] || tool
-        # RubyLLM uses a different tool format - this would need adaptation
-        # based on actual RubyLLM API
+        definition = tool[:function] || tool
+        tool_name = definition[:name].to_s
+        schema = definition[:parameters] || definition[:input_schema]
+
+        Class.new(RubyLLM::Tool) do
+          description definition[:description]
+          parameters schema if schema
+          define_singleton_method(:tool_name) { tool_name }
+        end
       end
 
+      # Add a message to the RubyLLM chat instance based on its role
+      # @param chat [RubyLLM::Chat] RubyLLM chat instance
+      # @param message [Message] conversation message dispatched by role (system, user, assistant, tool)
+      # @return [void]
       def add_message_to_chat(chat, message)
         case message.role
         when Role::SYSTEM
-          chat.with_system_prompt(message.content)
+          chat.with_instructions(message.content, append: true)
         when Role::USER
-          chat.ask(message.content, stream: false)
+          text, attachments = split_user_content(chat, message.content)
+          chat.add_message(role: :user, content: text, attachments: attachments)
         when Role::ASSISTANT
-          # RubyLLM manages assistant messages internally
+          chat.add_message(
+            role: :assistant,
+            content: message.content.to_s.empty? ? nil : message.content,
+            tool_calls: build_ruby_llm_tool_calls(message.tool_calls)
+          )
         when Role::TOOL
-          # Tool results handled differently in RubyLLM
+          chat.add_message(role: :tool, content: message.content.to_s, tool_call_id: message.tool_call_id)
         end
       end
 
+      # Split user content into text and RubyLLM attachments. Media the model cannot read, or that is missing,
+      # becomes placeholder text, as RubyLLM raises on it
+      # @param chat [RubyLLM::Chat] chat whose model decides which images it accepts
+      # @param content [String, Array<Hash>] text or content blocks with text and media
+      # @return [Array(String, Array<RubyLLM::Attachment>)] text and attachments
+      def split_user_content(chat, content)
+        return [content, []] unless content.is_a?(Array)
+
+        vision = chat.model.modalities.input.include?("image")
+        texts = []
+        attachments = []
+
+        content.each do |block|
+          next texts << block[:text] if block[:type] == "text"
+          next unless block[:type] == "media"
+
+          attachment = build_attachment(block[:media], vision)
+          attachment.is_a?(String) ? texts << attachment : attachments << attachment
+        end
+
+        [texts.join("\n"), attachments]
+      end
+
+      # Convert a media item to a RubyLLM attachment, or to placeholder text when it cannot be sent
+      # @param media [Bus::Media, nil] media with a file path or base64 data
+      # @param vision [Boolean] whether the model accepts image input
+      # @return [RubyLLM::Attachment, String] attachment or placeholder text
+      def build_attachment(media, vision)
+        return "[unsupported media]" unless media
+        unless vision && media.image? && Media::Processor::VISION_IMAGE_TYPES.include?(media.mime_type)
+          return "[Attached: #{media.filename} (#{media.mime_type})]"
+        end
+
+        filename = media.filename || File.basename(media.path.to_s)
+        if media.data
+          RubyLLM::Attachment.new(StringIO.new(Base64.decode64(media.data)), filename: filename)
+        elsif media.path && File.exist?(media.path)
+          RubyLLM::Attachment.new(media.path, filename: filename)
+        else
+          "[Image not available]"
+        end
+      end
+
+      # Convert pocketrb tool calls to RubyLLM tool calls keyed by ID
+      # @param tool_calls [Array<ToolCall>, nil] tool calls made by the assistant
+      # @return [Hash{String => RubyLLM::ToolCall}, nil] RubyLLM tool calls
+      def build_ruby_llm_tool_calls(tool_calls)
+        return if tool_calls.nil? || tool_calls.empty?
+
+        tool_calls.to_h do |tc|
+          [tc.id, RubyLLM::ToolCall.new(id: tc.id, name: tc.name, arguments: tc.arguments)]
+        end
+      end
+
+      # Parse a RubyLLM response into an LLMResponse
+      # @param response [RubyLLM::Message] RubyLLM assistant message
+      # @param model [String] model name used
+      # @return [LLMResponse] structured response
       def parse_ruby_llm_response(response, model)
-        tool_calls = (response.tool_calls || []).map do |tc|
-          ToolCall.new(
-            id: tc.id,
-            name: tc.name,
-            arguments: tc.arguments
-          )
+        tool_calls = (response.tool_calls || {}).values.map do |tc|
+          ToolCall.new(id: tc.id, name: tc.name, arguments: tc.arguments)
         end
 
         LLMResponse.new(
           content: response.content,
           tool_calls: tool_calls,
           usage: Usage.new(
-            input_tokens: response.input_tokens || 0,
-            output_tokens: response.output_tokens || 0
+            input_tokens: response.tokens.input || 0,
+            output_tokens: response.tokens.output || 0,
+            cache_read: response.tokens.cache_read,
+            cache_write: response.tokens.cache_write
           ),
-          model: model
+          stop_reason: stop_reason(response),
+          model: model,
+          thinking: response.thinking&.text
         )
       end
+
+      # Map a RubyLLM finish reason to an LLMResponse stop reason
+      # @param response [RubyLLM::Message] RubyLLM assistant message
+      # @return [Symbol] :tool_use, :max_tokens or :end_turn
+      def stop_reason(response)
+        return :tool_use if response.tool_call?
+        return :max_tokens if response.max_tokens?
+
+        :end_turn
+      end
     end
   end
 end

data/lib/pocketrb/providers/types.rb

@@ -11,18 +11,31 @@ module Pocketrb
       :model,        # String - model that generated the response
       :thinking      # String|nil - extended thinking content (Claude)
     ) do
+      # Initialize LLM response
+      # @param content [String, nil] Text content of the response
+      # @param tool_calls [Array<ToolCall>] Tool calls requested by the model (defaults to empty)
+      # @param usage [Usage, nil] Token usage statistics
+      # @param stop_reason [Symbol] Reason for stopping (:end_turn, :tool_use, :max_tokens, :stop_sequence)
+      # @param model [String, nil] Model that generated the response
+      # @param thinking [String, nil] Extended thinking content (Claude)
       def initialize(content:, tool_calls: [], usage: nil, stop_reason: :end_turn, model: nil, thinking: nil)
         super
       end
 
+      # Check if response has tool calls
+      # @return [Boolean] True if tool calls are present
       def has_tool_calls?
         tool_calls && !tool_calls.empty?
       end
 
+      # Check if response has text content
+      # @return [Boolean] True if content is present
       def has_content?
         content && !content.empty?
       end
 
+      # Check if response has thinking content
+      # @return [Boolean] True if thinking is present
       def has_thinking?
         thinking && !thinking.empty?
       end
@@ -34,8 +47,12 @@ module Pocketrb
       :name,         # String - name of the tool to execute
       :arguments     # Hash - arguments to pass to the tool
     ) do
+      # Initialize tool call
+      # @param id [String] Unique identifier for this tool call
+      # @param name [String] Name of the tool to execute
+      # @param arguments [Hash, String] Arguments to pass to the tool (JSON string or hash)
       def initialize(id:, name:, arguments:)
-        args = arguments.is_a?(String) ? JSON.parse(arguments) : arguments
+        args = arguments.is_a?(String) ? JSON.parse(arguments, allow_duplicate_key: true) : arguments
         super(id: id, name: name, arguments: args)
       rescue JSON::ParserError
         super(id: id, name: name, arguments: {})
@@ -49,10 +66,17 @@ module Pocketrb
       :cache_read,     # Integer|nil - tokens read from cache
       :cache_write     # Integer|nil - tokens written to cache
     ) do
+      # Initialize token usage statistics
+      # @param input_tokens [Integer] Tokens in the input (defaults to 0)
+      # @param output_tokens [Integer] Tokens in the output (defaults to 0)
+      # @param cache_read [Integer, nil] Tokens read from cache
+      # @param cache_write [Integer, nil] Tokens written to cache
       def initialize(input_tokens: 0, output_tokens: 0, cache_read: nil, cache_write: nil)
         super
       end
 
+      # Calculate total tokens used
+      # @return [Integer] Sum of input and output tokens
       def total_tokens
         input_tokens + output_tokens
       end
@@ -60,9 +84,13 @@ module Pocketrb
 
     # Message role for conversation history
     module Role
+      # System message role
       SYSTEM = "system"
+      # User message role
       USER = "user"
+      # Assistant message role
       ASSISTANT = "assistant"
+      # Tool result message role
       TOOL = "tool"
     end
 
@@ -74,14 +102,27 @@ module Pocketrb
       :tool_call_id, # String|nil - for tool role, the tool call this responds to
       :tool_calls    # Array<ToolCall>|nil - for assistant role, tool calls made
     ) do
+      # Initialize message
+      # @param role [String] Message role (system, user, assistant, or tool)
+      # @param content [String, Array] Text content or content blocks
+      # @param name [String, nil] For tool role, the tool name
+      # @param tool_call_id [String, nil] For tool role, the tool call this responds to
+      # @param tool_calls [Array<ToolCall>, nil] For assistant role, tool calls made
       def initialize(role:, content:, name: nil, tool_call_id: nil, tool_calls: nil)
         super
       end
 
+      # Create a system message
+      # @param content [String] System message content
+      # @return [Message] New system message
       def self.system(content)
         new(role: Role::SYSTEM, content: content)
       end
 
+      # Create a user message
+      # @param content [String] User message content
+      # @param media [Array<Media>, nil] Media attachments (images, files)
+      # @return [Message] New user message
       def self.user(content, media: nil)
         if media && !media.empty?
           # Build content blocks array with text and images
@@ -99,10 +140,19 @@ module Pocketrb
         end
       end
 
+      # Create an assistant message
+      # @param content [String] Assistant message content
+      # @param tool_calls [Array<ToolCall>, nil] Tool calls made by the assistant
+      # @return [Message] New assistant message
       def self.assistant(content, tool_calls: nil)
         new(role: Role::ASSISTANT, content: content, tool_calls: tool_calls)
       end
 
+      # Create a tool result message
+      # @param tool_call_id [String] Tool call identifier this result responds to
+      # @param name [String] Name of the tool that was executed
+      # @param content [String] Tool execution result content
+      # @return [Message] New tool result message
       def self.tool_result(tool_call_id:, name:, content:)
         new(role: Role::TOOL, content: content, name: name, tool_call_id: tool_call_id)
       end

data/lib/pocketrb/session/manager.rb

@@ -3,11 +3,14 @@
 require "json"
 
 module Pocketrb
+  # Session management for conversation history
   module Session
     # Manages session persistence using JSONL files
     class Manager
       attr_reader :storage_dir
 
+      # Initialize session manager
+      # @param storage_dir [String, Pathname] Directory path for storing session JSONL files
       def initialize(storage_dir:)
         @storage_dir = Pathname.new(storage_dir)
         @sessions = {}
@@ -27,7 +30,7 @@ module Pocketrb
 
       # Get an existing session
       # @param key [String] Session key
-      # @return [Session|nil]
+      # @return [Session, nil]
       def get(key)
         @mutex.synchronize do
           @sessions[key] || load_session(key)
@@ -76,7 +79,8 @@ module Pocketrb
         end
       end
 
-      # Clear all sessions
+      # Clear all sessions from memory and disk
+      # @return [void]
       def clear_all!
         @mutex.synchronize do
           @sessions.clear
@@ -86,20 +90,31 @@ module Pocketrb
 
       private
 
+      # Ensure the storage directory exists
+      # @return [void]
       def ensure_storage_dir!
         FileUtils.mkdir_p(@storage_dir) unless @storage_dir.exist?
       end
 
+      # Build the JSONL file path for a session key
+      # @param key [String] session key
+      # @return [Pathname] sanitized session file path
       def session_file(key)
         # Sanitize key for filename
         safe_key = key.gsub(/[^a-zA-Z0-9_-]/, "_")
         @storage_dir.join("#{safe_key}.jsonl")
       end
 
+      # Load an existing session or create a new one
+      # @param key [String] session key
+      # @return [Session] loaded or newly created session
       def load_or_create(key)
         load_session(key) || Session.new(key: key)
       end
 
+      # Load a session from its JSONL file
+      # @param key [String] session key
+      # @return [Session, nil] loaded session or nil if file does not exist
       def load_session(key)
         file = session_file(key)
         return nil unless file.exist?
@@ -124,6 +139,9 @@ module Pocketrb
         Session.new(key: key)
       end
 
+      # Parse raw tool call hashes into ToolCall objects
+      # @param tool_calls [Array<Hash>, nil] raw tool call data
+      # @return [Array<Providers::ToolCall>, nil] parsed tool calls or nil
       def parse_tool_calls(tool_calls)
         return nil unless tool_calls
 
@@ -136,6 +154,9 @@ module Pocketrb
         end
       end
 
+      # Write all session messages to a JSONL file
+      # @param session [Session] conversation session whose messages will be written to JSONL
+      # @return [void]
       def persist_session(session)
         file = session_file(session.key)
         File.open(file, "w") do |f|
@@ -145,6 +166,9 @@ module Pocketrb
         end
       end
 
+      # Serialize a message to a JSON string
+      # @param message [Providers::Message] conversation turn to convert into a compact JSON line
+      # @return [String] JSON string
       def message_to_json(message)
         {
           role: message.role,
@@ -158,6 +182,8 @@ module Pocketrb
       end
 
       # Sanitize content to ensure valid UTF-8 for JSON encoding
+      # @param content [String, Array, nil] message content to sanitize
+      # @return [String, Array, nil] sanitized content
       def sanitize_content(content)
         return nil if content.nil?
 
@@ -171,6 +197,9 @@ module Pocketrb
         end
       end
 
+      # Sanitize a single content block's string values to valid UTF-8
+      # @param block [Hash] content block hash
+      # @return [Hash] sanitized content block
       def sanitize_content_block(block)
         return block unless block.is_a?(Hash)
 
@@ -183,6 +212,9 @@ module Pocketrb
         end
       end
 
+      # Delete the JSONL file for a session
+      # @param key [String] session key
+      # @return [void]
       def delete_session_file(key)
         file = session_file(key)
         File.delete(file) if file.exist?