clusterkit 0.3.0-x86_64-linux

data/ext/clusterkit/src/utils.rs

@@ -0,0 +1,183 @@
+use magnus::{function, prelude::*, Error, Value, RArray, TryConvert, Float, Integer, Ruby};
+use ndarray::Array2;
+
+pub fn init(parent: &magnus::RModule) -> Result<(), Error> {
+    let utils_module = parent.define_module("Utils")?;
+
+    utils_module.define_singleton_method(
+        "estimate_intrinsic_dimension_rust",
+        function!(estimate_intrinsic_dimension, 2),
+    )?;
+
+    utils_module.define_singleton_method(
+        "estimate_hubness_rust",
+        function!(estimate_hubness, 1),
+    )?;
+
+    Ok(())
+}
+
+fn estimate_intrinsic_dimension(_data: Value, _k_neighbors: usize) -> Result<f64, Error> {
+    let ruby = Ruby::get().unwrap();
+    Err(Error::new(
+        ruby.exception_not_imp_error(),
+        "Dimension estimation not implemented yet",
+    ))
+}
+
+fn estimate_hubness(_data: Value) -> Result<Value, Error> {
+    let ruby = Ruby::get().unwrap();
+    Err(Error::new(
+        ruby.exception_not_imp_error(),
+        "Hubness estimation not implemented yet",
+    ))
+}
+
+/// Convert Ruby 2D array to ndarray Array2<f64>
+/// Handles validation and provides consistent error messages
+pub fn ruby_array_to_ndarray2(data: Value) -> Result<Array2<f64>, Error> {
+    let ruby = Ruby::get().unwrap();
+    let rarray: RArray = TryConvert::try_convert(data)?;
+    let n_samples = rarray.len();
+
+    if n_samples == 0 {
+        return Err(Error::new(
+            ruby.exception_arg_error(),
+            "Data cannot be empty",
+        ));
+    }
+
+    // Get dimensions from first row
+    let first_row: RArray = rarray.entry::<RArray>(0)?;
+    let n_features = first_row.len();
+
+    if n_features == 0 {
+        return Err(Error::new(
+            ruby.exception_arg_error(),
+            "Data rows cannot be empty",
+        ));
+    }
+
+    // Create ndarray and populate
+    let mut data_array = Array2::<f64>::zeros((n_samples, n_features));
+    for i in 0..n_samples {
+        let row: RArray = rarray.entry(i as isize)?;
+
+        // Validate row length consistency
+        if row.len() != n_features {
+            return Err(Error::new(
+                ruby.exception_arg_error(),
+                format!("Row {} has {} elements, expected {}", i, row.len(), n_features),
+            ));
+        }
+
+        for j in 0..n_features {
+            let val: f64 = row.entry(j as isize)?;
+            data_array[[i, j]] = val;
+        }
+    }
+
+    Ok(data_array)
+}
+
+/// Convert Ruby 2D array to Vec<Vec<f64>>
+/// Handles validation and provides consistent error messages
+pub fn ruby_array_to_vec_vec_f64(data: Value) -> Result<Vec<Vec<f64>>, Error> {
+    let ruby = Ruby::get().unwrap();
+    let rarray: RArray = TryConvert::try_convert(data)?;
+    let n_samples = rarray.len();
+
+    if n_samples == 0 {
+        return Err(Error::new(
+            ruby.exception_arg_error(),
+            "Data cannot be empty",
+        ));
+    }
+
+    let mut data_vec: Vec<Vec<f64>> = Vec::with_capacity(n_samples);
+    let mut expected_features: Option<usize> = None;
+
+    for i in 0..n_samples {
+        let row: RArray = rarray.entry(i as isize)?;
+        let n_features = row.len();
+
+        // Check row length consistency
+        match expected_features {
+            Some(expected) => {
+                if n_features != expected {
+                    return Err(Error::new(
+                        ruby.exception_arg_error(),
+                        format!("Row {} has {} elements, expected {}", i, n_features, expected),
+                    ));
+                }
+            }
+            None => expected_features = Some(n_features),
+        }
+
+        let mut row_vec: Vec<f64> = Vec::with_capacity(n_features);
+        for j in 0..n_features {
+            let val: f64 = row.entry(j as isize)?;
+            row_vec.push(val);
+        }
+        data_vec.push(row_vec);
+    }
+
+    Ok(data_vec)
+}
+
+/// Convert Ruby 2D array to Vec<Vec<f32>>
+/// For algorithms that require f32 precision (like UMAP)
+pub fn ruby_array_to_vec_vec_f32(data: Value) -> Result<Vec<Vec<f32>>, Error> {
+    let ruby = Ruby::get().unwrap();
+    let rarray: RArray = TryConvert::try_convert(data)?;
+    let array_len = rarray.len();
+
+    if array_len == 0 {
+        return Err(Error::new(
+            ruby.exception_arg_error(),
+            "Input data cannot be empty",
+        ));
+    }
+
+    let mut rust_data: Vec<Vec<f32>> = Vec::with_capacity(array_len);
+
+    for i in 0..array_len {
+        let row = rarray.entry::<Value>(i as isize)?;
+        let row_array = RArray::try_convert(row).map_err(|_| {
+            Error::new(
+                ruby.exception_type_error(),
+                "Expected array of arrays (2D array)",
+            )
+        })?;
+
+        let mut rust_row: Vec<f32> = Vec::new();
+        let row_len = row_array.len();
+
+        for j in 0..row_len {
+            let val = row_array.entry::<Value>(j as isize)?;
+            let float_val = if let Ok(f) = Float::try_convert(val) {
+                f.to_f64() as f32
+            } else if let Ok(i) = Integer::try_convert(val) {
+                i.to_i64()? as f32
+            } else {
+                return Err(Error::new(
+                    ruby.exception_type_error(),
+                    "All values must be numeric",
+                ));
+            };
+            rust_row.push(float_val);
+        }
+
+        // Validate row length consistency
+        if !rust_data.is_empty() && rust_row.len() != rust_data[0].len() {
+            return Err(Error::new(
+                ruby.exception_arg_error(),
+                "All rows must have the same length",
+            ));
+        }
+
+        rust_data.push(rust_row);
+    }
+
+    Ok(rust_data)
+}

