Reranker 

interface RerankerInterface

Fully qualified name

\Netresearch\NrLlm\Service\Rerank\RerankerInterface

Neutral cross-encoder reranking protocol (ADR-075: Neutral cross-encoder reranker protocol): scores retrieval candidates against a query. Candidates go in as plain id/text shapes and scores come back as plain id/score shapes — no consumer DTOs cross the boundary. Consumers own DTO mapping, the ordering merge, the degradation policy on failure, and any score-threshold gate.

The container service is factory-built from the extension configuration: an empty rerankerEndpoint resolves to NullReranker, a configured endpoint to HttpReranker.

rerank ( string $query, array $candidates) : array

Score each (query, candidate text) pair. Returns one entry per scored candidate in input order; an entry the backend failed to score may be omitted — merge by id.

param string $query

The query the candidates are scored against

param array $candidates

list<array{id: string, text: string}>

throws

RerankerException when the reranker backend is unreachable or answers outside the protocol

Returns

list<array{id: string, score: float}>

class HttpReranker

Fully qualified name

\Netresearch\NrLlm\Service\Rerank\HttpReranker

Speaks the cross-encoder sidecar contract (Build/reranker): POST {endpoint}/rerank with {"query", "documents"}, scores returned in input order. Pools above the sidecar's batch cap (128 documents) are split into sequential requests. The score scale is model-specific (default BAAI/bge-reranker-v2-m3).

class NullReranker

Fully qualified name

\Netresearch\NrLlm\Service\Rerank\NullReranker

Selected when no sidecar endpoint is configured. Returns one entry per candidate in input order with a uniform score of 0.0 — no ranking signal, shape-identical to HttpReranker.

class RerankerException

Fully qualified name

\Netresearch\NrLlm\Service\Rerank\Exception\RerankerException

Typed failure of the reranker backend: unreachable endpoint (code 1784750001), non-200 status (1784750002), invalid JSON (1784750003), or a response missing the scores array (1784750004). Implements NrLlmExceptionInterface (ADR-053); the caller decides how to degrade — nr_llm never silently falls back.