shared_tools 0.3.1 → 0.4.1

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

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+begin
+  require "docx"
+rescue LoadError
+  # docx is optional - will raise error when tool is used without it
+end
+
+module SharedTools
+  module Tools
+    module Doc
+      # Read text content from Microsoft Word (.docx) documents.
+      #
+      # @example
+      #   tool = SharedTools::Tools::Doc::DocxReaderTool.new
+      #   tool.execute(doc_path: "./report.docx")
+      #   tool.execute(doc_path: "./report.docx", paragraph_range: "1-10")
+      class DocxReaderTool < ::RubyLLM::Tool
+        def self.name = 'doc_docx_read'
+
+        description "Read the text content of a Microsoft Word (.docx) document."
+
+        params do
+          string :doc_path, description: "Path to the .docx file."
+
+          string :paragraph_range, description: <<~DESC.strip, required: false
+            Optional range of paragraphs to extract, 1-based.
+            Accepts the same notation as pdf_read page numbers:
+            - Single paragraph: "5"
+            - Multiple paragraphs: "1, 3, 5"
+            - Range: "1-20"
+            - Mixed: "1, 5-10, 15"
+            Omit to return the full document.
+          DESC
+        end
+
+        # @param logger [Logger] optional logger
+        def initialize(logger: nil)
+          @logger = logger || RubyLLM.logger
+        end
+
+        # @param doc_path [String] path to .docx file
+        # @param paragraph_range [String, nil] optional paragraph range
+        # @return [Hash] extraction result
+        def execute(doc_path:, paragraph_range: nil)
+          raise LoadError, "DocxReaderTool requires the 'docx' gem. Install it with: gem install docx" unless defined?(Docx)
+
+          @logger.info("DocxReaderTool#execute doc_path=#{doc_path} paragraph_range=#{paragraph_range}")
+
+          unless File.exist?(doc_path)
+            return { error: "File not found: #{doc_path}" }
+          end
+
+          unless File.extname(doc_path).downcase == '.docx'
+            return { error: "Expected a .docx file, got: #{File.extname(doc_path)}" }
+          end
+
+          doc        = Docx::Document.open(doc_path)
+          paragraphs = doc.paragraphs.map(&:to_s).reject { |p| p.strip.empty? }
+          total      = paragraphs.length
+
+          @logger.debug("Loaded #{total} non-empty paragraphs from #{doc_path}")
+
+          selected_indices = if paragraph_range
+            parse_range(paragraph_range, total)
+          else
+            (1..total).to_a
+          end
+
+          invalid = selected_indices.select { |n| n < 1 || n > total }
+          valid   = selected_indices.select { |n| n >= 1 && n <= total }
+
+          extracted = valid.map { |n| { paragraph: n, text: paragraphs[n - 1] } }
+
+          @logger.info("Extracted #{extracted.size} paragraphs from #{doc_path}")
+
+          {
+            doc_path:           doc_path,
+            total_paragraphs:   total,
+            requested_range:    paragraph_range || "all",
+            invalid_paragraphs: invalid,
+            paragraphs:         extracted,
+            full_text:          extracted.map { |p| p[:text] }.join("\n\n")
+          }
+        rescue => e
+          @logger.error("Failed to read DOCX '#{doc_path}': #{e.message}")
+          { error: e.message }
+        end
+
+        private
+
+        # Parse a range string like "1, 3-5, 10" into a sorted array of integers.
+        def parse_range(range_str, max)
+          range_str.split(',').flat_map do |part|
+            part.strip!
+            if part.include?('-')
+              lo, hi = part.split('-').map { |n| n.strip.to_i }
+              (lo..hi).to_a
+            else
+              [part.to_i]
+            end
+          end.uniq.sort
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+begin
+  require "roo"
+rescue LoadError
+  # roo is optional - will raise an error when the tool is used without it
+end
+
+module SharedTools
+  module Tools
+    module Doc
+      # Read spreadsheet data from CSV, XLSX, ODS, and other formats supported by the roo gem.
+      #
+      # @example Read all rows from a CSV
+      #   tool = SharedTools::Tools::Doc::SpreadsheetReaderTool.new
+      #   tool.execute(doc_path: "./data.csv")
+      #
+      # @example Read a specific sheet from an Excel workbook
+      #   tool.execute(doc_path: "./report.xlsx", sheet: "Q1 Sales")
+      #
+      # @example Read a row range from a worksheet
+      #   tool.execute(doc_path: "./report.xlsx", sheet: "Summary", row_range: "2-50")
+      class SpreadsheetReaderTool < ::RubyLLM::Tool
+        def self.name = 'doc_spreadsheet_read'
+
+        description "Read tabular data from spreadsheet files (CSV, XLSX, ODS, and other formats)."
+
+        SUPPORTED_FORMATS = %w[.csv .xlsx .ods .xlsm].freeze
+
+        params do
+          string :doc_path, description: <<~DESC.strip
+            Path to the spreadsheet file. Supported formats:
+            - .csv  — Comma-separated values (plain text, no gem beyond roo required)
+            - .xlsx — Microsoft Excel Open XML Workbook (Excel 2007+)
+            - .xlsm — Microsoft Excel Macro-Enabled Workbook
+            - .ods  — OpenDocument Spreadsheet (LibreOffice / OpenOffice)
+            Note: Legacy .xls (Excel 97-2003) requires the additional 'roo-xls' gem.
+          DESC
+
+          string :sheet, description: <<~DESC.strip, required: false
+            Name or 1-based index of the worksheet to read. For multi-sheet workbooks
+            (XLSX, ODS), specify the exact sheet name (e.g. "Q1 Sales") or a number
+            (e.g. "2" for the second sheet). Defaults to the first sheet.
+            CSV files always have a single implicit sheet called "default".
+          DESC
+
+          string :row_range, description: <<~DESC.strip, required: false
+            Row range to extract, 1-based (row 1 is the header row in most spreadsheets).
+            Accepts the same notation as other doc tool parameters:
+            - Single row:    "3"
+            - Multiple rows: "1, 3, 5"
+            - Range:         "1-100"
+            - Mixed:         "1, 5-20, 30"
+            Omit to return all rows.
+          DESC
+
+          boolean :headers, description: <<~DESC.strip, required: false
+            When true (default), treats the first row as column headers and returns
+            each subsequent row as a hash keyed by header name. When false, returns
+            each row as a plain array of values. Set to false when the spreadsheet
+            has no header row or when you want raw positional data.
+          DESC
+        end
+
+        # @param logger [Logger] optional logger
+        def initialize(logger: nil)
+          @logger = logger || RubyLLM.logger
+        end
+
+        # @param doc_path [String] path to spreadsheet file
+        # @param sheet [String, nil] sheet name or 1-based index
+        # @param row_range [String, nil] row range to extract
+        # @param headers [Boolean] whether first row is headers
+        # @return [Hash] extraction result
+        def execute(doc_path:, sheet: nil, row_range: nil, headers: true)
+          raise LoadError, "SpreadsheetReaderTool requires the 'roo' gem. Install it with: gem install roo" unless defined?(Roo)
+
+          @logger.info("SpreadsheetReaderTool#execute doc_path=#{doc_path} sheet=#{sheet} row_range=#{row_range}")
+
+          return { error: "File not found: #{doc_path}" } unless File.exist?(doc_path)
+
+          ext = File.extname(doc_path).downcase
+          unless SUPPORTED_FORMATS.include?(ext)
+            return { error: "Unsupported format '#{ext}'. Supported: #{SUPPORTED_FORMATS.join(', ')}" }
+          end
+
+          ss = Roo::Spreadsheet.open(doc_path)
+
+          # Select sheet
+          active_sheet = resolve_sheet(ss, sheet)
+          return active_sheet if active_sheet.is_a?(Hash) && active_sheet[:error]
+
+          ss.default_sheet = active_sheet
+
+          total_rows  = ss.last_row.to_i
+          first_row   = ss.first_row.to_i
+          header_row  = headers ? ss.row(first_row).map { |h| h.to_s.strip } : nil
+
+          # Determine data rows (skip header if using headers)
+          data_start  = headers ? first_row + 1 : first_row
+          all_indices = (data_start..total_rows).to_a
+
+          selected = row_range ? filter_rows(all_indices, row_range) : all_indices
+          invalid  = selected.reject { |n| n >= first_row && n <= total_rows }
+          valid    = selected.select { |n| n >= first_row && n <= total_rows }
+
+          rows = valid.map do |n|
+            raw = ss.row(n)
+            if headers && header_row
+              header_row.zip(raw).to_h
+            else
+              raw
+            end
+          end
+
+          @logger.info("SpreadsheetReaderTool: read #{rows.size} rows from '#{active_sheet}'")
+
+          {
+            doc_path:       doc_path,
+            format:         ext,
+            available_sheets: ss.sheets,
+            active_sheet:   active_sheet,
+            total_rows:     total_rows,
+            header_row:     header_row,
+            requested_range: row_range || "all",
+            invalid_rows:   invalid,
+            row_count:      rows.size,
+            rows:           rows
+          }
+        rescue => e
+          @logger.error("SpreadsheetReaderTool failed for '#{doc_path}': #{e.message}")
+          { error: e.message }
+        end
+
+        private
+
+        # Resolve sheet name or 1-based index to the actual sheet name.
+        def resolve_sheet(ss, sheet_param)
+          return ss.sheets.first if sheet_param.nil?
+
+          # Numeric string → treat as 1-based index
+          if sheet_param.match?(/\A\d+\z/)
+            idx = sheet_param.to_i - 1
+            return { error: "Sheet index #{sheet_param} out of range (workbook has #{ss.sheets.size} sheet(s))" } if idx < 0 || idx >= ss.sheets.size
+            return ss.sheets[idx]
+          end
+
+          # Named sheet
+          return sheet_param if ss.sheets.include?(sheet_param)
+
+          { error: "Sheet '#{sheet_param}' not found. Available sheets: #{ss.sheets.join(', ')}" }
+        end
+
+        # Parse a range string like "1, 3-5, 10" into a sorted array of row indices.
+        def filter_rows(all_indices, range_str)
+          requested = range_str.split(',').flat_map do |part|
+            part.strip!
+            if part.include?('-')
+              lo, hi = part.split('-').map { |n| n.strip.to_i }
+              (lo..hi).to_a
+            else
+              [part.to_i]
+            end
+          end.uniq.sort
+
+          all_indices & requested
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module SharedTools
+  module Tools
+    module Doc
+      # Read and return the full contents of a plain text file.
+      #
+      # @example
+      #   tool = SharedTools::Tools::Doc::TextReaderTool.new
+      #   tool.execute(doc_path: "./guide.txt")
+      class TextReaderTool < ::RubyLLM::Tool
+        def self.name = 'doc_text_read'
+
+        description "Read the full contents of a plain text file."
+
+        params do
+          string :doc_path, description: "Path to the text file to read."
+        end
+
+        # @param logger [Logger] optional logger
+        def initialize(logger: nil)
+          @logger = logger || RubyLLM.logger
+        end
+
+        # @param doc_path [String] path to the text file
+        # @return [Hash] file content and metadata
+        def execute(doc_path:)
+          @logger.info("TextReaderTool#execute doc_path=#{doc_path.inspect}")
+
+          raise ArgumentError, "doc_path is required" if doc_path.nil? || doc_path.strip.empty?
+          raise ArgumentError, "File not found: #{doc_path}" unless File.exist?(doc_path)
+          raise ArgumentError, "Not a file: #{doc_path}" unless File.file?(doc_path)
+
+          content    = File.read(doc_path, encoding: 'utf-8')
+          line_count = content.lines.size
+          char_count = content.length
+          word_count = content.split.size
+
+          @logger.info("TextReaderTool read #{char_count} chars, #{line_count} lines from #{doc_path}")
+
+          {
+            doc_path:   doc_path,
+            content:    content,
+            line_count: line_count,
+            word_count: word_count,
+            char_count: char_count
+          }
+        rescue ArgumentError
+          raise
+        rescue => e
+          @logger.error("TextReaderTool failed to read #{doc_path}: #{e.message}")
+          { error: e.message, doc_path: doc_path }
+        end
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/doc.rb

