retrieve run the whole
thing.
Stage → surface map
Stage by stage
Every stage except recall is optional and independently negotiated — a server advertises only what it implements, and a client sees the rest as absent.Transform — sharpen the query
Rewrite, expand, or decompose the raw query before recall: HyDE (embed a
hypothetical answer), multi-query (fan out into paraphrases), step-back
(generalise), or decomposition (split a multi-hop question into parts).
Exposed as
query/transform, or folded into a retrieve call via
retrieve.rewrite. Capability: transform.Recall — cast a wide net
Fetch a large candidate set cheaply.
mode picks the matcher: dense
(bi-encoder semantic search), sparse (BM25 or learned-sparse / SPLADE
lexical), or hybrid (both at once). This is the one stage always present.
Capability: retrieve.Fuse — merge the lists
When recall runs more than one matcher, their scores are not comparable, so
the ranked lists are merged by rank: reciprocal-rank fusion (
rrf) or a
weighted blend. Controlled by retrieve.fusion. The exact algorithm is
available as a reference primitive —
rrf_fuse / weighted_fuse
— in every SDK, so client-side fusion matches server-side byte-for-byte.Rerank — score precisely
Rescore the surviving candidates with an expensive, accurate model: a
cross-encoder, ColBERT late interaction (MaxSim), or an LLM judge. Available
standalone as
rerank or inside retrieve.
Capability: rerank.Diversify — cut redundancy
Maximal Marginal Relevance (MMR) trades a little relevance for novelty so the
final set isn’t five paraphrases of one passage. Controlled by
retrieve.mmr. Capability: retrieve.mmr.Pack + cite — assemble the answer
Return the best
k hits, each with its citation, trust signals, and
enough chunk context to ground a generation step.Beside the pipeline
Three surfaces sit next to the linear flow rather than inside it:Graph
Local (entity-anchored), global (community-summary), or DRIFT search over a
knowledge graph — GraphRAG.
Index
Mutate the corpus the pipeline runs over with
index/add and index/delete.Embed
Expose the server’s vectors so a client can build its own ANN index.
Two ways to drive it
Let the server run it
A client that just wants “the best hits for this query” calls
retrieve and
lets the server run its full pipeline — transform, recall, fuse, rerank, MMR,
cite. One request, one ranked list.Orchestrate it yourself
A client building an agentic loop calls the stages individually —
query/transform to plan, embed for a client-side ANN index, rerank to
rescore, graph to walk relationships.The funnel invariant
The three result-size knobs onretrieve form a funnel and MUST satisfy:
candidateK candidates, the reranker rescores the top
rerank.topN of them, and the server returns the best k. This is why a good
retrieve implementation is cheap-and-wide then precise-and-narrow.
See it end to end
The
retrieve method drives every stage of this pipeline through one call.