@denizsvnc/ai-rag-engine 2.2.2 → 2.2.3

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 This file follows Semantic Versioning.
 
+## 2.2.3 — 2026-11-10
+
+### Fixed
+
+- **Transformers.js Concurrency Lock:** Implemented static Promise lock chain (`acquireInitLock`) in `SMLEngine` to serialize `init()` calls across independent instances and isolate mutable Transformers.js global `env`. Model inference remains fully concurrent.
+- **LLM Adapter Constructor Flexibility:** Dual constructor signatures added to `GeminiAdapter`, `OpenAIAdapter`, and `OpenRouterAdapter` accepting both `{ apiKey, model, temperature }` configuration objects and positional parameters.
+- **Document Chunking Bounds & Streaming UTF-8 Decoder:** Enforced `RangeError` on invalid chunk boundaries (`chunkSize > 0`, `overlap < chunkSize`). Added `StringDecoder('utf-8')` to prevent split multi-byte characters (e.g. Turkish `ş`, `ğ`) across stream chunks.
+- **Native zlib PDF FlateDecode Ingestion:** Integrated Node's native `zlib.inflateSync` & `inflateRawSync` for zero-dependency decompression of vector PDF streams.
+- **RAGEvaluator Heuristics & Polarity:** Ensured empty answers score 0.0; deduplicated retrieved IDs; added English & Turkish negation and polarity contradiction checks.
+
+### Added
+
+- **Bun Runtime Compatibility:** Dedicated Bun test suite (`test/bun/bun-compat.test.ts`) and npm script `npm run test:bun` verifying ONNX embeddings, PII masking, vector math, and RAG execution under Bun v1.4.4+.
+- **CI Workflow Hardening:** Added automated Bun compatibility verification job in GitHub Actions CI workflow.
+- **Engineering & Security Audits:** Comprehensive audit documentation covering Baseline, Architecture, Security (OWASP Top 10 LLM), Invariants, Performance Benchmarks, RAG Evaluation, and Node/Bun Compatibility in `docs/audits/`.
+
 ## 2.2.2 — 2026-11-10
 
 ### Fixed

package/dist/adapters/llm/gemini.adapter.d.ts

@@ -1,8 +1,17 @@
 import type { ILLMProvider, ILLMRequest, ILLMResponse } from '../../interfaces/llm.interface.js';
+export interface GeminiConfig {
+    /** Google Gemini API Key. Defaults to process.env.GEMINI_API_KEY. */
+    apiKey?: string | undefined;
+    /** Model identifier (e.g. 'gemini-2.0-flash', 'gemini-1.5-flash', 'gemini-1.5-pro'). Defaults to process.env.GEMINI_MODEL || 'gemini-2.0-flash'. */
+    model?: string | undefined;
+    /** Sampling temperature. Defaults to 0.1 for deterministic RAG answers. */
+    temperature?: number | undefined;
+}
 export declare class GeminiAdapter implements ILLMProvider {
     private apiKey;
     private model;
-    constructor(apiKey?: string, model?: string);
+    private temperature;
+    constructor(configOrApiKey?: string | GeminiConfig, model?: string);
     static createFast(apiKey?: string): GeminiAdapter;
     static createSmart(apiKey?: string): GeminiAdapter;
     generate(request: ILLMRequest): Promise<ILLMResponse>;

package/dist/adapters/llm/openai.adapter.d.ts

@@ -1,9 +1,20 @@
 import type { ILLMProvider, ILLMRequest, ILLMResponse } from '../../interfaces/llm.interface.js';
+export interface OpenAIConfig {
+    /** OpenAI API Key. Defaults to process.env.OPENAI_API_KEY. */
+    apiKey?: string | undefined;
+    /** Model identifier (e.g. 'gpt-4o-mini', 'gpt-4o'). Defaults to process.env.OPENAI_MODEL || 'gpt-4o-mini'. */
+    model?: string | undefined;
+    /** Base API endpoint. Defaults to 'https://api.openai.com/v1/chat/completions'. */
+    endpoint?: string | undefined;
+    /** Sampling temperature. Defaults to 0.1 for deterministic RAG answers. */
+    temperature?: number | undefined;
+}
 export declare class OpenAIAdapter implements ILLMProvider {
     protected apiKey: string;
     protected model: string;
     protected endpoint: string;
-    constructor(apiKey?: string, model?: string, endpoint?: string);
+    protected temperature: number;
+    constructor(configOrApiKey?: string | OpenAIConfig, model?: string, endpoint?: string);
     static createFast(apiKey?: string): OpenAIAdapter;
     static createSmart(apiKey?: string): OpenAIAdapter;
     generate(request: ILLMRequest): Promise<ILLMResponse>;

package/dist/adapters/llm/openrouter.adapter.d.ts

@@ -1,6 +1,8 @@
-import { OpenAIAdapter } from './openai.adapter.js';
+import { OpenAIAdapter, type OpenAIConfig } from './openai.adapter.js';
+export interface OpenRouterConfig extends OpenAIConfig {
+}
 export declare class OpenRouterAdapter extends OpenAIAdapter {
-    constructor(apiKey?: string, model?: string, endpoint?: string);
+    constructor(configOrApiKey?: string | OpenRouterConfig, model?: string, endpoint?: string);
     static createFast(apiKey?: string): OpenRouterAdapter;
     static createSmart(apiKey?: string): OpenRouterAdapter;
 }

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;
-        }
-      }).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);
+          releaseLock();
         }
-        throw err;
-      });
+      })();
     }
     return this.extractorPromise;
   }
@@ -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;
@@ -1576,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;
@@ -1598,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;
@@ -2038,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)) {
@@ -2053,7 +2161,15 @@ 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);
@@ -2158,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();
@@ -2553,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");
@@ -2575,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) {
@@ -2625,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");
@@ -2648,7 +2812,7 @@ var GeminiAdapter = class _GeminiAdapter {
         }
       ],
       generationConfig: {
-        temperature: 0.1
+        temperature: this.temperature
         // Low temperature to reduce hallucination in RAG pipelines
       }
     };
@@ -2712,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");

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.