@retrivora-ai/rag-engine 1.0.4 → 1.0.5

package/dist/handlers/index.js

@@ -1508,7 +1508,11 @@ __export(handlers_exports, {
   createHealthHandler: () => createHealthHandler,
   createIngestHandler: () => createIngestHandler,
   createStreamHandler: () => createStreamHandler,
-  createUploadHandler: () => createUploadHandler
+  createUploadHandler: () => createUploadHandler,
+  sseErrorFrame: () => sseErrorFrame,
+  sseFrame: () => sseFrame,
+  sseMetaFrame: () => sseMetaFrame,
+  sseTextFrame: () => sseTextFrame
 });
 module.exports = __toCommonJS(handlers_exports);
 var import_server = require("next/server");
@@ -1691,13 +1695,20 @@ function getRagConfig(env = process.env) {
 }
 
 // src/core/ConfigResolver.ts
+var _cachedEnvConfig = null;
+function getCachedEnvConfig() {
+  if (!_cachedEnvConfig) {
+    _cachedEnvConfig = getRagConfig();
+  }
+  return _cachedEnvConfig;
+}
 var ConfigResolver = class {
   /**
-   * Resolves the final configuration by merging host-provided config with defaults.
+   * Resolves the final configuration by merging host-provided config with environment defaults.
    * @param hostConfig - Partial configuration passed from the host application.
    */
   static resolve(hostConfig) {
-    const envConfig = getRagConfig();
+    const envConfig = getCachedEnvConfig();
     if (!hostConfig) {
       return envConfig;
     }
@@ -2971,14 +2982,16 @@ var LangChainAgent = class {
     this.config = config;
   }
   /**
-   * Initializes the agent with the RAG pipeline as a primary tool.
-   * Dynamically imports LangChain dependencies to avoid build errors if missing.
+   * Initializes the LangChain ReAct agent with the RAG pipeline as a tool.
+   * Dynamically imports langchain so the package doesn't crash if it isn't installed.
    */
   async initialize(chatModel) {
     try {
-      const { DynamicTool } = await import(`${"@langchain/core/tools"}`);
-      const { ChatPromptTemplate, MessagesPlaceholder } = await import(`${"@langchain/core/prompts"}`);
-      const { AgentExecutor, createOpenAIFunctionsAgent } = await import(`${"langchain/agents"}`);
+      const [{ DynamicTool }, { HumanMessage }, { createAgent }] = await Promise.all([
+        import("@langchain/core/tools"),
+        import("@langchain/core/messages"),
+        import("langchain")
+      ]);
       const searchTool = new DynamicTool({
         name: "document_search",
         description: "Use this tool to search through the knowledge base and document repository. Input should be a specific search query.",
@@ -2987,42 +3000,53 @@ var LangChainAgent = class {
           return `Search Results:
 ${response.reply}
 
-Sources Used: ${JSON.stringify(response.sources.map((s) => s.id))}`;
+Sources Used: ${JSON.stringify(
+            response.sources.map((s) => s.id)
+          )}`;
         }
       });
-      const tools = [searchTool];
-      const prompt = ChatPromptTemplate.fromMessages([
-        ["system", this.config.llm.systemPrompt || "You are a helpful AI assistant with access to a document search tool."],
-        new MessagesPlaceholder("chat_history"),
-        ["human", "{input}"],
-        new MessagesPlaceholder("agent_scratchpad")
-      ]);
-      const agent = await createOpenAIFunctionsAgent({
-        llm: chatModel,
-        tools,
-        prompt
-      });
-      this.executor = new AgentExecutor({
-        agent,
-        tools
+      this.agent = createAgent({
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        model: chatModel,
+        tools: [searchTool],
+        systemPrompt: this.config.llm.systemPrompt || "You are a helpful AI assistant with access to a document search tool."
       });
+      void HumanMessage;
     } catch (error) {
-      console.error("[LangChainAgent] Failed to initialize. Ensure 'langchain' and '@langchain/core' are installed.");
-      throw error;
+      const isMissing = error instanceof Error && error.message.includes("Cannot find module");
+      const hint = isMissing ? " Make sure 'langchain' and '@langchain/core' are installed:\n  npm install langchain @langchain/core" : "";
+      throw new Error(
+        `[LangChainAgent] Failed to initialize.${hint}
+${error instanceof Error ? error.message : String(error)}`
+      );
     }
   }
   /**
    * Run the agentic flow.
+   *
+   * LangChain v1.x: invoke takes `{ messages: [...] }` instead of `{ input, chat_history }`.
+   * The agent returns `{ messages: [...] }` — the last message is the final answer.
    */
   async run(input, chatHistory = []) {
-    if (!this.executor) {
+    var _a, _b, _c;
+    if (!this.agent) {
       throw new Error("[LangChainAgent] Agent not initialized. Call initialize() first.");
     }
-    const response = await this.executor.invoke({
-      input,
-      chat_history: chatHistory
+    const { HumanMessage, AIMessage } = await import("@langchain/core/messages");
+    const historyMessages = chatHistory.map(
+      (m) => m.role === "user" ? new HumanMessage(m.content) : new AIMessage(m.content)
+    );
+    const response = await this.agent.invoke({
+      messages: [...historyMessages, new HumanMessage(input)]
     });
-    return response.output;
+    const lastMessage = (_a = response == null ? void 0 : response.messages) == null ? void 0 : _a.at(-1);
+    if (lastMessage && typeof lastMessage.content === "string") {
+      return lastMessage.content;
+    }
+    if (Array.isArray(lastMessage == null ? void 0 : lastMessage.content)) {
+      return lastMessage.content.filter((c) => c.type === "text").map((c) => c.text).join("");
+    }
+    return String((_c = (_b = response == null ? void 0 : response.output) != null ? _b : response) != null ? _c : "");
   }
 };
 
@@ -3425,6 +3449,10 @@ var QueryProcessor = class {
   }
   /**
    * Constructs a QueryFilter object from extracted hints.
+   *
+   * Note: proper nouns are extracted inside `extractQueryFieldHints` and surfaced
+   * as field-less hints; `buildQueryFilter` adds them to `keywords` without
+   * re-running the proper noun regex to avoid duplication.
    */
   static buildQueryFilter(question, hints) {
     const filter = { metadata: {}, keywords: [], queryText: question };
@@ -3432,13 +3460,11 @@ var QueryProcessor = class {
       if (hint.field) {
         filter.metadata[hint.field] = hint.value;
       } else {
-        filter.keywords.push(hint.value);
+        if (!filter.keywords.includes(hint.value)) {
+          filter.keywords.push(hint.value);
+        }
       }
     }
-    for (const match of question.matchAll(/\b[A-Z][a-z]+(?:\s+[A-Z][a-z]+){0,3}\b/g)) {
-      const term = this.normalizeHintValue(match[0]);
-      if (term && !filter.keywords.includes(term)) filter.keywords.push(term);
-    }
     if (Object.keys(filter.metadata || {}).length === 0) delete filter.metadata;
     if (filter.keywords && filter.keywords.length === 0) delete filter.keywords;
     return filter;
@@ -3446,10 +3472,40 @@ var QueryProcessor = class {
 };
 
 // src/core/Pipeline.ts
+var LRUEmbeddingCache = class {
+  constructor(maxSize = 500) {
+    this.cache = /* @__PURE__ */ new Map();
+    this.maxSize = maxSize;
+  }
+  get(key) {
+    const value = this.cache.get(key);
+    if (value !== void 0) {
+      this.cache.delete(key);
+      this.cache.set(key, value);
+    }
+    return value;
+  }
+  set(key, value) {
+    if (this.cache.has(key)) {
+      this.cache.delete(key);
+    } else if (this.cache.size >= this.maxSize) {
+      const oldestKey = this.cache.keys().next().value;
+      if (oldestKey !== void 0) this.cache.delete(oldestKey);
+    }
+    this.cache.set(key, value);
+  }
+  clear() {
+    this.cache.clear();
+  }
+  get size() {
+    return this.cache.size;
+  }
+};
 var Pipeline = class {
   constructor(config) {
     this.config = config;
-    this.embeddingCache = /* @__PURE__ */ new Map();
+    /** LRU-bounded cache: avoids re-embedding identical queries within the same process. */
+    this.embeddingCache = new LRUEmbeddingCache(500);
     this.initialised = false;
     var _a, _b, _c, _d, _e;
     this.chunker = new DocumentChunker(
@@ -3537,6 +3593,7 @@ var Pipeline = class {
   }
   /**
    * Step 2: Generate embeddings for chunks with retry logic.
+   * Uses batchEmbed when available for efficiency; falls back to sequential embedding.
    */
   async processEmbeddings(chunks) {
     const embedBatchOptions = {
@@ -3550,7 +3607,9 @@ var Pipeline = class {
       embedBatchOptions
     );
     if (vectors.length !== chunks.length) {
-      throw new Error(`Embedding mismatch: got ${vectors.length} vectors for ${chunks.length} chunks`);
+      throw new Error(
+        `[Pipeline] Embedding mismatch: got ${vectors.length} vectors for ${chunks.length} chunks. Check embedding provider logs for individual chunk failures.`
+      );
     }
     return vectors;
   }
@@ -3704,6 +3763,7 @@ ${context}`;
   }
   /**
    * Universal retrieval method combining all enabled providers.
+   * Uses an LRU-bounded embedding cache to avoid re-embedding the same query.
    */
   async retrieve(query, options) {
     var _a, _b, _c;
@@ -3736,10 +3796,13 @@ ${history.map((m) => `${m.role}: ${m.content}`).join("\n")}
 New Question: ${question}
 
 Optimized Search Query:`;
-    const rewrite = await this.llmProvider.chat([
-      { role: "system", content: "You are an assistant that optimizes search queries for RAG systems." },
-      { role: "user", content: prompt }
-    ], "");
+    const rewrite = await this.llmProvider.chat(
+      [
+        { role: "system", content: "You are an assistant that optimizes search queries for RAG systems." },
+        { role: "user", content: prompt }
+      ],
+      ""
+    );
     return rewrite.trim() || question;
   }
 };
@@ -3958,8 +4021,35 @@ var DocumentParser = class {
 };
 
 // src/handlers/index.ts
-function createChatHandler(config) {
-  const plugin = new VectorPlugin(config);
+function sseFrame(payload) {
+  return `data: ${JSON.stringify(payload)}
+
+`;
+}
+function sseTextFrame(text) {
+  return `data: ${JSON.stringify({ type: "text", text })}
+
+`;
+}
+function sseMetaFrame(meta) {
+  return `data: ${JSON.stringify(__spreadValues({ type: "metadata" }, meta != null ? meta : {}))}
+
+`;
+}
+function sseErrorFrame(message) {
+  return `data: ${JSON.stringify({ type: "error", error: message })}
+
+`;
+}
+var SSE_HEADERS = {
+  "Content-Type": "text/event-stream; charset=utf-8",
+  "Cache-Control": "no-cache, no-transform",
+  Connection: "keep-alive",
+  "X-Accel-Buffering": "no"
+  // Disable Nginx buffering for streaming
+};
+function createChatHandler(configOrPlugin) {
+  const plugin = configOrPlugin instanceof VectorPlugin ? configOrPlugin : new VectorPlugin(configOrPlugin);
   return async function POST(req) {
     try {
       const body = await req.json();
@@ -3975,67 +4065,64 @@ function createChatHandler(config) {
     }
   };
 }
-function createStreamHandler(config) {
-  const plugin = new VectorPlugin(config);
+function createStreamHandler(configOrPlugin) {
+  const plugin = configOrPlugin instanceof VectorPlugin ? configOrPlugin : new VectorPlugin(configOrPlugin);
   return async function POST(req) {
+    let body;
     try {
-      const body = await req.json();
-      const { message, history = [], namespace } = body;
-      const encoder = new TextEncoder();
-      const stream = new ReadableStream({
-        async start(controller) {
+      body = await req.json();
+    } catch (e) {
+      return new Response(JSON.stringify({ error: "Invalid JSON body" }), {
+        status: 400,
+        headers: { "Content-Type": "application/json" }
+      });
+    }
+    const { message, history = [], namespace } = body;
+    if (!(message == null ? void 0 : message.trim())) {
+      return new Response(JSON.stringify({ error: "message is required" }), {
+        status: 400,
+        headers: { "Content-Type": "application/json" }
+      });
+    }
+    const encoder = new TextEncoder();
+    const stream = new ReadableStream({
+      async start(controller) {
+        const enqueue = (text) => controller.enqueue(encoder.encode(text));
+        try {
+          const pipelineStream = plugin.chatStream(message, history, namespace);
           try {
-            const pipelineStream = plugin.chatStream(message, history, namespace);
-            try {
-              for (var iter = __forAwait(pipelineStream), more, temp, error; more = !(temp = await iter.next()).done; more = false) {
-                const chunk = temp.value;
-                if (typeof chunk === "string") {
-                  controller.enqueue(encoder.encode(chunk));
-                } else {
-                  controller.enqueue(encoder.encode(`
-
-__METADATA__${JSON.stringify(chunk)}`));
-                }
+            for (var iter = __forAwait(pipelineStream), more, temp, error; more = !(temp = await iter.next()).done; more = false) {
+              const chunk = temp.value;
+              if (typeof chunk === "string") {
+                enqueue(sseTextFrame(chunk));
+              } else {
+                enqueue(sseMetaFrame(chunk));
               }
-            } catch (temp) {
-              error = [temp];
+            }
+          } catch (temp) {
+            error = [temp];
+          } finally {
+            try {
+              more && (temp = iter.return) && await temp.call(iter);
             } finally {
-              try {
-                more && (temp = iter.return) && await temp.call(iter);
-              } finally {
-                if (error)
-                  throw error[0];
-              }
+              if (error)
+                throw error[0];
             }
-            controller.close();
-          } catch (streamError) {
-            console.error("[createStreamHandler] Stream processing error:", streamError);
-            const errorMessage = streamError instanceof Error ? streamError.message : String(streamError);
-            controller.enqueue(encoder.encode(`
-
-__ERROR__${JSON.stringify({ error: errorMessage })}`));
-            controller.close();
           }
+        } catch (streamError) {
+          const errorMessage = streamError instanceof Error ? streamError.message : String(streamError);
+          console.error("[createStreamHandler] Stream error:", streamError);
+          enqueue(sseErrorFrame(errorMessage));
+        } finally {
+          controller.close();
         }
-      });
-      return new Response(stream, {
-        headers: {
-          "Content-Type": "text/event-stream",
-          "Cache-Control": "no-cache",
-          "Connection": "keep-alive"
-        }
-      });
-    } catch (err) {
-      const message = err instanceof Error ? err.message : "Internal server error";
-      return new Response(JSON.stringify({ error: message }), {
-        status: 500,
-        headers: { "Content-Type": "application/json" }
-      });
-    }
+      }
+    });
+    return new Response(stream, { headers: SSE_HEADERS });
   };
 }
-function createIngestHandler(config) {
-  const plugin = new VectorPlugin(config);
+function createIngestHandler(configOrPlugin) {
+  const plugin = configOrPlugin instanceof VectorPlugin ? configOrPlugin : new VectorPlugin(configOrPlugin);
   return async function POST(req) {
     try {
       const body = await req.json();
@@ -4051,8 +4138,8 @@ function createIngestHandler(config) {
     }
   };
 }
-function createHealthHandler(config) {
-  const plugin = new VectorPlugin(config);
+function createHealthHandler(configOrPlugin) {
+  const plugin = configOrPlugin instanceof VectorPlugin ? configOrPlugin : new VectorPlugin(configOrPlugin);
   return async function GET() {
     try {
       const health = await plugin.checkHealth();
@@ -4068,8 +4155,8 @@ function createHealthHandler(config) {
     }
   };
 }
-function createUploadHandler(config) {
-  const plugin = new VectorPlugin(config);
+function createUploadHandler(configOrPlugin) {
+  const plugin = configOrPlugin instanceof VectorPlugin ? configOrPlugin : new VectorPlugin(configOrPlugin);
   return async function POST(req) {
     try {
       const formData = await req.formData();
@@ -4107,5 +4194,9 @@ function createUploadHandler(config) {
   createHealthHandler,
   createIngestHandler,
   createStreamHandler,
-  createUploadHandler
+  createUploadHandler,
+  sseErrorFrame,
+  sseFrame,
+  sseMetaFrame,
+  sseTextFrame
 });

package/dist/handlers/index.mjs

@@ -3,8 +3,12 @@ import {
   createHealthHandler,
   createIngestHandler,
   createStreamHandler,
-  createUploadHandler
-} from "../chunk-6MLZHQZT.mjs";
+  createUploadHandler,
+  sseErrorFrame,
+  sseFrame,
+  sseMetaFrame,
+  sseTextFrame
+} from "../chunk-MWL4AGQI.mjs";
 import "../chunk-YLTMFW4M.mjs";
 import "../chunk-X4TOT24V.mjs";
 export {
@@ -12,5 +16,9 @@ export {
   createHealthHandler,
   createIngestHandler,
   createStreamHandler,
-  createUploadHandler
+  createUploadHandler,
+  sseErrorFrame,
+  sseFrame,
+  sseMetaFrame,
+  sseTextFrame
 };

package/dist/index-CSfaCeux.d.ts

@@ -0,0 +1,206 @@
+import { g as RagConfig, C as ChatMessage, b as ChatResponse, e as IngestDocument } from './RagConfig-BEmz4hVP.js';
+import { NextRequest, NextResponse } from 'next/server';
+
+interface ValidationError {
+    field: string;
+    message: string;
+    suggestion?: string;
+    severity: 'error' | 'warning';
+}
+/**
+ * ConfigValidator.ts — Comprehensive configuration validation.
+ * Uses a pluggable architecture to delegate provider-specific checks.
+ */
+declare class ConfigValidator {
+    /**
+     * Validates the entire RagConfig object.
+     */
+    static validate(config: RagConfig): Promise<ValidationError[]>;
+    private static validateVectorDbConfig;
+    private static validateLLMConfig;
+    private static validateEmbeddingConfig;
+    /**
+     * Temporary fallbacks for providers not yet migrated to the pluggable architecture.
+     */
+    private static fallbackVectorValidation;
+    private static fallbackLLMValidation;
+    private static fallbackEmbeddingValidation;
+    private static validateUIConfig;
+    private static validateRAGConfig;
+    private static isValidCSSColor;
+    static validateAndThrow(config: RagConfig): Promise<void>;
+}
+
+/**
+ * Interface for provider-specific configuration validation logic.
+ */
+interface IProviderValidator {
+    /**
+     * Validates the configuration for a specific provider.
+     * @param config - The configuration object to validate.
+     * @returns An array of validation errors (empty if valid).
+     */
+    validate(config: Record<string, unknown>): ValidationError[];
+}
+/**
+ * Result of a provider health check.
+ */
+interface HealthCheckResult {
+    healthy: boolean;
+    provider: string;
+    version?: string;
+    capabilities?: Record<string, unknown>;
+    error?: string;
+    timestamp: number;
+}
+/**
+ * Interface for provider-specific health checking logic.
+ */
+interface IProviderHealthChecker {
+    /**
+     * Performs a health check for a specific provider.
+     * @param config - The configuration object used to connect to the provider.
+     * @returns A promise that resolves to the health check result.
+     */
+    check(config: Record<string, unknown>): Promise<HealthCheckResult>;
+}
+
+/**
+ * VectorPlugin — main orchestrator class.
+ * This is the primary interface for host applications.
+ *
+ * Features:
+ * - Configuration resolution from host + environment
+ * - Configuration validation with detailed error messages
+ * - Provider health checks before initialization
+ * - Multi-provider support (Vector DBs & LLMs)
+ * - Per-tenant data isolation via namespacing
+ */
+declare class VectorPlugin {
+    private config;
+    private pipeline;
+    private validationPromise;
+    constructor(hostConfig?: Partial<RagConfig>);
+    /**
+     * Get the current resolved configuration.
+     */
+    getConfig(): RagConfig;
+    /**
+     * Perform pre-flight health checks on all configured providers.
+     * Useful to verify connectivity before running operations.
+     *
+     * @returns Health status for vector DB, LLM, and embedding providers
+     */
+    checkHealth(): Promise<{
+        vectorDb: HealthCheckResult;
+        llm: HealthCheckResult;
+        embedding?: HealthCheckResult;
+        allHealthy: boolean;
+    }>;
+    /**
+     * Run a chat query.
+     */
+    chat(message: string, history?: ChatMessage[], namespace?: string): Promise<ChatResponse>;
+    /**
+     * Run a streaming chat query.
+     */
+    chatStream(message: string, history?: ChatMessage[], namespace?: string): AsyncGenerator<string | ChatResponse, void, any>;
+    /**
+     * Ingest documents into the vector database.
+     */
+    ingest(documents: IngestDocument[], namespace?: string): Promise<Array<{
+        docId: string | number;
+        chunksIngested: number;
+    }>>;
+}
+
+/**
+ * Encode a payload as a Server-Sent Events frame.
+ *   data: <json>\n\n
+ */
+declare function sseFrame(payload: unknown): string;
+/** Encode a plain text chunk as an SSE frame. */
+declare function sseTextFrame(text: string): string;
+/** Encode the retrieval metadata as an SSE frame. */
+declare function sseMetaFrame(meta: unknown): string;
+/** Encode a stream error as an SSE frame. */
+declare function sseErrorFrame(message: string): string;
+/**
+ * createChatHandler — factory that returns a Next.js App Router POST handler.
+ *
+ * Accepts either a full/partial `RagConfig` **or** a pre-built `VectorPlugin`
+ * instance (preferred for singleton/multi-tenant setups).
+ *
+ * @example
+ * // Option A — pass config (plugin created once at module load time)
+ * export const POST = createChatHandler(getRagConfig());
+ *
+ * // Option B — pass a pre-built plugin (most flexible)
+ * const plugin = new VectorPlugin(getRagConfig());
+ * export const POST = createChatHandler(plugin);
+ */
+declare function createChatHandler(configOrPlugin?: Partial<RagConfig> | VectorPlugin): (req: NextRequest) => Promise<NextResponse<{
+    error: string;
+}> | NextResponse<ChatResponse>>;
+/**
+ * createStreamHandler — factory for a streaming SSE Next.js App Router POST handler.
+ *
+ * Streams the assistant response as Server-Sent Events (SSE). Each frame is a
+ * JSON object with a `type` discriminant:
+ *   - `{ type: "text",     text: "..." }`       — incremental text chunk
+ *   - `{ type: "metadata", sources: [...] }`    — retrieval metadata (last frame)
+ *   - `{ type: "error",    error: "..." }`       — stream-level error
+ *
+ * @example
+ * // src/app/api/chat/route.ts
+ * export const POST = createStreamHandler(getRagConfig());
+ *
+ * // Client-side parsing in useRagChat.ts:
+ * // const lines = chunk.split('\n');
+ * // for (const line of lines) {
+ * //   if (line.startsWith('data: ')) {
+ * //     const frame = JSON.parse(line.slice(6));
+ * //     if (frame.type === 'text') { ... }
+ * //   }
+ * // }
+ */
+declare function createStreamHandler(configOrPlugin?: Partial<RagConfig> | VectorPlugin): (req: NextRequest) => Promise<Response>;
+/**
+ * createIngestHandler — factory for the document ingestion endpoint.
+ */
+declare function createIngestHandler(configOrPlugin?: Partial<RagConfig> | VectorPlugin): (req: NextRequest) => Promise<NextResponse<{
+    error: string;
+}> | NextResponse<{
+    results: {
+        docId: string | number;
+        chunksIngested: number;
+    }[];
+}>>;
+/**
+ * createHealthHandler — factory for the health-check endpoint.
+ */
+declare function createHealthHandler(configOrPlugin?: Partial<RagConfig> | VectorPlugin): () => Promise<NextResponse<{
+    timestamp: string;
+    vectorDb: HealthCheckResult;
+    llm: HealthCheckResult;
+    embedding?: HealthCheckResult;
+    allHealthy: boolean;
+    status: string;
+}> | NextResponse<{
+    status: string;
+    error: string;
+}>>;
+/**
+ * createUploadHandler — factory for the file upload ingestion endpoint.
+ */
+declare function createUploadHandler(configOrPlugin?: Partial<RagConfig> | VectorPlugin): (req: NextRequest) => Promise<NextResponse<{
+    error: string;
+}> | NextResponse<{
+    message: string;
+    results: {
+        docId: string | number;
+        chunksIngested: number;
+    }[];
+}>>;
+
+export { ConfigValidator as C, type HealthCheckResult as H, type IProviderValidator as I, type ValidationError as V, type IProviderHealthChecker as a, VectorPlugin as b, createChatHandler as c, createHealthHandler as d, createIngestHandler as e, createStreamHandler as f, createUploadHandler as g, sseFrame as h, sseMetaFrame as i, sseTextFrame as j, sseErrorFrame as s };