embed-cluster 0.3.0

package/README.md

@@ -0,0 +1,122 @@
+# embed-cluster
+
+Cluster embeddings into topics with automatic labeling.
+
+## Installation
+
+```bash
+npm install embed-cluster
+```
+
+For dimensionality reduction (PCA or UMAP), install the optional peer dependencies:
+
+```bash
+npm install ml-pca    # PCA-based dimensionality reduction
+npm install umap-js   # UMAP-based dimensionality reduction
+```
+
+## Quick Start
+
+```ts
+import { cluster, createClusterer } from 'embed-cluster';
+
+// Cluster raw embedding vectors
+const result = await cluster(embeddings, { k: 5 });
+
+console.log(result.clusters); // 5 clusters with labels, centroids, items
+console.log(result.quality);  // silhouette score, inertia, interpretation
+
+// Or use a pre-configured clusterer
+const clusterer = createClusterer({
+  autoK: true,
+  maxK: 15,
+  normalize: true,
+});
+
+const result = await clusterer.cluster(items);
+const optimal = await clusterer.findOptimalK(items);
+```
+
+## Available Exports
+
+### Clustering Functions
+
+- **`cluster(items, options): Promise<ClusterResult>`** -- Cluster EmbedItems using k-means++ and return a full ClusterResult with silhouette scores. Provide `options.k` for a fixed cluster count or `options.autoK = true` for automatic selection.
+- **`findOptimalK(items, options?): OptimalKResult`** -- Try k from 2 to `maxK` (default min(10, √n)), compute silhouette score for each, and return the k that maximises the score.
+- **`silhouetteScore(result): SilhouetteResult`** -- Compute per-item, per-cluster, and overall mean silhouette coefficients for an existing ClusterResult. Returns a value in [-1, 1]; higher is better.
+- **`createClusterer(config): Clusterer`** -- Create a pre-configured Clusterer instance with `cluster()`, `findOptimalK()`, and `silhouetteScore()` bound to the given config.
+
+### Utility Functions
+
+- **`normalizeVector(vec: number[]): number[]`** -- L2-normalize a single vector to unit length. Returns a zero vector unchanged.
+- **`normalizeVectors(vecs: number[][]): number[][]`** -- L2-normalize a batch of vectors independently.
+- **`euclideanDistance(a, b): number`** -- Euclidean distance between two vectors.
+- **`cosineDistance(a, b): number`** -- Cosine distance (1 - cosine similarity) between two vectors.
+
+### Types
+
+All TypeScript interfaces are exported for consumer use:
+
+- `EmbedItem` -- Input item with id, text, embedding, and optional metadata
+- `ClusterItem` -- An `EmbedItem` assigned to a cluster with distance-to-centroid
+- `Cluster` -- A cluster with centroid, items, label, size, and cohesion metrics
+- `ClusterOptions` -- Configuration for clustering (k, autoK, maxK, tolerance, seed, etc.)
+- `ClusterResult` -- Full result including clusters, quality metrics, iteration count, and timing
+- `Clusterer` -- Interface for a pre-configured clusterer instance
+- `SilhouetteResult` -- Silhouette coefficient scores (overall, per-cluster, per-item)
+- `OptimalKResult` -- Result of automatic k selection with scores per candidate k
+- `ClusterQuality` -- Quality metrics including silhouette, inertia, and optional indices
+- `VisualizationData` -- 2D projected points for visualization (PCA, UMAP, or t-SNE)
+- `LabelerFn` -- Custom labeling function signature
+
+### Error Handling
+
+- **`ClusterError`** -- Error class with typed `code` field for programmatic error handling
+- **`ClusterErrorCode`** -- Union type of error codes: `EMPTY_INPUT`, `INCONSISTENT_DIMENSIONS`, `DEGENERATE_INPUT`, `INVALID_K`, `INVALID_OPTIONS`
+
+```ts
+import { ClusterError } from 'embed-cluster';
+
+try {
+  const result = await cluster([], { k: 3 });
+} catch (err) {
+  if (err instanceof ClusterError) {
+    console.error(err.code); // 'EMPTY_INPUT'
+  }
+}
+```
+
+## Features
+
+- **k-means++ clustering** -- Smart centroid initialization for faster convergence and better results
+- **Silhouette analysis** -- Evaluate cluster quality with per-point and per-cluster silhouette coefficients
+- **Automatic k selection** -- Find the optimal number of clusters using silhouette and elbow methods
+- **PCA/UMAP visualization** -- Reduce high-dimensional embeddings to 2D for visualization (requires optional peer deps)
+- **L2 normalization** -- Built-in vector normalization for cosine-distance clustering
+- **Custom labeling** -- Provide your own labeling function or use built-in TF-IDF topic extraction
+- **Reproducible results** -- Seed-based random number generation for deterministic clustering
+- **TypeScript-first** -- Full type definitions with strict typing throughout
+
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `k` | `number` | -- | Number of clusters (required if `autoK` is false) |
+| `autoK` | `boolean` | `false` | Automatically select optimal k |
+| `maxK` | `number` | `10` | Maximum k to try when `autoK` is true |
+| `maxIterations` | `number` | `100` | Maximum k-means iterations |
+| `tolerance` | `number` | `1e-4` | Convergence tolerance |
+| `seed` | `number` | -- | Random seed for reproducibility |
+| `normalize` | `boolean` | `true` | L2-normalize embeddings before clustering |
+| `labeler` | `LabelerFn` | -- | Custom labeling function |
+| `distanceFn` | `Function` | -- | Custom distance function |
+
+## CLI
+
+```bash
+npx embed-cluster --input embeddings.json --k 5 --format summary
+```
+
+## License
+
+MIT

