swarm_memory 2.1.4 → 2.1.6

data/lib/swarm_sdk/tools/delegate.rb

@@ -1,267 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Tools
-    # Delegate tool for working with other agents in the swarm
-    #
-    # Creates agent-specific collaboration tools (e.g., WorkWithBackend)
-    # that allow one agent to work with another agent.
-    # Supports pre/post delegation hooks for customization.
-    class Delegate < RubyLLM::Tool
-      # Tool name prefix for delegation tools
-      # Change this to customize the tool naming pattern (e.g., "DelegateTaskTo", "AskAgent", etc.)
-      TOOL_NAME_PREFIX = "WorkWith"
-
-      class << self
-        # Generate tool name for a delegate agent
-        #
-        # This is the single source of truth for delegation tool naming.
-        # Used both when creating Delegate instances and when predicting tool names
-        # for agent context setup.
-        #
-        # @param delegate_name [String, Symbol] Name of the delegate agent
-        # @return [String] Tool name (e.g., "WorkWithBackend")
-        def tool_name_for(delegate_name)
-          "#{TOOL_NAME_PREFIX}#{delegate_name.to_s.capitalize}"
-        end
-      end
-
-      attr_reader :delegate_name, :delegate_target, :tool_name
-
-      # Initialize a delegation tool
-      #
-      # @param delegate_name [String] Name of the delegate agent (e.g., "backend")
-      # @param delegate_description [String] Description of the delegate agent
-      # @param delegate_chat [AgentChat, nil] The chat instance for the delegate agent (nil if delegating to swarm)
-      # @param agent_name [Symbol, String] Name of the agent using this tool
-      # @param swarm [Swarm] The swarm instance (provides hook_registry, delegation_call_stack, swarm_registry)
-      # @param delegating_chat [Agent::Chat, nil] The chat instance of the agent doing the delegating (for accessing hooks)
-      def initialize(
-        delegate_name:,
-        delegate_description:,
-        delegate_chat:,
-        agent_name:,
-        swarm:,
-        delegating_chat: nil
-      )
-        super()
-
-        @delegate_name = delegate_name
-        @delegate_description = delegate_description
-        @delegate_chat = delegate_chat
-        @agent_name = agent_name
-        @swarm = swarm
-        @delegating_chat = delegating_chat
-
-        # Generate tool name using canonical method
-        @tool_name = self.class.tool_name_for(delegate_name)
-        @delegate_target = delegate_name.to_s
-      end
-
-      # Override description to return dynamic string based on delegate
-      def description
-        "Work with #{@delegate_name} to delegate work, ask questions, or collaborate. #{@delegate_description}"
-      end
-
-      param :message,
-        type: "string",
-        desc: "Message to send to the agent - can be a work request, question, or collaboration message",
-        required: true
-
-      # Override name to return custom delegation tool name
-      def name
-        @tool_name
-      end
-
-      # Execute delegation with pre/post hooks
-      #
-      # @param message [String] Message to send to the agent
-      # @return [String] Result from delegate agent or error message
-      def execute(message:)
-        # Access swarm infrastructure
-        call_stack = @swarm.delegation_call_stack
-        hook_registry = @swarm.hook_registry
-        swarm_registry = @swarm.swarm_registry
-
-        # Check for circular dependency
-        if call_stack.include?(@delegate_target)
-          emit_circular_warning(call_stack)
-          return "Error: Circular delegation detected: #{call_stack.join(" -> ")} -> #{@delegate_target}. " \
-            "Please restructure your delegation to avoid infinite loops."
-        end
-
-        # Get agent-specific hooks from the delegating chat instance
-        agent_hooks = if @delegating_chat&.respond_to?(:hook_agent_hooks)
-          @delegating_chat.hook_agent_hooks || {}
-        else
-          {}
-        end
-
-        # Trigger pre_delegation callback
-        context = Hooks::Context.new(
-          event: :pre_delegation,
-          agent_name: @agent_name,
-          swarm: @swarm,
-          delegation_target: @delegate_target,
-          metadata: {
-            tool_name: @tool_name,
-            message: message,
-            timestamp: Time.now.utc.iso8601,
-          },
-        )
-
-        executor = Hooks::Executor.new(hook_registry, logger: RubyLLM.logger)
-        pre_agent_hooks = agent_hooks[:pre_delegation] || []
-        result = executor.execute_safe(event: :pre_delegation, context: context, callbacks: pre_agent_hooks)
-
-        # Check if callback halted or replaced the delegation
-        if result.halt?
-          return result.value || "Delegation halted by callback"
-        elsif result.replace?
-          return result.value
-        end
-
-        # Determine delegation type and proceed
-        delegation_result = if @delegate_chat
-          # Delegate to agent
-          delegate_to_agent(message, call_stack)
-        elsif swarm_registry&.registered?(@delegate_target)
-          # Delegate to registered swarm
-          delegate_to_swarm(message, call_stack, swarm_registry)
-        else
-          raise ConfigurationError, "Unknown delegation target: #{@delegate_target}"
-        end
-
-        # Trigger post_delegation callback
-        post_context = Hooks::Context.new(
-          event: :post_delegation,
-          agent_name: @agent_name,
-          swarm: @swarm,
-          delegation_target: @delegate_target,
-          delegation_result: delegation_result,
-          metadata: {
-            tool_name: @tool_name,
-            message: message,
-            result: delegation_result,
-            timestamp: Time.now.utc.iso8601,
-          },
-        )
-
-        post_agent_hooks = agent_hooks[:post_delegation] || []
-        post_result = executor.execute_safe(event: :post_delegation, context: post_context, callbacks: post_agent_hooks)
-
-        # Return modified result if callback replaces it
-        if post_result.replace?
-          post_result.value
-        else
-          delegation_result
-        end
-      rescue Faraday::TimeoutError, Net::ReadTimeout => e
-        # Log timeout error as JSON event
-        LogStream.emit(
-          type: "delegation_error",
-          agent: @agent_name,
-          swarm_id: @swarm.swarm_id,
-          parent_swarm_id: @swarm.parent_swarm_id,
-          delegate_to: @tool_name,
-          error_class: e.class.name,
-          error_message: "Request timed out",
-          error_backtrace: e.backtrace&.first(5) || [],
-        )
-        "Error: Request to #{@tool_name} timed out. The agent may be overloaded or the LLM service is not responding. Please try again or simplify the task."
-      rescue Faraday::Error => e
-        # Log network error as JSON event
-        LogStream.emit(
-          type: "delegation_error",
-          agent: @agent_name,
-          swarm_id: @swarm.swarm_id,
-          parent_swarm_id: @swarm.parent_swarm_id,
-          delegate_to: @tool_name,
-          error_class: e.class.name,
-          error_message: e.message,
-          error_backtrace: e.backtrace&.first(5) || [],
-        )
-        "Error: Network error communicating with #{@tool_name}: #{e.class.name}. Please check connectivity and try again."
-      rescue StandardError => e
-        # Log unexpected error as JSON event
-        backtrace_array = e.backtrace&.first(5) || []
-        LogStream.emit(
-          type: "delegation_error",
-          agent: @agent_name,
-          swarm_id: @swarm.swarm_id,
-          parent_swarm_id: @swarm.parent_swarm_id,
-          delegate_to: @tool_name,
-          error_class: e.class.name,
-          error_message: e.message,
-          error_backtrace: backtrace_array,
-        )
-        # Return error string for LLM
-        backtrace_str = backtrace_array.join("\n  ")
-        "Error: #{@tool_name} encountered an error: #{e.class.name}: #{e.message}\nBacktrace:\n  #{backtrace_str}"
-      end
-
-      private
-
-      # Delegate to an agent
-      #
-      # @param message [String] Message to send to the agent
-      # @param call_stack [Array] Delegation call stack for circular dependency detection
-      # @return [String] Result from agent
-      def delegate_to_agent(message, call_stack)
-        # Push delegate target onto call stack to track delegation chain
-        call_stack.push(@delegate_target)
-        begin
-          response = @delegate_chat.ask(message, source: "delegation")
-          response.content
-        ensure
-          # Always pop from stack, even if delegation fails
-          call_stack.pop
-        end
-      end
-
-      # Delegate to a registered swarm
-      #
-      # @param message [String] Message to send to the swarm
-      # @param call_stack [Array] Delegation call stack for circular dependency detection
-      # @param swarm_registry [SwarmRegistry] Registry for sub-swarms
-      # @return [String] Result from swarm's lead agent
-      def delegate_to_swarm(message, call_stack, swarm_registry)
-        # Load sub-swarm (lazy load + cache)
-        subswarm = swarm_registry.load_swarm(@delegate_target)
-
-        # Push delegate target onto call stack to track delegation chain
-        call_stack.push(@delegate_target)
-        begin
-          # Execute sub-swarm's lead agent
-          lead_agent = subswarm.agents[subswarm.lead_agent]
-          response = lead_agent.ask(message, source: "delegation")
-          result = response.content
-
-          # Reset if keep_context: false
-          swarm_registry.reset_if_needed(@delegate_target)
-
-          result
-        ensure
-          # Always pop from stack, even if delegation fails
-          call_stack.pop
-        end
-      end
-
-      # Emit circular dependency warning event
-      #
-      # @param call_stack [Array] Current delegation call stack
-      # @return [void]
-      def emit_circular_warning(call_stack)
-        LogStream.emit(
-          type: "delegation_circular_dependency",
-          agent: @agent_name,
-          swarm_id: @swarm.swarm_id,
-          parent_swarm_id: @swarm.parent_swarm_id,
-          target: @delegate_target,
-          call_stack: call_stack,
-          timestamp: Time.now.utc.iso8601,
-        )
-      end
-    end
-  end
-end

data/lib/swarm_sdk/tools/document_converters/base_converter.rb

@@ -1,83 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Tools
-    module DocumentConverters
-      # Base class for document converters
-      # Provides common interface and utility methods for converting various document formats
-      class BaseConverter
-        class << self
-          # The gem name required for this converter
-          # @return [String]
-          def gem_name
-            raise NotImplementedError, "#{name} must implement .gem_name"
-          end
-
-          # Human-readable format name
-          # @return [String]
-          def format_name
-            raise NotImplementedError, "#{name} must implement .format_name"
-          end
-
-          # File extensions this converter handles
-          # @return [Array<String>]
-          def extensions
-            raise NotImplementedError, "#{name} must implement .extensions"
-          end
-
-          # Check if the required gem is available
-          # @return [Boolean]
-          def available?
-            gem_available?(gem_name)
-          end
-
-          # Check if a gem is installed
-          # @param gem_name [String] Name of the gem to check
-          # @return [Boolean]
-          def gem_available?(gem_name)
-            Gem::Specification.find_by_name(gem_name)
-            true
-          rescue Gem::LoadError
-            false
-          end
-        end
-
-        # Convert a document file to text/content
-        # @param file_path [String] Path to the file
-        # @return [String, RubyLLM::Content] Converted content or error message
-        def convert(file_path)
-          raise NotImplementedError, "#{self.class.name} must implement #convert"
-        end
-
-        protected
-
-        # Return a system reminder about missing gem
-        # @param format [String] Format name (e.g., "PDF")
-        # @param gem_name [String] Required gem name
-        # @return [String]
-        def unsupported_format_reminder(format, gem_name)
-          <<~REMINDER
-            <system-reminder>
-            This file is a #{format} document, but the required gem is not installed.
-
-            To enable #{format} file reading, please install the gem:
-              gem install #{gem_name}
-
-            Or add to your Gemfile:
-              gem "#{gem_name}"
-
-            Don't install the gem yourself. Ask the user if they would like you to install this gem.
-            </system-reminder>
-          REMINDER
-        end
-
-        # Return an error message
-        # @param message [String] Error message
-        # @return [String]
-        def error(message)
-          "Error: #{message}"
-        end
-      end
-    end
-  end
-end

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

