Skip to main content

Interface: KbRetriever

Defined in: internal/kb-retriever/KbRetriever.ts:66

KbRetriever -- the read side of the knowledge base: prompt to grounded chunks

About​

Finds what the model should read, or says plainly that there is nothing.

Implements IKbRetriever: rewrite the prompt into a query (QueryRewriter, when switched on) → embed it (Embedder.embedOne) → search the tenant's index inside the scope the caller named (VectorStore.search) → keep the hits of at least minScore, best first, at most k. noMatch is a first-class result: the prompt then tells the model the knowledge base has nothing. searched tells that apart from a call that named no library and did not use the knowledge base at all (D25, D26).

It sets the quality ceiling of grounded answers whatever the main model is: a chunk it misses is never read.

Who needs it​

prepareCall, once per ask / run call, with IGatewayInput.kbFilters as the scope; the result goes to the ContextAssembler. A host replaces it with its own IKbRetriever (a reranker, hybrid search) in overrides.kbRetriever.

What needs​

queryRewriter, embedder, vectorStore.

Usage​

When to use it​

Always, through the gateway: createGatewayDeps creates it from IAIGatewayConfig.kbRetriever (optional, all defaults).

When shouldn't use it​

A call that should not touch the knowledge base passes an empty libraryIds: no rewrite, no embedding, no search.

Pitfalls​

minScore is tied to the embedding model: change the model and the default drops the right chunks or lets the wrong ones through. The retriever has no reranker and no keyword search: a question whose words are not in the chunk and not in its heading path is missed.

Implements​

Methods​

retrieve()​

retrieve(__namedParameters): Promise<IRetrievalResult>

Defined in: internal/kb-retriever/KbRetriever.ts:93

retrieve -- the chunks for one prompt

About​

Rewrite, embed, search, cut.

Rewrites the prompt into a query (when switched on), embeds it, searches the libraries and books of filters for the tenant and keeps the hits of at least minScore, best first, at most k. With an empty filters.libraryIds the knowledge base is not used: no model call, searched is false, noMatch is true. k and minScore override the config for this call (the caller's IGatewayAskInput.kbRetrieval).

Who needs it​

prepareCall, once per call, after the input check and before the request is assembled.

Pitfalls​

Two model calls per search (rewrite, embed), each one usage-guard check and one trace. The search takes no abort signal: prepareCall checks the signal before it, not during.

Parameters​

__namedParameters​
cheapModelId​

string

facts​

Record<string, string>

filters​

IChunkFilters

The libraries and books to search. With an empty libraryIds nothing is searched: the result is noMatch, without a model call.

k?​

number = ...

Override config.k for this call.

meta​

Omit<ILLMClientCallMeta, "kind">

Who asks, for the usage adapter and the trace; the kind is set here: QUERY_REWRITE for the rewrite, EMBED for the embedding.

minScore?​

number = ...

Override config.minScore for this call.

prompt​

string

summary​

string

tenantId​

string

Returns​

Promise<IRetrievalResult>

Implementation of​

IKbRetriever.retrieve