@@ -6,3 +6,6 @@
 require 'shared_tools'
 
 require_relative 'doc/pdf_reader_tool'
+require_relative 'doc/text_reader_tool'
+require_relative 'doc/docx_reader_tool'
+require_relative 'doc/spreadsheet_reader_tool'

data/lib/shared_tools/tools/doc_tool.rb

@@ -9,19 +9,28 @@ module SharedTools
       def self.name = 'doc_tool'
 
       module Action
-        PDF_READ = "pdf_read"
+        PDF_READ         = "pdf_read"
+        TEXT_READ        = "text_read"
+        DOCX_READ        = "docx_read"
+        SPREADSHEET_READ = "spreadsheet_read"
       end
 
       ACTIONS = [
         Action::PDF_READ,
+        Action::TEXT_READ,
+        Action::DOCX_READ,
+        Action::SPREADSHEET_READ,
       ].freeze
 
       description <<~TEXT
-        Read and process various document formats.
+        Read and process document files.
 
         ## Actions:
 
-        1. `#{Action::PDF_READ}` - Read specific pages from a PDF document
+        1. `#{Action::TEXT_READ}` - Read the full contents of a plain text file (.txt, .md, etc.)
+          Required: "action": "text_read", "doc_path": "[path to text file]"
+
+        2. `#{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:
@@ -29,8 +38,18 @@ module SharedTools
           - Multiple pages: "1, 3, 5"
           - Range notation: "1-10" or "1, 3-5, 10"
 
+        3. `#{Action::DOCX_READ}` - Read text content from a Microsoft Word (.docx) document
+          Required: "action": "docx_read", "doc_path": "[path to .docx file]"
+          Optional: "paragraph_range": "[comma-separated paragraph numbers or ranges]"
+
+          The paragraph_range parameter accepts the same notation as page_numbers.
+          Omit paragraph_range to return the full document.
+
         ## Examples:
 
+        Read a text file
+          {"action": "#{Action::TEXT_READ}", "doc_path": "./notes.txt"}
+
         Read single page from PDF
           {"action": "#{Action::PDF_READ}", "doc_path": "./document.pdf", "page_numbers": "1"}
 
@@ -42,17 +61,41 @@ module SharedTools
 
         Read specific pages with range
           {"action": "#{Action::PDF_READ}", "doc_path": "./manual.pdf", "page_numbers": "1, 5-8, 15, 20-25"}
+
+        Read a full Word document
+          {"action": "#{Action::DOCX_READ}", "doc_path": "./report.docx"}
+
+        Read first 20 paragraphs of a Word document
+          {"action": "#{Action::DOCX_READ}", "doc_path": "./report.docx", "paragraph_range": "1-20"}
+
+        4. `#{Action::SPREADSHEET_READ}` - Read tabular data from a spreadsheet file
+          Supported formats: CSV, XLSX, ODS, XLSM
+          Required: "action": "spreadsheet_read", "doc_path": "[path to spreadsheet]"
+          Optional: "sheet": "[sheet name or 1-based index]"
+                    "row_range": "[row range, e.g. '2-100']"
+                    "headers": true/false (default true — first row treated as headers)
+
+        Read a full CSV file
+          {"action": "#{Action::SPREADSHEET_READ}", "doc_path": "./data.csv"}
+
+        Read a specific sheet from an Excel workbook
+          {"action": "#{Action::SPREADSHEET_READ}", "doc_path": "./report.xlsx", "sheet": "Q1 Sales"}
+
+        Read rows 2-50 from a worksheet without header treatment
+          {"action": "#{Action::SPREADSHEET_READ}", "doc_path": "./report.xlsx", "row_range": "2-50", "headers": false}
       TEXT
 
       params do
         string :action, description: <<~TEXT.strip
           The document action to perform. Options:
+          * `#{Action::TEXT_READ}`: Read a plain text file
           * `#{Action::PDF_READ}`: Read pages from a PDF document
+          * `#{Action::DOCX_READ}`: Read paragraphs from a Microsoft Word (.docx) document
+          * `#{Action::SPREADSHEET_READ}`: Read tabular data from a spreadsheet (CSV, XLSX, ODS)
         TEXT
 
         string :doc_path, description: <<~TEXT.strip, required: false
-          Path to the document file. Required for the following actions:
-          * `#{Action::PDF_READ}`
+          Path to the document file. Required for all actions.
         TEXT
 
         string :page_numbers, description: <<~TEXT.strip, required: false
@@ -61,6 +104,34 @@ module SharedTools
           Required for the following actions:
           * `#{Action::PDF_READ}`
         TEXT
+
+        string :paragraph_range, description: <<~TEXT.strip, required: false
+          Comma-separated paragraph numbers or ranges to read from a Word document (first paragraph is 1).
+          Examples: "1", "1, 3, 5", "1-20", "1, 5-8, 15"
+          Optional for the following actions (omit to return the full document):
+          * `#{Action::DOCX_READ}`
+        TEXT
+
+        string :sheet, description: <<~TEXT.strip, required: false
+          Sheet name or 1-based sheet index to read from a multi-sheet spreadsheet.
+          Examples: "Q1 Sales", "2"
+          Optional for the following actions (defaults to the first sheet):
+          * `#{Action::SPREADSHEET_READ}`
+        TEXT
+
+        string :row_range, description: <<~TEXT.strip, required: false
+          Comma-separated row numbers or ranges to read from a spreadsheet (first row is 1).
+          Examples: "1", "2-100", "1, 5-20, 30"
+          Optional for the following actions (omit to return all rows):
+          * `#{Action::SPREADSHEET_READ}`
+        TEXT
+
+        boolean :headers, description: <<~TEXT.strip, required: false
+          When true (default), treats the first row as column headers and returns each
+          subsequent row as a hash. When false, returns rows as plain arrays.
+          Optional for the following actions:
+          * `#{Action::SPREADSHEET_READ}`
+        TEXT
       end
 
       # @param logger [Logger] optional logger
