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.
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 →