### Vectra JS Quickstart with ChromaDB

Source: https://github.com/iamabhishek-n/vectra-js/blob/master/documentation.md

Minimal setup using ChromaDB for initial use. Ensure environment variables for API keys are set.

```javascript
const { VectraClient, ProviderType, RetrievalStrategy } = require('vectra-js');
const { ChromaClient } = require('chromadb');
const chroma = new ChromaClient();

const config = {
  embedding: { provider: ProviderType.OPENAI, apiKey: process.env.OPENAI_API_KEY, modelName: 'text-embedding-3-small' },
  llm: { provider: ProviderType.GEMINI, apiKey: process.env.GOOGLE_API_KEY, modelName: 'gemini-1.5-pro-latest' },
  database: { type: 'chroma', clientInstance: chroma, tableName: 'rag_collection' },
  retrieval: { strategy: RetrievalStrategy.NAIVE }
};
const client = new VectraClient(config);
await client.ingestDocuments('./docs/hello.txt');
const res = await client.queryRAG('Hello');
console.log(res.answer);
```

--------------------------------

### Vectra.js Quick Start Example

Source: https://github.com/iamabhishek-n/vectra-js/blob/master/README.md

Initialize the Vectra client with OpenAI embeddings, Gemini LLM, and a PostgreSQL database, then ingest documents and perform a RAG query.

```javascript
const { VectraClient, ProviderType } = require('vectra-js');
const { Pool } = require('pg');

const pool = new Pool({
  connectionString: process.env.DATABASE_URL
});

const client = new VectraClient({
  embedding: {
    provider: ProviderType.OPENAI,
    apiKey: process.env.OPENAI_API_KEY,
    modelName: 'text-embedding-3-small'
  },
  llm: {
    provider: ProviderType.GEMINI,
    apiKey: process.env.GOOGLE_API_KEY,
    modelName: 'gemini-2.5-flash'
  },
  database: {
    type: 'postgres',
    clientInstance: pool,
    tableName: 'document',
    columnMap: { 'content': 'content', 'metadata': 'metadata', 'vector': 'vector' }
  }
});

await client.ingestDocuments('./docs');
const res = await client.queryRAG('What is the vacation policy?');
console.log(res.answer);
```

--------------------------------

### Launch WebConfig UI

Source: https://github.com/iamabhishek-n/vectra-js/blob/master/README.md

Start the WebConfig UI for interactively building and validating a `vectra.config.json` file. Ideal for initial setup and non-backend users.

```bash
vectra webconfig
```

--------------------------------

### Vectra CLI Usage Examples

Source: https://context7.com/iamabhishek-n/vectra-js/llms.txt

Demonstrates common commands for the vectra-js CLI, including installation, document ingestion, querying (streaming and non-streaming), and launching utility UIs.

```bash
# Install globally
npm i -g vectra-js

# Ingest documents
vectra ingest ./docs --config=./vectra-config.json

# Query (non-streaming)
vectra query "What is the vacation policy?" --config=./vectra-config.json

# Query with streaming
vectra query "Summarize the Q3 report" --config=./vectra-config.json --stream

# Launch the WebConfig UI (browser-based config builder at http://localhost:PORT)
vectra webconfig

# Launch the Observability Dashboard (browser-based trace/metric viewer)
vectra dashboard
```

--------------------------------

### Install Vectra.js Library

Source: https://github.com/iamabhishek-n/vectra-js/blob/master/README.md

Install the core Vectra.js library using npm or pnpm.

```bash
npm install vectra-js
# or
pnpm add vectra-js
```

--------------------------------

### Initialize Qdrant Client

Source: https://github.com/iamabhishek-n/vectra-js/blob/master/documentation.md

Example of how to initialize the Qdrant client, requiring the URL and API key for connecting to a Qdrant instance.

```javascript
const qdrant = new QdrantClient({ url, apiKey });
```

--------------------------------

### Initialize ChromaDB Client

Source: https://github.com/iamabhishek-n/vectra-js/blob/master/documentation.md

Example of how to initialize the ChromaDB client for local collection management. Assumes ChromaDB is running locally.

```javascript
const { ChromaClient } = require('chromadb'); const chroma = new ChromaClient();
```

--------------------------------

### Install Vectra.js CLI

Source: https://github.com/iamabhishek-n/vectra-js/blob/master/README.md

Install the Vectra.js command-line interface globally using npm or pnpm.

```bash
npm i -g vectra-js
```

```bash
# or
pnpm add -g vectra-js
```

--------------------------------

### Initialize Milvus Client

Source: https://github.com/iamabhishek-n/vectra-js/blob/master/documentation.md

Example of how to initialize the Milvus client, specifying the address for connecting to a Milvus cluster.

```javascript
const milvus = new MilvusClient({ address });
```

--------------------------------

### Vectra.js Configuration File Example

Source: https://context7.com/iamabhishek-n/vectra-js/llms.txt

An example JSON configuration file for Vectra.js, specifying settings for embedding, LLM, database, retrieval strategy, and observability.

```json
{
  "embedding": {
    "provider": "openai",
    "apiKey": "sk-...",
    "modelName": "text-embedding-3-small"
  },
  "llm": {
    "provider": "openai",
    "apiKey": "sk-...",
    "modelName": "gpt-4o"
  },
  "database": {
    "type": "postgres",
    "tableName": "document",
    "columnMap": { "content": "content", "metadata": "metadata", "vector": "vector" }
  },
  "retrieval": { "strategy": "hybrid" },
  "observability": { "enabled": true, "sqlitePath": "./vectra-observability.db" }
}
```

--------------------------------

### Install Backend Dependencies for Vectra.js

Source: https://github.com/iamabhishek-n/vectra-js/blob/master/README.md

Install specific backend dependencies based on your chosen vector store or database.

```bash
npm install pg                    # https://node-postgres.com/
```

```bash
npm install @prisma/client       # https://prisma.io/docs
```

```bash
npm install chromadb              # https://docs.trychroma.com/
```

