localvectordb.reranking module

Reranking providers for LocalVectorDB.

This module provides cross-encoder and API-based reranking to improve search result quality by re-scoring candidates with more powerful models.

class localvectordb.reranking.Reranker(model: str, *, timeout: int = 90, max_retries: int = 3, **kwargs: Any)

Bases: ABC

Abstract base class for reranking providers.

__init__(model: str, *, timeout: int = 90, max_retries: int = 3, **kwargs: Any) → None
abstractmethod rerank(query: str, results: List[QueryResult], top_k: int | None = None) → List[QueryResult]

Rerank search results synchronously.

Parameters:

  • query (str) – The original query text.

  • results (List[QueryResult]) – Search results to rerank.

  • top_k (int, optional) – Maximum number of results to return. If None, returns all.

Returns:

Reranked results with updated scores, best first.

Return type:

List[QueryResult]

Notes

Every provider writes two metadata keys and leaves result.score holding an absolute [0, 1] relevance score – one that means the same thing regardless of the other candidates in the batch, so it survives score_threshold filtering and cross-query comparison:

  • metadata["original_score"] – the pre-rerank search score.

  • metadata["rerank_raw_score"] – the reranker model’s raw output before the provider’s [0, 1] mapping.

The mapping is provider-specific because the raw scores are:

  • Jina – the API returns a native [0, 1] relevance score; used as-is.

  • SentenceTransformers / HuggingFace – a cross-encoder logit, squashed with a logistic sigmoid. This is deliberately not a per-batch min-max: min-max is pool-relative (top always 1.0, bottom always 0.0) and would break score_threshold exactly as the pre-T1.1 hybrid fusion did.

  • Mock – word-overlap fraction, already in [0, 1].

async rerank_async(query: str, results: List[QueryResult], top_k: int | None = None) → List[QueryResult]

Rerank search results asynchronously. Default delegates to sync.

abstract property provider_name: str

Return the reranker provider name.

abstractmethod validate_model() → bool

Check if the model is available/valid.

class localvectordb.reranking.JinaReranker(model: str = 'jina-reranker-v2-base-multilingual', *, api_key: str | None = None, timeout: int = 90, max_retries: int = 3, **kwargs: Any)

Bases: Reranker

Jina AI reranker using the Jina Reranker API.

Parameters:

  • model (str) – The Jina reranker model. Default: “jina-reranker-v2-base-multilingual”

  • api_key (str, optional) – API key. Falls back to JINA_API_KEY env var.

  • timeout (int) – Request timeout in seconds.

  • max_retries (int) – Number of retry attempts.

__init__(model: str = 'jina-reranker-v2-base-multilingual', *, api_key: str | None = None, timeout: int = 90, max_retries: int = 3, **kwargs: Any) → None
property provider_name: str

Return the reranker provider name.

validate_model() → bool

Check if the model is available/valid.

rerank(query: str, results: List[QueryResult], top_k: int | None = None) → List[QueryResult]

Rerank search results synchronously.

Parameters:

  • query (str) – The original query text.

  • results (List[QueryResult]) – Search results to rerank.

  • top_k (int, optional) – Maximum number of results to return. If None, returns all.

Returns:

Reranked results with updated scores, best first.

Return type:

List[QueryResult]

Notes

Every provider writes two metadata keys and leaves result.score holding an absolute [0, 1] relevance score – one that means the same thing regardless of the other candidates in the batch, so it survives score_threshold filtering and cross-query comparison:

  • metadata["original_score"] – the pre-rerank search score.

  • metadata["rerank_raw_score"] – the reranker model’s raw output before the provider’s [0, 1] mapping.

The mapping is provider-specific because the raw scores are:

  • Jina – the API returns a native [0, 1] relevance score; used as-is.

  • SentenceTransformers / HuggingFace – a cross-encoder logit, squashed with a logistic sigmoid. This is deliberately not a per-batch min-max: min-max is pool-relative (top always 1.0, bottom always 0.0) and would break score_threshold exactly as the pre-T1.1 hybrid fusion did.

  • Mock – word-overlap fraction, already in [0, 1].

async rerank_async(query: str, results: List[QueryResult], top_k: int | None = None) → List[QueryResult]

Rerank search results asynchronously. Default delegates to sync.

class localvectordb.reranking.SentenceTransformersReranker(model: str = 'cross-encoder/ms-marco-MiniLM-L-6-v2', *, device: str | None = None, timeout: int = 90, max_retries: int = 3, **kwargs: Any)

Bases: Reranker

Cross-encoder reranker using sentence-transformers.

Parameters:

  • model (str) – The cross-encoder model name. Default: “cross-encoder/ms-marco-MiniLM-L-6-v2”

  • device (str, optional) – Device for inference (cpu/cuda/mps). Default: auto-detect.

__init__(model: str = 'cross-encoder/ms-marco-MiniLM-L-6-v2', *, device: str | None = None, timeout: int = 90, max_retries: int = 3, **kwargs: Any) → None
property provider_name: str

Return the reranker provider name.

validate_model() → bool

Check if the model is available/valid.

rerank(query: str, results: List[QueryResult], top_k: int | None = None) → List[QueryResult]

Rerank search results synchronously.

Parameters:

  • query (str) – The original query text.

  • results (List[QueryResult]) – Search results to rerank.

  • top_k (int, optional) – Maximum number of results to return. If None, returns all.

Returns:

Reranked results with updated scores, best first.

Return type:

List[QueryResult]

Notes