@@ -73,14 +144,23 @@ module SharedTools
       # @param page_numbers [String, nil] page numbers to read
       #
       # @return [Hash] execution result
-      def execute(action:, doc_path: nil, page_numbers: nil)
+      def execute(action:, doc_path: nil, page_numbers: nil, paragraph_range: nil, sheet: nil, row_range: nil, headers: true)
         @logger.info("DocTool#execute action=#{action}")
 
         case action.to_s.downcase
+        when Action::TEXT_READ
+          require_param!(:doc_path, doc_path)
+          text_reader_tool.execute(doc_path: doc_path)
         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)
+        when Action::DOCX_READ
+          require_param!(:doc_path, doc_path)
+          docx_reader_tool.execute(doc_path: doc_path, paragraph_range: paragraph_range)
+        when Action::SPREADSHEET_READ
+          require_param!(:doc_path, doc_path)
+          spreadsheet_reader_tool.execute(doc_path: doc_path, sheet: sheet, row_range: row_range, headers: headers)
         else
           { error: "Unsupported action: #{action}. Supported actions are: #{ACTIONS.join(', ')}" }
         end
@@ -104,6 +184,21 @@ module SharedTools
       def pdf_reader_tool
         @pdf_reader_tool ||= Doc::PdfReaderTool.new(logger: @logger)
       end
+
+      # @return [Doc::TextReaderTool]
+      def text_reader_tool
+        @text_reader_tool ||= Doc::TextReaderTool.new(logger: @logger)
+      end
+
+      # @return [Doc::DocxReaderTool]
+      def docx_reader_tool
+        @docx_reader_tool ||= Doc::DocxReaderTool.new(logger: @logger)
+      end
+
+      # @return [Doc::SpreadsheetReaderTool]
+      def spreadsheet_reader_tool
+        @spreadsheet_reader_tool ||= Doc::SpreadsheetReaderTool.new(logger: @logger)
+      end
     end
   end
 end

data/lib/shared_tools/tools/docker/compose_run_tool.rb

