swarm_sdk 2.0.0.pre.2

data/lib/swarm_sdk/tools/grep.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Tools
+    # Grep tool for searching file contents using ripgrep-style patterns
+    #
+    # Powerful search capabilities with regex support, context lines, and filtering.
+    # Built on ripgrep (rg) for fast, efficient searching.
+    class Grep < RubyLLM::Tool
+      include PathResolver
+
+      def initialize(directory:)
+        super()
+        @directory = File.expand_path(directory)
+      end
+
+      define_method(:name) { "Grep" }
+
+      description <<~DESC
+        A powerful search tool built on ripgrep
+
+        Usage:
+        - ALWAYS use Grep for search tasks. NEVER invoke `grep` or `rg` as a Bash command. The Grep tool has been optimized for correct permissions and access.
+        - Supports full regex syntax (e.g., "log.*Error", "function\\s+\\w+")
+        - Filter files with glob parameter (e.g., "*.js", "**/*.tsx") or type parameter (e.g., "js", "py", "rust")
+        - Output modes: "content" shows matching lines, "files_with_matches" shows only file paths (default), "count" shows match counts
+        - Use Task tool for open-ended searches requiring multiple rounds
+        - Pattern syntax: Uses ripgrep (not grep) - literal braces need escaping (use `interface\\{\\}` to find `interface{}` in Go code)
+        - Multiline matching: By default patterns match within single lines only. For cross-line patterns like `struct \\{[\\s\\S]*?field`, use `multiline: true`
+      DESC
+
+      param :pattern,
+        type: "string",
+        desc: "The regular expression pattern to search for in file contents",
+        required: true
+
+      param :path,
+        type: "string",
+        desc: "File or directory to search in (rg PATH). Defaults to current working directory.",
+        required: false
+
+      param :glob,
+        type: "string",
+        desc: "Glob pattern to filter files (e.g. \"*.js\", \"*.{ts,tsx}\") - maps to rg --glob",
+        required: false
+
+      param :type,
+        type: "string",
+        desc: "File type to search (rg --type). Common types: js, py, rust, go, java, etc.",
+        required: false
+
+      param :output_mode,
+        type: "string",
+        desc: "Output mode: \"content\" shows matching lines (supports -A/-B/-C context, -n line numbers, head_limit), \"files_with_matches\" shows file paths (supports head_limit), \"count\" shows match counts (supports head_limit). Defaults to \"files_with_matches\".",
+        required: false
+
+      param :"-i",
+        type: "boolean",
+        desc: "Case insensitive search (rg -i)",
+        required: false
+
+      param :multiline,
+        type: "boolean",
+        desc: "Enable multiline mode where . matches newlines and patterns can span lines (rg -U --multiline-dotall)",
+        required: false
+
+      param :"-B",
+        type: "integer",
+        desc: "Number of lines to show before each match (rg -B). Requires output_mode: \"content\", ignored otherwise.",
+        required: false
+
+      param :"-A",
+        type: "integer",
+        desc: "Number of lines to show after each match (rg -A). Requires output_mode: \"content\", ignored otherwise.",
+        required: false
+
+      param :"-C",
+        type: "integer",
+        desc: "Number of lines to show before and after each match (rg -C). Requires output_mode: \"content\", ignored otherwise.",
+        required: false
+
+      param :"-n",
+        type: "boolean",
+        desc: "Show line numbers in output (rg -n). Requires output_mode: \"content\", ignored otherwise.",
+        required: false
+
+      param :head_limit,
+        type: "integer",
+        desc: "Limit output to first N lines/entries, equivalent to \"| head -N\". Works across all output modes: content (limits output lines), files_with_matches (limits file paths), count (limits count entries). When unspecified, shows all results from ripgrep.",
+        required: false
+
+      def execute(
+        pattern:,
+        path: nil,
+        glob: nil,
+        type: nil,
+        output_mode: "files_with_matches",
+        **options
+      )
+        # Validate inputs
+        return validation_error("pattern is required") if pattern.nil? || pattern.empty?
+
+        # CRITICAL: Default path to agent's directory (NOT current directory)
+        path = if path.nil? || path.to_s.strip.empty?
+          @directory
+        else
+          # Resolve relative paths against agent directory
+          resolve_path(path)
+        end
+
+        # Extract options with their flag names
+        case_insensitive = options["-i"] || false
+        multiline = options[:multiline] || false
+        context_before = options["-B"]
+        context_after = options["-A"]
+        context = options["-C"]
+        line_numbers = options["-n"] || false
+        head_limit = options[:head_limit]
+
+        # Validate output_mode
+        valid_modes = ["content", "files_with_matches", "count"]
+        unless valid_modes.include?(output_mode)
+          return validation_error("output_mode must be one of: #{valid_modes.join(", ")}")
+        end
+
+        # Build ripgrep command
+        cmd = ["rg"]
+
+        # Output mode flags
+        case output_mode
+        when "files_with_matches"
+          cmd << "-l" # List files with matches
+        when "count"
+          cmd << "-c" # Count matches per file
+        when "content"
+          # Default mode, no special flag needed
+          # Add line numbers if requested
+          cmd << "-n" if line_numbers
+
+          # Add context flags
+          cmd << "-B" << context_before.to_s if context_before
+          cmd << "-A" << context_after.to_s if context_after
+          cmd << "-C" << context.to_s if context
+        end
+
+        # Case sensitivity
+        cmd << "-i" if case_insensitive
+
+        # Multiline mode
+        if multiline
+          cmd << "-U" << "--multiline-dotall"
+        end
+
+        # File filtering (only add if non-empty)
+        cmd << "--type" << type if type && !type.to_s.strip.empty?
+        cmd << "--glob" << glob if glob && !glob.to_s.strip.empty?
+
+        # Pattern
+        cmd << "-e" << pattern
+
+        # Path
+        cmd << path
+
+        # Execute command
+        begin
+          require "open3"
+
+          stdout, stderr, status = Open3.capture3(*cmd)
+
+          # Handle no matches (exit code 1 for ripgrep means no matches found)
+          if status.exitstatus == 1 && stderr.empty?
+            return "No matches found for pattern: #{pattern}"
+          end
+
+          # Handle errors (exit code 2 means error)
+          if status.exitstatus == 2 || !stderr.empty?
+            return error("ripgrep error: #{stderr}")
+          end
+
+          # Success - format output
+          output = stdout
+
+          # Apply head_limit if specified
+          if head_limit && head_limit > 0
+            lines = output.lines
+            if lines.count > head_limit
+              output = lines.take(head_limit).join
+              output += "\n\n<system-reminder>Output limited to first #{head_limit} lines. Total results: #{lines.count} lines.</system-reminder>"
+            end
+          end
+
+          # Add reminder about usage
+          reminder = build_usage_reminder(output_mode, pattern)
+          output = "#{output}\n\n#{reminder}" unless reminder.empty?
+
+          output.empty? ? "No matches found for pattern: #{pattern}" : output
+        rescue Errno::ENOENT
+          error("ripgrep (rg) is not installed or not in PATH. Please install ripgrep to use the Grep tool.")
+        rescue Errno::EACCES
+          error("Permission denied: Cannot search in '#{path}'")
+        rescue StandardError => e
+          error("Failed to execute search: #{e.class.name} - #{e.message}")
+        end
+      rescue StandardError => e
+        error("Unexpected error during search: #{e.class.name} - #{e.message}")
+      end
+
+      private
+
+      def validation_error(message)
+        "<tool_use_error>InputValidationError: #{message}</tool_use_error>"
+      end
+
+      def error(message)
+        "Error: #{message}"
+      end
+
+      def build_usage_reminder(output_mode, pattern)
+        return "" if output_mode == "content"
+
+        <<~REMINDER
+          <system-reminder>
+          You used output_mode: '#{output_mode}' which only shows #{output_mode == "files_with_matches" ? "file paths" : "match counts"}.
+          To see the actual matching lines and their content, use output_mode: 'content'.
+          You can also add -n: true and context lines (-B, -A, or -C) for better context.
+          </system-reminder>
+        REMINDER
+      end
+    end
+  end
+end