Every provider writes two metadata keys and leaves result.score holding an absolute [0, 1] relevance score – one that means the same thing regardless of the other candidates in the batch, so it survives score_threshold filtering and cross-query comparison:

  • metadata["original_score"] – the pre-rerank search score.

  • metadata["rerank_raw_score"] – the reranker model’s raw output before the provider’s [0, 1] mapping.

The mapping is provider-specific because the raw scores are:

  • Jina – the API returns a native [0, 1] relevance score; used as-is.

  • SentenceTransformers / HuggingFace – a cross-encoder logit, squashed with a logistic sigmoid. This is deliberately not a per-batch min-max: min-max is pool-relative (top always 1.0, bottom always 0.0) and would break score_threshold exactly as the pre-T1.1 hybrid fusion did.

  • Mock – word-overlap fraction, already in [0, 1].

class localvectordb.reranking.HuggingFaceReranker(model: str = 'BAAI/bge-reranker-v2-m3', *, api_key: str | None = None, base_url: str | None = None, timeout: int = 90, max_retries: int = 3, **kwargs: Any)

Bases: Reranker

HuggingFace Inference API reranker.

Parameters:

  • model (str) – HuggingFace model ID. Default: “BAAI/bge-reranker-v2-m3”

  • api_key (str, optional) – API key. Falls back to HF_TOKEN / HUGGINGFACE_TOKEN env vars.

  • base_url (str, optional) – API base URL. Default: https://api-inference.huggingface.co

__init__(model: str = 'BAAI/bge-reranker-v2-m3', *, api_key: str | None = None, base_url: str | None = None, timeout: int = 90, max_retries: int = 3, **kwargs: Any) → None
property provider_name: str

Return the reranker provider name.

validate_model() → bool

Check if the model is available/valid.

rerank(query: str, results: List[QueryResult], top_k: int | None = None) → List[QueryResult]

Rerank search results synchronously.

Parameters:

  • query (str) – The original query text.

  • results (List[QueryResult]) – Search results to rerank.

  • top_k (int, optional) – Maximum number of results to return. If None, returns all.

Returns:

Reranked results with updated scores, best first.

Return type:

List[QueryResult]

Notes

Every provider writes two metadata keys and leaves result.score holding an absolute [0, 1] relevance score – one that means the same thing regardless of the other candidates in the batch, so it survives score_threshold filtering and cross-query comparison:

  • metadata["original_score"] – the pre-rerank search score.

  • metadata["rerank_raw_score"] – the reranker model’s raw output before the provider’s [0, 1] mapping.

The mapping is provider-specific because the raw scores are:

  • Jina – the API returns a native [0, 1] relevance score; used as-is.

  • SentenceTransformers / HuggingFace – a cross-encoder logit, squashed with a logistic sigmoid. This is deliberately not a per-batch min-max: min-max is pool-relative (top always 1.0, bottom always 0.0) and would break score_threshold exactly as the pre-T1.1 hybrid fusion did.

  • Mock – word-overlap fraction, already in [0, 1].

class localvectordb.reranking.MockReranker(model: str = 'mock-reranker', *, timeout: int = 90, max_retries: int = 3, **kwargs: Any)

Bases: Reranker

Mock reranker for testing. Uses word-overlap scoring.

__init__(model: str = 'mock-reranker', *, timeout: int = 90, max_retries: int = 3, **kwargs: Any) → None
property provider_name: str

Return the reranker provider name.

validate_model() → bool

Check if the model is available/valid.

rerank(query: str, results: List[QueryResult], top_k: int | None = None) → List[QueryResult]

Rerank search results synchronously.

Parameters:

  • query (str) – The original query text.

  • results (List[QueryResult]) – Search results to rerank.

  • top_k (int, optional) – Maximum number of results to return. If None, returns all.

Returns:

Reranked results with updated scores, best first.

Return type:

List[QueryResult]

Notes

Every provider writes two metadata keys and leaves result.score holding an absolute [0, 1] relevance score – one that means the same thing regardless of the other candidates in the batch, so it survives score_threshold filtering and cross-query comparison:

  • metadata["original_score"] – the pre-rerank search score.

  • metadata["rerank_raw_score"] – the reranker model’s raw output before the provider’s [0, 1] mapping.

The mapping is provider-specific because the raw scores are:

  • Jina – the API returns a native [0, 1] relevance score; used as-is.

  • SentenceTransformers / HuggingFace – a cross-encoder logit, squashed with a logistic sigmoid. This is deliberately not a per-batch min-max: min-max is pool-relative (top always 1.0, bottom always 0.0) and would break score_threshold exactly as the pre-T1.1 hybrid fusion did.

  • Mock – word-overlap fraction, already in [0, 1].

class localvectordb.reranking.RerankerRegistry

Bases: object

Registry for reranker providers with plugin discovery.

classmethod register(name: str, provider_class: Type[Reranker]) → None

Register a new reranker provider.

classmethod get(name: str) → Type[Reranker]

Get a reranker provider by name.

classmethod create_reranker(provider_name: str, model: str | None = None, **kwargs: Any) → Reranker

Create a reranker instance.

classmethod list() → List[str]

List all registered reranker providers.

classmethod refresh_plugins() → None

Force re-discovery of plugins (useful for testing).

localvectordb.reranking.create_reranker(provider: str, model: str | None = None, **kwargs: Any) → Reranker

Create a reranker instance.

localvectordb.reranking.list_rerankers() → List[str]

List available reranker providers.