package/dist/__tests__/cluster.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cluster.test.d.ts.map

package/dist/__tests__/cluster.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cluster.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/cluster.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/cluster.test.js

@@ -0,0 +1,202 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const clusterer_1 = require("../clusterer");
+const silhouette_1 = require("../silhouette");
+const errors_1 = require("../errors");
+const embeddings_small_json_1 = __importDefault(require("./fixtures/embeddings-small.json"));
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function makeItems(coords) {
+    return coords.map((embedding, i) => ({ id: `item-${i}`, text: `doc ${i}`, embedding }));
+}
+// Two clear clusters: group near [1,0] and group near [-1,0]
+const GROUP_A = [[1, 0.05], [1.1, 0], [0.9, -0.05], [1.0, 0.02]];
+const GROUP_B = [[-1, 0.05], [-1.1, 0], [-0.9, -0.05], [-1.0, 0.02]];
+const ITEMS_2 = makeItems([...GROUP_A, ...GROUP_B]);
+// Three clear clusters
+const GROUP_C = [[0, 1.0], [0.05, 1.1], [-0.05, 0.95]];
+const ITEMS_3 = makeItems([...GROUP_A, ...GROUP_B, ...GROUP_C]);
+// ---------------------------------------------------------------------------
+// cluster()
+// ---------------------------------------------------------------------------
+(0, vitest_1.describe)('cluster()', () => {
+    (0, vitest_1.it)('returns a ClusterResult with k=2 clusters', async () => {
+        const result = await (0, clusterer_1.cluster)(ITEMS_2, { k: 2, normalize: false, seed: 1 });
+        (0, vitest_1.expect)(result.k).toBe(2);
+        (0, vitest_1.expect)(result.clusters).toHaveLength(2);
+    });
+    (0, vitest_1.it)('all items appear in result', async () => {
+        const result = await (0, clusterer_1.cluster)(ITEMS_2, { k: 2, normalize: false, seed: 1 });
+        const total = result.clusters.reduce((s, c) => s + c.items.length, 0);
+        (0, vitest_1.expect)(total).toBe(ITEMS_2.length);
+    });
+    (0, vitest_1.it)('quality.silhouette.score is populated (non-zero for separated data)', async () => {
+        const result = await (0, clusterer_1.cluster)(ITEMS_2, { k: 2, normalize: false, seed: 1 });
+        (0, vitest_1.expect)(result.quality.silhouette.score).toBeGreaterThan(0.5);
+    });
+    (0, vitest_1.it)('quality.silhouette.perCluster has length k', async () => {
+        const result = await (0, clusterer_1.cluster)(ITEMS_2, { k: 2, normalize: false, seed: 1 });
+        (0, vitest_1.expect)(result.quality.silhouette.perCluster).toHaveLength(2);
+    });
+    (0, vitest_1.it)('throws ClusterError EMPTY_INPUT for empty array', async () => {
+        await (0, vitest_1.expect)((0, clusterer_1.cluster)([], { k: 2 })).rejects.toThrow(errors_1.ClusterError);
+        await (0, vitest_1.expect)((0, clusterer_1.cluster)([], { k: 2 })).rejects.toMatchObject({ code: 'EMPTY_INPUT' });
+    });
+    (0, vitest_1.it)('throws ClusterError INVALID_OPTIONS when neither k nor autoK provided', async () => {
+        await (0, vitest_1.expect)((0, clusterer_1.cluster)(ITEMS_2, {})).rejects.toThrow(errors_1.ClusterError);
+        await (0, vitest_1.expect)((0, clusterer_1.cluster)(ITEMS_2, {})).rejects.toMatchObject({ code: 'INVALID_OPTIONS' });
+    });
+    (0, vitest_1.it)('autoK=true selects k and returns result', async () => {
+        const result = await (0, clusterer_1.cluster)(ITEMS_3, { autoK: true, normalize: false, seed: 1 });
+        (0, vitest_1.expect)(result.k).toBeGreaterThanOrEqual(2);
+        (0, vitest_1.expect)(result.clusters).toHaveLength(result.k);
+    });
+    (0, vitest_1.it)('durationMs is populated', async () => {
+        const result = await (0, clusterer_1.cluster)(ITEMS_2, { k: 2, normalize: false, seed: 1 });
+        (0, vitest_1.expect)(result.durationMs).toBeGreaterThanOrEqual(0);
+    });
+    (0, vitest_1.it)('labeler is called for each cluster', async () => {
+        const labels = [];
+        const result = await (0, clusterer_1.cluster)(ITEMS_2, {
+            k: 2,
+            normalize: false,
+            seed: 1,
+            labeler: (_items, id) => {
+                const label = `cluster-${id}`;
+                labels.push(label);
+                return label;
+            },
+        });
+        (0, vitest_1.expect)(labels).toHaveLength(2);
+        for (const c of result.clusters) {
+            (0, vitest_1.expect)(c.label).toBeDefined();
+            (0, vitest_1.expect)(c.label).toMatch(/^cluster-\d$/);
+        }
+    });
+    (0, vitest_1.it)('async labeler is supported', async () => {
+        const result = await (0, clusterer_1.cluster)(ITEMS_2, {
+            k: 2,
+            normalize: false,
+            seed: 1,
+            labeler: async (_items, id) => {
+                return `async-label-${id}`;
+            },
+        });
+        for (const c of result.clusters) {
+            (0, vitest_1.expect)(c.label).toMatch(/^async-label-\d$/);
+        }
+    });
+    (0, vitest_1.it)('works with fixture data (20 items, 4D embeddings, k=3)', async () => {
+        const items = embeddings_small_json_1.default.items;
+        const result = await (0, clusterer_1.cluster)(items, { k: 3, normalize: true, seed: 42 });
+        (0, vitest_1.expect)(result.k).toBe(3);
+        const total = result.clusters.reduce((s, c) => s + c.items.length, 0);
+        (0, vitest_1.expect)(total).toBe(20);
+    });
+    (0, vitest_1.it)('fixture: silhouette score > 0.5 for well-separated clusters', async () => {
+        const items = embeddings_small_json_1.default.items;
+        const result = await (0, clusterer_1.cluster)(items, { k: 3, normalize: true, seed: 42 });
+        (0, vitest_1.expect)(result.quality.silhouette.score).toBeGreaterThan(0.5);
+    });
+});
+// ---------------------------------------------------------------------------
+// findOptimalK()
+// ---------------------------------------------------------------------------
+(0, vitest_1.describe)('findOptimalK()', () => {
+    (0, vitest_1.it)('returns an OptimalKResult with a k value', () => {
+        const result = (0, clusterer_1.findOptimalK)(ITEMS_3, { normalize: false, seed: 1 });
+        (0, vitest_1.expect)(result.k).toBeGreaterThanOrEqual(2);
+    });
+    (0, vitest_1.it)('method is "silhouette"', () => {
+        const result = (0, clusterer_1.findOptimalK)(ITEMS_3, { normalize: false, seed: 1 });
+        (0, vitest_1.expect)(result.method).toBe('silhouette');
+    });
+    (0, vitest_1.it)('scores array has an entry per k tried', () => {
+        const result = (0, clusterer_1.findOptimalK)(ITEMS_3, { normalize: false, seed: 1, maxK: 4 });
+        // kMin=2, kMax=min(4, n-1)
+        (0, vitest_1.expect)(result.scores.length).toBeGreaterThanOrEqual(1);
+        for (const entry of result.scores) {
+            (0, vitest_1.expect)(entry.k).toBeGreaterThanOrEqual(2);
+            (0, vitest_1.expect)(typeof entry.silhouette).toBe('number');
+            (0, vitest_1.expect)(typeof entry.inertia).toBe('number');
+        }
+    });
+    (0, vitest_1.it)('returns k >= 3 for clearly 3-cluster data (silhouette selects good k)', () => {
+        const result = (0, clusterer_1.findOptimalK)(ITEMS_3, { normalize: false, seed: 1, maxK: 5 });
+        // The selected k must be at least 3 (the true cluster count); silhouette
+        // may also prefer tighter sub-clusters when maxK allows it.
+        (0, vitest_1.expect)(result.k).toBeGreaterThanOrEqual(3);
+    });
+    (0, vitest_1.it)('selected k has the highest silhouette score in scores', () => {
+        const result = (0, clusterer_1.findOptimalK)(ITEMS_3, { normalize: false, seed: 1, maxK: 5 });
+        const best = result.scores.reduce((a, b) => (a.silhouette > b.silhouette ? a : b));
+        (0, vitest_1.expect)(result.k).toBe(best.k);
+    });
+    (0, vitest_1.it)('fixture: findOptimalK returns k=3 for 3-cluster fixture', () => {
+        const items = embeddings_small_json_1.default.items;
+        const result = (0, clusterer_1.findOptimalK)(items, { normalize: true, seed: 42, maxK: 6 });
+        (0, vitest_1.expect)(result.k).toBe(3);
+    });
+});
+// ---------------------------------------------------------------------------
+// createClusterer()
+// ---------------------------------------------------------------------------
+(0, vitest_1.describe)('createClusterer()', () => {
+    (0, vitest_1.it)('returns an object with cluster, findOptimalK, silhouetteScore', () => {
+        const c = (0, clusterer_1.createClusterer)({ normalize: false, seed: 1 });
+        (0, vitest_1.expect)(typeof c.cluster).toBe('function');
+        (0, vitest_1.expect)(typeof c.findOptimalK).toBe('function');
+        (0, vitest_1.expect)(typeof c.silhouetteScore).toBe('function');
+    });
+    (0, vitest_1.it)('cluster() uses bound config', async () => {
+        const c = (0, clusterer_1.createClusterer)({ normalize: false, seed: 1 });
+        const result = await c.cluster(ITEMS_2, { k: 2 });
+        (0, vitest_1.expect)(result.k).toBe(2);
+        (0, vitest_1.expect)(result.clusters).toHaveLength(2);
+    });
+    (0, vitest_1.it)('cluster() options override bound config', async () => {
+        const c = (0, clusterer_1.createClusterer)({ normalize: false, seed: 1, k: 2 });
+        // Override k=2 with k=1
+        const result = await c.cluster(ITEMS_2, { k: 1 });
+        (0, vitest_1.expect)(result.k).toBe(1);
+    });
+    (0, vitest_1.it)('findOptimalK() uses bound config', async () => {
+        const c = (0, clusterer_1.createClusterer)({ normalize: false, seed: 1 });
+        const result = await c.findOptimalK(ITEMS_3, { maxK: 5 });
+        (0, vitest_1.expect)(result.k).toBeGreaterThanOrEqual(2);
+    });
+    (0, vitest_1.it)('silhouetteScore() returns SilhouetteResult', async () => {
+        const c = (0, clusterer_1.createClusterer)({ normalize: false, seed: 1 });
+        const result = await c.cluster(ITEMS_2, { k: 2 });
+        const sil = c.silhouetteScore(result);
+        (0, vitest_1.expect)(typeof sil.score).toBe('number');
+        (0, vitest_1.expect)(sil.perCluster).toHaveLength(2);
+    });
+    (0, vitest_1.it)('two clusterers with different seeds can produce different assignments', async () => {
+        // Use a case where seed matters: run on data where init order could vary
+        const c1 = (0, clusterer_1.createClusterer)({ normalize: false, seed: 1 });
+        const c2 = (0, clusterer_1.createClusterer)({ normalize: false, seed: 99999 });
+        const r1 = await c1.cluster(ITEMS_3, { k: 3 });
+        const r2 = await c2.cluster(ITEMS_3, { k: 3 });
+        // Both should still produce 3 clusters — the assignments may differ
+        (0, vitest_1.expect)(r1.clusters).toHaveLength(3);
+        (0, vitest_1.expect)(r2.clusters).toHaveLength(3);
+    });
+});
+// ---------------------------------------------------------------------------
+// silhouetteScore re-export from clusterer
+// ---------------------------------------------------------------------------
+(0, vitest_1.describe)('silhouetteScore re-export', () => {
+    (0, vitest_1.it)('silhouetteScore from clusterer matches silhouetteScore from silhouette module', async () => {
+        const result = await (0, clusterer_1.cluster)(ITEMS_2, { k: 2, normalize: false, seed: 1 });
+        const s1 = (0, clusterer_1.silhouetteScore)(result);
+        const s2 = (0, silhouette_1.silhouetteScore)(result);
+        (0, vitest_1.expect)(s1.score).toBeCloseTo(s2.score, 10);
+    });
+});
+//# sourceMappingURL=cluster.test.js.map

