classifier 2.0.0 → 2.1.0

data/ext/classifier/vector.c

@@ -0,0 +1,319 @@
+/*
+ * vector.c
+ * Vector implementation for Classifier native linear algebra
+ */
+
+#include "linalg.h"
+
+const rb_data_type_t cvector_type = {
+    .wrap_struct_name = "Classifier::Linalg::Vector",
+    .function = {
+        .dmark = NULL,
+        .dfree = cvector_free,
+        .dsize = NULL,
+    },
+    .flags = RUBY_TYPED_FREE_IMMEDIATELY
+};
+
+/* Allocate a new CVector */
+CVector *cvector_alloc(size_t size)
+{
+    CVector *v = ALLOC(CVector);
+    v->size = size;
+    v->data = ALLOC_N(double, size);
+    v->is_col = 0;  /* Default to row vector */
+    memset(v->data, 0, size * sizeof(double));
+    return v;
+}
+
+/* Free a CVector */
+void cvector_free(void *ptr)
+{
+    CVector *v = (CVector *)ptr;
+    if (v) {
+        if (v->data) xfree(v->data);
+        xfree(v);
+    }
+}
+
+/* Calculate magnitude (Euclidean norm) */
+double cvector_magnitude(CVector *v)
+{
+    double sum = 0.0;
+    for (size_t i = 0; i < v->size; i++) {
+        sum += v->data[i] * v->data[i];
+    }
+    return sqrt(sum);
+}
+
+/* Return normalized copy */
+CVector *cvector_normalize(CVector *v)
+{
+    CVector *result = cvector_alloc(v->size);
+    result->is_col = v->is_col;
+    double mag = cvector_magnitude(v);
+
+    if (mag <= CLASSIFIER_EPSILON) {
+        /* Return zero vector if magnitude is too small */
+        return result;
+    }
+
+    for (size_t i = 0; i < v->size; i++) {
+        result->data[i] = v->data[i] / mag;
+    }
+    return result;
+}
+
+/* Sum all elements */
+double cvector_sum(CVector *v)
+{
+    double sum = 0.0;
+    for (size_t i = 0; i < v->size; i++) {
+        sum += v->data[i];
+    }
+    return sum;
+}
+
+/* Dot product */
+double cvector_dot(CVector *a, CVector *b)
+{
+    if (a->size != b->size) {
+        rb_raise(rb_eArgError, "Vector sizes must match for dot product");
+    }
+    double sum = 0.0;
+    for (size_t i = 0; i < a->size; i++) {
+        sum += a->data[i] * b->data[i];
+    }
+    return sum;
+}
+
+/* Ruby allocation function */
+static VALUE rb_cvector_alloc(VALUE klass)
+{
+    CVector *v = cvector_alloc(0);
+    return TypedData_Wrap_Struct(klass, &cvector_type, v);
+}
+
+/*
+ * Vector.alloc(size_or_array)
+ * Create a new vector from size (zero-filled) or array of values
+ */
+static VALUE rb_cvector_s_alloc(VALUE klass, VALUE arg)
+{
+    CVector *v;
+    VALUE result;
+
+    if (RB_TYPE_P(arg, T_ARRAY)) {
+        long len = RARRAY_LEN(arg);
+        v = cvector_alloc((size_t)len);
+        for (long i = 0; i < len; i++) {
+            v->data[i] = NUM2DBL(rb_ary_entry(arg, i));
+        }
+    } else {
+        size_t size = NUM2SIZET(arg);
+        v = cvector_alloc(size);
+    }
+
+    result = TypedData_Wrap_Struct(klass, &cvector_type, v);
+    return result;
+}
+
+/* Vector#size */
+static VALUE rb_cvector_size(VALUE self)
+{
+    CVector *v;
+    GET_CVECTOR(self, v);
+    return SIZET2NUM(v->size);
+}
+
+/* Vector#[] */
+static VALUE rb_cvector_aref(VALUE self, VALUE idx)
+{
+    CVector *v;
+    GET_CVECTOR(self, v);
+    long i = NUM2LONG(idx);
+
+    if (i < 0) i += v->size;
+    if (i < 0 || (size_t)i >= v->size) {
+        rb_raise(rb_eIndexError, "index %ld out of bounds", i);
+    }
+
+    return DBL2NUM(v->data[i]);
+}
+
+/* Vector#[]= */
+static VALUE rb_cvector_aset(VALUE self, VALUE idx, VALUE val)
+{
+    CVector *v;
+    GET_CVECTOR(self, v);
+    long i = NUM2LONG(idx);
+
+    if (i < 0) i += v->size;
+    if (i < 0 || (size_t)i >= v->size) {
+        rb_raise(rb_eIndexError, "index %ld out of bounds", i);
+    }
+
+    v->data[i] = NUM2DBL(val);
+    return val;
+}
+
+/* Vector#to_a */
+static VALUE rb_cvector_to_a(VALUE self)
+{
+    CVector *v;
+    GET_CVECTOR(self, v);
+    VALUE ary = rb_ary_new_capa((long)v->size);
+
+    for (size_t i = 0; i < v->size; i++) {
+        rb_ary_push(ary, DBL2NUM(v->data[i]));
+    }
+    return ary;
+}
+
+/* Vector#sum */
+static VALUE rb_cvector_sum(VALUE self)
+{
+    CVector *v;
+    GET_CVECTOR(self, v);
+    return DBL2NUM(cvector_sum(v));
+}
+
+/* Vector#each */
+static VALUE rb_cvector_each(VALUE self)
+{
+    CVector *v;
+    GET_CVECTOR(self, v);
+
+    RETURN_ENUMERATOR(self, 0, 0);
+
+    for (size_t i = 0; i < v->size; i++) {
+        rb_yield(DBL2NUM(v->data[i]));
+    }
+    return self;
+}
+
+/* Vector#collect (map) */
+static VALUE rb_cvector_collect(VALUE self)
+{
+    CVector *v;
+    GET_CVECTOR(self, v);
+
+    RETURN_ENUMERATOR(self, 0, 0);
+
+    CVector *result = cvector_alloc(v->size);
+    result->is_col = v->is_col;
+
+    for (size_t i = 0; i < v->size; i++) {
+        VALUE val = rb_yield(DBL2NUM(v->data[i]));
+        result->data[i] = NUM2DBL(val);
+    }
+
+    return TypedData_Wrap_Struct(cClassifierVector, &cvector_type, result);
+}
+
+/* Vector#normalize */
+static VALUE rb_cvector_normalize(VALUE self)
+{
+    CVector *v;
+    GET_CVECTOR(self, v);
+    CVector *result = cvector_normalize(v);
+    return TypedData_Wrap_Struct(cClassifierVector, &cvector_type, result);
+}
+
+/* Vector#row - return self as row vector */
+static VALUE rb_cvector_row(VALUE self)
+{
+    CVector *v;
+    GET_CVECTOR(self, v);
+
+    CVector *result = cvector_alloc(v->size);
+    memcpy(result->data, v->data, v->size * sizeof(double));
+    result->is_col = 0;
+
+    return TypedData_Wrap_Struct(cClassifierVector, &cvector_type, result);
+}
+
+/* Vector#col - return self as column vector */
+static VALUE rb_cvector_col(VALUE self)
+{
+    CVector *v;
+    GET_CVECTOR(self, v);
+
+    CVector *result = cvector_alloc(v->size);
+    memcpy(result->data, v->data, v->size * sizeof(double));
+    result->is_col = 1;
+
+    return TypedData_Wrap_Struct(cClassifierVector, &cvector_type, result);
+}
+
+/* Vector#* - dot product with vector, or matrix multiplication */
+static VALUE rb_cvector_mul(VALUE self, VALUE other)
+{
+    CVector *v;
+    GET_CVECTOR(self, v);
+
+    if (rb_obj_is_kind_of(other, cClassifierVector)) {
+        CVector *w;
+        GET_CVECTOR(other, w);
+        return DBL2NUM(cvector_dot(v, w));
+    } else if (RB_TYPE_P(other, T_FLOAT) || RB_TYPE_P(other, T_FIXNUM)) {
+        /* Scalar multiplication */
+        double scalar = NUM2DBL(other);
+        CVector *result = cvector_alloc(v->size);
+        result->is_col = v->is_col;
+        for (size_t i = 0; i < v->size; i++) {
+            result->data[i] = v->data[i] * scalar;
+        }
+        return TypedData_Wrap_Struct(cClassifierVector, &cvector_type, result);
+    }
+
+    rb_raise(rb_eTypeError, "Cannot multiply Vector with %s", rb_obj_classname(other));
+    return Qnil;
+}
+
+/* Vector#_dump for Marshal */
+static VALUE rb_cvector_dump(VALUE self, VALUE depth)
+{
+    CVector *v;
+    GET_CVECTOR(self, v);
+    VALUE ary = rb_cvector_to_a(self);
+    rb_ary_push(ary, v->is_col ? Qtrue : Qfalse);
+    return rb_marshal_dump(ary, Qnil);
+}
+
+/* Vector._load for Marshal */
+static VALUE rb_cvector_s_load(VALUE klass, VALUE str)
+{
+    VALUE ary = rb_marshal_load(str);
+    VALUE is_col = rb_ary_pop(ary);
+    VALUE result = rb_cvector_s_alloc(klass, ary);
+    CVector *v;
+    GET_CVECTOR(result, v);
+    v->is_col = RTEST(is_col) ? 1 : 0;
+    return result;
+}
+
+void Init_vector(void)
+{
+    cClassifierVector = rb_define_class_under(mClassifierLinalg, "Vector", rb_cObject);
+
+    rb_define_alloc_func(cClassifierVector, rb_cvector_alloc);
+    rb_define_singleton_method(cClassifierVector, "alloc", rb_cvector_s_alloc, 1);
+    rb_define_singleton_method(cClassifierVector, "_load", rb_cvector_s_load, 1);
+
+    rb_define_method(cClassifierVector, "size", rb_cvector_size, 0);
+    rb_define_method(cClassifierVector, "[]", rb_cvector_aref, 1);
+    rb_define_method(cClassifierVector, "[]=", rb_cvector_aset, 2);
+    rb_define_method(cClassifierVector, "to_a", rb_cvector_to_a, 0);
+    rb_define_method(cClassifierVector, "sum", rb_cvector_sum, 0);
+    rb_define_method(cClassifierVector, "each", rb_cvector_each, 0);
+    rb_define_method(cClassifierVector, "collect", rb_cvector_collect, 0);
+    rb_define_alias(cClassifierVector, "map", "collect");
+    rb_define_method(cClassifierVector, "normalize", rb_cvector_normalize, 0);
+    rb_define_method(cClassifierVector, "row", rb_cvector_row, 0);
+    rb_define_method(cClassifierVector, "col", rb_cvector_col, 0);
+    rb_define_method(cClassifierVector, "*", rb_cvector_mul, 1);
+    rb_define_method(cClassifierVector, "_dump", rb_cvector_dump, 1);
+
+    rb_include_module(cClassifierVector, rb_mEnumerable);
+}

