swarm_sdk 3.0.0.alpha1 → 3.0.0.alpha3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 373c4df61931acf2a3ed260a6686068dc918f9d3ad6f3eea746f81a38711e2b5
-  data.tar.gz: 2b5414dd35362e4e58616092717b47b2207dcf54a886c10e74f5408f07686192
+  metadata.gz: 569ac707625b9bcfc78080af26a7c1d48895b5057302c23f98543b9b44e6a706
+  data.tar.gz: ab685ff041e4106046ce4da5e4ec9b3937fd4d6290e1f5deeb7d7991f579da6b
 SHA512:
-  metadata.gz: 46a0bba9e559d4acc92dbb5bf68776471bf2409a2aa0cee9b3ed458e0d9028b24b69534b6963a9a1b57de23ff305c9d69c7a927828f80de4de7750561311bb4f
-  data.tar.gz: add457e2f8a04cca43f0fd9f169207695cad562a7f7c0b98a217a002560d335e693cca5ef0a39ad0438a7d0ff818246f97d43a0155d103f9d3944e73cb9e3027
+  metadata.gz: fd68128f22e9758ae66548a4ae2f48b210e92b2c79f4bd78c46fd47cd1d34a9d282740ee35881c27c515ac7eb8b294db6f36c8a70e762ea01ad1d52085da0b5b
+  data.tar.gz: d802eb7a4112874bf7b2ad414564af4fb9806074b8d8d108a471efc33943133942ee646360c7f4ce8390728d44cc031cede119fca993a79a8c6f1e6a7a6c7ee1

data/lib/swarm_sdk/v3/agent.rb

@@ -305,6 +305,77 @@ module SwarmSDK
         false
       end
 
+      # Run an iterative refinement loop over the agent
+      #
+      # Executes a kickoff prompt followed by repeated iterate prompts,
+      # optionally checking for convergence via embedding similarity
+      # between consecutive responses. Each iteration is a normal ask()
+      # call — hooks fire, memory ingests, and events stream normally.
+      #
+      # @param kickoff [String] Prompt for the first iteration
+      # @param iterate [String] Prompt for subsequent iterations
+      # @param max_iterations [Integer] Maximum number of iterations (>= 1)
+      # @param convergence_threshold [Float] Similarity threshold for convergence (0.0..1.0)
+      # @param converge [Boolean] Whether to check for convergence via embeddings
+      # @yield [event] Optional block receives ALL events (content_chunk, loop_*, etc.)
+      # @yieldparam event [Hash] Event hash with :type, :timestamp, and event-specific fields
+      # @return [Loop::Result] Aggregate result with iterations and convergence status
+      #
+      # @example Basic iterative refinement
+      #   result = agent.loop(
+      #     kickoff: "Write a poem about the sea",
+      #     iterate: "Improve the poem, making it more vivid",
+      #     max_iterations: 5,
+      #   )
+      #   puts result.final_response.content
+      #   puts "Converged: #{result.converged?}"
+      #
+      # @example Without convergence checking
+      #   result = agent.loop(
+      #     kickoff: "Draft an outline",
+      #     iterate: "Expand the next section",
+      #     max_iterations: 3,
+      #     converge: false,
+      #   )
+      #
+      # @example With event streaming
+      #   agent.loop(kickoff: "Start", iterate: "Continue", max_iterations: 5) do |event|
+      #     case event[:type]
+      #     when "loop_iteration_completed"
+      #       puts "Iteration #{event[:iteration]}, delta: #{event[:delta_score]}"
+      #     when "content_chunk"
+      #       print event[:content]
+      #     end
+      #   end
+      #
+      # @raise [ArgumentError] If max_iterations < 1 or convergence_threshold out of range
+      def loop(kickoff:, iterate:, max_iterations: 10, convergence_threshold: 0.95, converge: true, &block)
+        validate_loop_params!(max_iterations, convergence_threshold)
+
+        embedder = converge ? loop_embedder : nil
+        ask_callable = ->(prompt) { ask(prompt, &block) }
+
+        executor = Loop::Executor.new(
+          ask_callable: ask_callable,
+          embedder: embedder,
+          agent_id: @id,
+        )
+
+        # Wrap with block emitter so loop lifecycle events
+        # (loop_started, loop_iteration_completed, loop_completed)
+        # reach the caller's block. Each ask() inside the executor
+        # will also set/restore the block emitter for its own events.
+        with_block_emitter(block) do
+          executor.run(
+            kickoff: kickoff,
+            iterate: iterate,
+            max_iterations: max_iterations,
+            convergence_threshold: convergence_threshold,
+            converge: converge,
+          )
+        end
+      end
+
       # Run memory defragmentation (compression, consolidation, promotion, pruning)
       #
       # Call this between sessions, on a schedule, or whenever appropriate.
