Reranker

Modules concerning the rerankers used in Gen AI applications.

`CohereBedrockReranker(model_name, access_key_id=None, secret_access_key=None, region_name='us-east-1', fallback_to_original=True, context_config=None, **kwargs)`

Bases: BaseReranker

A reranker to rerank search results using AWS Bedrock's Cohere service.

Attributes:

Name	Type	Description
`context_config`	`ContextConfig \| None`	Configuration for rendering chunks as model input.

Examples:

Basic usage with explicit credentials:

reranker = CohereBedrockReranker(
    model_name="cohere.rerank-v3-5:0",
    access_key_id="your_access_key_id",
    secret_access_key="your_secret_access_key"
)

chunks = [Chunk(content="Python programming"), Chunk(content="ML algorithms")]
reranked = await reranker.rerank(chunks, "machine learning")

With explicit region:

reranker = CohereBedrockReranker(
    model_name="cohere.rerank-v3-5:0",
    access_key_id="your_key",
    secret_access_key="your_secret",
    region_name="us-west-2"
)

Graceful fallback on errors:

reranker = CohereBedrockReranker(
    model_name="cohere.rerank-v3-5:0",
    access_key_id="invalid_key",
    secret_access_key="invalid_secret"
)
result = await reranker.rerank(chunks, "query")

Note

Requires AWS credentials with Bedrock permissions. Currently supported model: 1. cohere.rerank-v3-5:0

See: https://docs.aws.amazon.com/bedrock/latest/userguide/models-supported.html

Initializes a new instance of the CohereBedrockReranker class.

Parameters:

Name	Type	Description	Default
`model_name`	`str`	The model to use for reranking. Currently supported: "cohere.rerank-v3-5:0"	required
`access_key_id`	`str \| None`	The AWS access key ID. Defaults to None, in which case the `AWS_ACCESS_KEY_ID` environment variable will be used.	`None`
`secret_access_key`	`str \| None`	The AWS secret access key. Defaults to None, in which case the `AWS_SECRET_ACCESS_KEY` environment variable will be used.	`None`
`region_name`	`str`	The AWS region name. Defaults to "us-east-1".	`'us-east-1'`
`fallback_to_original`	`bool`	Whether to fallback to the original chunks if the reranking fails. Defaults to True.	`True`
`context_config`	`ContextConfig \| None`	Context rendering configuration. Defaults to None, which renders only chunk content.	`None`
`**kwargs`	`Any`	Additional keyword arguments.	`{}`

`DMReranker(dm_invoker, top_n=10, relevance_question=None, hyperparameters=None, context_config=None)`

Bases: BaseReranker, DMComponent

[BETA] Rerank chunks using an ordered answer-bearing rubric normalized to [0, 1].

BaseDMInvoker and DMComponent are beta contracts intended only for quick local prototyping, not production use. Retries and timeouts belong to the invoker.

Examples:

With OPENROUTER_API_KEY set and gllm-inference[typesafe] installed:

from gllm_core.schema import Chunk
from gllm_retrieval.reranker import DMReranker

reranker = DMReranker.from_config(model_id="openrouter/typesafe/jev-1.13")
ranked = await reranker.rerank([Chunk(content="Paris is the capital of France.")], "Capital of France?")

Or inject a preconfigured invoker:

from gllm_core.schema import Chunk
from gllm_inference.dm_invoker.openrouter_dm_invoker import OpenRouterDMInvoker
from gllm_retrieval.reranker import DMReranker

invoker = OpenRouterDMInvoker(model_name="typesafe/jev-1.13")
reranker = DMReranker(dm_invoker=invoker, top_n=2)
ranked = await reranker.rerank([Chunk(content="Paris is the capital of France.")], "Capital of France?")

Attributes:

Name	Type	Description
`dm_invoker`	`BaseDMInvoker`	Decisions-model invoker used to score candidates.
`top_n`	`int`	Maximum number of returned chunks.
`relevance_question`	`DMQuestion`	Score rubric and document instructions.
`hyperparameters`	`dict[str, Any] \| None`	Optional per-invocation model settings.
`context_config`	`ContextConfig \| None`	Configuration for rendering chunks as model input.

Initialize with a provider-independent decisions-model invoker.

Parameters:

