vectra-js 0.9.0

package/src/backends/huggingface.js

@@ -0,0 +1,52 @@
+class HuggingFaceBackend {
+  constructor(config) {
+    this.config = config;
+    this.apiKey = config.apiKey || process.env.HUGGINGFACE_API_KEY;
+    if (!this.apiKey) throw new Error('HuggingFace API Key missing. Set HUGGINGFACE_API_KEY.');
+    this.baseUrl = 'https://api-inference.huggingface.co/models';
+  }
+
+  async _post(model, payload) {
+    const res = await fetch(`${this.baseUrl}/${encodeURIComponent(model)}`, {
+      method: 'POST',
+      headers: { 'Authorization': `Bearer ${this.apiKey}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload)
+    });
+    if (!res.ok) {
+      const t = await res.text();
+      throw new Error(`HF error ${res.status}: ${t}`);
+    }
+    return await res.json();
+  }
+
+  async embedDocuments(texts) {
+    const out = [];
+    for (const text of texts) {
+      const r = await this._post(this.config.modelName, { inputs: text, options: { wait_for_model: true } });
+      const vec = Array.isArray(r) ? r.flat(2) : (r.embedding || r);
+      out.push(vec);
+    }
+    return out;
+  }
+
+  async embedQuery(text) {
+    const r = await this._post(this.config.modelName, { inputs: text, options: { wait_for_model: true } });
+    const vec = Array.isArray(r) ? r.flat(2) : (r.embedding || r);
+    return vec;
+  }
+
+  async generate(prompt, sys) {
+    const inputs = sys ? `${sys}\n${prompt}` : prompt;
+    const r = await this._post(this.config.modelName, { inputs, parameters: { temperature: this.config.temperature }, options: { wait_for_model: true } });
+    if (Array.isArray(r) && r[0]?.generated_text) return r[0].generated_text;
+    if (typeof r === 'string') return r;
+    if (r?.generated_text) return r.generated_text;
+    return String(r);
+  }
+
+  async *generateStream(prompt, sys) {
+    const text = await this.generate(prompt, sys);
+    yield { delta: text, finish_reason: null, usage: null };
+  }
+}
+module.exports = { HuggingFaceBackend };

package/src/backends/milvus_store.js

@@ -0,0 +1,61 @@
+const { VectorStore } = require('../interfaces');
+
+class MilvusVectorStore extends VectorStore {
+  constructor(config) { super(); this.config = config; this.client = config.clientInstance; this.collection = config.tableName || 'rag_collection'; }
+  async addDocuments(documents) {
+    const data = documents.map((doc) => ({ vector: doc.embedding, content: doc.content, metadata: JSON.stringify(doc.metadata) }));
+    await this.client.insert({ collection_name: this.collection, fields_data: data });
+  }
+  async upsertDocuments(documents) {
+    return this.addDocuments(documents);
+  }
+  async similaritySearch(vector, limit = 5, filter = null) {
+    const lim = Math.max(1, Number(limit) || 5);
+    let res;
+    if (filter) {
+      try {
+        res = await this.client.search({ collection_name: this.collection, data: [vector], limit: lim, filter });
+      } catch (_) {
+        try {
+          res = await this.client.search({ collection_name: this.collection, data: [vector], limit: lim, expr: filter });
+        } catch (_) {
+          res = await this.client.search({ collection_name: this.collection, data: [vector], limit: lim });
+        }
+      }
+    } else {
+      res = await this.client.search({ collection_name: this.collection, data: [vector], limit: lim });
+    }
+    const hits = res.results ? res.results : res;
+    return hits.map(h => ({ content: h.content || '', metadata: h.metadata ? JSON.parse(h.metadata) : {}, score: h.distance }));
+  }
+  async hybridSearch(text, vector, limit = 5, filter = null) { return this.similaritySearch(vector, limit, filter); }
+
+  async listDocuments({ filter = null, limit = 100, offset = 0 } = {}) {
+    if (typeof this.client.query !== 'function') throw new Error('listDocuments is not supported for this Milvus client');
+    const lim = Math.max(1, Math.min(1000, Number(limit) || 100));
+    const off = Math.max(0, Number(offset) || 0);
+    const res = await this.client.query({
+      collection_name: this.collection,
+      expr: filter || '',
+      output_fields: ['content', 'metadata'],
+      limit: lim,
+      offset: off,
+    });
+    const rows = Array.isArray(res) ? res : (res?.data || res?.results || []);
+    return rows.map((r) => ({ id: r.id, content: r.content || '', metadata: r.metadata ? JSON.parse(r.metadata) : {} }));
+  }
+
+  async deleteDocuments({ ids = null, filter = null } = {}) {
+    if (typeof this.client.delete !== 'function') throw new Error('deleteDocuments is not supported for this Milvus client');
+    if (Array.isArray(ids) && ids.length > 0) {
+      await this.client.delete({ collection_name: this.collection, ids });
+      return;
+    }
+    if (filter) {
+      await this.client.delete({ collection_name: this.collection, expr: filter });
+      return;
+    }
+    throw new Error('deleteDocuments requires ids or filter');
+  }
+}
+module.exports = { MilvusVectorStore };

package/src/backends/ollama.js

@@ -0,0 +1,63 @@
+class OllamaBackend {
+  constructor(config) {
+    this.config = config;
+    this.baseUrl = config.baseUrl || 'http://localhost:11434';
+  }
+  async embedDocuments(texts) {
+    const out = [];
+    for (const t of texts) {
+      const res = await fetch(`${this.baseUrl}/api/embeddings`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ model: this.config.modelName, prompt: t })
+      });
+      const json = await res.json();
+      out.push(json.embedding || json.data || []);
+    }
+    return out;
+  }
+  async embedQuery(text) {
+    const res = await fetch(`${this.baseUrl}/api/embeddings`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ model: this.config.modelName, prompt: text })
+    });
+    const json = await res.json();
+    return json.embedding || json.data || [];
+  }
+  async generate(prompt, sys) {
+    const res = await fetch(`${this.baseUrl}/api/generate`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ model: this.config.modelName, prompt: sys ? `${sys}\n\n${prompt}` : prompt, stream: false })
+    });
+    const json = await res.json();
+    return json.response || '';
+  }
+  async *generateStream(prompt, sys) {
+    const res = await fetch(`${this.baseUrl}/api/generate`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ model: this.config.modelName, prompt: sys ? `${sys}\n\n${prompt}` : prompt, stream: true })
+    });
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let done = false;
+    while (!done) {
+      const chunk = await reader.read();
+      done = chunk.done;
+      if (chunk.value) {
+        const text = decoder.decode(chunk.value);
+        const lines = text.split('\n').filter(l => l.trim().length > 0);
+        for (const line of lines) {
+          try {
+            const obj = JSON.parse(line);
+            const d = obj.response || '';
+            if (d) yield { delta: d, finish_reason: obj.done ? 'stop' : null, usage: null };
+          } catch {}
+        }
+      }
+    }
+  }
+}
+module.exports = { OllamaBackend };

package/src/backends/openai.js

@@ -0,0 +1,46 @@
+const OpenAI = require('openai');
+
+class OpenAIBackend {
+  constructor(config) {
+    this.config = config;
+    this.client = new OpenAI({ apiKey: config.apiKey || process.env.OPENAI_API_KEY });
+  }
+
+  async embedDocuments(texts) {
+    const res = await this.client.embeddings.create({ model: this.config.modelName, input: texts, dimensions: this.config.dimensions });
+    return res.data.map(d => d.embedding);
+  }
+
+  async embedQuery(text) {
+    const res = await this.client.embeddings.create({ model: this.config.modelName, input: text, dimensions: this.config.dimensions });
+    return res.data[0].embedding;
+  }
+
+  async generate(prompt, sys) {
+    const msgs = [];
+    if (sys) msgs.push({ role: 'system', content: sys });
+    msgs.push({ role: 'user', content: prompt });
+    const res = await this.client.chat.completions.create({ model: this.config.modelName, messages: msgs, temperature: this.config.temperature, max_tokens: this.config.maxTokens });
+    return res.choices[0].message.content || "";
+  }
+
+  async *generateStream(prompt, sys) {
+    const msgs = [];
+    if (sys) msgs.push({ role: 'system', content: sys });
+    msgs.push({ role: 'user', content: prompt });
+    
+    const stream = await this.client.chat.completions.create({
+      model: this.config.modelName,
+      messages: msgs,
+      temperature: this.config.temperature,
+      max_tokens: this.config.maxTokens,
+      stream: true,
+    });
+
+    for await (const chunk of stream) {
+      const content = chunk.choices[0]?.delta?.content || '';
+      if (content) yield { delta: content, finish_reason: null, usage: null };
+    }
+  }
+}
+module.exports = { OpenAIBackend };

package/src/backends/openrouter.js

@@ -0,0 +1,51 @@
+const OpenAI = require('openai');
+
+class OpenRouterBackend {
+  constructor(config) {
+    this.config = config;
+    const apiKey = config.apiKey || process.env.OPENROUTER_API_KEY;
+    if (!apiKey) throw new Error('OpenRouter API Key missing. Set OPENROUTER_API_KEY.');
+    this.client = new OpenAI({
+      apiKey,
+      baseURL: config.baseUrl || 'https://openrouter.ai/api/v1',
+      defaultHeaders: config.defaultHeaders || {
+        'HTTP-Referer': process.env.OPENROUTER_REFERER || '',
+        'X-Title': process.env.OPENROUTER_TITLE || ''
+      }
+    });
+  }
+
+  async embedDocuments(texts) { throw new Error('OpenRouter does not support embeddings via this SDK.'); }
+  async embedQuery(text) { throw new Error('OpenRouter does not support embeddings via this SDK.'); }
+
+  async generate(prompt, sys) {
+    const msgs = [];
+    if (sys) msgs.push({ role: 'system', content: sys });
+    msgs.push({ role: 'user', content: prompt });
+    const res = await this.client.chat.completions.create({
+      model: this.config.modelName,
+      messages: msgs,
+      temperature: this.config.temperature,
+      max_tokens: this.config.maxTokens
+    });
+    return res.choices[0]?.message?.content || '';
+  }
+
+  async *generateStream(prompt, sys) {
+    const msgs = [];
+    if (sys) msgs.push({ role: 'system', content: sys });
+    msgs.push({ role: 'user', content: prompt });
+    const stream = await this.client.chat.completions.create({
+      model: this.config.modelName,
+      messages: msgs,
+      temperature: this.config.temperature,
+      max_tokens: this.config.maxTokens,
+      stream: true
+    });
+    for await (const chunk of stream) {
+      const content = chunk.choices?.[0]?.delta?.content || '';
+      if (content) yield { delta: content, finish_reason: null, usage: null };
+    }
+  }
+}
+module.exports = { OpenRouterBackend };

package/src/backends/prisma_store.js

@@ -0,0 +1,160 @@
+const { v4: uuidv4 } = require('uuid');
+const { VectorStore } = require('../interfaces');
+
+const isSafeIdentifier = (value) => typeof value === 'string' && /^[A-Za-z_][A-Za-z0-9_]*$/.test(value);
+const assertSafeIdentifier = (value, label) => {
+  if (!isSafeIdentifier(value)) throw new Error(`Unsafe SQL identifier for ${label}`);
+};
+const quoteIdentifier = (value, label) => {
+  assertSafeIdentifier(value, label);
+  return `"${value}"`;
+};
+const quoteTableName = (value, label) => {
+  if (typeof value !== 'string' || value.trim().length === 0) throw new Error(`Unsafe SQL identifier for ${label}`);
+  const parts = value.split('.').map(p => p.trim()).filter(Boolean);
+  if (parts.length === 0 || parts.length > 2) throw new Error(`Unsafe SQL identifier for ${label}`);
+  parts.forEach((p, i) => assertSafeIdentifier(p, i === 0 && parts.length === 2 ? `${label} schema` : `${label} table`));
+  return parts.map(p => `"${p}"`).join('.');
+};
+
+class PrismaVectorStore extends VectorStore {
+  constructor(config) { 
+      super();
+      this.config = config; 
+      const tableName = config.tableName || 'Document';
+      const columnMap = config.columnMap || {};
+      this._table = quoteTableName(tableName, 'tableName');
+      this._tableBase = tableName.split('.').pop();
+      this._cContent = quoteIdentifier(columnMap.content || 'content', 'columnMap.content');
+      this._cMeta = quoteIdentifier(columnMap.metadata || 'metadata', 'columnMap.metadata');
+      this._cVec = quoteIdentifier(columnMap.vector || 'vector', 'columnMap.vector');
+  }
+  normalizeVector(v) {
+    const m = Math.sqrt(v.reduce((s, x) => s + x * x, 0));
+    return m === 0 ? v : v.map(x => x / m);
+  }
+  async addDocuments(docs) {
+    const { clientInstance } = this.config;
+    const q = `INSERT INTO ${this._table} ("id", ${this._cContent}, ${this._cMeta}, ${this._cVec}, "createdAt") VALUES ($1, $2, $3, $4::vector, NOW())`;
+    for (const doc of docs) {
+        const id = doc.id || uuidv4();
+        const vec = JSON.stringify(this.normalizeVector(doc.embedding));
+        try {
+          await clientInstance.$executeRawUnsafe(q, id, doc.content, doc.metadata, vec);
+        } catch (e) {
+          const msg = e?.message || String(e);
+          if (msg.includes('vector') && msg.includes('dimension')) {
+            throw new Error('DimensionMismatchError: Embedding dimension does not match pgvector column. Configure embedding.dimensions to match the column or migrate the column dimension.');
+          }
+          throw e;
+        }
+    }
+  }
+
+  async upsertDocuments(docs) {
+    const { clientInstance } = this.config;
+    const q = `INSERT INTO ${this._table} ("id", ${this._cContent}, ${this._cMeta}, ${this._cVec}, "createdAt") VALUES ($1, $2, $3, $4::vector, NOW()) ON CONFLICT ("id") DO UPDATE SET ${this._cContent} = EXCLUDED.${this._cContent}, ${this._cMeta} = EXCLUDED.${this._cMeta}, ${this._cVec} = EXCLUDED.${this._cVec}`;
+    for (const doc of docs) {
+      const id = doc.id || uuidv4();
+      const vec = JSON.stringify(this.normalizeVector(doc.embedding));
+      await clientInstance.$executeRawUnsafe(q, id, doc.content, doc.metadata, vec);
+    }
+  }
+
+  async similaritySearch(vector, limit = 5, filter = null) {
+    const { clientInstance } = this.config;
+
+    const vec = JSON.stringify(this.normalizeVector(vector));
+    let where = ""; const params = [vec];
+    if (filter) { where = `WHERE ${this._cMeta} @> $2::jsonb`; params.push(JSON.stringify(filter)); }
+    const q = `SELECT ${this._cContent} as content, ${this._cMeta} as metadata, 1 - (${this._cVec} <=> $1::vector) as score FROM ${this._table} ${where} ORDER BY score DESC LIMIT ${Math.max(1, Number(limit) || 5)}`;
+    const res = await clientInstance.$queryRawUnsafe(q, ...params);
+    return res.map(r => ({ content: r.content, metadata: r.metadata, score: r.score }));
+  }
+
+  async hybridSearch(text, vector, limit = 5, filter = null) {
+    const semantic = await this.similaritySearch(vector, limit * 2, filter);
+    const { clientInstance } = this.config;
+    const params = [text];
+    const where = filter ? ` AND ${this._cMeta} @> $2::jsonb` : '';
+    if (filter) params.push(JSON.stringify(filter));
+    const q = `SELECT ${this._cContent} as content, ${this._cMeta} as metadata FROM ${this._table} WHERE to_tsvector('simple', ${this._cContent}) @@ plainto_tsquery($1)${where} LIMIT ${Math.max(1, Number(limit) || 5) * 2}`;
+    let lexical = [];
+    try {
+      const res = await clientInstance.$queryRawUnsafe(q, ...params);
+      lexical = res.map(r => ({ content: r.content, metadata: r.metadata, score: 1.0 }));
+    } catch (_) {
+      lexical = [];
+    }
+    const combined = {};
+    const add = (list, weight = 1) => {
+      list.forEach((doc, idx) => {
+        const key = doc.content;
+        const score = 1 / (60 + idx + 1) * weight;
+        if (!combined[key]) combined[key] = { ...doc, score: 0 };
+        combined[key].score += score;
+      });
+    };
+    add(semantic, 1);
+    add(lexical, 1);
+    return Object.values(combined).sort((a, b) => b.score - a.score).slice(0, limit);
+  }
+
+  async ensureIndexes() {
+    const { clientInstance } = this.config;
+    const base = this._tableBase;
+    assertSafeIdentifier(base, 'tableName table');
+    const idxVec = `"${base}_embedding_ivfflat"`;
+    const idxFts = `"${base}_content_fts_gin"`;
+    try {
+      await clientInstance.$executeRawUnsafe('CREATE EXTENSION IF NOT EXISTS vector');
+      await clientInstance.$executeRawUnsafe(`CREATE INDEX IF NOT EXISTS ${idxVec} ON ${this._table} USING ivfflat (${this._cVec} vector_cosine_ops) WITH (lists = 100);`);
+      await clientInstance.$executeRawUnsafe(`CREATE INDEX IF NOT EXISTS ${idxFts} ON ${this._table} USING GIN (to_tsvector('english', ${this._cContent}));`);
+    } catch (e) {
+      // Best-effort; indexes are optional
+    }
+  }
+  
+  async fileExists(sha256, size, lastModified) {
+    const { clientInstance } = this.config;
+    const payload = JSON.stringify({ fileSHA256: sha256, fileSize: size, lastModified });
+    const q = `SELECT 1 FROM ${this._table} WHERE ${this._cMeta} @> $1::jsonb LIMIT 1`;
+    try {
+      const res = await clientInstance.$queryRawUnsafe(q, payload);
+      return Array.isArray(res) && res.length > 0;
+    } catch (_) {
+      return false;
+    }
+  }
+
+  async listDocuments({ filter = null, limit = 100, offset = 0 } = {}) {
+    const { clientInstance } = this.config;
+    const params = [];
+    let where = '';
+    if (filter) {
+      where = `WHERE ${this._cMeta} @> $1::jsonb`;
+      params.push(JSON.stringify(filter));
+    }
+    const lim = Math.max(1, Math.min(1000, Number(limit) || 100));
+    const off = Math.max(0, Number(offset) || 0);
+    const q = `SELECT "id" as id, ${this._cContent} as content, ${this._cMeta} as metadata, "createdAt" as createdAt FROM ${this._table} ${where} ORDER BY "createdAt" DESC LIMIT ${lim} OFFSET ${off}`;
+    const res = await clientInstance.$queryRawUnsafe(q, ...params);
+    return res.map(r => ({ id: r.id, content: r.content, metadata: r.metadata, createdAt: r.createdAt }));
+  }
+
+  async deleteDocuments({ ids = null, filter = null } = {}) {
+    const { clientInstance } = this.config;
+    if (Array.isArray(ids) && ids.length > 0) {
+      const q = `DELETE FROM ${this._table} WHERE "id" = ANY($1::uuid[])`;
+      await clientInstance.$executeRawUnsafe(q, ids);
+      return;
+    }
+    if (filter) {
+      const q = `DELETE FROM ${this._table} WHERE ${this._cMeta} @> $1::jsonb`;
+      await clientInstance.$executeRawUnsafe(q, JSON.stringify(filter));
+      return;
+    }
+    throw new Error('deleteDocuments requires ids or filter');
+  }
+}
+module.exports = { PrismaVectorStore };

package/src/backends/qdrant_store.js

@@ -0,0 +1,68 @@
+const { VectorStore } = require('../interfaces');
+
+class QdrantVectorStore extends VectorStore {
+  constructor(config) { super(); this.config = config; this.client = config.clientInstance; this.collection = config.tableName || 'rag_collection'; }
+
+  normalizeFilter(filter) {
+    if (!filter) return null;
+    if (typeof filter !== 'object') return filter;
+    if (filter.must || filter.should || filter.must_not) return filter;
+    const must = [];
+    Object.entries(filter).forEach(([k, v]) => {
+      if (v === undefined) return;
+      if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean') {
+        must.push({ key: `metadata.${k}`, match: { value: v } });
+      }
+    });
+    return must.length ? { must } : null;
+  }
+
+  async addDocuments(documents) {
+    const points = documents.map((doc, i) => ({ id: doc.id || `${Date.now()}-${i}`, vector: doc.embedding, payload: { content: doc.content, metadata: doc.metadata } }));
+    await this.client.upsert(this.collection, { points });
+  }
+  async upsertDocuments(documents) {
+    return this.addDocuments(documents);
+  }
+  async similaritySearch(vector, limit = 5, filter = null) {
+    const qFilter = this.normalizeFilter(filter);
+    const res = await this.client.search(this.collection, { vector, limit, filter: qFilter });
+    return res.map(r => ({ content: r.payload.content, metadata: r.payload.metadata, score: r.score }));
+  }
+  async hybridSearch(text, vector, limit = 5, filter = null) { return this.similaritySearch(vector, limit, filter); }
+  async listDocuments({ filter = null, limit = 100, offset = 0 } = {}) {
+    if (typeof this.client.scroll !== 'function') throw new Error('listDocuments is not supported for this Qdrant client');
+    const qFilter = this.normalizeFilter(filter);
+    const lim = Math.max(1, Math.min(1000, Number(limit) || 100));
+    const off = Math.max(0, Number(offset) || 0);
+    let skipped = 0;
+    const out = [];
+    let nextOffset = undefined;
+    while (out.length < lim) {
+      const res = await this.client.scroll(this.collection, { limit: Math.min(256, lim), filter: qFilter, offset: nextOffset });
+      const points = res?.points || res?.result?.points || [];
+      nextOffset = res?.next_page_offset || res?.result?.next_page_offset || res?.next_page_offset;
+      if (!points.length) break;
+      for (const p of points) {
+        if (skipped < off) { skipped++; continue; }
+        out.push({ id: p.id, content: p.payload?.content, metadata: p.payload?.metadata });
+        if (out.length >= lim) break;
+      }
+      if (!nextOffset) break;
+    }
+    return out;
+  }
+  async deleteDocuments({ ids = null, filter = null } = {}) {
+    if (typeof this.client.delete !== 'function') throw new Error('deleteDocuments is not supported for this Qdrant client');
+    if (Array.isArray(ids) && ids.length > 0) {
+      await this.client.delete(this.collection, { points: ids });
+      return;
+    }
+    if (filter) {
+      await this.client.delete(this.collection, { filter: this.normalizeFilter(filter) });
+      return;
+    }
+    throw new Error('deleteDocuments requires ids or filter');
+  }
+}
+module.exports = { QdrantVectorStore };

package/src/callbacks.js

@@ -0,0 +1,31 @@
+class LoggingCallbackHandler {
+  onIngestStart(filePath) { console.info(`[RAG] Starting ingestion: ${filePath}`); }
+  onIngestEnd(file, count, durationMs) { console.info(`[RAG] Finished ingestion. Chunks: ${count} (${durationMs} ms)`); }
+  onIngestSummary(summary) { console.info(`[RAG] Ingest summary: processed=${summary.processed}, ok=${summary.succeeded}, failed=${summary.failed}`); }
+  onChunkingStart(strategy) { console.debug(`[RAG] Chunking strategy: ${strategy}`); }
+  onEmbeddingStart(count) { console.debug(`[RAG] Embedding ${count} chunks...`); }
+  onRetrievalStart(query) { console.info(`[RAG] Querying: "${query}"`); }
+  onRetrievalEnd(count, durationMs) { console.info(`[RAG] Retrieved ${count} docs (${durationMs} ms).`); }
+  onRerankingStart(count) { console.debug(`[RAG] Reranking ${count} docs...`); }
+  onRerankingEnd(count) { console.debug(`[RAG] Reranking finished. Keeping top ${count}.`); }
+  onGenerationStart() { console.debug(`[RAG] Generating answer...`); }
+  onGenerationEnd(answer, durationMs) { console.info(`[RAG] Answer generated (${durationMs} ms).`); }
+  onError(err) { console.error(`[RAG] Error: ${err.message || err}`); }
+}
+
+class StructuredLoggingCallbackHandler {
+  constructor() { this.enabled = true; }
+  onIngestStart(filePath) { console.log(JSON.stringify({ event: 'ingest_start', filePath })); }
+  onIngestEnd(filePath, chunkCount, durationMs) { console.log(JSON.stringify({ event: 'ingest_end', filePath, chunkCount, durationMs })); }
+  onIngestSummary(summary) { console.log(JSON.stringify({ event: 'ingest_summary', ...summary })); }
+  onChunkingStart(strategy) { console.log(JSON.stringify({ event: 'chunking_start', strategy })); }
+  onEmbeddingStart(count) { console.log(JSON.stringify({ event: 'embedding_start', count })); }
+  onRetrievalStart(query) { console.log(JSON.stringify({ event: 'retrieval_start', query })); }
+  onRetrievalEnd(count, durationMs) { console.log(JSON.stringify({ event: 'retrieval_end', count, durationMs })); }
+  onRerankingStart(count) { console.log(JSON.stringify({ event: 'reranking_start', count })); }
+  onRerankingEnd(count) { console.log(JSON.stringify({ event: 'reranking_end', count })); }
+  onGenerationStart(promptPreview) { console.log(JSON.stringify({ event: 'generation_start', promptPreview: String(promptPreview).slice(0, 120) })); }
+  onGenerationEnd(answerPreview, durationMs) { console.log(JSON.stringify({ event: 'generation_end', answerPreview: String(answerPreview).slice(0, 120), durationMs })); }
+  onError(err) { console.log(JSON.stringify({ event: 'error', message: err?.message || String(err) })); }
+}
+module.exports = { LoggingCallbackHandler, StructuredLoggingCallbackHandler };

package/src/config.js

@@ -0,0 +1,123 @@
+const { z } = require('zod');
+
+const ProviderType = {
+  OPENAI: 'openai',
+  ANTHROPIC: 'anthropic',
+  GEMINI: 'gemini',
+  OPENROUTER: 'openrouter',
+  HUGGINGFACE: 'huggingface',
+  OLLAMA: 'ollama',
+};
+
+const ChunkingStrategy = {
+  RECURSIVE: 'recursive',
+  AGENTIC: 'agentic',
+};
+
+const RetrievalStrategy = {
+  NAIVE: 'naive',
+  HYDE: 'hyde',
+  MULTI_QUERY: 'multi_query',
+  HYBRID: 'hybrid',
+  MMR: 'mmr'
+};
+
+const EmbeddingConfigSchema = z.object({
+  provider: z.nativeEnum(ProviderType),
+  apiKey: z.string().optional(),
+  modelName: z.string().default('text-embedding-3-small'),
+  dimensions: z.number().optional(),
+});
+
+const LLMConfigSchema = z.object({
+  provider: z.nativeEnum(ProviderType),
+  apiKey: z.string().optional(),
+  modelName: z.string(),
+  temperature: z.number().default(0),
+  maxTokens: z.number().default(1024),
+  baseUrl: z.string().optional(),
+  defaultHeaders: z.record(z.string()).optional(),
+});
+
+const ChunkingConfigSchema = z.object({
+  strategy: z.nativeEnum(ChunkingStrategy).default(ChunkingStrategy.RECURSIVE),
+  chunkSize: z.number().default(1000),
+  chunkOverlap: z.number().default(200),
+  separators: z.array(z.string()).default(['\n\n', '\n', ' ', '']),
+  agenticLlm: LLMConfigSchema.optional(),
+}).refine((data) => {
+  if (data.strategy === ChunkingStrategy.AGENTIC && !data.agenticLlm) return false;
+  return true;
+}, { message: "agenticLlm required for AGENTIC strategy", path: ["agenticLlm"] });
+
+const RerankingConfigSchema = z.object({
+    enabled: z.boolean().default(false),
+    provider: z.literal('llm').default('llm'),
+    llmConfig: LLMConfigSchema.optional(),
+    topN: z.number().default(5),
+    windowSize: z.number().default(20)
+});
+
+const RetrievalConfigSchema = z.object({
+    strategy: z.nativeEnum(RetrievalStrategy).default(RetrievalStrategy.NAIVE),
+    llmConfig: LLMConfigSchema.optional(),
+    hybridAlpha: z.number().default(0.5),
+    mmrLambda: z.number().default(0.5),
+    mmrFetchK: z.number().default(20)
+}).refine((data) => {
+    if ((data.strategy === RetrievalStrategy.HYDE || data.strategy === RetrievalStrategy.MULTI_QUERY) && !data.llmConfig) return false;
+    return true;
+}, { message: "llmConfig required for advanced retrieval", path: ["llmConfig"] });
+
+const DatabaseConfigSchema = z.object({
+  type: z.string(), // 'prisma', 'chroma', etc.
+  tableName: z.string().optional(),
+  columnMap: z.object({
+    content: z.string(),
+    vector: z.string(),
+    metadata: z.string(),
+  }).default({ content: 'content', vector: 'vector', metadata: 'metadata' }),
+  clientInstance: z.any(), // The actual client object
+});
+
+const RAGConfigSchema = z.object({
+  embedding: EmbeddingConfigSchema,
+  llm: LLMConfigSchema,
+  database: DatabaseConfigSchema,
+  chunking: ChunkingConfigSchema.default({}),
+  retrieval: RetrievalConfigSchema.default({}),
+  reranking: RerankingConfigSchema.default({}),
+  metadata: z.object({ enrichment: z.boolean().default(false) }).optional(),
+  ingestion: z.object({ rateLimitEnabled: z.boolean().default(false), concurrencyLimit: z.number().default(5) }).optional(),
+  memory: z.object({
+    enabled: z.boolean().default(false),
+    type: z.enum(['in-memory','redis','postgres']).default('in-memory'),
+    maxMessages: z.number().default(20),
+    redis: z.object({
+      clientInstance: z.any().optional(),
+      keyPrefix: z.string().default('vectra:chat:')
+    }).optional(),
+    postgres: z.object({
+      clientInstance: z.any().optional(),
+      tableName: z.string().default('ChatMessage'),
+      columnMap: z.object({
+        sessionId: z.string().default('sessionId'),
+        role: z.string().default('role'),
+        content: z.string().default('content'),
+        createdAt: z.string().default('createdAt')
+      }).default({ sessionId: 'sessionId', role: 'role', content: 'content', createdAt: 'createdAt' })
+    }).optional()
+  }).optional(),
+  queryPlanning: z.object({ tokenBudget: z.number().default(2048), preferSummariesBelow: z.number().default(1024), includeCitations: z.boolean().default(true) }).optional(),
+  grounding: z.object({ enabled: z.boolean().default(false), strict: z.boolean().default(false), maxSnippets: z.number().default(3) }).optional(),
+  generation: z.object({ structuredOutput: z.enum(['none','citations']).default('none'), outputFormat: z.enum(['text','json']).default('text') }).optional(),
+  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(), 
+});
+
+module.exports = {
+  ProviderType, ChunkingStrategy, RetrievalStrategy,
+  EmbeddingConfigSchema, LLMConfigSchema, ChunkingConfigSchema,
+  RetrievalConfigSchema, RerankingConfigSchema, DatabaseConfigSchema, RAGConfigSchema
+};