evoc 0.1.3
Embedding Vector Oriented Clustering
License: BSD License
Requires Python: >=3.10
Keywords: embedding vector, vector database, topic modelling, cluster, clustering

.. image:: doc/evoc_logo.png
  :width: 600
  :align: center
  :alt: EVōC Logo

====
EVōC
====

EVōC (pronounced as "evoke") is Embedding Vector Oriented Clustering.
EVōC is a library for fast and flexible clustering of large datasets of high dimensional embedding vectors. 
If you have CLIP-vectors, outputs from sentence-transformers, or openAI, or Cohere embed, and you want
to quickly get good clusters out this is the library for you. EVōC takes all the good parts of the 
combination of UMAP + HDBSCAN for embedding clustering, improves upon them, and removes all 
the time-consuming parts. By specializing directly to embedding vectors we can get good
quality clustering with fewer hyper-parameters to tune and in a fraction of the time.

EVōC is the library to use if you want:

 * Fast clustering of embedding vectors on CPU
 * Multi-granularity clustering, and automatic selection of the number of clusters
 * Clustering of int8 or binary quantized embedding vectors that works out-of-the-box

 As of now this is very much an early beta version of the library. Things can and will break right now.
 We would welcome feedback, use cases and feature suggestions however.

-----------
Basic Usage
-----------

EVōC follows the scikit-learn API, so it should be familiar to most users. You can use EVōC wherever
you might have previously been using other sklearn clustering algorithms. Here is a simple example

.. code-block:: python

    import evoc
    from sklearn.datasets import make_blobs

    data, _ = make_blobs(n_samples=100_000, n_features=1024, centers=100)

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

Some more unique features include the generation of multiple layers of cluster granularity,
the ability to extract a hierarchy of clusters across those layers, and automatic duplicate 
(or very near duplicate) detection.

.. code-block:: python

    import evoc
    from sklearn.datasets import make_blobs

    data, _ = make_blobs(n_samples=100_000, n_features=1024, centers=100)

    clusterer = evoc.EVoC()
    cluster_labels = clusterer.fit_predict(data)
    cluster_layers = clusterer.cluster_layers_
    hierarchy = clusterer.cluster_tree_
    potential_duplicates = clusterer.duplicates_

The cluster layers are a list of cluster label vectors with the first being the finest grained
and later layers being coarser grained. This is ideal for layered topic modelling and use with
`DataMapPlot <https://github.com/TutteInstitute/datamapplot>`_. See 
`this data map <https://lmcinnes.github.io/datamapplot_examples/ArXiv_data_map_example.html>`_
for an example of using these layered clusters in topic modelling (zoom in to access finer 
grained topics).

------------
Installation
------------

EVōC has a small set of dependencies:

 * numpy
 * scikit-learn
 * numba
 * tqdm
 * tbb

At some point in the near future ... you can install EVōC from PyPI using pip:

.. code-block:: bash

    pip install evoc

For now install the latest version of EVōC from source you can do so by cloning the repository and running:

.. code-block:: bash

    git clone https://github.com/TutteInstitute/evoc
    cd evoc
    pip install .

-------
License
-------

EVōC is BSD (2-clause) licensed. See the LICENSE file for details.

------------
Contributing
------------

Contributions are more than welcome! If you have ideas for features of projects please get in touch. Everything from
code to notebooks to examples and documentation are all *equally valuable* so please don't feel you can't contribute.
To contribute please `fork the project <https://github.com/TutteInstitute/evoc/issues#fork-destination-box>`_ make your
changes and submit a pull request. We will do our best to work through any issues with you and get your code merged in.