Retrieval inspector
For a test question, shows which passages search found, how they scored, and which made it into the model's context.
Loading preview…
Install
- 1
Run this command in your Tailwind CSS project. It adds
components/ai/retrieval-inspector-chunks.tsxand installs its dependencies.$ npx shadcn@latest add https://gradientdeck.com/ai-components/r/retrieval-inspector-chunks.json
Usage & API
Example
import { RetrievalInspector } from "@/components/ai/retrieval-inspector-chunks"
<RetrievalInspector
query="…"
onQueryChange={() => {}}
onRun={() => {}}
loading={true}
passages={[]}
terms={[]}
threshold={1}
onThresholdChange={() => {}}
topK={1}
onTopKChange={() => {}}
selectedId={null}
onSelect={() => {}}
/>Props RetrievalInspector
| Prop | Type & description | Required |
|---|---|---|
query | string | Required |
onQueryChange | (q: string) => void | Required |
onRun | () => voidCalled on Enter. | Required |
loading | boolean | Required |
passages | Passage[] | Required |
terms | string[]Terms from the last run, highlighted in passages. | Required |
threshold | number | Required |
onThresholdChange | (v: number) => void | Required |
topK | number | Required |
onTopKChange | (k: number) => void | Required |
tokenBudget | number | Optional |
selectedId | string | null | Required |
onSelect | (id: string) => void | Required |
summary | stringe.g. "Searched 1,912 chunks in 7 sources · 44ms" | Optional |
embedding | string | Optional |
Dependencies
- React
- Tailwind CSS
- motion
- lucide-react
Implementation notes
The chunks screen puts the agent name and the model in the header, with the test question and a run control. After a run, a summary line can say how many chunks and sources were searched and how long it took. The threshold slider is marked with the scores you passed. Top-k has fewer and more buttons. Order switches By score and As sent. Each row shows the source, the location, the score to two decimals, a bar, and a chip: In context, Over top-k, or Below threshold. Selecting a row opens the passage, with Back to passages on a narrow layout. Neighbours and Metadata sit under the text. Terms from the question are highlighted. An empty result says nothing in the agent's knowledge matched.
Example
import { RetrievalTrace } from "@/components/ai/retrieval-inspector-pipeline"
<RetrievalTrace
question="…"
onQuestionChange={() => {}}
onRun={() => {}}
running={true}
stages={[]}
terms={[]}
expanded={[]}
onExpandedChange={() => {}}
/>Props RetrievalTrace
| Prop | Type & description | Required |
|---|---|---|
question | string | Required |
onQuestionChange | (q: string) => void | Required |
onRun | () => void | Required |
running | boolean | Required |
stages | TraceStage[] | Required |
terms | string[] | Required |
expanded | string[] | Required |
onExpandedChange | (ids: string[]) => void | Required |
traceId | string | Optional |
ranAt | string | Optional |
Dependencies
- React
- Tailwind CSS
- motion
- lucide-react
Implementation notes
The trace screen uses the same style of question field. The button reads Trace, or Tracing while running. A line says which stage is running, or the end-to-end time and when it ran. The trace id can be copied. Expand all and Collapse all toggle every stage, and they are disabled while a run is in progress. A timing bar shows each stage's slice, and hovering a slice lights the row. Parallel stages share a lane so they occupy one slot. Opening a stage lists its items and any fact pairs, plus a footnote such as how many hits were kept. Arrow keys move between stage headers.
Choosing a layout
Use the ranked passages when someone is tuning the cutoff: too many irrelevant chunks, or the right paragraph sitting just outside the top k. Use the trace when the question is which stage dropped it, a rewrite, a keyword search, a merge, rather than the final score alone. Both start from the same kind of test question, the one a customer would ask.
Adding the file is source ingest. Turning the file on for the project is knowledge sources. Reading the passage an answer already cited, inside the chat, is the source viewer. The inspector is the test bench before those answers exist. It is not the reply the customer sees.
Does moving the threshold run the search again?
No. Status is computed from the passages, the threshold and the top k you already have. In context means the passage is among the top k and at or above the threshold. Below threshold and Over top-k are the other two. A new search is the run button, which calls onRun.
What is a lane on the trace?
Stages with the same lane id are drawn as parallel work and share one slot on the timing bar. Stages without a lane run in sequence. The bar uses the start and duration you set on each stage. It does not measure them.