From 32d4a127c1c3780ed848874180a25df746e9f727 Mon Sep 17 00:00:00 2001 From: Reuven Cohen Date: Wed, 11 Nov 2026 17:40:44 +0000 Subject: [PATCH] feat: integrate shared e-means clustering submodules --- Cargo.lock | 9 ++ Cargo.toml | 3 + docs/adr/ADR-013-e-means-clustering.md | 55 +++++++++++ integrations/ruv-fann/package.json | 10 +- .../ruv-fann/src/clustering-cloudflare.d.ts | 2 + .../ruv-fann/src/clustering-cloudflare.mjs | 2 + integrations/ruv-fann/src/clustering-ivf.d.ts | 2 + integrations/ruv-fann/src/clustering-ivf.mjs | 2 + .../ruv-fann/src/clustering-metaharness.d.ts | 2 + .../ruv-fann/src/clustering-metaharness.mjs | 2 + .../ruv-fann/src/clustering-quantization.d.ts | 2 + .../ruv-fann/src/clustering-quantization.mjs | 2 + integrations/ruv-fann/src/clustering.d.ts | 2 + integrations/ruv-fann/src/clustering.mjs | 2 + .../ruv-fann/test/clustering-types.test.mts | 19 ++++ .../ruv-fann/test/clustering.test.mjs | 42 ++++++++ integrations/ruv-fann/tsconfig.json | 2 +- packages/core/package.json | 23 ++++- .../capabilities/clustering-cloudflare.d.ts | 2 + .../src/capabilities/clustering-cloudflare.js | 2 + .../core/src/capabilities/clustering-ivf.d.ts | 2 + .../core/src/capabilities/clustering-ivf.js | 2 + .../capabilities/clustering-metaharness.d.ts | 2 + .../capabilities/clustering-metaharness.js | 2 + .../capabilities/clustering-quantization.d.ts | 2 + .../capabilities/clustering-quantization.js | 2 + .../core/src/capabilities/clustering.d.ts | 2 + packages/core/src/capabilities/clustering.js | 2 + .../core/test/clustering-submodules.test.mjs | 46 +++++++++ .../core/test/clustering-submodules.types.mts | 20 ++++ packages/core/test/clustering.test.mjs | 27 ++++++ src/clustering.rs | 50 ++++++++++ src/lib.rs | 2 + tests/clustering_tests.rs | 96 +++++++++++++++++++ 34 files changed, 440 insertions(+), 4 deletions(-) create mode 100644 docs/adr/ADR-013-e-means-clustering.md create mode 100644 integrations/ruv-fann/src/clustering-cloudflare.d.ts create mode 100644 integrations/ruv-fann/src/clustering-cloudflare.mjs create mode 100644 integrations/ruv-fann/src/clustering-ivf.d.ts create mode 100644 integrations/ruv-fann/src/clustering-ivf.mjs create mode 100644 integrations/ruv-fann/src/clustering-metaharness.d.ts create mode 100644 integrations/ruv-fann/src/clustering-metaharness.mjs create mode 100644 integrations/ruv-fann/src/clustering-quantization.d.ts create mode 100644 integrations/ruv-fann/src/clustering-quantization.mjs create mode 100644 integrations/ruv-fann/src/clustering.d.ts create mode 100644 integrations/ruv-fann/src/clustering.mjs create mode 100644 integrations/ruv-fann/test/clustering-types.test.mts create mode 100644 integrations/ruv-fann/test/clustering.test.mjs create mode 100644 packages/core/src/capabilities/clustering-cloudflare.d.ts create mode 100644 packages/core/src/capabilities/clustering-cloudflare.js create mode 100644 packages/core/src/capabilities/clustering-ivf.d.ts create mode 100644 packages/core/src/capabilities/clustering-ivf.js create mode 100644 packages/core/src/capabilities/clustering-metaharness.d.ts create mode 100644 packages/core/src/capabilities/clustering-metaharness.js create mode 100644 packages/core/src/capabilities/clustering-quantization.d.ts create mode 100644 packages/core/src/capabilities/clustering-quantization.js create mode 100644 packages/core/src/capabilities/clustering.d.ts create mode 100644 packages/core/src/capabilities/clustering.js create mode 100644 packages/core/test/clustering-submodules.test.mjs create mode 100644 packages/core/test/clustering-submodules.types.mts create mode 100644 packages/core/test/clustering.test.mjs create mode 100644 src/clustering.rs create mode 100644 tests/clustering_tests.rs diff --git a/Cargo.lock b/Cargo.lock index b6931024..b68c878f 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1515,6 +1515,7 @@ dependencies = [ "rand 0.8.6", "rand_distr", "rayon", + "ruvector-e-means", "serde", "serde_json", "thiserror", @@ -1526,6 +1527,14 @@ dependencies = [ "wgpu", ] +[[package]] +name = "ruvector-e-means" +version = "0.1.0" +dependencies = [ + "rand_chacha", + "rand_core 0.6.4", +] + [[package]] name = "ryu" version = "1.0.20" diff --git a/Cargo.toml b/Cargo.toml index 454b9ef4..d6ecf49d 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -38,6 +38,8 @@ serde = { version = "1.0", features = ["derive"], optional = true } serde_json = { version = "1.0", optional = true, features = ["float_roundtrip"] } thiserror = "1.0" num-traits = "0.2" +# Optional unsupervised input/codebook clustering, shared with RuVector. +ruvector-e-means = { version = "0.1.0", optional = true } # Parallel processing rayon = { version = "1.8", optional = true } @@ -102,6 +104,7 @@ simd = [] binary = ["dep:bincode"] compression = ["dep:flate2"] io = ["binary", "compression", "serde"] +clustering = ["dep:ruvector-e-means", "std"] # no_std support no_std = [] diff --git a/docs/adr/ADR-013-e-means-clustering.md b/docs/adr/ADR-013-e-means-clustering.md new file mode 100644 index 00000000..e23f83cf --- /dev/null +++ b/docs/adr/ADR-013-e-means-clustering.md @@ -0,0 +1,55 @@ +# ADR-013: Shared e-means input clustering with RuVector + +Status: Implemented source architecture; release requires publishing the shared dependencies first. +Date: 2026-11-11. +Reference: Bessa et al., [e-means: outperforming k-means (in one-tenth the epochs), arXiv:2611.09501v1](https://arxiv.org/abs/2611.09501v1). + +## Context + +ruv-FANN applications need to group training inputs and train representative codebooks. RuVector needs the same operation for vector quantization. Maintaining separate clustering algorithms would allow numerical behavior, validation and defaults to diverge between the two projects and their JavaScript interfaces. + +The paper describes mini-batch centroid updates using exponentially weighted counts and sums, cosine scheduling, donor splitting to revive inactive clusters, and last-epoch mean finalization. Its batch-size and peak-step scaling laws provide defaults without application-specific tuning. The published performance measurements use different hardware and datasets from this implementation; they do not establish local CPU or WASM speedups. + +## Decision + +Use the independent `ruvector-e-means` Rust crate, version `0.1.0`, owned by the RuVector repository. Enable it through the optional `clustering` Cargo feature. Export its `fit`, `Config`, `Finalization`, `Model` and `Error` interfaces from `ruv_fann::clustering`. + +Add `TrainingData::cluster_inputs(&Config)` as the bridge from nested training input rows to the shared flat row-major API. Validate that rows are nonempty and rectangular before flattening. Delegate configuration, finite-coordinate and clustering validation to the shared crate. Return a distinct adapter error for invalid input shapes. Outputs do not participate in this unsupervised operation; the method borrows data without changing inputs, outputs or network weights. + +Add the explicit `ruv-fann/clustering` npm subpath, backed by an exact `@ruvector/e-means@0.1.0` dependency. Its JavaScript and TypeScript modules re-export the shared package directly, including asynchronous `init` and synchronous `fit`/`predict` after initialization. The npm package runs the same Rust algorithm compiled to WASM. The root neural inference and training entrypoint does not eagerly initialize clustering. + +The initial scope includes exact squared-Euclidean assignment, seeded reproducibility, automatic scaling-law parameters, EMA updates, cosine annealing, dead-cluster revival and last-epoch mean finalization. The alternative `ema` finalization exposes the terminal EMA centroids. Slow-EMA finalization, approximate assignment and GPU kernels remain outside this first implementation. + +## Alternatives + +Embedding a second Rust implementation in ruv-FANN would duplicate maintenance and numerical testing. A JavaScript rewrite would also introduce a second algorithm and different random-number behavior. Both lose the shared implementation boundary. + +Replacing backpropagation, RProp or AdamW with clustering would change the supervised learning contract. The new feature instead supports input analysis and codebook training through a separate API. Applications choose explicitly how to use the resulting assignments and centroids. + +## Dependencies and release order + +Cargo uses a version-only dependency and npm uses an exact registry version. There are no committed paths to a sibling checkout or unpublished Git revision. Publish `ruvector-e-means@0.1.0` and `@ruvector/e-means@0.1.0`, verify fresh registry installs, then release the consuming ruv-FANN artifacts. Until then, independent dependency resolution requires a local override; passing local checks does not prove registry availability. + +For development with sibling checkouts: + +```sh +cargo test --features clustering --test clustering_tests \ + --config 'patch.crates-io.ruvector-e-means.path="../ruvector/crates/ruvector-e-means"' +``` + +For npm validation, build and pack the shared package, install that exact archive in an isolated consumer, and import the packed ruv-FANN `clustering` subpath. An archive override is for qualification only; published dependency metadata retains the registry version. + +Rollback removes the optional feature usage and npm subpath usage. Existing supervised inference and training callers have no API migration. + +## Acceptance and evidence + +| Requirement | Executable evidence | +| --- | --- | +| Use the shared Rust dependency | `tests/clustering_tests.rs` compares adapter and direct shared-crate centroids/assignments | +| Provide useful input clustering | Separated-cluster prediction and one-cluster mean numerical oracles | +| Preserve supervised inputs and targets | Adapter test compares borrowed data before and after clustering | +| Reject malformed boundaries | Empty/ragged rows and non-finite-coordinate regressions | +| Expose the same dependency to npm | `packages/core/test/clustering.test.mjs` imports `ruv-fann/clustering` and executes WASM training/prediction | +| Remain reproducible | Same seed/data/config yields identical centroids | + +Focused validation must run against actual crate and WASM bytes. The shared crate owns algorithm-level tests and benchmarks; ruv-FANN owns the adapter and package-boundary checks. Broader Cargo and npm regressions remain required when preparing a release. No accuracy guarantee for arbitrary datasets or reproduction of the paper's GPU throughput is implied. diff --git a/integrations/ruv-fann/package.json b/integrations/ruv-fann/package.json index ad43166d..f24da76c 100644 --- a/integrations/ruv-fann/package.json +++ b/integrations/ruv-fann/package.json @@ -9,7 +9,12 @@ ".": { "types": "./src/index.d.ts", "import": "./src/index.mjs" }, "./ruvector": { "types": "./src/ruvector.d.ts", "import": "./src/ruvector.mjs" }, "./metaharness": { "types": "./src/metaharness.d.ts", "import": "./src/metaharness.mjs" }, - "./node": { "types": "./src/node.d.ts", "import": "./src/node.mjs" } + "./node": { "types": "./src/node.d.ts", "import": "./src/node.mjs" }, + "./clustering": { "types": "./src/clustering.d.ts", "import": "./src/clustering.mjs" }, + "./clustering/quantization": { "types": "./src/clustering-quantization.d.ts", "import": "./src/clustering-quantization.mjs" }, + "./clustering/ivf": { "types": "./src/clustering-ivf.d.ts", "import": "./src/clustering-ivf.mjs" }, + "./clustering/metaharness": { "types": "./src/clustering-metaharness.d.ts", "import": "./src/clustering-metaharness.mjs" }, + "./clustering/cloudflare": { "types": "./src/clustering-cloudflare.d.ts", "import": "./src/clustering-cloudflare.mjs" } }, "files": ["src/", "README.md", "LICENSE-MIT", "LICENSE-APACHE"], "engines": { "node": ">=22.13.0" }, @@ -25,7 +30,8 @@ }, "dependencies": { "@ruvector/wasm": "0.2.1", - "@metaharness/darwin": "0.13.0" + "@metaharness/darwin": "0.13.0", + "@ruvector/e-means": "0.1.0" }, "devDependencies": { "typescript": "5.9.3" } } diff --git a/integrations/ruv-fann/src/clustering-cloudflare.d.ts b/integrations/ruv-fann/src/clustering-cloudflare.d.ts new file mode 100644 index 00000000..75f5993d --- /dev/null +++ b/integrations/ruv-fann/src/clustering-cloudflare.d.ts @@ -0,0 +1,2 @@ +/** Explicit shared clustering capability; initialize the numerical runtime explicitly. */ +export * from '@ruvector/e-means/cloudflare'; diff --git a/integrations/ruv-fann/src/clustering-cloudflare.mjs b/integrations/ruv-fann/src/clustering-cloudflare.mjs new file mode 100644 index 00000000..75f5993d --- /dev/null +++ b/integrations/ruv-fann/src/clustering-cloudflare.mjs @@ -0,0 +1,2 @@ +/** Explicit shared clustering capability; initialize the numerical runtime explicitly. */ +export * from '@ruvector/e-means/cloudflare'; diff --git a/integrations/ruv-fann/src/clustering-ivf.d.ts b/integrations/ruv-fann/src/clustering-ivf.d.ts new file mode 100644 index 00000000..3c7cd409 --- /dev/null +++ b/integrations/ruv-fann/src/clustering-ivf.d.ts @@ -0,0 +1,2 @@ +/** Explicit shared clustering capability; initialize the numerical runtime explicitly. */ +export * from '@ruvector/e-means/ivf'; diff --git a/integrations/ruv-fann/src/clustering-ivf.mjs b/integrations/ruv-fann/src/clustering-ivf.mjs new file mode 100644 index 00000000..3c7cd409 --- /dev/null +++ b/integrations/ruv-fann/src/clustering-ivf.mjs @@ -0,0 +1,2 @@ +/** Explicit shared clustering capability; initialize the numerical runtime explicitly. */ +export * from '@ruvector/e-means/ivf'; diff --git a/integrations/ruv-fann/src/clustering-metaharness.d.ts b/integrations/ruv-fann/src/clustering-metaharness.d.ts new file mode 100644 index 00000000..780155f6 --- /dev/null +++ b/integrations/ruv-fann/src/clustering-metaharness.d.ts @@ -0,0 +1,2 @@ +/** Explicit shared clustering capability; initialize the numerical runtime explicitly. */ +export * from '@ruvector/e-means/metaharness'; diff --git a/integrations/ruv-fann/src/clustering-metaharness.mjs b/integrations/ruv-fann/src/clustering-metaharness.mjs new file mode 100644 index 00000000..780155f6 --- /dev/null +++ b/integrations/ruv-fann/src/clustering-metaharness.mjs @@ -0,0 +1,2 @@ +/** Explicit shared clustering capability; initialize the numerical runtime explicitly. */ +export * from '@ruvector/e-means/metaharness'; diff --git a/integrations/ruv-fann/src/clustering-quantization.d.ts b/integrations/ruv-fann/src/clustering-quantization.d.ts new file mode 100644 index 00000000..fc1b7cd2 --- /dev/null +++ b/integrations/ruv-fann/src/clustering-quantization.d.ts @@ -0,0 +1,2 @@ +/** Explicit shared clustering capability; initialize the numerical runtime explicitly. */ +export * from '@ruvector/e-means/quantization'; diff --git a/integrations/ruv-fann/src/clustering-quantization.mjs b/integrations/ruv-fann/src/clustering-quantization.mjs new file mode 100644 index 00000000..fc1b7cd2 --- /dev/null +++ b/integrations/ruv-fann/src/clustering-quantization.mjs @@ -0,0 +1,2 @@ +/** Explicit shared clustering capability; initialize the numerical runtime explicitly. */ +export * from '@ruvector/e-means/quantization'; diff --git a/integrations/ruv-fann/src/clustering.d.ts b/integrations/ruv-fann/src/clustering.d.ts new file mode 100644 index 00000000..6fa400ea --- /dev/null +++ b/integrations/ruv-fann/src/clustering.d.ts @@ -0,0 +1,2 @@ +/** Explicit shared clustering capability; initialize the numerical runtime explicitly. */ +export * from '@ruvector/e-means'; diff --git a/integrations/ruv-fann/src/clustering.mjs b/integrations/ruv-fann/src/clustering.mjs new file mode 100644 index 00000000..6fa400ea --- /dev/null +++ b/integrations/ruv-fann/src/clustering.mjs @@ -0,0 +1,2 @@ +/** Explicit shared clustering capability; initialize the numerical runtime explicitly. */ +export * from '@ruvector/e-means'; diff --git a/integrations/ruv-fann/test/clustering-types.test.mts b/integrations/ruv-fann/test/clustering-types.test.mts new file mode 100644 index 00000000..7f4817a9 --- /dev/null +++ b/integrations/ruv-fann/test/clustering-types.test.mts @@ -0,0 +1,19 @@ +import { init, type EMeansOptions } from '@ruv-fann/integrations/clustering'; +import { trainProductQuantizer, encodeProductQuantizer, decodeProductQuantizer, type ProductQuantizer } from '@ruv-fann/integrations/clustering/quantization'; +import { partition, postingList, type IVFPartition } from '@ruv-fann/integrations/clustering/ivf'; +import { createClusteringEvaluator } from '@ruv-fann/integrations/clustering/metaharness'; +import { createClusteringWorker, type WorkerOptions } from '@ruv-fann/integrations/clustering/cloudflare'; + +const data = new Float32Array([1, 2, 3, 4]); +const options: EMeansOptions = { clusters: 1 }; +await init(); +const model: ProductQuantizer = trainProductQuantizer(data, 2, 2, options); +const decoded: Float32Array = decodeProductQuantizer(model, encodeProductQuantizer(model, data)); +const ivf: IVFPartition = partition(decoded, 2, options); +const list: Uint32Array = postingList(ivf, 0); +const evaluator: typeof createClusteringEvaluator = createClusteringEvaluator; +declare const workerOptions: WorkerOptions; +const worker = createClusteringWorker(workerOptions); +void [list, evaluator, worker]; +// @ts-expect-error float32 vectors are required +trainProductQuantizer([1, 2], 2, 1, options); diff --git a/integrations/ruv-fann/test/clustering.test.mjs b/integrations/ruv-fann/test/clustering.test.mjs new file mode 100644 index 00000000..7ca851a6 --- /dev/null +++ b/integrations/ruv-fann/test/clustering.test.mjs @@ -0,0 +1,42 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { readFile } from 'node:fs/promises'; +import { init } from '@ruv-fann/integrations/clustering'; +import { trainProductQuantizer, encodeProductQuantizer, decodeProductQuantizer } from '@ruv-fann/integrations/clustering/quantization'; +import { partition, postingList } from '@ruv-fann/integrations/clustering/ivf'; +import { createClusteringEvaluator } from '@ruv-fann/integrations/clustering/metaharness'; +import { createClusteringWorker } from '@ruv-fann/integrations/clustering/cloudflare'; + +await init(); + +test('optional integrations expose shared Rust/WASM clustering without a prepared network', () => { + const data = new Float32Array([1, 3, 5, 7]); + const model = trainProductQuantizer(data, 2, 2, { clusters: 1 }); + assert.deepEqual(Array.from(model.centroids), [3, 5]); + assert.deepEqual(Array.from(decodeProductQuantizer(model, encodeProductQuantizer(model, data))), [3, 5, 3, 5]); + const result = partition(data, 2, { clusters: 1 }); + assert.deepEqual(Array.from(postingList(result, 0)), [0, 1]); +}); + +test('optional MetaHarness clustering alias evaluates held-out data', async () => { + const evaluator = createClusteringEvaluator({ + training: new Float32Array([1, 3, 5, 7]), holdout: new Float32Array([3, 5, 7, 9]), dimensions: 2, + baseline: { clusters: 1, epochs: 2, batchSize: 2, peakStep: 0.5, seed: 42 }, + domain: { peakStep: { min: 0.25, max: 1, type: 'float', scale: 'linear' } }, + budget: { maxEvaluations: 1, maxDistanceCoordinates: 10000 }, + }); + const score = await evaluator.evaluate(evaluator.baselineGenome, 'fann-integrations-baseline'); + assert.equal(score.raw.holdoutMse, 16); + assert.equal(evaluator.receipt().sourceApplied, false); +}); + +test('optional Cloudflare clustering alias executes a local Worker fit', async () => { + const wasmModule = await WebAssembly.compile(await readFile(new URL(import.meta.resolve('@ruvector/e-means/wasm')))); + const worker = createClusteringWorker({ wasmModule, allowUnauthenticated: true, maxWork: 10000 }); + const response = await worker.fetch(new Request('https://local.test/fit', { + method: 'POST', headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ data: [1, 3, 5, 7], dimensions: 2, options: { clusters: 1 } }), + })); + assert.equal(response.status, 200); + assert.deepEqual((await response.json()).centroids, [3, 5]); +}); diff --git a/integrations/ruv-fann/tsconfig.json b/integrations/ruv-fann/tsconfig.json index d2cf4e04..2bca57e7 100644 --- a/integrations/ruv-fann/tsconfig.json +++ b/integrations/ruv-fann/tsconfig.json @@ -9,5 +9,5 @@ "skipLibCheck": false, "types": [] }, - "include": ["src/**/*.d.ts", "test/types.test.mts"] + "include": ["src/**/*.d.ts", "test/types.test.mts", "test/clustering-types.test.mts"] } diff --git a/packages/core/package.json b/packages/core/package.json index 3a3edc7c..0ac170b5 100644 --- a/packages/core/package.json +++ b/packages/core/package.json @@ -70,6 +70,26 @@ "./agenticow": { "types": "./src/capabilities/agenticow.d.ts", "import": "./src/capabilities/agenticow.js" + }, + "./clustering": { + "types": "./src/capabilities/clustering.d.ts", + "import": "./src/capabilities/clustering.js" + }, + "./clustering/quantization": { + "types": "./src/capabilities/clustering-quantization.d.ts", + "import": "./src/capabilities/clustering-quantization.js" + }, + "./clustering/ivf": { + "types": "./src/capabilities/clustering-ivf.d.ts", + "import": "./src/capabilities/clustering-ivf.js" + }, + "./clustering/metaharness": { + "types": "./src/capabilities/clustering-metaharness.d.ts", + "import": "./src/capabilities/clustering-metaharness.js" + }, + "./clustering/cloudflare": { + "types": "./src/capabilities/clustering-cloudflare.d.ts", + "import": "./src/capabilities/clustering-cloudflare.js" } }, "files": [ @@ -93,7 +113,8 @@ "ruvnet-constellation": "0.1.0", "ruvnet-constellation-contracts": "0.1.0", "ruvnet-constellation-telemetry": "0.1.0", - "agenticow": "0.3.0" + "agenticow": "0.3.0", + "@ruvector/e-means": "0.1.0" }, "scripts": { "test": "node --test test/*.test.mjs", diff --git a/packages/core/src/capabilities/clustering-cloudflare.d.ts b/packages/core/src/capabilities/clustering-cloudflare.d.ts new file mode 100644 index 00000000..12e37493 --- /dev/null +++ b/packages/core/src/capabilities/clustering-cloudflare.d.ts @@ -0,0 +1,2 @@ +/** Explicit shared clustering cloudflare capability. */ +export * from '@ruvector/e-means/cloudflare'; diff --git a/packages/core/src/capabilities/clustering-cloudflare.js b/packages/core/src/capabilities/clustering-cloudflare.js new file mode 100644 index 00000000..12e37493 --- /dev/null +++ b/packages/core/src/capabilities/clustering-cloudflare.js @@ -0,0 +1,2 @@ +/** Explicit shared clustering cloudflare capability. */ +export * from '@ruvector/e-means/cloudflare'; diff --git a/packages/core/src/capabilities/clustering-ivf.d.ts b/packages/core/src/capabilities/clustering-ivf.d.ts new file mode 100644 index 00000000..60479870 --- /dev/null +++ b/packages/core/src/capabilities/clustering-ivf.d.ts @@ -0,0 +1,2 @@ +/** Explicit shared clustering ivf capability. */ +export * from '@ruvector/e-means/ivf'; diff --git a/packages/core/src/capabilities/clustering-ivf.js b/packages/core/src/capabilities/clustering-ivf.js new file mode 100644 index 00000000..60479870 --- /dev/null +++ b/packages/core/src/capabilities/clustering-ivf.js @@ -0,0 +1,2 @@ +/** Explicit shared clustering ivf capability. */ +export * from '@ruvector/e-means/ivf'; diff --git a/packages/core/src/capabilities/clustering-metaharness.d.ts b/packages/core/src/capabilities/clustering-metaharness.d.ts new file mode 100644 index 00000000..83c303e9 --- /dev/null +++ b/packages/core/src/capabilities/clustering-metaharness.d.ts @@ -0,0 +1,2 @@ +/** Explicit shared clustering metaharness capability. */ +export * from '@ruvector/e-means/metaharness'; diff --git a/packages/core/src/capabilities/clustering-metaharness.js b/packages/core/src/capabilities/clustering-metaharness.js new file mode 100644 index 00000000..83c303e9 --- /dev/null +++ b/packages/core/src/capabilities/clustering-metaharness.js @@ -0,0 +1,2 @@ +/** Explicit shared clustering metaharness capability. */ +export * from '@ruvector/e-means/metaharness'; diff --git a/packages/core/src/capabilities/clustering-quantization.d.ts b/packages/core/src/capabilities/clustering-quantization.d.ts new file mode 100644 index 00000000..e648706f --- /dev/null +++ b/packages/core/src/capabilities/clustering-quantization.d.ts @@ -0,0 +1,2 @@ +/** Explicit shared clustering quantization capability. */ +export * from '@ruvector/e-means/quantization'; diff --git a/packages/core/src/capabilities/clustering-quantization.js b/packages/core/src/capabilities/clustering-quantization.js new file mode 100644 index 00000000..e648706f --- /dev/null +++ b/packages/core/src/capabilities/clustering-quantization.js @@ -0,0 +1,2 @@ +/** Explicit shared clustering quantization capability. */ +export * from '@ruvector/e-means/quantization'; diff --git a/packages/core/src/capabilities/clustering.d.ts b/packages/core/src/capabilities/clustering.d.ts new file mode 100644 index 00000000..e21ef7bd --- /dev/null +++ b/packages/core/src/capabilities/clustering.d.ts @@ -0,0 +1,2 @@ +/** Shared e-means clustering; call init() before synchronous fit/predict. */ +export * from '@ruvector/e-means'; diff --git a/packages/core/src/capabilities/clustering.js b/packages/core/src/capabilities/clustering.js new file mode 100644 index 00000000..e21ef7bd --- /dev/null +++ b/packages/core/src/capabilities/clustering.js @@ -0,0 +1,2 @@ +/** Shared e-means clustering; call init() before synchronous fit/predict. */ +export * from '@ruvector/e-means'; diff --git a/packages/core/test/clustering-submodules.test.mjs b/packages/core/test/clustering-submodules.test.mjs new file mode 100644 index 00000000..ba10a512 --- /dev/null +++ b/packages/core/test/clustering-submodules.test.mjs @@ -0,0 +1,46 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { readFile } from 'node:fs/promises'; +import { init } from 'ruv-fann/clustering'; +import { trainProductQuantizer, encodeProductQuantizer, decodeProductQuantizer } from 'ruv-fann/clustering/quantization'; +import { partition, postingList } from 'ruv-fann/clustering/ivf'; +import { createClusteringEvaluator } from 'ruv-fann/clustering/metaharness'; +import { createClusteringWorker } from 'ruv-fann/clustering/cloudflare'; + +await init(); + +test('clustering submodules expose real shared codebook codecs and IVF posting lists', () => { + const data = new Float32Array([0, 2, 4, 6, 8, 10]); + const model = trainProductQuantizer(data, 2, 2, { clusters: 1, batchSize: 2 }); + const codes = encodeProductQuantizer(model, data); + assert.deepEqual(codes, new Uint8Array(6)); + assert.deepEqual(Array.from(decodeProductQuantizer(model, codes)), [4, 6, 4, 6, 4, 6]); + const result = partition(data, 2, { clusters: 1, batchSize: 2 }); + assert.deepEqual(Array.from(result.model.centroids), [4, 6]); + assert.deepEqual(Array.from(postingList(result, 0)), [0, 1, 2]); +}); + +test('clustering MetaHarness alias measures a real held-out numerical objective', async () => { + const evaluator = createClusteringEvaluator({ + training: new Float32Array([1, 3, 5, 7]), holdout: new Float32Array([3, 5, 7, 9]), dimensions: 2, + baseline: { clusters: 1, epochs: 2, batchSize: 2, peakStep: 0.5, seed: 42 }, + domain: { peakStep: { min: 0.25, max: 1, type: 'float', scale: 'linear' } }, + budget: { maxEvaluations: 1, maxDistanceCoordinates: 10000 }, + }); + const score = await evaluator.evaluate(evaluator.baselineGenome, 'fann-core-baseline'); + assert.equal(score.raw.trainMse, 8); + assert.equal(score.raw.holdoutMse, 16); + assert.equal(evaluator.receipt().trials.length, 1); + assert.equal(evaluator.receipt().sourceApplied, false); +}); + +test('clustering Cloudflare alias executes a local Worker request with real WASM', async () => { + const wasmModule = await WebAssembly.compile(await readFile(new URL(import.meta.resolve('@ruvector/e-means/wasm')))); + const worker = createClusteringWorker({ wasmModule, allowUnauthenticated: true, maxWork: 10000 }); + const response = await worker.fetch(new Request('https://local.test/fit', { + method: 'POST', headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ data: [1, 3, 5, 7], dimensions: 2, options: { clusters: 1 } }), + })); + assert.equal(response.status, 200); + assert.deepEqual((await response.json()).centroids, [3, 5]); +}); diff --git a/packages/core/test/clustering-submodules.types.mts b/packages/core/test/clustering-submodules.types.mts new file mode 100644 index 00000000..a13c547e --- /dev/null +++ b/packages/core/test/clustering-submodules.types.mts @@ -0,0 +1,20 @@ +import { init, type EMeansOptions } from 'ruv-fann/clustering'; +import { trainProductQuantizer, encodeProductQuantizer, decodeProductQuantizer, type ProductQuantizer } from 'ruv-fann/clustering/quantization'; +import { partition, postingList, type IVFPartition } from 'ruv-fann/clustering/ivf'; +import { createClusteringEvaluator, type ClusteringEvaluator } from 'ruv-fann/clustering/metaharness'; +import { createClusteringWorker, type WorkerOptions } from 'ruv-fann/clustering/cloudflare'; + +const data = new Float32Array([1, 2, 3, 4]); +const options: EMeansOptions = { clusters: 1 }; +await init(); +const model: ProductQuantizer = trainProductQuantizer(data, 2, 2, options); +const reconstructed: Float32Array = decodeProductQuantizer(model, encodeProductQuantizer(model, data)); +const ivf: IVFPartition = partition(reconstructed, 2, options); +const list: Uint32Array = postingList(ivf, 0); +const evaluator: typeof createClusteringEvaluator = createClusteringEvaluator; +declare const instance: ClusteringEvaluator; +declare const workerOptions: WorkerOptions; +const worker: { fetch(request: Request): Promise } = createClusteringWorker(workerOptions); +void [list, evaluator, instance, worker]; +// @ts-expect-error byte codes are required +decodeProductQuantizer(model, new Uint32Array()); diff --git a/packages/core/test/clustering.test.mjs b/packages/core/test/clustering.test.mjs new file mode 100644 index 00000000..bb0d4a8f --- /dev/null +++ b/packages/core/test/clustering.test.mjs @@ -0,0 +1,27 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { init, fit, predict } from 'ruv-fann/clustering'; + +await init(); + +test('clustering capability trains and predicts using the shared WASM dependency', () => { + const data = new Float32Array([-10, -9, -9, -10, 9, 10, 10, 9]); + const options = { clusters: 2, epochs: 6, batchSize: 2, seed: 42 }; + const model = fit(data, 2, options); + assert.ok(model.centroids instanceof Float32Array); + assert.ok(model.assignments instanceof Uint32Array); + assert.equal(model.assignments[0], model.assignments[1]); + assert.equal(model.assignments[2], model.assignments[3]); + assert.notEqual(model.assignments[0], model.assignments[2]); + assert.ok(model.mse < 1); + assert.deepEqual(predict(data, 2, model.centroids), model.assignments); + assert.deepEqual(fit(data, 2, options).centroids, model.centroids); +}); + +test('clustering capability uses the last-epoch mean and rejects malformed inputs', () => { + const model = fit(new Float32Array([0, 2, 4, 6, 8, 10]), 2, { clusters: 1, batchSize: 2 }); + assert.deepEqual(Array.from(model.centroids), [4, 6]); + assert.throws(() => fit(new Float32Array([NaN]), 1, { clusters: 1 })); + assert.throws(() => fit(new Float32Array([1, 2, 3]), 2, { clusters: 1 })); + assert.throws(() => fit(new Float32Array(), 1, { clusters: 1 })); +}); diff --git a/src/clustering.rs b/src/clustering.rs new file mode 100644 index 00000000..e34ad99e --- /dev/null +++ b/src/clustering.rs @@ -0,0 +1,50 @@ +//! Optional e-means input clustering, shared with RuVector. +//! +//! Enable the `clustering` feature to build codebooks or group training inputs. +//! This module does not replace supervised neural-network training algorithms. + +use crate::TrainingData; +use thiserror::Error as ThisError; + +pub use ruvector_e_means::{fit, Config, Error, Finalization, Model}; + +/// Errors at the boundary between nested training inputs and flat e-means data. +#[derive(Debug, ThisError)] +pub enum InputClusteringError { + #[error("input clustering requires at least one nonempty input row")] + EmptyInputs, + #[error("input row {row} has {actual} dimensions; expected {expected}")] + RaggedInputs { + row: usize, + expected: usize, + actual: usize, + }, + #[error(transparent)] + Clustering(#[from] Error), +} + +impl TrainingData { + /// Cluster the input vectors without changing inputs, outputs or network weights. + /// + /// Outputs do not participate in unsupervised clustering. The shared e-means + /// implementation validates the configuration and rejects non-finite coordinates. + pub fn cluster_inputs(&self, config: &Config) -> Result { + let dimensions = self + .inputs + .first() + .map(Vec::len) + .filter(|&dimensions| dimensions > 0) + .ok_or(InputClusteringError::EmptyInputs)?; + for (row, input) in self.inputs.iter().enumerate() { + if input.len() != dimensions { + return Err(InputClusteringError::RaggedInputs { + row, + expected: dimensions, + actual: input.len(), + }); + } + } + let inputs: Vec = self.inputs.iter().flatten().copied().collect(); + Ok(fit(&inputs, dimensions, config)?) + } +} diff --git a/src/lib.rs b/src/lib.rs index d26756fa..8f5461ba 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -44,6 +44,8 @@ pub mod activation; pub mod autograd; pub mod calibration; pub mod cascade; +#[cfg(feature = "clustering")] +pub mod clustering; pub mod connection; pub mod errors; #[cfg(test)] diff --git a/tests/clustering_tests.rs b/tests/clustering_tests.rs new file mode 100644 index 00000000..a00cea13 --- /dev/null +++ b/tests/clustering_tests.rs @@ -0,0 +1,96 @@ +#![cfg(feature = "clustering")] + +use ruv_fann::{ + clustering::{fit, Config, InputClusteringError}, + TrainingData, +}; + +#[test] +fn training_inputs_use_the_shared_codebook_and_preserve_supervised_data() { + let data = TrainingData { + inputs: vec![ + vec![-10.0, -9.0], + vec![-9.0, -10.0], + vec![9.0, 10.0], + vec![10.0, 9.0], + ], + outputs: vec![vec![0.0], vec![0.0], vec![1.0], vec![1.0]], + }; + let original = data.clone(); + let config = Config { + clusters: 2, + epochs: 6, + batch_size: Some(2), + seed: 42, + ..Config::default() + }; + let model = data.cluster_inputs(&config).unwrap(); + let flat = data.inputs.iter().flatten().copied().collect::>(); + let shared = fit(&flat, 2, &config).unwrap(); + assert_eq!(model.centroids, shared.centroids); + assert_eq!(model.assignments, shared.assignments); + assert_eq!(model.dimensions, 2); + assert_eq!(model.assignments[0], model.assignments[1]); + assert_eq!(model.assignments[2], model.assignments[3]); + assert_ne!(model.assignments[0], model.assignments[2]); + assert!(model.mse < 1.0); + assert_eq!(data.inputs, original.inputs); + assert_eq!(data.outputs, original.outputs); +} + +#[test] +fn one_cluster_is_the_input_mean_independent_of_targets() { + let data = TrainingData { + inputs: vec![vec![0.0, 2.0], vec![4.0, 6.0], vec![8.0, 10.0]], + outputs: vec![], + }; + let model = data + .cluster_inputs(&Config { + clusters: 1, + batch_size: Some(2), + ..Config::default() + }) + .unwrap(); + assert_eq!(model.centroids, vec![4.0, 6.0]); + assert_eq!(model.assignments, vec![0, 0, 0]); + assert_eq!(model.predict(&[4.0, 6.0]).unwrap(), vec![0]); +} + +#[test] +fn input_shape_and_finiteness_fail_before_a_model_is_returned() { + for inputs in [vec![], vec![vec![]]] { + let data = TrainingData:: { + inputs, + outputs: vec![], + }; + assert!(matches!( + data.cluster_inputs(&Config::default()), + Err(InputClusteringError::EmptyInputs) + )); + } + let data = TrainingData { + inputs: vec![vec![1.0, 2.0], vec![3.0]], + outputs: vec![], + }; + assert!(matches!( + data.cluster_inputs(&Config::default()), + Err(InputClusteringError::RaggedInputs { + row: 1, + expected: 2, + actual: 1 + }) + )); + for coordinate in [f32::NAN, f32::INFINITY, f32::NEG_INFINITY] { + let data = TrainingData { + inputs: vec![vec![coordinate]], + outputs: vec![], + }; + assert!(matches!( + data.cluster_inputs(&Config { + clusters: 1, + ..Config::default() + }), + Err(InputClusteringError::Clustering(_)) + )); + } +}