shared_tools 0.2.3 → 0.3.0

data/lib/shared_tools/tools/disk/file_create_tool.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "local_driver"
+
+module SharedTools
+  module Tools
+    module Disk
+      # @example
+      #   tool = SharedTools::Tools::Disk::FileCreateTool.new(root: "./project")
+      #   tool.execute(path: "./README.md")
+      class FileCreateTool < ::RubyLLM::Tool
+        def self.name = 'disk_file_create'
+
+        description "Creates a file."
+
+        params do
+          string :path, description: "a path to the file (e.g. `./README.md`)"
+        end
+
+        def initialize(driver: nil, logger: nil)
+          @driver = driver || SharedTools::Tools::Disk::LocalDriver.new(root: Dir.pwd)
+          @logger = logger || RubyLLM.logger
+        end
+
+        # @param path [String]
+        #
+        # @return [String]
+        def execute(path:)
+          @logger.info("#{self.class.name}#execute path=#{path.inspect}")
+          @driver.file_create(path:)
+        rescue SecurityError => e
+          @logger.error(e.message)
+          raise e
+        end
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/disk/file_delete_tool.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "local_driver"
+
+module SharedTools
+  module Tools
+    module Disk
+      # @example
+      #   tool = SharedTools::Tools::Disk::FileDeleteTool.new(root: "./project")
+      #   tool.execute(path: "./README.md")
+      class FileDeleteTool < ::RubyLLM::Tool
+        def self.name = 'disk_file_delete'
+
+        description "Deletes a file."
+
+        params do
+          string :path, description: "a path to the file (e.g. `./README.md`)"
+        end
+
+        def initialize(driver: nil, logger: nil)
+          @driver = driver || SharedTools::Tools::Disk::LocalDriver.new(root: Dir.pwd)
+          @logger = logger || RubyLLM.logger
+        end
+
+        # @param path [String]
+        #
+        # @raise [SecurityError]
+        #
+        # @return [String]
+        def execute(path:)
+          @logger.info("#{self.class.name}#execute path=#{path.inspect}")
+          @driver.file_delete(path:)
+        rescue SecurityError => e
+          @logger.error(e.message)
+          raise e
+        end
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/disk/file_move_tool.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "local_driver"
+
+module SharedTools
+  module Tools
+    module Disk
+      # @example
+      #   tool = SharedTools::Tools::Disk::FileMoveTool.new(root: "./project")
+      #   tool.execute(
+      #     path: "./README.txt",
+      #     destination: "./README.md",
+      #   )
+      class FileMoveTool < ::RubyLLM::Tool
+        def self.name = 'disk_file_move'
+
+        description "Moves a file."
+
+        params do
+          string :path, description: "a path (e.g. `./old.rb`)"
+          string :destination, description: "a path (e.g. `./new.rb`)"
+        end
+
+        def initialize(driver: nil, logger: nil)
+          @driver = driver || SharedTools::Tools::Disk::LocalDriver.new(root: Dir.pwd)
+          @logger = logger || RubyLLM.logger
+        end
+
+        # @param path [String]
+        # @param destination [String]
+        #
+        # @return [String]
+        def execute(path:, destination:)
+          @logger.info("#{self.class.name}#execute path=#{path.inspect} destination=#{destination.inspect}")
+          @driver.file_move(path:, destination:)
+        rescue SecurityError => e
+          @logger.info("ERROR: #{e.message}")
+          raise e
+        end
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/disk/file_read_tool.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "local_driver"
+
+module SharedTools
+  module Tools
+    module Disk
+      # @example
+      #   tool = SharedTools::Tools::Disk::FileReadTool.new
+      #   tool.execute(path: "./README.md") # => "..."
+      class FileReadTool < ::RubyLLM::Tool
+        def self.name = 'disk_file_read'
+
+        description "Reads the contents of a file."
+
+        params do
+          string :path, description: "a path (e.g. `./main.rb`)"
+        end
+
+        # @param driver [SharedTools::Tools::Disk::BaseDriver] optional, defaults to LocalDriver with current directory
+        # @param logger [Logger] optional logger
+        def initialize(driver: nil, logger: nil)
+          @driver = driver || SharedTools::Tools::Disk::LocalDriver.new(root: Dir.pwd)
+          @logger = logger || RubyLLM.logger
+        end
+
+        # @param path [String]
+        #
+        # @return [String]
+        def execute(path:)
+          @logger.info("#{self.class.name}#execute path=#{path}")
+          @driver.file_read(path:)
+        rescue StandardError => e
+          @logger.error(e.message)
+          raise e
+        end
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/disk/file_replace_tool.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "local_driver"
+
+module SharedTools
+  module Tools
+    module Disk
+      # @example
+      #   tool = SharedTools::Tools::Disk::FileReadTool.new(root: "./project")
+      #   tool.execute(
+      #     old_text: 'puts "ABC"',
+      #     new_text: 'puts "DEF"',
+      #     path: "README.md"
+      #   )
+      class FileReplaceTool < ::RubyLLM::Tool
+        def self.name = 'disk_file_replace'
+
+        description "Replaces a specific string in a file (old_text => new_text)."
+
+        params do
+          string :old_text, description: "the old text (e.g. `puts 'ABC'`)"
+          string :new_text, description: "the new text (e.g. `puts 'DEF'`)"
+          string :path, description: "a path (e.g. `./main.rb`)"
+        end
+
+        def initialize(driver: nil, logger: nil)
+          @driver = driver || SharedTools::Tools::Disk::LocalDriver.new(root: Dir.pwd)
+          @logger = logger || RubyLLM.logger
+        end
+
+        # @param path [String]
+        # @param old_text [String]
+        # @param new_text [String]
+        def execute(old_text:, new_text:, path:)
+          @logger.info %(#{self.class.name}#execute old_text="#{old_text}" new_text="#{new_text}" path="#{path}")
+          @driver.file_replace(old_text:, new_text:, path:)
+        rescue SecurityError => e
+          @logger.error(e.message)
+          raise e
+        end
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/disk/file_write_tool.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "local_driver"
+
+module SharedTools
+  module Tools
+    module Disk
+      # @example
+      #    tool = SharedTools::Tools::Disk::FileWriteTool.new(root: "./project")
+      #    tool.execute(path: "./README.md", text: "Hello World")
+      class FileWriteTool < ::RubyLLM::Tool
+        def self.name = 'disk_file_write'
+
+        description "Writes the contents of a file."
+
+        params do
+          string :path, description: "a path for the file (e.g. `./main.rb`)"
+          string :text, description: "the text to write to the file (e.g. `puts 'Hello World'`)"
+        end
+
+        def initialize(driver: nil, logger: nil)
+          @driver = driver || SharedTools::Tools::Disk::LocalDriver.new(root: Dir.pwd)
+          @logger = logger || RubyLLM.logger
+        end
+
+        # @param path [String]
+        # @param text [String]
+        #
+        # @return [String]
+        def execute(path:, text:)
+          @logger.info("#{self.class.name}#execute path=#{path}")
+          @driver.file_write(path:, text:)
+        rescue SecurityError => e
+          @logger.error("ERROR: #{e.message}")
+          raise e
+        end
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/disk/local_driver.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require_relative "base_driver"
+
+module SharedTools
+  module Tools
+    module Disk
+      # A driver for interacting with a disk via various operations
+      class LocalDriver < BaseDriver
+        # @raise [SecurityError]
+        #
+        # @param path [String]
+        def directory_create(path:)
+          FileUtils.mkdir_p(resolve!(path:))
+        end
+
+        # @param path [String]
+        def directory_delete(path:)
+          FileUtils.rmdir(resolve!(path:))
+        end
+
+        # @param path [String] optional
+        def directory_list(path: ".")
+          Dir.chdir(resolve!(path:)) do
+            Dir.glob("**/*").map { |path| summarize(path:) }.join("\n")
+          end
+        end
+
+        # @param path [String]
+        # @param destination [String]
+        def directory_move(path:, destination:)
+          FileUtils.mv(resolve!(path:), resolve!(path: destination))
+        end
+
+        # @param path [String]
+        def file_create(path:)
+          path = resolve!(path:)
+          FileUtils.touch(path) unless File.exist?(path)
+        end
+
+        # @param path [String]
+        def file_delete(path:)
+          File.delete(resolve!(path:))
+        end
+
+        # @param path [String]
+        # @param destination [String]
+        def file_move(path:, destination:)
+          FileUtils.mv(resolve!(path:), resolve!(path: destination))
+        end
+
+        # @param path [String]
+        #
+        # @return [String]
+        def file_read(path:)
+          File.read(resolve!(path:))
+        end
+
+        # @param old_text [String]
+        # @param new_text [String]
+        # @param path [String]
+        def file_replace(old_text:, new_text:, path:)
+          path = resolve!(path:)
+          contents = File.read(path)
+          text = contents.gsub(old_text, new_text)
+          File.write(path, text)
+        end
+
+        # @param path [String]
+        # @param text [String]
+        def file_write(path:, text:)
+          File.write(resolve!(path:), text)
+        end
+
+      protected
+
+        # @param path [String]
+        #
+        # @raise [SecurityError]
+        #
+        # @return Pathname
+        def resolve!(path:)
+          @root.join(path).tap do |resolved|
+            relative = resolved.ascend.any? { |ancestor| ancestor.eql?(@root) }
+            raise SecurityError, "unknown path=#{resolved}" unless relative
+          end
+        end
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/disk.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# Collection loader for all disk tools
+# Usage: require 'shared_tools/tools/disk'
+
+require 'shared_tools'
+
+require_relative 'disk/file_read_tool'
+require_relative 'disk/file_write_tool'
+require_relative 'disk/file_create_tool'
+require_relative 'disk/file_delete_tool'
+require_relative 'disk/file_move_tool'
+require_relative 'disk/file_replace_tool'
+require_relative 'disk/directory_list_tool'
+require_relative 'disk/directory_create_tool'
+require_relative 'disk/directory_delete_tool'
+require_relative 'disk/directory_move_tool'

data/lib/shared_tools/tools/disk_tool.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require_relative '../../shared_tools'
+
+module SharedTools
+  module Tools
+    # A tool for interacting with files and directories. Be careful using as it can perform actions on your computer!
+    #
+    # @example
+    #   disk = SharedTools::Tools::DiskTool.new
+    #   disk.execute(action: SharedTools::Tools::DiskTool::Action::FILE_CREATE, path: "./demo.rb")
+    #   disk.execute(action: SharedTools::Tools::DiskTool::Action::FILE_WRITE, path: "./demo.rb", text: "puts 'Hello'")
+    #   disk.execute(action: SharedTools::Tools::DiskTool::Action::FILE_READ, path: "./demo.rb")
+    #   disk.execute(action: SharedTools::Tools::DiskTool::Action::FILE_DELETE, path: "./demo.rb")
+    class DiskTool < ::RubyLLM::Tool
+      def self.name = 'disk_tool' 
+      description <<~TEXT
+        A tool for interacting with a system. It is able to list, create, delete, move and modify directories and files.
+      TEXT
+
+      module Action
+        DIRECTORY_CREATE = "directory_create"
+        DIRECTORY_DELETE = "directory_delete"
+        DIRECTORY_MOVE = "directory_move"
+        DIRECTORY_LIST = "directory_list"
+        FILE_CREATE = "file_create"
+        FILE_DELETE = "file_delete"
+        FILE_MOVE = "file_move"
+        FILE_READ = "file_read"
+        FILE_WRITE = "file_write"
+        FILE_REPLACE = "file_replace"
+      end
+
+      ACTIONS = [
+        Action::DIRECTORY_CREATE,
+        Action::DIRECTORY_DELETE,
+        Action::DIRECTORY_MOVE,
+        Action::DIRECTORY_LIST,
+        Action::FILE_CREATE,
+        Action::FILE_DELETE,
+        Action::FILE_MOVE,
+        Action::FILE_READ,
+        Action::FILE_WRITE,
+        Action::FILE_REPLACE,
+      ].freeze
+
+      params do
+        string :action, description: <<~TEXT.strip
+          Options:
+          * `#{Action::DIRECTORY_CREATE}`: creates a directory at a specific `path`
+          * `#{Action::DIRECTORY_DELETE}`: deletes a directory at a specific `path`
+          * `#{Action::DIRECTORY_MOVE}`: moves a directory from `path` to (`to`)
+          * `#{Action::DIRECTORY_LIST}`: lists the contents of a directory at a specific `path` (use '.' for root)
+          * `#{Action::FILE_CREATE}`: creates a file at a specific `path`
+          * `#{Action::FILE_DELETE}`: deletes a file at a specific `path`
+          * `#{Action::FILE_MOVE}`: moves a file from `path` to another
+          * `#{Action::FILE_READ}`: reads the contents of a file at a specific path
+          * `#{Action::FILE_WRITE}`: writes the contents of a file at a specific path
+          * `#{Action::FILE_REPLACE}`: replaces the contents of a file at a specific path
+        TEXT
+
+        string :path, description: <<~TEXT.strip
+          A file or directory path that is required for the following actions:
+          * `#{Action::DIRECTORY_CREATE}`
+          * `#{Action::DIRECTORY_DELETE}`
+          * `#{Action::DIRECTORY_MOVE}`
+          * `#{Action::DIRECTORY_LIST}`
+          * `#{Action::FILE_DELETE}`
+          * `#{Action::FILE_READ}`
+          * `#{Action::FILE_WRITE}`
+          * `#{Action::FILE_REPLACE}`
+        TEXT
+
+        string :destination, description: <<~TEXT.strip, required: false
+          A file or directory path that is required for the following actions:
+          * `#{Action::DIRECTORY_MOVE}`
+          * `#{Action::FILE_MOVE}`
+        TEXT
+
+        string :text, description: <<~TEXT.strip, required: false
+          The text to be written to a file for the `#{Action::FILE_WRITE}` action.
+        TEXT
+
+        string :old_text, description: <<~TEXT.strip, required: false
+          The old text to be replaced in a file for the `#{Action::FILE_REPLACE}` action.
+        TEXT
+
+        string :new_text, description: <<~TEXT.strip, required: false
+          The new text to replace in a few file for the `#{Action::FILE_REPLACE}` action.
+        TEXT
+      end
+
+
+      # @param driver [SharedTools::Tools::Disk::BaseDriver] optional, defaults to LocalDriver with current directory
+      # @param logger [Logger] optional logger
+      def initialize(driver: nil, logger: nil)
+        @driver = driver || Disk::LocalDriver.new(root: Dir.pwd)
+        @logger = logger || RubyLLM.logger
+      end
+
+      # @param action [String]
+      # @param path [String]
+      # @param destination [String] optional
+      # @param old_text [String] optional
+      # @param new_text [String] optional
+      # @param text [String] optional
+      def execute(action:, path:, destination: nil, old_text: nil, new_text: nil, text: nil)
+        @logger.info({
+          action:,
+          path:,
+          destination:,
+          old_text:,
+          new_text:,
+          text:,
+        }.compact.map { |key, value| "#{key}=#{value.inspect}" }.join(" "))
+
+        case action
+        when Action::DIRECTORY_CREATE then @driver.directory_create(path:)
+        when Action::DIRECTORY_DELETE then @driver.directory_delete(path:)
+        when Action::DIRECTORY_MOVE then @driver.directory_move(path:, destination:)
+        when Action::DIRECTORY_LIST then @driver.directory_list(path:)
+        when Action::FILE_CREATE then @driver.file_create(path:)
+        when Action::FILE_DELETE then @driver.file_delete(path:)
+        when Action::FILE_MOVE then @driver.file_move(path:, destination:)
+        when Action::FILE_READ then @driver.file_read(path:)
+        when Action::FILE_WRITE then @driver.file_write(path:, text:)
+        when Action::FILE_REPLACE then @driver.file_replace(old_text:, new_text:, path:)
+        end
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/doc/pdf_reader_tool.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+# Credit: https://max.engineer/giant-pdf-llm
+
+begin
+  require "pdf-reader"
+rescue LoadError
+  # pdf-reader is optional - will raise error when tool is used without it
+end
+
+module SharedTools
+  module Tools
+    module Doc
+      # @example
+      #   tool = SharedTools::Tools::Doc::PdfReaderTool.new
+      #   tool.execute(doc_path: "./document.pdf", page_numbers: "1, 5, 10")
+      class PdfReaderTool < ::RubyLLM::Tool
+        def self.name = 'doc_pdf_read'
+
+        description "Read the text of any set of pages from a PDF document."
+
+        params do
+          string :page_numbers, description: 'Comma-separated page numbers (first page: 1). (e.g. "12, 14, 15")'
+          string :doc_path, description: "Path to the PDF document."
+        end
+
+        # @param logger [Logger] optional logger
+        def initialize(logger: nil)
+          @logger = logger || RubyLLM.logger
+        end
+
+        # @param page_numbers [String] comma-separated page numbers
+        # @param doc_path [String] path to PDF file
+        #
+        # @return [Hash] extraction result
+        def execute(page_numbers:, doc_path:)
+          raise LoadError, "PdfReaderTool requires the 'pdf-reader' gem. Install it with: gem install pdf-reader" unless defined?(PDF::Reader)
+
+          @logger.info("Reading PDF: #{doc_path}, pages: #{page_numbers}")
+
+          begin
+            @doc ||= PDF::Reader.new(doc_path)
+            @logger.debug("PDF loaded successfully, total pages: #{@doc.pages.size}")
+
+            page_numbers = page_numbers.split(",").map { |num| num.strip.to_i }
+            @logger.debug("Processing pages: #{page_numbers.join(", ")}")
+
+            # Validate page numbers
+            total_pages = @doc.pages.size
+            invalid_pages = page_numbers.select { |num| num < 1 || num > total_pages }
+
+            if invalid_pages.any?
+              @logger.warn("Invalid page numbers requested: #{invalid_pages.join(", ")}. Document has #{total_pages} pages.")
+            end
+
+            # Filter valid pages and map to content
+            valid_pages = page_numbers.select { |num| num >= 1 && num <= total_pages }
+            pages = valid_pages.map { |num| [num, @doc.pages[num.to_i - 1]] }
+
+            result = {
+              total_pages: total_pages,
+              requested_pages: page_numbers,
+              invalid_pages: invalid_pages,
+              pages: pages.map { |num, p|
+                @logger.debug("Extracted text from page #{num} (#{p&.text&.bytesize || 0} bytes)")
+                { page: num, text: p&.text }
+              },
+            }
+
+            @logger.info("Successfully extracted #{pages.size} pages from PDF")
+            result
+          rescue => e
+            @logger.error("Failed to read PDF '#{doc_path}': #{e.message}")
+            { error: e.message }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/doc.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Collection loader for all doc tools
+# Usage: require 'shared_tools/tools/doc'
+
+require 'shared_tools'
+
+require_relative 'doc/pdf_reader_tool'

data/lib/shared_tools/tools/doc_tool.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require_relative '../../shared_tools'
+
+module SharedTools
+  module Tools
+    # A tool for reading and processing documents
+    class DocTool < ::RubyLLM::Tool
+      def self.name = 'doc_tool'
+
+      module Action
+        PDF_READ = "pdf_read"
+      end
+
+      ACTIONS = [
+        Action::PDF_READ,
+      ].freeze
+
+      description <<~TEXT
+        Read and process various document formats.
+
+        ## Actions:
+
+        1. `#{Action::PDF_READ}` - Read specific pages from a PDF document
+          Required: "action": "pdf_read", "doc_path": "[path to PDF]", "page_numbers": "[comma-separated page numbers]"
+
+          The page_numbers parameter accepts:
+          - Single page: "5"
+          - Multiple pages: "1, 3, 5"
+          - Range notation: "1-10" or "1, 3-5, 10"
+
+        ## Examples:
+
+        Read single page from PDF
+          {"action": "#{Action::PDF_READ}", "doc_path": "./document.pdf", "page_numbers": "1"}
+
+        Read multiple pages
+          {"action": "#{Action::PDF_READ}", "doc_path": "./report.pdf", "page_numbers": "1, 5, 10"}
+
+        Read page range
+          {"action": "#{Action::PDF_READ}", "doc_path": "./book.pdf", "page_numbers": "10-15"}
+
+        Read specific pages with range
+          {"action": "#{Action::PDF_READ}", "doc_path": "./manual.pdf", "page_numbers": "1, 5-8, 15, 20-25"}
+      TEXT
+
+      params do
+        string :action, description: <<~TEXT.strip
+          The document action to perform. Options:
+          * `#{Action::PDF_READ}`: Read pages from a PDF document
+        TEXT
+
+        string :doc_path, description: <<~TEXT.strip, required: false
+          Path to the document file. Required for the following actions:
+          * `#{Action::PDF_READ}`
+        TEXT
+
+        string :page_numbers, description: <<~TEXT.strip, required: false
+          Comma-separated page numbers to read (first page is 1).
+          Examples: "1", "1, 3, 5", "1-10", "1, 5-8, 15"
+          Required for the following actions:
+          * `#{Action::PDF_READ}`
+        TEXT
+      end
+
+      # @param logger [Logger] optional logger
+      def initialize(logger: nil)
+        @logger = logger || RubyLLM.logger
+      end
+
+      # @param action [String] the action to perform
+      # @param doc_path [String, nil] path to document
+      # @param page_numbers [String, nil] page numbers to read
+      #
+      # @return [Hash] execution result
+      def execute(action:, doc_path: nil, page_numbers: nil)
+        @logger.info("DocTool#execute action=#{action}")
+
+        case action.to_s.downcase
+        when Action::PDF_READ
+          require_param!(:doc_path, doc_path)
+          require_param!(:page_numbers, page_numbers)
+          pdf_reader_tool.execute(doc_path: doc_path, page_numbers: page_numbers)
+        else
+          { error: "Unsupported action: #{action}. Supported actions are: #{ACTIONS.join(', ')}" }
+        end
+      rescue StandardError => e
+        @logger.error("DocTool execution failed: #{e.message}")
+        { error: e.message }
+      end
+
+    private
+
+      # @param name [Symbol]
+      # @param value [Object]
+      #
+      # @raise [ArgumentError]
+      # @return [void]
+      def require_param!(name, value)
+        raise ArgumentError, "#{name} param is required for this action" if value.nil?
+      end
+
+      # @return [Doc::PdfReaderTool]
+      def pdf_reader_tool
+        @pdf_reader_tool ||= Doc::PdfReaderTool.new(logger: @logger)
+      end
+    end
+  end
+end