pocketrb 0.1.0 → 0.3.0

data/lib/pocketrb/tools/send_file.rb

@@ -4,6 +4,7 @@ module Pocketrb
   module Tools
     # Tool for sending files/images to chat channels
     class SendFile < Base
+      # Allowed file extensions for sending
       ALLOWED_EXTENSIONS = %w[
         .jpg .jpeg .png .gif .webp .bmp
         .pdf .txt .md .json .csv .xml
@@ -12,14 +13,20 @@ module Pocketrb
         .zip .tar .gz
       ].freeze
 
+      # Tool name
+      # @return [String]
       def name
         "send_file"
       end
 
+      # Tool description
+      # @return [String]
       def description
         "Send a file (image, document, audio, video) to the user via chat. Use this to share generated content, screenshots, reports, or any files."
       end
 
+      # Parameter schema
+      # @return [Hash]
       def parameters
         {
           type: "object",
@@ -45,6 +52,12 @@ module Pocketrb
         }
       end
 
+      # Execute file sending
+      # @param path [String] File path to send
+      # @param caption [String, nil] Optional caption text
+      # @param channel [String, nil] Target channel name
+      # @param chat_id [String, nil] Target chat identifier
+      # @return [String] Success or error message
       def execute(path:, caption: nil, channel: nil, chat_id: nil)
         # Resolve path
         file_path = resolve_path(path)
@@ -84,22 +97,32 @@ module Pocketrb
         success("Sent #{File.basename(file_path)} to #{channel}")
       end
 
+      # Check if tool is available
+      # @return [Boolean] true if message bus is available
       def available?
         !bus.nil?
       end
 
       private
 
+      # Access the message bus from context
+      # @return [Object, nil]
       def bus
         @context[:bus]
       end
 
+      # Resolve a path, using workspace as base for relative paths
+      # @param path [String] file path to resolve
+      # @return [String] absolute file path
       def resolve_path(path)
         return path if Pathname.new(path).absolute?
 
         workspace.join(path).to_s
       end
 
+      # Create a media object from a file path
+      # @param path [String] path to the file
+      # @return [Bus::Media] media object for sending
       def create_media(path)
         ext = File.extname(path).downcase
         mime_type = detect_mime_type(ext)
@@ -114,6 +137,9 @@ module Pocketrb
         )
       end
 
+      # Detect media type from file extension
+      # @param ext [String] file extension (e.g. ".png")
+      # @return [Symbol] media type (:image, :audio, :video, or :file)
       def detect_type(ext)
         case ext
         when ".jpg", ".jpeg", ".png", ".gif", ".webp", ".bmp"
@@ -127,6 +153,9 @@ module Pocketrb
         end
       end
 