@@ -1,99 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Tools
-    module DocumentConverters
-      # Converts DOCX documents to text with image extraction
-      class DocxConverter < BaseConverter
-        class << self
-          def gem_name
-            "docx"
-          end
-
-          def format_name
-            "DOCX"
-          end
-
-          def extensions
-            [".docx", ".doc"]
-          end
-        end
-
-        # Convert a DOCX document to text/content
-        # @param file_path [String] Path to the DOCX file
-        # @return [String, RubyLLM::Content] Converted content or error message
-        def convert(file_path)
-          unless self.class.available?
-            return unsupported_format_reminder(self.class.format_name, self.class.gem_name)
-          end
-
-          # Check for legacy DOC format
-          if File.extname(file_path).downcase == ".doc"
-            return error("DOC format is not supported. Please convert to DOCX first.")
-          end
-
-          begin
-            require "docx"
-            require "tmpdir"
-
-            doc = Docx::Document.open(file_path)
-
-            # Extract images from the DOCX
-            image_paths = ImageExtractors::DocxImageExtractor.extract_images(doc, file_path)
-
-            output = []
-            output << "Document: #{File.basename(file_path)}"
-            output << "=" * 60
-            output << ""
-
-            # Extract paragraphs
-            paragraphs = doc.paragraphs.map(&:text).reject(&:empty?)
-
-            # Check for empty document
-            if paragraphs.empty? && doc.tables.empty?
-              output << "(Document is empty - no paragraphs or tables)"
-            else
-              output += paragraphs
-
-              # Extract tables with enhanced formatting
-              if doc.tables.any?
-                output << ""
-                output << "Tables:"
-                output << "-" * 60
-
-                doc.tables.each_with_index do |table, idx|
-                  output << ""
-                  output << "Table #{idx + 1} (#{table.row_count} rows × #{table.column_count} columns):"
-
-                  table.rows.each do |row|
-                    output << row.cells.map(&:text).join(" | ")
-                  end
-                end
-              end
-            end
-
-            text_content = output.join("\n")
-
-            # If there are images, return Content with attachments
-            if image_paths.any?
-              content = RubyLLM::Content.new(text_content)
-              image_paths.each do |image_path|
-                content.add_attachment(image_path)
-              end
-              content
-            else
-              # No images, return just text
-              text_content
-            end
-          rescue Zip::Error => e
-            error("Invalid or corrupted DOCX file: #{e.message}")
-          rescue Errno::ENOENT => e
-            error("File not found or missing document.xml: #{e.message}")
-          rescue StandardError => e
-            error("Failed to parse DOCX file: #{e.message}")
-          end
-        end
-      end
-    end
-  end
-end

