---
title: "Reranker"
manual: "TYPO3 LLM Extension"
version: "0.35"
permalink: "https://docs.typo3.org/permalink/netresearch/nr-llm:api-reranker@0.35"
source: "Api/Reranker.rst"
modified: "2026-09-16T22:09:16+00:00"
---

# Reranker

-   **interface RerankerInterface**

    -   *Fully qualified name:* `\Netresearch\NrLlm\Service\Rerank\RerankerInterface`

    Neutral cross-encoder reranking protocol ([ADR-075: Neutral cross-encoder reranker protocol](https://docs.typo3.org/permalink/netresearch/nr-llm:adr-075@0.35)): 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](https://docs.typo3.org/permalink/netresearch/nr-llm:adr-053@0.35)); the caller decides how to degrade —
    nr_llm never silently falls back.

## Configuration

Extension configuration keys (`nr_llm`):

-   `rerankerEndpoint` — base URL of the cross-encoder sidecar, e.g.
    `http://reranker:8081`. Empty (default) disables reranking.
-   `rerankerTimeout` — request timeout in seconds (default 30; a CPU
    cross-encoder can be slow for a wide candidate pool).

See `Build/reranker/README.md` for running the sidecar.