Repolode
Submit
TutteInstitute

TutteInstitute/evoc

A Python library for fast CPU clustering of large high-dimensional embedding vectors, with a scikit-learn style API.

View on GitHub
Stars
356
Forks
22
Open issues
12
Last commit
9 days ago

What is it?

EVōC (Embedding Vector Oriented Clustering) is a library for clustering large datasets of high-dimensional embedding vectors, such as CLIP vectors or outputs from sentence-transformers, OpenAI, or Cohere embedding models. It is designed to replace a UMAP plus HDBSCAN pipeline for this task, aiming for good clustering quality with fewer hyper-parameters and much less run time.

The library follows the scikit-learn API, so it can be used anywhere other sklearn clustering algorithms are used. Beyond a single set of labels, it produces multiple layers of clusters at different granularities, can extract a hierarchy across those layers, and flags duplicate or near-duplicate vectors. It also accepts int8 or binary quantized vectors directly.

EVōC is installable from PyPI and depends on numpy, scikit-learn, numba, tqdm and tbb. The project is an early beta, so its interfaces may change. Its cluster extraction is based on the PLSCAN method described in a 2025 arXiv paper.

Key features

  • 01Fast clustering of embedding vectors on CPU.
  • 02Produces multiple cluster layers from fine to coarse granularity.
  • 03Extracts a hierarchy of clusters across layers.
  • 04Detects duplicate and near-duplicate vectors.
  • 05Works directly with int8 and binary quantized embeddings.
  • 06Uses a scikit-learn compatible fit_predict interface.

Use cases

  • Grouping CLIP or sentence embeddings into topics for large text or image collections.
  • Building layered topic maps that zoom from broad to fine-grained topics.
  • Finding duplicate or near-duplicate items in an embedding corpus.

Quick start

  1. 1

    Install EVōC from PyPI with pip

    pip install evoc
  2. 2

    Import EVōC and cluster your embedding vectors with fit_predict

    import evoc clusterer = evoc.EVoC() cluster_labels = clusterer.fit_predict(data)

Things to know

  • The library is in early beta, so things can and will break.
  • The algorithm is not published yet, so the README asks you to cite the PLSCAN paper instead.

Topics

#clustering#embeddings#vector-search#scikit-learn#topic-modeling#machine-learning

FAQ

What is evoc?
A Python library for fast CPU clustering of large high-dimensional embedding vectors, with a scikit-learn style API. EVōC (Embedding Vector Oriented Clustering) is a library for clustering large datasets of high-dimensional embedding vectors, such as CLIP vectors or outputs from sentence-transformers, OpenAI, or Cohere embedding models. It is designed to replace a UMAP plus HDBSCAN pipeline for this task, aiming for good clustering quality with fewer hyper-parameters and much less run time.
Is evoc free to use? What license does it have?
evoc is open source under the BSD-2-Clause license. Check the license terms before using it in commercial products.
Is evoc still maintained?
Actively maintained. The last commit to evoc was on Oct 29, 2026.
What can I use evoc for?
Grouping CLIP or sentence embeddings into topics for large text or image collections. Building layered topic maps that zoom from broad to fine-grained topics. Finding duplicate or near-duplicate items in an embedding corpus.
How do I install evoc?
Install EVōC from PyPI with pip: pip install evoc Import EVōC and cluster your embedding vectors with fit_predict: import evoc clusterer = evoc.EVoC() cluster_labels = clusterer.fit_predict(data)
Where can I get evoc?
The source code and installation instructions are on GitHub: https://github.com/TutteInstitute/evoc

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects