Reranking
==========

Overview
--------

The ``zvec_db.rerankers`` sub-package provides algorithms to combine and rerank search results from multiple sources.

**Available classes:**

* :class:`RerankFunction` - Abstract base class for all rerankers
* :class:`FusionRerankerBase` - Base class for fusion-based rerankers
* :class:`RrfReranker` - Reciprocal Rank Fusion (RRF)
* :class:`WeightedReranker` - Weighted fusion with normalization and metric conversion
* :class:`MultiFieldWeightedReranker` - Field-based weighting (title, content, tags)
* :class:`Normalize` - Score normalization utility
* :class:`PipelineReranker` - Pipeline to chain multiple rerankers
* :class:`BaseCrossEncoderReranker` - Base class for Cross-Encoder rerankers
* :class:`SentenceTransformerReranker` - Local Cross-Encoder with Sentence Transformers
* :class:`ClassificationReranker` - Cross-Encoder with multi-class classification
* :class:`OpenAIReranker` - Cross-Encoder via OpenAI-compatible API
* :class:`OpenAIEncoderReranker` - Encoder-based reranker via API
* :class:`OpenAIDecoderReranker` - Decoder-based reranker via API (chat completions)

**Understanding the ``metrics`` parameter:**

The ``metrics`` parameter controls how scores are converted from distance to similarity:

* ``metrics=MetricType.COSINE`` - Apply cosine conversion ``(2 - score) / 2`` to all sources
* ``metrics={"dense": COSINE, "bm25": None}`` - Per-source metrics (None = no conversion)
* ``metrics=None`` with ``schema=...`` - Auto-detect from collection schema
* ``metrics=None`` without schema - No conversion (scores assumed to be similarities)

**Default:** ``metrics=MetricType.COSINE`` for compatibility with zvec/Qdrant cosine distances.
For BM25-only, use ``metrics=None``.

**Understanding the ``normalize`` parameter:**

The ``normalize`` parameter controls score normalization after metric conversion:

* ``normalize=True`` (default) - Smart default: COSINE → no-op, others → ``"bayes"``
* ``normalize="bayes"`` - Bayesian sigmoid calibration (robust to outliers)
* ``normalize="minmax"`` - Min-max scaling: ``(x - min) / (max - min)``
* ``normalize="percentile"`` - Rank-based normalization (very robust to outliers)
* ``normalize="cosine"`` - No-op (identity). COSINE scores already in [0, 1]
* ``normalize={"source1": "bayes", "source2": "cosine"}`` - Per-source configuration
* ``normalize=None`` or ``False`` - No normalization (scores after conversion only)

Base Classes
------------

RerankFunction
~~~~~~~~~~~~~~

.. autoclass:: zvec_db.rerankers.RerankFunction
   :members:
   :undoc-members:
   :inherited-members:

FusionRerankerBase
~~~~~~~~~~~~~~~~~~

.. autoclass:: zvec_db.rerankers.FusionRerankerBase
   :members:
   :undoc-members:
   :inherited-members:

Fusion Rerankers
----------------

RrfReranker
~~~~~~~~~~~

.. autoclass:: zvec_db.rerankers.RrfReranker
   :members:
   :undoc-members:
   :inherited-members:

WeightedReranker
~~~~~~~~~~~~~~~~

.. autoclass:: zvec_db.rerankers.WeightedReranker
   :members:
   :undoc-members:
   :inherited-members:

MultiFieldWeightedReranker
~~~~~~~~~~~~~~~~~~~~~~~~~~

.. autoclass:: zvec_db.rerankers.MultiFieldWeightedReranker
   :members:
   :undoc-members:
   :inherited-members:

Cross-Encoder Rerankers
-----------------------

BaseCrossEncoderReranker
~~~~~~~~~~~~~~~~~~~~~~~~

.. autoclass:: zvec_db.rerankers.BaseCrossEncoderReranker
   :members:
   :undoc-members:
   :inherited-members:

SentenceTransformerReranker
~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. autoclass:: zvec_db.rerankers.SentenceTransformerReranker
   :members:
   :undoc-members:
   :inherited-members:

ClassificationReranker
~~~~~~~~~~~~~~~~~~~~~~

.. autoclass:: zvec_db.rerankers.ClassificationReranker
   :members:
   :undoc-members:
   :inherited-members:

OpenAIReranker
~~~~~~~~~~~~~~

.. autoclass:: zvec_db.rerankers.OpenAIReranker
   :members:
   :undoc-members:
   :inherited-members:

OpenAIEncoderReranker
~~~~~~~~~~~~~~~~~~~~~

.. autoclass:: zvec_db.rerankers.OpenAIEncoderReranker
   :members:
   :undoc-members:
   :inherited-members:

OpenAIDecoderReranker
~~~~~~~~~~~~~~~~~~~~~

.. autoclass:: zvec_db.rerankers.OpenAIDecoderReranker
   :members:
   :undoc-members:
   :inherited-members:

Utilities
---------

Normalize
~~~~~~~~~

.. autoclass:: zvec_db.rerankers.Normalize
   :members:
   :undoc-members:
   :inherited-members:

PipelineReranker
~~~~~~~~~~~~~~~~

.. autoclass:: zvec_db.rerankers.PipelineReranker
   :members:
   :undoc-members:
   :inherited-members: