@denizsvnc/ai-rag-engine 2.2.1 → 2.2.3

package/dist/api/server.js

@@ -168,7 +168,19 @@ var CircuitBreakerOpenError = class extends Error {
     this.name = "CircuitBreakerOpenError";
   }
 };
-var SMLEngine = class {
+var SMLEngine = class _SMLEngine {
+  static initLockChain = Promise.resolve();
+  static async acquireInitLock() {
+    let releaseLock = () => {
+    };
+    const nextLock = new Promise((resolve) => {
+      releaseLock = resolve;
+    });
+    const currentLock = _SMLEngine.initLockChain;
+    _SMLEngine.initLockChain = currentLock.then(() => nextLock);
+    await currentLock;
+    return releaseLock;
+  }
   modelName;
   cacheDir;
   localFilesOnly;
@@ -228,48 +240,62 @@ var SMLEngine = class {
       console.log(`[SML CircuitBreaker] Cooldown expired. Transitioned to HALF_OPEN for probe.`);
     }
     if (!this.extractorPromise) {
-      console.log(`[SML] Loading ${this.modelName} (dtype: ${this.dtype})...`);
-      this.extractorPromise = import("@huggingface/transformers").then(async ({ pipeline: pipeline2, env }) => {
-        const previousCacheDir = env.cacheDir;
-        const previousAllowRemote = env.allowRemoteModels;
+      this.extractorPromise = (async () => {
+        const releaseLock = await _SMLEngine.acquireInitLock();
         try {
-          if (this.cacheDir) {
-            env.cacheDir = this.cacheDir;
+          console.log(`[SML] Loading ${this.modelName} (dtype: ${this.dtype})...`);
+          const { pipeline: pipeline2, env } = await import("@huggingface/transformers");
+          const previousCacheDir = env.cacheDir;
+          const previousAllowRemote = env.allowRemoteModels;
+          const previousLocalModelPath = env.localModelPath;
+          try {
+            if (this.cacheDir) {
+              env.cacheDir = this.cacheDir;
+            }
+            if (this.localFilesOnly !== void 0) {
+              env.allowRemoteModels = !this.localFilesOnly;
+            }
+            const pipelineOptions = {
+              dtype: this.dtype
+            };
+            if (this.cacheDir) {
+              pipelineOptions.cache_dir = this.cacheDir;
+            }
+            if (this.localFilesOnly !== void 0) {
+              pipelineOptions.local_files_only = this.localFilesOnly;
+            }
+            const pipelineInstance = await pipeline2("feature-extraction", this.modelName, pipelineOptions);
+            this.circuitState = "CLOSED";
+            this.failureCount = 0;
+            const extract = async (text, options) => {
+              const output = await pipelineInstance(text, options);
+              const values = output.data;
+              const data = output.data instanceof Float32Array ? output.data : Float32Array.from({ length: values.length }, (_, index) => Number(values[index]));
+              return { data, dims: output.dims };
+            };
+            return extract;
+          } finally {
+            env.cacheDir = previousCacheDir;
+            env.allowRemoteModels = previousAllowRemote;
+            env.localModelPath = previousLocalModelPath;
           }
-          if (this.localFilesOnly) {
-            env.allowRemoteModels = false;
+        } catch (err) {
+          this.failureCount++;
+          this.lastFailureTime = Date.now();
+          this.extractorPromise = null;
+          if (this.failureCount >= this.failureThreshold) {
+            this.circuitState = "OPEN";
+            console.error(
+              `[SML CircuitBreaker] \u26A0\uFE0F Tripped to OPEN state! Model failed ${this.failureCount} times. Pausing requests for ${this.cooldownMs / 1e3}s.`
+            );
+          } else {
+            console.error(`[SML] Model loading error (attempt ${this.failureCount}/${this.failureThreshold}):`, err);
           }
-          return await pipeline2("feature-extraction", this.modelName, {
-            dtype: this.dtype
-          });
+          throw err;
         } finally {
-          env.cacheDir = previousCacheDir;
-          env.allowRemoteModels = previousAllowRemote;
+          releaseLock();
         }
-      }).then((pipelineInstance) => {
-        this.circuitState = "CLOSED";
-        this.failureCount = 0;
-        const extract = async (text, options) => {
-          const output = await pipelineInstance(text, options);
-          const values = output.data;
-          const data = output.data instanceof Float32Array ? output.data : Float32Array.from({ length: values.length }, (_, index) => Number(values[index]));
-          return { data, dims: output.dims };
-        };
-        return extract;
-      }).catch((err) => {
-        this.failureCount++;
-        this.lastFailureTime = Date.now();
-        this.extractorPromise = null;
-        if (this.failureCount >= this.failureThreshold) {
-          this.circuitState = "OPEN";
-          console.error(
-            `[SML CircuitBreaker] \u26A0\uFE0F Tripped to OPEN state! Model failed ${this.failureCount} times. Pausing requests for ${this.cooldownMs / 1e3}s.`
-          );
-        } else {
-          console.error(`[SML] Model loading error (attempt ${this.failureCount}/${this.failureThreshold}):`, err);
-        }
-        throw err;
-      });
+      })();
     }
     return this.extractorPromise;
   }
@@ -535,11 +561,11 @@ var InjectionDetector = class {
     // 2. Jailbreaks, DAN modes, role hijacking
     {
       id: "JAILBREAK_MODE_EN",
-      regex: /\b(you\s+are\s+now|act\s+as|switch\s+to|enter)\s+(an?\s+)?(developer|dan|jailbreak|unrestricted|unfiltered|god)\s*(mode|persona|ai)?\b/i
+      regex: /\b(you\s+are\s+now|act\s+as|switch\s+to|enter)\s+(in\s+(an?\s+)?|an?\s+)?(developer|dan|jailbreak|unrestricted|unfiltered|god)\s*(mode|persona|ai)?\b/i
     },
     {
       id: "JAILBREAK_MODE_TR",
-      regex: /\bartık\s+(geliştirici|dan|kısıtlamasız|admin|jailbreak)\s+(modundasın|moduna\s+geç|olarak\s+davran)\b/i
+      regex: /(?:^|\s|[.,!?])(artık|şimdi)\s+(bir\s+)?(geliştirici|dan|kısıtlamasız|admin|jailbreak)\s+(modundasın|moduna\s+geç|olarak\s+davran)(?:$|\s|[.,!?])/i
     },
     {
       id: "DISABLE_SAFETY_EN",
@@ -1211,6 +1237,8 @@ import fs3 from "node:fs";
 import fsp from "node:fs/promises";
 import path3 from "node:path";
 import os from "node:os";
+import zlib from "node:zlib";
+import { StringDecoder } from "node:string_decoder";
 
 // src/core/queue/in-memory-queue.ts
 import { randomUUID } from "node:crypto";
@@ -1462,17 +1490,71 @@ var DocumentIngestionService = class _DocumentIngestionService {
    * - Performs binary artifact suppression and multi-lingual UTF-8 normalization (Turkish, European, and CJK diacritics).
    */
   static extractText(filename, buffer) {
-    const rawString = buffer.toString("utf-8");
-    if (buffer.length >= 4 && buffer.slice(0, 4).toString() === "%PDF") {
-      return _DocumentIngestionService.extractPdfText(rawString);
+    if (buffer.length >= 4 && buffer.subarray(0, 4).toString() === "%PDF") {
+      return _DocumentIngestionService.extractPdfText(buffer);
     }
-    return rawString.trim();
+    return buffer.toString("utf-8").trim();
   }
   /**
-   * Enterprise High-Efficiency PDF Lexical Extractor.
-   * Parses PDF content streams without heavy external C++/WASM dependencies.
+   * Enterprise High-Efficiency PDF Lexical Extractor with native zlib.inflate decompression.
+   * Decodes and parses PDF content streams without heavy external C++/WASM dependencies.
+   * 
+   * Supports:
+   * - Decompression of compressed stream objects (/Filter /FlateDecode) via Node.js native zlib.
+   * - BT (Begin Text) ... ET (End Text) matrices.
+   * - TJ array operators with kerning spacing preservation.
+   * - Literal (Tj) and hexadecimal (<hex> Tj) text operators with escape and octal decoding.
    */
   static extractPdfText(rawContent) {
+    const buffer = Buffer.isBuffer(rawContent) ? rawContent : Buffer.from(rawContent, "latin1");
+    const decompressedStreams = [];
+    const streamMarker = Buffer.from("stream");
+    const endStreamMarker = Buffer.from("endstream");
+    let pos = 0;
+    while (pos < buffer.length) {
+      const streamIdx = buffer.indexOf(streamMarker, pos);
+      if (streamIdx === -1) break;
+      const prevChar = streamIdx > 0 ? buffer[streamIdx - 1] : 32;
+      if (prevChar !== 10 && prevChar !== 13 && prevChar !== 32 && prevChar !== 62) {
+        pos = streamIdx + 6;
+        continue;
+      }
+      let dataStart = streamIdx + 6;
+      if (buffer[dataStart] === 13 && buffer[dataStart + 1] === 10) {
+        dataStart += 2;
+      } else if (buffer[dataStart] === 10 || buffer[dataStart] === 13) {
+        dataStart += 1;
+      }
+      const endIdx = buffer.indexOf(endStreamMarker, dataStart);
+      if (endIdx === -1) break;
+      let dataEnd = endIdx;
+      while (dataEnd > dataStart && (buffer[dataEnd - 1] === 10 || buffer[dataEnd - 1] === 13 || buffer[dataEnd - 1] === 32)) {
+        dataEnd--;
+      }
+      const streamBytes = buffer.subarray(dataStart, dataEnd);
+      const dictStart = Math.max(0, streamIdx - 500);
+      const dictSnippet = buffer.subarray(dictStart, streamIdx).toString("latin1");
+      const isFlate = /\/Filter\s*(?:\[\s*)?\/(?:FlateDecode|Fl)\b/.test(dictSnippet) || !/\/Filter\b/.test(dictSnippet);
+      let decoded = "";
+      if (isFlate && streamBytes.length > 0) {
+        try {
+          decoded = zlib.inflateSync(streamBytes).toString("utf-8");
+        } catch {
+          try {
+            decoded = zlib.inflateRawSync(streamBytes).toString("utf-8");
+          } catch {
+            decoded = streamBytes.toString("utf-8");
+          }
+        }
+      } else {
+        decoded = streamBytes.toString("utf-8");
+      }
+      if (decoded && decoded.trim().length > 0) {
+        decompressedStreams.push(decoded);
+      }
+      pos = endIdx + 9;
+    }
+    const contentToScan = [buffer.toString("latin1"), ...decompressedStreams].join("\n");
     const extractedSegments = [];
     const decodePdfLiteral = (encoded) => {
       return encoded.replace(/\\([0-7]{1,3})/g, (_, oct) => String.fromCharCode(parseInt(oct, 8))).replace(/\\n/g, "\n").replace(/\\r/g, "\r").replace(/\\t/g, "	").replace(/\\b/g, "\b").replace(/\\f/g, "\f").replace(/\\\(/g, "(").replace(/\\\)/g, ")").replace(/\\\\/g, "\\");
@@ -1487,7 +1569,7 @@ var DocumentIngestionService = class _DocumentIngestionService {
     };
     const btEtRegex = /BT[\s\S]*?ET/g;
     let btMatch;
-    while ((btMatch = btEtRegex.exec(rawContent)) !== null) {
+    while ((btMatch = btEtRegex.exec(contentToScan)) !== null) {
       const blockContent = btMatch[0];
       const tjArrayRegex = /\[([\s\S]*?)\]\s*TJ/g;
       let tjArrMatch;
@@ -1532,7 +1614,7 @@ var DocumentIngestionService = class _DocumentIngestionService {
     if (extractedSegments.length > 0) {
       return extractedSegments.join(" ").replace(/\s+/g, " ").trim();
     }
-    const cleaned = rawContent.replace(/%PDF-[^\n]+/g, "").replace(/stream[\s\S]*?endstream/g, (streamObj) => {
+    const cleaned = contentToScan.replace(/%PDF-[^\n]+/g, "").replace(/stream[\s\S]*?endstream/g, (streamObj) => {
       const innerMatch = streamObj.match(/\((.*?)\)/g);
       return innerMatch ? innerMatch.map((s) => decodePdfLiteral(s.slice(1, -1))).join(" ") : "";
     }).replace(/obj[\s\S]*?endobj/g, (obj) => {
@@ -1542,8 +1624,17 @@ var DocumentIngestionService = class _DocumentIngestionService {
     return cleaned || "PDF document with no extractable plain text stream.";
   }
   static chunkText(text, chunkSize = 500, overlap = 50) {
-    if (!text || text.length <= chunkSize) {
-      return text ? [text] : [];
+    if (!Number.isFinite(chunkSize) || chunkSize <= 0) {
+      throw new RangeError(`[DocumentIngestionService] chunkSize must be a positive integer greater than 0. Received: ${chunkSize}`);
+    }
+    if (!Number.isFinite(overlap) || overlap < 0 || overlap >= chunkSize) {
+      throw new RangeError(`[DocumentIngestionService] overlap must be non-negative and strictly less than chunkSize (${chunkSize}). Received: ${overlap}`);
+    }
+    if (!text || text.trim().length === 0) {
+      return [];
+    }
+    if (text.length <= chunkSize) {
+      return [text.trim()];
     }
     const chunks = [];
     let startIndex = 0;
@@ -1565,6 +1656,9 @@ var DocumentIngestionService = class _DocumentIngestionService {
       if (chunk.length > 0) {
         chunks.push(chunk);
       }
+      if (endIndex >= text.length) {
+        break;
+      }
       startIndex = Math.max(startIndex + 1, endIndex - overlap);
     }
     return chunks;
@@ -1573,11 +1667,19 @@ var DocumentIngestionService = class _DocumentIngestionService {
    * Streaming chunk generator.
    * Ingests chunks of text or buffers incrementally with natural backpressure,
    * maintaining a constant O(1) memory footprint regardless of file size.
+   * Preserves UTF-8 multibyte character boundaries across stream buffer splits.
    */
   static async *chunkStream(textStream, chunkSize = 500, overlap = 50) {
+    if (!Number.isFinite(chunkSize) || chunkSize <= 0) {
+      throw new RangeError(`[DocumentIngestionService] chunkSize must be a positive integer greater than 0. Received: ${chunkSize}`);
+    }
+    if (!Number.isFinite(overlap) || overlap < 0 || overlap >= chunkSize) {
+      throw new RangeError(`[DocumentIngestionService] overlap must be non-negative and strictly less than chunkSize (${chunkSize}). Received: ${overlap}`);
+    }
+    const decoder = new StringDecoder("utf-8");
     let window = "";
     for await (const rawChunk of textStream) {
-      const chunkStr = Buffer.isBuffer(rawChunk) ? rawChunk.toString("utf-8") : String(rawChunk);
+      const chunkStr = Buffer.isBuffer(rawChunk) ? decoder.write(rawChunk) : String(rawChunk);
       window += chunkStr;
       while (window.length >= chunkSize) {
         let endIndex = chunkSize;
@@ -1595,9 +1697,13 @@ var DocumentIngestionService = class _DocumentIngestionService {
         if (emitted.length > 0) {
           yield emitted;
         }
-        window = window.slice(Math.max(1, endIndex - overlap));
+        window = window.slice(Math.max(0, endIndex - overlap));
       }
     }
+    const flushed = decoder.end();
+    if (flushed) {
+      window += flushed;
+    }
     const remaining = window.trim();
     if (remaining.length > 0) {
       yield remaining;
@@ -1945,6 +2051,12 @@ var MemoryVectorAdapter = class {
   smlEngine;
   documents = [];
   bm25Index = new BM25Index();
+  setSMLEngine(engine) {
+    this.smlEngine = engine;
+  }
+  getSMLEngine() {
+    return this.smlEngine;
+  }
   /**
    * Adds documents to memory, computes their embeddings, and indexes them in BM25.
    */
@@ -2029,6 +2141,11 @@ var MemoryVectorAdapter = class {
 
 // src/core/engine.ts
 var RAGEngine = class {
+  /**
+   * Initializes a new instance of `RAGEngine` with the provided configuration.
+   * 
+   * @param config - The engine configuration options (`EngineConfig`).
+   */
   constructor(config) {
     this.config = config;
     if (config.tools?.items.some((tool) => tool.isMutating || tool.requiresConfirmation)) {
@@ -2044,8 +2161,22 @@ var RAGEngine = class {
         config.cache?.ttlMs || 1e3 * 60 * 60 * 24
       );
     }
-    this.smlEngine = new SMLEngine({ modelName: config.smlConfig?.modelName });
+    this.smlEngine = new SMLEngine({
+      modelName: config.smlConfig?.modelName,
+      dtype: config.smlConfig?.dtype,
+      cacheDir: config.smlConfig?.cacheDir,
+      localFilesOnly: config.smlConfig?.localFilesOnly,
+      cacheSize: config.smlConfig?.cacheSize,
+      circuitBreakerThreshold: config.smlConfig?.circuitBreakerThreshold,
+      circuitBreakerCooldownMs: config.smlConfig?.circuitBreakerCooldownMs
+    });
     const vectorStore = config.inputs?.vectorStore || new MemoryVectorAdapter(this.smlEngine);
+    if (typeof vectorStore.setSMLEngine === "function") {
+      vectorStore.setSMLEngine(this.smlEngine);
+    }
+    if (config.inputs?.faq && typeof config.inputs.faq.setSMLEngine === "function") {
+      config.inputs.faq.setSMLEngine(this.smlEngine);
+    }
     this.config = {
       ...config,
       inputs: {
@@ -2143,8 +2274,27 @@ var RAGEngine = class {
     await this.toolRegistry.registerTool(tool);
   }
   /**
-   * Executes the query lifecycle:
-   * Security Guardrail -> Cache -> SML Routing -> Retrieval -> Untrusted Boundary Framing -> LLM Generation.
+   * Executes the complete RAG query lifecycle:
+   * 1. Security Inspection (Prompt Injection Defense, PII Masking)
+   * 2. Cache Lookup (Role & Tenant isolated caching)
+   * 3. SML Semantic Routing (FAQ matching and Tool execution)
+   * 4. Hybrid Dense/Sparse Retrieval (Vector search + BM25 keyword search)
+   * 5. Untrusted Boundary Framing (Anti-indirect injection prompt wrapping)
+   * 6. LLM Answer Synthesis & Citation Tagging
+   * 
+   * @param userPrompt - The natural language query or question from the user.
+   * @param context - Optional multi-tenant security context including `tenantId`, `userId`, and `roles`.
+   * @returns Promise resolving to `RAGResponse` containing synthesized answer, citations, intent, and metrics.
+   * 
+   * @example
+   * ```typescript
+   * const response = await engine.query('What is our return policy?', {
+   *   tenantId: 'tenant_123',
+   *   userId: 'usr_456',
+   *   roles: ['customer']
+   * });
+   * console.log(response.answer);
+   * ```
    */
   async query(userPrompt, context) {
     const startTime = Date.now();
@@ -2538,13 +2688,29 @@ var OpenAIAdapter = class _OpenAIAdapter {
   apiKey;
   model;
   endpoint;
-  constructor(apiKey, model, endpoint) {
-    this.apiKey = apiKey || process.env.OPENAI_API_KEY || "";
+  temperature;
+  constructor(configOrApiKey, model, endpoint) {
+    let key = "";
+    let resolvedModel = "";
+    let resolvedEndpoint = "";
+    let temp = 0.1;
+    if (typeof configOrApiKey === "object" && configOrApiKey !== null) {
+      key = configOrApiKey.apiKey || process.env.OPENAI_API_KEY || "";
+      resolvedModel = configOrApiKey.model || process.env.OPENAI_MODEL || process.env.OPENAI_MODEL_FAST || "gpt-4o-mini";
+      resolvedEndpoint = configOrApiKey.endpoint || process.env.OPENAI_ENDPOINT || "https://api.openai.com/v1/chat/completions";
+      if (configOrApiKey.temperature !== void 0) temp = configOrApiKey.temperature;
+    } else {
+      key = configOrApiKey || process.env.OPENAI_API_KEY || "";
+      resolvedModel = model || process.env.OPENAI_MODEL || process.env.OPENAI_MODEL_FAST || "gpt-4o-mini";
+      resolvedEndpoint = endpoint || process.env.OPENAI_ENDPOINT || "https://api.openai.com/v1/chat/completions";
+    }
+    this.apiKey = key;
     if (!this.apiKey) {
       throw new Error("[OpenAIAdapter] API Key not found. Provide it in constructor or set OPENAI_API_KEY in .env");
     }
-    this.model = model || process.env.OPENAI_MODEL || process.env.OPENAI_MODEL_FAST || "gpt-4o-mini";
-    this.endpoint = endpoint || process.env.OPENAI_ENDPOINT || "https://api.openai.com/v1/chat/completions";
+    this.model = resolvedModel;
+    this.endpoint = resolvedEndpoint;
+    this.temperature = temp;
   }
   static createFast(apiKey) {
     return new _OpenAIAdapter(apiKey, process.env.OPENAI_MODEL_FAST || "gpt-4o-mini");
@@ -2560,7 +2726,7 @@ var OpenAIAdapter = class _OpenAIAdapter {
     const body = {
       model: this.model,
       messages,
-      temperature: 0.1
+      temperature: this.temperature
       // Low temperature to reduce hallucination in RAG pipelines
     };
     if (request.tools && request.tools.length > 0) {
@@ -2610,15 +2776,28 @@ var OpenAIAdapter = class _OpenAIAdapter {
 var GeminiAdapter = class _GeminiAdapter {
   apiKey;
   model;
-  constructor(apiKey, model) {
-    this.apiKey = apiKey || process.env.GEMINI_API_KEY || "";
+  temperature;
+  constructor(configOrApiKey, model) {
+    let key = "";
+    let resolvedModel = "";
+    let temp = 0.1;
+    if (typeof configOrApiKey === "object" && configOrApiKey !== null) {
+      key = configOrApiKey.apiKey || process.env.GEMINI_API_KEY || "";
+      resolvedModel = configOrApiKey.model || process.env.GEMINI_MODEL || process.env.GEMINI_MODEL_FAST || "gemini-2.0-flash";
+      if (configOrApiKey.temperature !== void 0) temp = configOrApiKey.temperature;
+    } else {
+      key = configOrApiKey || process.env.GEMINI_API_KEY || "";
+      resolvedModel = model || process.env.GEMINI_MODEL || process.env.GEMINI_MODEL_FAST || "gemini-2.0-flash";
+    }
+    this.apiKey = key;
     if (!this.apiKey) {
       throw new Error("[GeminiAdapter] API Key not found. Provide it in constructor or set GEMINI_API_KEY in .env");
     }
-    this.model = model || process.env.GEMINI_MODEL || process.env.GEMINI_MODEL_FAST || "gemini-1.5-flash";
+    this.model = resolvedModel;
+    this.temperature = temp;
   }
   static createFast(apiKey) {
-    return new _GeminiAdapter(apiKey, process.env.GEMINI_MODEL_FAST || "gemini-1.5-flash");
+    return new _GeminiAdapter(apiKey, process.env.GEMINI_MODEL_FAST || "gemini-2.0-flash");
   }
   static createSmart(apiKey) {
     return new _GeminiAdapter(apiKey, process.env.GEMINI_MODEL_SMART || "gemini-1.5-pro");
@@ -2633,7 +2812,7 @@ var GeminiAdapter = class _GeminiAdapter {
         }
       ],
       generationConfig: {
-        temperature: 0.1
+        temperature: this.temperature
         // Low temperature to reduce hallucination in RAG pipelines
       }
     };
@@ -2697,18 +2876,34 @@ var GeminiAdapter = class _GeminiAdapter {
 
 // src/adapters/llm/openrouter.adapter.ts
 var OpenRouterAdapter = class _OpenRouterAdapter extends OpenAIAdapter {
-  constructor(apiKey, model, endpoint = "https://openrouter.ai/api/v1/chat/completions") {
+  constructor(configOrApiKey, model, endpoint = "https://openrouter.ai/api/v1/chat/completions") {
     if (process.env.ALLOW_PUBLIC_OPENSOURCE_LLM === "false") {
       throw new Error(
         "[OpenRouterAdapter] Blocked by security policy: ALLOW_PUBLIC_OPENSOURCE_LLM is set to false in .env. Corporate prompts cannot be routed to public external open-source models."
       );
     }
-    const key = apiKey || process.env.OPENROUTER_API_KEY || "";
+    let key = "";
+    let resolvedModel = "";
+    let resolvedEndpoint = endpoint;
+    let temp = 0.1;
+    if (typeof configOrApiKey === "object" && configOrApiKey !== null) {
+      key = configOrApiKey.apiKey || process.env.OPENROUTER_API_KEY || "";
+      resolvedModel = configOrApiKey.model || process.env.OPENROUTER_MODEL || process.env.OPENROUTER_MODEL_FAST || "meta-llama/llama-3.2-3b-instruct:free";
+      if (configOrApiKey.endpoint) resolvedEndpoint = configOrApiKey.endpoint;
+      if (configOrApiKey.temperature !== void 0) temp = configOrApiKey.temperature;
+    } else {
+      key = configOrApiKey || process.env.OPENROUTER_API_KEY || "";
+      resolvedModel = model || process.env.OPENROUTER_MODEL || process.env.OPENROUTER_MODEL_FAST || "meta-llama/llama-3.2-3b-instruct:free";
+    }
     if (!key) {
       throw new Error("[OpenRouterAdapter] API Key not found. Provide it in constructor or set OPENROUTER_API_KEY in .env");
     }
-    const resolvedModel = model || process.env.OPENROUTER_MODEL || process.env.OPENROUTER_MODEL_FAST || "meta-llama/llama-3.2-3b-instruct:free";
-    super(key, resolvedModel, endpoint);
+    super({
+      apiKey: key,
+      model: resolvedModel,
+      endpoint: resolvedEndpoint,
+      temperature: temp
+    });
   }
   static createFast(apiKey) {
     return new _OpenRouterAdapter(apiKey, process.env.OPENROUTER_MODEL_FAST || "meta-llama/llama-3.2-3b-instruct:free");
@@ -2865,11 +3060,24 @@ var FallbackLLMProvider = class {
     this.providers = providers;
     this.logFailover = options?.logFailover ?? true;
   }
+  getProviderName(provider, index) {
+    if (provider.name && typeof provider.name === "string") {
+      return provider.name;
+    }
+    if (provider.model && typeof provider.model === "string") {
+      const ctor = provider.constructor?.name && provider.constructor.name !== "Object" ? provider.constructor.name : "LLMProvider";
+      return `${ctor}(${provider.model})`;
+    }
+    if (provider.constructor?.name && provider.constructor.name !== "Object") {
+      return provider.constructor.name;
+    }
+    return `Provider#${index + 1}`;
+  }
   async generate(request) {
     const failureErrors = [];
     for (let i = 0; i < this.providers.length; i++) {
       const provider = this.providers[i];
-      const providerName = provider.constructor.name || `Provider#${i + 1}`;
+      const providerName = this.getProviderName(provider, i);
       try {
         return await provider.generate(request);
       } catch (error) {
@@ -2877,7 +3085,7 @@ var FallbackLLMProvider = class {
         failureErrors.push({ providerName, error: errorMessage });
         if (this.logFailover) {
           const nextProvider = this.providers[i + 1];
-          const nextName = nextProvider ? nextProvider.constructor.name || `Provider#${i + 2}` : "None";
+          const nextName = nextProvider ? this.getProviderName(nextProvider, i + 1) : "None";
           console.warn(
             `[FallbackLLMProvider] ${providerName} failed: "${errorMessage}". Failing over to next provider: ${nextName}`
           );
@@ -3006,8 +3214,12 @@ var TieredLLMProvider = class _TieredLLMProvider {
 // src/adapters/rules/static-rules.adapter.ts
 var StaticRulesAdapter = class {
   rules;
-  constructor(rules) {
-    this.rules = rules;
+  constructor(rules = []) {
+    this.rules = rules.map((r) => {
+      if (typeof r === "string") return r;
+      if (r && typeof r === "object" && typeof r.rule === "string") return r.rule;
+      return String(r);
+    });
   }
   // Optional tenantId can be used for tenant-specific rules
   async getActiveRules(tenantId) {
@@ -3029,6 +3241,12 @@ var LocalFaqAdapter = class {
     this.smlEngine = options?.smlEngine || new SMLEngine();
     this.defaultThreshold = options?.defaultMatchThreshold ?? 0.6;
   }
+  setSMLEngine(engine) {
+    this.smlEngine = engine;
+  }
+  getSMLEngine() {
+    return this.smlEngine;
+  }
   /**
    * Initializes the adapter by reading the JSON file and caching embeddings in RAM.
    */

package/dist/core/engine.d.ts

@@ -5,6 +5,34 @@ import type { Job } from './queue/job-queue.interface.js';
 import type { QueryContext } from '../interfaces/query-context.interface.js';
 import type { ToolAuditLog } from '../interfaces/tool.interface.js';
 import type { ICacheAdapter } from '../interfaces/cache.interface.js';
+/**
+ * Enterprise Production-Grade Retrieval-Augmented Generation (RAG) Engine.
+ *
+ * Features:
+ * - Multi-tenant isolation & zero-trust security guardrails (prompt injection detection, PII redaction, boundary framing).
+ * - Pluggable LLM providers (Gemini, OpenAI, Ollama, Tiered, Fallback).
+ * - In-process Small Machine Learning (SML) engine for sub-millisecond semantic routing and multilingual embeddings.
+ * - Hybrid dense/sparse vector retrieval with Reciprocal Rank Fusion (RRF).
+ * - Governed tool execution with role-based access control (RBAC) and cryptographic mutation tickets.
+ * - High-throughput document ingestion supporting PDF (/FlateDecode decompressed), Markdown, and text streams.
+ *
+ * @example
+ * ```typescript
+ * const engine = new RAGEngine({
+ *   llmProvider: new GeminiAdapter({ apiKey: process.env.GEMINI_API_KEY }),
+ *   inputs: {
+ *     vectorStore: new PostgresVectorAdapter({ connectionString: process.env.DATABASE_URL })
+ *   }
+ * });
+ *
+ * const response = await engine.query('Summarize our Q3 compliance audit report.', {
+ *   tenantId: 'enterprise-client-42',
+ *   userId: 'usr_8472',
+ *   roles: ['compliance_officer']
+ * });
+ * console.log(response.answer, response.sources);
+ * ```
+ */
 export declare class RAGEngine {
     private config;
     private confirmationService;
@@ -17,6 +45,11 @@ export declare class RAGEngine {
     private initPromise;
     private auditLogs;
     private readonly maxAuditLogs;
+    /**
+     * Initializes a new instance of `RAGEngine` with the provided configuration.
+     *
+     * @param config - The engine configuration options (`EngineConfig`).
+     */
     constructor(config: EngineConfig);
     /**
      * Records a tool audit log entry into a bounded ring buffer (max 1000 items)
@@ -31,8 +64,27 @@ export declare class RAGEngine {
     init(): Promise<void>;
     registerTool(tool: any): Promise<void>;
     /**
-     * Executes the query lifecycle:
-     * Security Guardrail -> Cache -> SML Routing -> Retrieval -> Untrusted Boundary Framing -> LLM Generation.
+     * Executes the complete RAG query lifecycle:
+     * 1. Security Inspection (Prompt Injection Defense, PII Masking)
+     * 2. Cache Lookup (Role & Tenant isolated caching)
+     * 3. SML Semantic Routing (FAQ matching and Tool execution)
+     * 4. Hybrid Dense/Sparse Retrieval (Vector search + BM25 keyword search)
+     * 5. Untrusted Boundary Framing (Anti-indirect injection prompt wrapping)
+     * 6. LLM Answer Synthesis & Citation Tagging
+     *
+     * @param userPrompt - The natural language query or question from the user.
+     * @param context - Optional multi-tenant security context including `tenantId`, `userId`, and `roles`.
+     * @returns Promise resolving to `RAGResponse` containing synthesized answer, citations, intent, and metrics.
+     *
+     * @example
+     * ```typescript
+     * const response = await engine.query('What is our return policy?', {
+     *   tenantId: 'tenant_123',
+     *   userId: 'usr_456',
+     *   roles: ['customer']
+     * });
+     * console.log(response.answer);
+     * ```
      */
     query(userPrompt: string, context?: QueryContext): Promise<RAGResponse>;
     /**

package/dist/core/metrics/rag-evaluator.d.ts

@@ -49,6 +49,11 @@ export declare class RAGEvaluator {
         grounded: boolean;
         groundingScore: number;
     };
+    /**
+     * Evaluates Answer Faithfulness / Groundedness using deterministic heuristics.
+     * Note: This measures lexical consistency, numerical overlap, and negation polarity.
+     * It serves as a fast in-process heuristic filter and is not an external semantic LLM judge.
+     */
     static evaluateFaithfulness(answer: string, contextTexts: string[]): FaithfulnessEvalResult;
     /**
      * Conducts a full RAG evaluation given a query, generated answer, retrieved docs, and ground truth IDs.

package/dist/core/queue/job-queue.interface.d.ts

@@ -1,4 +1,11 @@
 export type JobStatus = 'pending' | 'queued' | 'processing' | 'completed' | 'failed';
+export declare const JobStatusValues: {
+    readonly PENDING: 'pending';
+    readonly QUEUED: 'queued';
+    readonly PROCESSING: 'processing';
+    readonly COMPLETED: 'completed';
+    readonly FAILED: 'failed';
+};
 export interface Job<TData = any, TResult = any> {
     attemptsMade?: number | undefined;
     maxAttempts?: number | undefined;