ts-classify 0.1.0 → 0.2.0

package/LICENSE.md

@@ -0,0 +1,20 @@
+Copyright (c) 2026 Bart Riepe
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,148 +1,95 @@
-# SVM
+# ts-classify
 
-A fast Support Vector Machine implementation in Rust, targeting both native and WebAssembly.
+Fast text classification via SVM, compiled to WebAssembly.
 
 ## Features
 
-- **Binary SVM** with two solvers:
-  - **Coordinate Descent** (default) - O(N) per pass, fast for large datasets
-  - **SMO** - O(N²), useful for kernel SVMs (future)
-- **Multiclass classification**:
-  - **One-vs-Rest (OvR)** - K classifiers for K classes, fast prediction
-  - **One-vs-One (OvO)** - K(K-1)/2 classifiers, often more accurate
 - **Sparse vectors** - efficient for high-dimensional data (text, trigrams)
-- **Parallel training** via rayon (native only)
-- **Binary serialization** via bincode
-- **WebAssembly support** with JS-friendly API
+- **Binary serialization** - train once, load instantly
+- **Written in Rust**, compiled to WASM for near-native performance in the browser
 
 ## Installation
 
-```toml
-[dependencies]
-svm = { path = "." }
+```bash
+npm install ts-classify
 ```
 
-## Usage
-
-### Binary SVM
-
-```rust
-use svm::{SVM, SparseVec};
+## Classifiers
 
-// Sparse format: Vec<(index, value)>
-let samples: Vec<SparseVec> = vec![
-    vec![(0, -2.0), (1, 0.0)],
-    vec![(0, -1.0), (1, 1.0)],
-    vec![(0, 1.0), (1, 0.0)],
-    vec![(0, 2.0), (1, 1.0)],
-];
-let labels = vec![-1.0, -1.0, 1.0, 1.0];
+All classifiers use the same sparse data format: flat `Float64Array` of `[index, value, index, value, ...]` pairs.
 
-let mut svm = SVM::new();
-svm.train_sparse(&samples, &labels);
+```javascript
+import init, { JsOneVsRestSVM, JsMulticlassSVM, JsNearestCentroid, JsSVM } from 'ts-classify';
 
-assert_eq!(svm.predict_sparse(&[(0, -3.0)]), -1.0);
-assert_eq!(svm.predict_sparse(&[(0, 3.0)]), 1.0);
+await init();
 ```
 
-### Multiclass (One-vs-Rest)
-
-```rust
-use svm::{OneVsRestSVM, SparseVec};
+### JsOneVsRestSVM
 
-let samples: Vec<SparseVec> = vec![
-    vec![(0, -2.0), (1, -2.0)],  // class 0
-    vec![(0, 2.0), (1, -2.0)],   // class 1
-    vec![(0, 0.0), (1, 2.0)],    // class 2
-    // ... more samples
-];
-let labels = vec![0, 1, 2, /* ... */];
+Multiclass SVM using one-vs-rest strategy. Trains K classifiers for K classes. Best for large numbers of classes.
 
-let mut svm = OneVsRestSVM::new();
-svm.train_sparse(&samples, &labels);
-
-let predicted_class = svm.predict_sparse(&[(0, 0.0), (1, 3.0)]);
+```javascript
+const svm = new JsOneVsRestSVM();
+svm.train(samplesFlat, sampleLengths, labels);
+const prediction = svm.predict(sampleFlat);
+const margins = svm.margins(sampleFlat); // [class0, margin0, class1, margin1, ...]
 ```
 
-### Custom Configuration
+### JsMulticlassSVM
 
-```rust
-use svm::{SVM, TrainConfig, Solver};
+Multiclass SVM using one-vs-one strategy. Trains K(K-1)/2 classifiers, predicts by voting. Often more accurate for smaller numbers of classes.
 