```bash
npm install qdrant-client         # https://qdrant.tech/documentation/
```

```bash
npm install pymilvus              # https://milvus.io/docs/
```

--------------------------------

### Install vectra-js

Source: https://context7.com/iamabhishek-n/vectra-js/llms.txt

Install the core vectra-js package using npm or pnpm. Optional backend packages may be required depending on your chosen database or ORM.

```bash
npm install vectra-js
# or
pnpm add vectra-js
```

```bash
npm install pg                   # PostgreSQL (native)
npm install @prisma/client       # Prisma ORM
npm install chromadb             # ChromaDB
npm install qdrant-client        # Qdrant
```

--------------------------------

### Launch Observability Dashboard

Source: https://github.com/iamabhishek-n/vectra-js/blob/master/README.md

Start the local Observability Dashboard UI, backed by SQLite, to visualize ingestion/query latency, retrieval/generation traces, and chat sessions.

```bash
vectra dashboard
```

--------------------------------

### Example Metadata Enrichment Output

Source: https://context7.com/iamabhishek-n/vectra-js/llms.txt

Illustrates the structure of metadata added to each chunk when enrichment is enabled. Includes summary, keywords, and hypothetical questions.

```json
{
  summary: "This section describes the company's 20-day annual leave policy...",
  keywords: ["leave", "vacation", "annual", "policy", "days", ...],
  hypothetical_questions: ["How many vacation days do employees get?", ...]
}
```

--------------------------------

### Example Reranking Query

Source: https://context7.com/iamabhishek-n/vectra-js/llms.txt

Demonstrates a query that utilizes reranking. The system retrieves documents, reranks them using the configured LLM, and returns the top N most relevant results.

```javascript
const result = await client.queryRAG('Explain the employee benefits package');
// Retrieves 20 docs, LLM reranks them, returns top 5 most relevant
```

--------------------------------

### Ingest Documents with Logging Callbacks

Source: https://context7.com/iamabhishek-n/vectra-js/llms.txt

Shows how to ingest documents while observing progress using a LoggingCallbackHandler. This setup is useful for monitoring ingestion status and performance, especially for large datasets.

```javascript
const { LoggingCallbackHandler } = require('vectra-js');

const clientWithLogs = new VectraClient({
  embedding: { provider: ProviderType.OPENAI, apiKey: process.env.OPENAI_API_KEY, modelName: 'text-embedding-3-small' },
  llm: { provider: ProviderType.GEMINI, apiKey: process.env.GOOGLE_API_KEY, modelName: 'gemini-2.5-flash' },
  database: { type: 'postgres', clientInstance: pool, tableName: 'doc',
    columnMap: { content: 'content', metadata: 'metadata', vector: 'vector' } },
  callbacks: [new LoggingCallbackHandler()]
});

await clientWithLogs.ingestDocuments('./contracts');
// [RAG] Starting ingestion: ./contracts
// [RAG] Finished ingestion. Chunks: 142 (3812 ms)
```

--------------------------------

### Vectra.js Configuration Object

Source: https://github.com/iamabhishek-n/vectra-js/blob/master/documentation.md

Defines the centralized configuration for providers, database, and pipeline options. Copy-paste this template to customize your Vectra.js setup.

```javascript
const { ProviderType, ChunkingStrategy, RetrievalStrategy } = require('vectra-js');
const config = {
  // Embedding
  embedding: {
    provider: ProviderType.OPENAI,
    apiKey: process.env.OPENAI_API_KEY,
    modelName: 'text-embedding-3-small',
    // dimensions: 1536
  },
  // LLM (generation)
  llm: {
    provider: ProviderType.GEMINI,
    apiKey: process.env.GOOGLE_API_KEY,
    modelName: 'gemini-1.5-pro-latest',
    // temperature: 0.3,
    // maxTokens: 1024,
    // defaultHeaders: {} // OpenRouter only
  },
  // Memory (toggleable, defaults off)
  memory: {
    enabled: false,
    type: 'in-memory', // or 'redis' | 'postgres'
    maxMessages: 20,
    // Redis options
    redis: { 
      clientInstance: /* redis client */, 
      keyPrefix: 'vectra:chat:' 
    },
    // Postgres options
    postgres: {
      clientInstance: /* Prisma client */,
      tableName: 'ChatMessage',
      columnMap: { sessionId: 'sessionId', role: 'role', content: 'content', createdAt: 'createdAt' }
    }
  },
  // Ingestion (rate limit is toggleable, defaults off)
  ingestion: { rateLimitEnabled: false, concurrencyLimit: 5 },
  // Database
  database: {
    type: 'chroma', // 'prisma' | 'qdrant' | 'milvus'
    clientInstance: null, // your DB client
    tableName: 'Document',
    columnMap: { content: 'content', vector: 'embedding', metadata: 'metadata' } // Prisma only
  },
  // Chunking
  chunking: {
    strategy: ChunkingStrategy.RECURSIVE, // or ChunkingStrategy.AGENTIC
    chunkSize: 1000,
    chunkOverlap: 200,
    // separators: ['\n\n', '\n', ' ', '']
    // agenticLlm: { provider: ProviderType.OPENAI, apiKey: process.env.OPENAI_API_KEY, modelName: 'gpt-4o-mini' } // required for AGENTIC
  },
  // Retrieval
  retrieval: {
    strategy: RetrievalStrategy.HYBRID, // NAIVE | HYDE | MULTI_QUERY | HYBRID | MMR
    // llmConfig: { provider: ProviderType.OPENAI, apiKey: process.env.OPENAI_API_KEY, modelName: 'gpt-4o-mini' }, // HYDE/MULTI_QUERY
    // hybridAlpha: 0.5 // tuning
    // mmrLambda: 0.5,
    // mmrFetchK: 20
  },
  // Reranking
  reranking: {
    enabled: false,
    // topN: 5,
    // windowSize: 20,
    // llmConfig: { provider: ProviderType.ANTHROPIC, apiKey: process.env.ANTHROPIC_API_KEY, modelName: 'claude-3-haiku' }
  },
  // Metadata
  metadata: { enrichment: false }, // summary, keywords, hypothetical_questions
  // Query Planning
  queryPlanning: { tokenBudget: 2048, preferSummariesBelow: 1024, includeCitations: true },
  // Grounding
  grounding: { enabled: false, strict: false, maxSnippets: 4 },
  // Generation
  generation: { outputFormat: 'text', structuredOutput: 'none' }, // 'json' and 'citations' supported
  // Prompts
  prompts: { query: 'Use only the following context.\nContext:\n{{context}}\n\nQ: {{question}}' },
  // Callbacks
  callbacks: []
};

```