@@ -1160,6 +1231,33 @@ module SwarmSDK
         @mcp_connectors.each(&:disconnect!)
         @mcp_connectors.clear
       end
+
+      # Validate loop parameters
+      #
+      # @param max_iterations [Integer] Must be >= 1
+      # @param convergence_threshold [Float] Must be between 0.0 and 1.0
+      # @raise [ArgumentError] If parameters are invalid
+      # @return [void]
+      def validate_loop_params!(max_iterations, convergence_threshold)
+        unless max_iterations.is_a?(Integer) && max_iterations >= 1
+          raise ArgumentError, "max_iterations must be an integer >= 1, got #{max_iterations.inspect}"
+        end
+
+        unless convergence_threshold.is_a?(Numeric) && convergence_threshold >= 0.0 && convergence_threshold <= 1.0
+          raise ArgumentError,
+            "convergence_threshold must be between 0.0 and 1.0, got #{convergence_threshold.inspect}"
+        end
+      end
+
+      # Resolve or create an embedder for loop convergence detection
+      #
+      # Reuses the memory store's embedder if available (ONNX model
+      # already loaded), otherwise creates a standalone instance.
+      #
+      # @return [Memory::Embedder]
+      def loop_embedder
+        @memory_store&.embedder || Memory::Embedder.new
+      end
     end
   end
 end

