embed-cluster

Cluster embedding vectors into semantically coherent groups with automatic k selection, silhouette analysis, and custom labeling.

Description

embed-cluster groups high-dimensional embedding vectors into semantically coherent clusters using k-means++ initialization and configurable distance metrics. It is built for the characteristics of vectors produced by modern language model embedding APIs (768--3072 dimensions, cosine-similarity geometry) where generic clustering libraries require significant hand-tuning.

The package provides a complete clustering pipeline in a single function call: L2 normalization, k-means++ centroid initialization, iterative assignment and convergence, silhouette quality scoring, and optional automatic k selection. All algorithms are self-contained with zero mandatory runtime dependencies.

Key capabilities:

k-means++ clustering with smart centroid initialization for faster convergence and better separation.
Automatic k selection via silhouette analysis across a range of candidate k values.
Silhouette scoring at the per-item, per-cluster, and aggregate level.
Custom labeling through a caller-supplied sync or async labeling function.
Reproducible results using a seeded pseudo-random number generator.
L2 normalization built in, enabled by default, so cosine-distance clustering works out of the box.
Custom distance functions for specialized similarity metrics beyond Euclidean and cosine.

Installation

npm install embed-cluster

For optional dimensionality reduction, install the peer dependencies:

npm install ml-pca    # PCA-based dimensionality reduction
npm install umap-js   # UMAP-based dimensionality reduction

Both peer dependencies are optional and the core clustering API works without them.

Quick Start

import { cluster } from "embed-cluster";

// Prepare items with id, text, and embedding vector
const items = [
  { id: "doc-1", text: "Introduction to machine learning", embedding: [0.12, 0.85, 0.33, ...] },
  { id: "doc-2", text: "Deep learning architectures",      embedding: [0.14, 0.82, 0.31, ...] },
  { id: "doc-3", text: "Cooking Italian pasta",             embedding: [0.91, 0.05, 0.72, ...] },
  // ...more items
];

// Cluster with a fixed k
const result = await cluster(items, { k: 3, seed: 42 });

console.log(result.k);             // 3
console.log(result.clusters);      // Array of 3 Cluster objects
console.log(result.quality);       // { silhouette, inertia }
console.log(result.converged);     // true
console.log(result.durationMs);    // elapsed time in milliseconds

Automatic k selection

const result = await cluster(items, { autoK: true, maxK: 10 });
// k is chosen automatically to maximize silhouette score
console.log(result.k); // e.g. 4

Pre-configured clusterer

import { createClusterer } from "embed-cluster";

const clusterer = createClusterer({
  autoK: true,
  maxK: 15,
  normalize: true,
  seed: 42,
});

const result = await clusterer.cluster(items);
const optimal = await clusterer.findOptimalK(items);
const quality = clusterer.silhouetteScore(result);

Custom labeling

const result = await cluster(items, {
  k: 5,
  labeler: async (clusterItems, clusterId) => {
    // Call an LLM, run TF-IDF, or apply any labeling logic
    const texts = clusterItems.map((item) => item.text).join("\n");
    return `Topic ${clusterId}: ${texts.slice(0, 50)}`;
  },
});

for (const c of result.clusters) {
  console.log(c.label); // "Topic 0: Introduction to machine learning..."
}

Features