--------------------------------

### Implement Custom VectorStore in Vectra.js

Source: https://context7.com/iamabhishek-n/vectra-js/llms.txt

Example of extending the VectorStore base class to create a custom vector store implementation. This involves overriding methods for document operations and search.

```javascript
const { VectorStore } = require('vectra-js');

class MyCustomStore extends VectorStore {
  async addDocuments(documents) {
    // documents: Array<{ id: string, content: string, embedding: number[], metadata: object }>
    for (const doc of documents) {
      await myDb.insert({ id: doc.id, vec: doc.embedding, text: doc.content, meta: doc.metadata });
    }
  }

  async upsertDocuments(documents) {
    for (const doc of documents) {
      await myDb.upsert({ id: doc.id, vec: doc.embedding, text: doc.content, meta: doc.metadata });
    }
  }

  async similaritySearch(vector, limit = 5, filter = null) {
    const rows = await myDb.vectorSearch(vector, limit, filter);
    return rows.map(r => ({ content: r.text, metadata: r.meta, score: r.similarity }));
  }

  async hybridSearch(text, vector, limit = 5, filter = null) {
    // Optional: implement combined semantic + keyword search
    return this.similaritySearch(vector, limit, filter);
  }

  async listDocuments({ filter, limit, cursor } = {}) {
    const docs = await myDb.list(filter, limit, cursor);
    return { documents: docs, nextCursor: docs.length === limit ? docs.at(-1).id : null };
  }

  async deleteDocuments({ ids, filter } = {}) {
    if (ids) await myDb.deleteByIds(ids);
    else if (filter) await myDb.deleteByFilter(filter);
  }

  async fileExists(sha256, size, lastModified) {
    return myDb.exists({ fileSHA256: sha256, fileSize: size, lastModified });
  }
}

// Inject the custom store by wrapping the config
const client = new VectraClient({
  embedding: { provider: ProviderType.OPENAI, apiKey: process.env.OPENAI_API_KEY, modelName: 'text-embedding-3-small' },
  llm: { provider: ProviderType.OPENAI, apiKey: process.env.OPENAI_API_KEY, modelName: 'gpt-4o-mini' },
  database: { type: 'postgres', clientInstance: pool, tableName: 'doc',
    columnMap: { content: 'content', metadata: 'metadata', vector: 'vector' } }
});
client.vectorStore = new MyCustomStore(); // Override after construction
```

--------------------------------

### Tailwind CSS Configuration and Theme Setup

Source: https://github.com/iamabhishek-n/vectra-js/blob/master/src/dashboard/index.html

Configure Tailwind CSS with custom colors and theme extensions. This setup includes a 'brand' color palette and dark mode specific colors.

```javascript
tailwind.config = {
  darkMode: 'class',
  theme: {
    extend: {
      colors: {
        brand: {
          50: '#f5f3ff',
          100: '#ede9fe',
          200: '#ddd6fe',
          300: '#c4b5fd',
          400: '#a78bfa',
          500: '#8b5cf6',
          600: '#7c3aed',
          700: '#6d28d9',
          800: '#5b21b6',
          900: '#4c1d95',
          950: '#2e1065',
        },
        dark: {
          950: '#020204',
          900: '#08080C',
          850: '#0F0F16',
          800: '#14141F',
          700: '#1C1C2E',
        }
      }
    }
  }
}
```

--------------------------------

### Database Configuration (Qdrant)

Source: https://github.com/iamabhishek-n/vectra-js/blob/master/README.md

Configure the Qdrant vector store using its client instance and collection name.

```javascript
// Qdrant
database: {
  type: 'qdrant',
  clientInstance: qdrantClient,
  collectionName: 'rag_collection'
}
```

--------------------------------

### Configure Token Budget for Context Assembly

Source: https://context7.com/iamabhishek-n/vectra-js/llms.txt

Control the token budget for context assembly during query planning. Use chunk summaries for efficiency when the token count is below a specified threshold.

```javascript
const clientBudget = new VectraClient({
  /* ...required config... */
  queryPlanning: {
    tokenBudget: 4096,
    preferSummariesBelow: 512     // Use chunk summaries if token count is under this threshold
  }
});
```

--------------------------------

### VectraClient Constructor

Source: https://context7.com/iamabhishek-n/vectra-js/llms.txt

The main entry point for the SDK. It initializes all necessary components for a RAG pipeline, including embedding models, LLMs, vector stores, and observability features, through a single configuration object.

```APIDOC
## VectraClient Constructor

The main entry point. Accepts a single configuration object validated by `RAGConfigSchema` (Zod). Initializes the embedding backend, generation LLM, vector store, chunker, memory, observability logger, and reranker in one call.

```js
const { VectraClient, ProviderType, ChunkingStrategy, RetrievalStrategy } = require('vectra-js');
const { Pool } = require('pg');

const pool = new Pool({ connectionString: process.env.DATABASE_URL });