+      # Detect MIME type from file extension
+      # @param ext [String] file extension (e.g. ".png")
+      # @return [String] MIME type string
       def detect_mime_type(ext)
         {
           ".jpg" => "image/jpeg",

data/lib/pocketrb/tools/think.rb

@@ -4,14 +4,20 @@ module Pocketrb
   module Tools
     # Internal reasoning tool for complex problem solving
     class Think < Base
+      # Tool name
+      # @return [String]
       def name
         "think"
       end
 
+      # Tool description
+      # @return [String]
       def description
         "Use this tool to think through complex problems step by step. The content is not shown to the user but helps you reason through the task. Use it when you need to analyze information, plan an approach, or work through logic."
       end
 
+      # Parameter schema
+      # @return [Hash]
       def parameters
         {
           type: "object",
@@ -25,6 +31,9 @@ module Pocketrb
         }
       end
 
+      # Execute thinking process
+      # @param thought [String] Internal reasoning or analysis text
+      # @return [String] Confirmation message
       def execute(thought:)
         # The thought is logged but not displayed to the user
         Pocketrb.logger.debug("Agent thought: #{thought[0..200]}...")

data/lib/pocketrb/tools/web_fetch.rb

@@ -11,14 +11,20 @@ module Pocketrb
       MAX_CONTENT_SIZE = 500_000 # characters
       TIMEOUT = 30 # seconds
 
+      # Tool name
+      # @return [String]
       def name
         "web_fetch"
       end
 
+      # Tool description
+      # @return [String]
       def description
         "Fetch content from a URL. Returns the text content of the page. Use for reading documentation, articles, or other web content."
       end
 
+      # Parameter schema
+      # @return [Hash]
       def parameters
         {
           type: "object",
@@ -36,6 +42,10 @@ module Pocketrb
         }
       end
 
+      # Execute web content fetching
+      # @param url [String] URL to fetch content from
+      # @param selector [String, nil] CSS selector for extracting specific content
+      # @return [String] Extracted text content or error message
       def execute(url:, selector: nil)
         # Validate URL
         uri = parse_url(url)
@@ -54,6 +64,9 @@ module Pocketrb
 
       private
 
+      # Parse and validate a URL, adding https if no scheme is present
+      # @param url [String] URL string to parse
+      # @return [URI, nil] parsed URI or nil if invalid
       def parse_url(url)
         # Add https if no scheme
         url = "https://#{url}" unless url.match?(%r{^https?://})
@@ -66,6 +79,9 @@ module Pocketrb
         nil
       end
 
+      # Fetch content from a URI using Faraday
+      # @param uri [URI] parsed URI to fetch
+      # @return [Hash] response hash with :body/:content_type or :error
       def fetch_url(uri)
         conn = Faraday.new(url: uri.to_s) do |f|
           f.options.timeout = TIMEOUT
@@ -79,12 +95,35 @@ module Pocketrb
         response = conn.get
 
         if response.success?
-          { body: response.body, content_type: response.headers["content-type"] }
+          content_type = response.headers["content-type"]
+          { body: to_utf8(response.body.to_s, content_type), content_type: content_type }
         else
           { error: "HTTP #{response.status}" }
         end
       end
 
+      # Convert a raw response body to valid UTF-8
+      # @param body [String] raw response body
+      # @param content_type [String, nil] Content-Type header value
+      # @return [String] UTF-8 body with invalid bytes replaced
+      def to_utf8(body, content_type)
+        charset = content_type.to_s[/charset=["']?([^;"'\s]+)/i, 1]
+        encoding = begin
+          charset ? Encoding.find(charset) : Encoding::UTF_8
+        rescue ArgumentError
+          Encoding::UTF_8
+        end
+
+        body
+          .dup
+          .force_encoding(encoding)
+          .encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+      end
+
+      # Extract readable content from response body
+      # @param body [String] raw response body
+      # @param selector [String, nil] CSS selector to narrow extraction
+      # @return [String] extracted text content
       def extract_content(body, selector)
         content_type = detect_content_type(body)
 
@@ -98,6 +137,9 @@ module Pocketrb
         end
       end
 
+      # Detect content type by inspecting the body
+      # @param body [String] response body to analyze
+      # @return [Symbol] :json, :html, or :text
       def detect_content_type(body)
         return :json if body.strip.start_with?("{", "[")
         return :html if body.include?("<html") || body.include?("<body")
@@ -105,6 +147,10 @@ module Pocketrb
         :text
       end
 
+      # Convert HTML to plain text by stripping tags
+      # @param html [String] raw HTML content
+      # @param _selector [String, nil] CSS selector (unused, reserved for Nokogiri)
+      # @return [String] extracted plain text
       def extract_html_content(html, _selector)
         # Simple HTML to text conversion
         # A full implementation would use nokogiri
@@ -120,11 +166,14 @@ module Pocketrb
                .gsub("&lt;", "<")
                .gsub("&gt;", ">")
                .gsub("&quot;", '"')
-               .gsub(/&#\d+;/) do |m|
-                 [m[2..].to_i].pack("U")
+
+        text = text.gsub(/&#\d+;/) do |m|
+          [m[2..].to_i].pack("U")
         rescue StandardError
           m
         end
+
+        text = text
                .gsub(/\n{3,}/, "\n\n")
                .strip
 
@@ -132,6 +181,9 @@ module Pocketrb
         text.lines.map(&:strip).reject(&:empty?).join("\n")
       end
 
+      # Pretty-print JSON body
+      # @param body [String] raw JSON string
+      # @return [String] formatted JSON or original body on parse error
       def format_json(body)
         data = JSON.parse(body)
         JSON.pretty_generate(data)
@@ -139,6 +191,9 @@ module Pocketrb
         body
       end
 
+      # Truncate content exceeding the maximum size
+      # @param content [String] extracted page text that may exceed size limits
+      # @return [String] truncated or original content
       def truncate_content(content)
         return content if content.length <= MAX_CONTENT_SIZE
 

data/lib/pocketrb/tools/web_search.rb

@@ -7,16 +7,23 @@ module Pocketrb
   module Tools
     # Search the web using Brave Search API
     class WebSearch < Base
+      # Brave Search API endpoint URL
       BRAVE_API_URL = "https://api.search.brave.com/res/v1/web/search"
 
+      # Tool name
+      # @return [String]
       def name
         "web_search"
       end
 
+      # Tool description
+      # @return [String]
       def description
         "Search the web for information. Returns relevant search results with titles, URLs, and descriptions."
       end
 
+      # Parameter schema
+      # @return [Hash]
       def parameters
         {
           type: "object",
@@ -34,10 +41,16 @@ module Pocketrb
         }
       end
 
+      # Check if tool is available
+      # @return [Boolean] true if Brave API key is configured
       def available?
         api_key && !api_key.empty?
       end
 
+      # Execute web search
+      # @param query [String] Search query string
+      # @param count [Integer] Number of results to return (1-20)
+      # @return [String] Formatted search results
       def execute(query:, count: 5)
         return error("Web search requires BRAVE_API_KEY environment variable") unless api_key
 
@@ -60,10 +73,14 @@ module Pocketrb
 
       private
 
+      # Get the Brave Search API key from context or environment
+      # @return [String, nil]
       def api_key
         @context[:brave_api_key] || ENV.fetch("BRAVE_API_KEY", nil)
       end
 
+      # Build or access the Faraday HTTP client for Brave API
+      # @return [Faraday::Connection]
       def client
         @client ||= Faraday.new(url: BRAVE_API_URL) do |f|
           f.headers["Accept"] = "application/json"
@@ -72,6 +89,10 @@ module Pocketrb
         end
       end
 
+      # Format search response data into readable output
+      # @param data [Hash] parsed JSON response from Brave API
+      # @param query [String] original search query
+      # @return [String] formatted search results
       def format_results(data, query)
         results = data.dig("web", "results") || []
 
@@ -86,6 +107,10 @@ module Pocketrb
         output.join("\n")
       end
 
+      # Format a single search result entry
+      # @param result [Hash] search result with title, url, and description
+      # @param index [Integer] result number for display
+      # @return [String] formatted result entry
       def format_result(result, index)
         title = result["title"] || "Untitled"
         url = result["url"] || ""

data/lib/pocketrb/tools/write_file.rb

@@ -6,14 +6,20 @@ module Pocketrb
     class WriteFile < Base
       MAX_FILE_SIZE = 10 * 1024 * 1024 # 10MB
 
+      # Tool name
+      # @return [String]
       def name
         "write_file"
       end
 
+      # Tool description
+      # @return [String]
       def description
         "Write content to a file. Creates the file if it doesn't exist, or overwrites if it does. Creates parent directories as needed."
       end
 
+      # Parameter schema
+      # @return [Hash]
       def parameters
         {
           type: "object",
@@ -31,6 +37,10 @@ module Pocketrb
         }
       end
 
+      # Execute file write operation
+      # @param path [String] File path (relative or absolute)
+      # @param content [String] File content (text or binary data) to write to disk
+      # @return [String] Success or error message
       def execute(path:, content:)
         resolved = resolve_path(path)
 

data/lib/pocketrb/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module Pocketrb
-  VERSION = "0.1.0"
+  # Gem version number
+  VERSION = "0.3.0"
 end

data/lib/pocketrb.rb

@@ -6,7 +6,6 @@ require "json"
 require "yaml"
 require "logger"
 require "fileutils"
-require "pathname"
 
 # Pocketrb: Ruby AI agent with multi-LLM support and advanced planning capabilities
 module Pocketrb
@@ -28,6 +27,9 @@ module Pocketrb
   # Raised when MCP (Model Context Protocol) operations fail
   class MCPError < Error; end
 
+  # Raised when an optional gem needed by a feature is not installed
+  class MissingDependencyError < LoadError; end
+
   class << self
     attr_writer :logger
 
@@ -54,6 +56,7 @@ loader.inflector.inflect(
   "llm" => "LLM",
   "mcp" => "MCP",
   "openrouter" => "OpenRouter",
+  "openai_compatible" => "OpenAICompatible",
   "ruby_llm_provider" => "RubyLLMProvider",
   "claude_cli" => "ClaudeCLI",
   "claude_max_proxy" => "ClaudeMaxProxy",

data/pocketrb.gemspec

@@ -21,21 +21,19 @@ Gem::Specification.new do |spec|
     JSON-based memory with keyword matching.
   DESC
 
-  spec.required_ruby_version = ">= 3.2.0"
+  spec.required_ruby_version = ">= 4.0.0"
 
   # Runtime dependencies
-  spec.add_dependency "anthropic", "~> 0.3"
   spec.add_dependency "async", "~> 2.0"
   spec.add_dependency "faraday", "~> 2.0"
   spec.add_dependency "faraday-follow_redirects", "~> 0.3"
-  spec.add_dependency "json", "~> 2.7"
-  spec.add_dependency "pastel", "~> 0.8"
+  spec.add_dependency "fugit", "~> 1.11"
+  spec.add_dependency "json", ">= 2.7", "< 4"
   spec.add_dependency "playwright-ruby-client", "~> 1.58"
-  spec.add_dependency "ruby_llm", "~> 1.0"
+  spec.add_dependency "ruby_llm", "~> 2.0"
   spec.add_dependency "telegram-bot-ruby", "~> 2.0"
   spec.add_dependency "thor", "~> 1.3"
-  spec.add_dependency "tty-markdown", "~> 0.7"
-  spec.add_dependency "tty-prompt", "~> 0.23"
+  spec.add_dependency "tty-spinner", "~> 0.9"
   spec.add_dependency "yaml", "~> 0.3"
   spec.add_dependency "zeitwerk", "~> 2.6"
 
@@ -51,10 +49,10 @@ Gem::Specification.new do |spec|
     "changelog_uri" => "https://github.com/mensfeld/pocketrb/blob/master/CHANGELOG.md",
     "homepage_uri" => "https://github.com/mensfeld/pocketrb",
     "source_code_uri" => "https://github.com/mensfeld/pocketrb/tree/master",
+    "documentation_uri" => "https://github.com/mensfeld/pocketrb",
     "rubygems_mfa_required" => "true"
   }
 end
 
 # Optional dependencies (loaded on demand)
 # For WhatsApp bridge: gem install websocket-client-simple
-# For cron expressions: gem install fugit

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pocketrb
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Maciej Mensfeld
@@ -9,20 +9,6 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: anthropic
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.3'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.3'
 - !ruby/object:Gem::Dependency
   name: async
   requirement: !ruby/object:Gem::Requirement
@@ -66,33 +52,39 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0.3'
 - !ruby/object:Gem::Dependency
-  name: json
+  name: fugit
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.7'
+        version: '1.11'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.7'
+        version: '1.11'
 - !ruby/object:Gem::Dependency
-  name: pastel
+  name: json
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0.8'
+        version: '2.7'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.7'
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '0.8'
+        version: '4'
 - !ruby/object:Gem::Dependency
   name: playwright-ruby-client
   requirement: !ruby/object:Gem::Requirement
@@ -113,14 +105,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '2.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: telegram-bot-ruby
   requirement: !ruby/object:Gem::Requirement
@@ -150,33 +142,19 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1.3'
 - !ruby/object:Gem::Dependency
-  name: tty-markdown
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.7'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.7'
-- !ruby/object:Gem::Dependency
-  name: tty-prompt
+  name: tty-spinner
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.23'
+        version: '0.9'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.23'
+        version: '0.9'
 - !ruby/object:Gem::Dependency
   name: yaml
   requirement: !ruby/object:Gem::Requirement
@@ -261,6 +239,7 @@ files:
 - lib/pocketrb/providers/base.rb
 - lib/pocketrb/providers/claude_cli.rb
 - lib/pocketrb/providers/claude_max_proxy.rb
+- lib/pocketrb/providers/openai_compatible.rb
 - lib/pocketrb/providers/openrouter.rb
 - lib/pocketrb/providers/registry.rb
 - lib/pocketrb/providers/ruby_llm_provider.rb
@@ -306,6 +285,7 @@ metadata:
   changelog_uri: https://github.com/mensfeld/pocketrb/blob/master/CHANGELOG.md
   homepage_uri: https://github.com/mensfeld/pocketrb
   source_code_uri: https://github.com/mensfeld/pocketrb/tree/master
+  documentation_uri: https://github.com/mensfeld/pocketrb
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -314,14 +294,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.0
+      version: 4.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.0.beta2
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Pocket-sized Ruby AI agent framework with multi-LLM support
 test_files: []