feat(bayes): add keyword argument API for train and untrain

Replace method_missing magic with explicit keyword arguments as the
primary training API. This provides better IDE discoverability and
a more modern Ruby interface.

New API:
  classifier.train(spam: "text")
  classifier.train(spam: ["msg1", "msg2"], ham: ["msg3"])

Batch training and multi-category training in a single call are now
supported. Legacy positional args and dynamic methods still work for
backwards compatibility.

Closes #96

Author: cardmagic

README.md

@@ -81,13 +81,17 @@ Fast, accurate classification with modest memory requirements. Ideal for spam fi
 ```ruby
 require 'classifier'
 
-classifier = Classifier::Bayes.new('Spam', 'Ham')
+classifier = Classifier::Bayes.new(:spam, :ham)
 
-# Train the classifier
-classifier.train_spam "Buy cheap viagra now! Limited offer!"
-classifier.train_spam "You've won a million dollars! Claim now!"
-classifier.train_ham "Meeting scheduled for tomorrow at 10am"
-classifier.train_ham "Please review the attached document"
+# Train with keyword arguments
+classifier.train(spam: "Buy cheap viagra now! Limited offer!")
+classifier.train(ham: "Meeting scheduled for tomorrow at 10am")
+
+# Train multiple items at once
+classifier.train(
+  spam: ["You've won a million dollars!", "Free money!!!"],
+  ham: ["Please review the document", "Lunch tomorrow?"]
+)
 
 # Classify new text
 classifier.classify "Congratulations! You've won a prize!"
@@ -152,9 +156,9 @@ Save and load trained classifiers with pluggable storage backends. Works with bo
 ```ruby
 require 'classifier'
 
-classifier = Classifier::Bayes.new('Spam', 'Ham')
-classifier.train_spam "Buy now! Limited offer!"
-classifier.train_ham "Meeting tomorrow at 3pm"
+classifier = Classifier::Bayes.new(:spam, :ham)
+classifier.train(spam: "Buy now! Limited offer!")
+classifier.train(ham: "Meeting tomorrow at 3pm")
 
 # Configure storage and save
 classifier.storage = Classifier::Storage::File.new(path: "spam_filter.json")

lib/classifier/bayes.rb

@@ -41,57 +41,45 @@ def initialize(*categories)
 
     # Provides a general training method for all categories specified in Bayes#new
     # For example:
-    #     b = Classifier::Bayes.new 'This', 'That', 'the_other'
-    #     b.train :this, "This text"
-    #     b.train "that", "That text"
-    #     b.train "The other", "The other text"
+    #     b = Classifier::Bayes.new :spam, :ham
     #
-    # @rbs (String | Symbol, String) -> void
-    def train(category, text)
-      category = category.prepare_category_name
-      word_hash = text.word_hash
-      synchronize do
-        invalidate_caches
-        @dirty = true
-        @category_counts[category] += 1
-        word_hash.each do |word, count|
-          @categories[category][word] ||= 0
-          @categories[category][word] += count
-          @total_words += count
-          @category_word_count[category] += count
-        end
+    #     # Keyword argument API (preferred)
+    #     b.train(spam: "Buy cheap viagra now!!!")
+    #     b.train(spam: ["msg1", "msg2"], ham: ["msg3", "msg4"])
+    #
+    #     # Positional argument API (legacy)
+    #     b.train :spam, "This text"
+    #     b.train "ham", "That text"
+    #
+    # @rbs (?String | Symbol, ?String, **String | Array[String]) -> void
+    def train(category = nil, text = nil, **categories)
+      return train_single(category, text) if category
+
+      categories.each do |cat, texts|
+        Array(texts).each { |t| train_single(cat, t) }
       end
     end
 
     # Provides a untraining method for all categories specified in Bayes#new
     # Be very careful with this method.
     #
     # For example:
-    #     b = Classifier::Bayes.new 'This', 'That', 'the_other'
-    #     b.train :this, "This text"
-    #     b.untrain :this, "This text"
+    #     b = Classifier::Bayes.new :spam, :ham
     #
-    # @rbs (String | Symbol, String) -> void
-    def untrain(category, text)
-      category = category.prepare_category_name
-      word_hash = text.word_hash
-      synchronize do
-        invalidate_caches
-        @dirty = true
-        @category_counts[category] -= 1
-        word_hash.each do |word, count|
-          next unless @total_words >= 0
+    #     # Keyword argument API (preferred)
+    #     b.train(spam: "Buy cheap viagra now!!!")
+    #     b.untrain(spam: "Buy cheap viagra now!!!")
+    #
+    #     # Positional argument API (legacy)
+    #     b.train :spam, "This text"
+    #     b.untrain :spam, "This text"
+    #
+    # @rbs (?String | Symbol, ?String, **String | Array[String]) -> void
+    def untrain(category = nil, text = nil, **categories)
+      return untrain_single(category, text) if category
 