data/lib/swarm_sdk/tools/document_converters/html_converter.rb

@@ -1,101 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Tools
-    module DocumentConverters
-      # Converter for HTML to Markdown
-      # Uses reverse_markdown gem if available, otherwise falls back to simple regex-based conversion
-      class HtmlConverter < BaseConverter
-        class << self
-          def gem_name
-            "reverse_markdown"
-          end
-
-          def format_name
-            "HTML"
-          end
-
-          def extensions
-            [".html", ".htm"]
-          end
-        end
-
-        # Convert HTML string to Markdown
-        # @param html [String] HTML content to convert
-        # @return [String] Markdown content
-        def convert_string(html)
-          if self.class.available?
-            convert_with_gem(html)
-          else
-            convert_simple(html)
-          end
-        end
-
-        # Convert HTML file to Markdown
-        # @param file_path [String] Path to HTML file
-        # @return [String] Markdown content
-        def convert(file_path)
-          html = File.read(file_path)
-          convert_string(html)
-        rescue StandardError => e
-          error("Failed to read HTML file: #{e.message}")
-        end
-
-        private
-
-        # Convert HTML to Markdown using reverse_markdown gem
-        # @param html [String] HTML content
-        # @return [String] Markdown content
-        def convert_with_gem(html)
-          require "reverse_markdown"
-
-          ReverseMarkdown.convert(html, unknown_tags: :bypass, github_flavored: true)
-        rescue StandardError
-          # Fallback to simple conversion if gem conversion fails
-          convert_simple(html)
-        end
-
-        # Simple regex-based HTML to Markdown conversion (fallback)
-        # @param html [String] HTML content
-        # @return [String] Markdown content
-        def convert_simple(html)
-          # Remove script and style tags
-          content = html.gsub(%r{<script[^>]*>.*?</script>}im, "")
-          content = content.gsub(%r{<style[^>]*>.*?</style>}im, "")
-
-          # Convert common HTML elements
-          content = content.gsub(%r{<h1[^>]*>(.*?)</h1>}im, "\n# \\1\n")
-          content = content.gsub(%r{<h2[^>]*>(.*?)</h2>}im, "\n## \\1\n")
-          content = content.gsub(%r{<h3[^>]*>(.*?)</h3>}im, "\n### \\1\n")
-          content = content.gsub(%r{<h4[^>]*>(.*?)</h4>}im, "\n#### \\1\n")
-          content = content.gsub(%r{<h5[^>]*>(.*?)</h5>}im, "\n##### \\1\n")
-          content = content.gsub(%r{<h6[^>]*>(.*?)</h6>}im, "\n###### \\1\n")
-          content = content.gsub(%r{<p[^>]*>(.*?)</p>}im, "\n\\1\n")
-          content = content.gsub(%r{<br\s*/?>}i, "\n")
-          content = content.gsub(%r{<strong[^>]*>(.*?)</strong>}im, "**\\1**")
-          content = content.gsub(%r{<b[^>]*>(.*?)</b>}im, "**\\1**")
-          content = content.gsub(%r{<em[^>]*>(.*?)</em>}im, "_\\1_")
-          content = content.gsub(%r{<i[^>]*>(.*?)</i>}im, "_\\1_")
-          content = content.gsub(%r{<code[^>]*>(.*?)</code>}im, "`\\1`")
-          content = content.gsub(%r{<a[^>]*href=["']([^"']*)["'][^>]*>(.*?)</a>}im, "[\\2](\\1)")
-          content = content.gsub(%r{<li[^>]*>(.*?)</li>}im, "- \\1\n")
-
-          # Remove remaining HTML tags
-          content = content.gsub(/<[^>]+>/, "")
-
-          # Decode HTML entities
-          content = content.gsub("&lt;", "<")
-          content = content.gsub("&gt;", ">")
-          content = content.gsub("&amp;", "&")
-          content = content.gsub("&quot;", "\"")
-          content = content.gsub("&#39;", "'")
-          content = content.gsub("&nbsp;", " ")
-
-          # Clean up whitespace
-          content = content.gsub(/\n\n\n+/, "\n\n")
-          content.strip
-        end
-      end
-    end
-  end
-end

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