k-means++ initialization -- Selects initial centroids using D-squared weighted probabilistic sampling, producing better starting positions than random initialization and converging in fewer iterations.
Silhouette analysis -- Computes per-item silhouette coefficients measuring how well each point fits its assigned cluster versus the nearest alternative cluster. Returns per-cluster and overall mean scores in the range [-1, 1].
Automatic k selection -- Sweeps k from 2 to min(maxK, floor(sqrt(n))), scores each with silhouette analysis, and selects the k that maximizes the mean silhouette coefficient.
L2 normalization -- Normalizes embedding vectors to unit length before clustering (enabled by default), which is the correct preprocessing for cosine-distance clustering of embedding vectors.
Custom distance functions -- Supply any (a: number[], b: number[]) => number function to replace the default Euclidean distance. Built-in cosineDistance is exported for convenience.
Custom labeling -- Provide a sync or async LabelerFn to generate human-readable labels for each cluster. The function receives the cluster's items and cluster ID.
Seeded PRNG -- Deterministic pseudo-random number generation (mulberry32) ensures identical results across runs when a seed is provided.
Convergence control -- Configurable maximum iterations and tolerance threshold for centroid movement. The result reports whether the algorithm converged and how many iterations were needed.
Quality metrics -- Every result includes inertia (within-cluster sum of squared distances), silhouette scores, cohesion (average pairwise intra-cluster distance), and average distance to centroid per cluster.
Zero runtime dependencies -- All algorithms are self-contained TypeScript. No mandatory third-party libraries.
TypeScript-first -- Full type definitions with strict typing throughout. All interfaces and types are exported for consumer use.

API Reference

`cluster(items, options?)`

Cluster a set of EmbedItem objects using k-means++ and return a ClusterResult with silhouette scores.

function cluster(
  items: EmbedItem[],
  options?: ClusterOptions
): Promise<ClusterResult>;

Parameters:

Parameter	Type	Description
`items`	`EmbedItem[]`	Array of items to cluster. Must not be empty.
`options`	`ClusterOptions`	Clustering configuration. Provide `k` or set `autoK: true`.

Returns: Promise<ClusterResult>

Throws: ClusterError with code EMPTY_INPUT if items is empty, INVALID_OPTIONS if neither k nor autoK is provided, INVALID_K if k is invalid, INCONSISTENT_DIMENSIONS if embedding dimensions differ.

`createClusterer(config?)`

Create a pre-configured Clusterer instance. The returned object exposes cluster(), findOptimalK(), and silhouetteScore() methods that merge the bound config with per-call options.

function createClusterer(config?: ClusterOptions): Clusterer;

Parameters:

Parameter	Type	Description
`config`	`ClusterOptions`	Default configuration applied to all method calls. Per-call options override these defaults.

Returns: Clusterer

The Clusterer interface:

interface Clusterer {
  cluster(items: EmbedItem[], options?: ClusterOptions): Promise<ClusterResult>;
  findOptimalK(items: EmbedItem[], options?: Omit<ClusterOptions, "k">): Promise<OptimalKResult>;
  silhouetteScore(result: ClusterResult): SilhouetteResult;
}

`findOptimalK(items, options?)`

Try k from 2 to min(maxK, floor(sqrt(n))), run k-means for each, compute the silhouette score, and return the k that maximizes it.

function findOptimalK(
  items: EmbedItem[],
  options?: Omit<ClusterOptions, "k">
): OptimalKResult;

Parameters:

Parameter	Type	Description
`items`	`EmbedItem[]`	Array of items to evaluate.
`options`	`Omit<ClusterOptions, "k">`	Configuration (k is excluded since it is being searched).

Returns: OptimalKResult

interface OptimalKResult {
  k: number;                                                    // optimal k
  scores: Array<{ k: number; silhouette: number; inertia: number }>;  // score per candidate
  method: "silhouette" | "elbow" | "combined";                  // selection method used
}

`silhouetteScore(result, distFn?)`

Compute the silhouette score for an existing ClusterResult.

function silhouetteScore(
  result: ClusterResult,
  distFn?: (a: number[], b: number[]) => number
): SilhouetteResult;

Parameters:

Parameter	Type	Default	Description
`result`	`ClusterResult`	--	A clustering result to evaluate.
`distFn`	`(a: number[], b: number[]) => number`	`euclideanDistance`	Distance function for silhouette computation.

Returns: SilhouetteResult

interface SilhouetteResult {
  score: number;        // overall mean silhouette coefficient (-1 to 1)
  perCluster: number[]; // per-cluster mean silhouette
  perItem?: number[];   // per-item silhouette (optional, expensive)
}

Returns { score: 0, perCluster: [0, ...], perItem: [0, ...] } when fewer than 2 clusters exist.