package/dist/__tests__/cluster.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cluster.test.js","sourceRoot":"","sources":["../../src/__tests__/cluster.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/errors.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=errors.test.d.ts.map

package/dist/__tests__/errors.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/errors.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/errors.test.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const errors_1 = require("../errors");
+(0, vitest_1.describe)('ClusterError', () => {
+    (0, vitest_1.it)('extends Error', () => {
+        const err = new errors_1.ClusterError('something failed', 'EMPTY_INPUT');
+        (0, vitest_1.expect)(err).toBeInstanceOf(Error);
+    });
+    (0, vitest_1.it)('name is ClusterError', () => {
+        const err = new errors_1.ClusterError('msg', 'INVALID_K');
+        (0, vitest_1.expect)(err.name).toBe('ClusterError');
+    });
+    (0, vitest_1.it)('code is accessible', () => {
+        const err = new errors_1.ClusterError('bad k', 'INVALID_K');
+        (0, vitest_1.expect)(err.code).toBe('INVALID_K');
+    });
+    (0, vitest_1.it)('instanceof ClusterError is correct', () => {
+        const err = new errors_1.ClusterError('test', 'INVALID_OPTIONS');
+        (0, vitest_1.expect)(err).toBeInstanceOf(errors_1.ClusterError);
+    });
+    (0, vitest_1.it)('message is preserved', () => {
+        const msg = 'embeddings array is empty';
+        const err = new errors_1.ClusterError(msg, 'EMPTY_INPUT');
+        (0, vitest_1.expect)(err.message).toBe(msg);
+    });
+    (0, vitest_1.it)('constructs with EMPTY_INPUT code', () => {
+        const err = new errors_1.ClusterError('no items', 'EMPTY_INPUT');
+        (0, vitest_1.expect)(err.code).toBe('EMPTY_INPUT');
+    });
+    (0, vitest_1.it)('constructs with INCONSISTENT_DIMENSIONS code', () => {
+        const err = new errors_1.ClusterError('dim mismatch', 'INCONSISTENT_DIMENSIONS');
+        (0, vitest_1.expect)(err.code).toBe('INCONSISTENT_DIMENSIONS');
+    });
+    (0, vitest_1.it)('constructs with DEGENERATE_INPUT code', () => {
+        const err = new errors_1.ClusterError('all zeros', 'DEGENERATE_INPUT');
+        (0, vitest_1.expect)(err.code).toBe('DEGENERATE_INPUT');
+    });
+    (0, vitest_1.it)('constructs with INVALID_K code', () => {
+        const err = new errors_1.ClusterError('k must be >= 2', 'INVALID_K');
+        (0, vitest_1.expect)(err.code).toBe('INVALID_K');
+    });
+    (0, vitest_1.it)('constructs with INVALID_OPTIONS code', () => {
+        const err = new errors_1.ClusterError('bad options', 'INVALID_OPTIONS');
+        (0, vitest_1.expect)(err.code).toBe('INVALID_OPTIONS');
+    });
+    (0, vitest_1.it)('all 5 error codes construct correctly', () => {
+        const codes = [
+            'EMPTY_INPUT',
+            'INCONSISTENT_DIMENSIONS',
+            'DEGENERATE_INPUT',
+            'INVALID_K',
+            'INVALID_OPTIONS',
+        ];
+        for (const code of codes) {
+            const err = new errors_1.ClusterError(`error: ${code}`, code);
+            (0, vitest_1.expect)(err).toBeInstanceOf(errors_1.ClusterError);
+            (0, vitest_1.expect)(err).toBeInstanceOf(Error);
+            (0, vitest_1.expect)(err.code).toBe(code);
+            (0, vitest_1.expect)(err.name).toBe('ClusterError');
+        }
+    });
+    (0, vitest_1.it)('stack trace is populated', () => {
+        const err = new errors_1.ClusterError('trace check', 'EMPTY_INPUT');
+        (0, vitest_1.expect)(err.stack).toBeDefined();
+    });
+});
+//# sourceMappingURL=errors.test.js.map