data/lib/swarm_sdk/tools/image_extractors/docx_image_extractor.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Tools
+    module ImageExtractors
+      # Extracts images from DOCX documents
+      # DOCX files are ZIP archives with images stored in word/media/
+      class DocxImageExtractor
+        class << self
+          # Extract all images from a DOCX document
+          # @param doc [Docx::Document] The DOCX document instance
+          # @param docx_path [String] Path to the DOCX file
+          # @return [Array<String>] Array of temporary file paths containing extracted images
+          def extract_images(doc, docx_path)
+            image_paths = []
+            temp_dir = Dir.mktmpdir("docx_images_#{File.basename(docx_path, ".*")}")
+
+            # DOCX files are ZIP archives with images in word/media/
+            doc.zip.glob("word/media/*").each do |entry|
+              next unless entry.file?
+
+              # Check if it's an image by extension
+              next unless entry.name.match?(/\.(png|jpe?g|gif|bmp|tiff?)$/i)
+
+              output_path = File.join(temp_dir, File.basename(entry.name))
+
+              File.open(output_path, "wb") do |f|
+                f.write(doc.zip.read(entry.name))
+              end
+
+              image_paths << output_path
+            end
+
+            image_paths
+          rescue StandardError
+            # If image extraction fails, don't fail the entire document read
+            []
+          end
+        end
+      end
+    end
+  end
+end