`kMeans(items, k, options?)`

Low-level k-means implementation. Runs a single k-means pass with k-means++ initialization and returns a ClusterResult with placeholder silhouette scores (use silhouetteScore() separately to populate them).

function kMeans(
  items: EmbedItem[],
  k: number,
  options?: ClusterOptions
): ClusterResult;

Parameters:

Parameter	Type	Description
`items`	`EmbedItem[]`	Array of items to cluster.
`k`	`number`	Number of clusters. Must be a positive integer not exceeding `items.length`.
`options`	`ClusterOptions`	Clustering configuration.

Returns: ClusterResult

`kMeansPlusPlusInit(vectors, k, distFn, rand)`

k-means++ centroid initialization. Selects k initial centroids from the input vectors using D-squared weighted probabilistic selection.

function kMeansPlusPlusInit(
  vectors: number[][],
  k: number,
  distFn: (a: number[], b: number[]) => number,
  rand: () => number
): number[][];

Parameters:

Parameter	Type	Description
`vectors`	`number[][]`	Input data points.
`k`	`number`	Number of centroids to select.
`distFn`	`(a: number[], b: number[]) => number`	Distance function.
`rand`	`() => number`	Random number generator returning values in [0, 1).

Returns: number[][] -- Array of k centroid vectors.

`euclideanDistance(a, b)`

Compute the Euclidean distance between two vectors.

function euclideanDistance(a: number[], b: number[]): number;

`cosineDistance(a, b)`

Compute the cosine distance (1 - cosine similarity) between two vectors. Returns 1 for zero vectors.

function cosineDistance(a: number[], b: number[]): number;

`normalizeVector(vec)`

L2-normalize a single vector to unit length. Returns a copy; does not mutate the input. Returns a zero vector unchanged.

function normalizeVector(vec: number[]): number[];

`normalizeVectors(vecs)`

L2-normalize a batch of vectors independently.

function normalizeVectors(vecs: number[][]): number[][];

`ClusterError`

Error class with a typed code field for programmatic error handling.

class ClusterError extends Error {
  readonly name: "ClusterError";
  readonly code: ClusterErrorCode;
  constructor(message: string, code: ClusterErrorCode);
}

Types

All TypeScript interfaces are exported from the package entry point.

`EmbedItem`

interface EmbedItem {
  id: string;
  text: string;
  embedding: number[];
  metadata?: Record<string, unknown>;
}

An input item pairing text content with its embedding vector. The optional metadata field carries arbitrary data through the clustering pipeline.

`ClusterItem`

interface ClusterItem extends EmbedItem {
  clusterId: number;
  distanceToCentroid: number;
}

An EmbedItem after cluster assignment, annotated with the assigned cluster ID and its distance to the cluster centroid.

`Cluster`

interface Cluster {
  id: number;
  centroid: number[];
  items: ClusterItem[];
  label?: string;
  size: number;
  avgDistanceToCentroid: number;
  cohesion: number; // average intra-cluster pairwise distance
}

A single cluster containing its centroid, assigned items, optional label, and quality metrics.

`ClusterOptions`

interface ClusterOptions {
  k?: number;
  autoK?: boolean;
  maxK?: number;
  maxIterations?: number;
  tolerance?: number;
  seed?: number;
  normalize?: boolean;
  labeler?: LabelerFn;
  distanceFn?: (a: number[], b: number[]) => number;
}

`ClusterResult`

interface ClusterResult {
  clusters: Cluster[];
  quality: ClusterQuality;
  k: number;
  iterations: number;
  converged: boolean;
  durationMs: number;
}

`ClusterQuality`

interface ClusterQuality {
  silhouette: SilhouetteResult;
  inertia: number;
  daviesBouldin?: number;
  calinski?: number;
}

`SilhouetteResult`

interface SilhouetteResult {
  score: number;        // overall mean (-1 to 1)
  perCluster: number[]; // per-cluster mean
  perItem?: number[];   // per-item scores
}

`OptimalKResult`

