swarm_sdk 2.7.14 → 3.0.0.alpha2

data/lib/swarm_sdk/v3/tools/document_converters/docx_converter.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module V3
+    module Tools
+      module DocumentConverters
+        # DOCX document converter
+        #
+        # Converts DOCX files to text and extracts images.
+        # Requires the docx gem (which includes rubyzip).
+        class DocxConverter < Base
+          class << self
+            # @return [String] gem name
+            def gem_name
+              "docx"
+            end
+
+            # @return [String] format name
+            def format_name
+              "DOCX"
+            end
+
+            # @return [Array<String>] supported extensions
+            def extensions
+              [".docx"]
+            end
+          end
+
+          # Convert DOCX to text with optional image attachments
+          #
+          # @param file_path [String] path to DOCX file
+          # @return [String, RubyLLM::Content] text or content with images
+          def convert(file_path)
+            return unsupported_format_message unless self.class.available?
+            return error("Legacy .doc format not supported") if file_path.end_with?(".doc")
+
+            require "docx"
+            doc = Docx::Document.open(file_path)
+
+            # Extract text content
+            output = build_text_output(doc, file_path)
+
+            # Extract images (inline - no separate class)
+            image_paths = extract_images(file_path)
+
+            if image_paths.any?
+              content = RubyLLM::Content.new(output)
+              image_paths.each { |path| content.add_attachment(path) }
+              content
+            else
+              output
+            end
+          rescue StandardError => e
+            error("DOCX conversion failed: #{e.message}")
+          end
+
+          private
+
+          # Build text output from DOCX document
+          #
+          # @param doc [Docx::Document] opened document
+          # @param file_path [String] original file path
+          # @return [String] formatted text output
+          def build_text_output(doc, file_path)
+            output = []
+            output << "DOCX: #{File.basename(file_path)}"
+            output << "=" * 60
+            output << ""
+
+            # Paragraphs
+            doc.paragraphs.each do |para|
+              text = para.text.strip
+              output << text unless text.empty?
+            end
+
+            # Tables
+            doc.tables.each_with_index do |table, idx|
+              output << ""
+              output << "Table #{idx + 1}:"
+              output << "-" * 40
+              table.rows.each do |row|
+                cells = row.cells.map(&:text)
+                output << cells.join(" | ")
+              end
+            end
+
+            output.join("\n")
+          end
+
+          # Extract images from DOCX ZIP (word/media/)
+          #
+          # @param docx_path [String] path to DOCX file
+          # @return [Array<String>] paths to extracted image files
+          def extract_images(docx_path)
+            require "zip"
+            images = []
+            temp_dir = Dir.mktmpdir("docx_#{Process.pid}")
+
+            Zip::File.open(docx_path) do |zip|
+              zip.each do |entry|
+                next unless entry.name.start_with?("word/media/")
+
+                ext = File.extname(entry.name).downcase
+                next unless [".png", ".jpg", ".jpeg", ".gif"].include?(ext)
+
+                path = File.join(temp_dir, File.basename(entry.name))
+                entry.extract(path)
+                images << path
+              end
+            end
+
+            images
+          rescue StandardError
+            [] # Silently ignore extraction failures
+          end
+        end
+      end
+    end
+  end
+end

