pocketrb 0.1.0 → 0.3.0

data/lib/pocketrb/mcp/memory_tool.rb

@@ -4,19 +4,27 @@ module Pocketrb
   module MCP
     # Tool for interacting with memory via MCP
     class MemoryTool < Tools::Base
+      # Initialize memory tool
+      # @param context [Hash] Context hash containing :mcp_client (defaults to empty hash)
       def initialize(context = {})
         super
         @client = context[:mcp_client] || Client.new
       end
 
+      # Tool name
+      # @return [String] Tool identifier
       def name
         "memory"
       end
 
+      # Tool description
+      # @return [String] Human-readable description
       def description
         "Interact with long-term memory. Search for relevant information or store new knowledge for future reference."
       end
 
+      # Tool parameters schema
+      # @return [Hash] JSON schema
       def parameters
         {
           type: "object",
@@ -48,12 +56,21 @@ module Pocketrb
         }
       end
 
+      # Check if MCP client is available
+      # @return [Boolean] True if client can connect
       def available?
         @client.connected? || @client.connect
       rescue StandardError
         false
       end
 
+      # Execute memory operation
+      # @param action [String] Action to perform ("search" or "store")
+      # @param query [String, nil] Search query (for search action)
+      # @param content [String, nil] Content to store (for store action)
+      # @param tags [Array<String>, nil] Tags to associate with content (for store action)
+      # @param limit [Integer] Maximum search results (defaults to 5)
+      # @return [String] JSON result of operation
       def execute(action:, query: nil, content: nil, tags: nil, limit: 5)
         case action
         when "search"
@@ -67,6 +84,10 @@ module Pocketrb
 
       private
 
+      # Execute a memory search operation
+      # @param query [String] search query
+      # @param limit [Integer] maximum number of results
+      # @return [String] formatted search results or error message
       def execute_search(query, limit)
         return error("Query is required for search") if query.nil? || query.empty?
 
@@ -79,6 +100,10 @@ module Pocketrb
         error("Memory search failed: #{e.message}")
       end
 
+      # Execute a memory store operation
+      # @param content [String] text or fact to persist in the memory backend
+      # @param tags [Array<String>, nil] tags to associate with content
+      # @return [String] success or error message
       def execute_store(content, tags)
         return error("Content is required for store") if content.nil? || content.empty?
 
@@ -98,6 +123,10 @@ module Pocketrb
         error("Memory store failed: #{e.message}")
       end
 
+      # Format search results into a readable string
+      # @param results [String, Array, Hash] raw search results from MCP
+      # @param query [String] original search query
+      # @return [String] formatted results
       def format_search_results(results, query)
         output = ["Memory search results for: #{query}\n"]
 
@@ -117,6 +146,10 @@ module Pocketrb
         output.join("\n")
       end
 
+      # Format a single search result entry
+      # @param result [Hash] result hash with content, score, and tags
+      # @param index [Integer] display index (1-based)
+      # @return [String] formatted result line
       def format_result(result, index)
         content = result["content"] || result["text"] || result.to_s
         score = result["score"]

data/lib/pocketrb/media/processor.rb

@@ -5,6 +5,7 @@ require "fileutils"
 require "tmpdir"
 
 module Pocketrb
+  # Media processing for images, files, and attachments
   module Media
     # Handles media processing: downloading, encoding, type detection
     class Processor
@@ -31,13 +32,16 @@ module Pocketrb
 
       attr_reader :cache_dir
 
+      # Initialize media processor
+      # @param cache_dir [String, Pathname, nil] Directory path for caching downloaded media (defaults to system temp
+      #   dir)
       def initialize(cache_dir: nil)
         @cache_dir = cache_dir || default_cache_dir
         ensure_cache_dir!
       end
 
       # Download media from URL and return Media object
-      # @param url [String] URL to download
+      # @param url [String] HTTP/HTTPS URL pointing to the media resource to fetch
       # @param filename [String, nil] Original filename
       # @param mime_type [String, nil] Known MIME type
       # @return [Bus::Media]
@@ -169,20 +173,30 @@ module Pocketrb
 
       private
 
+      # Default cache directory in system temp dir
+      # @return [Pathname] default cache directory path
       def default_cache_dir
         Pathname.new(Dir.tmpdir).join("pocketrb-media")
       end
 
