vectra-js 0.9.3 → 0.9.5

package/README.md

@@ -161,6 +161,13 @@ const config = {
   - `enrichment`: boolean; generate `summary`, `keywords`, `hypothetical_questions`
 - Callbacks
   - `callbacks`: array of handlers; use `LoggingCallbackHandler` or `StructuredLoggingCallbackHandler`
+- Observability
+  - `enabled`: boolean; enable SQLite-based observability (default: false)
+  - `sqlitePath`: string; path to SQLite database file (default: 'vectra-observability.db')
+  - `projectId`: string; project identifier for multi-project support (default: 'default')
+  - `trackMetrics`: boolean; track latency and other metrics
+  - `trackTraces`: boolean; track detailed workflow traces
+  - `sessionTracking`: boolean; track chat sessions
 - Index Helpers (Postgres + Prisma)
   - `ensureIndexes()`: creates ivfflat and GIN FTS indexes and optional `tsvector` trigger
 
@@ -601,6 +608,29 @@ const { StructuredLoggingCallbackHandler } = require('vectra-js/src/callbacks');
 const config = { callbacks: [ new StructuredLoggingCallbackHandler() ] };
 ```
 
+### Observability
+
+Built-in SQLite-based observability to track metrics, traces, and sessions.
+
+```javascript
+const config = {
+  // ...
+  observability: {
+    enabled: true,
+    sqlitePath: 'vectra-observability.db',
+    projectId: 'my-project',
+    trackMetrics: true,
+    trackTraces: true,
+    sessionTracking: true
+  }
+};
+```
+
+This tracks:
+- **Metrics**: Latency (ingest, query).
+- **Traces**: Detailed spans for retrieval, generation, and ingestion workflows.
+- **Sessions**: Chat session history and last query tracking.
+
 ### Vector Stores
 - Prisma (Postgres + pgvector), Chroma, Qdrant, Milvus.
 - Configure `database.type`, `tableName`, `columnMap`, `clientInstance`.

package/bin/vectra.js

@@ -28,12 +28,18 @@ async function run() {
   
   if (cmd === 'webconfig') {
       const cfgPath = configPath || path.join(process.cwd(), 'vectra-config.json');
-      startWebConfig(cfgPath);
+      startWebConfig(cfgPath, 'webconfig');
       return;
   }
 
-  if (!cmd || (!target && cmd !== 'webconfig')) {
-    console.error('Usage: vectra <ingest|query|webconfig> <path|text> [--config=path] [--stream]');
+  if (cmd === 'dashboard') {
+      const cfgPath = configPath || path.join(process.cwd(), 'vectra-config.json');
+      startWebConfig(cfgPath, 'dashboard');
+      return;
+  }
+
+  if (!cmd || (!target && cmd !== 'webconfig' && cmd !== 'dashboard')) {
+    console.error('Usage: vectra <ingest|query|webconfig|dashboard> <path|text> [--config=path] [--stream]');
     process.exit(1);
   }
 

package/package.json

@@ -1,19 +1,14 @@
 {
   "name": "vectra-js",
-  "version": "0.9.3",
+  "version": "0.9.5",
   "description": "A production-ready, provider-agnostic Node.js SDK for End-to-End RAG pipelines.",
   "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
-    "prisma:generate": "prisma generate",
-    "lint": "eslint . --ext .js,.cjs,.mjs",
-    "lint:fix": "eslint . --ext .js,.cjs,.mjs --fix",
-    "prepublishOnly": "pnpm run lint",
-    "publish": "npm publish --access public"
-  },
   "bin": {
     "vectra": "bin/vectra.js"
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "keywords": [
     "rag",
     "llm",
@@ -33,22 +28,29 @@
   "author": "Abhishek N",
   "license": "GPL-3.0",
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.20.0",
-    "@google/genai": "^1.30.0",
-    "openai": "^4.0.0",
-    "zod": "^3.22.0",
-    "pdf-parse": "^1.1.1",
-    "mammoth": "^1.7.0",
+    "@anthropic-ai/sdk": "^0.20.9",
+    "@google/genai": "^1.34.0",
+    "dotenv": "^16.6.1",
+    "mammoth": "^1.11.0",
+    "openai": "^6.15.0",
+    "pdf-parse": "^2.4.5",
+    "sqlite3": "^5.1.7",
+    "uuid": "^9.0.1",
     "xlsx": "^0.18.5",
-    "uuid": "^9.0.0",
-    "dotenv": "^16.0.0"
+    "zod": "^3.25.76"
   },
   "peerDependencies": {
     "@prisma/client": "^5.0.0"
   },
   "devDependencies": {
-    "prisma": "^5.22.0",
-    "eslint": "^9.13.0",
-    "globals": "^13.24.0"
+    "eslint": "^9.39.2",
+    "globals": "^16.5.0",
+    "prisma": "^7.2.0"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "prisma:generate": "prisma generate",
+    "lint": "eslint . --ext .js,.cjs,.mjs",
+    "lint:fix": "eslint . --ext .js,.cjs,.mjs --fix"
   }
-}
+}

package/src/backends/chroma_store.js

@@ -15,11 +15,22 @@ class ChromaVectorStore extends VectorStore {
         }
     }
 
+    _cleanMetadata(meta) {
+        if (!meta) return {};
+        const out = {};
+        for (const [k, v] of Object.entries(meta)) {
+            if (v !== undefined && v !== null) {
+                out[k] = v;
+            }
+        }
+        return out;
+    }
+
     async addDocuments(docs) {
         await this._init();
         const ids = docs.map((d) => d.id || uuidv4());
         const embeddings = docs.map(d => d.embedding);
-        const metadatas = docs.map(d => d.metadata);
+        const metadatas = docs.map(d => this._cleanMetadata(d.metadata));
         const documents = docs.map(d => d.content);
 
         await this.collection.add({
@@ -34,7 +45,7 @@ class ChromaVectorStore extends VectorStore {
         await this._init();
         const ids = docs.map((d) => d.id || uuidv4());
         const embeddings = docs.map(d => d.embedding);
-        const metadatas = docs.map(d => d.metadata);
+        const metadatas = docs.map(d => this._cleanMetadata(d.metadata));
         const documents = docs.map(d => d.content);
         if (typeof this.collection.upsert === 'function') {
             await this.collection.upsert({ ids, embeddings, metadatas, documents });

package/src/config.js

@@ -114,6 +114,15 @@ const RAGConfigSchema = z.object({
   prompts: z.object({ query: z.string().optional(), reranking: z.string().optional() }).optional(),
   tracing: z.object({ enable: z.boolean().default(false) }).optional(),
   callbacks: z.array(z.custom((val) => true)).optional(), 
+  observability: z.object({
+    enabled: z.boolean().default(false),
+    sqlitePath: z.string().default('vectra-observability.db'),
+    projectId: z.string().default('default'),
+    trackMetrics: z.boolean().default(true),
+    trackTraces: z.boolean().default(true),
+    trackLogs: z.boolean().default(true),
+    sessionTracking: z.boolean().default(true)
+  }).default({})
 });
 
 module.exports = {

package/src/core.js

@@ -16,12 +16,20 @@ const { LLMReranker } = require('./reranker');
 const { InMemoryHistory, RedisHistory, PostgresHistory } = require('./memory');
 const { OllamaBackend } = require('./backends/ollama');
 const { v5: uuidv5 } = require('uuid');
+const { v4: uuidv4 } = require('uuid');
+const SQLiteLogger = require('./observability');
 
 class VectraClient {
   constructor(config) {
     const parsed = RAGConfigSchema.parse(config);
     this.config = parsed;
     this.callbacks = config.callbacks || [];
+    
+    // Initialize observability
+    this.logger = (this.config.observability && this.config.observability.enabled) 
+      ? new SQLiteLogger(this.config.observability) 
+      : null;
+
     // Initialize processor
     const agenticLlm = (this.config.chunking && this.config.chunking.agenticLlm)
         ? this.createLLM(this.config.chunking.agenticLlm)
@@ -128,6 +136,12 @@ class VectraClient {
   }
 
   async ingestDocuments(filePath) {
+    const traceId = uuidv4();
+    const rootSpanId = uuidv4();
+    const tStart = Date.now();
+    const provider = this.config.embedding.provider;
+    const modelName = this.config.embedding.modelName;
+    
     try {
       const stats = await fs.promises.stat(filePath);
 
@@ -292,8 +306,35 @@ class VectraClient {
       }
       const durationMs = Date.now() - t0;
       this.trigger('onIngestEnd', filePath, chunks.length, durationMs);
+      
+      this.logger.logTrace({
+        traceId,
+        spanId: rootSpanId,
+        name: 'ingestDocuments',
+        startTime: tStart,
+        endTime: Date.now(),
+        input: { filePath },
+        output: { chunks: chunks.length, durationMs },
+        attributes: { fileSize: size },
+        provider,
+        modelName
+      });
+      this.logger.logMetric({ name: 'ingest_latency', value: durationMs, tags: { type: 'single_file' } });
+
     } catch (e) {
       this.trigger('onError', e);
+      this.logger.logTrace({
+        traceId,
+        spanId: rootSpanId,
+        name: 'ingestDocuments',
+        startTime: tStart,
+        endTime: Date.now(),
+        input: { filePath },
+        error: { message: e.message },
+        status: 'error',
+        provider,
+        modelName
+      });
       throw e;
     }
   }
@@ -459,6 +500,19 @@ class VectraClient {
   }
 
   async queryRAG(query, filter = null, stream = false, sessionId = null) {
+    const traceId = uuidv4();
+    const rootSpanId = uuidv4();
+    const tStart = Date.now();
+    
+    if (sessionId) {
+        this.logger.updateSession(sessionId, null, { lastQuery: query });
+    }
+
+    const provider = this.config.llm.provider;
+    const modelName = this.config.llm.modelName;
+    const embeddingProvider = this.config.embedding.provider;
+    const embeddingModelName = this.config.embedding.modelName;
+
     try {
         const tRetrieval = Date.now();
         this.trigger('onRetrievalStart', query);
@@ -505,6 +559,20 @@ class VectraClient {
 
         const retrievalMs = Date.now() - tRetrieval;
         this.trigger('onRetrievalEnd', docs.length, retrievalMs);
+        
+        this.logger.logTrace({
+            traceId,
+            spanId: uuidv4(),
+            parentSpanId: rootSpanId,
+            name: 'retrieval',
+            startTime: tRetrieval,
+            endTime: Date.now(),
+            input: { query, filter, strategy },
+            output: { documentsFound: docs.length },
+            provider: embeddingProvider,
+            modelName: embeddingModelName
+        });
+
         const terms = query.toLowerCase().split(/\W+/).filter(t=>t.length>2);
         docs = docs.map(d => {
           const kws = Array.isArray(d.metadata?.keywords) ? d.metadata.keywords.map(k=>String(k).toLowerCase()) : [];
@@ -547,7 +615,91 @@ class VectraClient {
         if (stream) {
             // Streaming return
             if (!this.llm.generateStream) throw new Error("Streaming not implemented for this provider");
-            return this.llm.generateStream(prompt, systemInst);
+            
+            this.logger.logTrace({
+                traceId,
+                spanId: uuidv4(),
+                parentSpanId: rootSpanId,
+                name: 'generation_stream_start',
+                startTime: tGen,
+                endTime: Date.now(),
+                input: { prompt },
+                output: { stream: true },
+                provider,
+                modelName
+            });
+
+            const originalStream = await this.llm.generateStream(prompt, systemInst);
+            const self = this;
+            
+            async function* wrappedStream() {
+                let fullAnswer = '';
+                try {
+                    for await (const chunk of originalStream) {
+                        const delta = (chunk && chunk.delta) ? chunk.delta : (typeof chunk === 'string' ? chunk : '');
+                        fullAnswer += delta;
+                        yield chunk;
+                    }
+                } catch (e) {
+                    self.trigger('onError', e);
+                     self.logger.logTrace({
+                        traceId,
+                        spanId: rootSpanId,
+                        name: 'queryRAG',
+                        startTime: tStart,
+                        endTime: Date.now(),
+                        input: { query, sessionId },
+                        error: { message: e.message, stack: e.stack },
+                        status: 'error',
+                        provider,
+                        modelName
+                      });
+                    throw e;
+                }
+
+                // Stream finished successfully
+                const genMs = Date.now() - tGen;
+                self.trigger('onGenerationEnd', fullAnswer, genMs);
+
+                const promptChars = prompt.length;
+                const answerChars = fullAnswer.length;
+
+                self.logger.logTrace({
+                    traceId,
+                    spanId: uuidv4(),
+                    parentSpanId: rootSpanId,
+                    name: 'generation',
+                    startTime: tGen,
+                    endTime: Date.now(),
+                    input: { prompt },
+                    output: { answer: fullAnswer.substring(0, 1000) }, 
+                    attributes: { prompt_chars: promptChars, completion_chars: answerChars },
+                    provider,
+                    modelName
+                });
+
+                self.logger.logMetric({ name: 'prompt_chars', value: promptChars });
+                self.logger.logMetric({ name: 'completion_chars', value: answerChars });
+
+                self.logger.logTrace({
+                    traceId,
+                    spanId: rootSpanId,
+                    name: 'queryRAG',
+                    startTime: tStart,
+                    endTime: Date.now(),
+                    input: { query, sessionId },
+                    output: { success: true },
+                    attributes: { retrievalMs, genMs, docCount: docs.length },
+                    provider,
+                    modelName
+                });
+                
+                self.logger.logMetric({ name: 'query_latency', value: Date.now() - tStart, tags: { type: 'total' } });
+                self.logger.logMetric({ name: 'retrieval_latency', value: retrievalMs, tags: { type: 'retrieval' } });
+                self.logger.logMetric({ name: 'generation_latency', value: genMs, tags: { type: 'generation' } });
+            }
+
+            return wrappedStream();
         } else {
             const answer = await this.llm.generate(prompt, systemInst);
             if (this.history && sessionId) {
@@ -561,6 +713,44 @@ class VectraClient {
             }
             const genMs = Date.now() - tGen;
             this.trigger('onGenerationEnd', answer, genMs);
+
+            const promptChars = prompt.length;
+            const answerChars = answer ? String(answer).length : 0;
+
+            this.logger.logTrace({
+                traceId,
+                spanId: uuidv4(),
+                parentSpanId: rootSpanId,
+                name: 'generation',
+                startTime: tGen,
+                endTime: Date.now(),
+                input: { prompt },
+                output: { answer: String(answer).substring(0, 1000) }, // Truncate for log
+                attributes: { prompt_chars: promptChars, completion_chars: answerChars },
+                provider,
+                modelName
+            });
+
+            this.logger.logMetric({ name: 'prompt_chars', value: promptChars });
+            this.logger.logMetric({ name: 'completion_chars', value: answerChars });
+
+            this.logger.logTrace({
+                traceId,
+                spanId: rootSpanId,
+                name: 'queryRAG',
+                startTime: tStart,
+                endTime: Date.now(),
+                input: { query, sessionId },
+                output: { success: true },
+                attributes: { retrievalMs, genMs, docCount: docs.length },
+                provider,
+                modelName
+            });
+            
+            this.logger.logMetric({ name: 'query_latency', value: Date.now() - tStart, tags: { type: 'total' } });
+            this.logger.logMetric({ name: 'retrieval_latency', value: retrievalMs, tags: { type: 'retrieval' } });
+            this.logger.logMetric({ name: 'generation_latency', value: genMs, tags: { type: 'generation' } });
+
             if (this.config.generation && this.config.generation.outputFormat === 'json') {
               try { const parsed = JSON.parse(String(answer)); return { answer: parsed, sources: docs.map(d => d.metadata) }; } catch { return { answer, sources: docs.map(d => d.metadata) }; }
             }
@@ -568,6 +758,18 @@ class VectraClient {
         }
     } catch (e) {
       this.trigger('onError', e);
+      this.logger.logTrace({
+        traceId,
+        spanId: rootSpanId,
+        name: 'queryRAG',
+        startTime: tStart,
+        endTime: Date.now(),
+        input: { query, sessionId },
+        error: { message: e.message, stack: e.stack },
+        status: 'error',
+        provider,
+        modelName
+      });
       throw e;
     }
   }