Package com.tnsai.intelligence.rag

Interface Reranker

public interface Reranker
Service provider interface for query-aware document reranking.

Providers advertise the model identifiers they support through supports(String) and are discovered with ServiceLoader. TnsAI deliberately does not bundle or impersonate a cross-encoder model: provider modules own model inference, credentials, transport, and lifecycle management.

Implementations may reorder or remove candidates, but must not introduce documents that were not present in Reranker.Request.documents(). The runtime validates that invariant and applies Reranker.Request.topN() after the provider returns.

Thread safety

Implementations must be thread-safe. A single provider instance is shared by every agent thread for the JVM's lifetime: the retrieval SPI that owns reranking is memoised in an AtomicReference by RetrievalSpi.find(), and it resolves the provider from a registry built once from ServiceLoader. Providers must therefore keep no per-request mutable state in fields; per-call state belongs in locals derived from the Reranker.Request.

Since:
0.13.0

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static final record 
    Reranker.Request
    Immutable input passed to a Reranker provider.

  • Method Summary

    Modifier and Type
    Method
    Description
    static Reranker
    noOp()
    Returns the null-object reranker: it advertises no model and returns candidates in the order it received them.
    List<RetrievedDocument>
    rerank(Reranker.Request request)
    Reranks retrieved candidates for the original user query.
    boolean
    supports(String model)
    Returns whether this provider supports the exact model identifier.

  • Method Details

    • noOp

      static Reranker noOp()
      Returns the null-object reranker: it advertises no model and returns candidates in the order it received them.

      Lets a call site hold a Reranker whether or not @Search.rerank is enabled, so the disabled case needs no null sentinel. supports(String) answers false for every identifier, so the no-op can never win provider resolution and mask a genuinely missing provider.

      Returns:
      the shared no-op instance (never null)
      Since:
      0.13.0

    • supports

      boolean supports(String model)
      Returns whether this provider supports the exact model identifier.

      Model identifiers are case-sensitive provider contracts. Providers should return false, rather than throw, for unknown identifiers. The answer must be local — no network call — because Role initialization checks provider support before dispatch and the runtime rechecks it on every retrieval dispatch before consulting the result cache.

      Parameters:
      model - model identifier from @Search.rerankerModel
      Returns:
      true when this provider can serve the model

    • rerank

      List<RetrievedDocument> rerank(Reranker.Request request)
      Reranks retrieved candidates for the original user query.

      Returning an empty list for a non-empty Reranker.Request.documents() is in contract — a provider applying a relevance threshold may legitimately reject every candidate — but the runtime logs it at WARN, because from the caller's side it is indistinguishable from a provider that dropped the candidates by accident.

      Parameters:
      request - immutable reranking request
      Returns:
      candidates in relevance order, optionally filtered