Achilles — Query Engine: RAG route

The core of grounding mode: how a question turns into a grounded answer once the model decides to search. RAG here is a route: having called search_knowledge, the model sends the query down through five steps — Embed → Retrieve → Rerank → Augment → Generate. The decision to call the tool and the self-contained query itself belong to the model (decision to search); the route's area of responsibility is reranking, context packing, and grounding generation; embedding the query and the search itself belong to Knowledge Store. Which model does which work is on the model map; where a single round of tools ends and the agent loop begins is at the boundary.

Search route: the query descends through five layers

The route is the body of the search_knowledge tool: it runs when the model has decided to search and passed a self-contained query. One pass top to bottom: steps 1–2 (embed · retrieve) are executed by Knowledge Store, steps 3–5 (rerank · augment · generate) by Query Engine. At the entrance is a cache gate: a repeat identical search by the same identity returns candidates from cache, bypassing the expensive embed/retrieve. The boundary between the two sides runs along a layer, not between sections: the same stack shows where storage returns candidates and where RAG refines them.

◇ Exact cache? key = self-contained query + identity

hit ──▶ candidates from cache · bypassing embed + retrieve

miss ▼ the route continues

1 Embed Knowledge Store Query → vector.

Query embedding

The self-contained query is turned into a vector by the same embedding model that built the index — the shared platform embedder (Harvester / KS), not a Query Engine setting. The step is executed by Knowledge Store; Query Engine only passes the text and the user's identity. The search mechanics are held by retrieval · boundary.

2 Retrieve Knowledge Store An assembled hybrid result under access rights.

One call — fused candidates

Query Engine takes a ready hybrid result from Knowledge Store in a single query: four search primitives, their fusion (RRF), and the ACL pre-filter — all inside KS, under the user's identity. Query Engine neither builds nor sees the rights scheme — identity is the input, candidates under rights are the output. Mapping the identity to source accounts is held by retrieval · identity.

3 Rerank Query Engine Reorder candidates against the question.

Order from KS, no model

In v1, reranking relies on the RRF order already assembled by Knowledge Store — there is no separate model. A cross-encoder reranker, re-scoring the top-N as “query × candidate” pairs, is a separate v2 step; covered on the rerank map.

4 Augment Query Engine Packing context for the model.

Prompt assembly

The selected candidates are packed into the model's context:

The best fragment as evidence — one most telling fragment per entity, not all of its material: a trade of completeness for source diversity.
Cut-off under the shared window budget — fragments are laid out from more to less important and trimmed not against the whole window but against the remainder left by history: the room is shared by the context-window budget, keeping the reserve for the answer.
Source markup for citation — each fragment gets an origin marker so the answer can cite it.
Augment does not duplicate history — the model already holds it in the window as the driving turn, so only the found fragments go into the packing, not a second copy of history. Follow-up coherence (“expand the previous point”) comes from that same history in the window; the answer's evidentiary base is only what was found.

Above it all sits the platform prompt — the shared layer of security and organization rules that Admin sets once per instance; then come the found fragments. Here too the grounding rule is fixed — answer only from the embedded context; the wording of the honest “not found” is held by grounding. The found content is untrusted input: fragments are supplied as data, not as instructions to the model; hardened protection against prompt injection is v2.

5 Generate AI Query Engine Builds the answer on what was found — the same chat model.

Grounding generation

The packed context is returned to the same chat model that called the tool — the one the user picked in the chat and that drives the conversation, not a separate platform model. It builds the answer strictly on what was found and streams it synchronously, citing the sources. The per-step model layout is held by the model map.

Knowledge Store steps 1–2 · embed + retrieve

▸

Query Engine steps 3–5 · rerank + augment + generate

Model map: who works with what

drives the turn + generate AI

The selected chat model

The model the user picked in the chat drives the whole turn: it decides whether to call search_knowledge, formulates the self-contained query, and builds the answer on what was found. Not a separate platform “RAG model” and not a service router. Assigned in admin · AI models.

embed AI

The shared embedder

Query embedding — by the same platform embedder that built the index (Harvester / KS). Otherwise the query vector and the chunk vectors are incomparable.

rerank v2

v1 — no model

In v1, reranking is the RRF order from Knowledge Store, without inference. A cross-encoder reranker as a model is v2.

Rerank: RRF now, cross-encoder later

Reranking decides which of the candidates make it into the context and in what order. A fork by iterations, not by alternatives — v2 builds on top of v1 rather than replacing it.

RRF from KS

The order is taken straight from the assembled hybrid result: Knowledge Store has already fused the primitive lists by reciprocal rank fusion. Query Engine packs the candidates in the order they arrived.

Cross-encoder reranker v2

A separate model re-scores the top-N candidates as “query × candidate” pairs — more precise than RRF, because it sees the query and the text together rather than summing positions.

Boundary: one round of tools, agents go further

The boundary is not whether the model has tools, but whether there is a loop. Query Engine's chat model gets one round of tools per turn: it may call several in parallel (say search_knowledge + web_search), receive the results, and must answer. There is no loop — a round is not followed by a second round based on the results of the first. This keeps the answer predictable and separates a conversational turn from a full agent. The tool-calling under both is the shared harness: the boundary below is its parameterization — one round versus a loop.

Query Engine one round of tools

Per turn the model does one round: it calls zero, one, or several tools at once (KB + web search), receives the results, and builds the answer. Without planning and without a second round based on the results of the first.

▸

Agent Engine the agent loop

Multi-step, tool-using reasoning — search loops, choosing a tool from a set, planning — belongs to → Agent Engine, which calls the Knowledge Store primitives directly, bypassing Query Engine.

v2 — multi-round agent chat: the model plans and takes several rounds within the conversation itself, reading further based on the results of the previous one. A layer on top of the single round, not an access boundary.

v2 exception to the single call: on low confidence in the candidates, Query Engine makes a bounded (N=1) repeat search before answering “not found” — one attempt to rephrase and re-ask, not a full agent loop. The “not found” answer itself and its honesty are held by grounding.