Installation

RAG Doctor is available on npm as rag-doctor. You can install it globally, use it with npx, or add it as a development dependency in your project.

Requirements

  • Node.js 18 or higher
  • npm, pnpm, or yarn

Global install

Install RAG Doctor globally to use the rag-doctor command anywhere on your system:

bash
# npm
npm install -g rag-doctor
 
# pnpm
pnpm add -g rag-doctor
 
# yarn
yarn global add rag-doctor

Project dependency

Add RAG Doctor as a dev dependency to use it in CI pipelines or project scripts:

bash
# npm
npm install --save-dev rag-doctor
 
# pnpm
pnpm add -D rag-doctor
 
# yarn
yarn add -D rag-doctor

No install (npx)

Run RAG Doctor without installing using npx:

bash
npx rag-doctor analyze ./traces/session.json

npx caching

npx will cache the downloaded package after the first run. Subsequent runs will be fast. To force the latest version, use npx rag-doctor@latest.

Quick start

Once installed, verify the installation and run your first analysis:

bash
# Verify installation
rag-doctor --version
 
# Show help
rag-doctor --help
 
# Analyze a trace file
rag-doctor analyze ./traces/session.json
 
# Get structured JSON output
rag-doctor analyze ./traces/session.json --json

Trace file format

RAG Doctor expects a JSON trace file describing a RAG execution. At minimum, it must contain a query and an array of retrieved chunks:

trace.json
1{
2  "query": "What are the side effects of ibuprofen?",
3  "chunks": [
4    {
5      "id": "chunk-001",
6      "content": "Ibuprofen is a nonsteroidal anti-inflammatory drug (NSAID)...",
7      "score": 0.91,
8      "tokens": 312,
9      "source": "medical-db/ibuprofen-overview.txt"
10    },
11    {
12      "id": "chunk-002",
13      "content": "Common side effects include stomach upset, heartburn...",
14      "score": 0.87,
15      "tokens": 198,
16      "source": "medical-db/ibuprofen-side-effects.txt"
17    }
18  ],
19  "model": "gpt-4o",
20  "totalTokens": 510
21}

Adapters

RAG Doctor can accept trace data from LangChain callbacks, LlamaIndex event hooks, and custom instrumentation. See the architecture docs for details on the ingestion layer.

Next

CLI Reference