data/lib/swarm_sdk/tools/image_extractors/pdf_image_extractor.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Tools
+    module ImageExtractors
+      # Extracts images from PDF documents
+      # Supports JPEG (DCTDecode), FlateDecode, and LZWDecode formats
+      # Converts non-JPEG images to TIFF format
+      class PdfImageExtractor
+        class << self
+          # Extract all images from a PDF document
+          # @param reader [PDF::Reader] The PDF reader instance
+          # @param pdf_path [String] Path to the PDF file
+          # @return [Array<String>] Array of temporary file paths containing extracted images
+          def extract_images(reader, pdf_path)
+            image_paths = []
+            temp_dir = Dir.mktmpdir("pdf_images_#{File.basename(pdf_path, ".*")}")
+
+            reader.pages.each_with_index do |page, page_index|
+              page_images = extract_from_page(page, page_index + 1, temp_dir)
+              image_paths.concat(page_images)
+            end
+
+            image_paths
+          rescue StandardError
+            # If image extraction fails, log it but don't fail the entire PDF read
+            []
+          end
+
+          # Extract images from a single PDF page
+          # @param page [PDF::Reader::Page] The PDF page
+          # @param page_number [Integer] Page number (1-indexed)
+          # @param temp_dir [String] Directory to save extracted images
+          # @return [Array<String>] Array of file paths for extracted images
+          def extract_from_page(page, page_number, temp_dir)
+            extracted_files = []
+
+            # Get XObjects (external objects) from the page
+            xobjects = page.xobjects
+            return extracted_files if xobjects.empty?
+
+            xobjects.each do |name, stream|
+              # Only process Image XObjects (not Form XObjects)
+              next unless stream.hash[:Subtype] == :Image
+
+              file_path = save_image(stream, page_number, name, temp_dir)
+              extracted_files << file_path if file_path
+            end
+
+            extracted_files
+          rescue StandardError
+            # If extraction fails for this page, continue with others
+            []
+          end
+
+          # Save a PDF image stream to disk
+          # Supports JPEG (DCTDecode) and raw formats
+          # @param stream [PDF::Reader::Stream] The image stream
+          # @param page_number [Integer] Page number
+          # @param name [Symbol] Image name from XObject
+          # @param temp_dir [String] Directory to save the image
+          # @return [String, nil] File path if successful, nil otherwise
+          def save_image(stream, page_number, name, temp_dir)
+            filter = stream.hash[:Filter]
+
+            case filter
+            when :DCTDecode
+              # JPEG images can be saved directly
+              save_jpeg(stream, page_number, name, temp_dir)
+            when :FlateDecode, :LZWDecode, nil
+              # Raw or compressed formats - save as TIFF
+              save_as_tiff(stream, page_number, name, temp_dir)
+            end
+            # Unsupported formats return nil
+          rescue StandardError
+            # If saving fails, skip this image
+            nil
+          end
+
+          # Save JPEG image directly from PDF stream
+          # @param stream [PDF::Reader::Stream] The image stream
+          # @param page_number [Integer] Page number
+          # @param name [Symbol] Image name
+          # @param temp_dir [String] Directory to save the image
+          # @return [String] File path
+          def save_jpeg(stream, page_number, name, temp_dir)
+            filename = File.join(temp_dir, "page-#{page_number}-#{name}.jpg")
+
+            # JPEG images can be written directly - the stream.data contains a complete JPEG file
+            File.open(filename, "wb") do |file|
+              file.write(stream.data)
+            end
+
+            filename
+          end
+
+          # Save raw image data as TIFF
+          # @param stream [PDF::Reader::Stream] The image stream
+          # @param page_number [Integer] Page number
+          # @param name [Symbol] Image name
+          # @param temp_dir [String] Directory to save the image
+          # @return [String, nil] File path if successful, nil for unsupported color spaces
+          def save_as_tiff(stream, page_number, name, temp_dir)
+            color_space = stream.hash[:ColorSpace]
+
+            case color_space
+            when :DeviceRGB
+              save_rgb_tiff(stream, page_number, name, temp_dir)
+            when :DeviceGray
+              save_gray_tiff(stream, page_number, name, temp_dir)
+            end
+            # Unsupported color spaces return nil
+          rescue StandardError
+            # If conversion fails, skip this image
+            nil
+          end
+
+          # Save RGB image as TIFF
+          # @param stream [PDF::Reader::Stream] The image stream
+          # @param page_number [Integer] Page number
+          # @param name [Symbol] Image name
+          # @param temp_dir [String] Directory to save the image
+          # @return [String] File path
+          def save_rgb_tiff(stream, page_number, name, temp_dir)
+            filename = File.join(temp_dir, "page-#{page_number}-#{name}.tif")
+
+            width = stream.hash[:Width]
+            height = stream.hash[:Height]
+            bpc = stream.hash[:BitsPerComponent] || 8
+
+            # Build TIFF header
+            tiff = ImageFormats::TiffBuilder.build_rgb_header(width, height, bpc)
+            tiff << stream.unfiltered_data # Get decompressed raw pixel data
+
+            File.open(filename, "wb") { |file| file.write(tiff) }
+            filename
+          end
+
+          # Save grayscale image as TIFF
+          # @param stream [PDF::Reader::Stream] The image stream
+          # @param page_number [Integer] Page number
+          # @param name [Symbol] Image name
+          # @param temp_dir [String] Directory to save the image
+          # @return [String] File path
+          def save_gray_tiff(stream, page_number, name, temp_dir)
+            filename = File.join(temp_dir, "page-#{page_number}-#{name}.tif")
+
+            width = stream.hash[:Width]
+            height = stream.hash[:Height]
+            bpc = stream.hash[:BitsPerComponent] || 8
+
+            # Build TIFF header for grayscale
+            tiff = ImageFormats::TiffBuilder.build_gray_header(width, height, bpc)
+            tiff << stream.unfiltered_data
+
+            File.open(filename, "wb") { |file| file.write(tiff) }
+            filename
+          end
+        end
+      end
+    end
+  end
+end

