clusterkit 0.3.0-arm64-darwin

data/lib/clusterkit/dimensionality/umap.rb

@@ -0,0 +1,282 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'json'
+require_relative '../configuration'
+require_relative '../silence'
+require_relative '../data_validator'
+
+module ClusterKit
+  module Dimensionality
+    class UMAP
+    attr_reader :n_components, :n_neighbors, :random_seed, :nb_grad_batch, :nb_sampling_by_edge
+
+    # Initialize a new UMAP instance
+    # @param n_components [Integer] Target number of dimensions (default: 2)
+    # @param n_neighbors [Integer] Number of neighbors for manifold approximation (default: 15)
+    # @param random_seed [Integer, nil] Random seed for reproducibility (default: nil)
+    # @param nb_grad_batch [Integer] Number of gradient descent batches (default: 10)
+    #                                Controls training iterations - lower = faster but less accurate
+    # @param nb_sampling_by_edge [Integer] Number of negative samples per edge (default: 8)
+    #                                      Controls sampling quality - lower = faster but less accurate
+    def initialize(n_components: 2, n_neighbors: 15, random_seed: nil,
+                   nb_grad_batch: 10, nb_sampling_by_edge: 8)
+      @n_components = n_components
+      @n_neighbors = n_neighbors
+      @random_seed = random_seed
+      @nb_grad_batch = nb_grad_batch
+      @nb_sampling_by_edge = nb_sampling_by_edge
+      @fitted = false
+      # Don't create RustUMAP yet - will be created in fit/fit_transform with adjusted parameters
+      @rust_umap = nil
+    end
+
+    # Fit the model to the data (training)
+    # @param data [Array<Array<Numeric>>] Training data as 2D array
+    # @return [self] Returns self for method chaining
+    # @note UMAP's training process inherently produces embeddings. Since the
+    #       underlying Rust implementation doesn't separate training from
+    #       transformation, we call fit_transform but discard the embeddings.
+    #       Use fit_transform if you need both training and the transformed data.
+    def fit(data)
+      validate_input(data)
+
+      # Always recreate RustUMAP for fit to ensure fresh fit
+      @rust_umap = nil
+      create_rust_umap_with_adjusted_params(data)
+
+      # UMAP doesn't separate training from transformation internally,
+      # so we call fit_transform but discard the result
+      begin
+        Silence.maybe_silence do
+          @rust_umap.fit_transform(data)
+        end
+        @fitted = true
+        self
+      rescue StandardError => e
+        handle_umap_error(e, data)
+      rescue => e
+        # Handle fatal errors that aren't StandardError
+        handle_umap_error(RuntimeError.new(e.message), data)
+      end
+    end
+
+    # Transform data using the fitted model
+    # @param data [Array<Array<Numeric>>] Data to transform
+    # @return [Array<Array<Float>>] Transformed data in reduced dimensions
+    # @raise [RuntimeError] If model hasn't been fitted yet
+    def transform(data)
+      raise RuntimeError, "Model must be fitted before transform. Call fit or fit_transform first." unless fitted?
+      validate_input(data, check_min_samples: false)
+      Silence.maybe_silence do
+        @rust_umap.transform(data)
+      end
+    end
+
+    # Fit the model and transform the data in one step
+    # @param data [Array<Array<Numeric>>] Training data as 2D array
+    # @return [Array<Array<Float>>] Transformed data in reduced dimensions
+    def fit_transform(data)
+      validate_input(data)
+
+      # Always recreate RustUMAP for fit_transform to ensure fresh fit
+      @rust_umap = nil
+      create_rust_umap_with_adjusted_params(data)
+
+      begin
+        result = Silence.maybe_silence do
+          @rust_umap.fit_transform(data)
+        end
+        @fitted = true
+        result
+      rescue StandardError => e
+        handle_umap_error(e, data)
+      rescue => e
+        # Handle fatal errors that aren't StandardError
+        handle_umap_error(RuntimeError.new(e.message), data)
+      end
+    end
+
+    # Check if the model has been fitted
+    # @return [Boolean] true if model is fitted, false otherwise
+    def fitted?
+      @fitted
+    end
+
+    # Save the fitted model to a file
+    # @param path [String] Path where to save the model
+    # @raise [RuntimeError] If model hasn't been fitted yet
+    def save_model(path)
+      raise RuntimeError, "No model to save. Call fit or fit_transform first." unless fitted?
+
+      # Ensure directory exists
+      dir = File.dirname(path)
+      FileUtils.mkdir_p(dir) unless dir == '.' || dir == '/'
+
+      @rust_umap.save_model(path)
+    end
+
+    # Load a fitted model from a file
+    # @param path [String] Path to the saved model
+    # @return [UMAP] A new UMAP instance with the loaded model
+    # @raise [ArgumentError] If file doesn't exist
+    def self.load_model(path)
+      raise ArgumentError, "File not found: #{path}" unless File.exist?(path)
+
+      # Load the Rust model (access private constant)
+      rust_umap = ::ClusterKit.const_get(:RustUMAP).load_model(path)
+
+      # Create a new UMAP instance with the loaded model
+      instance = allocate
+      instance.instance_variable_set(:@rust_umap, rust_umap)
+      instance.instance_variable_set(:@fitted, true)
+      # The model file should contain these parameters, but for now we don't have access
+      instance.instance_variable_set(:@n_components, nil)
+      instance.instance_variable_set(:@n_neighbors, nil)
+      instance.instance_variable_set(:@random_seed, nil)
+
+      instance
+    end
+
+    # Save transformed data to JSON file
+    # @param data [Array<Array<Float>>] Transformed data to save
+    # @param path [String] Path where to save the data
+    def self.save_data(data, path)
+      FileUtils.mkdir_p(File.dirname(path)) unless File.dirname(path) == '.'
+      File.write(path, JSON.pretty_generate(data))
+    end
+
+    # Load transformed data from JSON file
+    # @param path [String] Path to the saved data
+    # @return [Array<Array<Float>>] The loaded data
+    # @raise [ArgumentError] If file doesn't exist
+    def self.load_data(path)
+      raise ArgumentError, "File not found: #{path}" unless File.exist?(path)
+      JSON.parse(File.read(path))
+    end
+
+    private
+
+    def handle_umap_error(error, data)
+      error_msg = error.message
+      n_samples = data.size
+
+      case error_msg
+      when /isolated point/i, /graph will not be connected/i
+        raise ::ClusterKit::IsolatedPointError, <<~MSG
+          UMAP found isolated points in your data that are too far from other points.
+
+          This typically happens when:
+          • Your data contains outliers that are very different from other points
+          • You're using random data without inherent structure
+          • The n_neighbors parameter (#{@n_neighbors}) is too high for your data distribution
+
+          Solutions:
+          1. Reduce n_neighbors (try 5 or even 3): UMAP.new(n_neighbors: 5)
+          2. Remove outliers from your data before applying UMAP
+          3. Ensure your data has some structure (not purely random)
+          4. For small datasets (< 50 points), consider using PCA instead
+
+          Your data: #{n_samples} samples, #{data.first&.size || 0} dimensions
+        MSG
+
+      when /assertion failed.*box_size/i
+        raise ::ClusterKit::ConvergenceError, <<~MSG
+          UMAP failed to converge due to numerical instability in your data.
+
+          This typically happens when:
+          • Data points are too spread out or have extreme values
+          • The scale of different features varies wildly
+          • There are duplicate or nearly-duplicate points
+
+          Solutions:
+          1. Normalize your data first: ClusterKit::Preprocessing.normalize(data)
+          2. Use a smaller n_neighbors value: UMAP.new(n_neighbors: 5)
+          3. Check for and remove duplicate points
+          4. Scale your data to a reasonable range (e.g., 0-1 or -1 to 1)
+
+          Your data: #{n_samples} samples, #{data.first&.size || 0} dimensions
+        MSG
+
+      when /n_neighbors.*larger than/i, /too many neighbors/i
+        raise ::ClusterKit::InvalidParameterError, <<~MSG
+          The n_neighbors parameter (#{@n_neighbors}) is too large for your dataset size (#{n_samples}).
+
+          UMAP needs n_neighbors to be less than the number of samples.
+          Suggested value: #{[5, (n_samples * 0.1).to_i].max}
+
+          This should have been auto-adjusted. If you're seeing this error, please report it.
+        MSG
+
+      else
+        # For unknown errors, still provide some guidance
+        raise ::ClusterKit::Error, <<~MSG
+          UMAP encountered an error: #{error_msg}
+
+          Common solutions:
+          1. Try reducing n_neighbors (current: #{@n_neighbors})
+          2. Normalize your data first
+          3. Check for NaN or infinite values in your data
+          4. Ensure you have at least 10 data points
+
+          If this persists, consider using PCA for dimensionality reduction instead.
+        MSG
+      end
+    end
+
+    def validate_input(data, check_min_samples: true)
+      # Use shared validation for common checks
+      DataValidator.validate_standard(data)
+
+      # UMAP-specific validations
+      if check_min_samples && data.size < 10
+        raise ::ClusterKit::InsufficientDataError, <<~MSG
+          UMAP requires at least 10 data points, but only #{data.size} provided.
+
+          For small datasets, consider:
+          1. Using PCA instead: ClusterKit::Dimensionality::PCA.new(n_components: 2)
+          2. Collecting more data points
+          3. Using simpler visualization methods
+        MSG
+      end
+
+      # Check for extreme data ranges that might cause numerical issues
+      stats = DataValidator.data_statistics(data)
+      if stats[:data_range] > 1000
+        warn "WARNING: Large data range detected (#{stats[:data_range].round(2)}). Consider normalizing your data to prevent numerical instability."
+      end
+    end
+
+    def create_rust_umap_with_adjusted_params(data)
+      # Only create if not already created
+      return if @rust_umap
+
+      n_samples = data.size
+
+      # Automatically adjust n_neighbors if it's too high for the dataset
+      # n_neighbors should be less than n_samples
+      # Use a reasonable default: min(15, n_samples / 4) but at least 2
+      max_neighbors = [n_samples - 1, 2].max  # At least 2, but less than n_samples
+      suggested_neighbors = [[15, n_samples / 4].min.to_i, 2].max
+
+      adjusted_n_neighbors = @n_neighbors
+      if @n_neighbors > max_neighbors
+        adjusted_n_neighbors = [suggested_neighbors, max_neighbors].min
+
+        if ::ClusterKit.configuration.verbose
+          warn "UMAP: Adjusted n_neighbors from #{@n_neighbors} to #{adjusted_n_neighbors} for dataset with #{n_samples} samples"
+        end
+      end
+
+      # Access the private constant from inside the module
+      @rust_umap = ::ClusterKit.const_get(:RustUMAP).new({
+        n_components: @n_components,
+        n_neighbors: adjusted_n_neighbors,
+        random_seed: @random_seed,
+        nb_grad_batch: @nb_grad_batch,
+        nb_sampling_by_edge: @nb_sampling_by_edge
+      })
+    end
+    end
+  end
+end

data/lib/clusterkit/dimensionality.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module ClusterKit
+  # Module for dimensionality reduction algorithms
+  module Dimensionality
+    # Load classes - can't use autoload with require issues
+    require_relative "dimensionality/umap"
+    require_relative "dimensionality/pca"
+    require_relative "dimensionality/svd"
+    
+    # Module-level evaluation methods
+    
+    # Calculate reconstruction error for a dimensionality reduction
+    # @param original_data [Array<Array<Numeric>>] Original high-dimensional data
+    # @param reconstructed_data [Array<Array<Numeric>>] Reconstructed data
+    # @return [Float] Mean squared reconstruction error
+    def self.reconstruction_error(original_data, reconstructed_data)
+      raise ArgumentError, "Data sizes don't match" if original_data.size != reconstructed_data.size
+      
+      total_error = 0.0
+      original_data.zip(reconstructed_data).each do |orig, recon|
+        error = orig.zip(recon).map { |o, r| (o - r) ** 2 }.sum
+        total_error += error
+      end
+      
+      total_error / original_data.size
+    end
+  end
+end

data/lib/clusterkit/hdbscan_api_design.rb

@@ -0,0 +1,142 @@
+# API Design for HDBSCAN to match KMeans pattern
+
+module ClusterKit
+  module Clustering
+    
+    # HDBSCAN clustering algorithm - matching KMeans API pattern
+    class HDBSCAN
+      attr_reader :min_samples, :min_cluster_size, :labels, :probabilities, 
+                  :outlier_scores, :cluster_persistence
+
+      # Initialize HDBSCAN clusterer (matches KMeans pattern)
+      # @param min_samples [Integer] Min neighborhood size for core points (default: 5)
+      # @param min_cluster_size [Integer] Minimum size of clusters (default: 5)
+      # @param metric [String] Distance metric (default: 'euclidean')
+      def initialize(min_samples: 5, min_cluster_size: 5, metric: 'euclidean')
+        raise ArgumentError, "min_samples must be positive" unless min_samples > 0
+        raise ArgumentError, "min_cluster_size must be positive" unless min_cluster_size > 0
+        @min_samples = min_samples
+        @min_cluster_size = min_cluster_size
+        @metric = metric
+        @fitted = false
+      end
+
+      # Fit the HDBSCAN model (matches KMeans.fit)
+      # @param data [Array] 2D array of data points
+      # @return [self] Returns self for method chaining
+      def fit(data)
+        validate_data(data)
+        
+        # Call Rust implementation (hdbscan crate)
+        result = Clustering.hdbscan_rust(data, @min_samples, @min_cluster_size, @metric)
+        
+        @labels = result[:labels]
+        @probabilities = result[:probabilities]
+        @outlier_scores = result[:outlier_scores]
+        @cluster_persistence = result[:cluster_persistence]
+        @fitted = true
+        
+        self
+      end
+
+      # HDBSCAN doesn't support predict for new points (unlike KMeans)
+      # But we keep the method for API consistency
+      # @param data [Array] 2D array of data points
+      # @return [Array] Returns nil or raises
+      def predict(data)
+        raise NotImplementedError, "HDBSCAN does not support prediction on new data. " \
+                                  "Use approximate_predict for approximate membership"
+      end
+
+      # Fit the model and return labels (matches KMeans.fit_predict)
+      # @param data [Array] 2D array of data points
+      # @return [Array] Cluster labels (-1 for noise)
+      def fit_predict(data)
+        fit(data)
+        @labels
+      end
+
+      # Check if model has been fitted (matches KMeans.fitted?)
+      # @return [Boolean] True if fitted
+      def fitted?
+        @fitted
+      end
+
+      # Get number of clusters found (similar to KMeans.k but discovered)
+      # @return [Integer] Number of clusters (excluding noise)
+      def n_clusters
+        return 0 unless fitted?
+        @labels.max + 1 rescue 0
+      end
+
+      # Get noise ratio (HDBSCAN-specific but follows naming pattern)
+      # @return [Float] Fraction of points labeled as noise
+      def noise_ratio
+        return 0.0 unless fitted?
+        @labels.count(-1).to_f / @labels.length
+      end
+
+      private
+
+      def validate_data(data)
+        # Exact same validation as KMeans for consistency
+        raise ArgumentError, "Data must be an array" unless data.is_a?(Array)
+        raise ArgumentError, "Data cannot be empty" if data.empty?
+        raise ArgumentError, "Data must be 2D array" unless data.first.is_a?(Array)
+        
+        row_length = data.first.length
+        unless data.all? { |row| row.is_a?(Array) && row.length == row_length }
+          raise ArgumentError, "All rows must have the same length"
+        end
+        
+        data.each_with_index do |row, i|
+          row.each_with_index do |val, j|
+            unless val.is_a?(Numeric)
+              raise ArgumentError, "Element at position [#{i}, #{j}] is not numeric"
+            end
+          end
+        end
+      end
+    end
+
+    # Module-level convenience methods (matching KMeans pattern)
+    class << self
+      # Perform HDBSCAN clustering (matches Clustering.kmeans signature)
+      # @param data [Array] 2D array of data points
+      # @param min_samples [Integer] Min neighborhood size for core points
+      # @param min_cluster_size [Integer] Minimum size of clusters
+      # @return [Hash] Result hash with :labels, :probabilities, :outlier_scores
+      def hdbscan(data, min_samples: 5, min_cluster_size: 5)
+        clusterer = HDBSCAN.new(min_samples: min_samples, min_cluster_size: min_cluster_size)
+        clusterer.fit(data)
+        {
+          labels: clusterer.labels,
+          probabilities: clusterer.probabilities,
+          outlier_scores: clusterer.outlier_scores,
+          n_clusters: clusterer.n_clusters,
+          noise_ratio: clusterer.noise_ratio
+        }
+      end
+    end
+  end
+end
+
+# Usage comparison:
+
+# KMeans usage:
+kmeans = ClusterKit::Clustering::KMeans.new(k: 3)
+kmeans.fit(data)
+labels = kmeans.labels
+# or
+labels = kmeans.fit_predict(data)
+
+# HDBSCAN usage (identical pattern):
+hdbscan = ClusterKit::Clustering::HDBSCAN.new(min_samples: 5, min_cluster_size: 5)
+hdbscan.fit(data)
+labels = hdbscan.labels
+# or
+labels = hdbscan.fit_predict(data)
+
+# Module-level convenience (both follow same pattern):
+result = ClusterKit::Clustering.kmeans(data, 3)
+result = ClusterKit::Clustering.hdbscan(data, min_samples: 5)

data/lib/clusterkit/hnsw.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+module ClusterKit
+  # HNSW (Hierarchical Navigable Small World) index for fast approximate nearest neighbor search
+  #
+  # @example Basic usage
+  #   index = ClusterKit::HNSW.new(dim: 128, space: :euclidean)
+  #   index.add_batch(vectors, labels: labels)
+  #   neighbors = index.search(query_vector, k: 10)
+  #
+  # @example With metadata
+  #   index = ClusterKit::HNSW.new(dim: 768, space: :cosine)
+  #   index.add_item(vector, label: "doc_1", metadata: { title: "Introduction", date: "2024-01-01" })
+  #   results = index.search_with_metadata(query, k: 5)
+  #   # => [{ label: "doc_1", distance: 0.23, metadata: { title: "...", date: "..." } }, ...]
+  class HNSW
+    # Note: The actual HNSW class is defined in Rust (ext/clusterkit/src/hnsw.rs)
+    # This Ruby file adds additional convenience methods and documentation.
+    # The Rust implementation provides these core methods:
+    #   - new(kwargs) - constructor
+    #   - add_item(vector, kwargs) - add single item
+    #   - add_batch(vectors, kwargs) - add multiple items
+    #   - search(query, kwargs) - search for neighbors
+    #   - search_with_metadata(query, kwargs) - search with metadata
+    #   - size() - get number of items
+    #   - config() - get configuration
+    #   - stats() - get statistics
+    #   - set_ef(ef) - set search quality parameter
+    #   - save(path) - save to file
+    
+    # Initialize is actually handled by the Rust code
+    # This documentation is for reference
+    #
+    # @param dim [Integer] Dimension of vectors (required)
+    # @param space [Symbol] Distance metric: :euclidean, :cosine, or :inner_product (default: :euclidean)
+    # @param max_elements [Integer] Maximum number of elements (default: 10_000)
+    # @param m [Integer] Number of bi-directional links (default: 16)
+    # @param ef_construction [Integer] Size of dynamic candidate list (default: 200)
+    # @param random_seed [Integer, nil] Random seed for reproducible builds (default: nil)
+    # @param dynamic_list [Boolean] Allow index to grow dynamically (not yet implemented)
+    
+    # Fit the index with training data (alias for add_batch)
+    #
+    # @param data [Array<Array>, Numo::NArray] Training vectors
+    # @param labels [Array, nil] Optional labels for vectors
+    # @return [self]
+    def fit(data, labels: nil)
+      add_batch(data, labels: labels)
+      self
+    end
+    
+    # Fit and return transformed data (for compatibility with sklearn-like interface)
+    #
+    # @param data [Array<Array>, Numo::NArray] Training vectors
+    # @return [self]
+    def fit_transform(data)
+      fit(data)
+      self
+    end
+    
+    # Add a vector using the << operator
+    #
+    # @param vector [Array, Numo::NArray] Vector to add
+    # @return [self]
+    def <<(vector)
+      add_item(vector, {})
+      self
+    end
+    
+    # Alias for search that always includes distances
+    #
+    # @param query [Array, Numo::NArray] Query vector
+    # @param k [Integer] Number of neighbors
+    # @param ef [Integer, nil] Search parameter (higher = better quality, slower)
+    # @return [Array<Array>] Array of [indices, distances]
+    def knn_query(query, k: 10, ef: nil)
+      search(query, k: k, ef: ef, include_distances: true)
+    end
+    
+    # Batch search for multiple queries
+    #
+    # @param queries [Array<Array>, Numo::NArray] Multiple query vectors
+    # @param k [Integer] Number of neighbors per query
+    # @param parallel [Boolean] Process queries in parallel
+    # @return [Array<Array>] Results for each query
+    def batch_search(queries, k: 10, parallel: true)
+      queries = ensure_array(queries)
+      
+      if parallel && queries.size > 1
+        require 'parallel'
+        Parallel.map(queries) { |query| search(query, k: k) }
+      else
+        queries.map { |query| search(query, k: k) }
+      end
+    rescue LoadError
+      # Parallel gem not available, fall back to sequential
+      queries.map { |query| search(query, k: k) }
+    end
+    
+    # Range search - find all points within a given radius
+    #
+    # @param query [Array, Numo::NArray] Query vector
+    # @param radius [Float] Search radius
+    # @param limit [Integer, nil] Maximum number of results
+    # @return [Array<Hash>] Results within radius
+    def range_search(query, radius:, limit: nil)
+      # Get a large number of candidates
+      k = limit || size
+      k = [k, size].min
+      
+      results = search_with_metadata(query, k: k)
+      
+      # Filter by radius
+      results.select { |r| r[:distance] <= radius }
+             .take(limit || results.size)
+    end
+    
+    # Check if index is empty
+    # @return [Boolean]
+    def empty?
+      size == 0
+    end
+    
+    # Clear all elements from the index
+    #
+    # @return [self]
+    def clear!
+      # Would need to recreate the index
+      raise NotImplementedError, "Clear not yet implemented"
+    end
+    
+    # Check if a label exists in the index
+    #
+    # @param label [String, Integer] Label to check
+    # @return [Boolean]
+    def include?(label)
+      # This would need to be implemented in Rust
+      # For now, return false
+      false
+    end
+    
+    # Get recall rate for a test set
+    #
+    # @param test_queries [Array<Array>] Query vectors
+    # @param ground_truth [Array<Array>] True nearest neighbors for each query
+    # @param k [Integer] Number of neighbors to evaluate
+    # @return [Float] Recall rate (0.0 to 1.0)
+    def recall(test_queries, ground_truth, k: 10)
+      test_queries = ensure_array(test_queries)
+      
+      require 'set'
+      total_correct = 0
+      total_possible = 0
+      
+      test_queries.each_with_index do |query, i|
+        predicted = Set.new(search(query, k: k))
+        actual = Set.new(ground_truth[i].take(k))
+        
+        total_correct += (predicted & actual).size
+        total_possible += [k, actual.size].min
+      end
+      
+      total_possible > 0 ? total_correct.to_f / total_possible : 0.0
+    end
+    
+    # Load an index from file
+    # Note: This uses Box::leak internally to work around hnsw_rs lifetime constraints
+    # This causes a small memory leak - the HnswIo struct won't be freed until program exit
+    #
+    # @param path [String] File path to load from
+    # @return [HNSW] New HNSW instance loaded from file
+    # (The actual implementation is in Rust)
+    
+    # Create an index from embeddings produced by UMAP or other dimensionality reduction
+    #
+    # @param embeddings [Array<Array>, Numo::NArray] Embedding vectors
+    # @param kwargs [Hash] Additional options for HNSW initialization
+    # @return [HNSW] New HNSW instance
+    def self.from_embedding(embeddings, **kwargs)
+      embeddings = ensure_array(embeddings)
+      
+      dim = embeddings.first.size
+      index = new(dim: dim, **kwargs)
+      index.fit(embeddings)
+      index
+    end
+    
+    # Builder pattern for creating HNSW indices
+    class Builder
+      def initialize
+        @config = {}
+      end
+      
+      def space(type)
+        @config[:space] = type
+        self
+      end
+      
+      def dimensions(dim)
+        @config[:dim] = dim
+        self
+      end
+      
+      def max_elements(n)
+        @config[:max_elements] = n
+        self
+      end
+      
+      def m_parameter(m)
+        @config[:m] = m
+        self
+      end
+      
+      def ef_construction(ef)
+        @config[:ef_construction] = ef
+        self
+      end
+      
+      def seed(seed)
+        @config[:random_seed] = seed
+        self
+      end
+      
+      def build
+        HNSW.new(**@config)
+      end
+    end
+    
+    private
+    
+    # Ensure input is a proper array format
+    def ensure_array(data)
+      case data
+      when Array
+        data
+      else
+        data.respond_to?(:to_a) ? data.to_a : raise(ArgumentError, "Data must be convertible to Array")
+      end
+    end
+    
+    # Class method to make it available to class methods
+    def self.ensure_array(data)
+      case data
+      when Array
+        data
+      else
+        data.respond_to?(:to_a) ? data.to_a : raise(ArgumentError, "Data must be convertible to Array")
+      end
+    end
+  end
+end