const client = new VectraClient({
  // --- Required ---
  embedding: {
    provider: ProviderType.OPENAI,
    apiKey: process.env.OPENAI_API_KEY,
    modelName: 'text-embedding-3-small',
    dimensions: 1536                      // Must match pgvector column dimension
  },
  llm: {
    provider: ProviderType.GEMINI,
    apiKey: process.env.GOOGLE_API_KEY,
    modelName: 'gemini-2.5-flash',
    temperature: 0.2,
    maxTokens: 2048
  },
  database: {
    type: 'postgres',
    clientInstance: pool,
    tableName: 'document',
    columnMap: { content: 'content', metadata: 'metadata', vector: 'vector' }
  },

  // --- Optional ---
  chunking: {
    strategy: ChunkingStrategy.RECURSIVE,
    chunkSize: 1000,
    chunkOverlap: 200
  },
  retrieval: {
    strategy: RetrievalStrategy.HYBRID
  },
  reranking: {
    enabled: true,
    topN: 5,
    windowSize: 20
  },
  memory: {
    enabled: true,
    type: 'in-memory',
    maxMessages: 20
  },
  observability: {
    enabled: true,
    sqlitePath: './vectra-observability.db'
  },
  telemetry: { enabled: false }           // Opt-out of anonymous telemetry
});
```
```

--------------------------------

### Initialize VectraClient with OpenRouter Backend

Source: https://context7.com/iamabhishek-n/vectra-js/llms.txt

Set up Vectra.js to use OpenRouter for LLM access, leveraging a wide range of models. OpenAI is used for embeddings as OpenRouter does not support them directly.

```javascript
const { VectraClient, ProviderType } = require('vectra-js');

// OpenRouter provides access to 100+ models via a single API
const client = new VectraClient({
  embedding: {                            // OpenRouter does NOT support embeddings
    provider: ProviderType.OPENAI,        // Use OpenAI for embeddings
    apiKey: process.env.OPENAI_API_KEY,
    modelName: 'text-embedding-3-small'
  },
  llm: {
    provider: ProviderType.OPENROUTER,
    apiKey: process.env.OPENROUTER_API_KEY,
    modelName: 'anthropic/claude-3.5-sonnet',
    defaultHeaders: {
      'HTTP-Referer': 'https://myapp.com',
      'X-Title': 'My RAG App'
    }
  },
  database: { type: 'postgres', clientInstance: pool, tableName: 'doc',
    columnMap: { content: 'content', metadata: 'metadata', vector: 'vector' } }
});
```

--------------------------------

### Database Configuration (Prisma)

Source: https://github.com/iamabhishek-n/vectra-js/blob/master/README.md

Configure the database connection for Prisma, providing the Prisma client instance, table name, and column mappings.

```javascript
// Prisma
database: {
  type: 'prisma',
  clientInstance: prisma,
  tableName: 'Document',
  columnMap: { content: 'content', metadata: 'metadata', vector: 'embedding' }
}
```

--------------------------------

### Observability Configuration

Source: https://github.com/iamabhishek-n/vectra-js/blob/master/README.md

Enable observability features and specify the SQLite database path for storing logs.

```javascript
observability: {
  enabled: true,
  sqlitePath: 'vectra-observability.db'
}
```

--------------------------------

### Implement Data Transformation with Middleware

Source: https://context7.com/iamabhishek-n/vectra-js/llms.txt

Use `VectraMiddleware` to intercept and modify data at various stages of the RAG pipeline. Examples include PII redaction before chunking and after generation, or query expansion before retrieval.

```javascript
const { VectraMiddleware } = require('vectra-js');

class PIIRedactionMiddleware extends VectraMiddleware {
  async onBeforeChunk(text, config) {
    // Redact SSNs before chunking
    return text.replace(/\b\d{3}-\d{2}-\d{4}\b/g, '[SSN_REDACTED]');
  }

  async onAfterGenerate(answer, sources) {
    // Post-process the generated answer
    const cleanAnswer = answer.replace(/\b\d{3}-\d{2}-\d{4}\b/g, '[REDACTED]');
    return [cleanAnswer, sources];
  }
}

class QueryExpansionMiddleware extends VectraMiddleware {
  async onBeforeRetrieve(query, vector) {
    console.log(`Query before retrieval: ${query}`);
    return [query, vector];  // Can modify both query text and vector
  }

  async onAfterEmbed(chunks, embeddings) {
    console.log(`Embedded ${chunks.length} chunks`);
    return [chunks, embeddings];
  }
}

const client = new VectraClient({
  /* ...config... */
  middlewares: [new PIIRedactionMiddleware(), new QueryExpansionMiddleware()]
});
```

--------------------------------

### Database Configuration (Milvus)

Source: https://github.com/iamabhishek-n/vectra-js/blob/master/README.md

Configure the Milvus vector store using its client instance and collection name.

```javascript
// Milvus
database: {
  type: 'milvus',
  clientInstance: milvusClient,
  collectionName: 'rag_collection'
}
```

--------------------------------

### Database Configuration (ChromaDB)

Source: https://github.com/iamabhishek-n/vectra-js/blob/master/README.md

Configure the ChromaDB vector store using its client instance and collection name.

```javascript
// ChromaDB
database: {
  type: 'chroma',
  clientInstance: chromaClient,
  collectionName: 'rag_collection'
}
```

--------------------------------

### Initialize VectraClient with Ollama Backend

Source: https://context7.com/iamabhishek-n/vectra-js/llms.txt

Configure Vectra.js to use local Ollama models for embeddings and LLM. Ensure Ollama is running locally.

```javascript
const { VectraClient, ProviderType } = require('vectra-js');

// Ollama must be running locally: https://ollama.ai
const client = new VectraClient({
  embedding: {
    provider: ProviderType.OLLAMA,
    modelName: 'nomic-embed-text',
    baseUrl: 'http://localhost:11434'   // Default Ollama URL
  },
  llm: {
    provider: ProviderType.OLLAMA,
    modelName: 'llama3.2',
    baseUrl: 'http://localhost:11434'
  },
  database: { type: 'postgres', clientInstance: pool, tableName: 'doc',
    columnMap: { content: 'content', metadata: 'metadata', vector: 'vector' } }
});

await client.ingestDocuments('./docs');
const result = await client.queryRAG('Summarize the main points');
// Runs entirely locally — no API keys required
```

