@denizsvnc/ai-rag-engine 2.2.0 → 2.2.2

package/CHANGELOG.md

@@ -1,8 +1,30 @@
 # Changelog
 
-This file follows Semantic Versioning. Entries are maintained by the repository owner. No npm publication or Git tag is implied by an entry.
+This file follows Semantic Versioning.
 
-## 2.2.0 — Unreleased
+## 2.2.2 — 2026-11-10
+
+### Fixed
+
+- **Document Ingestion:** Resolved infinite decaying chunk loop in `DocumentIngestionService.chunkText` when `endIndex >= text.length`.
+- **Security & Prompt Injection:** Resolved regex boundary and preposition issues in `InjectionDetector` for English DAN jailbreak attacks (`in DAN mode`) and Turkish Unicode word boundaries (`ş, ç`).
+- **LLM Failover Logging:** Replaced generic `Object failed` error message in `FallbackLLMProvider` with dynamic provider, model, or constructor resolution.
+- **Rules Adapter:** Extended `StaticRulesAdapter` to accept structured rule objects (`{ id, rule }`) alongside plain string arrays via polymorphic `RuleInput`.
+- **Performance & SML Sharing:** Prevented redundant ONNX model downloads and duplicate memory footprint by sharing `SMLEngine` instances across `RAGEngine`, `LocalFaqAdapter`, and `MemoryVectorAdapter`.
+
+### Added
+
+- Exported `JobStatusValues` constants in `job-queue.interface.ts` to prevent casing mismatches.
+- Exported `RuleInput` type in root exports.
+
+## 2.2.1 — 2026-11-10
+
+### Documentation
+
+- Updated `README.md`, `README_tr.md`, and `README_de.md` with verified, type-safe production examples featuring `GeminiAdapter`, `PostgresVectorAdapter`, `RedisCacheAdapter`, `LocalFaqAdapter`, and `SecurityConfig`.
+- Removed legacy pre-publication disclaimers and streamlined installation documentation for live npm consumption.
+
+## 2.2.0 — 2026-11-10
 
 ### Added
 

package/README.md

@@ -22,27 +22,14 @@
 
 </div>
 
-**Publication status:** prepared locally for `@denizsvnc/ai-rag-engine@2.2.0`; this is not a claim that it is already available on npm. Scope ownership and publication remain the maintainer's responsibility.
-
 ## Requirements and installation
 
 ESM only. Node.js **22.14 or newer**; the compatibility matrix covers Node 22 and 24. TypeScript consumers should use TypeScript 5.8+ with NodeNext or Bundler resolution. Runtime applications do not need TypeScript or build tools.
 
-After publication:
-
 ```sh
 npm install @denizsvnc/ai-rag-engine
 ```
 
-Before publication, install a locally built artifact:
-
-```sh
-npm ci
-npm pack
-# From a different project:
-npm install /absolute/path/to/denizsvnc-ai-rag-engine-2.2.0.tgz
-```
-
 ## Quick Start
 
 This deterministic example needs no credentials, model download, HTTP server, or database. The provider and vector adapter are test doubles demonstrating the integration contract; use real adapters for application data.
