feat: add save/load methods for classifier persistence (#85)

* feat: add save/load methods for classifier persistence

Provides a cleaner API than raw Marshal for persisting trained
classifiers. Users can now save training state and resume later:

  classifier.save('model.json')
  loaded = Classifier::Bayes.load('model.json')
  loaded.train_spam('more data')  # continue training

Both Bayes and LSI classifiers support:
- to_json / from_json for string serialization
- save(path) / load(path) for file operations

LSI serializes only source data (word_hash, categories), not computed
vectors. The index rebuilds on load, making JSON files portable across
GSL/non-GSL environments.

Closes #17

* feat: add as_json method and accept hash in from_json

- Add as_json method that returns a Hash representation
- Modify to_json to use as_json internally
- Modify from_json to accept both String and Hash arguments

This provides more flexibility for serialization workflows.

* fix: resolve RuboCop and Steep type check issues

- Extract restore_state private method to reduce from_json AbcSize
- Change as_json return type to untyped for Steep compatibility
- Use assert_path_exists in tests per Minitest/AssertPathExists
- Add JSON RBS vendor file for type checking
- Regenerate RBS files

Author: cardmagic

lib/classifier/bayes.rb

@@ -4,6 +4,7 @@
 # Copyright:: Copyright (c) 2005 Lucas Carlson
 # License::   LGPL
 
+require 'json'
 require 'mutex_m'
 
 module Classifier
@@ -117,6 +118,55 @@ def classify(text)
       best.first.to_s
     end
 
+    # Returns a hash representation of the classifier state.
+    # This can be converted to JSON or used directly.
+    #
+    # @rbs () -> untyped
+    def as_json(*)
+      {
+        version: 1,
+        type: 'bayes',
+        categories: @categories.transform_keys(&:to_s).transform_values { |v| v.transform_keys(&:to_s) },
+        total_words: @total_words,
+        category_counts: @category_counts.transform_keys(&:to_s),
+        category_word_count: @category_word_count.transform_keys(&:to_s)
+      }
+    end
+
+    # Serializes the classifier state to a JSON string.
+    # This can be saved to a file and later loaded with Bayes.from_json.
+    #
+    # @rbs () -> String
+    def to_json(*)
+      as_json.to_json
+    end
+
+    # Loads a classifier from a JSON string or a Hash created by #to_json or #as_json.
+    #
+    # @rbs (String | Hash[String, untyped]) -> Bayes
+    def self.from_json(json)
+      data = json.is_a?(String) ? JSON.parse(json) : json
+      raise ArgumentError, "Invalid classifier type: #{data['type']}" unless data['type'] == 'bayes'
+
+      instance = allocate
+      instance.send(:restore_state, data)
+      instance
+    end
+
+    # Saves the classifier state to a file.
+    #
+    # @rbs (String) -> Integer
+    def save(path)
+      File.write(path, to_json)
+    end
+
+    # Loads a classifier from a file saved with #save.
+    #
+    # @rbs (String) -> Bayes
+    def self.load(path)
+      from_json(File.read(path))
+    end
+
     #
     # Provides training and untraining methods for the categories specified in Bayes#new
     # For example:
@@ -200,5 +250,29 @@ def remove_category(category)
         @category_word_count.delete(category)
       end
     end
+
+    private
+
+    # Restores classifier state from a hash (used by from_json)
+    # @rbs (Hash[String, untyped]) -> void
+    def restore_state(data)
+      mu_initialize
+      @categories = {} #: Hash[Symbol, Hash[Symbol, Integer]]
+      @total_words = data['total_words']
+      @category_counts = Hash.new(0) #: Hash[Symbol, Integer]
+      @category_word_count = Hash.new(0) #: Hash[Symbol, Integer]
+
+      data['categories'].each do |cat_name, words|
+        @categories[cat_name.to_sym] = words.transform_keys(&:to_sym)
+      end
+
+      data['category_counts'].each do |cat_name, count|
+        @category_counts[cat_name.to_sym] = count
+      end
+
+      data['category_word_count'].each do |cat_name, count|
+        @category_word_count[cat_name.to_sym] = count
+      end
+    end
   end
 end

lib/classifier/lsi.rb

@@ -53,6 +53,7 @@ def matrix_class
   require 'classifier/extensions/vector'
 end
 
+require 'json'
 require 'mutex_m'
 require 'classifier/lsi/word_list'
 require 'classifier/lsi/content_node'
@@ -365,6 +366,75 @@ def marshal_load(data)
       @auto_rebuild, @word_list, @items, @version, @built_at_version = data
     end
 
+    # Returns a hash representation of the LSI index.
+    # Only source data (word_hash, categories) is included, not computed vectors.
+    # This can be converted to JSON or used directly.
+    #
+    # @rbs () -> untyped
+    def as_json(*)
+      items_data = @items.transform_values do |node|
+        {
+          word_hash: node.word_hash.transform_keys(&:to_s),
+          categories: node.categories.map(&:to_s)
+        }
+      end
+
+      {
+        version: 1,
+        type: 'lsi',
+        auto_rebuild: @auto_rebuild,
+        items: items_data
+      }
+    end
+
+    # Serializes the LSI index to a JSON string.
+    # Only source data (word_hash, categories) is serialized, not computed vectors.
+    # On load, the index will be rebuilt automatically.
+    #
+    # @rbs () -> String
+    def to_json(*)
+      as_json.to_json
+    end
+
+    # Loads an LSI index from a JSON string or Hash created by #to_json or #as_json.
+    # The index will be rebuilt after loading.
+    #
+    # @rbs (String | Hash[String, untyped]) -> LSI
+    def self.from_json(json)
+      data = json.is_a?(String) ? JSON.parse(json) : json
+      raise ArgumentError, "Invalid classifier type: #{data['type']}" unless data['type'] == 'lsi'
+
+      # Create instance with auto_rebuild disabled during loading
+      instance = new(auto_rebuild: false)
+
+      # Restore items (categories stay as strings, matching original storage)
+      data['items'].each do |item_key, item_data|
+        word_hash = item_data['word_hash'].transform_keys(&:to_sym)
+        categories = item_data['categories']
+        instance.instance_variable_get(:@items)[item_key] = ContentNode.new(word_hash, *categories)
+        instance.instance_variable_set(:@version, instance.instance_variable_get(:@version) + 1)
+      end
+
+      # Restore auto_rebuild setting and rebuild index
+      instance.auto_rebuild = data['auto_rebuild']
+      instance.build_index
+      instance
+    end
+
+    # Saves the LSI index to a file.
+    #
+    # @rbs (String) -> Integer
+    def save(path)
+      File.write(path, to_json)
+    end
+
+    # Loads an LSI index from a file saved with #save.
+    #
+    # @rbs (String) -> LSI
+    def self.load(path)
+      from_json(File.read(path))
+    end
+
     private
 
     # Assigns LSI vectors using native C extension

sig/vendor/json.rbs

@@ -0,0 +1,4 @@
+module JSON
+  def self.parse: (String source, ?symbolize_names: bool) -> untyped
+  def self.generate: (untyped obj) -> String
+end

test/bayes/bayesian_test.rb

@@ -435,4 +435,112 @@ def test_laplace_smoothing_denominator_includes_vocabulary
     refute_in_delta scores1['Spam'], scores2['Spam'], 0.1,
                     'Vocabulary size should affect word probabilities in denominator'
   end
+
+  # Save/Load tests
+
+  def test_as_json
+    @classifier.train_interesting 'good words here'
+    @classifier.train_uninteresting 'bad words there'
+
+    data = @classifier.as_json
+
+    assert_instance_of Hash, data
+    assert_equal 1, data[:version]
+    assert_equal 'bayes', data[:type]
+    assert_includes data[:categories].keys, 'Interesting'
+    assert_includes data[:categories].keys, 'Uninteresting'
+  end
+
+  def test_to_json
+    @classifier.train_interesting 'good words here'
+    @classifier.train_uninteresting 'bad words there'
+
+    json = @classifier.to_json
+    data = JSON.parse(json)
+
+    assert_equal 1, data['version']
+    assert_equal 'bayes', data['type']
+    assert_includes data['categories'].keys, 'Interesting'
+    assert_includes data['categories'].keys, 'Uninteresting'
+  end
+
+  def test_from_json_with_string
+    @classifier.train_interesting 'good words here'
+    @classifier.train_uninteresting 'bad words there'
+
+    json = @classifier.to_json
+    loaded = Classifier::Bayes.from_json(json)
+
+    assert_equal @classifier.categories.sort, loaded.categories.sort
+    assert_equal @classifier.classify('good words'), loaded.classify('good words')
+    assert_equal @classifier.classify('bad words'), loaded.classify('bad words')
+  end
+
+  def test_from_json_with_hash
+    @classifier.train_interesting 'good words here'
+    @classifier.train_uninteresting 'bad words there'
+
+    # Use as_json to get a hash, then convert keys to strings (as would happen from JSON.parse)
+    hash = JSON.parse(@classifier.to_json)
+    loaded = Classifier::Bayes.from_json(hash)
+
+    assert_equal @classifier.categories.sort, loaded.categories.sort
+    assert_equal @classifier.classify('good words'), loaded.classify('good words')
+    assert_equal @classifier.classify('bad words'), loaded.classify('bad words')
+  end
+
+  def test_from_json_invalid_type
+    invalid_json = { version: 1, type: 'invalid' }.to_json
+
+    assert_raises(ArgumentError) { Classifier::Bayes.from_json(invalid_json) }
+  end
+
+  def test_save_and_load
+    @classifier.train_interesting 'good words here'
+    @classifier.train_uninteresting 'bad words there'
+
+    Dir.mktmpdir do |dir|
+      path = File.join(dir, 'classifier.json')
+      @classifier.save(path)
+
+      assert_path_exists path, 'Save should create file'
+
+      loaded = Classifier::Bayes.load(path)
+
+      assert_equal @classifier.categories.sort, loaded.categories.sort
+      assert_equal @classifier.classify('good'), loaded.classify('good')
+    end
+  end
+
+  def test_save_load_preserves_training_state
+    @classifier.train_interesting 'apple banana cherry'
+    @classifier.train_uninteresting 'dog elephant fox'
+
+    Dir.mktmpdir do |dir|
+      path = File.join(dir, 'classifier.json')
+      @classifier.save(path)
+      loaded = Classifier::Bayes.load(path)
+
+      # Verify classifications match
+      assert_equal @classifier.classifications('apple'), loaded.classifications('apple')
+      assert_equal @classifier.classifications('dog'), loaded.classifications('dog')
+    end
+  end
+
+  def test_loaded_classifier_can_continue_training
+    @classifier.train_interesting 'initial training'
+
+    Dir.mktmpdir do |dir|
+      path = File.join(dir, 'classifier.json')
+      @classifier.save(path)
+      loaded = Classifier::Bayes.load(path)
+
+      # Continue training on loaded classifier
+      loaded.train_interesting 'more interesting content'
+      loaded.train_uninteresting 'boring content here'
+
+      assert_equal 'Interesting', loaded.classify('interesting content')
+      assert_equal 'Uninteresting', loaded.classify('boring content')
+    end
+  end
 end