claude_swarm 1.0.0 → 1.0.2

data/lib/swarm_memory/dsl/memory_config.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module SwarmMemory
+  module DSL
+    # Memory configuration for agents
+    #
+    # This class is injected into SwarmSDK when swarm_memory is required,
+    # allowing agents to configure memory via the DSL.
+    #
+    # Supports custom adapters through options hash that gets passed through
+    # to the adapter constructor.
+    #
+    # @example Filesystem adapter
+    #   memory do
+    #     adapter :filesystem
+    #     directory ".swarm/memory"
+    #   end
+    #
+    # @example Custom adapter
+    #   memory do
+    #     adapter :activerecord
+    #     option :namespace, "my_agent"
+    #     option :table_name, "memory_entries"
+    #   end
+    class MemoryConfig
+      attr_reader :adapter_type, :adapter_options
+
+      def initialize
+        @adapter_type = :filesystem # Default adapter
+        @adapter_options = {} # Options passed to adapter constructor
+        @mode = :assistant # Default mode
+      end
+
+      # DSL method to set/get adapter type
+      #
+      # @param value [Symbol, nil] Adapter type
+      # @return [Symbol] Current adapter
+      def adapter(value = nil)
+        return @adapter_type if value.nil?
+
+        @adapter_type = value.to_sym
+      end
+
+      # DSL method to set adapter option (generic)
+      #
+      # This allows passing any option to the adapter constructor.
+      #
+      # @param key [Symbol] Option key
+      # @param value [Object] Option value
+      #
+      # @example
+      #   option :namespace, "my_agent"
+      #   option :connection_pool_size, 5
+      def option(key, value)
+        @adapter_options[key.to_sym] = value
+      end
+
+      # DSL method to set/get directory (convenience for filesystem adapter)
+      #
+      # Equivalent to: option :directory, value
+      #
+      # @param value [String, nil] Memory directory path
+      # @return [String] Current directory
+      def directory(value = nil)
+        if value.nil?
+          @adapter_options[:directory]
+        else
+          @adapter_options[:directory] = value
+        end
+      end
+
+      # DSL method to set/get mode
+      #
+      # Modes:
+      # - :assistant (default) - Read + Write, balanced for learning and retrieval
+      # - :retrieval - Read-only, optimized for Q&A
+      # - :researcher - All tools, optimized for knowledge extraction
+      #
+      # @param value [Symbol, nil] Memory mode
+      # @return [Symbol] Current mode
+      def mode(value = nil)
+        return @mode if value.nil?
+
+        @mode = value.to_sym
+      end
+
+      # Check if memory is enabled
+      #
+      # @return [Boolean] True if adapter is configured with required options
+      def enabled?
+        case @adapter_type
+        when :filesystem
+          !@adapter_options[:directory].nil?
+        else
+          # For custom adapters, assume enabled if adapter is set
+          # Custom adapter will validate its own requirements
+          true
+        end
+      end
+
+      # Convert config to hash (for SDK plugin)
+      #
+      # @return [Hash] Configuration as hash
+      def to_h
+        {
+          adapter: @adapter_type,
+          mode: @mode,
+          **@adapter_options,
+        }
+      end
+    end
+  end
+end

data/lib/swarm_memory/embeddings/embedder.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module SwarmMemory
+  module Embeddings
+    # Abstract embedder interface
+    #
+    # Subclasses implement different embedding providers
+    # (Informers, OpenAI API, etc.)
+    class Embedder
+      # Generate embedding for single text
+      #
+      # @param text [String] Text to embed
+      # @return [Array<Float>] Embedding vector
+      # @raise [EmbeddingError] If embedding generation fails
+      def embed(text)
+        raise NotImplementedError, "Subclass must implement #embed"
+      end
+
+      # Generate embeddings for multiple texts (batched)
+      #
+      # @param texts [Array<String>] Texts to embed
+      # @return [Array<Array<Float>>] Array of embedding vectors
+      # @raise [EmbeddingError] If embedding generation fails
+      def embed_batch(texts)
+        raise NotImplementedError, "Subclass must implement #embed_batch"
+      end
+
+      # Get embedding dimensionality
+      #
+      # @return [Integer] Vector dimensions
+      def dimensions
+        raise NotImplementedError, "Subclass must implement #dimensions"
+      end
+    end
+  end
+end

