starlight-cluster

starlight-cluster is a lightweight unsupervised machine learning package for the Starlight ecosystem. It provides clustering algorithms (starting with K-Means) built on top of vector representations from starlight-vec.

This package is designed to be simple, fast, and dependency-light, making it ideal for NLP experiments, document grouping, and semantic analysis.

Features

• K-Means clustering
• Works with TF-IDF vectors
• Automatic centroid updates
• Euclidean distance calculations
• Zero heavy ML dependencies
• ES Module compatible

Installation

npm install starlight-cluster

Requires:

• starlight-vec
• starlight-ml

Quick Example (JavaScript)

import { KMeans } from "starlight-cluster";

const vectors = [
  [1, 0, 0],
  [0.9, 0.1, 0],
  [0, 1, 0],
  [0, 0.9, 0.1]
];

const kmeans = new KMeans(2);
kmeans.fit(vectors);

console.log(kmeans.labels);
console.log(kmeans.centroids);

API Overview

new KMeans(k = 2, maxIterations = 100)

Creates a new K-Means clustering instance.

| Parameter | Description | | --------------- | ----------------------- | | k | Number of clusters | | maxIterations | Max training iterations |

fit(vectors: number[][])

Clusters the provided vectors.

• Automatically initializes centroids
• Stops early if centroids converge

predict(vector: number[]) → number

Returns the closest cluster index for a new vector.

distance(a, b)

Computes Euclidean distance between two vectors.

Typical Use Cases

• Document clustering
• Topic grouping
• Semantic similarity grouping
• Preprocessing for classifiers
• Unsupervised NLP pipelines

Design Philosophy

• No black boxes
• Readable math
• Educational + practical
• Built for Starlight, but usable anywhere

Related Packages

| Package | Purpose | | ---------------------- | ------------------------------ | | starlight-ml | Tokenization & NLP utilities | | starlight-vec | TF-IDF vectorization | | starlight-classifier | Supervised text classification |

License

MIT License © Dominex Macedon