interface OptimalKResult {
  k: number;
  scores: Array<{ k: number; silhouette: number; inertia: number }>;
  method: "silhouette" | "elbow" | "combined";
}

`VisualizationData`

interface VisualizationData {
  points: Array<{ id: string; x: number; y: number; clusterId: number }>;
  method: "pca" | "umap" | "tsne";
}

`LabelerFn`

type LabelerFn = (
  items: EmbedItem[],
  clusterId: number
) => Promise<string> | string;

`ClusterErrorCode`

type ClusterErrorCode =
  | "EMPTY_INPUT"
  | "INCONSISTENT_DIMENSIONS"
  | "DEGENERATE_INPUT"
  | "INVALID_K"
  | "INVALID_OPTIONS";

Configuration

Option	Type	Default	Description
`k`	`number`	--	Number of clusters. Required when `autoK` is `false`.
`autoK`	`boolean`	`false`	Automatically select the optimal k using silhouette analysis.
`maxK`	`number`	`min(10, floor(sqrt(n)))`	Maximum k to evaluate when `autoK` is `true`.
`maxIterations`	`number`	`100`	Maximum number of k-means iterations before stopping.
`tolerance`	`number`	`1e-4`	Convergence tolerance. The algorithm stops when the maximum centroid shift falls below this value.
`seed`	`number`	`42`	Seed for the pseudo-random number generator. Set to any integer for reproducible results.
`normalize`	`boolean`	`true`	L2-normalize all embedding vectors before clustering. Recommended for cosine-distance semantics.
`labeler`	`LabelerFn`	--	Custom function to generate a label for each cluster. Called once per cluster after assignment.
`distanceFn`	`(a: number[], b: number[]) => number`	`euclideanDistance`	Custom distance function. Use `cosineDistance` for angular separation or provide your own metric.

Error Handling

All errors thrown by the library are instances of ClusterError, which extends Error and carries a typed code field for programmatic handling.

import { cluster, ClusterError } from "embed-cluster";

try {
  await cluster([], { k: 3 });
} catch (err) {
  if (err instanceof ClusterError) {
    switch (err.code) {
      case "EMPTY_INPUT":
        console.error("No items provided");
        break;
      case "INVALID_K":
        console.error("k is out of range");
        break;
      case "INVALID_OPTIONS":
        console.error("Provide k or set autoK: true");
        break;
      case "INCONSISTENT_DIMENSIONS":
        console.error("All embeddings must have the same dimension");
        break;
      case "DEGENERATE_INPUT":
        console.error("Input data is degenerate");
        break;
    }
  }
}

Error Code	Condition
`EMPTY_INPUT`	The items array is empty.
`INCONSISTENT_DIMENSIONS`	Embedding vectors have different lengths.
`DEGENERATE_INPUT`	Input data is degenerate (e.g., all identical vectors).
`INVALID_K`	k is not a positive integer, or k exceeds the number of items.
`INVALID_OPTIONS`	Neither `k` nor `autoK: true` was provided.

Advanced Usage

Using cosine distance

import { cluster, cosineDistance } from "embed-cluster";

const result = await cluster(items, {
  k: 5,
  normalize: true,
  distanceFn: cosineDistance,
});

When normalize is true (the default), all vectors are L2-normalized before clustering. Combined with cosineDistance, this performs angular clustering -- the standard approach for embedding vectors from language models.

Evaluating an existing clustering

import { kMeans, silhouetteScore, cosineDistance } from "embed-cluster";

const result = kMeans(items, 4, { seed: 123, normalize: true });
const quality = silhouetteScore(result, cosineDistance);

console.log(quality.score);      // overall mean silhouette
console.log(quality.perCluster); // [0.72, 0.85, 0.61, 0.78]
console.log(quality.perItem);    // per-item scores (same length as items)

Comparing different k values

import { findOptimalK } from "embed-cluster";

const optimal = findOptimalK(items, {
  maxK: 15,
  normalize: true,
  seed: 42,
});

