Rerank Module¶

The Rerank module provides document reranking functionality with support for two provider modes: OpenAI-compatible and DashScope.

The module uses a strategy pattern with separate handlers for each mode, ensuring a unified interface while hiding provider-specific differences.

Supported Modes¶

openai: OpenAI-compatible standard rerank API (e.g., Jina AI) (default)
dashscope: Alibaba Cloud DashScope rerank API

All modes return the same RerankResult format, hiding provider differences from users.

Unified Result Format¶

Regardless of the backend provider, all modes return a consistent RerankResult:

Results: List of tuples (index, score) or (index, score, document)
Sorting: Always sorted by score in descending order (higher is better)
Index Mapping: Original document indices are preserved correctly
Usage: Unified Usage object with token statistics

The internal transformation process handles: - Request format adaptation (parameter name mapping, structure wrapping) - Response parsing (extracting from provider-specific structures) - Result normalization (sorting, filtering, formatting)

See Rerank Modes Comparison for detailed comparison of internal data formats.

Rerank API client.

Provides a simple, function-like API for document reranking with unified usage tracking. Supports multiple provider modes: OpenAI-compatible and DashScope. Supports both sync and async operations with connection pooling.

class lexilux.rerank.RerankResult(*, results, usage, raw=None)[source]¶

Bases: ResultBase

Rerank result.

The results field contains: - Ranked (List[Tuple[int, float]]) when include_docs=False - RankedWithDoc (List[Tuple[int, float, str]]) when include_docs=True

Results are sorted by score in descending order.

results¶: Ranked results (with or without documents).

usage¶: Usage statistics.

raw¶: Raw API response.

Examples

>>> result = rerank("python http", ["urllib", "requests", "httpx"])
>>> ranked = result.results  # List[Tuple[int, float]]
>>> print(ranked[0])  # (1, 0.95) - (index, score)

>>> result = rerank("python http", ["urllib", "requests"], include_docs=True)
>>> ranked = result.results  # List[Tuple[int, float, str]]
>>> print(ranked[0])  # (1, 0.95, "requests") - (index, score, doc)

__init__(*, results, usage, raw=None)[source]¶

Initialize RerankResult.

Parameters:

results (list[tuple[int, float]] | list[tuple[int, float, str]]) – Ranked results.
usage (Usage) – Usage statistics.
raw (dict[str, Any] | None) – Raw API response.

__repr__()[source]¶

Return string representation.

class lexilux.rerank.RerankModeHandler(base_url, api_key, headers, timeout_s, proxies=None, session=None)[source]¶

Bases: ABC

Abstract base class for rerank mode handlers.

Each handler implements provider-specific request/response format conversion while maintaining a unified interface. Supports connection pooling via shared session.

__init__(base_url, api_key, headers, timeout_s, proxies=None, session=None)[source]¶

Initialize mode handler.

Parameters:

base_url (str) – Base URL for the API.
api_key (str | None) – API key for authentication.
headers (dict[str, str]) – HTTP headers.
timeout_s (float) – Request timeout in seconds.
proxies (dict[str, str] | None) – Optional proxy configuration dict.
session (Session | None) – Optional requests.Session for connection pooling.

abstractmethod build_request(query, docs, model, top_k, include_docs, extra)[source]¶

Build HTTP request for this mode.

Parameters:

query (str) – Query string.
docs (Sequence[str]) – Document strings to rerank.
model (str) – Model identifier.
top_k (int | None) – Number of top results to return.
include_docs (bool) – Whether to include documents in response.
extra (dict[str, Any] | None) – Additional parameters.

Returns:

Tuple of (url, payload).

Return type:

tuple[str, dict[str, Any]]

abstractmethod parse_response(response_data, docs, include_docs, top_k)[source]¶

Parse API response for this mode.

Parameters:

response_data (dict[str, Any]) – Raw API response JSON.
docs (Sequence[str]) – Original document list (for index mapping).
include_docs (bool) – Whether documents were requested.
top_k (int | None) – Requested top_k limit.

Returns:

Tuple of (parsed_results, usage). parsed_results: List of (index, score, optional_doc) tuples.

Return type:

tuple[list[tuple[int, float, str | None]], Usage]

make_request(url, payload)[source]¶

Make HTTP request using connection pooling.

Parameters:

url (str) – Request URL.
payload (dict[str, Any]) – Request payload.

Returns:

Response JSON data.

Raises:

requests.RequestException – On network or HTTP errors.

Return type:

dict[str, Any]

async amake_request(url, payload, async_client)[source]¶

Make async HTTP request.

Parameters:

url (str) – Request URL.
payload (Json) – Request payload.
async_client (httpx.AsyncClient) – httpx.AsyncClient instance.

Returns:

Response JSON data.

Raises:

httpx.HTTPError – On network or HTTP errors.

Return type:

Json

class lexilux.rerank.OpenAICompatibleHandler(base_url, api_key, headers, timeout_s, proxies=None, session=None)[source]¶

Bases: RerankModeHandler

Handler for OpenAI-compatible rerank API.

Standard OpenAI rerank format: - Endpoint: POST {base_url}/rerank - Request: {“model”: “…”, “query”: “…”, “documents”: […], “top_n”: …, “return_documents”: …} - Response: {“results”: [{“index”: 0, “relevance_score”: 0.95, “document”: {“text”: “…”}}, …], “usage”: {…}}

