localvectordb.visualization.clustering module

Clustering utilities for document embeddings.

localvectordb.visualization._clustering.cluster_embeddings(embeddings: ndarray, n_clusters: int | None = None, method: str = 'kmeans', **kwargs) → ClusterResult

Cluster embeddings using k-means.

Parameters:

  • embeddings (np.ndarray) – (N, D) embeddings.

  • n_clusters (int, optional) – Number of clusters. If None, determined automatically via find_optimal_clusters().

  • method (str) – Clustering method (currently only "kmeans").

  • **kwargs – Forwarded to KMeans.

Return type:

ClusterResult

localvectordb.visualization._clustering.find_optimal_clusters(embeddings: ndarray, max_k: int | None = None) → int

Determine the optimal number of clusters via silhouette analysis.

Parameters:

  • embeddings (np.ndarray) – (N, D) embeddings.

  • max_k (int, optional) – Maximum number of clusters to try. Defaults to min(10, N - 1).

Returns:

Optimal cluster count (>= 2, or 1 if too few samples).

Return type:

int