Add zero-dependency native C extension for LSI acceleration (#89)

* feat: add zero-dependency native C extension for LSI acceleration

Replace the rb-gsl dependency with a self-contained C extension that
implements Vector, Matrix, and Jacobi SVD operations. This eliminates
the need for users to install external libraries while providing
significant performance improvements.

The native extension provides 5-50x speedup over pure Ruby, with the
SVD-heavy build_index operation showing up to 384x improvement on
larger document sets. The implementation ports the existing Ruby
Jacobi SVD algorithm to C, ensuring consistent results.

Key changes:
- Add ext/classifier/ with ~850 lines of C code
- Implement Classifier::Linalg::Vector and Matrix classes
- Port Jacobi SVD from Ruby to C
- Auto-detect backend: native extension > pure Ruby fallback
- Remove GSL-related code and dependencies
- Update benchmarks to compare native C vs pure Ruby

Closes #87

* chore: add native extension build artifacts to gitignore

* style: fix RuboCop offenses in tests and config files

Apply RuboCop autocorrections and add necessary inline disables:
- Use %i symbol array syntax in Rakefile
- Add empty lines before assertion methods per Minitest style
- Convert float assert_equal to assert_in_delta for precision
- Disable Style/GlobalVars for $CFLAGS (required for mkmf)
- Disable Style/MapIntoArray in test intentionally testing each

* refactor: address PR review feedback

- Use SVD_CONVERGENCE_THRESHOLD constant instead of magic number
- Clarify comment about undef_method vs override behavior

Author: cardmagic

.gitignore

@@ -5,6 +5,15 @@ coverage/
 *.gem
 pkg/
 
+# Native extension build artifacts
+*.bundle
+*.so
+*.o
+tmp/
+lib/classifier/classifier_ext.*
+Makefile
+mkmf.log
+
 # IDE/editor files
 .idea/
 *.swp

CLAUDE.md

@@ -11,16 +11,23 @@ Ruby gem providing text classification via two algorithms:
 ## Common Commands
 
 ```bash
-# Run all tests
+# Compile native C extension
+rake compile
+
+# Run all tests (compiles first)
 rake test
 
 # Run a single test file
 ruby -Ilib test/bayes/bayesian_test.rb
 ruby -Ilib test/lsi/lsi_test.rb
 
-# Run tests with native Ruby vector (without GSL)
+# Run tests with pure Ruby (no native extension)
 NATIVE_VECTOR=true rake test
 
+# Run benchmarks
+rake benchmark
+rake benchmark:compare
+
 # Interactive console
 rake console
 
@@ -39,7 +46,7 @@ rake doc
 
 **LSI Classifier** (`lib/classifier/lsi.rb`)
 - Uses Singular Value Decomposition (SVD) for semantic analysis
-- Optional GSL gem for 10x faster matrix operations; falls back to pure Ruby SVD
+- Native C extension for 5-50x faster matrix operations; falls back to pure Ruby
 - Key operations: `add_item`, `classify`, `find_related`, `search`
 - `auto_rebuild` option controls automatic index rebuilding after changes
 
@@ -49,15 +56,18 @@ rake doc
 - Uses `fast-stemmer` gem for Porter stemming
 
 **Vector Extensions** (`lib/classifier/extensions/vector.rb`)
-- Pure Ruby SVD implementation (`Matrix#SV_decomp`)
+- Pure Ruby SVD implementation (`Matrix#SV_decomp`) - used as fallback
 - Vector normalization and magnitude calculations
 
-### GSL Integration
+### Native C Extension (`ext/classifier/`)
+
+LSI uses a native C extension for fast linear algebra operations:
+- `Classifier::Linalg::Vector` - Vector operations (alloc, normalize, dot product)
+- `Classifier::Linalg::Matrix` - Matrix operations (alloc, transpose, multiply)
+- Jacobi SVD implementation for singular value decomposition
 
-LSI checks for the `gsl` gem at load time. When available:
-- Uses `GSL::Matrix` and `GSL::Vector` for faster operations
-- Serialization handled via `vector_serialize.rb`
-- Test without GSL: `NATIVE_VECTOR=true rake test`
+Check current backend: `Classifier::LSI.backend` returns `:native` or `:ruby`
+Force pure Ruby: `NATIVE_VECTOR=true rake test`
 
 ### Content Nodes (`lib/classifier/lsi/content_node.rb`)
 

Gemfile.lock

@@ -59,6 +59,8 @@ GEM
     racc (1.8.1)
     rainbow (3.1.1)
     rake (13.3.1)
+    rake-compiler (1.3.1)
+      rake
     rb-fsevent (0.11.2)
     rb-inotify (0.11.1)
       ffi (~> 1.0)
@@ -137,6 +139,7 @@ DEPENDENCIES
   minitest
   mutex_m
   ostruct
+  rake-compiler
   rbs-inline
   rdoc
   rubocop
@@ -145,4 +148,4 @@ DEPENDENCIES
   steep
 
 BUNDLED WITH
-   2.4.17
+   4.0.3

README.md

@@ -36,47 +36,27 @@ Or install directly:
 gem install classifier
 ```
 
-### Optional: GSL for Faster LSI
+### Native C Extension
 
-For significantly faster LSI operations, install the [GNU Scientific Library](https://www.gnu.org/software/gsl/).
+The gem includes a native C extension for fast LSI operations. It compiles automatically during gem installation. No external dependencies are required.
 
-<details>
-<summary><strong>Ruby 3+</strong></summary>
-
-The released `gsl` gem doesn't support Ruby 3+. Install from source:
+To verify the native extension is active:
 
-```bash
-# Install GSL library
-brew install gsl        # macOS
-apt-get install libgsl-dev  # Ubuntu/Debian
-
-# Build and install the gem
-git clone https://github.com/cardmagic/rb-gsl.git
-cd rb-gsl
-git checkout fix/ruby-3.4-compatibility
-gem build gsl.gemspec
-gem install gsl-*.gem
+```ruby
+require 'classifier'
+puts Classifier::LSI.backend  # => :native
 ```
-</details>
 
-<details>
-<summary><strong>Ruby 2.x</strong></summary>
+To force pure Ruby mode (for debugging):
 
 ```bash
-# macOS
-brew install gsl
-gem install gsl
-
-# Ubuntu/Debian
-apt-get install libgsl-dev
-gem install gsl
+NATIVE_VECTOR=true ruby your_script.rb
 ```
-</details>
 
-When GSL is installed, Classifier automatically uses it. To suppress the GSL notice:
+To suppress the warning when native extension isn't available:
 
 ```bash
-SUPPRESS_GSL_WARNING=true ruby your_script.rb
+SUPPRESS_LSI_WARNING=true ruby your_script.rb
 ```
 
 ### Compatibility
@@ -181,36 +161,37 @@ lsi.search "programming", 3
 
 ## Performance
 
-### GSL vs Native Ruby
+### Native C Extension vs Pure Ruby
 
-GSL provides dramatic speedups for LSI operations, especially `build_index` (SVD computation):
+The native C extension provides dramatic speedups for LSI operations, especially `build_index` (SVD computation):
 
 | Documents | build_index | Overall |
 |-----------|-------------|---------|
-| 5         | 4x faster   | 2.5x    |
-| 10        | 24x faster  | 5.5x    |
-| 15        | 116x faster | 17x     |
+| 5         | 7x faster   | 2.6x    |
+| 10        | 25x faster  | 4.6x    |
+| 15        | 112x faster | 14.5x   |
+| 20        | 385x faster | 48.7x   |
 
 <details>
-<summary>Detailed benchmark (15 documents)</summary>
+<summary>Detailed benchmark (20 documents)</summary>
 
 ```
-Operation              Native          GSL      Speedup
+Operation            Pure Ruby     Native C      Speedup
 ----------------------------------------------------------
-build_index            0.1412       0.0012       116.2x
-classify               0.0142       0.0049         2.9x
-search                 0.0102       0.0026         3.9x
-find_related           0.0069       0.0016         4.2x
+build_index            0.5540       0.0014       384.5x
+classify               0.0190       0.0060         3.2x
+search                 0.0145       0.0037         3.9x
+find_related           0.0098       0.0011         8.6x
 ----------------------------------------------------------
-TOTAL                  0.1725       0.0104        16.6x
+TOTAL                  0.5973       0.0123        48.7x
 ```
 </details>
 
 ### Running Benchmarks
 
 ```bash
 rake benchmark              # Run with current configuration
-rake benchmark:compare      # Compare GSL vs native Ruby
+rake benchmark:compare      # Compare native C vs pure Ruby
 ```
 
 ## Development
@@ -221,15 +202,16 @@ rake benchmark:compare      # Compare GSL vs native Ruby
 git clone https://github.com/cardmagic/classifier.git
 cd classifier
 bundle install
+rake compile  # Compile native C extension
 ```
 
 ### Running Tests
 
 ```bash
-rake test                        # Run all tests
+rake test                        # Run all tests (compiles first)
 ruby -Ilib test/bayes/bayesian_test.rb  # Run specific test file
 
-# Test without GSL (pure Ruby)
+# Test with pure Ruby (no native extension)
 NATIVE_VECTOR=true rake test
 ```
 

Rakefile

@@ -2,8 +2,20 @@ require 'rake'
 require 'rake/testtask'
 require 'rdoc/task'
 
+# Try to load rake-compiler for native extension support
+begin
+  require 'rake/extensiontask'
+  Rake::ExtensionTask.new('classifier_ext') do |ext|
+    ext.lib_dir = 'lib/classifier'
+    ext.ext_dir = 'ext/classifier'
+  end
+  HAVE_EXTENSION = true
+rescue LoadError
+  HAVE_EXTENSION = false
+end
+
 desc 'Default Task'
-task default: [:test]
+task default: HAVE_EXTENSION ? %i[compile test] : [:test]
 
 # Run the unit tests
 desc 'Run all unit tests'