--------------------------------

### Ingest Data and Query

Source: https://github.com/iamabhishek-n/vectra-js/blob/master/README.md

Ingest data from a specified directory and query the knowledge base using a configuration file. Supports streaming results.

```bash
vectra ingest ./docs --config=./config.json
```

```bash
vectra query "What is our leave policy?" --config=./config.json --stream
```

--------------------------------

### Query Vector Database using Vectra CLI

Source: https://github.com/iamabhishek-n/vectra-js/blob/master/documentation.md

Command-line instruction to query the vector database with a specific question, using a configuration file and enabling streaming output.

```bash
vectra query "What is our leave policy?" --config=./config.json --stream
```

--------------------------------

### ChromaDB Database Backend

Source: https://context7.com/iamabhishek-n/vectra-js/llms.txt

Integrate Vectra.js with ChromaDB for vector storage and retrieval. Initialize the ChromaDB client and configure the Vectra client with the ChromaDB type, client instance, and collection name.

```javascript
const { ChromaClient } = require('chromadb');
const { VectraClient, ProviderType } = require('vectra-js');

const chromaClient = new ChromaClient({ path: 'http://localhost:8000' });

const client = new VectraClient({
  embedding: { provider: ProviderType.OPENAI, apiKey: process.env.OPENAI_API_KEY, modelName: 'text-embedding-3-small' },
  llm: { provider: ProviderType.GEMINI, apiKey: process.env.GOOGLE_API_KEY, modelName: 'gemini-2.5-flash' },
  database: {
    type: 'chroma',
    clientInstance: chromaClient,
    tableName: 'rag_collection'         // ChromaDB collection name
  }
});

await client.ingestDocuments('./knowledge-base');
const result = await client.queryRAG('What are the system requirements?');
console.log(result.answer);
```

--------------------------------

### VectraClient Constructor

Source: https://github.com/iamabhishek-n/vectra-js/blob/master/documentation.md

Initializes a new VectraClient instance with the provided configuration.

```APIDOC
## new VectraClient(config: VectraConfig)

### Description
Initializes a new VectraClient instance.

### Parameters
#### Path Parameters
- **config** (VectraConfig) - Required - The configuration object for the Vectra client.
```

--------------------------------

### Configure Custom LLM for Reranking

Source: https://context7.com/iamabhishek-n/vectra-js/llms.txt

Use a custom, potentially cheaper LLM for reranking to control costs. Specify the LLM configuration within the reranking settings.

```javascript
// Custom LLM for reranking (cost control: use cheap model for reranking)
const clientCustomRerank = new VectraClient({
  /* ...required config... */
  reranking: {
    enabled: true,
    provider: RerankingProvider.LLM,
    llmConfig: {
      provider: ProviderType.OPENAI,
      apiKey: process.env.OPENAI_API_KEY,
      modelName: 'gpt-4o-mini'   // Cheaper model for reranking
    },
    topN: 5,
    windowSize: 25
  }
});
```

--------------------------------

### Reranking Configuration

Source: https://github.com/iamabhishek-n/vectra-js/blob/master/README.md

Enable reranking with specified window size and top N results.

```javascript
reranking: {
  enabled: true,
  windowSize: 20,
  topN: 5
}
```

--------------------------------

### Initialize VectraClient

Source: https://context7.com/iamabhishek-n/vectra-js/llms.txt

Initialize the VectraClient with a comprehensive configuration object. This client orchestrates the entire RAG pipeline, including embeddings, LLM, vector store, and more. Ensure all required parameters are provided and optional ones are configured as needed.

```javascript
const { VectraClient, ProviderType, ChunkingStrategy, RetrievalStrategy } = require('vectra-js');
const { Pool } = require('pg');

const pool = new Pool({ connectionString: process.env.DATABASE_URL });

const client = new VectraClient({
  // --- Required ---
  embedding: {
    provider: ProviderType.OPENAI,
    apiKey: process.env.OPENAI_API_KEY,
    modelName: 'text-embedding-3-small',
    dimensions: 1536                      // Must match pgvector column dimension
  },
  llm: {
    provider: ProviderType.GEMINI,
    apiKey: process.env.GOOGLE_API_KEY,
    modelName: 'gemini-2.5-flash',
    temperature: 0.2,
    maxTokens: 2048
  },
  database: {
    type: 'postgres',
    clientInstance: pool,
    tableName: 'document',
    columnMap: { content: 'content', metadata: 'metadata', vector: 'vector' }
  },

  // --- Optional ---
  chunking: {
    strategy: ChunkingStrategy.RECURSIVE,
    chunkSize: 1000,
    chunkOverlap: 200
  },
  retrieval: {
    strategy: RetrievalStrategy.HYBRID
  },
  reranking: {
    enabled: true,
    topN: 5,
    windowSize: 20
  },
  memory: {
    enabled: true,
    type: 'in-memory',
    maxMessages: 20
  },
  observability: {
    enabled: true,
    sqlitePath: './vectra-observability.db'
  },
  telemetry: { enabled: false }           // Opt-out of anonymous telemetry
});
```

--------------------------------

### Database Configuration (PostgreSQL)

Source: https://github.com/iamabhishek-n/vectra-js/blob/master/README.md

Configure the database connection for PostgreSQL using a native pg Pool instance, specifying the table name and column mappings.

```javascript
// PostgreSQL (native pg)
database: {
  type: 'postgres',
  clientInstance: pool, // new Pool(...)
  tableName: 'document',
  columnMap: { content: 'content', metadata: 'metadata', vector: 'vector' }
}
```

--------------------------------

### Configure VectraClient with Recursive Chunking

Source: https://context7.com/iamabhishek-n/vectra-js/llms.txt

Sets up the VectraClient using the default RECURSIVE chunking strategy, which is sentence- and structure-aware with entropy-based overlap. Specify chunk size and overlap for optimal splitting.

