spellkit 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: df48970adccf2bea2fae1a69f0e3704c0276bac9ab908a1bc5af6835edde0008
-  data.tar.gz: 28a8f37086361c742f902fa33bfd39003a1fff758b7ee306de1069344cf114d0
+  metadata.gz: e36701637cedd91531b05d0b18680e57d26b9aae7e117d6a179f27d30a61e444
+  data.tar.gz: 560114d91574153e6b618c509a705bbcd82969e4a437aee777fa2ee7f10babcc
 SHA512:
-  metadata.gz: fcc1a0678ff2714a8844657f883354594d7bfb5be6e76a2708aa6134fa5ef9ef0a407a4be06a5f727e540ab99e6d21bc086a0bc740d3bd6cc2a5ed7c6d9458b0
-  data.tar.gz: 043b4f1aa59dd2ced9219f11736053d577d8afa7bdc83cb746ab91c4dc4bb1d5fd28c05aee79c09e739a3b1dd89c49ee088b2c189af81148db09ac40e0de1f06
+  metadata.gz: 6cc82708564b26e943b4bc394ec41c13aa59c3ff7388027d113001cc8f8f8e83f219795b5547ab2ed318c9ab89733efbfbf3b937cdcf75d70a51836d5c2e4283
+  data.tar.gz: a6903fb208c64dc53bd07ee2b183e4a5bfe552d038ee87129e6afe3f32b14197c0d6546139abeada777ff98db3ee2466c86dd158561bf8d9d8beedacc6b7b335

data/README.md

@@ -1,6 +1,6 @@
 <img src="/docs/assets/spellkit-wide.png" alt="spellkit" height="160px">
 
-Fast, safe typo correction for search-term extraction, wrapping the SymSpell algorithm in Rust via Magnus.
+Fast, safe typo correction for search-term extraction. A Ruby gem with a native Rust implementation of the SymSpell algorithm.
 
 SpellKit provides:
 - **Fast correction** using SymSpell with configurable edit distance (1 or 2)
@@ -9,6 +9,8 @@ SpellKit provides:
 - **Sub-millisecond latency** - p95 < 2µs on small dictionaries
 - **Thread-safe** - built with Rust's Arc<RwLock> for safe concurrent access
 
+**Why a custom implementation?** Existing Rust SymSpell crates require lowercase dictionary entries, but SpellKit preserves canonical forms (NASA stays NASA, iPhone stays iPhone). We also needed domain-specific guards, hot-reload, and Aspell-style skip patterns - features not available in existing implementations.
+
 ## Why SpellKit?
 
 ### No Runtime Dependencies
@@ -146,13 +148,13 @@ SpellKit.load!(
   protected_patterns: [/^[A-Z]{3,4}\d+$/]
 )
 
-# Use guard: :domain to enable protection
-SpellKit.correct("CDK10", guard: :domain)
+# Protected terms are automatically respected
+SpellKit.correct("CDK10")
 # => "CDK10"  # protected, never changed
 
-# Batch correction with guards
+# Batch correction with protection
 tokens = %w[helllo wrld ABC-123 for CDK10]
-SpellKit.correct_tokens(tokens, guard: :domain)
+SpellKit.correct_tokens(tokens)
 # => ["hello", "world", "ABC-123", "for", "CDK10"]
 ```
 
@@ -300,7 +302,7 @@ SpellKit.correct("rarword")   # => "rarword" (no correction if freq < 1000)
 
 ### Skip Patterns
 
-SpellKit can automatically skip certain patterns to avoid "correcting" technical terms, URLs, and other special content. Inspired by Aspell's filter modes, these patterns are applied when `guard: :domain` is enabled.
+SpellKit can automatically skip certain patterns to avoid "correcting" technical terms, URLs, and other special content. Inspired by Aspell's filter modes, these patterns are automatically applied when configured.
 
 **Available skip patterns:**
 
@@ -315,13 +317,13 @@ SpellKit.load!(
 )
 
 # With skip patterns enabled, technical content is preserved
-SpellKit.correct("https://example.com", guard: :domain)  # => "https://example.com"
-SpellKit.correct("user@test.com", guard: :domain)        # => "user@test.com"
-SpellKit.correct("getElementById", guard: :domain)       # => "getElementById"
-SpellKit.correct("version-1.2.3", guard: :domain)        # => "version-1.2.3"
+SpellKit.correct("https://example.com")  # => "https://example.com"
+SpellKit.correct("user@test.com")        # => "user@test.com"
+SpellKit.correct("getElementById")       # => "getElementById"
+SpellKit.correct("version-1.2.3")        # => "version-1.2.3"
 
 # Regular typos are still corrected
-SpellKit.correct("helllo", guard: :domain)               # => "hello"
+SpellKit.correct("helllo")               # => "hello"
 ```
 
 **What each skip pattern matches:**