@@ -75,6 +62,71 @@ const result = await engine.query('What is the return window?', {
 console.log(result.answer); // Returns: 14 days.
 ```
 
+### Production Example (Multi-Tenant with Gemini, pgvector & Redis)
+
+For production applications with external LLMs, multi-tenant persistence, and distributed caching:
+
+```ts
+import {
+  RAGEngine,
+  GeminiAdapter,
+  PostgresVectorAdapter,
+  RedisCacheAdapter,
+  LocalFaqAdapter
+} from '@denizsvnc/ai-rag-engine';
+
+const engine = new RAGEngine({
+  // 1. LLM Provider (Gemini, OpenAI, Ollama, or Custom)
+  llmProvider: new GeminiAdapter(
+    process.env.GEMINI_API_KEY,
+    'gemini-1.5-flash'
+  ),
+
+  // 2. Knowledge Retrieval & Semantic FAQ Matching
+  inputs: {
+    vectorStore: new PostgresVectorAdapter({
+      connectionString: process.env.DATABASE_URL,
+      tableName: 'enterprise_embeddings'
+    }),
+    faq: new LocalFaqAdapter({
+      filePath: './faq.json',
+      defaultMatchThreshold: 0.65
+    })
+  },
+
+  // 3. Distributed Cache & Security Guardrails
+  cache: {
+    enabled: true,
+    adapter: new RedisCacheAdapter({
+      url: process.env.REDIS_URL,
+      defaultTtlMs: 3600000 // 1 hour
+    })
+  },
+  security: {
+    enabled: true,
+    blockHighRiskInjections: true,
+    pii: {
+      enabled: true,
+      maskTCKN: true,
+      maskCreditCards: true,
+      maskEmails: true
+    }
+  }
+});
+
+// Query with tenant isolation & role-based access
+const response = await engine.query('Q3 compliance audit summary', {
+  tenantId: 'tenant-acme',
+  userId: 'usr_8472',
+  roles: ['compliance_officer']
+});
+
+console.log(response.answer);
+console.log('Intent:', response.intent);
+console.log('Latency (ms):', response.latencyMs);
+console.log('Sources:', response.sources);
+```
+
 Importing the SDK does not start a server, load `.env`, open Redis/PostgreSQL connections, download models, or change the Transformers global environment. Constructors and explicit initialization perform the operations described in [the usage guide](docs/USAGE.md).
 
 ## Capabilities and operational boundaries
@@ -96,7 +148,7 @@ Prompt filters and PII patterns are defenses with limitations, not guarantees of
 - [Configuration, real providers, vectors, FAQ, tools and troubleshooting](docs/USAGE.md)
 - [Versioning, manual publication and release checklist](docs/RELEASING.md)
 - [Changelog](CHANGELOG.md)
-- [Detailed local release-readiness report](https://github.com/Denizsvnc/ai-rag-engine/blob/main/docs/NPM_RELEASE_READINESS.md)
+- [Detailed release-readiness report](docs/NPM_RELEASE_READINESS.md)
 
 ## Repository verification
 

package/dist/adapters/faq/local-faq.adapter.d.ts

@@ -16,6 +16,8 @@ export declare class LocalFaqAdapter implements IFAQAdapter {
     private items;
     private isLoaded;
     constructor(options?: LocalFaqAdapterOptions);
+    setSMLEngine(engine: SMLEngine): void;
+    getSMLEngine(): SMLEngine;
     /**
      * Initializes the adapter by reading the JSON file and caching embeddings in RAM.
      */

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

@@ -6,5 +6,6 @@ export declare class FallbackLLMProvider implements ILLMProvider {
     private providers;
     private logFailover;
     constructor(providers: ILLMProvider[], options?: FallbackProviderOptions);
+    private getProviderName;
     generate(request: ILLMRequest): Promise<ILLMResponse>;
 }

package/dist/adapters/rules/static-rules.adapter.d.ts

@@ -1,6 +1,11 @@
 import type { IRulesAdapter } from '../../interfaces/rules.interface.js';
+export type RuleInput = string | {
+    id?: string;
+    rule: string;
+    [key: string]: any;
+};
 export declare class StaticRulesAdapter implements IRulesAdapter {
     private rules;
-    constructor(rules: string[]);
+    constructor(rules?: Array<RuleInput>);
     getActiveRules(tenantId?: string): Promise<string[]>;
 }

package/dist/adapters/vector/memory-vector.adapter.d.ts

@@ -6,6 +6,8 @@ export declare class MemoryVectorAdapter implements IVectorStoreAdapter {
     private documents;
     private bm25Index;
     constructor(smlEngine?: SMLEngine);
+    setSMLEngine(engine: SMLEngine): void;
+    getSMLEngine(): SMLEngine;
     /**
      * Adds documents to memory, computes their embeddings, and indexes them in BM25.
      */

package/dist/api/server.js

@@ -535,11 +535,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",
@@ -1565,6 +1565,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;
@@ -1945,6 +1948,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.
    */
@@ -2046,6 +2055,12 @@ var RAGEngine = class {
     }
     this.smlEngine = new SMLEngine({ modelName: config.smlConfig?.modelName });
     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: {
@@ -2865,11 +2880,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 +2905,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 +3034,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 +3061,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/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;

package/dist/index.d.ts

@@ -39,7 +39,7 @@ export { OllamaAdapter, type OllamaConfig } from './adapters/llm/ollama.adapter.
 export { FallbackLLMProvider, type FallbackProviderOptions } from './adapters/llm/fallback.adapter.js';
 export { TieredLLMProvider, type TieredLLMConfig } from './adapters/llm/tiered.adapter.js';
 export { MemoryVectorAdapter } from './adapters/vector/memory-vector.adapter.js';
-export { StaticRulesAdapter } from './adapters/rules/static-rules.adapter.js';
+export { StaticRulesAdapter, type RuleInput } from './adapters/rules/static-rules.adapter.js';
 export { UrlFaqAdapter } from './adapters/faq/url-faq.adapter.js';
 export { LocalFaqAdapter, type LocalFaqAdapterOptions } from './adapters/faq/local-faq.adapter.js';
 export { RedisConfirmationNonceStore, MemoryConfirmationNonceStore, type ConfirmationNonceStore } from './core/security/nonce-store.js';

package/dist/index.js

@@ -531,11 +531,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",
@@ -1561,6 +1561,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;
@@ -1941,6 +1944,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.
    */
@@ -2042,6 +2051,12 @@ var RAGEngine = class {
     }
     this.smlEngine = new SMLEngine({ modelName: config.smlConfig?.modelName });
     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: {
@@ -2708,6 +2723,15 @@ var RAGEvaluator = class {
   }
 };
 
+// src/core/queue/job-queue.interface.ts
+var JobStatusValues = {
+  PENDING: "pending",
+  QUEUED: "queued",
+  PROCESSING: "processing",
+  COMPLETED: "completed",
+  FAILED: "failed"
+};
+
 // src/core/queue/bullmq-queue.ts
 import { Queue, Worker, UnrecoverableError } from "bullmq";
 import { Redis } from "ioredis";
@@ -3716,11 +3740,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) {
@@ -3728,7 +3765,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}`
           );
@@ -3857,8 +3894,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) {
@@ -3915,6 +3956,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.
    */
@@ -4474,6 +4521,7 @@ export {
   IngestionWorker,
   InjectionDetector,
   InputSanitizer,
+  JobStatusValues,
   LocalFaqAdapter,
   MemoryConfirmationNonceStore,
   MemoryVectorAdapter,

package/dist/worker.js

@@ -1237,6 +1237,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;

package/docs/RELEASING.md

@@ -2,7 +2,7 @@
 
 ## Policy
 
-The recommended first public version is **2.2.0**: the repository already identifies its preceding API as 2.1.0, and the new distribution includes durable ingestion and persistence. No public npm history or tag was found during preparation. This recommendation does not assert that any version was published. The maintainer must approve the version before publication. If API stabilization is still desired, use a deliberate `2.2.0-rc.1` prerelease and a non-latest dist-tag.
+The recommended first public version is **2.2.0**: the repository already identifies its preceding API as 2.1.0, and the new distribution includes durable ingestion and persistence. Version **2.2.0** is the official initial release published on npm under `@denizsvnc/ai-rag-engine`.
 
 After the first public release, use patch releases for compatible fixes, minor releases for compatible features, and major releases for incompatible public API, security-contract or supported-runtime changes. Document security-driven breaks and migration paths. Never reuse a published version; do not silently modify artifacts after review.
 

package/docs/USAGE.md

@@ -2,7 +2,13 @@
 
 ## Runtime and module contract
 
-Install `@denizsvnc/ai-rag-engine` after publication, or its local `.tgz` before publication. Use ESM (`"type": "module"` in the application). CommonJS `require()` is not a supported contract; CommonJS applications can use asynchronous `import()`. Node.js 22.14+ is required; Node 22/24 are the explicit test matrix. TypeScript 5.8+ is recommended; NodeNext and Bundler resolution are validated with strict checking. `skipLibCheck` is not required. Supported exports are the root API and `./package.json`; internal `dist/` paths are private. CLI commands are separate entry points.
+Install `@denizsvnc/ai-rag-engine` from npm:
+
+```sh
+npm install @denizsvnc/ai-rag-engine
+```
+
+Use ESM (`"type": "module"` in the application). CommonJS `require()` is not a supported contract; CommonJS applications can use asynchronous `import()`. Node.js 22.14+ is required; Node 22/24 are the explicit test matrix. TypeScript 5.8+ is recommended; NodeNext and Bundler resolution are validated with strict checking. `skipLibCheck` is not required. Supported exports are the root API and `./package.json`; internal `dist/` paths are private. CLI commands are separate entry points.
 
 The library never automatically loads `.env`. Applications may call `dotenv.config()` themselves. The server/worker/migration CLIs explicitly load `.env`. Importing the root library creates no server, connection, model download, or background worker. Native Transformers is imported lazily on the first embedding initialization.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@denizsvnc/ai-rag-engine",
-  "version": "2.2.0",
+  "version": "2.2.2",
   "description": "TypeScript RAG engine with pluggable providers, local semantic routing, tenant-aware retrieval, and durable document ingestion.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",