Inspectable Retrieval

A working definition

Inspectable retrieval

/ɪnˈspɛktəbəl rɪˈtriːvəl/

The ability to inspect what a retrieval system returned, where it came from, and the query and configuration used to retrieve it.

Before judging an answer, look at the evidence the system retrieved.

What inspection reveals

The result
Which passages matched, in what order, and with which scores.
The source
The document, chunk, and location behind each passage. A relevant-sounding sentence needs its context.
The request
The query, filters, and retrieval parameters used to produce the result.
The configuration
The embedding model, index, and ranking settings needed to make comparisons meaningful.

Replay makes retrieval drift visible

Keep the original query, parameters and ranked results in a query log. After your collection changes, rerun the query against its current state and compare the records: which passages moved, disappeared or appeared? Changed results are the evidence you are looking for.

The log provides a comparison baseline. Reconstructing an earlier collection state is a separate task that requires retaining its data and retrieval configuration.

A retrieval problem, up close

Debug RAG retrieval: right topic, missing answer.

A passage can sound relevant without answering the question. Check what was retrieved before changing the generation prompt.

Illustrative example · fictional documents

Query
How long do I have to request a refund?

You can cancel your subscription at any time.
Inspect the passage and source
Source
Subscription guide · Cancellation
Chunk
“You can cancel your subscription at any time. Access continues until the end of the billing period.”
What is missing?
This passage says when access ends. It gives no deadline for requesting a refund.

The separate Refund policy says, “Refund requests are accepted within 14 days of purchase.” In this example, that is the evidence the retriever needed to return.

Check that the refund document was ingested, that its chunk keeps the deadline with its context, and that filters did not exclude it. Keep the original result record, then rerun the query after the change. Compare the sources and ranking to check whether the refund passage now appears. Inspection identifies the problem; replay helps check the fix.

The book · public draft coming soon

Inspectable
Retrieval

with PaveDB

Building RAG and semantic search systems you can deploy, operate, observe, and trust.

Rodrigo Rodrigues da Silva

Flowlexi Labs

From embedded Python to an operated service: inspect sources, compare query replays and keep retrieval under your control. The full public draft will be available as a PDF by email. For publication news, contact the author.

Find the author on LinkedIn →

Put the method to work

PaveDB is one open-source implementation of inspectable retrieval and the engine used in the book. It brings source provenance, query history and text-query replay to embedded Python and HTTP deployments. The method applies wherever you need to understand what retrieval returned and how it changes.

Start with PaveDB’s documentation and API reference. For the design decisions behind the work, read Signal / Action.

Explore PaveDB →