@@ -351,9 +353,9 @@ SpellKit.load!(
   protected_patterns: [/^CUSTOM-\d+$/]  # Your custom patterns
 )
 
-# Both work together
-SpellKit.correct("https://example.com", guard: :domain)  # => "https://example.com" (skip_urls)
-SpellKit.correct("CUSTOM-123", guard: :domain)           # => "CUSTOM-123" (custom pattern)
+# Both work together automatically
+SpellKit.correct("https://example.com")  # => "https://example.com" (skip_urls)
+SpellKit.correct("CUSTOM-123")           # => "CUSTOM-123" (custom pattern)
 ```
 
 ## API Reference
@@ -426,33 +428,32 @@ SpellKit.suggestions("helllo", 5)
 # => [{"term"=>"hello", "distance"=>1, "freq"=>10000}, ...]
 ```
 
-### `SpellKit.correct(word, guard:)`
+### `SpellKit.correct(word)`
 
-Return corrected word or original if no better match found. Respects `frequency_threshold` configuration.
+Return corrected word or original if no better match found. Respects `frequency_threshold` configuration. Protected terms and skip patterns are automatically applied when configured.
 
 **Parameters:**
 - `word` (required) - The word to correct
-- `guard:` (optional) - Set to `:domain` to enable protection checks
 
 **Behavior:**
 - Returns original word if it exists in dictionary
 - For misspellings, only accepts corrections with frequency ≥ `frequency_threshold`
 - Returns original word if no corrections pass the threshold
-- When `guard: :domain` is set, protected terms and skip patterns are applied
+- Automatically respects protected terms and skip patterns configured in `load!`
 
 **Example:**
 ```ruby
-SpellKit.correct("helllo")                  # => "hello"
-SpellKit.correct("hello")                   # => "hello" (already correct)
-SpellKit.correct("CDK10", guard: :domain)   # => "CDK10" (protected)
+SpellKit.correct("helllo")  # => "hello"
+SpellKit.correct("hello")   # => "hello" (already correct)
+SpellKit.correct("CDK10")   # => "CDK10" (protected if configured)
 ```
 
-### `SpellKit.correct_tokens(tokens, guard:)`
+### `SpellKit.correct_tokens(tokens)`
 
-Batch correction of an array of tokens. Respects `frequency_threshold` configuration.
+Batch correction of an array of tokens. Respects `frequency_threshold` configuration. Protected terms and skip patterns are automatically applied when configured.
 
-**Options:**
-- `guard:` - Set to `:domain` to enable protection checks
+**Parameters:**
+- `tokens` (required) - Array of words to correct
 
 **Returns:** Array of corrected strings
 
@@ -472,7 +473,7 @@ Verify system is properly loaded. Raises error if not.
 
 ## Term Protection
 
-The `guard: :domain` option enables protection for specific terms:
+When configured, SpellKit automatically protects specific terms from correction:
 
 ### Exact Matches
 Terms in `protected_path` file are never corrected, even if similar dictionary words exist. Matching is case-insensitive, but original casing is preserved in output.
@@ -536,14 +537,14 @@ end
 class SearchPreprocessor
   def self.correct_query(text)
     tokens = text.downcase.split(/\s+/)
