RAG Knowledge Base

Demo & usage

More examples

When to use

• Managing a retrieval-augmented knowledge base: sources, ingestion, index health.
• RAG-powered products that need source and pipeline visibility.
• For displaying retrieved chunks in chat, use the AI Chat tool-call chips.

Async states

• loading
• error
• retry

Item identity & owned state

Restorable state

• syncingIds

Bind these to put a saved view back — the open sections, the hidden columns, the selected rows — and read their Change events to store what the user does.

Outputs

Wire it to your API

This component is headless about transport: it renders what you give it and reports what the user asks for. Nothing below requires @styloviz/data — drive it from whatever you already use.

• This component does not emit a query, so it renders what you give it. Fetch on your own trigger and bind `sources`, `loading` and `error`.
• Normalize failures with `toSvDataError()` from `@styloviz/core`. It derives `retryable` from the status, so a 404 does not get a "Try again" button that can only fail again.

Full walkthrough: Connecting to a backend.

Customization & theming

• Who can retrieve a source is on **every row**, not only in the expanded panel: a compact audience chip (Everyone, or the group names) in the overview Source Health strip and on each collapsed row in the sources view, with a roll-up of how many sources are open to everyone. The full sentence stays in the expanded detail.
• `KbSource.audience` lists the groups that can retrieve a source, and every row says who that is. An **undeclared audience reads as everyone** and says so — reading silence as 'restricted' would make an unmigrated index look safer than it is, which is the one direction this surface must never round. A roll-up counts the sources open to everyone, because a reviewer scanning forty rows will not notice the one without a lock.
• `status: 'deleting'` with `KbSource.deletion` — chunks remaining, embeddings remaining, and **whether it can still be retrieved**. Deletion is a lag, not an event: until the chunks and the embeddings go, the retriever can still return the thing somebody asked to have removed, and a panel that says 'deleted' the moment the button is pressed is making a compliance claim it cannot support. The source stays listed while it happens rather than vanishing from a panel whose answers keep arriving. The retrievability sentence renders as real emphasis from `svDeletionParts()` (structured runs, no Markdown, no `innerHTML`); `svDeletionLabel()` is the same notice as plain text.
• The retrievability sentence is never omitted while it is true, including when both counts have reached zero — that is the dangerous middle, where nothing is left to delete and answers are still arriving. The counts are reassuring because they go down, and a reader watching them fall will assume the job is done long before it is.
• Redaction, from the pack-wide policy (`X-2`): a chunk preview is masked BEFORE it is truncated. The other order leaves a half-secret whenever the preview boundary falls inside one — `sk-live-abcde…` is not a redaction, it is a shorter version of the key.
• Every content set is an input defaulting to the bundled sample — `stats`, `sources`, `pipelineRun`, `pastRuns` and `alerts`. Uploads and sync progress are transient local state layered over `sources`; supplying a new list discards that layer, because your data is the truth. Alert resolutions are layered the same way and reported through `alertResolved`.
• `simulate` is off by default, so `sourceAdded` fires on upload and you supply the updated `sources`. Set it to true only in a showcase — a progress bar that tracks a timer instead of an indexer is worse than none.
• Overview, sources, pipeline and health views.
• Index stats and sync progress.
• Pipeline stage visualization.
• Set `uploadable` (sources view) for a drag-and-drop upload zone that adds files as new sources; constrain types with `accept` and listen to `sourceAdded`. An added source is marked as not yet persisted until your `sources` list contains it.
• Also emits `sourceSelect` and `syncTriggered` with the source id.
• The retrieval panel's two confidence lines are inputs too: `[spreadFlatPct]` (5) and `[marginDecisive]` (0.5), from the still-exported `SV_SPREAD_FLAT_PCT` and `SV_MARGIN_DECISIVE`. Both describe one retriever's score distribution — cosine similarities between 0.78 and 0.83 are flat at five per cent by definition, and BM25 scores from 40 to 2 are never flat at all. `[marginDecisive]` is a SHARE of the spread, so it lives in 0–1; a figure above 1 is refused with a dev warning rather than making every query read "contested" for ever.
• The chunk inspector's three token limits are inputs: `[minChunkTokens]` (48), `[maxChunkTokens]` (512) and `[embedTokenLimit]` (8192), defaulting to the exported `SV_CHUNK_MIN_TOKENS`, `SV_CHUNK_MAX_TOKENS` and `SV_EMBED_TOKEN_LIMIT`, which are still exported — `svChunkRows` and `svChunkFlagLabel` take them as an optional last argument. A target ceiling above the embedding limit is clamped down (it would let a chunk be reported healthy AND truncated at embed time), a floor at or above the ceiling is clamped below it, and each `SvChunkRow` carries the limits it was judged against so the wording can never quote a threshold that had nothing to do with the flag.

Best practices

• Do: Show sync progress and index stats so stale sources are obvious.
• Do: Use the health variant to surface ingestion failures with actionable alerts.
• Do: Set `[embedTokenLimit]` to your embedding model's real input limit. The 8,192 default is `text-embedding-3`; on a smaller encoder a chunk can be reported healthy while its tail is dropped at embed time — content that is present, searchable-looking and unreachable, which is the worst failure mode in a retrieval system.
• Don't: Don't set `[maxChunkTokens]` above `[embedTokenLimit]`. A target ceiling above the hard limit is the one combination that re-creates the defect the flag exists for; the component clamps it down and says so once in a dev warning.
• Tip: Group sources by status (synced, syncing, failed) for quick triage.

Accessibility

• Status and progress conveyed as text.
• The upload zone is a real `<label>`-wrapped file input — keyboard-focusable and screen-reader labelled.
• Alerts use appropriate roles.
• A flagged chunk states the limit it breached in words — in the badge tooltip and in the row's accessible name — and both quote the limits THAT ROW was judged against rather than whatever the inputs currently say, so a re-render cannot put a fresh threshold into a sentence explaining an old verdict.