feat(lsi): add hash-style API for adding items (#101)

* test: add property-based tests for probabilistic invariants

Add comprehensive property-based testing using the Rantly gem to verify
that probabilistic invariants hold across random inputs. This addresses
the gap in test coverage for edge cases and mathematical properties.

Tests added for Bayes classifier:
- Classification determinism (same input = same output)
- Training order independence (commutativity)
- Train/untrain inverse property
- Word and category counts never go negative
- Log probabilities are always finite
- Multiple training equivalence

Tests added for LSI:
- Classification, search, and find_related determinism
- Graceful handling of uncategorized items
- Consistency after index rebuild

Tests added for category operations:
- Add/remove category consistency
- Training data isolation between categories

Closes #70

* style: fix RuboCop offenses in property tests

* refactor: remove redundant comments from property tests

* ci: drop Ruby 3.2 from test matrix

* feat(lsi): add hash-style API for adding items

The existing add_item API had confusing positional arguments - it wasn't
clear whether the first argument was the key or the content. The new
add() method uses hash syntax to make the relationship explicit:

  lsi.add("Ruby programming" => doc1)
  lsi.add("Java development" => [doc2, :programming])

This also enables batch operations naturally:

  lsi.add(
    "Ruby programming" => doc1,
    "Java development" => doc2
  )

The add_item method is preserved but marked as deprecated for backward
compatibility.

Closes #100

* style: fix RuboCop symbol array offenses

* fix(lsi): correct add API to use category => items syntax

The hash key should be the category, with values being items (or arrays
of items) that belong to that category. This mirrors the Bayes API:

  lsi.add("Dog" => "Dogs are loyal pets")
  lsi.add("Dog" => ["Puppies are cute", "Canines are friendly"])
  lsi.add(
    "Dog" => ["Dogs are loyal", "Puppies are cute"],
    "Cat" => ["Cats are independent", "Kittens are playful"]
  )

* refactor(lsi): simplify add method with Array()

Author: cardmagic

README.md

@@ -115,19 +115,27 @@ require 'classifier'
 
 lsi = Classifier::LSI.new
 
-# Add documents with categories
-lsi.add_item "Dogs are loyal pets that love to play fetch", :pets
-lsi.add_item "Cats are independent and love to nap", :pets
-lsi.add_item "Ruby is a dynamic programming language", :programming
-lsi.add_item "Python is great for data science", :programming
+# Add documents with hash-style syntax (category => item(s))
+lsi.add("Pets" => "Dogs are loyal pets that love to play fetch")
+lsi.add("Pets" => "Cats are independent and love to nap")
+lsi.add("Programming" => "Ruby is a dynamic programming language")
+
+# Add multiple items with the same category
+lsi.add("Programming" => ["Python is great for data science", "JavaScript runs in browsers"])
+
+# Batch operations with multiple categories
+lsi.add(
+  "Pets" => ["Hamsters are small furry pets", "Birds can be great companions"],
+  "Programming" => "Go is fast and concurrent"
+)
 
 # Classify new text
 lsi.classify "My puppy loves to run around"
-# => :pets
+# => "Pets"
 
 # Get classification with confidence score
 lsi.classify_with_confidence "Learning to code in Ruby"
-# => [:programming, 0.89]
+# => ["Programming", 0.89]
 ```
 
 ### Search and Discovery

lib/classifier/lsi.rb

@@ -122,12 +122,39 @@ def singular_value_spectrum
       end
     end
 
+    # Adds items to the index using hash-style syntax.
+    # The hash keys are categories, and values are items (or arrays of items).
+    #
+    # For example:
+    #   lsi = Classifier::LSI.new
+    #   lsi.add("Dog" => "Dogs are loyal pets")
+    #   lsi.add("Cat" => "Cats are independent")
+    #   lsi.add(Bird: "Birds can fly")  # Symbol keys work too
+    #
+    # Multiple items with the same category:
+    #   lsi.add("Dog" => ["Dogs are loyal", "Puppies are cute"])
+    #
+    # Batch operations with multiple categories:
+    #   lsi.add(
+    #     "Dog" => ["Dogs are loyal", "Puppies are cute"],
+    #     "Cat" => ["Cats are independent", "Kittens are playful"]
+    #   )
+    #
+    # @rbs (**untyped items) -> void
+    def add(**items)
+      items.each do |category, value|
+        Array(value).each { |doc| add_item(doc, category.to_s) }
+      end
+    end
+
     # Adds an item to the index. item is assumed to be a string, but
     # any item may be indexed so long as it responds to #to_s or if
     # you provide an optional block explaining how the indexer can
     # fetch fresh string data. This optional block is passed the item,
     # so the item may only be a reference to a URL or file name.
     #
+    # @deprecated Use {#add} instead for clearer hash-style syntax.
+    #
     # For example:
     #   lsi = Classifier::LSI.new
     #   lsi.add_item "This is just plain text"

test/lsi/lsi_test.rb

@@ -11,6 +11,110 @@ def setup
     @str5 = 'This text involves birds. Birds.'
   end
 
+  # Hash-style add API tests (Issue #100)
+
+  def test_add_with_hash_syntax
+    lsi = Classifier::LSI.new
+    lsi.add('Dog' => 'Dogs are loyal pets')
+    lsi.add('Cat' => 'Cats are independent')
+
+    assert_equal 2, lsi.items.size
+    assert_includes lsi.items, 'Dogs are loyal pets'
+    assert_includes lsi.items, 'Cats are independent'
+  end
+
+  def test_add_with_symbol_keys
+    lsi = Classifier::LSI.new
+    lsi.add(Dog: 'Dogs are loyal', Cat: 'Cats are independent')
+
+    assert_equal 2, lsi.items.size
+    assert_equal ['Dog'], lsi.categories_for('Dogs are loyal')
+    assert_equal ['Cat'], lsi.categories_for('Cats are independent')
+  end
+
+  def test_add_multiple_items_same_category
+    lsi = Classifier::LSI.new
+    lsi.add('Dog' => ['Dogs are loyal', 'Puppies are cute', 'Canines are friendly'])
+
+    assert_equal 3, lsi.items.size
+    assert_equal ['Dog'], lsi.categories_for('Dogs are loyal')
+    assert_equal ['Dog'], lsi.categories_for('Puppies are cute')
+    assert_equal ['Dog'], lsi.categories_for('Canines are friendly')
+  end
+
+  def test_add_batch_operations
+    lsi = Classifier::LSI.new
+    lsi.add(
+      'Dog' => ['Dogs are loyal', 'Puppies are cute'],
+      'Cat' => ['Cats are independent', 'Kittens are playful']
+    )
+
+    assert_equal 4, lsi.items.size
+    assert_equal ['Dog'], lsi.categories_for('Dogs are loyal')
+    assert_equal ['Cat'], lsi.categories_for('Cats are independent')
+  end
+
+  def test_add_classification_works
+    lsi = Classifier::LSI.new
+    lsi.add(
+      'Dog' => @str2,
+      'Cat' => [@str3, @str4],
+      'Bird' => @str5
+    )
+
+    assert_equal 'Dog', lsi.classify(@str1)
+    assert_equal 'Cat', lsi.classify(@str3)
+    assert_equal 'Bird', lsi.classify(@str5)
+  end
+
+  def test_add_find_related_works
+    lsi = Classifier::LSI.new
+    lsi.add(
+      'Dog' => [@str1, @str2],
+      'Cat' => [@str3, @str4],
+      'Bird' => @str5
+    )
+
+    # The closest match to str1 should be str2 (both about dogs)
+    related = lsi.find_related(@str1, 3)
+
+    assert_equal @str2, related.first, 'Most related to dog text should be other dog text'
+  end
+
+  def test_add_equivalence_to_add_item
+    # Using add
+    lsi1 = Classifier::LSI.new
+    lsi1.add(
+      'Programming' => ['Ruby programming language', 'Java enterprise development'],
+      'Entertainment' => 'Cat pictures are cute'
+    )
+
+    # Using add_item (legacy)
+    lsi2 = Classifier::LSI.new
+    lsi2.add_item 'Ruby programming language', 'Programming'
+    lsi2.add_item 'Java enterprise development', 'Programming'
+    lsi2.add_item 'Cat pictures are cute', 'Entertainment'
+
+    # Both should classify the same
+    test_text = 'Python programming'
+
+    assert_equal lsi1.classify(test_text), lsi2.classify(test_text)
+  end
+
+  def test_add_triggers_auto_rebuild
+    lsi = Classifier::LSI.new auto_rebuild: true
+    lsi.add('Dog' => ['Dogs are great', 'More about dogs'])
+
+    refute_predicate lsi, :needs_rebuild?, 'Auto-rebuild should keep index current'
+  end
+
+  def test_add_respects_auto_rebuild_false
+    lsi = Classifier::LSI.new auto_rebuild: false
+    lsi.add('Dog' => ['Dogs are great', 'More about dogs'])
+
+    assert_predicate lsi, :needs_rebuild?, 'Index should need rebuild when auto_rebuild is false'
+  end
+
   def test_basic_indexing
     lsi = Classifier::LSI.new
     [@str1, @str2, @str3, @str4, @str5].each { |x| lsi << x }