data/lib/swarm_sdk/v3/tools/document_converters/pdf_converter.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module V3
+    module Tools
+      module DocumentConverters
+        # PDF document converter
+        #
+        # Converts PDF files to text and extracts JPEG images.
+        # Requires the pdf-reader gem.
+        class PdfConverter < Base
+          class << self
+            # @return [String] gem name
+            def gem_name
+              "pdf-reader"
+            end
+
+            # @return [String] format name
+            def format_name
+              "PDF"
+            end
+
+            # @return [Array<String>] supported extensions
+            def extensions
+              [".pdf"]
+            end
+          end
+
+          # Convert PDF to text with optional image attachments
+          #
+          # @param file_path [String] path to PDF file
+          # @return [String, RubyLLM::Content] text or content with images
+          def convert(file_path)
+            return unsupported_format_message unless self.class.available?
+
+            require "pdf-reader"
+            reader = PDF::Reader.new(file_path)
+
+            # Extract text from all pages
+            output = build_text_output(reader, file_path)
+
+            # Extract JPEG images (inline - no separate class)
+            image_paths = extract_jpeg_images(reader)
+
+            # Return with images if any extracted
+            if image_paths.any?
+              content = RubyLLM::Content.new(output)
+              image_paths.each { |path| content.add_attachment(path) }
+              content
+            else
+              output
+            end
+          rescue PDF::Reader::MalformedPDFError => e
+            error("Malformed PDF: #{e.message}")
+          rescue StandardError => e
+            error("PDF conversion failed: #{e.message}")
+          end
+
+          private
+
+          # Build text output from PDF pages
+          #
+          # @param reader [PDF::Reader] initialized reader
+          # @param file_path [String] original file path
+          # @return [String] formatted text output
+          def build_text_output(reader, file_path)
+            output = []
+            output << "PDF: #{File.basename(file_path)}"
+            output << "=" * 60
+            output << "Pages: #{reader.page_count}"
+            output << ""
+
+            reader.pages.each_with_index do |page, idx|
+              output << "Page #{idx + 1}:"
+              output << "-" * 60
+              text = page.text.strip
+              output << (text.empty? ? "(No text)" : text)
+              output << ""
+            end
+
+            output.join("\n")
+          end
+
+          # Extract JPEG images only (LLM API compatible)
+          #
+          # @param reader [PDF::Reader] initialized reader
+          # @return [Array<String>] paths to extracted JPEG files
+          def extract_jpeg_images(reader)
+            images = []
+            temp_dir = Dir.mktmpdir("pdf_#{Process.pid}")
+
+            reader.pages.each_with_index do |page, page_num|
+              page.xobjects.each do |name, stream|
+                next unless stream.hash[:Subtype] == :Image
+                next unless stream.hash[:Filter] == :DCTDecode # JPEG only
+
+                path = File.join(temp_dir, "p#{page_num + 1}_#{name}.jpg")
+                File.binwrite(path, stream.data)
+                images << path
+              end
+            end
+
+            images
+          rescue StandardError
+            [] # Silently ignore extraction failures
+          end
+        end
+      end
+    end
+  end
+end

