Retrieval

Choose between two entry points: query an index directly with IRagRetriever, or configure Agent.UseRag(...) to retrieve and evaluate context during an agent execution.

Query an index directly with IRagRetriever

IRagRetriever, available in Runiq.AI.Rag.Abstractions.Retrieval, returns retrieval candidates. The caller chooses the index, question, mode, and candidate limit. This direct call does not execute an agent, apply its rag.Acceptance or grounding policy, or generate an answer.

This fragment assumes an injected IRagRetriever retriever, an ingested company-policies index, and a configured embedding client:

using Runiq.AI.Rag.Models.Queries;
using Runiq.AI.Rag.Models.Retrieval;

var results = await retriever.RetrieveAsync(new RagQuery
{
    IndexName = "company-policies",
    Text = "How do I reset access to my account?",
    Mode = RagRetrievalMode.Semantic,
    TopK = 5,
}, cancellationToken);

TopK limits retrieval candidates. Application code owns what it does with these raw results. Agent runtime acceptance and grounding apply when using the separate agent execution path below; they are not automatically added to a direct retriever call.

Retrieve, accept, and ground with Agent.UseRag

Calling IRagRetriever directly and attaching RAG to an agent are separate operations. Registering an index does not make agents search it. Use .UseRag(...) on the agent and set rag.IndexName to company-policies, matching the index registration. Defining indexes shows the complete host example.

Inside that callback, acceptance is configured through the agent runtime:

rag.Acceptance.MinimumRelevance = 0.55;
rag.Acceptance.CandidateCount = 20;
rag.Acceptance.MaximumAcceptedResults = 6;

CandidateCount is the retrieval budget, MinimumRelevance is an optional normalized relevance threshold, and MaximumAcceptedResults caps accepted context results. These example values are policy choices, not quality guarantees. Duplicate filtering and subsequent context-budget selection can further affect which text reaches the model.

With rag.Mode = RagExecutionMode.Required and rag.NoContextBehavior = RagNoContextBehavior.ReturnNotFound, successful retrieval without accepted context produces a framework-owned not-found response and skips the model. Retrieval errors remain failures rather than becoming normal answers.

Accepted document text is sent in a separate <untrusted-external-context> user message. The runtime treats it as evidence rather than promoting it to system, developer, agent, or framework instructions. This prompt-injection mitigation does not independently verify the correctness of a generated answer.

Choose the search mode

Lexical mode removes the embedding requirement from the query path; it does not imply that a named index can omit its registration requirements or that every ingestion pipeline is embedding-free. The selected store must support the requested search mode.

var identifiers = await retriever.RetrieveAsync(new RagQuery
{
    IndexName = "company-policies",
    Text = "POL-HR-014",
    Mode = RagRetrievalMode.Lexical,
}, cancellationToken);

var phrase = await retriever.RetrieveAsync(new RagQuery
{
    IndexName = "company-policies",
    Text = "\"account recovery\"",
    Mode = RagRetrievalMode.Hybrid,
}, cancellationToken);

Surrounding double quotes express exact phrase intent. PostgreSQL combines its simple text-search configuration with trigram indexing to preserve searches for punctuation-sensitive terms.

Hybrid search requires both sources to succeed. It merges identities by document and chunk, using reciprocal rank fusion with 1 / (60 + sourceRank) and one-based ranks. It retains each source's scores in retrieval provenance rather than averaging incompatible values.

Interpret scores correctly

For example, in-memory cosine uses a higher-is-better similarity, while PostgreSQL exposes a lower-is-better cosine distance. Dot product is unbounded and has no normalized relevance in these adapters. Do not display a raw score as a percentage confidence or compare raw values across different providers.

Optional reranking

IRagReranker provides a second scoring stage over a bounded set of accepted chunk identities and their text. It returns normalized relevance and answerability signals while preserving retrieval scores and provenance. The agent runtime owns candidate limits, timeout, fallback behavior, and grounding enforcement.

A remote reranker receives the original query and full candidate text. Choose it according to the application's data boundaries, keep credentials in a secret provider, and treat retrieved text as scoring input rather than instructions. The adapter should not copy candidate content into logs or errors.

Reference: RAG retrieval and reranking contracts.