package/dist/__tests__/errors.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.test.js","sourceRoot":"","sources":["../../src/__tests__/errors.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/fixtures/embeddings-small.json

@@ -0,0 +1,25 @@
+{
+    "description": "20 synthetic 4D embeddings with 3 clear clusters",
+    "items": [
+        { "id": "c0-0", "text": "doc 0", "embedding": [0.95, 0.1, -0.1, 0.05] },
+        { "id": "c0-1", "text": "doc 1", "embedding": [1.0, -0.05, 0.08, -0.03] },
+        { "id": "c0-2", "text": "doc 2", "embedding": [0.9, 0.15, -0.12, 0.1] },
+        { "id": "c0-3", "text": "doc 3", "embedding": [0.98, 0.0, 0.05, -0.08] },
+        { "id": "c0-4", "text": "doc 4", "embedding": [0.92, -0.1, 0.1, 0.05] },
+        { "id": "c0-5", "text": "doc 5", "embedding": [0.97, 0.07, -0.07, 0.02] },
+        { "id": "c1-0", "text": "doc 6", "embedding": [-0.05, 0.95, 0.1, 0.05] },
+        { "id": "c1-1", "text": "doc 7", "embedding": [0.08, 1.0, -0.05, -0.03] },
+        { "id": "c1-2", "text": "doc 8", "embedding": [-0.1, 0.9, 0.15, 0.1] },
+        { "id": "c1-3", "text": "doc 9", "embedding": [0.0, 0.98, 0.05, -0.08] },
+        { "id": "c1-4", "text": "doc 10", "embedding": [0.07, 0.93, -0.1, -0.05] },
+        { "id": "c1-5", "text": "doc 11", "embedding": [-0.03, 0.97, 0.07, 0.02] },
+        { "id": "c2-0", "text": "doc 12", "embedding": [0.05, -0.05, 0.95, 0.1] },
+        { "id": "c2-1", "text": "doc 13", "embedding": [-0.08, 0.05, 1.0, -0.05] },
+        { "id": "c2-2", "text": "doc 14", "embedding": [0.1, -0.1, 0.9, 0.15] },
+        { "id": "c2-3", "text": "doc 15", "embedding": [-0.0, 0.0, 0.98, 0.05] },
+        { "id": "c2-4", "text": "doc 16", "embedding": [0.07, 0.05, 0.93, -0.1] },
+        { "id": "c2-5", "text": "doc 17", "embedding": [-0.03, -0.03, 0.97, 0.07] },
+        { "id": "extra-0", "text": "doc 18", "embedding": [0.96, 0.12, -0.08, 0.03] },
+        { "id": "extra-1", "text": "doc 19", "embedding": [-0.02, 0.96, 0.12, 0.04] }
+    ]
+}