data/lib/swarm_memory/embeddings/informers_embedder.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module SwarmMemory
+  module Embeddings
+    # Embedder implementation using Informers gem (fast ONNX inference)
+    #
+    # Uses sentence-transformers models via ONNX for fast, local embedding generation.
+    # Supports quantized models for even better performance.
+    #
+    # @example
+    #   embedder = InformersEmbedder.new
+    #   vector = embedder.embed("This is a test sentence")
+    #   vector.size # => 384
+    class InformersEmbedder < Embedder
+      DEFAULT_MODEL = "sentence-transformers/multi-qa-MiniLM-L6-cos-v1"
+      EMBEDDING_DIMENSIONS = 384
+
+      # Initialize embedder with model configuration
+      #
+      # Model can be configured via SWARM_MEMORY_EMBEDDING_MODEL environment variable.
+      #
+      # Available models:
+      # - sentence-transformers/all-MiniLM-L6-v2 (default, general purpose, 256 tokens)
+      # - sentence-transformers/multi-qa-MiniLM-L6-cos-v1 (Q&A optimized, 512 tokens)
+      #
+      # @param model [String, nil] HuggingFace model identifier (defaults to env var or DEFAULT_MODEL)
+      # @param quantized [Boolean] Use quantized variant (default: false for original model)
+      # @param cache_dir [String, nil] Optional custom cache directory
+      # @raise [EmbeddingError] If Informers gem is not available
+      #
+      # Note: The original sentence-transformers model uses unquantized ONNX (90MB).
+      # For a smaller quantized version (22MB), use model: "Xenova/all-MiniLM-L6-v2", quantized: true
+      def initialize(model: nil, quantized: false, cache_dir: nil)
+        super()
+
+        unless defined?(Informers)
+          raise EmbeddingError,
+            "Informers gem is not available. Install with: gem install informers"
+        end
+
+        # Use env var if available, otherwise use provided model or default
+        @model_name = model || ENV["SWARM_MEMORY_EMBEDDING_MODEL"] || DEFAULT_MODEL
+        @quantized = quantized
+        @model = nil # Lazy load
+
+        # Optional: Set custom cache directory
+        Informers.cache_dir = cache_dir if cache_dir
+      end
+
+      # Explicitly pre-load the model (triggers download if not cached)
+      #
+      # Call this during initialization to download the model immediately
+      # rather than waiting for the first embedding call.
+      #
+      # @return [self]
+      #
+      # @example
+      #   embedder = InformersEmbedder.new
+      #   embedder.preload!  # Downloads ~80MB model on first call
+      #   embedder.embed("text")  # No download wait
+      def preload!
+        ensure_model_loaded
+        self
+      end
+
+      # Check if model is already cached locally
+      #
+      # @return [Boolean] True if model files exist in cache
+      #
+      # @example
+      #   embedder = InformersEmbedder.new
+      #   if embedder.cached?
+      #     puts "Ready to use!"
+      #   else
+      #     puts "Will download on first use (~80MB)"
+      #   end
+      def cached?
+        cache_dir = Informers.cache_dir
+
+        # Different models have different file names
+        # Original sentence-transformers: model.onnx (unquantized)
+        # Xenova version: model_quantized.onnx (quantized)
+        suffix = @quantized ? "_quantized" : ""
+
+        # Check for required model files
+        model_file = File.join(cache_dir, @model_name, "onnx", "model#{suffix}.onnx")
+        tokenizer_file = File.join(cache_dir, @model_name, "tokenizer.json")
+
+        File.exist?(model_file) && File.exist?(tokenizer_file)
+      end
+
+      # Generate embedding for single text
+      #
+      # @param text [String] Text to embed
+      # @return [Array<Float>] 384-dimensional embedding vector
+      # @raise [EmbeddingError] If embedding generation fails
+      def embed(text)
+        raise ArgumentError, "text is required" if text.nil? || text.to_s.strip.empty?
+
+        begin
+          ensure_model_loaded
+          # Informers handles single strings directly - returns single embedding array
+          @model.call(text)
+        rescue StandardError => e
+          raise EmbeddingError, "Failed to generate embedding: #{e.message}"
+        end
+      end
+
+      # Generate embeddings for multiple texts (batched)
+      #
+      # @param texts [Array<String>] Texts to embed
+      # @return [Array<Array<Float>>] Array of embedding vectors
+      # @raise [EmbeddingError] If embedding generation fails
+      def embed_batch(texts)
+        raise ArgumentError, "texts must be an array" unless texts.is_a?(Array)
+        raise ArgumentError, "texts cannot be empty" if texts.empty?
+
+        begin
+          ensure_model_loaded
+          # Batch call - returns array of embedding arrays
+          @model.call(texts)
+        rescue StandardError => e
+          raise EmbeddingError, "Failed to generate embeddings: #{e.message}"
+        end
+      end
+
+      # Get embedding dimensionality
+      #
+      # @return [Integer] Vector dimensions (384 for all-MiniLM-L6-v2)
+      def dimensions
+        EMBEDDING_DIMENSIONS
+      end
+
+      private
+
+      # Lazy load the Informers model
+      #
+      # @return [void]
+      def ensure_model_loaded
+        return if @model
+
+        @model = Informers.pipeline(
+          "embedding",
+          @model_name,
+          quantized: @quantized,
+        )
+      rescue StandardError => e
+        raise EmbeddingError, "Failed to load embedding model '#{@model_name}': #{e.message}"
+      end
+    end
+  end
+end