Name	Type	Description	Default
`dm_invoker`	`BaseDMInvoker`	Invoker used to score all candidates in one request.	required
`top_n`	`int`	Maximum number of results. Defaults to 10.	`10`
`relevance_question`	`DMQuestion \| None`	Score rubric with `{document}` instructions. Defaults to the built-in five-level rubric.	`None`
`hyperparameters`	`dict[str, Any] \| None`	Model options forwarded to the invoker. Defaults to None.	`None`
`context_config`	`ContextConfig \| None`	Context rendering configuration. Defaults to None, which renders only chunk content.	`None`

Raises:

Type	Description
`RetrievalValueError`	If top_n or the custom question is invalid.

`from_config(model_id, credentials=None, config=None, *, top_n=10, relevance_question=None, hyperparameters=None, context_config=None)` `classmethod`

Construct using the inference-owned provider factory.

Parameters:

Name	Type	Description	Default
`model_id`	`str \| ModelId`	Provider-qualified model identifier.	required
`credentials`	`str \| dict[str, Any] \| None`	Provider credentials. Defaults to None.	`None`
`config`	`dict[str, Any] \| None`	Provider settings, excluding credentials. Defaults to None.	`None`
`top_n`	`int`	Maximum number of results. Defaults to 10.	`10`
`relevance_question`	`DMQuestion \| None`	Custom score question. Defaults to None.	`None`
`hyperparameters`	`dict[str, Any] \| None`	Model options forwarded per request. Defaults to None.	`None`
`context_config`	`ContextConfig \| None`	Context rendering configuration. Defaults to None, which renders only chunk content.	`None`

Returns:

Name	Type	Description
`Self`	`Self`	Configured reranker.

`FlagEmbeddingReranker(model_path, use_fp16=True, context_config=None)`

Bases: BaseReranker

Reranks a list of chunks using a flag embedding.

Requires the FlagEmbedding package to be installed.

Examples:

reranker = FlagEmbeddingReranker(
    model_path="path/to/your/model",
    use_fp16=True
)

chunks = [Chunk(content="Python programming"), Chunk(content="ML algorithms")]
reranked = await reranker.rerank(chunks, "machine learning")

Attributes:

Name	Type	Description
`context_config`	`ContextConfig \| None`	Configuration for rendering chunks as model input.
`reranker`	`FlagReranker`	The flag embedding reranker model.

Initializes a new instance of the FlagEmbeddingReranker class.

Parameters:

Name	Type	Description	Default
`model_path`	`str`	A path containing the reranker model.	required
`use_fp16`	`bool`	Whether to reduce the model size to FP16 or not. Defaults to True.	`True`
`context_config`	`ContextConfig \| None`	Context rendering configuration. Defaults to None, which renders only chunk content.	`None`

`JinaAPIError`

Bases: RuntimeError

Deprecated base exception for Jina API errors.

Catch gllm_inference.exceptions.BaseInvokerError instead. Every error raised for a non-successful Jina API response is also a BaseInvokerError.

`JinaClientError`

Bases: JinaAPIError

Deprecated exception for any other non-successful Jina API status, mainly 4xx (non-retryable).

Catch gllm_inference.exceptions.ProviderInvalidArgsError, ProviderAuthError, ModelNotFoundError or ProviderRateLimitError instead.

`JinaReranker(model='jina-reranker-v3', api_key=None, top_n=None, timeout=30, fallback_to_original=False, context_config=None)`

Bases: BaseReranker

A class to rerank chunks by utilizing Jina AI's reranker API.

Examples:

Basic usage with API key from environment:

reranker = JinaReranker(
    model="jina-reranker-v3"
)

chunks = [Chunk(content="Python programming"), Chunk(content="ML algorithms")]
reranked = await reranker.rerank(chunks, "machine learning")

With explicit API key and custom parameters:

reranker = JinaReranker(
    model="jina-reranker-v3",
    api_key="jina_your_api_key_here",
    top_n=5,
    timeout=30
)

With fallback enabled:

reranker = JinaReranker(
    model="jina-reranker-v3",
    fallback_to_original=True
)
result = await reranker.rerank(chunks, "query")

With error handling:

reranker = JinaReranker()
try:
    reranked = await reranker.rerank(chunks, "machine learning")
except RuntimeError as e:
    logger.error(f"Reranking failed: {e}")
    # Handle error appropriately
finally:
    await reranker.close()

Attributes:

Name	Type	Description
`context_config`	`ContextConfig \| None`	Configuration for rendering chunks as model input.
`model`	`str`	The Jina reranker model to use (e.g., "jina-reranker-v3").
`top_n`	`int \| None`	Maximum number of top results to return. If None, returns all reranked results.
`timeout`	`int`	The timeout for API requests in seconds.
`fallback_to_original`	`bool`	Whether to fallback to the original chunks if the reranking fails.

Initializes a new instance of the JinaReranker class.

Parameters:

Name	Type	Description	Default
`model`	`str`	The Jina reranker model to use. Defaults to "jina-reranker-v3".	`'jina-reranker-v3'`
`api_key`	`str \| None`	The Jina API key. Defaults to None, in which case the `JINA_API_KEY` environment variable will be used.	`None`
`top_n`	`int \| None`	Maximum number of top results to return. If None, returns all. Defaults to None.	`None`
`timeout`	`int`	The timeout for API requests in seconds. Defaults to 30.	`30`
`fallback_to_original`	`bool`	Whether to fallback to the original chunks if the reranking fails. Defaults to False.	`False`
`context_config`	`ContextConfig \| None`	Context rendering configuration. Defaults to None, which renders only chunk content.	`None`

`close()` `async`

Closes the aiohttp ClientSession if it exists.

This method should be called when the reranker is no longer needed to properly clean up resources.

`JinaServerError`

Bases: JinaAPIError

Deprecated exception for 5xx server errors (retryable).

Catch gllm_inference.exceptions.ProviderInternalError or ProviderOverloadedError instead.

`SimilarityBasedReranker(embeddings, similarity_func=lambda x, y: 1 - cosine_distance(x, y), context_config=None)`

Bases: SimilarityReranker

Deprecated compatibility name for SimilarityReranker.

Attributes:

Name	Type	Description
`context_config`	`ContextConfig \| None`	Configuration for rendering chunks as model input.

Initialize the deprecated reranker name with the legacy constructor.

Parameters:

Name	Type	Description	Default
`embeddings`	`BaseEMInvoker`	The embedding model invoker.	required
`similarity_func`	`Callable[[Vector, Vector], float]`	A callback that receives one query and one chunk vector and returns a score. Defaults to cosine similarity.	`lambda x, y: 1 - cosine(x, y)`
`context_config`	`ContextConfig \| None`	Context rendering configuration. Defaults to None, which renders only chunk content.	`None`

Raises:

Type	Description
`RetrievalValueError`	If `similarity_func` is not callable.

`from_config(model_id, credentials=None, config=None, **kwargs)` `classmethod`

Build the legacy class through its original embeddings constructor argument.

Parameters:

Name	Type	Description	Default
`model_id`	`str \| ModelId`	The model ID.	required
`credentials`	`str \| dict[str, Any] \| None`	The credentials.	`None`
`config`	`dict[str, Any] \| None`	The config.	`None`
`**kwargs`	`Any`	The keyword arguments.	`{}`

Returns:

Name	Type	Description
`Self`	`Self`	The legacy class instance.

`SimilarityReranker(em_invoker, similarity_func=None, context_config=None)`

Bases: EMComponent, BaseReranker

A class to rerank chunks based on their similarity to a given query.

Examples:

reranker = SimilarityReranker(
    em_invoker=OpenAIEMInvoker(...),
    similarity_func=lambda x, y: custom_similarity(x, y)
)

chunks = [Chunk(content="Python programming"), Chunk(content="ML algorithms")]
reranked = await reranker.rerank(chunks, "machine learning")

Attributes:

Name	Type	Description
`context_config`	`ContextConfig \| None`	Configuration for rendering chunks as model input.
`em_invoker`	`BaseEMInvoker`	The embedding model invoker.
`similarity_func`	`Callable[[Vector, Vector], float] \| None`	An optional callback to calculate similarity.

Initializes the SimilarityReranker class with an embedding invoker and optional similarity function.

The parent classes are initialized explicitly because EMComponent does not delegate to the next class in the method resolution order.

Parameters:

Name	Type	Description	Default
`em_invoker`	`BaseEMInvoker`	The embedding model invoker used for queries and chunks.	required
`similarity_func`	`Callable[[Vector, Vector], float] \| None`	A callback that receives one query and one chunk vector and returns a score. Defaults to None, which uses the shared batch cosine implementation.	`None`
`context_config`	`ContextConfig \| None`	Context rendering configuration. Defaults to None, which renders only chunk content.	`None`