data/lib/swarm_sdk/v3/tools/document_converters/xlsx_converter.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module V3
+    module Tools
+      module DocumentConverters
+        # XLSX/Spreadsheet converter
+        #
+        # Converts spreadsheet files (XLSX, XLS, ODS) to CSV format.
+        # Requires the roo gem (and roo-xls for legacy XLS support).
+        class XlsxConverter < Base
+          class << self
+            # @return [String] gem name
+            def gem_name
+              "roo"
+            end
+
+            # @return [String] format name
+            def format_name
+              "XLSX/Spreadsheet"
+            end
+
+            # @return [Array<String>] supported extensions
+            def extensions
+              [".xlsx", ".xls", ".ods"]
+            end
+          end
+
+          # Convert spreadsheet to CSV text format
+          #
+          # @param file_path [String] path to spreadsheet file
+          # @return [String] CSV formatted text
+          def convert(file_path)
+            return unsupported_format_message unless self.class.available?
+            return unsupported_xls_message if file_path.end_with?(".xls") && !xls_available?
+
+            require "roo"
+            require "csv"
+
+            spreadsheet = Roo::Spreadsheet.open(file_path)
+            build_csv_output(spreadsheet, file_path)
+          rescue StandardError => e
+            error("Spreadsheet conversion failed: #{e.message}")
+          end
+
+          private
+
+          # Check if roo-xls gem is available for legacy XLS support
+          #
+          # @return [Boolean] true if roo-xls is installed
+          def xls_available?
+            Gem::Specification.find_by_name("roo-xls")
+            true
+          rescue Gem::MissingSpecError
+            false
+          end
+
+          # Return system reminder for missing roo-xls gem
+          #
+          # @return [String] formatted system reminder
+          def unsupported_xls_message
+            <<~MSG.strip
+              <system-reminder>
+              Legacy XLS format requires additional gem.
+
+              To enable XLS support:
+                gem install roo-xls
+
+              Or save as .xlsx format.
+              </system-reminder>
+            MSG
+          end
+
+          # Build CSV output from spreadsheet
+          #
+          # @param spreadsheet [Roo::Spreadsheet] opened spreadsheet
+          # @param file_path [String] original file path
+          # @return [String] formatted CSV output
+          def build_csv_output(spreadsheet, file_path)
+            output = []
+            output << "Spreadsheet: #{File.basename(file_path)}"
+            output << "=" * 60
+            output << ""
+
+            spreadsheet.sheets.each do |sheet_name|
+              spreadsheet.default_sheet = sheet_name
+              rows = spreadsheet.last_row || 0
+              cols = spreadsheet.last_column || 0
+
+              output << "Sheet: #{sheet_name} (#{rows} rows × #{cols} cols)"
+              output << "-" * 60
+
+              # Stream rows for memory efficiency
+              spreadsheet.each_row_streaming do |row|
+                cells = row.map { |cell| format_cell(cell) }
+                output << CSV.generate_line(cells).chomp
+              end
+
+              output << ""
+            end
+
+            output.join("\n")
+          end
+
+          # Format cell based on type
+          #
+          # @param cell [Roo::Cell] cell to format
+          # @return [String] formatted cell value
+          def format_cell(cell)
+            return "" if cell.nil? || cell.value.nil?
+
+            case cell.type
+            when :string then cell.value.to_s
+            when :float, :number then cell.value.to_s
+            when :date then cell.value.strftime("%Y-%m-%d")
+            when :datetime then cell.value.strftime("%Y-%m-%d %H:%M:%S")
+            when :time then cell.value.strftime("%H:%M:%S")
+            when :boolean then cell.value ? "TRUE" : "FALSE"
+            when :formula then cell.value.to_s # Calculated value
+            when :percentage then "#{(cell.value * 100).round(2)}%"
+            else cell.value.to_s
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/swarm_sdk/v3/tools/edit.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module V3
+    module Tools
+      # Edit tool for performing exact string replacements in files
+      #
+      # Uses exact string matching to find and replace content.
+      # Requires the file to have been read first via the Read tool.
+      class Edit < Base
+        class << self
+          # @return [Array<Symbol>] Constructor requirements
+          def creation_requirements
+            [:agent_name, :directory, :read_tracker]
+          end
+        end
+
+        description <<~DESC
+          Performs exact string replacements in files.
+          You must use Read on a file before editing it.
+          The edit will FAIL if old_string is not unique — provide more context or use replace_all.
+
+          Path handling:
+          - Relative paths resolve against your working directory
+          - Absolute paths (starting with /) are used as-is
+        DESC
+
+        param :file_path,
+          type: "string",
+          desc: "Path to the file to edit",
+          required: true
+
+        param :old_string,
+          type: "string",
+          desc: "The exact text to replace (must match exactly including whitespace)",
+          required: true
+
+        param :new_string,
+          type: "string",
+          desc: "The text to replace it with (must be different from old_string)",
+          required: true
+
+        param :replace_all,
+          type: "boolean",
+          desc: "Replace all occurrences of old_string (default false)",
+          required: false
+
+        # @param agent_name [Symbol, String] Agent identifier
+        # @param directory [String] Agent's working directory
+        # @param read_tracker [ReadTracker] Shared read tracker for enforcement
+        def initialize(agent_name:, directory:, read_tracker:)
+          super()
+          @agent_name = agent_name.to_sym
+          @directory = File.expand_path(directory)
+          @read_tracker = read_tracker
+        end
+
+        # Execute file edit
+        #
+        # @param file_path [String] Path to the file
+        # @param old_string [String] Text to find
+        # @param new_string [String] Replacement text
+        # @param replace_all [Boolean] Replace all occurrences
+        # @return [String] Success or error message
+        def execute(file_path:, old_string:, new_string:, replace_all: false)
+          return validation_error("file_path is required") if file_path.nil? || file_path.to_s.strip.empty?
+          return validation_error("old_string is required") if old_string.nil? || old_string.empty?
+          return validation_error("new_string is required") if new_string.nil?
+          return validation_error("old_string and new_string must be different.") if old_string == new_string
+
+          resolved_path = resolve_path(file_path)
+          return validation_error("File does not exist: #{file_path}") unless File.exist?(resolved_path)
+
+          unless @read_tracker.file_read?(@agent_name, resolved_path)
+            return validation_error(
+              "Cannot edit file without reading it first. " \
+                "Use the Read tool on '#{file_path}' before editing.",
+            )
+          end
+
+          content = File.read(resolved_path, encoding: "UTF-8")
+
+          unless content.include?(old_string)
+            return validation_error("old_string not found in file. Make sure it matches exactly, including all whitespace and indentation.")
+          end
+
+          occurrences = content.scan(old_string).count
+
+          if !replace_all && occurrences > 1
+            return validation_error(
+              "Found #{occurrences} occurrences of old_string. " \
+                "Provide more context to make the match unique, or use replace_all: true.",
+            )
+          end
+
+          new_content = replace_all ? content.gsub(old_string, new_string) : content.sub(old_string, new_string)
+          File.write(resolved_path, new_content, encoding: "UTF-8")
+
+          replaced_count = replace_all ? occurrences : 1
+          "Successfully replaced #{replaced_count} occurrence(s) in #{file_path}"
+        rescue Encoding::InvalidByteSequenceError, Encoding::UndefinedConversionError
+          error("File contains invalid UTF-8. Cannot edit binary files.")
+        rescue Errno::EACCES
+          error("Permission denied: Cannot read or write file '#{file_path}'")
+        rescue StandardError => e
+          error("Unexpected error editing file: #{e.class.name} - #{e.message}")
+        end
+      end
+    end
+  end
+end

