LlamaIndex Integration
Drop-in callback handler for LlamaIndex pipelines. Register LumiqLlamaIndexHandler with Settings.callbackManager and every query, retrieval, and synthesis step is traced.
LlamaIndex is a Python and TypeScript framework for building RAG applications — query engines, retrievers, agents, and data pipelines — over structured and unstructured data.
Getting Started
Install the SDK
Install @zespan/sdk alongside llamaindex.
npm install @zespan/sdk llamaindexRegister the handler
Add LumiqLlamaIndexHandler to Settings.callbackManager before creating your query engine. All queries, retrievals, and synthesis steps are traced automatically from that point.
import { Settings } from 'llamaindex';
import { LumiqLlamaIndexHandler } from '@zespan/sdk';
Settings.callbackManager.addEventHandler(
new LumiqLlamaIndexHandler({
apiKey: process.env.ZESPAN_API_KEY,
})
);
// Your existing query engine code unchanged
const queryEngine = index.asQueryEngine();
const response = await queryEngine.query({ query: 'What is RAG?' });View traces in Zespan
Open Trace Explorer. Each query appears as a trace with the full RAG pipeline — retrieval, reranking, and synthesis — as nested spans.
What's captured automatically
- Full RAG pipeline: query encoding, retrieval, reranking, and synthesis as linked spans
- Retrieved documents: scores, node counts, and chunk content per retrieval span
- Synthesis LLM cost: token usage attributed to the synthesis call separately from retrieval
- Works with query engines, agents, and tools
- LlamaIndex ReAct agents: tool invocations and reasoning steps as child spans
- Faithfulness evals: pair with auto-evaluators for hallucination detection on every response
FAQ
Do I need to modify my index or query engine?
No. Register the handler once with Settings.callbackManager before creating your query engine. All LlamaIndex pipelines in that process are traced automatically.
Does this work for Python LlamaIndex?
The LumiqLlamaIndexHandler is for the JS/TS LlamaIndex SDK. Python LlamaIndex can use the Zespan Python SDK with a similar callback registration pattern.
Start for free — 10K traces/month, no card needed
LlamaIndex integration works on all plans including the free tier.