Vectra

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

npm install @zespan/sdk vectra-js

pip install zespan vectra-py

Setup

import { VectraClient } from "vectra-js";
import { zespan, ZespanVectraCallbackHandler } from "@zespan/sdk";

zespan.init({ apiKey: process.env.ZESPAN_API_KEY! });

const client = new VectraClient({
  embedding: { provider: "openai", apiKey: process.env.OPENAI_API_KEY! },
  llm: { provider: "openai", apiKey: process.env.OPENAI_API_KEY! },
  database: { type: "postgres", clientInstance: pgClient, tableName: "docs" },
  callbacks: [new ZespanVectraCallbackHandler()],
});

import os
import zespan
from vectra import VectraClient
from zespan.integrations.vectra import ZespanVectraCallbackHandler

zespan.init(api_key=os.environ["ZESPAN_API_KEY"])

client = VectraClient(
    embedding={"provider": "openai", "api_key": os.environ["OPENAI_API_KEY"]},
    llm={"provider": "openai", "api_key": os.environ["OPENAI_API_KEY"]},
    database={"type": "postgres", "client_instance": pg_client, "table_name": "docs"},
    callbacks=[ZespanVectraCallbackHandler()],
)

Example

await client.ingestDocuments("./docs/handbook.pdf");
const result = await client.queryRAG("What's our refund policy?");

client.ingest_documents("./docs/handbook.pdf")
result = client.query_rag("What's our refund policy?")

What gets captured

Stage	Span kind	Fields
Ingestion (`ingestDocuments`/`ingest_documents`)	`embedding`	Chunk count
Retrieval + reranking	`retriever`	Query, retrieved count, reranked count
Generation	`llm`	Prompt/completion text (respects `storePrompts`)
Errors	attached to whichever stage was in flight, or a standalone span	Error message

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().

Overview

CLI

TypeScript SDK

Python SDK

Advanced SDK Configuration

Integrations

LLM Providers

Agent Frameworks

RAG Frameworks

Gateways

Vector Databases

Custom / Other

Guides

Installation

Setup

Example

What gets captured

​Installation

​Setup

​Example

​What gets captured

Installation

Setup

Example

What gets captured