+      # Ensure the cache directory exists
+      # @return [void]
       def ensure_cache_dir!
         FileUtils.mkdir_p(@cache_dir)
       end
 
+      # Build a timestamped cache file path for a given filename
+      # @param filename [String] original filename to sanitize and store
+      # @return [Pathname] full path to cached file
       def cache_file_path(filename)
         # Sanitize filename and add timestamp to avoid conflicts
         safe_name = filename.gsub(/[^a-zA-Z0-9._-]/, "_")
         @cache_dir.join("#{Time.now.to_i}_#{safe_name}")
       end
 
+      # Detect media type category from MIME type
+      # @param mime_type [String] MIME type string
+      # @return [Symbol] media type (:image, :audio, :video, or :file)
       def detect_type(mime_type)
         case mime_type
         when %r{^image/}
@@ -196,11 +210,18 @@ module Pocketrb
         end
       end
 
+      # Detect MIME type from file extension
+      # @param path [String] file path
+      # @return [String] MIME type string
       def detect_mime_type(path)
         ext = File.extname(path).downcase
         MIME_TYPES[ext] || "application/octet-stream"
       end
 
+      # Base64-encode content if it is a small vision-compatible image
+      # @param content [String] binary content
+      # @param mime_type [String] MIME type of the content
+      # @return [String, nil] base64 string or nil if too large or not an image
       def encode_if_small(content, mime_type)
         return nil if content.bytesize > MAX_INLINE_SIZE
         return nil unless VISION_IMAGE_TYPES.include?(mime_type)
@@ -208,6 +229,10 @@ module Pocketrb
         Base64.strict_encode64(content)
       end
 
+      # Extract or generate a filename from a URL
+      # @param url [String] source URL
+      # @param content_type [String] MIME type for extension fallback
+      # @return [String] extracted or generated filename
       def extract_filename(url, content_type)
         # Try to get filename from URL
         uri_path = begin
@@ -225,10 +250,14 @@ module Pocketrb
         name
       end
 
+      # Get file extension for a MIME type
+      # @param mime_type [String] MIME type string
+      # @return [String] file extension without dot
       def extension_for(mime_type)
         EXTENSIONS[mime_type] || "bin"
       end
 
+      # Mapping of file extensions to MIME types
       MIME_TYPES = {
         ".jpg" => "image/jpeg",
         ".jpeg" => "image/jpeg",
@@ -246,6 +275,7 @@ module Pocketrb
         ".json" => "application/json"
       }.freeze
 
+      # Mapping of MIME types to file extensions
       EXTENSIONS = MIME_TYPES.invert.merge(
         "image/jpeg" => "jpg",
         "audio/mpeg" => "mp3",
@@ -253,6 +283,7 @@ module Pocketrb
       ).freeze
     end
 
+    # Error raised when media processing fails
     class MediaError < Pocketrb::Error; end
   end
 end

data/lib/pocketrb/memory.rb

@@ -4,8 +4,7 @@ require "json"
 require "fileutils"
 
 module Pocketrb
-  # Simple memory system for facts and recent events
-  # Inspired by nanobot - no vector DB, just JSON + keyword matching
+  # Simple memory system for facts and recent events. Inspired by nanobot - no vector DB, just JSON + keyword matching
   class Memory
     # Maximum number of recent events to keep
     MAX_RECENT = 50
@@ -241,6 +240,7 @@ module Pocketrb
     end
 
     # Get memory statistics
+    # @return [Hash] counts of learned topics, facts, preferences, and events
     def stats
       {
         learned_topics: @facts["learned"].keys.size,
@@ -252,7 +252,8 @@ module Pocketrb
       }
     end
 