@@ -1,78 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Tools
-    module DocumentConverters
-      # Converts PDF documents to text with image extraction
-      class PdfConverter < BaseConverter
-        class << self
-          def gem_name
-            "pdf-reader"
-          end
-
-          def format_name
-            "PDF"
-          end
-
-          def extensions
-            [".pdf"]
-          end
-        end
-
-        # Convert a PDF document to text/content
-        # @param file_path [String] Path to the PDF file
-        # @return [String, RubyLLM::Content] Converted content or error message
-        def convert(file_path)
-          unless self.class.available?
-            return unsupported_format_reminder(self.class.format_name, self.class.gem_name)
-          end
-
-          begin
-            require "pdf-reader"
-            require "tmpdir"
-            require "fileutils"
-
-            reader = PDF::Reader.new(file_path)
-            output = []
-            output << "PDF Document: #{File.basename(file_path)}"
-            output << "=" * 60
-            output << "Pages: #{reader.page_count}"
-            output << ""
-
-            # Extract images from the PDF
-            image_paths = ImageExtractors::PdfImageExtractor.extract_images(reader, file_path)
-
-            # Extract text from each page
-            reader.pages.each_with_index do |page, index|
-              output << "Page #{index + 1}:"
-              output << "-" * 60
-              text = page.text.strip
-              output << (text.empty? ? "(No text content on this page)" : text)
-              output << ""
-            end
-
-            text_content = output.join("\n")
-
-            # If there are images, return Content with attachments
-            if image_paths.any?
-              content = RubyLLM::Content.new(text_content)
-              image_paths.each do |image_path|
-                content.add_attachment(image_path)
-              end
-              content
-            else
-              # No images, return just text
-              text_content
-            end
-          rescue PDF::Reader::MalformedPDFError => e
-            error("PDF file is malformed: #{e.message}")
-          rescue PDF::Reader::UnsupportedFeatureError => e
-            error("PDF contains unsupported features: #{e.message}")
-          rescue StandardError => e
-            error("Failed to parse PDF file: #{e.message}")
-          end
-        end
-      end
-    end
-  end
-end