-    SpellKit.correct_tokens(tokens, guard: :domain).join(" ")
+    SpellKit.correct_tokens(tokens).join(" ")
   end
 end
 ```
 
 ## Performance
 
-### SpellKit Standalone (M1 MacBook Pro, Ruby 3.3.0, 80k dictionary)
+### SpellKit Standalone (M4 Max MacBook Pro, Ruby 3.3.0, 80k dictionary)
 
 **Single Word Suggestions:**
 - 3,345 i/s (298.96 μs/i) with max: 1 suggestion
@@ -554,10 +555,10 @@ end
 - `correct`: 1,858 i/s (538.17 μs/i)
 - `correct_tokens` (batch): 2,005 i/s (498.76 μs/i)
 
-**Guard Performance:**
-- Without guard: 2,926 i/s (341.79 μs/i)
-- With guard: 9,337 i/s (107.10 μs/i) - **3.19x faster!**
-  *(Guards short-circuit expensive lookups)*
+**Protection Performance:**
+- Without protection: 2,926 i/s (341.79 μs/i)
+- With protection: 9,337 i/s (107.10 μs/i) - **3.19x faster!**
+  *(Protection checks short-circuit expensive dictionary lookups)*
 
 **Latency Distribution (10,000 iterations):**
 - p50: 61μs
@@ -573,6 +574,27 @@ end
 3. **High Throughput**: Over 16k operations per second with 80k word dictionary
 4. **Scales Well**: Minimal performance difference between 1 vs 10 suggestions
 
+### Comparison with Aspell
+
+SpellKit vs Aspell (M4 Max MacBook Pro, Ruby 3.3.0, 80k dictionary):
+
+**Suggestion Performance (13 misspelled words):**
+- SpellKit: 3,162 i/s (316μs per batch)
+- Aspell: 433 i/s (2.31ms per batch)
+- **SpellKit is 7.3x faster**
+
+**Spell Checking (correct? on 26 words):**
+- SpellKit: 263,279 i/s (3.8μs per batch)
+- Aspell: 72,099 i/s (13.9μs per batch)
+- **SpellKit is 3.65x faster**
+
+**Latency Distribution (10,000 single-word suggestions):**
+- SpellKit: p50=63μs, p95=69μs, p99=98μs
+- Aspell: p50=105μs, p95=121μs, p99=182μs
+- **SpellKit is 1.7x faster at p50, 1.75x faster at p95**
+
+Both libraries provide high-quality spell checking, but SpellKit's SymSpell algorithm (O(1) lookup) offers significant performance advantages over Aspell's statistical approach, especially for high-throughput applications.
+
 ## Benchmarks
 
 SpellKit includes comprehensive benchmarks to measure performance and compare with other spell checkers.
@@ -672,4 +694,4 @@ Bug reports and pull requests are welcome at https://github.com/scientist-labs/s
 
 ## License
 
-MIT License - see [LICENSE](LICENSE) file for details.
+MIT License - see [LICENSE](LICENSE.txt) file for details.

data/ext/spellkit/Cargo.toml

@@ -16,4 +16,4 @@ hashbrown = "0.15"
 unicode-normalization = "0.1"
 regex = "1.11"
 
-[dev-dependencies]
+[dev-dependencies]

data/ext/spellkit/src/lib.rs

@@ -52,14 +52,11 @@ fn correct_word(
     state: &CheckerState,
     symspell: &SymSpell,
     word: &str,
-    use_guard: bool,
 ) -> String {
-    // Check if word is protected
-    if use_guard {
-        let normalized = SymSpell::normalize_word(word);
-        if state.guards.is_protected_normalized(word, &normalized) {
-            return word.to_string();
-        }
+    // Always check if word is protected
+    let normalized = SymSpell::normalize_word(word);
+    if state.guards.is_protected_normalized(word, &normalized) {
+        return word.to_string();
     }
 
     let suggestions = symspell.suggestions(word, 5);
@@ -298,7 +295,7 @@ impl Checker {
         }
     }
 
-    fn correct_if_unknown(&self, word: String, use_guard: Option<bool>) -> Result<String, Error> {
+    fn correct_if_unknown(&self, word: String) -> Result<String, Error> {
         let ruby = Ruby::get().unwrap();
         let state = self.state.read().unwrap();
 
@@ -307,18 +304,17 @@ impl Checker {
         }
 
         if let Some(ref symspell) = state.symspell {
-            Ok(correct_word(&state, symspell, &word, use_guard.unwrap_or(false)))
+            Ok(correct_word(&state, symspell, &word))
         } else {
             Err(Error::new(ruby.exception_runtime_error(), "SymSpell not initialized"))
         }
     }
 
-    fn correct_tokens(&self, tokens: RArray, use_guard: Option<bool>) -> Result<RArray, Error> {
+    fn correct_tokens(&self, tokens: RArray) -> Result<RArray, Error> {
         // Optimize batch correction by acquiring lock once for all tokens
         // instead of calling correct_if_unknown per token (which re-locks each time)
         let ruby = Ruby::get().unwrap();
         let state = self.state.read().unwrap();
-        let use_guard = use_guard.unwrap_or(false);
 
         if !state.loaded {
             return Err(Error::new(ruby.exception_runtime_error(), "Dictionary not loaded. Call load! first"));
@@ -329,7 +325,7 @@ impl Checker {
         if let Some(ref symspell) = state.symspell {
             for token in tokens.into_iter() {
                 let word: String = TryConvert::try_convert(token)?;
-                let corrected = correct_word(&state, symspell, &word, use_guard);
+                let corrected = correct_word(&state, symspell, &word);
                 result.push(corrected)?;
             }
 
@@ -388,8 +384,8 @@ fn init(_ruby: &Ruby) -> Result<(), Error> {
     checker_class.define_method("load!", method!(Checker::load_full, 1))?;
     checker_class.define_method("suggestions", method!(Checker::suggestions, 2))?;
     checker_class.define_method("correct?", method!(Checker::correct, 1))?;
-    checker_class.define_method("correct", method!(Checker::correct_if_unknown, 2))?;
-    checker_class.define_method("correct_tokens", method!(Checker::correct_tokens, 2))?;
+    checker_class.define_method("correct", method!(Checker::correct_if_unknown, 1))?;
+    checker_class.define_method("correct_tokens", method!(Checker::correct_tokens, 1))?;
     checker_class.define_method("stats", method!(Checker::stats, 0))?;
     checker_class.define_method("healthcheck", method!(Checker::healthcheck, 0))?;
 

data/lib/spellkit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SpellKit
-  VERSION = "0.1.0"
+  VERSION = "0.1.2"
 end

data/lib/spellkit.rb

@@ -76,12 +76,12 @@ module SpellKit
       default.correct?(word)
     end
 
-    def correct(word, guard: nil)
-      default.correct(word, guard: guard)
+    def correct(word)
+      default.correct(word)
     end
 
-    def correct_tokens(tokens, guard: nil)
-      default.correct_tokens(tokens, guard: guard)
+    def correct_tokens(tokens)
+      default.correct_tokens(tokens)
     end
 
     def stats
@@ -211,19 +211,17 @@ class SpellKit::Checker
     _rust_correct?(word)
   end
 
-  def correct(word, guard: nil)
+  def correct(word)
     raise SpellKit::InvalidArgumentError, "word cannot be nil" if word.nil?
     raise SpellKit::InvalidArgumentError, "word cannot be empty" if word.to_s.empty?
 
-    use_guard = guard == :domain
-    _rust_correct(word, use_guard)
+    _rust_correct(word)
   end
 
-  def correct_tokens(tokens, guard: nil)
+  def correct_tokens(tokens)
     raise SpellKit::InvalidArgumentError, "tokens must be an Array" unless tokens.is_a?(Array)
 
-    use_guard = guard == :domain
-    _rust_correct_tokens(tokens, use_guard)
+    _rust_correct_tokens(tokens)
   end
 
   def stats

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: spellkit
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Chris Petersen
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-09-27 00:00:00.000000000 Z
+date: 2025-09-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rb_sys
@@ -150,8 +150,8 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: A Ruby gem that provides fast typo correction using SymSpell algorithm,
-  with domain-specific term protection
+description: A Ruby gem with a native Rust implementation of the SymSpell algorithm
+  for fast typo correction with domain-specific term protection
 email:
 - chris@petersen.io
 executables: []
@@ -191,7 +191,6 @@ licenses:
 metadata:
   homepage_uri: https://github.com/scientist-labs/spellkit
   source_code_uri: https://github.com/scientist-labs/spellkit
-  changelog_uri: https://github.com/scientist-labs/spellkit/blob/main/CHANGELOG.md
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -206,7 +205,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
-requirements: []
+requirements:
+- Rust >= 1.85
 rubygems_version: 3.5.3
 signing_key:
 specification_version: 4