swarm_sdk 3.0.0.alpha1 → 3.0.0.alpha2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 373c4df61931acf2a3ed260a6686068dc918f9d3ad6f3eea746f81a38711e2b5
-  data.tar.gz: 2b5414dd35362e4e58616092717b47b2207dcf54a886c10e74f5408f07686192
+  metadata.gz: 4feb796b3437eea5e610a13ed80923a4d2bda9841fc164d44cb330a5da20e97e
+  data.tar.gz: 3006b77e78aedd12c2371300d6599870aef32f9bf33285c7229ce9eadd453364
 SHA512:
-  metadata.gz: 46a0bba9e559d4acc92dbb5bf68776471bf2409a2aa0cee9b3ed458e0d9028b24b69534b6963a9a1b57de23ff305c9d69c7a927828f80de4de7750561311bb4f
-  data.tar.gz: add457e2f8a04cca43f0fd9f169207695cad562a7f7c0b98a217a002560d335e693cca5ef0a39ad0438a7d0ff818246f97d43a0155d103f9d3944e73cb9e3027
+  metadata.gz: 87bfebe06e4c043c131a6d51d2effe8cd7de7893075593b2b008126887f5837850486c8e354f918ef2fa283c9d286638a25efc632917f0a86ab57815102333ce
+  data.tar.gz: e2afe829f9c2394de45c07eb2b6ff692446ee2108d0b615a375447a87c797bd59b4f0745d96b1c7a8a40b7ef350e167b29c247a7a376ea366feb370ea0eaac1a

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

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module V3
+    module Tools
+      module DocumentConverters
+        # Abstract base class for document converters
+        #
+        # Provides common interface and helpers for converting documents to text.
+        # Each converter checks gem availability and provides clear error messages.
+        class Base
+          class << self
+            # Gem name required for this converter
+            #
+            # @return [String] the gem name
+            # @raise [NotImplementedError] if not implemented by subclass
+            def gem_name
+              raise NotImplementedError, "#{name} must implement .gem_name"
+            end
+
+            # Human-readable format name
+            #
+            # @return [String] the format name (e.g., "PDF", "DOCX")
+            # @raise [NotImplementedError] if not implemented by subclass
+            def format_name
+              raise NotImplementedError, "#{name} must implement .format_name"
+            end
+
+            # File extensions this converter handles
+            #
+            # @return [Array<String>] array of extensions including dot (e.g., [".pdf"])
+            # @raise [NotImplementedError] if not implemented by subclass
+            def extensions
+              raise NotImplementedError, "#{name} must implement .extensions"
+            end
+
+            # Check if required gem is available
+            #
+            # @return [Boolean] true if gem is installed
+            def available?
+              Gem::Specification.find_by_name(gem_name)
+              true
+            rescue Gem::MissingSpecError
+              false
+            end
+          end
+
+          # Convert document to text (possibly with image attachments)
+          #
+          # @param file_path [String] absolute path to document
+          # @return [String, RubyLLM::Content] text or text with image attachments
+          # @raise [NotImplementedError] if not implemented by subclass
+          def convert(file_path)
+            raise NotImplementedError, "#{self.class.name} must implement #convert"
+          end
+
+          protected
+
+          # Return system reminder for missing gem
+          #
+          # @return [String] formatted system reminder message
+          def unsupported_format_message
+            <<~MSG.strip
+              <system-reminder>
+              This is a #{self.class.format_name} document, but the required gem is not installed.
+
+              To enable #{self.class.format_name} reading:
+                gem install #{self.class.gem_name}
+              </system-reminder>
+            MSG
+          end
+
+          # Return formatted error message
+          #
+          # @param message [String] error description
+          # @return [String] formatted error message
+          def error(message)
+            "Error: #{message}"
+          end
+        end
+      end
+    end
+  end
+end

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/read.rb

@@ -7,7 +7,15 @@ module SwarmSDK
       #
       # Supports reading entire files or specific line ranges with line numbers.
       # Tracks reads per agent for enforcing read-before-write/edit rules.
+      # Supports document formats (PDF, DOCX, XLSX) if gems installed.
       class Read < Base
+        # Document converters (optional gems)
+        CONVERTERS = [
+          DocumentConverters::PdfConverter,
+          DocumentConverters::DocxConverter,
+          DocumentConverters::XlsxConverter,
+        ].freeze
+
         class << self
           # @return [Array<Symbol>] Constructor requirements
           def creation_requirements
@@ -19,6 +27,7 @@ module SwarmSDK
           Reads a file from the local filesystem.
 
           Supports text files with line numbers. Binary files (images) are returned as visual content.
+          Supports document formats (PDF, DOCX, XLSX) if gems installed.
 
           Path handling:
           - Relative paths resolve against your working directory
@@ -32,12 +41,12 @@ module SwarmSDK
 
         param :offset,
           type: "integer",
-          desc: "Line number to start reading from (1-indexed). Use for large files.",
+          desc: "Line number to start reading from (1-indexed). Use for large text files. Ignored for documents.",
           required: false
 
         param :limit,
           type: "integer",
-          desc: "Number of lines to read. Use for large files.",
+          desc: "Number of lines to read. Use for large text files. Ignored for documents.",
           required: false
 
         # @param agent_name [Symbol, String] Agent identifier for read tracking
@@ -72,6 +81,20 @@ module SwarmSDK
           return validation_error("File does not exist: #{file_path}") unless File.exist?(resolved_path)
           return validation_error("Path is a directory. Use Bash with ls to list directories.") if File.directory?(resolved_path)
 
+          # Try document converter first
+          converter_class = find_converter(resolved_path)
+          if converter_class
+            result = converter_class.new.convert(resolved_path)
+
+            # Register read for successful conversions
+            unless result.start_with?("<system-reminder>") || result.start_with?("Error:")
+              @read_tracker.register_read(@agent_name, resolved_path)
+            end
+
+            return result
+          end
+
+          # Standard text file handling
           content = read_file_content(resolved_path)
 
           # Binary file — return as-is
@@ -175,6 +198,15 @@ module SwarmSDK
           "\n\n<system-reminder>This file has #{total_lines} lines but only the first #{limit} are shown. " \
             "Use offset and limit parameters to read more.</system-reminder>"
         end
+
+        # Find appropriate document converter for file extension
+        #
+        # @param file_path [String] Resolved file path
+        # @return [Class, nil] Converter class or nil if no match
+        def find_converter(file_path)
+          ext = File.extname(file_path).downcase
+          CONVERTERS.find { |c| c.extensions.include?(ext) }
+        end
       end
     end
   end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: swarm_sdk
 version: !ruby/object:Gem::Version
-  version: 3.0.0.alpha1
+  version: 3.0.0.alpha2
 platform: ruby
 authors:
 - Paulo Arruda
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 1980-01-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
@@ -167,6 +167,10 @@ files:
 - lib/swarm_sdk/v3/tools/base.rb
 - lib/swarm_sdk/v3/tools/bash.rb
 - lib/swarm_sdk/v3/tools/clock.rb
+- lib/swarm_sdk/v3/tools/document_converters/base.rb
+- lib/swarm_sdk/v3/tools/document_converters/docx_converter.rb
+- lib/swarm_sdk/v3/tools/document_converters/pdf_converter.rb
+- lib/swarm_sdk/v3/tools/document_converters/xlsx_converter.rb
 - lib/swarm_sdk/v3/tools/edit.rb
 - lib/swarm_sdk/v3/tools/glob.rb
 - lib/swarm_sdk/v3/tools/grep.rb