Skip to main content
Available for: Python and TypeScript.
Vectra is a modular RAG pipeline SDK (Load → Chunk → Embed → Store → Retrieve → Rerank → Plan → Ground → Generate → Stream). It dispatches lifecycle events to any object in its callbacks config array that implements the matching method — no base class required. ZespanVectraCallbackHandler implements that interface directly, so every stage of the pipeline becomes a Zespan span with no changes to how you call Vectra.

Installation

Setup

Example

What gets captured

Vectra’s callback API doesn’t pass a per-call request ID into the callback arguments — only the query, prompt, or counts for that stage. The handler correlates a query’s retrieval and generation spans using the ambient Zespan trace context, so wrap each request in withZespanTrace() (with_zespan_context() in Python) for correct span grouping under concurrent requests. Without an ambient trace, spans fall back to a single shared slot — correct for one in-flight query at a time, not for concurrent ones on the same client.
Vectra’s callbacks pass retrieval counts, not the retrieved chunks themselves — the retrieval span records how many documents came back, not their content. If you want chunk text on the trace, call recordRetrieval(docs, { query }) (record_retrieval in Python) yourself alongside queryRAG()/query_rag().

Stack-layer metadata

The retrieval span records how many chunks came back (zespan.retrieval.returned, empty) and the query hash, so an empty retrieval is visible even though vectra reports only counts. To record the chunks themselves and mark them in the prompt, see Context segments.