Raises:

Type	Description
`RetrievalValueError`	If `similarity_func` is not callable.

`TEIReranker(url, username=None, password=None, api_key=None, timeout=10, fallback_to_original=False, context_config=None)`

Bases: BaseReranker

A class to rerank chunks by utilizing a reranker model hosted on Text Embedding Inference (TEI).

Examples:

reranker = TEIReranker(
    url="https://api-inference.huggingface.co/models/your-model-id"
)

chunks = [Chunk(content="Python programming"), Chunk(content="ML algorithms")]
reranked = await reranker.rerank(chunks, "machine learning")

Attributes:

Name	Type	Description
`context_config`	`ContextConfig \| None`	Configuration for rendering chunks as model input.
`url`	`str`	The URL of the TEI endpoint that hosts the reranker model.
`auth_kwargs`	`dict[str, Any]`	Additional authentication arguments for the TEI reranker model.
`timeout`	`int`	The timeout for the TEI reranker model in seconds.
`fallback_to_original`	`bool`	Whether to fallback to the original chunks if the reranking fails.

Initializes a new instance of the TEIReranker class.

Parameters:

Name	Type	Description	Default
`url`	`str`	The URL of the TEI endpoint that hosts the reranker model.	required
`username`	`str \| None`	The username for the TEI reranker model. Defaults to None.	`None`
`password`	`str \| None`	The password for the TEI reranker model. Defaults to None.	`None`
`api_key`	`str \| None`	The API key for the TEI reranker model. Defaults to None.	`None`
`timeout`	`int`	The timeout for the TEI reranker model in seconds. Defaults to 10.	`10`
`fallback_to_original`	`bool`	Whether to fallback to the original chunks if the reranking fails. Defaults to False.	`False`
`context_config`	`ContextConfig \| None`	Context rendering configuration. Defaults to None, which renders only chunk content.	`None`

`close()` `async`

Closes the aiohttp ClientSession if it exists.

This method should be called when the reranker is no longer needed to properly clean up resources.

Reranker

CohereBedrockReranker(model_name, access_key_id=None, secret_access_key=None, region_name='us-east-1', fallback_to_original=True, context_config=None, **kwargs)

DMReranker(dm_invoker, top_n=10, relevance_question=None, hyperparameters=None, context_config=None)

from_config(model_id, credentials=None, config=None, *, top_n=10, relevance_question=None, hyperparameters=None, context_config=None) classmethod

FlagEmbeddingReranker(model_path, use_fp16=True, context_config=None)

JinaAPIError

JinaClientError

JinaReranker(model='jina-reranker-v3', api_key=None, top_n=None, timeout=30, fallback_to_original=False, context_config=None)

close() async

JinaServerError

SimilarityBasedReranker(embeddings, similarity_func=lambda x, y: 1 - cosine_distance(x, y), context_config=None)

from_config(model_id, credentials=None, config=None, **kwargs) classmethod

SimilarityReranker(em_invoker, similarity_func=None, context_config=None)

TEIReranker(url, username=None, password=None, api_key=None, timeout=10, fallback_to_original=False, context_config=None)

close() async

`CohereBedrockReranker(model_name, access_key_id=None, secret_access_key=None, region_name='us-east-1', fallback_to_original=True, context_config=None, **kwargs)`

`DMReranker(dm_invoker, top_n=10, relevance_question=None, hyperparameters=None, context_config=None)`

`from_config(model_id, credentials=None, config=None, *, top_n=10, relevance_question=None, hyperparameters=None, context_config=None)` `classmethod`

`FlagEmbeddingReranker(model_path, use_fp16=True, context_config=None)`

`JinaAPIError`

`JinaClientError`

`JinaReranker(model='jina-reranker-v3', api_key=None, top_n=None, timeout=30, fallback_to_original=False, context_config=None)`

`close()` `async`

`JinaServerError`

`SimilarityBasedReranker(embeddings, similarity_func=lambda x, y: 1 - cosine_distance(x, y), context_config=None)`

`from_config(model_id, credentials=None, config=None, **kwargs)` `classmethod`

`SimilarityReranker(em_invoker, similarity_func=None, context_config=None)`

`TEIReranker(url, username=None, password=None, api_key=None, timeout=10, fallback_to_original=False, context_config=None)`

`close()` `async`