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

``bash
npm install starlight-cluster
`

> Requires:
>
> * starlight-vec
> * starlight-ml

---

Quick Example (JavaScript)

`js
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

$3

Creates a new K-Means clustering instance.

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

---

$3

Clusters the provided vectors.

* Automatically initializes centroids
* Stops early if centroids converge

---

$3

Returns the closest cluster index for a new vector.

---

$3

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