data/lib/swarm_sdk/tools/image_formats/tiff_builder.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Tools
+    module ImageFormats
+      # Builds TIFF image files from raw pixel data
+      # Supports RGB and grayscale color spaces
+      class TiffBuilder
+        class << self
+          # Build TIFF header for RGB images
+          # @param width [Integer] Image width in pixels
+          # @param height [Integer] Image height in pixels
+          # @param bpc [Integer] Bits per component (typically 8)
+          # @return [String] Binary TIFF header
+          def build_rgb_header(width, height, bpc)
+            # Helper lambdas for TIFF tags
+            long_tag  = ->(tag, count, value) { [tag, 4, count, value].pack("ssII") }
+            short_tag = ->(tag, count, value) { [tag, 3, count, value].pack("ssII") }
+
+            tag_count = 8
+            header = [73, 73, 42, 8, tag_count].pack("ccsIs") # Little-endian TIFF
+
+            tiff = header.dup
+            tiff << short_tag.call(256, 1, width)                             # ImageWidth
+            tiff << short_tag.call(257, 1, height)                            # ImageHeight
+            tiff << long_tag.call(258, 3, header.size + (tag_count * 12) + 4) # BitsPerSample
+            tiff << short_tag.call(259, 1, 1)                                 # Compression (none)
+            tiff << short_tag.call(262, 1, 2)                                 # PhotometricInterpretation (RGB)
+            tiff << long_tag.call(273, 1, header.size + (tag_count * 12) + 16) # StripOffsets
+            tiff << short_tag.call(277, 1, 3)                                 # SamplesPerPixel
+            tiff << long_tag.call(279, 1, width * height * 3)                 # StripByteCounts
+            tiff << [0].pack("I")                                             # Next IFD pointer
+            tiff << [bpc, bpc, bpc].pack("III")                               # BitsPerSample values
+            tiff
+          end
+
+          # Build TIFF header for grayscale images
+          # @param width [Integer] Image width in pixels
+          # @param height [Integer] Image height in pixels
+          # @param bpc [Integer] Bits per component (typically 8)
+          # @return [String] Binary TIFF header
+          def build_gray_header(width, height, bpc)
+            long_tag  = ->(tag, count, value) { [tag, 4, count, value].pack("ssII") }
+            short_tag = ->(tag, count, value) { [tag, 3, count, value].pack("ssII") }
+
+            tag_count = 8
+            header = [73, 73, 42, 8, tag_count].pack("ccsIs")
+
+            tiff = header.dup
+            tiff << short_tag.call(256, 1, width)                             # ImageWidth
+            tiff << short_tag.call(257, 1, height)                            # ImageHeight
+            tiff << short_tag.call(258, 1, bpc)                               # BitsPerSample
+            tiff << short_tag.call(259, 1, 1)                                 # Compression (none)
+            tiff << short_tag.call(262, 1, 1)                                 # PhotometricInterpretation (MinIsBlack)
+            tiff << long_tag.call(273, 1, header.size + (tag_count * 12) + 4) # StripOffsets
+            tiff << short_tag.call(277, 1, 1)                                 # SamplesPerPixel
+            tiff << long_tag.call(279, 1, width * height)                     # StripByteCounts
+            tiff << [0].pack("I")                                             # Next IFD pointer
+            tiff
+          end
+        end
+      end
+    end
+  end
+end