RAG Pipeline Viz

A stage-by-stage visualisation of a Retrieval-Augmented Generation pipeline: Query → Embed → Retrieve → Rank → Augment → Generate. A single cursor advances through the stages; optional accent-coloured tokens flow along the edge between the current and next stage to show data moving downstream.

Installation

npx shadcn@latest add https://craftbits.dev/r/rag-pipeline-viz.json

Usage

import { RAGPipelineViz } from "@craft-bits/core";
 
<RAGPipelineViz />

Override stages to teach a custom pipeline — e.g. an agentic loop:

<RAGPipelineViz
  stages={[
    { id: "plan",   label: "Plan",   description: "Pick a tool" },
    { id: "act",    label: "Act",    description: "Run the tool" },
    { id: "verify", label: "Verify", description: "Check output" },
    { id: "answer", label: "Answer", description: "Reply to user" },
  ]}
/>

Drive playback from outside the component:

const [step, setStep] = useState(0);
 
<RAGPipelineViz
  currentStage={step}
  onCurrentStageChange={setStep}
  playing={false}
/>

Understanding the component

1. One cursor through the whole pipeline. A single currentStage index drives the active highlight, the past/future styling, and the edge that carries flowing tokens — there is no per-stage state machine.
2. Stages are cards; edges are arrows. Each stage renders as a bordered card with an icon, label, and optional description. Edges between adjacent stages share a rail and arrow-head glyph; the active edge lights up in --cb-accent.
3. Tokens flow only on the active edge. Three accent dots travel along the rail between the current stage and the next, staggered by 50ms each. They use SPRINGS.snap so they feel like discrete packets, not a continuous wave.
4. SPRINGS.smooth for the stage cursor. The active card scales to 1.02 and brightens via a smooth spring from @craft-bits/core/motion — the cursor settles on each stage rather than snapping.
5. Reduced-motion fallback. With prefers-reduced-motion: reduce, the pipeline renders fully lit on mount, autoplay pauses, and the flowing-token dots are suppressed.
6. Two orientations, same component. horizontal flows left → right (default); vertical stacks top → bottom with arrows pointing down.

Props

Accessibility

• The root is role="figure" with aria-labelledby pointing at the "RAG pipeline" heading and aria-describedby at a visually-hidden aria-live="polite" summary.
• The summary announces the current stage and step counter whenever the cursor advances.
• Stages are rendered in a semantic <ol> with aria-current="step" on the active card.
• The play / pause button uses aria-pressed; the label flips between "Play pipeline" and "Pause pipeline".
• The scrubber is a native <input type="range"> with an aria-label so keyboard arrows nudge the cursor and screen readers narrate the value.
• Color is never the only signal — stage labels, descriptions, and the step counter are all textual.
• prefers-reduced-motion: reduce renders the pipeline fully lit on mount, suppresses flowing tokens, and disables autoplay.

Credits

• Extracted from: craftingattention (app/src/lessons/primitives/systems/RAGPipelineViz.tsx). Stripped the lesson-specific four-stage state machine (query / retrieval / reranking / context), document score bars, precision-gauge sub-component, retrieval-mode toggle, narration heuristics, and the bespoke document set. Generalised to an arbitrary stages: RAGPipelineStage[] array with controlled / uncontrolled state pairs and added orientation + flowing-token visualisation.