@denizsvnc/ai-rag-engine 2.2.2 → 2.2.3

package/dist/core/sml-engine.d.ts

@@ -11,17 +11,53 @@ export interface EmbeddingExtractor {
 export declare class CircuitBreakerOpenError extends Error {
     constructor(message: string);
 }
+/**
+ * Industry-standard ONNX embedding model presets for the Small Machine Learning (SML) engine.
+ * Powered by `@huggingface/transformers` without requiring Python or external API keys.
+ */
+export declare const SMLModelPresets: {
+    /**
+     * Ultra-fast English embedding model (~30MB q8 ONNX).
+     * Ideal for English-only workloads, low-latency semantic routing, and minimal RAM footprint.
+     */
+    readonly ENGLISH_FAST: 'Xenova/all-MiniLM-L6-v2';
+    /**
+     * Highly recommended balanced multilingual model (~117MB q8 ONNX).
+     * Provides exceptional semantic similarity across 50+ languages including Turkish, German, English, French, and Spanish.
+     */
+    readonly MULTILINGUAL: 'Xenova/paraphrase-multilingual-MiniLM-L12-v2';
+    /**
+     * Heavyweight high-accuracy multilingual foundation model (1024-dim, long context, 100+ languages).
+     * Highest precision across mixed-language corpora, but requires higher memory and CPU allocation.
+     */
+    readonly MULTILINGUAL_ACCURATE: 'Xenova/bge-m3';
+};
+export type SMLModelPreset = typeof SMLModelPresets[keyof typeof SMLModelPresets];
 export interface SMLEngineConfig {
+    /** Directory where downloaded ONNX models are cached. Defaults to process.env.RAG_MODEL_CACHE_DIR or './data/models'. */
     cacheDir?: string | undefined;
+    /** When true, only loads models already present on local disk and prevents external network fetching. */
     localFilesOnly?: boolean | undefined;
-    modelName?: string | undefined;
+    /**
+     * Hugging Face ONNX model identifier.
+     * Use a preset (e.g. `SMLModelPresets.MULTILINGUAL`) or pass any custom HuggingFace model string (e.g. `'my-org/my-custom-model'`).
+     * Defaults to `'Xenova/all-MiniLM-L6-v2'`.
+     */
+    modelName?: string | SMLModelPreset | undefined;
+    /** Maximum number of precomputed query/document embeddings retained in RAM LRU cache. Defaults to 1000. */
     cacheSize?: number | undefined;
+    /** Model quantization data type: 'q8' (default), 'fp32', 'fp16', or 'q4'. */
     dtype?: 'q8' | 'fp32' | 'fp16' | 'q4' | undefined;
+    /** Legacy flag for quantization: false forces 'fp32'. */
     quantized?: boolean | undefined;
+    /** Number of consecutive load failures before tripping the circuit breaker OPEN. Defaults to 3. */
     circuitBreakerThreshold?: number | undefined;
+    /** Cooldown period in milliseconds before re-testing model recovery. Defaults to 15000 (15s). */
     circuitBreakerCooldownMs?: number | undefined;
 }
 export declare class SMLEngine {
+    private static initLockChain;
+    private static acquireInitLock;
     private readonly modelName;
     private readonly cacheDir;
     private readonly localFilesOnly;

package/dist/index.d.ts

@@ -8,7 +8,7 @@ export * from './interfaces/cache.interface.js';
 export * from './interfaces/llm.interface.js';
 export * from './core/security/security.types.js';
 export { RAGEngine } from './core/engine.js';
-export { SMLEngine, type SMLEngineConfig, type EmbeddingExtractor, CircuitBreakerOpenError } from './core/sml-engine.js';
+export { SMLEngine, SMLModelPresets, type SMLModelPreset, type SMLEngineConfig, type EmbeddingExtractor, CircuitBreakerOpenError } from './core/sml-engine.js';
 export { ToolRegistry } from './core/tool-registry.js';
 export { CacheManager } from './core/cache-manager.js';
 export { PromptBuilder, type PromptContext } from './core/prompt-builder.js';
@@ -31,9 +31,9 @@ export { RedisCacheAdapter, type IRedisClientLike, type RedisCacheOptions } from
 export { createRagMiddleware } from './api/middleware.js';
 export { createApiRoutes, type ApiRouteOptions } from './api/routes.js';
 export { createAuthToken, verifyAuthToken, createAuthMiddleware, requireRoles, type AuthTokenPayload, type AuthMiddlewareOptions } from './api/auth.js';
-export { OpenAIAdapter } from './adapters/llm/openai.adapter.js';
-export { GeminiAdapter } from './adapters/llm/gemini.adapter.js';
-export { OpenRouterAdapter } from './adapters/llm/openrouter.adapter.js';
+export { OpenAIAdapter, type OpenAIConfig } from './adapters/llm/openai.adapter.js';
+export { GeminiAdapter, type GeminiConfig } from './adapters/llm/gemini.adapter.js';
+export { OpenRouterAdapter, type OpenRouterConfig } from './adapters/llm/openrouter.adapter.js';
 export { CustomLLMAdapter, type CustomLLMConfig } from './adapters/llm/custom.adapter.js';
 export { OllamaAdapter, type OllamaConfig } from './adapters/llm/ollama.adapter.js';
 export { FallbackLLMProvider, type FallbackProviderOptions } from './adapters/llm/fallback.adapter.js';

package/dist/index.js

@@ -164,7 +164,36 @@ var CircuitBreakerOpenError = class extends Error {
     this.name = "CircuitBreakerOpenError";
   }
 };
-var SMLEngine = class {
+var SMLModelPresets = {
+  /**
+   * Ultra-fast English embedding model (~30MB q8 ONNX).
+   * Ideal for English-only workloads, low-latency semantic routing, and minimal RAM footprint.
+   */
+  ENGLISH_FAST: "Xenova/all-MiniLM-L6-v2",
+  /**
+   * Highly recommended balanced multilingual model (~117MB q8 ONNX).
+   * Provides exceptional semantic similarity across 50+ languages including Turkish, German, English, French, and Spanish.
+   */
+  MULTILINGUAL: "Xenova/paraphrase-multilingual-MiniLM-L12-v2",
+  /**
+   * Heavyweight high-accuracy multilingual foundation model (1024-dim, long context, 100+ languages).
+   * Highest precision across mixed-language corpora, but requires higher memory and CPU allocation.
+   */
+  MULTILINGUAL_ACCURATE: "Xenova/bge-m3"
+};
+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;
@@ -224,48 +253,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;
   }
@@ -1207,6 +1250,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";
@@ -1458,17 +1503,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, "\\");
@@ -1483,7 +1582,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;
@@ -1528,7 +1627,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) => {
@@ -1538,8 +1637,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;
@@ -1572,11 +1680,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;
@@ -1594,9 +1710,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;
@@ -2034,6 +2154,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)) {
@@ -2049,7 +2174,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);
@@ -2154,8 +2287,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();
@@ -2592,7 +2744,9 @@ var RAGEvaluator = class {
    * Proportion of retrieved documents in the top-K that are genuinely relevant.
    */
   static precisionAtK(retrievedIds, relevantIds, k = 3) {
-    const topK = retrievedIds.slice(0, k);
+    if (!Number.isFinite(k) || k <= 0) return 0;
+    const uniqueRetrieved = Array.from(new Set(retrievedIds));
+    const topK = uniqueRetrieved.slice(0, k);
     if (topK.length === 0) return 0;
     const relevantSet = new Set(relevantIds);
     const hits = topK.filter((id) => relevantSet.has(id)).length;
@@ -2604,7 +2758,9 @@ var RAGEvaluator = class {
    */
   static recallAtK(retrievedIds, relevantIds, k = 3) {
     if (relevantIds.length === 0) return 1;
-    const topK = retrievedIds.slice(0, k);
+    if (!Number.isFinite(k) || k <= 0) return 0;
+    const uniqueRetrieved = Array.from(new Set(retrievedIds));
+    const topK = uniqueRetrieved.slice(0, k);
     const relevantSet = new Set(relevantIds);
     const hits = topK.filter((id) => relevantSet.has(id)).length;
     return Number((hits / relevantIds.length).toFixed(4));
@@ -2638,28 +2794,44 @@ var RAGEvaluator = class {
       groundingScore: res.score
     };
   }
+  /**
+   * 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, contextTexts) {
+    if (!answer || answer.trim().length === 0) {
+      return {
+        score: 0,
+        lexicalGroundingScore: 0,
+        totalSentences: 0,
+        groundedSentences: 0,
+        contradictionsDetected: [],
+        ungroundedClaims: ["Empty answer provided"]
+      };
+    }
     const combinedContext = contextTexts.join(" ").toLowerCase();
     const contextClean = combinedContext.replace(/[^\p{L}\p{N}\s]/gu, " ");
     const contextWordTokens = new Set(contextClean.split(/\s+/).filter((w) => w.length > 2));
     const contextNumbers = new Set(
       (combinedContext.match(/\b\d+(?:[\.,]\d+)?\b/g) || []).map((n) => n.replace(",", "."))
     );
-    const sentences = answer.split(/(?<=[.!?])\s+/).map((s) => s.trim()).filter((s) => s.length > 10);
+    const sentences = answer.split(/(?<=[.!?])\s+/).map((s) => s.trim()).filter((s) => s.length > 0);
     if (sentences.length === 0) {
       return {
-        score: 1,
-        lexicalGroundingScore: 1,
+        score: 0,
+        lexicalGroundingScore: 0,
         totalSentences: 0,
         groundedSentences: 0,
         contradictionsDetected: [],
-        ungroundedClaims: []
+        ungroundedClaims: ["No meaningful sentences detected"]
       };
     }
     const ungroundedClaims = [];
     const contradictionsDetected = [];
     let groundedCount = 0;
     let totalLexicalOverlapSum = 0;
+    const negationTokens = /* @__PURE__ */ new Set(["not", "never", "cannot", "de\u011Fil", "yok", "olumsuz", "asla", "hay\u0131r"]);
     for (const sentence of sentences) {
       const lowerSentence = sentence.toLowerCase();
       const sentenceNumbers = (lowerSentence.match(/\b\d+(?:[\.,]\d+)?\b/g) || []).map((n) => n.replace(",", "."));
@@ -2673,16 +2845,28 @@ var RAGEvaluator = class {
           break;
         }
       }
-      const words = lowerSentence.replace(/[^\p{L}\p{N}\s]/gu, " ").split(/\s+/).filter((w) => w.length > 2);
+      const rawWords = lowerSentence.replace(/[^\p{L}\p{N}\s]/gu, " ").split(/\s+/).filter((w) => w.length > 0);
+      const sentenceNegations = rawWords.filter((w) => negationTokens.has(w));
+      let hasNegationMismatch = false;
+      if (sentenceNegations.length > 0) {
+        const contextHasNegation = sentenceNegations.some((neg) => contextWordTokens.has(neg) || combinedContext.includes(neg));
+        if (!contextHasNegation) {
+          hasNegationMismatch = true;
+          contradictionsDetected.push(
+            `Polarity Warning: Negation '${sentenceNegations.join(", ")}' in "${sentence}" absent from retrieved context.`
+          );
+        }
+      }
+      const words = rawWords.filter((w) => w.length > 2);
       if (words.length === 0) {
-        if (!hasNumberContradiction) groundedCount++;
+        if (!hasNumberContradiction && !hasNegationMismatch) groundedCount++;
         totalLexicalOverlapSum += 1;
         continue;
       }
       const groundedWords = words.filter((word) => contextWordTokens.has(word) || combinedContext.includes(word));
       const overlapRatio = groundedWords.length / words.length;
       totalLexicalOverlapSum += overlapRatio;
-      if (overlapRatio >= 0.4 && !hasNumberContradiction) {
+      if (overlapRatio >= 0.4 && !hasNumberContradiction && !hasNegationMismatch) {
         groundedCount++;
       } else {
         ungroundedClaims.push(sentence);
@@ -3413,13 +3597,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");
@@ -3435,7 +3635,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) {
@@ -3485,15 +3685,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");
@@ -3508,7 +3721,7 @@ var GeminiAdapter = class _GeminiAdapter {
         }
       ],
       generationConfig: {
-        temperature: 0.1
+        temperature: this.temperature
         // Low temperature to reduce hallucination in RAG pipelines
       }
     };
@@ -3572,18 +3785,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");
@@ -4539,6 +4768,7 @@ export {
   RedisCacheAdapter,
   RedisConfirmationNonceStore,
   SMLEngine,
+  SMLModelPresets,
   SecurityGuard,
   StaticRulesAdapter,
   TieredLLMProvider,