data/lib/swarm_memory/errors.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module SwarmMemory
+  # Base error class for SwarmMemory
+  class Error < StandardError; end
+
+  # Configuration errors
+  class ConfigurationError < Error; end
+
+  # Storage operation errors
+  class StorageError < Error; end
+
+  # Adapter-specific errors
+  class AdapterError < Error; end
+
+  # Search operation errors
+  class SearchError < Error; end
+
+  # Embedding generation errors
+  class EmbeddingError < Error; end
+end

data/lib/swarm_memory/integration/cli_registration.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module SwarmMemory
+  module Integration
+    # Auto-registration for SwarmCLI commands
+    #
+    # Registers memory management commands with SwarmCLI when available.
+    class CliRegistration
+      class << self
+        # Register memory CLI commands with SwarmCLI
+        #
+        # This is called automatically when swarm_memory is required.
+        #
+        # @return [void]
+        def register!
+          # Only register if SwarmCLI is present
+          return unless defined?(SwarmCLI)
+
+          # Load CLI commands explicitly (Zeitwerk might not have loaded it yet)
+          require_relative "../cli/commands"
+
+          # Register memory command
+          SwarmCLI::CommandRegistry.register(:memory, SwarmMemory::CLI::Commands)
+        rescue StandardError => e
+          warn("Warning: Failed to register SwarmMemory CLI commands: #{e.message}")
+        end
+      end
+    end
+  end
+end

data/lib/swarm_memory/integration/configuration.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module SwarmMemory
+  module Integration
+    # Configuration for agent memory
+    #
+    # Used by SwarmSDK to configure memory settings for agents.
+    # This mirrors the MemoryConfig in SwarmSDK but lives in SwarmMemory.
+    class Configuration
+      def initialize
+        @adapter = :filesystem
+        @directory = nil
+      end
+
+      # DSL method to set/get adapter
+      #
+      # @param value [Symbol, String, nil] Adapter type (:filesystem, :redis, etc.)
+      # @return [Symbol] Current adapter
+      def adapter(value = nil)
+        return @adapter if value.nil?
+
+        @adapter = value.to_sym
+      end
+
+      # DSL method to set/get directory
+      #
+      # @param value [String, nil] Directory path for storage
+      # @return [String, nil] Current directory
+      def directory(value = nil)
+        return @directory if value.nil?
+
+        @directory = value
+      end
+
+      # Check if memory is enabled
+      #
+      # @return [Boolean] True if directory is set
+      def enabled?
+        !@directory.nil?
+      end
+    end
+  end
+end

data/lib/swarm_memory/integration/registration.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module SwarmMemory
+  module Integration
+    # Auto-registration with SwarmSDK
+    #
+    # Registers SwarmMemory plugin with SwarmSDK when the swarm_memory gem is loaded.
+    # This enables SwarmSDK to automatically use SwarmMemory features.
+    class Registration
+      class << self
+        # Register SwarmMemory plugin with SwarmSDK
+        #
+        # This is called automatically when swarm_memory is required.
+        # It registers the plugin so SwarmSDK can provide memory tools and storage.
+        #
+        # @return [void]
+        def register!
+          # Only register if SwarmSDK is present
+          return unless defined?(SwarmSDK)
+          return unless defined?(SwarmSDK::PluginRegistry)
+
+          # Register plugin with SwarmSDK
+          plugin = SDKPlugin.new
+          SwarmSDK::PluginRegistry.register(plugin)
+        rescue StandardError => e
+          warn("Warning: Failed to register SwarmMemory plugin with SwarmSDK: #{e.message}")
+        end
+      end
+    end
+  end
+end