data/lib/clusterkit/clustering/hdbscan.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require_relative '../data_validator'
+
+module ClusterKit
+  module Clustering
+    # HDBSCAN clustering algorithm - matching KMeans API pattern
+    class HDBSCAN
+      attr_reader :min_samples, :min_cluster_size, :metric, :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
+        
+        valid_metrics = ['euclidean', 'l2', 'manhattan', 'l1', 'cosine']
+        unless valid_metrics.include?(metric)
+          raise ArgumentError, "metric must be one of: #{valid_metrics.join(', ')}"
+        end
+        
+        @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?
+        # Count unique labels excluding -1 (noise)
+        unique_labels = @labels.uniq.reject { |l| l == -1 }
+        unique_labels.length
+      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
+
+      # Get the number of noise points
+      # @return [Integer] Number of points labeled as noise
+      def n_noise_points
+        return 0 unless fitted?
+        @labels.count(-1)
+      end
+
+      # Get indices of noise points
+      # @return [Array<Integer>] Indices of points labeled as noise
+      def noise_indices
+        return [] unless fitted?
+        @labels.each_with_index.select { |label, _| label == -1 }.map { |_, idx| idx }
+      end
+
+      # Get indices of points in each cluster
+      # @return [Hash<Integer, Array<Integer>>] Mapping of cluster label to point indices
+      def cluster_indices
+        return {} unless fitted?
+        
+        result = {}
+        @labels.each_with_index do |label, idx|
+          next if label == -1  # Skip noise points
+          result[label] ||= []
+          result[label] << idx
+        end
+        result
+      end
+
+      # Get summary statistics
+      # @return [Hash] Summary of clustering results
+      def summary
+        return {} unless fitted?
+        
+        {
+          n_clusters: n_clusters,
+          n_noise_points: n_noise_points,
+          noise_ratio: noise_ratio,
+          cluster_sizes: cluster_indices.transform_values(&:length),
+          cluster_persistence: @cluster_persistence
+        }
+      end
+
+      private
+
+      def validate_data(data)
+        # Use same validation as KMeans for consistency
+        DataValidator.validate_clustering(data, check_finite: false)
+      end
+    end
+
+    # Module-level convenience methods (matching KMeans pattern)
+    class << self
+      # Perform HDBSCAN clustering (matches Clustering.kmeans signature pattern)
+      # @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
+      # @param metric [String] Distance metric
+      # @return [Hash] Result hash with :labels, :probabilities, :outlier_scores
+      def hdbscan(data, min_samples: 5, min_cluster_size: 5, metric: 'euclidean')
+        clusterer = HDBSCAN.new(
+          min_samples: min_samples,
+          min_cluster_size: min_cluster_size,
+          metric: metric
+        )
+        clusterer.fit(data)
+        {
+          labels: clusterer.labels,
+          probabilities: clusterer.probabilities,
+          outlier_scores: clusterer.outlier_scores,
+          n_clusters: clusterer.n_clusters,
+          noise_ratio: clusterer.noise_ratio,
+          cluster_persistence: clusterer.cluster_persistence || {}
+        }
+      end
+    end
+  end
+end

data/lib/clusterkit/clustering.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+require_relative 'clusterkit'
+require_relative 'clustering/hdbscan'
+require_relative 'data_validator'
+
+module ClusterKit
+  # Module for clustering algorithms
+  module Clustering
+    # K-means clustering algorithm
+    class KMeans
+      attr_reader :k, :max_iter, :centroids, :labels, :inertia
+
+      # Initialize K-means clusterer
+      # @param k [Integer] Number of clusters
+      # @param max_iter [Integer] Maximum iterations (default: 300)
+      # @param random_seed [Integer] Random seed for reproducibility (optional)
+      def initialize(k:, max_iter: 300, random_seed: nil)
+        raise ArgumentError, "k must be positive" unless k > 0
+        @k = k
+        @max_iter = max_iter
+        @random_seed = random_seed
+        @fitted = false
+      end
+
+      # Fit the K-means model
+      # @param data [Array] 2D array of data points
+      # @return [self] Returns self for method chaining
+      def fit(data)
+        validate_data(data)
+        
+        # Call Rust implementation with optional seed
+        @labels, @centroids, @inertia = Clustering.kmeans_rust(data, @k, @max_iter, @random_seed)
+        @fitted = true
+        
+        self
+      end
+
+      # Predict cluster labels for new data
+      # @param data [Array] 2D array of data points
+      # @return [Array] Cluster labels
+      def predict(data)
+        raise RuntimeError, "Model must be fitted before predict" unless fitted?
+        validate_data(data)
+        
+        Clustering.kmeans_predict_rust(data, @centroids)
+      end
+
+      # Fit the model and return labels
+      # @param data [Array] 2D array of data points
+      # @return [Array] Cluster labels
+      def fit_predict(data)
+        fit(data)
+        @labels
+      end
+
+      # Check if model has been fitted
+      # @return [Boolean] True if fitted
+      def fitted?
+        @fitted
+      end
+
+      # Get cluster centers
+      # @return [Array] 2D array of cluster centers
+      def cluster_centers
+        @centroids
+      end
+
+      # Get the sum of squared distances of samples to their closest cluster center
+      # @return [Float] Inertia value
+      def inertia
+        @inertia
+      end
+
+      # Class methods for K-means specific utilities
+      class << self
+        # Find optimal number of clusters using elbow method
+        # @param data [Array] 2D array of data points
+        # @param k_range [Range] Range of k values to try
+        # @param max_iter [Integer] Maximum iterations per k
+        # @return [Hash] Mapping of k to inertia values
+        def elbow_method(data, k_range: 2..10, max_iter: 300)
+          results = {}
+          
+          k_range.each do |k|
+            kmeans = new(k: k, max_iter: max_iter)
+            kmeans.fit(data)
+            results[k] = kmeans.inertia
+          end
+          
+          results
+        end
+
+        # Detect optimal k from elbow method results
+        # @param elbow_results [Hash] Mapping of k to inertia values (from elbow_method)
+        # @param fallback_k [Integer] Default k to return if detection fails (default: 3)
+        # @return [Integer] Optimal number of clusters
+        def detect_optimal_k(elbow_results, fallback_k: 3)
+          return fallback_k if elbow_results.nil? || elbow_results.empty?
+          
+          k_values = elbow_results.keys.sort
+          return k_values.first if k_values.size == 1
+          
+          # Find the k with the largest drop in inertia
+          max_drop = 0
+          optimal_k = k_values.first
+          
+          k_values.each_cons(2) do |k1, k2|
+            drop = elbow_results[k1] - elbow_results[k2]
+            if drop > max_drop
+              max_drop = drop
+              optimal_k = k2  # Use k after the drop
+            end
+          end
+          
+          optimal_k
+        end
+
+        # Find optimal k and return it
+        # @param data [Array] 2D array of data points
+        # @param k_range [Range] Range of k values to try (default: 2..10)
+        # @param max_iter [Integer] Maximum iterations (default: 300)
+        # @return [Integer] Optimal number of clusters
+        def optimal_k(data, k_range: 2..10, max_iter: 300)
+          elbow_results = elbow_method(data, k_range: k_range, max_iter: max_iter)
+          detect_optimal_k(elbow_results)
+        end
+      end
+
+      private
+
+      def validate_data(data)
+        DataValidator.validate_clustering(data, check_finite: false)
+      end
+    end
+
+    # Module-level methods for cross-algorithm functionality
+    class << self
+      # Calculate silhouette score for any clustering result
+      # @param data [Array] 2D array of data points
+      # @param labels [Array] Cluster labels
+      # @return [Float] Mean silhouette coefficient
+      def silhouette_score(data, labels)
+        n_samples = data.size
+        unique_labels = labels.uniq
+        
+        return 0.0 if unique_labels.size == 1
+        
+        silhouette_values = []
+        
+        data.each_with_index do |point, i|
+          cluster_label = labels[i]
+          
+          # Calculate mean intra-cluster distance
+          same_cluster_indices = labels.each_index.select { |j| labels[j] == cluster_label && j != i }
+          if same_cluster_indices.empty?
+            silhouette_values << 0.0
+            next
+          end
+          
+          a = same_cluster_indices.sum { |j| euclidean_distance(point, data[j]) } / same_cluster_indices.size.to_f
+          
+          # Calculate mean nearest-cluster distance
+          b = Float::INFINITY
+          unique_labels.each do |other_label|
+            next if other_label == cluster_label
+            
+            other_cluster_indices = labels.each_index.select { |j| labels[j] == other_label }
+            next if other_cluster_indices.empty?
+            
+            mean_dist = other_cluster_indices.sum { |j| euclidean_distance(point, data[j]) } / other_cluster_indices.size.to_f
+            b = mean_dist if mean_dist < b
+          end
+          
+          # Calculate silhouette value for this point
+          if a == 0.0 && b == 0.0
+            s = 0.0  # When all points are identical
+          else
+            s = (b - a) / [a, b].max
+          end
+          silhouette_values << s
+        end
+        
+        silhouette_values.sum / silhouette_values.size.to_f
+      end
+
+      private
+
+      def euclidean_distance(a, b)
+        Math.sqrt(a.zip(b).sum { |x, y| (x - y) ** 2 })
+      end
+    end
+  end
+end