data/lib/classifier/bayes.rb

@@ -4,23 +4,39 @@
 # Copyright:: Copyright (c) 2005 Lucas Carlson
 # License::   LGPL
 
+require 'json'
+require 'mutex_m'
+
 module Classifier
   class Bayes
+    include Mutex_m
+
     # @rbs @categories: Hash[Symbol, Hash[Symbol, Integer]]
     # @rbs @total_words: Integer
     # @rbs @category_counts: Hash[Symbol, Integer]
     # @rbs @category_word_count: Hash[Symbol, Integer]
+    # @rbs @cached_training_count: Float?
+    # @rbs @cached_vocab_size: Integer?
+    # @rbs @dirty: bool
+    # @rbs @storage: Storage::Base?
+
+    attr_accessor :storage
 
     # The class can be created with one or more categories, each of which will be
     # initialized and given a training method. E.g.,
     #      b = Classifier::Bayes.new 'Interesting', 'Uninteresting', 'Spam'
     # @rbs (*String | Symbol) -> void
     def initialize(*categories)
+      super()
       @categories = {}
       categories.each { |category| @categories[category.prepare_category_name] = {} }
       @total_words = 0
       @category_counts = Hash.new(0)
       @category_word_count = Hash.new(0)
+      @cached_training_count = nil
+      @cached_vocab_size = nil
+      @dirty = false
+      @storage = nil
     end
 
     # Provides a general training method for all categories specified in Bayes#new