data/lib/swarm_sdk/v3/loop/executor.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module V3
+    module Loop
+      # Core loop engine for iterative refinement
+      #
+      # Runs a sequence of ask() calls through a provided callable,
+      # optionally checking for convergence via embedding similarity
+      # between consecutive responses. Emits events for each iteration
+      # and the overall loop lifecycle.
+      #
+      # The Executor is stateless between runs — all configuration is
+      # passed to {#run}. The ask callable and embedder are injected
+      # at construction for testability.
+      #
+      # @example Basic usage (called internally by Agent#loop)
+      #   executor = Executor.new(
+      #     ask_callable: ->(prompt) { agent.ask(prompt) },
+      #     embedder: Memory::Embedder.new,
+      #     agent_id: "writer_abc123",
+      #   )
+      #   result = executor.run(
+      #     kickoff: "Write a poem about the sea",
+      #     iterate: "Improve the poem",
+      #     max_iterations: 5,
+      #     convergence_threshold: 0.95,
+      #     converge: true,
+      #   )
+      class Executor
+        include Memory::Adapters::VectorUtils
+
+        # Create a new Executor
+        #
+        # @param ask_callable [#call] Lambda wrapping agent.ask(prompt)
+        # @param embedder [Memory::Embedder, nil] Embedder for convergence detection (nil if converge: false)
+        # @param agent_id [String] Agent identifier for event emission
+        def initialize(ask_callable:, embedder:, agent_id:)
+          @ask_callable = ask_callable
+          @embedder = embedder
+          @agent_id = agent_id
+        end
+
+        # Execute the iterative loop
+        #
+        # Runs the kickoff prompt first, then the iterate prompt for
+        # subsequent iterations. If convergence checking is enabled,
+        # computes embedding similarity between consecutive responses
+        # and stops when it exceeds the threshold.
+        #
+        # @param kickoff [String] Prompt for the first iteration
+        # @param iterate [String] Prompt for subsequent iterations
+        # @param max_iterations [Integer] Maximum number of iterations (>= 1)
+        # @param convergence_threshold [Float] Similarity threshold for convergence (0.0..1.0)
+        # @param converge [Boolean] Whether to check for convergence
+        # @return [Result] Aggregate result with all iterations
+        #
+        # @example Run with convergence
+        #   result = executor.run(
+        #     kickoff: "Draft an essay",
+        #     iterate: "Revise and improve",
+        #     max_iterations: 10,
+        #     convergence_threshold: 0.95,
+        #     converge: true,
+        #   )
+        #   result.converged?  #=> true or false
+        def run(kickoff:, iterate:, max_iterations:, convergence_threshold:, converge:)
+          EventStream.emit(
+            type: "loop_started",
+            agent: @agent_id,
+            max_iterations: max_iterations,
+            convergence_threshold: convergence_threshold,
+          )
+
+          iterations = []
+          converged = false
+          previous_content = nil
+
+          max_iterations.times do |index|
+            prompt = index.zero? ? kickoff : iterate
+            response = @ask_callable.call(prompt)
+
+            # Handle interrupted agent (ask() returns nil)
+            break if response.nil?
+
+            current_content = response.content.to_s
+            input_tokens = response.respond_to?(:input_tokens) ? (response.input_tokens || 0) : 0
+            output_tokens = response.respond_to?(:output_tokens) ? (response.output_tokens || 0) : 0
+
+            delta_score = nil
+            if converge && previous_content && @embedder
+              delta_score = compute_delta(previous_content, current_content)
+            end
+
+            iteration = Iteration.new(
+              number: index + 1,
+              response: response,
+              prompt: prompt,
+              tokens: { input: input_tokens, output: output_tokens },
+              delta_score: delta_score,
+            )
+            iterations << iteration
+
+            EventStream.emit(
+              type: "loop_iteration_completed",
+              agent: @agent_id,
+              iteration: index + 1,
+              delta_score: delta_score,
+              converged: false,
+            )
+
+            if delta_score && delta_score >= convergence_threshold
+              converged = true
+              break
+            end
+
+            previous_content = current_content
+          end
+
+          EventStream.emit(
+            type: "loop_completed",
+            agent: @agent_id,
+            iterations: iterations.size,
+            converged: converged,
+          )
+
+          Result.new(iterations: iterations, converged: converged)
+        end
+
+        private
+
+        # Compute cosine similarity between two response texts
+        #
+        # Uses batch embedding for efficiency — both texts are embedded
+        # in a single call to the underlying model.
+        #
+        # @param previous_content [String] Previous iteration's response text
+        # @param current_content [String] Current iteration's response text
+        # @return [Float] Cosine similarity (0.0..1.0 for typical text)
+        def compute_delta(previous_content, current_content)
+          vectors = @embedder.embed_batch([previous_content, current_content])
+          similarity(vectors[0], vectors[1])
+        end
+      end
+    end
+  end
+end

