Retrieval pipeline

Retrieval is one of the core pipelines an agent can use. Behind a single question sits a staged pipeline that turns a user message into evidence, assembles a prompt, and presents an answer with citations.

The stages matter because they are where quality goes wrong. When an answer is off, find the stage that failed before you start changing agent skill settings, ingestion settings, or prompts.

Stages

Retrieval context

The pipeline starts by resolving system retrieval defaults, any retrieval.answer skill settings on the selected agent, and a limited conversation window. This stage decides the behavioral frame for the turn before any search runs.

Query interpretation

Radioso parses the original query, applies rewrite logic when enabled, and can split the request into retrieval subqueries. This is where semantic and lexical rewrite instructions matter.

Candidate retrieval

The system runs semantic and lexical retrieval. Semantic retrieval uses embeddings. Lexical retrieval uses search text built from the document title, chunk content, and metadata-derived text.

For listing-style event date questions, the pipeline can also ask a retrieval-owned temporal candidate port for ongoing and upcoming chunks with dateFrom and dateTo metadata. This path is controlled by the agent’s temporal structured lookup setting.

Candidate preparation

Retrieved chunks are normalized, merged, and scored. Metadata rules and explicit metadata filters narrow or boost the candidate set here.

Semantic cosine and query-relative lexical scores stay separate. Candidate preparation combines their source ranks into a fused score from 0 to 1, with a bounded boost when both sources find the same chunk. Weak lexical results must also meet an absolute lexical-rank floor before they can contribute to fusion or minimum-useful-candidate checks.

When upcoming-event boost is enabled, dated event evidence can receive a temporal boost during event date lookups. Topic relevance still applies; the temporal signal refines the candidate set rather than replacing it.

Context selection

The system reranks candidates when reranking is enabled, then selects the final prompt contexts. vectorTopK, similarityThreshold, rerankEnabled, and rerankTopK all influence this stage.

When deterministic temporal sort is enabled, selected dated event contexts can be ordered by extracted dates before prompt assembly. This makes “next events” and “sort by actuality” evidence order stable.

Prompt assembly and diagnostics

Radioso builds the final prompt, generates citations, and captures diagnostics and a retrieval trace. Chat then uses that result to generate the answer.

What operators can adjust

Retrieval behavior is configured per agent through the retrieval.answer skill. Retrieval-only API calls use system defaults and still accept per-call controls such as metadataFilter.

retrievalStrategy controls the execution style. fixed runs one search pass, reasoning lets the model plan and run multiple searches, and auto lets Radioso choose per query.
vectorTopK controls how many chunks are fetched from the vector index before filtering and reranking.
rerankEnabled controls whether fetched chunks are re-scored with the reranker model. It is off by default.
rerankTopK controls how many chunks survive reranking and are passed to the answer.
queryRewriteEnabled controls whether the user message is rewritten into search queries before retrieval.
semanticRewriteInstructions replaces the default instructions for rewriting the semantic vector search query. Empty means the default applies.
lexicalRewriteInstructions replaces the default instructions for rewriting the lexical keyword search query. Empty means the default applies.
suggestedQuestionsEnabled controls whether follow-up question suggestions are offered after each answer.
suggestedQuestionsCount controls how many follow-up questions to suggest.
metadataRules constrain the candidate set before prompt assembly for the agent.
temporalStructuredLookupEnabled, temporalBoostUpcomingEnabled, and temporalDeterministicSortEnabled control date-aware event lookup, boosting, and ordering for the agent.
Per-request metadataFilter constrains retrieval API calls without changing saved agent settings.
customInstruction influences how the final answer is written, but it cannot rescue bad retrieval.

What happens after retrieval

Retrieval does not directly become the user-visible answer. The agent chat layer presents the model output as answer segments with citations derived from the retrieved evidence.

In practice, poor answers usually come from weak retrieval inputs, weak candidate selection, or overly aggressive filtering. Prompt tweaking should usually come after you verify those earlier stages.

Debugging order

Confirm the document was fully processed and chunked.
Check whether the query needed rewriting or metadata filters.
Increase candidate depth before strengthening retrieval signals.
Revisit customInstruction only after retrieval evidence looks correct.