```javascript
const { ChunkingStrategy, ProviderType } = require('vectra-js');

// RECURSIVE (default): sentence- and structure-aware splitting with entropy-based overlap
const clientRecursive = new VectraClient({
  embedding: { provider: ProviderType.OPENAI, apiKey: process.env.OPENAI_API_KEY, modelName: 'text-embedding-3-small' },
  llm: { provider: ProviderType.OPENAI, apiKey: process.env.OPENAI_API_KEY, modelName: 'gpt-4o-mini' },
  database: { type: 'postgres', clientInstance: pool, tableName: 'doc',
    columnMap: { content: 'content', metadata: 'metadata', vector: 'vector' } },
  chunking: {
    strategy: ChunkingStrategy.RECURSIVE,
    chunkSize: 800,
    chunkOverlap: 150
  }
});
```

--------------------------------

### Ingest Documents using Vectra CLI

Source: https://github.com/iamabhishek-n/vectra-js/blob/master/documentation.md

Command-line instruction to ingest documents from a specified directory into the vector database using a configuration file.

```bash
vectra ingest ./docs --config=./config.json
```

--------------------------------

### PostgreSQL Database Backend

Source: https://context7.com/iamabhishek-n/vectra-js/llms.txt

Configure Vectra.js to use PostgreSQL with pgvector for similarity search, hybrid search, and index management. Ensure the `Pool` is initialized and the database configuration includes the client instance, table name, and column mapping.

```javascript
const { Pool } = require('pg');
const { VectraClient, ProviderType, RetrievalStrategy } = require('vectra-js');

const pool = new Pool({ connectionString: process.env.DATABASE_URL });

const client = new VectraClient({
  embedding: { provider: ProviderType.OPENAI, apiKey: process.env.OPENAI_API_KEY, modelName: 'text-embedding-3-small', dimensions: 1536 },
  llm: { provider: ProviderType.OPENAI, apiKey: process.env.OPENAI_API_KEY, modelName: 'gpt-4o' },
  database: {
    type: 'postgres',
    clientInstance: pool,
    tableName: 'document',              // Or schema-qualified: 'myschema.document'
    columnMap: {
      content: 'content',
      metadata: 'metadata',
      vector: 'vector'
    }
  },
  retrieval: { strategy: RetrievalStrategy.HYBRID }
});

// Tables and HNSW indexes are created automatically on first ingest
await client.ingestDocuments('./docs');
const result = await client.queryRAG('What does the contract say about liability?');
```

--------------------------------

### Initialize Lucide Icons

Source: https://github.com/iamabhishek-n/vectra-js/blob/master/src/dashboard/trace.html

Initializes Lucide icons on the page. This function should be called to ensure all icons are rendered correctly.

```javascript
lucide.createIcons();
```

--------------------------------

### Configure Postgres Conversation Memory

Source: https://context7.com/iamabhishek-n/vectra-js/llms.txt

Set up persistent conversation memory with a PostgreSQL database. Requires a pre-existing ChatMessage table and a configured database pool.

```javascript
const clientPgMemory = new VectraClient({
  /* ...required config... */
  memory: {
    enabled: true,
    type: 'postgres',
    maxMessages: 50,
    postgres: {
      clientInstance: pool,
      tableName: 'ChatMessage',
      columnMap: { sessionId: 'sessionId', role: 'role', content: 'content', createdAt: 'createdAt' }
    }
  }
});
```

--------------------------------

### Retrieval Configuration (Hybrid)

Source: https://github.com/iamabhishek-n/vectra-js/blob/master/README.md

Configure the retrieval strategy to use HYBRID, which is recommended for production environments.

```javascript
retrieval: { strategy: RetrievalStrategy.HYBRID }
```

--------------------------------

### Enable Observability with SQLite

Source: https://context7.com/iamabhishek-n/vectra-js/llms.txt

Configure Vectra.js to log traces, metrics, and sessions to a local SQLite database for dashboard access. Ensure the observability object is correctly configured with enabled, sqlitePath, projectId, and tracking options.

```javascript
const client = new VectraClient({
  /* ...required config... */
  observability: {
    enabled: true,
    sqlitePath: './logs/vectra-observability.db',
    projectId: 'my-rag-app',
    trackMetrics: true,
    trackTraces: true,
    trackLogs: true,
    sessionTracking: true
  }
});

// All queries automatically log:
// - Retrieval latency (ms)
// - Generation latency (ms)
// - Total query latency (ms)
// - Documents found count
// - Prompt and completion character counts
// - Full trace spans (retrieval → generation)

await client.queryRAG('What is the refund policy?', null, false, 'session-001');
// Metrics recorded: query_latency, retrieval_latency, generation_latency, prompt_chars, completion_chars
// Traces recorded:  retrieval span, generation span, root queryRAG span
```

--------------------------------

### Prisma Database Backend

Source: https://context7.com/iamabhishek-n/vectra-js/llms.txt

Connect Vectra.js to a database managed by Prisma. Configure the Vectra client with the Prisma type, client instance, table name, and column mapping, ensuring the Prisma schema includes the necessary fields for content, metadata, and vector.

```javascript
const { PrismaClient } = require('@prisma/client');
const { VectraClient, ProviderType } = require('vectra-js');

const prisma = new PrismaClient();

// Required Prisma schema:
// model Document {
//   id        String   @id @default(uuid())
//   content   String
//   metadata  Json
//   vector    Unsupported("vector")?
//   createdAt DateTime @default(now())
// }

const client = new VectraClient({
  embedding: { provider: ProviderType.OPENAI, apiKey: process.env.OPENAI_API_KEY, modelName: 'text-embedding-3-small' },
  llm: { provider: ProviderType.OPENAI, apiKey: process.env.OPENAI_API_KEY, modelName: 'gpt-4o' },
  database: {
    type: 'prisma',
    clientInstance: prisma,
    tableName: 'Document',
    columnMap: { content: 'content', metadata: 'metadata', vector: 'vector' }
  }
});

await client.ingestDocuments('./docs');
```

--------------------------------

### Memory Configuration (Redis)