package/dist/__tests__/fixtures.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=fixtures.test.d.ts.map

package/dist/__tests__/fixtures.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixtures.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/fixtures.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/fixtures.test.js

@@ -0,0 +1,44 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const embeddings_small_json_1 = __importDefault(require("./fixtures/embeddings-small.json"));
+(0, vitest_1.describe)('embeddings-small.json fixture', () => {
+    (0, vitest_1.it)('loads and parses', () => {
+        (0, vitest_1.expect)(embeddings_small_json_1.default).toBeDefined();
+        (0, vitest_1.expect)(typeof embeddings_small_json_1.default).toBe('object');
+    });
+    (0, vitest_1.it)('has exactly 20 items', () => {
+        (0, vitest_1.expect)(embeddings_small_json_1.default.items).toHaveLength(20);
+    });
+    (0, vitest_1.it)('each item has id, text, embedding fields', () => {
+        for (const item of embeddings_small_json_1.default.items) {
+            (0, vitest_1.expect)(typeof item.id).toBe('string');
+            (0, vitest_1.expect)(typeof item.text).toBe('string');
+            (0, vitest_1.expect)(Array.isArray(item.embedding)).toBe(true);
+        }
+    });
+    (0, vitest_1.it)('all embeddings have length 4', () => {
+        for (const item of embeddings_small_json_1.default.items) {
+            (0, vitest_1.expect)(item.embedding).toHaveLength(4);
+        }
+    });
+    (0, vitest_1.it)('all embedding values are numbers', () => {
+        for (const item of embeddings_small_json_1.default.items) {
+            for (const val of item.embedding) {
+                (0, vitest_1.expect)(typeof val).toBe('number');
+            }
+        }
+    });
+    (0, vitest_1.it)('all item ids are unique', () => {
+        const ids = embeddings_small_json_1.default.items.map((i) => i.id);
+        const unique = new Set(ids);
+        (0, vitest_1.expect)(unique.size).toBe(20);
+    });
+    (0, vitest_1.it)('has a description field', () => {
+        (0, vitest_1.expect)(typeof embeddings_small_json_1.default.description).toBe('string');
+    });
+});
+//# sourceMappingURL=fixtures.test.js.map