data/lib/swarm_sdk/v3/tools/glob.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module V3
+    module Tools
+      # Glob tool for fast file pattern matching
+      #
+      # Finds files and directories matching glob patterns, sorted by modification time.
+      class Glob < Base
+        class << self
+          # @return [Array<Symbol>] Constructor requirements
+          def creation_requirements
+            [:directory]
+          end
+        end
+
+        description <<~DESC
+          Fast file pattern matching tool.
+
+          Supports glob patterns like "**/*.js" or "src/**/*.ts".
+          Returns matching file paths sorted by modification time (most recent first).
+        DESC
+
+        param :pattern,
+          type: "string",
+          desc: "The glob pattern to match files against",
+          required: true
+
+        param :path,
+          type: "string",
+          desc: "Directory to search in. Defaults to working directory.",
+          required: false
+
+        # @param directory [String] Working directory for pattern matching
+        def initialize(directory:)
+          super()
+          @directory = File.expand_path(directory)
+        end
+
+        # Execute glob search
+        #
+        # @param pattern [String] Glob pattern
+        # @param path [String, nil] Search directory
+        # @return [String] Matching paths or error
+        def execute(pattern:, path: nil)
+          return validation_error("pattern is required") if pattern.nil? || pattern.to_s.strip.empty?
+
+          search_path = resolve_search_path(path)
+          return search_path if search_path.start_with?("<tool_use_error>")
+
+          full_pattern = pattern.start_with?("/") ? pattern : File.join(search_path, pattern)
+          matches = Dir.glob(full_pattern, File::FNM_DOTMATCH)
+
+          matches.reject! do |f|
+            basename = File.basename(f.chomp("/"))
+            basename == "." || basename == ".."
+          end
+
+          return "No matches found for pattern: #{pattern}" if matches.empty?
+
+          matches.sort_by! { |f| -File.mtime(f).to_i }
+
+          max_results = Configuration.instance.glob_result_limit
+          truncated = matches.count > max_results
+          matches = matches.take(max_results) if truncated
+
+          output = matches.join("\n")
+          output += "\n\n<system-reminder>Results limited to first #{max_results} matches.</system-reminder>" if truncated
+          output
+        rescue Errno::EACCES => e
+          error("Permission denied: #{e.message}")
+        rescue StandardError => e
+          error("Failed to execute glob: #{e.class.name} - #{e.message}")
+        end
+
+        private
+
+        # Resolve search path with validation
+        #
+        # @param path [String, nil] User-provided path
+        # @return [String] Resolved absolute path or validation error
+        def resolve_search_path(path)
+          if path && !path.to_s.strip.empty?
+            return validation_error("Invalid path value.") if ["undefined", "null"].include?(path.to_s.strip.downcase)
+            return validation_error("Path does not exist: #{path}") unless File.exist?(path)
+            return validation_error("Path is not a directory: #{path}") unless File.directory?(path)
+
+            resolve_path(path)
+          else
+            @directory
+          end
+        end
+      end
+    end
+  end
+end