shared_tools 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8ae3eef4f29e12a8be7ff8db5eec7e156bcfa1e767d5375b2ffde66db35629ef
+  data.tar.gz: 6f73bca50589be410d134eb2c02be5451bed2f875dea5854984181ff9f37fc44
+SHA512:
+  metadata.gz: 42a193b5df012a25909c94a28d60e1d66347683d32bc29979a578e4fbf705738c02053625c45828c7029fe2473fa8cf40ca2e83a67ed29599ac10ab4436f2d4c
+  data.tar.gz: 57bb4e3b32137687b81257adf786d684fc1bb521a8d661fb23ea057047c64ae78e1f2af0f2273199093d1194d8553276bbba3302f76d3942677b7c24a78dfcd7

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## [0.1.0] - 2025-06-05
+
+### Added
+
+- Initial gem release
+- SharedTools core module with automatic logger integration
+- RubyLlm tools: EditFile, ListFiles, PdfPageReader, ReadFile, RunShellCommand

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Dewayne VanHoozer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,112 @@
+# shared_tools
+A Ruby gem providing a collection of shared tools and utilities for Ruby applications, including configurable logging and AI-related tools.
+
+## Libraries Supported
+
+- ruby_llm: multi-provider
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'shared_tools'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install shared_tools
+```
+
+## Usage
+
+```ruby
+# To load all tools for a specific library
+require 'shared_tools/ruby_llm'
+
+# OR you can load a specific tool
+require 'shared_tools/ruby_llm/edit_file'
+```
+
+## Shared Logging
+
+All classes within the SharedTools namespace automatically have access to a configurable logger without requiring any explicit includes or setup.
+
+### Basic Usage
+
+Within any class in the SharedTools namespace, you can directly use the logger:
+
+```ruby
+module SharedTools
+  class MyTool
+    def perform_action
+      logger.info "Starting action"
+      # Do something
+      logger.debug "Details about action"
+      # Handle errors
+    rescue => e
+      logger.error "Action failed: #{e.message}"
+      raise
+    ensure
+      logger.info "Action completed"
+    end
+  end
+ end
+```
+
+### Configuration
+
+The logger can be configured using the `configure_logger` method:
+
+```ruby
+# Configure the logger in your application initialization
+SharedTools.configure_logger do |config|
+  config.level = Logger::DEBUG                   # Set log level
+  config.log_device = "logs/shared_tools.log"    # Set output file
+  config.formatter = proc do |severity, time, progname, msg|
+    "[#{time.strftime('%Y-%m-%d %H:%M:%S')}] #{severity}: #{msg}\n"
+  end
+ end
+```
+
+### Using with Rails
+
+To use the SharedTools logger with Rails and make it use the same logger instance:
+
+```ruby
+# In config/initializers/shared_tools.rb
+Rails.application.config.after_initialize do
+  # Make SharedTools use the Rails logger
+  SharedTools.logger = Rails.logger
+
+  # Alternatively, configure the Rails logger to use SharedTools settings
+  # SharedTools.configure_logger do |config|
+  #   config.level = Rails.logger.level
+  #   config.log_device = Rails.logger.instance_variable_get(:@logdev).dev
+  # end
+  # Rails.logger = SharedTools.logger
+
+  Rails.logger.info "SharedTools integrated with Rails logger"
+end
+```
+
+### Available Log Levels
+
+The logger supports the standard Ruby Logger levels:
+
+- `logger.debug` - Detailed debug information
+- `logger.info` - General information messages
+- `logger.warn` - Warning messages
+- `logger.error` - Error messages
+- `logger.fatal` - Fatal error messages
+
+### Thread Safety
+
+The shared logger is thread-safe and can be used across multiple threads in your application.

data/lib/shared_tools/core.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "logger"
+require "singleton"
+
+module SharedTools
+  DEFAULT_LOG_LEVEL = Logger::INFO
+
+  module InstanceMethods
+    # @return [Logger] The shared logger instance
+    def logger
+      SharedTools.logger
+    end
+  end
+
+  module ClassMethods
+    # @return [Logger] The shared logger instance
+    def logger
+      SharedTools.logger
+    end
+  end
+
+
+  class LoggerConfiguration
+    include Singleton
+
+    attr_accessor :level, :log_device, :formatter
+
+    def initialize
+      @level = DEFAULT_LOG_LEVEL
+      @log_device = STDOUT
+      @formatter = nil
+    end
+
+
+    def apply_to(logger)
+      logger.level = @level
+      logger.formatter = @formatter if @formatter
+    end
+  end
+
+
+  class << self
+    # @return [Logger] The configured logger instance
+    def logger
+      @logger ||= create_logger
+    end
+
+    # @param new_logger [Logger] A Logger instance to use
+    def logger=(new_logger)
+      @logger = new_logger
+    end
+
+
+    # @example
+    #   SharedTools.configure_logger do |config|
+    #     config.level = Logger::DEBUG
+    #     config.log_device = 'logs/application.log'
+    #     config.formatter = proc { |severity, time, progname, msg| "[#{time}] #{severity} - #{msg}\n" }
+    #   end
+    def configure_logger
+      yield LoggerConfiguration.instance
+
+
+      if @logger
+        @logger = create_logger
+      end
+    end
+
+    private
+
+    # @return [Logger] A newly configured logger
+    def create_logger
+      config = LoggerConfiguration.instance
+      logger = Logger.new(config.log_device)
+      config.apply_to(logger)
+      logger
+    end
+  end
+
+
+  # module LoggingSupport
+  #   def self.included(base)
+  #     base.include(SharedTools)
+  #   end
+  # end
+end

data/lib/shared_tools/ruby_llm/edit_file.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require("ruby_llm")     unless defined?(RubyLLM)
+require("shared_tools") unless defined?(SharedTools)
+
+module SharedTools
+  class EditFile < RubyLLM::Tool
+
+    description <<~DESCRIPTION
+                  Make edits to a text file.
+
+                  Replaces 'old_str' with 'new_str' in the given file.
+                  'old_str' and 'new_str' MUST be different from each other.
+
+                  If the file specified with path doesn't exist, it will be created.
+
+                  By default, only the first occurrence will be replaced. Set replace_all to true to replace all occurrences.
+                DESCRIPTION
+    param :path, desc: "The path to the file"
+    param :old_str, desc: "Text to search for - must match exactly"
+    param :new_str, desc: "Text to replace old_str with"
+    param :replace_all, desc: "Whether to replace all occurrences (true) or just the first one (false)", required: false
+
+    def execute(path:, old_str:, new_str:, replace_all: false)
+      logger.info("Editing file: #{path}")
+
+      # Normalize path to absolute path
+      absolute_path = File.absolute_path(path)
+
+      if File.exist?(absolute_path)
+        logger.debug("File exists, reading content")
+        content = File.read(absolute_path)
+      else
+        logger.debug("File doesn't exist, creating new file")
+        content = ""
+      end
+
+      matches = content.scan(old_str).size
+      logger.debug("Found #{matches} matches for the string to replace")
+
+      if matches == 0
+        logger.warn("No matches found for the string to replace. File will remain unchanged.")
+        return { success: false, warning: "No matches found for the string to replace" }
+      end
+
+      if matches > 1 && !replace_all
+        logger.warn("Multiple matches (#{matches}) found for the string to replace. Only the first occurrence will be replaced.")
+      end
+
+      if replace_all
+        updated_content = content.gsub(old_str, new_str)
+        replaced_count = matches
+        logger.info("Replacing all #{matches} occurrences")
+      else
+        updated_content = content.sub(old_str, new_str)
+        replaced_count = 1
+        logger.info("Replacing first occurrence only")
+      end
+
+      File.write(absolute_path, updated_content)
+
+      logger.info("Successfully updated file: #{path}")
+      { success: true, matches: matches, replaced: replaced_count }
+    rescue => e
+      logger.error("Failed to edit file '#{path}': #{e.message}")
+      { error: e.message }
+    end
+  end
+end

data/lib/shared_tools/ruby_llm/list_files.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require("ruby_llm")     unless defined?(RubyLLM)
+require("shared_tools") unless defined?(SharedTools)
+
+module SharedTools
+  class ListFiles < RubyLLM::Tool
+
+    description "List files and directories at a given path. If no path is provided, lists files in the current directory."
+    param :path, desc: "Optional relative path to list files from. Defaults to current directory if not provided."
+
+    def execute(path: Dir.pwd)
+      logger.info("Listing files in path: #{path}")
+
+      # Convert to absolute path for consistency
+      absolute_path = File.absolute_path(path)
+
+      # Verify the path exists and is a directory
+      unless File.directory?(absolute_path)
+        error_msg = "Path does not exist or is not a directory: #{path}"
+        logger.error(error_msg)
+        return { error: error_msg }
+      end
+
+      # Get all files including hidden ones
+      visible_files = Dir.glob(File.join(absolute_path, "*"))
+      hidden_files = Dir.glob(File.join(absolute_path, ".*"))
+                        .reject { |f| f.end_with?("/.") || f.end_with?("/..") }
+
+      # Combine and format results
+      all_files = (visible_files + hidden_files).sort
+      formatted_files = all_files.map do |filename|
+        if File.directory?(filename)
+          "#{filename}/"
+        else
+          filename
+        end
+      end
+
+      logger.debug("Found #{formatted_files.size} files/directories (including #{hidden_files.size} hidden)")
+      formatted_files
+    rescue => e
+      logger.error("Failed to list files in '#{path}': #{e.message}")
+      { error: e.message }
+    end
+  end
+end

data/lib/shared_tools/ruby_llm/pdf_page_reader.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+# Credit: https://max.engineer/giant-pdf-llm
+
+require "pdf-reader"
+
+require("ruby_llm")     unless defined?(RubyLLM)
+require("shared_tools") unless defined?(SharedTools)
+
+module SharedTools
+  class PdfPageReader < RubyLLM::Tool
+
+    description "Read the text of any set of pages from a PDF document."
+    param :page_numbers,
+      desc: 'Comma-separated page numbers (first page: 1). (e.g. "12, 14, 15")'
+    param :doc_path,
+      desc: "Path to the PDF document."
+
+    def execute(page_numbers:, doc_path:)
+      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

data/lib/shared_tools/ruby_llm/read_file.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require("ruby_llm")     unless defined?(RubyLLM)
+require("shared_tools") unless defined?(SharedTools)
+
+module SharedTools
+  class ReadFile < RubyLLM::Tool
+
+    description "Read the contents of a given relative file path. Use this when you want to see what's inside a file. Do not use this with directory names."
+    param :path, desc: "The relative path of a file in the working directory."
+
+    def execute(path:)
+      logger.info("Reading file: #{path}")
+
+      # Handle both relative and absolute paths consistently
+      absolute_path = File.absolute_path(path)
+
+      if File.directory?(absolute_path)
+        error_msg = "Path is a directory, not a file: #{path}"
+        logger.error(error_msg)
+        return { error: error_msg }
+      end
+
+      unless File.exist?(absolute_path)
+        error_msg = "File does not exist: #{path}"
+        logger.error(error_msg)
+        return { error: error_msg }
+      end
+
+      content = File.read(absolute_path)
+      logger.debug("Successfully read #{content.bytesize} bytes from #{path}")
+      content
+    rescue => e
+      logger.error("Failed to read file '#{path}': #{e.message}")
+      { error: e.message }
+    end
+  end
+end

data/lib/shared_tools/ruby_llm/run_shell_command.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require("ruby_llm")     unless defined?(RubyLLM)
+require("shared_tools") unless defined?(SharedTools)
+
+module SharedTools
+  class RunShellCommand < RubyLLM::Tool
+
+    description "Execute a shell command"
+    param :command, desc: "The command to execute"
+
+    def execute(command:)
+      logger.info("Requesting permission to execute command: '#{command}'")
+
+      if command.strip.empty?
+        error_msg = "Command cannot be empty"
+        logger.error(error_msg)
+        return { error: error_msg }
+      end
+
+      # Show user the command and ask for confirmation
+      puts "AI wants to execute the following shell command: '#{command}'"
+      print "Do you want to execute it? (y/n) "
+      response = gets.chomp.downcase
+
+      unless response == "y"
+        logger.warn("User declined to execute the command: '#{command}'")
+        return { error: "User declined to execute the command" }
+      end
+
+      logger.info("Executing command: '#{command}'")
+
+      # Use Open3 for safer command execution with proper error handling
+      require "open3"
+      stdout, stderr, status = Open3.capture3(command)
+
+      if status.success?
+        logger.debug("Command execution completed successfully with #{stdout.bytesize} bytes of output")
+        { stdout: stdout, exit_status: status.exitstatus }
+      else
+        logger.warn("Command execution failed with exit code #{status.exitstatus}: #{stderr}")
+        { error: "Command failed with exit code #{status.exitstatus}", stderr: stderr, exit_status: status.exitstatus }
+      end
+    rescue => e
+      logger.error("Command execution failed: #{e.message}")
+      { error: e.message }
+    end
+  end
+end

data/lib/shared_tools/ruby_llm.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require("ruby_llm")     unless defined?(RubyLLM)
+require("shared_tools") unless defined?(SharedTools)
+
+require_relative "ruby_llm/edit_file"
+require_relative "ruby_llm/list_files"
+require_relative "ruby_llm/pdf_page_reader"
+require_relative "ruby_llm/read_file"
+require_relative "ruby_llm/run_shell_command"

data/lib/shared_tools/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SharedTools
+  VERSION = "0.1.0"
+end

data/lib/shared_tools.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "shared_tools/version"
+
+module SharedTools
+  class << self
+    # def included(base)
+    #   base.extend(ClassMethods)
+
+    #   if base.is_a?(Class)
+    #     base.class_eval do
+    #       include InstanceMethods
+    #     end
+    #   else
+    #     base.module_eval do
+    #       def self.included(sub_base)
+    #         sub_base.include(SharedTools)
+    #       end
+    #     end
+    #   end
+    # end
+
+    # def extended(object)
+    #   object.extend(ClassMethods)
+    # end
+
+    # Hook to automatically inject logger into RubyLLM::Tool subclasses
+    def const_added(const_name)
+      const = const_get(const_name)
+
+      if const.is_a?(Class) && defined?(RubyLLM::Tool) && const < RubyLLM::Tool
+        const.class_eval do
+          def logger
+            SharedTools.logger
+          end
+
+          def self.logger
+            SharedTools.logger
+          end
+        end
+      end
+    end
+  end
+end
+
+require "shared_tools/core"

metadata

@@ -0,0 +1,140 @@
+--- !ruby/object:Gem::Specification
+name: shared_tools
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- MadBomber Team
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: pdf-reader
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: ruby_llm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: SharedTools provides common functionality including configurable logging
+  and LLM tools
+email:
+- example@example.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/shared_tools.rb
+- lib/shared_tools/core.rb
+- lib/shared_tools/ruby_llm.rb
+- lib/shared_tools/ruby_llm/edit_file.rb
+- lib/shared_tools/ruby_llm/list_files.rb
+- lib/shared_tools/ruby_llm/pdf_page_reader.rb
+- lib/shared_tools/ruby_llm/read_file.rb
+- lib/shared_tools/ruby_llm/run_shell_command.rb
+- lib/shared_tools/version.rb
+homepage: https://github.com/madbomber/shared_tools
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/madbomber/shared_tools
+  source_code_uri: https://github.com/madbomber/shared_tools
+  changelog_uri: https://github.com/madbomber/shared_tools/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: A collection of shared tools and utilities for Ruby applications
+test_files: []