package/dist/__tests__/fixtures.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixtures.test.js","sourceRoot":"","sources":["../../src/__tests__/fixtures.test.ts"],"names":[],"mappings":";;;;;AAAA,mCAA8C;AAC9C,6FAAuD;AAEvD,IAAA,iBAAQ,EAAC,+BAA+B,EAAE,GAAG,EAAE;IAC7C,IAAA,WAAE,EAAC,kBAAkB,EAAE,GAAG,EAAE;QAC1B,IAAA,eAAM,EAAC,+BAAO,CAAC,CAAC,WAAW,EAAE,CAAC;QAC9B,IAAA,eAAM,EAAC,OAAO,+BAAO,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACxC,CAAC,CAAC,CAAC;IAEH,IAAA,WAAE,EAAC,sBAAsB,EAAE,GAAG,EAAE;QAC9B,IAAA,eAAM,EAAC,+BAAO,CAAC,KAAK,CAAC,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC;IACzC,CAAC,CAAC,CAAC;IAEH,IAAA,WAAE,EAAC,0CAA0C,EAAE,GAAG,EAAE;QAClD,KAAK,MAAM,IAAI,IAAI,+BAAO,CAAC,KAAK,EAAE,CAAC;YACjC,IAAA,eAAM,EAAC,OAAO,IAAI,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACtC,IAAA,eAAM,EAAC,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACxC,IAAA,eAAM,EAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnD,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,IAAA,WAAE,EAAC,8BAA8B,EAAE,GAAG,EAAE;QACtC,KAAK,MAAM,IAAI,IAAI,+BAAO,CAAC,KAAK,EAAE,CAAC;YACjC,IAAA,eAAM,EAAC,IAAI,CAAC,SAAS,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QACzC,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,IAAA,WAAE,EAAC,kCAAkC,EAAE,GAAG,EAAE;QAC1C,KAAK,MAAM,IAAI,IAAI,+BAAO,CAAC,KAAK,EAAE,CAAC;YACjC,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;gBACjC,IAAA,eAAM,EAAC,OAAO,GAAG,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACpC,CAAC;QACH,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,IAAA,WAAE,EAAC,yBAAyB,EAAE,GAAG,EAAE;QACjC,MAAM,GAAG,GAAG,+BAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAC3C,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAA,eAAM,EAAC,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC/B,CAAC,CAAC,CAAC;IAEH,IAAA,WAAE,EAAC,yBAAyB,EAAE,GAAG,EAAE;QACjC,IAAA,eAAM,EAAC,OAAO,+BAAO,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACpD,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/__tests__/kmeans.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=kmeans.test.d.ts.map

package/dist/__tests__/kmeans.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kmeans.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/kmeans.test.ts"],"names":[],"mappings":""}