embed-cluster 0.3.0

package/dist/silhouette.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.silhouetteScore = silhouetteScore;
+const kmeans_1 = require("./kmeans");
+// ---------------------------------------------------------------------------
+// Silhouette scoring
+// ---------------------------------------------------------------------------
+/**
+ * Compute the silhouette score for a clustering result.
+ *
+ * Per-item silhouette coefficient:
+ *   s(i) = (b(i) - a(i)) / max(a(i), b(i))
+ *
+ * where:
+ *   a(i) = mean distance from item i to all other items in the same cluster
+ *   b(i) = mean distance from item i to all items in the nearest other cluster
+ *
+ * Returns value in [-1, 1]; higher is better.
+ * If only one cluster exists, returns 0 for all items.
+ */
+function silhouetteScore(result, distFn = kmeans_1.euclideanDistance) {
+    const { clusters } = result;
+    // Need at least 2 clusters to compute silhouette
+    if (clusters.length < 2) {
+        return {
+            score: 0,
+            perCluster: clusters.map(() => 0),
+            perItem: clusters.flatMap(c => c.items.map(() => 0)),
+        };
+    }
+    const allPerItem = [];
+    const perCluster = [];
+    for (const cluster of clusters) {
+        if (cluster.items.length === 0) {
+            perCluster.push(0);
+            continue;
+        }
+        const clusterScores = [];
+        for (const item of cluster.items) {
+            const v = item.embedding;
+            // a(i): mean intra-cluster distance
+            let a = 0;
+            if (cluster.items.length > 1) {
+                let aSum = 0;
+                for (const other of cluster.items) {
+                    if (other.id !== item.id) {
+                        aSum += distFn(v, other.embedding);
+                    }
+                }
+                a = aSum / (cluster.items.length - 1);
+            }
+            // If only 1 item in cluster, a = 0
+            // b(i): mean distance to nearest other cluster
+            let b = Infinity;
+            for (const otherCluster of clusters) {
+                if (otherCluster.id === cluster.id)
+                    continue;
+                if (otherCluster.items.length === 0)
+                    continue;
+                let bSum = 0;
+                for (const other of otherCluster.items) {
+                    bSum += distFn(v, other.embedding);
+                }
+                const bMean = bSum / otherCluster.items.length;
+                if (bMean < b)
+                    b = bMean;
+            }
+            // Silhouette for this item
+            let s;
+            if (b === Infinity) {
+                // Only one non-empty cluster
+                s = 0;
+            }
+            else {
+                const maxAB = Math.max(a, b);
+                s = maxAB === 0 ? 0 : (b - a) / maxAB;
+            }
+            clusterScores.push(s);
+            allPerItem.push(s);
+        }
+        const clusterMean = clusterScores.length > 0
+            ? clusterScores.reduce((sum, s) => sum + s, 0) / clusterScores.length
+            : 0;
+        perCluster.push(clusterMean);
+    }
+    const overallScore = allPerItem.length > 0
+        ? allPerItem.reduce((sum, s) => sum + s, 0) / allPerItem.length
+        : 0;
+    return {
+        score: overallScore,
+        perCluster,
+        perItem: allPerItem,
+    };
+}
+//# sourceMappingURL=silhouette.js.map

package/dist/silhouette.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,74 @@
+export interface EmbedItem {
+    id: string;
+    text: string;
+    embedding: number[];
+    metadata?: Record<string, unknown>;
+}
+export interface ClusterItem extends EmbedItem {
+    clusterId: number;
+    distanceToCentroid: number;
+}
+export interface Cluster {
+    id: number;
+    centroid: number[];
+    items: ClusterItem[];
+    label?: string;
+    size: number;
+    avgDistanceToCentroid: number;
+    cohesion: number;
+}
+export interface SilhouetteResult {
+    score: number;
+    perCluster: number[];
+    perItem?: number[];
+}
+export interface OptimalKResult {
+    k: number;
+    scores: Array<{
+        k: number;
+        silhouette: number;
+        inertia: number;
+    }>;
+    method: 'silhouette' | 'elbow' | 'combined';
+}
+export interface ClusterQuality {
+    silhouette: SilhouetteResult;
+    inertia: number;
+    daviesBouldin?: number;
+    calinski?: number;
+}
+export interface VisualizationData {
+    points: Array<{
+        id: string;
+        x: number;
+        y: number;
+        clusterId: number;
+    }>;
+    method: 'pca' | 'umap' | 'tsne';
+}
+export type LabelerFn = (items: EmbedItem[], clusterId: number) => Promise<string> | string;
+export interface ClusterOptions {
+    k?: number;
+    autoK?: boolean;
+    maxK?: number;
+    maxIterations?: number;
+    tolerance?: number;
+    seed?: number;
+    normalize?: boolean;
+    labeler?: LabelerFn;
+    distanceFn?: (a: number[], b: number[]) => number;
+}
+export interface ClusterResult {
+    clusters: Cluster[];
+    quality: ClusterQuality;
+    k: number;
+    iterations: number;
+    converged: boolean;
+    durationMs: number;
+}
+export interface Clusterer {
+    cluster(items: EmbedItem[], options?: ClusterOptions): Promise<ClusterResult>;
+    findOptimalK(items: EmbedItem[], options?: Omit<ClusterOptions, 'k'>): Promise<OptimalKResult>;
+    silhouetteScore(result: ClusterResult): SilhouetteResult;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "embed-cluster",
+  "version": "0.3.0",
+  "description": "Cluster embeddings into topics with automatic labeling",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "embed-cluster": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "lint": "eslint src/",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "ml-pca": ">=4.0.0",
+    "umap-js": ">=1.4.0"
+  },
+  "peerDependenciesMeta": {
+    "ml-pca": {
+      "optional": true
+    },
+    "umap-js": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "@typescript-eslint/eslint-plugin": "^8.57.1",
+    "@typescript-eslint/parser": "^8.57.1",
+    "eslint": "^10.1.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0"
+  }
+}