Source: https://github.com/iamabhishek-n/vectra-js/blob/master/README.md

Configure Redis for conversation memory, including the client instance, key prefix, and maximum number of messages.

```javascript
// Redis
memory: {
  enabled: true,
  type: 'redis',
  maxMessages: 20,
  redis: {
    clientInstance: redisClient,
    keyPrefix: 'vectra:chat:'
  }
}
```

--------------------------------

### Extend Vectra with Custom Vector Store

Source: https://github.com/iamabhishek-n/vectra-js/blob/master/README.md

Implement a custom vector store by extending the `VectorStore` class and implementing `addDocuments` and `similaritySearch` methods.

```javascript
class MyStore extends VectorStore {
  async addDocuments() {}
  async similaritySearch() {}
}
```

--------------------------------

### Memory Configuration (Postgres)

Source: https://github.com/iamabhishek-n/vectra-js/blob/master/README.md

Configure PostgreSQL for conversation memory, specifying the client instance, table name, column mappings, and maximum messages.

```javascript
// Postgres
memory: {
  enabled: true,
  type: 'postgres',
  maxMessages: 20,
  postgres: {
    clientInstance: pool, // pg Pool
    tableName: 'ChatMessage',
    columnMap: {
      sessionId: 'sessionId',
      role: 'role',
      content: 'content',
      createdAt: 'createdAt'
    }
  }
}
```

--------------------------------

### Configure VectraClient with Hybrid Retrieval

Source: https://context7.com/iamabhishek-n/vectra-js/llms.txt

Sets up the VectraClient for HYBRID retrieval, combining semantic search with BM25 keyword search using RRF. This is recommended for most production use cases. Adjust hybridAlpha to balance semantic and lexical search.

```javascript
const { RetrievalStrategy } = require('vectra-js');

// RetrievalStrategy.NAIVE       → cosine similarity
// RetrievalStrategy.HYDE        → Hypothetical Document Embeddings (requires llmConfig)
// RetrievalStrategy.MULTI_QUERY → multi-query expansion + RRF (requires llmConfig)
// RetrievalStrategy.HYBRID      → semantic + BM25 keyword search with RRF (recommended for production)
// RetrievalStrategy.MMR         → Maximal Marginal Relevance (diversity-optimized)

const client = new VectraClient({
  embedding: { provider: ProviderType.OPENAI, apiKey: process.env.OPENAI_API_KEY, modelName: 'text-embedding-3-small' },
  llm: { provider: ProviderType.OPENAI, apiKey: process.env.OPENAI_API_KEY, modelName: 'gpt-4o' },
  database: { type: 'postgres', clientInstance: pool, tableName: 'doc',
    columnMap: { content: 'content', metadata: 'metadata', vector: 'vector' } },
  retrieval: {
    strategy: RetrievalStrategy.HYBRID,    // Best for most production use cases
    hybridAlpha: 0.5                       // 0=pure lexical, 1=pure semantic
  }
});
```

--------------------------------

### Theme Persistence and Application Logic

Source: https://github.com/iamabhishek-n/vectra-js/blob/master/src/dashboard/index.html

JavaScript code to manage theme persistence using localStorage and apply the 'dark' class to the document element based on user preference or system settings.

```javascript
// Check for saved theme preference or use system preference
if (localStorage.getItem('color-theme') === 'dark' || (!('color-theme' in localStorage) && window.matchMedia('(prefers-color-scheme: dark)').matches)) {
  document.documentElement.classList.add('dark');
} else {
  document.documentElement.classList.remove('dark');
}
```

--------------------------------

### Configure VectraClient with HyDE Retrieval

Source: https://context7.com/iamabhishek-n/vectra-js/llms.txt

Sets up the VectraClient for Hypothetical Document Embeddings (HyDE) retrieval. This strategy generates a hypothetical answer to find similar real documents. Requires an LLM configuration for generating the hypothetical document.

```javascript
const { RetrievalStrategy } = require('vectra-js');

// HyDE — generates a hypothetical answer to find similar real documents
const clientHyde = new VectraClient({
  /* embedding, llm, database as above */
  retrieval: {
    strategy: RetrievalStrategy.HYDE,
    llmConfig: {                           // LLM used to generate the hypothetical doc
      provider: ProviderType.OPENAI,
      apiKey: process.env.OPENAI_API_KEY,
      modelName: 'gpt-4o-mini'
    }
  }
});
```

--------------------------------

### Configure Redis Conversation Memory

Source: https://context7.com/iamabhishek-n/vectra-js/llms.txt

Enable distributed and persistent conversation memory using Redis. Requires an ioredis client instance and a key prefix for chat sessions.

```javascript
const redis = require('ioredis');
const redisClient = new redis(process.env.REDIS_URL);

const clientRedis = new VectraClient({
  /* ...required config... */
  memory: {
    enabled: true,
    type: 'redis',
    maxMessages: 30,
    redis: {
      clientInstance: redisClient,
      keyPrefix: 'myapp:chat:'
    }
  }
});
```

--------------------------------

### Configure LLM-based Reranking

Source: https://context7.com/iamabhishek-n/vectra-js/llms.txt

Enable LLM-based reranking after document retrieval to improve precision. Configure the reranking provider, topN results, and windowSize for reranking.

```javascript
const { RerankingProvider } = require('vectra-js');

// LLM-based reranker (uses generation LLM by default)
const client = new VectraClient({
  /* ...required config... */
  reranking: {
    enabled: true,
    provider: RerankingProvider.LLM,
    topN: 5,
    windowSize: 20               // Number of retrieved docs to rerank before selecting topN
  }
});
```

--------------------------------

### client.evaluate

Source: https://context7.com/iamabhishek-n/vectra-js/llms.txt

Runs an LLM-based RAG evaluation pipeline over a test dataset. Computes key RAG metrics such as faithfulness, context precision, context recall, and answer correctness.