-          orig = @categories[category][word] || 0
-          @categories[category][word] ||= 0
-          @categories[category][word] -= count
-          if @categories[category][word] <= 0
-            @categories[category].delete(word)
-            count = orig
-          end
-          @category_word_count[category] -= count if @category_word_count[category] >= count
-          @total_words -= count
-        end
+      categories.each do |cat, texts|
+        Array(texts).each { |t| untrain_single(cat, t) }
       end
     end
 
@@ -340,6 +328,49 @@ def remove_category(category)
 
     private
 
+    # Core training logic for a single category and text.
+    # @rbs (String | Symbol, String) -> void
+    def train_single(category, text)
+      category = category.prepare_category_name
+      word_hash = text.word_hash
+      synchronize do
+        invalidate_caches
+        @dirty = true
+        @category_counts[category] += 1
+        word_hash.each do |word, count|
+          @categories[category][word] ||= 0
+          @categories[category][word] += count
+          @total_words += count
+          @category_word_count[category] += count
+        end
+      end
+    end
+
+    # Core untraining logic for a single category and text.
+    # @rbs (String | Symbol, String) -> void
+    def untrain_single(category, text)
+      category = category.prepare_category_name
+      word_hash = text.word_hash
+      synchronize do
+        invalidate_caches
+        @dirty = true
+        @category_counts[category] -= 1
+        word_hash.each do |word, count|
+          next unless @total_words >= 0
+
+          orig = @categories[category][word] || 0
+          @categories[category][word] ||= 0
+          @categories[category][word] -= count
+          if @categories[category][word] <= 0
+            @categories[category].delete(word)
+            count = orig
+          end
+          @category_word_count[category] -= count if @category_word_count[category] >= count
+          @total_words -= count
+        end
+      end
+    end
+
     # Restores classifier state from a JSON string (used by reload)
     # @rbs (String) -> void
     def restore_from_json(json)

test/bayes/bayesian_test.rb

@@ -246,6 +246,75 @@ def test_untrain_decrements_category_word_count
     assert_operator new_word_count, :<, initial_word_count, 'Category word count should decrease'
   end
 
+  # Keyword argument API tests
+
+  def test_train_with_keyword_argument
+    @classifier.train(interesting: 'good words here')
+    @classifier.train(uninteresting: 'bad words there')
+
+    assert_equal 'Interesting', @classifier.classify('good words')
+    assert_equal 'Uninteresting', @classifier.classify('bad words')
+  end
+
+  def test_train_with_array_value
+    @classifier.train(interesting: ['good words', 'great content', 'love this'])
+    @classifier.train(uninteresting: 'bad stuff')
+
+    assert_equal 'Interesting', @classifier.classify('good great love')
+  end
+
+  def test_train_with_multiple_categories
+    @classifier.train(
+      interesting: ['good words', 'great content'],
+      uninteresting: ['bad words', 'boring stuff']
+    )
+
+    assert_equal 'Interesting', @classifier.classify('good great')
+    assert_equal 'Uninteresting', @classifier.classify('bad boring')
+  end
+
+  def test_untrain_with_keyword_argument
+    @classifier.train(interesting: 'hello world')
+    @classifier.untrain(interesting: 'hello world')
+
+    category_words = @classifier.instance_variable_get(:@categories)[:Interesting]
+
+    assert_empty category_words
+  end
+
+  def test_untrain_with_array_value
+    @classifier.train(interesting: ['apple', 'banana', 'cherry'])
+    @classifier.untrain(interesting: ['apple', 'banana'])
+
+    result = @classifier.classify('cherry')
+
+    assert_equal 'Interesting', result
+  end
+
+  def test_keyword_and_positional_produce_same_result
+    classifier1 = Classifier::Bayes.new 'Spam', 'Ham'
+    classifier1.train :spam, 'buy now'
+    classifier1.train :ham, 'hello friend'
+
+    classifier2 = Classifier::Bayes.new 'Spam', 'Ham'
+    classifier2.train(spam: 'buy now')
+    classifier2.train(ham: 'hello friend')
+
+    assert_equal classifier1.classify('buy'), classifier2.classify('buy')
+    assert_equal classifier1.classify('hello'), classifier2.classify('hello')
+  end
+
+  def test_keyword_and_dynamic_method_produce_same_result
+    classifier1 = Classifier::Bayes.new 'Spam', 'Ham'
+    classifier1.train_spam 'buy now'
+    classifier1.train_ham 'hello friend'
+
+    classifier2 = Classifier::Bayes.new 'Spam', 'Ham'
+    classifier2.train(spam: 'buy now', ham: 'hello friend')
+
+    assert_equal classifier1.classifications('buy'), classifier2.classifications('buy')
+  end
+
   # Edge case tests
 
   def test_empty_string_training