@@ -33,12 +49,17 @@ module Classifier
     # @rbs (String | Symbol, String) -> void
     def train(category, text)
       category = category.prepare_category_name
-      @category_counts[category] += 1
-      text.word_hash.each do |word, count|
-        @categories[category][word] ||= 0
-        @categories[category][word] += count
-        @total_words += count
-        @category_word_count[category] += count
+      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
 
@@ -53,19 +74,24 @@ module Classifier
     # @rbs (String | Symbol, String) -> void
     def untrain(category, text)
       category = category.prepare_category_name
-      @category_counts[category] -= 1
-      text.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
+      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
-        @category_word_count[category] -= count if @category_word_count[category] >= count
-        @total_words -= count
       end
     end
 
@@ -77,17 +103,19 @@ module Classifier
     # @rbs (String) -> Hash[String, Float]
     def classifications(text)
       words = text.word_hash.keys
-      training_count = @category_counts.values.sum.to_f
-      vocab_size = [@categories.values.flat_map(&:keys).uniq.size, 1].max
+      synchronize do
+        training_count = cached_training_count
+        vocab_size = cached_vocab_size
 
-      @categories.to_h do |category, category_words|
-        smoothed_total = ((@category_word_count[category] || 0) + vocab_size).to_f
+        @categories.to_h do |category, category_words|
+          smoothed_total = ((@category_word_count[category] || 0) + vocab_size).to_f
 