build_request(query, docs, model, top_k, include_docs, extra)[source]¶

Build OpenAI-compatible request.

parse_response(response_data, docs, include_docs, top_k)[source]¶

Parse OpenAI-compatible response.

class lexilux.rerank.DashScopeHandler(base_url, api_key, headers, timeout_s, proxies=None, session=None)[source]¶

Bases: RerankModeHandler

Handler for Alibaba Cloud DashScope rerank API.

DashScope rerank format: - Endpoint: POST {base_url}/text-rerank/text-rerank (full path in base_url) - Request: {“model”: “…”, “input”: {“query”: “…”, “documents”: […]}, “parameters”: {…}} - Response: {“output”: {“results”: […]}, “usage”: {…}}

build_request(query, docs, model, top_k, include_docs, extra)[source]¶

Build DashScope request.

parse_response(response_data, docs, include_docs, top_k)[source]¶

Parse DashScope response.

class lexilux.rerank.Rerank(*, base_url, api_key=None, model=None, mode='openai', timeout_s=60.0, headers=None, proxies=None, pool_size=10)[source]¶

Bases: AsyncClientMixin

Rerank API client with connection pooling.

Provides a simple, function-like API for document reranking. Supports two modes: - “openai”: OpenAI-compatible standard API (default) - “dashscope”: Alibaba Cloud DashScope API

Uses connection pooling for improved performance in high-throughput scenarios.

Examples

>>> # OpenAI-compatible mode (default)
>>> rerank = Rerank(
...     base_url="https://api.example.com/v1",
...     api_key="key",
...     model="rerank-model",
...     mode="openai"
... )
>>> result = rerank("python http", ["urllib", "requests", "httpx"])
>>> ranked = result.results  # List[Tuple[int, float]]

>>> # DashScope mode
>>> rerank = Rerank(
...     base_url="https://dashscope.aliyuncs.com/api/v1/services/rerank/text-rerank/text-rerank",
...     api_key="key",
...     model="qwen3-rerank",
...     mode="dashscope"
... )
>>> result = rerank("python http", ["urllib", "requests", "httpx"])

>>> # Context manager for proper resource cleanup
>>> with Rerank(base_url="...", api_key="key") as rerank:
...     result = rerank("query", ["doc1", "doc2"])

__init__(*, base_url, api_key=None, model=None, mode='openai', timeout_s=60.0, headers=None, proxies=None, pool_size=10)[source]¶

Initialize Rerank client.

Parameters:

base_url (str) – Base URL for the API (e.g., “https://api.example.com/v1”).
api_key (str | None) – API key for authentication (optional if provided in headers).
model (str | None) – Default model to use (can be overridden in __call__).
mode (str) – Rerank mode. “openai” for OpenAI-compatible, “dashscope” for DashScope. Default is “openai”.
timeout_s (float) – Request timeout in seconds.
headers (dict[str, str] | None) – Additional headers to include in requests.
proxies (dict[str, str] | None) – Optional proxy configuration dict (e.g., {“http”: “http://proxy:port”}). If None, uses environment variables (HTTP_PROXY, HTTPS_PROXY). To disable proxies, pass {}.
pool_size (int) – Connection pool size for HTTP adapter (default: 10, max: 100).

Raises:

ValueError – If mode is not supported or pool_size is out of range.

__call__(query, docs, *, model=None, top_k=None, include_docs=False, extra=None, return_raw=False, mode=None)[source]¶

Make a rerank request.

Parameters:

query (str) – Query string.
docs (Sequence[str]) – Sequence of document strings to rerank.
model (str | None) – Model to use (overrides default).
top_k (int | None) – Number of top results to return (optional).
include_docs (bool) – Whether to include documents in results.
extra (dict[str, Any] | None) – Additional parameters to include in the request.
return_raw (bool) – Whether to include full raw response.
mode (str | None) – Override mode for this call (“openai” or “dashscope”).

Returns:

RerankResult with ranked results and usage.

Raises:

requests.RequestException – On network or HTTP errors.
ValueError – On invalid input or response format.

Return type:

RerankResult

async acall(query, docs, *, model=None, top_k=None, include_docs=False, extra=None, return_raw=False, mode=None)[source]¶

Make an async rerank request.

This is the async version of __call__(). All parameters and behavior are identical to the sync version.

Parameters:

query (str) – Query string.
docs (Sequence[str]) – Sequence of document strings to rerank.
model (str | None) – Model to use (overrides default).
top_k (int | None) – Number of top results to return (optional).
include_docs (bool) – Whether to include documents in results.
extra (dict[str, Any] | None) – Additional parameters to include in the request.
return_raw (bool) – Whether to include full raw response.
mode (str | None) – Override mode for this call.

Returns:

RerankResult with ranked results and usage.

Return type:

RerankResult

Examples

>>> result = await rerank.acall("python http", ["urllib", "requests"])
>>> ranked = result.results

close()[source]¶

Close the sync session and release resources.

Should be called when done with the client, or use context manager.

Rerank Module¶

Supported Modes¶

Unified Result Format¶

See Also¶