-let config = TrainConfig::coordinate_descent()
-    .with_c(0.5)           // regularization (default: 1.0)
-    .with_max_iter(500)    // max iterations (default: 1000)
-    .with_tol(0.001);      // tolerance (default: 0.01)
-
-let mut svm = SVM::new();
-svm.train_sparse_with_config(&samples, &labels, &config);
-
-// Or use SMO solver
-let config = TrainConfig::smo()
-    .with_c(1.0)
-    .with_max_iter(10000);
+```javascript
+const svm = new JsMulticlassSVM();
+svm.train(samplesFlat, sampleLengths, labels);
+const prediction = svm.predict(sampleFlat);
 ```
 
-### Serialization
+### JsNearestCentroid
 
-```rust
-// Save
-let bytes = svm.to_bytes()?;
-std::fs::write("model.bin", &bytes)?;
+Computes the centroid of each class and predicts by cosine similarity. Very fast to train, no hyperparameters.
 
-// Load
-let bytes = std::fs::read("model.bin")?;
-let svm = SVM::from_bytes(&bytes)?;
+```javascript
+const nc = new JsNearestCentroid();
+nc.train(samplesFlat, sampleLengths, labels);
+const prediction = nc.predict(sampleFlat);
+const similarities = nc.margins(sampleFlat); // [class0, sim0, class1, sim1, ...]
 ```
 
-## WebAssembly
-
-Build for WASM (without parallel feature):
+### JsSVM
 
-```bash
-cargo build --release --target wasm32-unknown-unknown --no-default-features
-```
+Binary SVM for two-class problems. Labels are -1.0 or 1.0.
 
-Or use wasm-pack:
-
-```bash
-wasm-pack build --target web --no-default-features
+```javascript
+const svm = new JsSVM();
+svm.train(samplesFlat, sampleLengths, labels); // labels: Float64Array of -1.0/1.0
+const prediction = svm.predict(sampleFlat);     // returns -1.0 or 1.0
+const margin = svm.margin(sampleFlat);           // raw decision value
 ```
 
-### JavaScript API
+### Data format
 
 ```javascript
-import { JsOneVsRestSVM } from 'svm';
-
-const svm = new JsOneVsRestSVM();
-
 // Flat sparse format: [idx, val, idx, val, ...]
-const sampleFlat = new Float64Array([0, -2.0, 1, 0.0]);  // single sample
 const samplesFlat = new Float64Array([
     0, -2.0, 1, 0.0,  // sample 0: 2 pairs
     0, 1.0, 1, 1.0,   // sample 1: 2 pairs
 ]);
 const sampleLengths = new Uint32Array([2, 2]);  // pairs per sample
-const labels = new Int32Array([0, 1]);
+const labels = new Int32Array([0, 1]);           // class IDs (or Float64Array for JsSVM)
+```
 
-svm.train(samplesFlat, sampleLengths, labels);
+### Serialization
 
-const prediction = svm.predict(sampleFlat);
+All classifiers support binary serialization:
 
-// Serialize/deserialize
+```javascript
 const bytes = svm.to_bytes();
 const loaded = JsOneVsRestSVM.from_bytes(bytes);
 ```
 
 ## Performance
 
-Coordinate descent vs SMO on 50-class OvR:
-
-| Solver | Train Time |
-|--------|------------|
-| Coordinate Descent | 6ms |
-| SMO | 29s |
-
 Scaling (coordinate descent, OvR):
 
 | Classes | Classifiers | Train | Predict |
@@ -152,16 +99,18 @@ Scaling (coordinate descent, OvR):
 | 100 | 100 | 1.4ms | 1.6µs |
 | 5000 | 5000 | ~50-100ms | ~80µs |
 
-## Feature Flags
+## Building from source
 