console.log(`Best k: ${optimal.k}`);
for (const entry of optimal.scores) {
  console.log(`  k=${entry.k}  silhouette=${entry.silhouette.toFixed(3)}  inertia=${entry.inertia.toFixed(1)}`);
}

Identifying outliers

Points with a negative per-item silhouette coefficient are poorly assigned and may be outliers:

const result = await cluster(items, { k: 5, seed: 42 });
const sil = silhouetteScore(result);

const outlierIndices: number[] = [];
if (sil.perItem) {
  sil.perItem.forEach((score, index) => {
    if (score < 0) {
      outlierIndices.push(index);
    }
  });
}
console.log(`Found ${outlierIndices.length} outlier(s)`);

Extracting cluster membership

const result = await cluster(items, { k: 4, seed: 42 });

for (const c of result.clusters) {
  console.log(`Cluster ${c.id} (${c.size} items, cohesion=${c.cohesion.toFixed(4)}):`);
  for (const item of c.items) {
    console.log(`  ${item.id}: ${item.text} (dist=${item.distanceToCentroid.toFixed(4)})`);
  }
}

Reusing configuration across calls

import { createClusterer } from "embed-cluster";

const clusterer = createClusterer({
  normalize: true,
  seed: 42,
  maxIterations: 200,
  tolerance: 1e-6,
});

// All calls inherit the bound configuration
const r1 = await clusterer.cluster(datasetA, { k: 3 });
const r2 = await clusterer.cluster(datasetB, { k: 5 });

// Per-call options override bound config
const r3 = await clusterer.cluster(datasetC, { autoK: true, maxK: 20 });

TypeScript

The package is written in TypeScript with strict mode enabled and ships type declarations alongside the compiled JavaScript. All interfaces, types, and the ClusterError class are exported from the package entry point.

import type {
  EmbedItem,
  ClusterItem,
  Cluster,
  ClusterOptions,
  ClusterResult,
  ClusterQuality,
  SilhouetteResult,
  OptimalKResult,
  VisualizationData,
  LabelerFn,
  Clusterer,
  ClusterErrorCode,
} from "embed-cluster";

The package targets ES2022 and compiles to CommonJS. It requires Node.js 18 or later.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
src		src
README.md		README.md
SPEC.md		SPEC.md
eslint.config.mjs		eslint.config.mjs
package-lock.json		package-lock.json
package.json		package.json
tasks.md		tasks.md
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

embed-cluster

Description

Installation

Quick Start

Automatic k selection

Pre-configured clusterer

Custom labeling

Features

API Reference

cluster(items, options?)

createClusterer(config?)

findOptimalK(items, options?)

silhouetteScore(result, distFn?)

kMeans(items, k, options?)

kMeansPlusPlusInit(vectors, k, distFn, rand)

euclideanDistance(a, b)

cosineDistance(a, b)

normalizeVector(vec)

normalizeVectors(vecs)

ClusterError

Types

EmbedItem

ClusterItem

Cluster

ClusterOptions

ClusterResult

ClusterQuality

SilhouetteResult

OptimalKResult

VisualizationData

LabelerFn

ClusterErrorCode

Configuration

Error Handling

Advanced Usage

Using cosine distance

Evaluating an existing clustering

Comparing different k values

Identifying outliers

Extracting cluster membership

Reusing configuration across calls

TypeScript

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`cluster(items, options?)`

`createClusterer(config?)`

`findOptimalK(items, options?)`

`silhouetteScore(result, distFn?)`

`kMeans(items, k, options?)`

`kMeansPlusPlusInit(vectors, k, distFn, rand)`

`euclideanDistance(a, b)`

`cosineDistance(a, b)`

`normalizeVector(vec)`

`normalizeVectors(vecs)`

`ClusterError`

`EmbedItem`

`ClusterItem`

`Cluster`

`ClusterOptions`

`ClusterResult`

`ClusterQuality`

`SilhouetteResult`

`OptimalKResult`

`VisualizationData`

`LabelerFn`

`ClusterErrorCode`

Packages