Retrieval with citations over the site's documents

A language model knows a great deal in general and nothing about the valve on your third line, the procedure your site adopted after last year's incident, or the note a technician left in a work order. The site's documents know all of that. The Retrieval service puts the two together, and insists that the model show its sources.

This article explains how Retrieval works on the appliance, what it asks of the site, and why citations are the point rather than a feature.

What Retrieval does

A caller asks a question. Retrieval searches the site's indexed documents for the passages most relevant to it, hands those passages to a language model, and asks the model to answer using them. The answer comes back with citations: which document, which section, which passage supported each claim.

The effect is an assistant that answers from the site's own knowledge rather than from general training. Asked how to clear a fault on a particular machine, it answers from that machine's manual and the site's own procedure, and the technician can open the cited page to confirm.

Indexing on the appliance

Before Retrieval can search, documents must be indexed. The site points the service at a library on the facility network. The appliance reads the documents, breaks them into passages, and runs each passage through an open embedding model served by Inference. The resulting index lives on the appliance.

Nothing in this step leaves the building. The documents are read in place or copied to the appliance; the embedding model runs in the rack; the index is stored in the rack. A site with sensitive procedures does not have to decide whether to trust an outside indexer, because there is none.

Indexing is a patient workload. It declares long budgets and runs in the gaps around the floor's urgent calls, so bringing a large library online does not slow the robots.

Collections and who may read them

Documents are organized into collections, and each collection carries access rules tied to caller identity. A maintenance assistant retrieves from the maintenance library. A line operator's console retrieves from procedures. An agent working a receiving dock retrieves from supplier specifications and the site's acceptance criteria.

Because identity and policy live on the single API, these rules are set once and apply to Retrieval the same way they apply to Inference. The Evaluation trace records which collection each answer drew from, so a question about whether a caller saw something it should not have is answered from the record.

Why citations matter

A grounded answer without citations is only a confident answer. Citations make it checkable. The reader can open the source and see whether the passage says what the model claims. On a floor where a wrong instruction has consequences, that check is the difference between an assistant that helps and one that must be second-guessed.

Citations also discipline the model. When the retrieved passages do not support an answer, Retrieval says so rather than letting the model fill the gap from general knowledge. A technician who asks about a procedure the site has not documented is told the procedure is not in the library, which is a more useful answer than a plausible invention.

Sites change their documents. A procedure is revised, a manual is replaced, a notice is withdrawn. Retrieval re-indexes what changes, and answers that cite a superseded document are flagged in the trace so the site can see where stale knowledge was used.

The trace is also where the site discovers gaps. Questions that returned no supporting passage are a list of what the library does not cover, which is usually what the site should write next.

Agents and the record

The agent layer on the appliance uses Retrieval to ground what agents say and do. An agent handling a maintenance request retrieves the relevant procedure before proposing a step; an agent preparing a shift summary retrieves the incident reports it is summarizing. The same citations that help a human reader let a supervisor check what an agent relied on.

Combined with Memory, which keeps the agent coherent across sessions, Retrieval is what lets an agent work from the site's knowledge rather than its own guesses.

Every retrieval is traced: the caller, the question, the collection searched, the passages returned, the model that answered, the answer, and the citations. When an answer was wrong, the trace shows whether the wrong passage was retrieved, the right passage was misread, or the library simply lacked the answer. Each has a different fix, and the record points to it.

How Retrieval sits with the other services is in one API for seven services. The service that keeps agents coherent between retrievals is in Memory that keeps an agent coherent. The trace that records every retrieval is in tracing every operation with Evaluation.