-- `parallel` (default) - Enable parallel training via rayon. Disable for WASM.
+Requires [Rust](https://rustup.rs/) and [wasm-pack](https://rustwasm.github.io/wasm-pack/installer/).
 
-```toml
-# Native with parallel
-svm = { path = "." }
+```bash
+wasm-pack build --target web --no-default-features
+```
 
-# WASM (no parallel)
-svm = { path = ".", default-features = false }
+Run tests (native):
+
+```bash
+cargo test --release
 ```
 
 ## License

package/package.json

@@ -2,7 +2,7 @@
   "name": "ts-classify",
   "type": "module",
   "description": "Fast text classification with SVM and Nearest Centroid (WebAssembly)",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/ts_classify.d.ts

@@ -1,6 +1,44 @@
 /* tslint:disable */
 /* eslint-disable */
 
+/**
+ * JS-friendly wrapper for One-vs-One multiclass SVM.
+ */
+export class JsMulticlassSVM {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Deserialize from bytes.
+     */
+    static from_bytes(bytes: Uint8Array): JsMulticlassSVM;
+    constructor();
+    /**
+     * Number of classes.
+     */
+    num_classes(): number;
+    /**
+     * Number of binary classifiers.
+     */
+    num_classifiers(): number;
+    /**
+     * Predict class for a single sparse sample.
+     */
+    predict(sample_flat: Float64Array): number;
+    /**
+     * Serialize to bytes.
+     */
+    to_bytes(): Uint8Array;
+    /**
+     * Train on sparse data.
+     * labels: integer class IDs (0, 1, 2, ...)
+     */
+    train(samples_flat: Float64Array, sample_lengths: Uint32Array, labels: Int32Array): void;
+    /**
+     * Train with custom parameters.
+     */
+    train_with_config(samples_flat: Float64Array, sample_lengths: Uint32Array, labels: Int32Array, use_smo: boolean, c: number, max_iter: number, tol: number): void;
+}
+
 /**
  * JS-friendly wrapper for Nearest Centroid classifier.
  */
@@ -119,9 +157,18 @@ export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembl
 
 export interface InitOutput {
     readonly memory: WebAssembly.Memory;
+    readonly __wbg_jsmulticlasssvm_free: (a: number, b: number) => void;
     readonly __wbg_jsnearestcentroid_free: (a: number, b: number) => void;
     readonly __wbg_jsonevsrestsvm_free: (a: number, b: number) => void;
     readonly __wbg_jssvm_free: (a: number, b: number) => void;
+    readonly jsmulticlasssvm_from_bytes: (a: number, b: number) => [number, number, number];
+    readonly jsmulticlasssvm_new: () => number;
+    readonly jsmulticlasssvm_num_classes: (a: number) => number;
+    readonly jsmulticlasssvm_num_classifiers: (a: number) => number;
+    readonly jsmulticlasssvm_predict: (a: number, b: number, c: number) => number;
+    readonly jsmulticlasssvm_to_bytes: (a: number) => [number, number, number, number];
+    readonly jsmulticlasssvm_train: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
+    readonly jsmulticlasssvm_train_with_config: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number) => void;
     readonly jsnearestcentroid_from_bytes: (a: number, b: number) => [number, number, number];
     readonly jsnearestcentroid_margins: (a: number, b: number, c: number) => [number, number];
     readonly jsnearestcentroid_new: () => number;

package/ts_classify.js

@@ -1,5 +1,124 @@
 /* @ts-self-types="./ts_classify.d.ts" */
 
+/**
+ * JS-friendly wrapper for One-vs-One multiclass SVM.
+ */
+export class JsMulticlassSVM {
+    static __wrap(ptr) {
+        ptr = ptr >>> 0;
+        const obj = Object.create(JsMulticlassSVM.prototype);
+        obj.__wbg_ptr = ptr;
+        JsMulticlassSVMFinalization.register(obj, obj.__wbg_ptr, obj);
+        return obj;
+    }
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        JsMulticlassSVMFinalization.unregister(this);
+        return ptr;
+    }
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_jsmulticlasssvm_free(ptr, 0);
+    }
+    /**
+     * Deserialize from bytes.
+     * @param {Uint8Array} bytes
+     * @returns {JsMulticlassSVM}
+     */
+    static from_bytes(bytes) {
+        const ptr0 = passArray8ToWasm0(bytes, wasm.__wbindgen_malloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.jsmulticlasssvm_from_bytes(ptr0, len0);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return JsMulticlassSVM.__wrap(ret[0]);
+    }
+    constructor() {
+        const ret = wasm.jsmulticlasssvm_new();
+        this.__wbg_ptr = ret >>> 0;
+        JsMulticlassSVMFinalization.register(this, this.__wbg_ptr, this);
+        return this;
+    }
+    /**
+     * Number of classes.
+     * @returns {number}
+     */
+    num_classes() {
+        const ret = wasm.jsmulticlasssvm_num_classes(this.__wbg_ptr);
+        return ret >>> 0;
+    }
+    /**
+     * Number of binary classifiers.
+     * @returns {number}
+     */
+    num_classifiers() {
+        const ret = wasm.jsmulticlasssvm_num_classifiers(this.__wbg_ptr);
+        return ret >>> 0;
+    }
+    /**
+     * Predict class for a single sparse sample.
+     * @param {Float64Array} sample_flat
+     * @returns {number}
+     */
+    predict(sample_flat) {
+        const ptr0 = passArrayF64ToWasm0(sample_flat, wasm.__wbindgen_malloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.jsmulticlasssvm_predict(this.__wbg_ptr, ptr0, len0);
+        return ret;
+    }
+    /**
+     * Serialize to bytes.
+     * @returns {Uint8Array}
+     */
+    to_bytes() {
+        const ret = wasm.jsmulticlasssvm_to_bytes(this.__wbg_ptr);
+        if (ret[3]) {
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        var v1 = getArrayU8FromWasm0(ret[0], ret[1]).slice();
+        wasm.__wbindgen_free(ret[0], ret[1] * 1, 1);
+        return v1;
+    }
+    /**
+     * Train on sparse data.
+     * labels: integer class IDs (0, 1, 2, ...)
+     * @param {Float64Array} samples_flat
+     * @param {Uint32Array} sample_lengths
+     * @param {Int32Array} labels
+     */
+    train(samples_flat, sample_lengths, labels) {
+        const ptr0 = passArrayF64ToWasm0(samples_flat, wasm.__wbindgen_malloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passArray32ToWasm0(sample_lengths, wasm.__wbindgen_malloc);
+        const len1 = WASM_VECTOR_LEN;
+        const ptr2 = passArray32ToWasm0(labels, wasm.__wbindgen_malloc);
+        const len2 = WASM_VECTOR_LEN;
+        wasm.jsmulticlasssvm_train(this.__wbg_ptr, ptr0, len0, ptr1, len1, ptr2, len2);
+    }
+    /**
+     * Train with custom parameters.
+     * @param {Float64Array} samples_flat
+     * @param {Uint32Array} sample_lengths
+     * @param {Int32Array} labels
+     * @param {boolean} use_smo
+     * @param {number} c
+     * @param {number} max_iter
+     * @param {number} tol
+     */
+    train_with_config(samples_flat, sample_lengths, labels, use_smo, c, max_iter, tol) {
+        const ptr0 = passArrayF64ToWasm0(samples_flat, wasm.__wbindgen_malloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passArray32ToWasm0(sample_lengths, wasm.__wbindgen_malloc);
+        const len1 = WASM_VECTOR_LEN;
+        const ptr2 = passArray32ToWasm0(labels, wasm.__wbindgen_malloc);
+        const len2 = WASM_VECTOR_LEN;
+        wasm.jsmulticlasssvm_train_with_config(this.__wbg_ptr, ptr0, len0, ptr1, len1, ptr2, len2, use_smo, c, max_iter, tol);
+    }
+}
+if (Symbol.dispose) JsMulticlassSVM.prototype[Symbol.dispose] = JsMulticlassSVM.prototype.free;
+
 /**
  * JS-friendly wrapper for Nearest Centroid classifier.
  */
@@ -377,6 +496,9 @@ function __wbg_get_imports() {
     };
 }
 
+const JsMulticlassSVMFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_jsmulticlasssvm_free(ptr >>> 0, 1));
 const JsNearestCentroidFinalization = (typeof FinalizationRegistry === 'undefined')
     ? { register: () => {}, unregister: () => {} }
     : new FinalizationRegistry(ptr => wasm.__wbg_jsnearestcentroid_free(ptr >>> 0, 1));