@@ -16,7 +16,7 @@ module SharedTools
         params do
           string :service, description: "The service to run the command on (e.g. `app`).", required: false
           string :command, description: "The command to run (e.g. `rspec`)."
-          array :args, description: "The arguments for the command.", required: false
+          array :args, of: :string, description: "The arguments for the command.", required: false
         end
 
         # @example

data/lib/shared_tools/tools/enabler.rb

@@ -0,0 +1,42 @@
+# lib/shared_tools/tools/enabler.rb
+# frozen_string_literal: true
+# Part of an idea to reduce the number of tokens used when there
+# are a large number tools available.  As part of the initial prompt
+# send tool names, descriptions and parameters alone with instructions
+# to call the enable tool with the tool name to use and a JSON
+# formatted parameters.
+#
+# This could be something lie a tool dispatcher that can call the
+# tool with the parameters and return the result.
+#
+# Maybe we have the DispatcherTool and a ToolBox tool where the ToolBox Tool
+# returns to the LLM the list of tool names, parameters and descriptions.
+# The DispatcherTool can then call the tool with the parameters and return the result.
+
+
+require 'ruby_llm/tool'
+
+module Tools
+  # A tool for reading the contents of a file.
+  class Enabler < RubyLLM::Tool
+    attr_reader :agent
+
+    description <<~DESCRIPTION
+      Enables a tool based on the request.
+    DESCRIPTION
+    param :tool, desc: 'Tool name to enable'
+    # param :params, desc: 'JSON formatted parameters'
+
+    def initialize(agent)
+      @agent = agent
+    end
+
+    def execute(tool:, params: '')
+      agent.add_tool(tool)
+      # TODO: call the tool with the params and return the result.
+      { success: true }
+    rescue StandardError => e
+      { error: e.message }
+    end
+  end
+end

data/lib/shared_tools/tools/error_handling_tool.rb

@@ -104,9 +104,11 @@ module SharedTools
       # @param max_retries [Integer] Maximum retry attempts
       #
       # @return [Hash] Operation result with success status
-      def execute(operation:, simulate_error: nil, max_retries: 3, **data)
+      def execute(operation:, simulate_error: nil, max_retries: 3, data: {}, **_rest)
         @operation_start_time = Time.now
         @logger.info("ErrorHandlingTool#execute operation=#{operation} simulate_error=#{simulate_error}")
+        # Normalise data keys to symbols (JSON tool calls use string keys)
+        data = (data || {}).transform_keys(&:to_sym)
 
         begin
           # Validate inputs

data/lib/shared_tools/tools/notification/base_driver.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module SharedTools
+  module Tools
+    module Notification
+      # Abstract base class for platform-specific notification drivers.
+      # Subclasses must implement notify, alert, and speak.
+      class BaseDriver
+        # Show a non-blocking desktop banner notification.
+        #
+        # @param message [String]
+        # @param title [String, nil]
+        # @param subtitle [String, nil]
+        # @param sound [String, nil]
+        # @return [Hash]
+        def notify(message:, title: nil, subtitle: nil, sound: nil)
+          raise NotImplementedError, "#{self.class}##{__method__} undefined"
+        end
+
+        # Show a modal dialog and wait for the user to click a button.
+        #
+        # @param message [String]
+        # @param title [String, nil]
+        # @param buttons [Array<String>]
+        # @param default_button [String, nil]
+        # @return [Hash] includes :button with the label of the clicked button
+        def alert(message:, title: nil, buttons: ['OK'], default_button: nil)
+          raise NotImplementedError, "#{self.class}##{__method__} undefined"
+        end
+
+        # Speak text aloud using text-to-speech.
+        #
+        # @param text [String]
+        # @param voice [String, nil]
+        # @param rate [Integer, nil] words per minute
+        # @return [Hash]
+        def speak(text:, voice: nil, rate: nil)
+          raise NotImplementedError, "#{self.class}##{__method__} undefined"
+        end
+
+        protected
+
+        # @param cmd [String]
+        # @return [Boolean]
+        def command_available?(cmd)
+          system("which #{cmd} > /dev/null 2>&1")
+        end
+      end
+    end
+  end
+end