-    # Dump all memories (for debugging)
+    # Dump all memories for debugging
+    # @return [Hash] all facts and recent events
     def dump_all
       {
         "facts" => @facts,
@@ -262,6 +263,10 @@ module Pocketrb
 
     private
 
+    # Load and parse a JSON file
+    # @param path [Pathname] path to JSON file
+    # @return [Hash, Array, nil] parsed JSON data or nil if file does not exist
+    # @raise [Pocketrb::ConfigurationError] if JSON is invalid
     def load_json(path)
       return nil unless path.exist? # Missing file OK (first run)
 
@@ -272,10 +277,14 @@ module Pocketrb
             "Invalid JSON in #{path}: #{e.message}\nContent preview: #{content[0..100]}"
     end
 
+    # Persist facts to disk
+    # @return [void]
     def save_facts
       @facts_file.write(JSON.pretty_generate(@facts))
     end
 
+    # Persist recent events to disk
+    # @return [void]
     def save_recent
       @recent_file.write(JSON.pretty_generate(@recent))
     end

data/lib/pocketrb/planning/manager.rb

@@ -3,11 +3,14 @@
 require "json"
 
 module Pocketrb
+  # Planning system with step-by-step execution plans
   module Planning
     # Manages plans persistence and lifecycle
     class Manager
       attr_reader :workspace
 
+      # Initialize planning manager
+      # @param workspace [String, Pathname] Workspace directory path for storing plans
       def initialize(workspace:)
         @workspace = Pathname.new(workspace)
         @plans_dir = @workspace.join(".pocketrb", "plans")
@@ -36,7 +39,7 @@ module Pocketrb
 
       # Get a plan by name
       # @param name [String] Plan name
-      # @return [Plan|nil]
+      # @return [Plan, nil]
       def get_plan(name)
         @plans_cache[name] ||= load_plan(name)
       end
@@ -62,6 +65,10 @@ module Pocketrb
       end
 
       # Fail a step in a plan
+      # @param name [String] Plan name
+      # @param step_index [Integer] Index of step to mark as failed
+      # @param notes [String, nil] Optional failure notes
+      # @return [Plan] Updated plan
       def fail_step(name:, step_index:, notes: nil)
         plan = get_plan(name)
         raise Error, "Plan '#{name}' not found" unless plan
@@ -72,6 +79,8 @@ module Pocketrb
       end
 
       # Activate a plan
+      # @param name [String] Plan name to activate
+      # @return [Plan] Activated plan
       def activate_plan(name)
         plan = get_plan(name)
         raise Error, "Plan '#{name}' not found" unless plan
@@ -82,6 +91,8 @@ module Pocketrb
       end
 
       # Mark a plan as complete
+      # @param name [String] Plan name to mark complete
+      # @return [Plan] Completed plan
       def mark_complete(name)
         plan = get_plan(name)
         raise Error, "Plan '#{name}' not found" unless plan
@@ -92,6 +103,8 @@ module Pocketrb
       end
 
       # Cancel a plan
+      # @param name [String] Plan name to cancel
+      # @return [Plan] Cancelled plan
       def cancel_plan(name)
         plan = get_plan(name)
         raise Error, "Plan '#{name}' not found" unless plan
@@ -102,6 +115,8 @@ module Pocketrb
       end
 
       # Delete a plan
+      # @param name [String] Plan name to delete
+      # @return [void]
       def delete_plan(name)
         file = plan_file(name)
         File.delete(file) if file.exist?
@@ -124,26 +139,39 @@ module Pocketrb
       end
 
       # Check if a plan exists
+      # @param name [String] Plan name to check
+      # @return [Boolean] true if plan exists
       def exists?(name)
         plan_file(name).exist?
       end
 
       private
 
+      # Ensure the plans directory exists
+      # @return [void]
       def ensure_plans_dir!
         FileUtils.mkdir_p(@plans_dir) unless @plans_dir.exist?
       end
 
+      # Build the file path for a plan by name
+      # @param name [String] plan name
+      # @return [Pathname] sanitized path to the plan JSON file
       def plan_file(name)
         safe_name = name.gsub(/[^a-zA-Z0-9_-]/, "_")
         @plans_dir.join("#{safe_name}.json")
       end
 
+      # Persist a plan to its JSON file
+      # @param plan [Plan] structured plan with steps to write as JSON
+      # @return [void]
       def save_plan(plan)
         file = plan_file(plan.name)
         File.write(file, JSON.pretty_generate(plan.to_h))
       end
 
+      # Load a plan from its JSON file
+      # @param name [String] plan name
+      # @return [Plan, nil] loaded plan or nil if not found
       def load_plan(name)
         file = plan_file(name)
         return nil unless file.exist?

data/lib/pocketrb/planning/plan.rb

@@ -9,39 +9,64 @@ module Pocketrb
 
       # Step statuses
       module StepStatus
+        # Step is waiting to be started
         PENDING = "pending"
+        # Step is currently being executed
         IN_PROGRESS = "in_progress"
+        # Step was completed successfully
         COMPLETED = "completed"
+        # Step execution failed
         FAILED = "failed"
+        # Step was skipped
         SKIPPED = "skipped"
       end
 
       # Plan statuses
       module PlanStatus
+        # Plan is being drafted
         DRAFT = "draft"
+        # Plan is actively being executed
         ACTIVE = "active"
+        # Plan completed successfully
         COMPLETED = "completed"
+        # Plan execution failed
         FAILED = "failed"
+        # Plan was cancelled
         CANCELLED = "cancelled"
       end
 
+      # Plan step data structure
       Step = Data.define(:index, :description, :status, :notes, :completed_at) do
+        # Initialize plan step
+        # @param index [Integer] Step position in the plan (zero-based)
+        # @param description [String] Step description or task to complete
+        # @param status [String] Step status (defaults to PENDING)
+        # @param notes [String, nil] Additional notes or execution details
+        # @param completed_at [Time, nil] Timestamp when step was completed
         def initialize(index:, description:, status: StepStatus::PENDING, notes: nil, completed_at: nil)
           super
         end
 
+        # Check if step is pending
+        # @return [Boolean] True if status is PENDING
         def pending?
           status == StepStatus::PENDING
         end
 
+        # Check if step is completed
+        # @return [Boolean] True if status is COMPLETED
         def completed?
           status == StepStatus::COMPLETED
         end
 
+        # Check if step failed
+        # @return [Boolean] True if status is FAILED
         def failed?
           status == StepStatus::FAILED
         end
 
+        # Convert step to hash
+        # @return [Hash] Step data as hash
         def to_h
           {
             index: index,
@@ -53,6 +78,12 @@ module Pocketrb
         end
       end
 
+      # Initialize plan
+      # @param name [String] Plan name
+      # @param description [String, nil] Plan description or goal
+      # @param steps [Array<Step, String>] Array of steps (Step objects or strings)
+      # @param status [String] Plan status (defaults to DRAFT)
+      # @param metadata [Hash] Additional metadata (defaults to empty hash)
       def initialize(name:, description: nil, steps: [], status: PlanStatus::DRAFT, metadata: {})
         @name = name
         @description = description
@@ -65,6 +96,8 @@ module Pocketrb
       end
 
       # Add a step to the plan
+      # @param description [String] Step description
+      # @return [Step] New step instance
       def add_step(description)
         step = Step.new(index: @steps.length, description: description)
         @steps << step
@@ -72,11 +105,17 @@ module Pocketrb
       end
 
       # Add multiple steps
+      # @param descriptions [Array<String>] Array of step descriptions
+      # @return [void]
       def add_steps(descriptions)
         descriptions.each { |d| add_step(d) }
       end
 
       # Update a step's status
+      # @param index [Integer] Step index
+      # @param status [String] New status value
+      # @param notes [String, nil] Optional notes to add
+      # @return [Step, nil] Updated step or nil if index invalid
       def update_step(index, status:, notes: nil)
         return nil unless @steps[index]
 
@@ -94,16 +133,25 @@ module Pocketrb
       end
 
       # Mark a step as completed
+      # @param index [Integer] Step index
+      # @param notes [String, nil] Optional completion notes
+      # @return [Step, nil] Updated step or nil if index invalid
       def complete_step(index, notes: nil)
         update_step(index, status: StepStatus::COMPLETED, notes: notes)
       end
 
       # Mark a step as failed
+      # @param index [Integer] Step index
+      # @param notes [String, nil] Optional failure notes
+      # @return [Step, nil] Updated step or nil if index invalid
       def fail_step(index, notes: nil)
         update_step(index, status: StepStatus::FAILED, notes: notes)
       end
 
       # Skip a step
+      # @param index [Integer] Step index
+      # @param notes [String, nil] Optional skip reason notes
+      # @return [Step, nil] Updated step or nil if index invalid
       def skip_step(index, notes: nil)
         update_step(index, status: StepStatus::SKIPPED, notes: notes)
       end
@@ -119,11 +167,13 @@ module Pocketrb
       end
 
       # Check if plan is complete
+      # @return [Boolean] true if all steps are completed
       def complete?
         @steps.all?(&:completed?)
       end
 
       # Check if plan has failed
+      # @return [Boolean] true if any step has failed
       def failed?
         @steps.any?(&:failed?)
       end
@@ -193,6 +243,8 @@ module Pocketrb
       end
 
       # Create from hash
+      # @param hash [Hash] Hash containing plan data
+      # @return [Plan] New plan instance
       def self.from_h(hash)
         steps = (hash[:steps] || hash["steps"] || []).map do |s|
           Step.new(

data/lib/pocketrb/planning/tool.rb

@@ -4,14 +4,20 @@ module Pocketrb
   module Planning
     # Tool for creating and managing execution plans
     class Tool < Tools::Base
+      # Tool name
+      # @return [String] Tool identifier
       def name
         "plan"
       end
 
+      # Tool description
+      # @return [String] Human-readable description
       def description
         "Create and manage execution plans for complex tasks. Plans help organize multi-step work and track progress."
       end
 
+      # Tool parameters schema
+      # @return [Hash] JSON schema
       def parameters
         {
           type: "object",
@@ -47,6 +53,14 @@ module Pocketrb
         }
       end
 
+      # Execute planning operation
+      # @param action [String] Action to perform (create, update, complete, fail, list, show)
+      # @param plan_name [String, nil] Plan name
+      # @param plan_description [String, nil] Plan description (for create action)
+      # @param steps [Array<String>, nil] Step descriptions (for create/update actions)
+      # @param step_index [Integer, nil] Step index (for complete/fail actions)
+      # @param notes [String, nil] Notes for step completion/failure
+      # @return [String] JSON result of operation
       def execute(
         action:,
         plan_name: nil,
@@ -77,10 +91,17 @@ module Pocketrb
 
       private
 
+      # Planning manager instance
+      # @return [Manager] lazily initialized manager
       def manager
         @manager ||= Manager.new(workspace: workspace)
       end
 
+      # Create and activate a new plan
+      # @param name [String] plan name
+      # @param description [String, nil] plan description
+      # @param steps [Array<String>] step descriptions
+      # @return [String] success or error message
       def create_plan(name, description, steps)
         return error("Plan name is required") unless name
         return error("At least one step is required") if steps.nil? || steps.empty?
@@ -94,6 +115,12 @@ module Pocketrb
         error(e.message)
       end
 
+      # Update an existing plan with new steps or step completion
+      # @param name [String] plan name
+      # @param new_steps [Array<String>, nil] steps to add
+      # @param step_index [Integer, nil] step index to mark complete
+      # @param notes [String, nil] notes for step completion
+      # @return [String] success or error message
       def update_plan(name, new_steps, step_index, notes)
         return error("Plan name is required") unless name
 
@@ -109,6 +136,11 @@ module Pocketrb
         error(e.message)
       end
 
+      # Mark a step as complete in a plan
+      # @param name [String] plan name
+      # @param step_index [Integer] step index to complete
+      # @param notes [String, nil] completion notes
+      # @return [String] success or error message
       def complete_step(name, step_index, notes)
         return error("Plan name is required") unless name
         return error("Step index is required") if step_index.nil?
@@ -125,6 +157,11 @@ module Pocketrb
         error(e.message)
       end
 
+      # Mark a step as failed in a plan
+      # @param name [String] plan name
+      # @param step_index [Integer] step index to fail
+      # @param notes [String, nil] failure notes
+      # @return [String] success or error message
       def fail_step(name, step_index, notes)
         return error("Plan name is required") unless name
         return error("Step index is required") if step_index.nil?
@@ -135,6 +172,8 @@ module Pocketrb
         error(e.message)
       end
 
+      # List all plans with their status
+      # @return [String] formatted plan listing
       def list_plans
         plans = manager.list_plans
 
@@ -156,6 +195,9 @@ module Pocketrb
         output.join("\n")
       end
 
+      # Show a plan's details in markdown format
+      # @param name [String] plan name
+      # @return [String] plan markdown or error message
       def show_plan(name)
         return error("Plan name is required") unless name
 
@@ -165,6 +207,9 @@ module Pocketrb
         plan.to_markdown
       end
 
+      # Delete a plan by name
+      # @param name [String] plan name
+      # @return [String] success or error message
       def delete_plan(name)
         return error("Plan name is required") unless name