```APIDOC
## client.evaluate(testSet)

Runs an LLM-based RAG evaluation pipeline over a test dataset. Computes faithfulness, context precision, context recall, and answer correctness for each test item. Returns a detailed per-question metrics report.

### Parameters
#### Path Parameters
- **testSet** (array) - Required - An array of test objects, each containing a `question` and `expectedGroundTruth`.

### Request Example
```js
const report = await client.evaluate([
  {
    question: 'What is the capital of France?',
    expectedGroundTruth: 'Paris'
  },
  {
    question: 'What is the vacation policy?',
    expectedGroundTruth: 'Employees get 20 days of paid vacation per year.'
  },
  {
    question: 'How do I submit an expense report?',
    expectedGroundTruth: 'Submit via the HR portal within 30 days of the expense.'
  }
]);

console.log(JSON.stringify(report, null, 2));
// [
//   {
//     "question": "What is the vacation policy?",
//     "expectedGroundTruth": "Employees get 20 days...",
//     "answer": "According to the handbook, employees receive...",
//     "metrics": {
//       "faithfulness": 0.95,
//       "relevance": 0.88,
//       "contextPrecision": 1.0,
//       "contextRecall": 0.90,
//       "answerCorrectness": 0.88
//     }
//   }
// ]
```

### Response
#### Success Response (200)
- **report** (array) - An array of evaluation results, each containing the original test item and computed metrics.
```

--------------------------------

### Chunking Configuration (Agentic)

Source: https://github.com/iamabhishek-n/vectra-js/blob/master/README.md

Configure agentic chunking using an LLM provider, API key, and model name.

```javascript
chunking: {
  strategy: ChunkingStrategy.AGENTIC,
  agenticLlm: {
    provider: ProviderType.OPENAI,
    apiKey: process.env.OPENAI_API_KEY,
    modelName: 'gpt-4o-mini'
  }
}
```

--------------------------------

### Embedding Configuration (OpenAI)

Source: https://github.com/iamabhishek-n/vectra-js/blob/master/README.md

Configure the embedding provider, API key, model name, and dimensions. Use `dimensions` when using pgvector to avoid runtime mismatches.

```javascript
embedding: {
  provider: ProviderType.OPENAI,
  apiKey: process.env.OPENAI_API_KEY,
  modelName: 'text-embedding-3-small',
  dimensions: 1536
}
```

--------------------------------

### Configure Ollama for Local LLM Development

Source: https://github.com/iamabhishek-n/vectra-js/blob/master/documentation.md

Sets the LLM provider to Ollama for local development. The base URL defaults to http://localhost:11434 but can be overridden.

```javascript
provider = ProviderType.OLLAMA
```

--------------------------------

### LLM Configuration (Gemini)

Source: https://github.com/iamabhishek-n/vectra-js/blob/master/README.md

Configure the LLM provider, API key, model name, temperature, and max tokens. Used for answer generation, HyDE, agentic chunking, and reranking.

```javascript
llm: {
  provider: ProviderType.GEMINI,
  apiKey: process.env.GOOGLE_API_KEY,
  modelName: 'gemini-2.5-flash',
  temperature: 0.3,
  maxTokens: 1024
}
```

--------------------------------

### Configure Grounding and Citations

Source: https://context7.com/iamabhishek-n/vectra-js/llms.txt

Enable inline citations in answers by setting generation.structuredOutput to 'citations'. Strict grounding can be enforced by setting grounding.enabled and grounding.strict to true.

```javascript
// Enable inline citations [1], [2] in answers
const clientCitations = new VectraClient({
  /* ...required config... */
  generation: {
    structuredOutput: 'citations'   // Prompts LLM to cite [1], [2] etc.
  }
});

const result = await clientCitations.queryRAG('What are the Q3 goals?');
console.log(result.answer);
// "The Q3 goals include increasing market share by 15% [1] and launching two new product lines [2]."
console.log(result.citations);
// [{ index: 1, source: './goals.pdf', page: 3, quote: 'Increase market share by 15%...' }]
```

```javascript
// Strict grounding — only use verbatim snippets, no hallucination
const clientGrounded = new VectraClient({
  /* ...required config... */
  grounding: {
    enabled: true,
    strict: true,       // Context replaced with top-N highest-similarity sentences
    maxSnippets: 5
  }
});
```

--------------------------------

### List Documents with Pagination and Filtering

Source: https://context7.com/iamabhishek-n/vectra-js/llms.txt

List documents in the vector store. Supports limiting results, filtering by metadata, and cursor-based pagination for retrieving large datasets.

```javascript
// List first 50 documents
const { documents, nextCursor } = await client.listDocuments({ limit: 50 });
console.log(documents[0]);
// { id: 'uuid...', content: 'The refund policy states...', metadata: { source: './policy.pdf', ... } }
```

```javascript
// Filter by metadata
const { documents: filtered } = await client.listDocuments({
  filter: { source: './docs/policy.pdf' },
  limit: 100
});
```

```javascript
// Paginate
let cursor = null;
do {
  const page = await client.listDocuments({ limit: 100, cursor });
  console.log(`Got ${page.documents.length} docs`);
  cursor = page.nextCursor;
} while (cursor);
```

--------------------------------

### Configure OpenRouter as a Unified Gateway

Source: https://github.com/iamabhishek-n/vectra-js/blob/master/documentation.md

Sets the LLM provider to OpenRouter, enabling access to various models through a single gateway. The model name should be specified in a format like 'provider/model'.

```javascript
llm.provider = ProviderType.OPENROUTER
modelName = "openai/gpt-4o"
```

--------------------------------

### Ingest Documents into Vector Store

Source: https://context7.com/iamabhishek-n/vectra-js/llms.txt

Demonstrates ingesting single files or entire directories into the vector store using client.ingestDocuments. The method supports various file types and includes automatic chunking, embedding, deduplication, and retry logic.

```javascript
// Ingest a single file
await client.ingestDocuments('./docs/employee-handbook.pdf');

// Ingest an entire directory recursively
await client.ingestDocuments('./knowledge-base');
// Output: console shows chunk counts and timing via callbacks
```