zvec-db Documentation
=====================

Welcome to the **zvec-db** documentation!

.. image:: https://img.shields.io/pypi/v/zvec-db.svg
   :alt: Version
   :target: https://pypi.org/project/zvec-db/

.. image:: https://img.shields.io/badge/python-3.12+-blue.svg
   :alt: Python
   :target: https://www.python.org/downloads/

.. image:: https://img.shields.io/badge/license-MIT-blue.svg
   :alt: License
   :target: https://github.com/ccdv-ai/zvec-db/blob/main/LICENSE

**zvec-db** is a utility suite for sparse vectorization and document reranking, designed to work with `zvec <https://github.com/ccdv-ai/zvec>`_.

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   installation
   scoring
   reranker
   guide
   api

Quick Start
-----------

Sparse Embedding
~~~~~~~~~~~~~~~~

.. code-block:: python

   from zvec_db.embedders import BM25Embedder

   # Training
   embedder = BM25Embedder(max_features=4096)
   embedder.fit(documents)

   # Embedding
   vector = embedder.embed("search query")
   print(vector)  # {42: 0.523, 108: 0.312, ...}

Reranking
~~~~~~~~~~

.. code-block:: python

   from zvec_db.rerankers import RrfReranker
   from zvec.model.doc import Doc

   reranker = RrfReranker(topn=10)
   results = reranker.rerank({
       "bm25": bm25_docs,
       "dense": dense_docs
   })

Features
--------

* **6 Sparse Embedders**: Count, BM25, BM25L, BM25+, DisMax, TF-IDF
* **3 Rerankers**: RRF, Weighted, MultiField
* **Normalization**: Standard and Bayesian
* **zvec-compatible**: Sparse vector formats compatible with zvec
* **Tests**: 100+ tests with ~95% coverage

.. note::
   For more examples and guides, see the :doc:`installation` and :doc:`scoring` and :doc:`reranker` sections.

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`