Optional cross-encoder reranking and MMR diversification for recall results. Fail-closed since 0.6.0 — throws RerankError on provider failure.

What is it?

A second-stage ranking step. After vector (and optional hybrid) retrieval, a reranker scores query–document pairs. MMR diversifies the final set to reduce near-duplicates.

Bi-encoder retrieval is fast but coarse. Cross-encoders improve precision. MMR improves diversity for agent context windows. Incorrect ranking that looks successful is worse than a loud error — so since 0.6.0, rerank fails closed.

How does it work?

Rerank

import { jinaReranker, cohereReranker } from "wolbarg";

reranker: jinaReranker({ apiKey: process.env.JINA_API_KEY! })

await ctx.recall({ query: "…", topK: 5, rerank: true });

Built-in factories: jinaReranker, cohereReranker, bgeReranker, crossEncoder, openaiReranker.

Fail-closed (0.6.0+)

No soft skip / identity fallback

rerank: true without a configured reranker throws ValidationError
Built-in HTTP / OpenAI rerankers throw RerankError on provider failure or empty rankings — they do not fall back to identity order

Catch RerankError explicitly when you enable rerank.

MMR

await ctx.recall({
  query: "…",
  topK: 5,
  mmr: true,              // lambda = 0.5
  // mmr: { lambda: 0.7 } // higher = more relevance, less diversity
});

When should it be used?

Use rerankers for high-stakes grounding (support answers, code RAG). Use MMR when agents repeatedly get near-duplicate snippets.

Performance notes

Over-fetch (retrieval.overFetchFactor) feeds the reranker more candidates
Network latency depends on the remote rerank API
Skip rerank in latency-critical hot paths

Rerankers