-        # Laplace smoothing: P(word|category) = (count + α) / (total + α * V)
-        word_score = words.sum { |w| Math.log(((category_words[w] || 0) + 1) / smoothed_total) }
-        prior_score = Math.log((@category_counts[category] || 0.1) / training_count)
+          # Laplace smoothing: P(word|category) = (count + α) / (total + α * V)
+          word_score = words.sum { |w| Math.log(((category_words[w] || 0) + 1) / smoothed_total) }
+          prior_score = Math.log((@category_counts[category] || 0.1) / training_count)
 
-        [category.to_s, word_score + prior_score]
+          [category.to_s, word_score + prior_score]
+        end
       end
     end
 
@@ -104,6 +132,119 @@ module Classifier
       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 to the configured storage.
+    # Raises ArgumentError if no storage is configured.
+    #
+    # @rbs () -> void
+    def save
+      raise ArgumentError, 'No storage configured. Use save_to_file(path) or set storage=' unless storage
+
+      storage.write(to_json)
+      @dirty = false
+    end
+
+    # Saves the classifier state to a file (legacy API).
+    #
+    # @rbs (String) -> Integer
+    def save_to_file(path)
+      result = File.write(path, to_json)
+      @dirty = false
+      result
+    end
+
+    # Reloads the classifier from the configured storage.
+    # Raises UnsavedChangesError if there are unsaved changes.
+    # Use reload! to force reload and discard changes.
+    #
+    # @rbs () -> self
+    def reload
+      raise ArgumentError, 'No storage configured' unless storage
+      raise UnsavedChangesError, 'Unsaved changes would be lost. Call save first or use reload!' if @dirty
+
+      data = storage.read
+      raise StorageError, 'No saved state found' unless data
+
+      restore_from_json(data)
+      @dirty = false
+      self
+    end
+
+    # Force reloads the classifier from storage, discarding any unsaved changes.
+    #
+    # @rbs () -> self
+    def reload!
+      raise ArgumentError, 'No storage configured' unless storage
+
+      data = storage.read
+      raise StorageError, 'No saved state found' unless data
+
+      restore_from_json(data)
+      @dirty = false
+      self
+    end
+
+    # Returns true if there are unsaved changes.
+    #
+    # @rbs () -> bool
+    def dirty?
+      @dirty
+    end
+
+    # Loads a classifier from the configured storage.
+    # The storage is set on the returned instance.
+    #
+    # @rbs (storage: Storage::Base) -> Bayes
+    def self.load(storage:)
+      data = storage.read
+      raise StorageError, 'No saved state found' unless data
+
+      instance = from_json(data)
+      instance.storage = storage
+      instance
+    end
+
+    # Loads a classifier from a file (legacy API).
+    #
+    # @rbs (String) -> Bayes
+    def self.load_from_file(path)
+      from_json(File.read(path))
+    end
+
     #
     # Provides training and untraining methods for the categories specified in Bayes#new
     # For example:
@@ -134,7 +275,7 @@ module Classifier
     #
     # @rbs () -> Array[String]
     def categories
-      @categories.keys.collect(&:to_s)
+      synchronize { @categories.keys.collect(&:to_s) }
     end
 
     # Allows you to add categories to the classifier.
@@ -148,11 +289,31 @@ module Classifier
     #
     # @rbs (String | Symbol) -> Hash[Symbol, Integer]
     def add_category(category)
-      @categories[category.prepare_category_name] = {}
+      synchronize do
+        invalidate_caches
+        @dirty = true
+        @categories[category.prepare_category_name] = {}
+      end
     end
 
     alias append_category add_category
 
+    # Custom marshal serialization to exclude mutex state
+    # @rbs () -> Array[untyped]
+    def marshal_dump
+      [@categories, @total_words, @category_counts, @category_word_count, @dirty]
+    end
+
+    # Custom marshal deserialization to recreate mutex
+    # @rbs (Array[untyped]) -> void
+    def marshal_load(data)
+      mu_initialize
+      @categories, @total_words, @category_counts, @category_word_count, @dirty = data
+      @cached_training_count = nil
+      @cached_vocab_size = nil
+      @storage = nil
+    end
+
     # Allows you to remove categories from the classifier.
     # For example:
     #     b.remove_category "Spam"
@@ -164,13 +325,72 @@ module Classifier
     # @rbs (String | Symbol) -> void
     def remove_category(category)
       category = category.prepare_category_name
-      raise StandardError, "No such category: #{category}" unless @categories.key?(category)
+      synchronize do
+        raise StandardError, "No such category: #{category}" unless @categories.key?(category)
+
+        invalidate_caches
+        @dirty = true
+        @total_words -= @category_word_count[category].to_i
+
+        @categories.delete(category)
+        @category_counts.delete(category)
+        @category_word_count.delete(category)
+      end
+    end
+
+    private
+
+    # Restores classifier state from a JSON string (used by reload)
+    # @rbs (String) -> void
+    def restore_from_json(json)
+      data = JSON.parse(json)
+      raise ArgumentError, "Invalid classifier type: #{data['type']}" unless data['type'] == 'bayes'
+
+      synchronize do
+        restore_state(data)
+      end
+    end
+
+    # 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]
+      @cached_training_count = nil
+      @cached_vocab_size = nil
+      @dirty = false
+      @storage = nil
+
+      data['categories'].each do |cat_name, words|
+        @categories[cat_name.to_sym] = words.transform_keys(&:to_sym)
+      end
 
-      @total_words -= @category_word_count[category].to_i
+      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
+
+    # @rbs () -> void
+    def invalidate_caches
+      @cached_training_count = nil
+      @cached_vocab_size = nil
+    end
+
+    # @rbs () -> Float
+    def cached_training_count
+      @cached_training_count ||= @category_counts.values.sum.to_f
+    end
 
-      @categories.delete(category)
-      @category_counts.delete(category)
-      @category_word_count.delete(category)
+    # @rbs () -> Integer
+    def cached_vocab_size
+      @cached_vocab_size ||= [@categories.values.flat_map(&:keys).uniq.size, 1].max
     end
   end
 end

data/lib/classifier/errors.rb

@@ -0,0 +1,16 @@
+# rbs_inline: enabled
+
+# Author::    Lucas Carlson  (mailto:lucas@rufy.com)
+# Copyright:: Copyright (c) 2005 Lucas Carlson
+# License::   LGPL
+
+module Classifier
+  # Base error class for all Classifier errors
+  class Error < StandardError; end
+
+  # Raised when reload would discard unsaved changes
+  class UnsavedChangesError < Error; end
+
+  # Raised when a storage operation fails
+  class StorageError < Error; end
+end