data/lib/swarm_sdk/v3/loop/iteration.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module V3
+    module Loop
+      # Immutable record of a single loop iteration
+      #
+      # Captures the prompt sent, the LLM response received, token usage,
+      # and the embedding-similarity delta from the previous iteration.
+      # Frozen on creation to prevent accidental mutation.
+      #
+      # @example First iteration (no delta)
+      #   iteration = Iteration.new(
+      #     number: 1,
+      #     response: response,
+      #     prompt: "Write a poem",
+      #     tokens: { input: 10, output: 20 },
+      #     delta_score: nil,
+      #   )
+      #
+      # @example Subsequent iteration with convergence score
+      #   iteration = Iteration.new(
+      #     number: 2,
+      #     response: response,
+      #     prompt: "Improve the poem",
+      #     tokens: { input: 15, output: 25 },
+      #     delta_score: 0.87,
+      #   )
+      class Iteration
+        # @return [Integer] 1-indexed iteration number
+        attr_reader :number
+
+        # @return [RubyLLM::Message] LLM response from ask()
+        attr_reader :response
+
+        # @return [String] Prompt used for this iteration (kickoff or iterate)
+        attr_reader :prompt
+
+        # @return [Hash{Symbol => Integer}] Token usage { input:, output: }
+        attr_reader :tokens
+
+        # @return [Float, nil] Cosine similarity to previous iteration (nil for iteration 1)
+        attr_reader :delta_score
+
+        # Create a new Iteration record
+        #
+        # @param number [Integer] 1-indexed iteration number
+        # @param response [RubyLLM::Message] LLM response
+        # @param prompt [String] Prompt used
+        # @param tokens [Hash{Symbol => Integer}] Token usage { input:, output: }
+        # @param delta_score [Float, nil] Similarity to previous iteration
+        def initialize(number:, response:, prompt:, tokens:, delta_score:)
+          @number = number
+          @response = response
+          @prompt = prompt
+          @tokens = tokens.freeze
+          @delta_score = delta_score
+          freeze
+        end
+      end
+    end
+  end
+end

data/lib/swarm_sdk/v3/loop/result.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module V3
+    module Loop
+      # Aggregate result of a completed loop execution
+      #
+      # Contains all iterations and whether the loop converged.
+      # Frozen on creation — both the Result and its iterations array
+      # are immutable after construction.
+      #
+      # @example Converged loop
+      #   result = executor.run(kickoff: "Write a poem", iterate: "Improve it", ...)
+      #   result.converged?       #=> true
+      #   result.iteration_count  #=> 3
+      #   result.final_response   #=> RubyLLM::Message
+      #   result.total_tokens     #=> { input: 45, output: 60 }
+      #
+      # @example Non-converged loop (hit max_iterations)
+      #   result.converged?       #=> false
+      #   result.iteration_count  #=> 10
+      class Result
+        # @return [Array<Iteration>] All iterations (frozen)
+        attr_reader :iterations
+
+        # @return [Boolean] Whether the loop converged below the threshold
+        attr_reader :converged
+        alias_method :converged?, :converged
+
+        # Create a new Result
+        #
+        # @param iterations [Array<Iteration>] Completed iterations
+        # @param converged [Boolean] Whether convergence was detected
+        def initialize(iterations:, converged:)
+          @iterations = iterations.freeze
+          @converged = converged
+          freeze
+        end
+
+        # The last iteration's LLM response
+        #
+        # @return [RubyLLM::Message, nil] Final response, or nil if no iterations
+        #
+        # @example
+        #   puts result.final_response.content
+        def final_response
+          @iterations.last&.response
+        end
+
+        # Number of iterations executed
+        #
+        # @return [Integer]
+        #
+        # @example
+        #   result.iteration_count  #=> 3
+        def iteration_count
+          @iterations.size
+        end
+
+        # Aggregate token usage across all iterations
+        #
+        # @return [Hash{Symbol => Integer}] { input:, output: }
+        #
+        # @example
+        #   result.total_tokens  #=> { input: 45, output: 60 }
+        def total_tokens
+          input = @iterations.sum { |i| i.tokens[:input] }
+          output = @iterations.sum { |i| i.tokens[:output] }
+          { input: input, output: output }
+        end
+      end
+    end
+  end
+end

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.alpha3
 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
@@ -139,6 +139,9 @@ files:
 - lib/swarm_sdk/v3/hooks/context.rb
 - lib/swarm_sdk/v3/hooks/result.rb
 - lib/swarm_sdk/v3/hooks/runner.rb
+- lib/swarm_sdk/v3/loop/executor.rb
+- lib/swarm_sdk/v3/loop/iteration.rb
+- lib/swarm_sdk/v3/loop/result.rb
 - lib/swarm_sdk/v3/mcp/connector.rb
 - lib/swarm_sdk/v3/mcp/mcp_error.rb
 - lib/swarm_sdk/v3/mcp/server_definition.rb
@@ -167,6 +170,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