data/lib/clusterkit/clusterkit.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# Load the compiled Rust extension. Precompiled (platform) gems install it into a
+# Ruby-ABI-versioned subdir (lib/clusterkit/<major.minor>/clusterkit.{so,bundle}) so a
+# single fat gem can carry a binary per Ruby version; source/dev builds place it flat at
+# lib/clusterkit/clusterkit.{so,bundle}. Try the versioned path first, fall back to the
+# flat one. Resolution goes through $LOAD_PATH (`require`, never `require_relative`)
+# because RubyGems installs native extensions outside the gem's lib/ dir.
+begin
+  RUBY_VERSION =~ /(\d+\.\d+)/
+  require "clusterkit/#{Regexp.last_match(1)}/clusterkit"
+rescue LoadError
+  require "clusterkit/clusterkit"
+end

data/lib/clusterkit/configuration.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module ClusterKit
+  class << self
+    attr_accessor :configuration
+  end
+
+  def self.configure
+    self.configuration ||= Configuration.new
+    yield(configuration) if block_given?
+  end
+
+  class Configuration
+    attr_accessor :verbose
+
+    def initialize
+      # Default to quiet unless explicitly set or debug env var is present
+      @verbose = ENV['CLUSTERKIT_VERBOSE'] == 'true' || ENV['DEBUG'] == 'true'
+    end
+  end
+end
+
+# Initialize default configuration
+ClusterKit.configure