@denizsvnc/ai-rag-engine 0.0.0-stage → 2.2.1

package/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+This file follows Semantic Versioning.
+
+## 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
+
+- Scoped npm distribution preparation for `@denizsvnc/ai-rag-engine`, explicit Node.js/ESM contract and package metadata.
+- Package allowlist verification and independent JavaScript/strict TypeScript consumer tests.
+- PostgreSQL/pgvector retrieval, document version manifests and revision-aware shared query caching.
+- Separate BullMQ ingestion worker, shared PostgreSQL upload/outbox, tenant quotas, retries and crash recovery.
+- Redis tenant rate limiting, provider timeouts and latency histogram accounting.
+
+### Fixed
+
+- Root import no longer eagerly loads Transformers or mutates its global cache configuration.
+- Builds clean stale artifacts, target Node-compatible JavaScript and omit broken declaration maps/demo data.
+- Public declarations resolve under NodeNext; runtime TypeScript tools are unnecessary.
+- Newly written local cache and tool-registry files use POSIX mode 0600.
+
+### Migration notes
+
+- Package identity changes from the repository's unscoped `ai-rag-engine` to `@denizsvnc/ai-rag-engine`. Update imports and installation commands. Registry scope ownership remains unverified until the owner authenticates.
+- Node.js 20 is no longer in the supported matrix; use Node.js 22.14+.
+- `LocalFaqAdapter()` starts empty. Supply `filePath` or call `setFaqs()`; checkout demo FAQs are not business defaults.
+- Internal `dist/` files are private; public entry points remain the root API and the documented CLI commands.
+- `SMLEngine.cacheDir` / `RAG_MODEL_CACHE_DIR` applies per instance; the SDK no longer sets Transformers `env.cacheDir` globally.
+- Persistent ingestion/vector storage requires migrations and shared settings across API/worker.
+
+## 2.1.0 — Repository history (not verified as an npm release)
+
+- JWT authentication and RBAC, tenant boundaries and signed single-use tool confirmation.
+- Semantic routing, FAQ matching, hybrid retrieval, local queue and telemetry APIs.
+
+The public registry returned 404 for scoped and unscoped names during this preparation. This is not proof of namespace ownership or publish authorization.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,168 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<img src="https://raw.githubusercontent.com/Denizsvnc/ai-rag-engine/main/assets/logo.jpg" alt="AI-RAG-ENGINE Logo" width="160" style="border-radius: 28px; box-shadow: 0 12px 40px rgba(124, 108, 245, 0.45); margin-bottom: 16px;" />
+
+# ⚡ AI-RAG-ENGINE
+
+**TypeScript RAG library with pluggable LLM and vector adapters, local semantic routing, tenant-aware retrieval, and durable document ingestion.**
+
+[![Version](https://img.shields.io/badge/npm-@denizsvnc/ai--rag--engine-6C5CE7?logo=npm&logoColor=white)](https://www.npmjs.com/package/@denizsvnc/ai-rag-engine)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.8+-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-22+-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
+[![CI](https://github.com/Denizsvnc/ai-rag-engine/actions/workflows/ci.yml/badge.svg)](https://github.com/Denizsvnc/ai-rag-engine/actions)
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+---
+
+### 🌐 Documentation Languages
+
+**[English](README.md)** • **[Türkçe](README_tr.md)** • **[Deutsch](README_de.md)**
+
+---
+
+</div>
+
+## 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.
+
+```sh
+npm install @denizsvnc/ai-rag-engine
+```
+
+## 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.
+
+```js
+import { RAGEngine } from '@denizsvnc/ai-rag-engine';
+
+const engine = new RAGEngine({
+  smlConfig: { enabled: false },
+  cache: { enabled: false },
+  inputs: {
+    vectorStore: {
+      async search(_query, _topK, filter) {
+        if (filter?.tenantId !== 'demo') return [];
+        return [{ id: 'returns', content: 'Returns are accepted within 14 days.' }];
+      }
+    }
+  },
+  llmProvider: {
+    async generate({ systemPrompt }) {
+      return { content: systemPrompt.includes('14 days') ? 'Returns: 14 days.' : 'Unknown.' };
+    }
+  }
+});
+
+await engine.init();
+const result = await engine.query('What is the return window?', {
+  tenantId: 'demo', userId: 'demo-user', roles: ['viewer']
+});
+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
+
+| Capability | Implementation / boundary |
+| --- | --- |
+| LLM providers | OpenAI, Gemini, Ollama, private OpenAI-compatible endpoints, configurable fallback/tiering |
+| Semantic FAQ and tool routing | Local Transformers/ONNX embeddings; initial use downloads model files unless local-only |
+| In-memory vectors and queue | Development / single-process use; data does not survive restart |
+| Persistent vectors | PostgreSQL/pgvector, tenant-scoped CRUD, dense + PostgreSQL full-text RRF retrieval |
+| Durable ingestion | Separate BullMQ worker, PostgreSQL uploads/outbox, retries, idempotent replacement, revision-aware cache |
+| Security boundaries | Authenticated HTTP context, tool RBAC/schema checks, signed single-use approval, tenant-scoped data access |
+| Metrics | Token/latency accounting and Prometheus histogram export |
+
+Prompt filters and PII patterns are defenses with limitations, not guarantees of complete detection. PostgreSQL full-text retrieval is not BM25. The current PDF extractor is limited and does not perform OCR. The dependency tree includes native ONNX runtimes and is substantially larger than the SDK tarball; model weights are not bundled.
+
+## Documentation
+
+- [Configuration, real providers, vectors, FAQ, tools and troubleshooting](docs/USAGE.md)
+- [Versioning, manual publication and release checklist](docs/RELEASING.md)
+- [Changelog](CHANGELOG.md)
+- [Detailed release-readiness report](docs/NPM_RELEASE_READINESS.md)
+
+## Repository verification
+
+```sh
+npm ci
+npm run typecheck
+PG_TEST_URL=postgresql://postgres:test@localhost/rag_test \
+REDIS_TEST_URL=redis://localhost:6379 npm test
+npm run test:security
+npm run test:package
+npm run test:consumer
+npm audit --audit-level=high
+```
+
+Tests with external services require disposable PostgreSQL/pgvector and Redis. Missing service variables explicitly skip those tests locally; CI provisions both and requires them. `test:consumer` installs the packed SDK in a separate project and verifies an inert ESM import, deterministic RAG and strict TypeScript declarations. `test:consumer:integration` adds actual local embeddings/generation and multi-process recovery; it requires test services and model downloads.
+
+MIT licensed. [Issue tracker](https://github.com/Denizsvnc/ai-rag-engine/issues).

package/dist/adapters/cache/index.d.ts

@@ -0,0 +1 @@
+export * from './redis-cache.adapter.js';

package/dist/adapters/cache/redis-cache.adapter.d.ts

@@ -0,0 +1,49 @@
+import type { ICacheAdapter } from '../../interfaces/cache.interface.js';
+/** ioredis-compatible command interface; injected clients own their connection lifecycle. */
+export interface IRedisClientLike {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ...args: any[]): Promise<any>;
+    del(key: string): Promise<number>;
+    del(keys: string[]): Promise<number>;
+    keys?(pattern: string): Promise<string[]>;
+    scan?(cursor: string, ...args: any[]): Promise<[string, string[]]>;
+    quit?(): Promise<any>;
+    disconnect?(): void;
+    ping?(): Promise<string>;
+}
+export interface RedisCacheOptions {
+    url?: string | undefined;
+    client?: IRedisClientLike | undefined;
+    keyPrefix?: string | undefined;
+    defaultTtlMs?: number | undefined;
+    /** Without Redis, enables local LRU. With Redis, read/write failures degrade to misses/skipped writes, never local copies. */
+    enableFallbackMemory?: boolean | undefined;
+    fallbackMaxItems?: number | undefined;
+}
+/** Shared Redis is authoritative. Local LRU is used only when no Redis was configured. */
+export declare class RedisCacheAdapter implements ICacheAdapter {
+    private options;
+    private client;
+    private readonly keyPrefix;
+    private readonly defaultTtlMs;
+    private readonly enableFallback;
+    private readonly remoteConfigured;
+    private readonly fallbackCache;
+    private isConnected;
+    constructor(options?: RedisCacheOptions);
+    init(): Promise<void>;
+    get(key: string): Promise<any | null>;
+    set(key: string, value: any, ttlMs?: number): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    /** Strings match keywords (case-insensitive), or anchored * / ? wildcard patterns. Regexes match namespaced keys. */
+    invalidate(patternOrKey: string | RegExp): Promise<number>;
+    clear(): Promise<void>;
+    getIsConnected(): boolean;
+    /** Number of local-only LRU entries; not a Redis key count. */
+    size(): number;
+    private removeMatching;
+    private keyBatches;
+    private matcher;
+    private requireClient;
+    private prefixKey;
+}

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

@@ -0,0 +1,29 @@
+import type { IFAQAdapter, FAQItem, FAQMatchResult } from '../../interfaces/faq.interface.js';
+import { SMLEngine } from '../../core/sml-engine.js';
+export interface LocalFaqAdapterOptions {
+    filePath?: string | undefined;
+    smlEngine?: SMLEngine | undefined;
+    defaultMatchThreshold?: number | undefined;
+}
+/**
+ * Loads pre-computed or dynamically embedded FAQs from a local JSON file.
+ * Matches questions using local cosine similarity without an LLM generation call.
+ */
+export declare class LocalFaqAdapter implements IFAQAdapter {
+    private filePath;
+    private smlEngine;
+    private defaultThreshold;
+    private items;
+    private isLoaded;
+    constructor(options?: LocalFaqAdapterOptions);
+    /**
+     * Initializes the adapter by reading the JSON file and caching embeddings in RAM.
+     */
+    init(): Promise<void>;
+    setFaqs(items: FAQItem[]): Promise<void>;
+    getFaqs(tenantId?: string): Promise<FAQItem[]>;
+    /**
+     * Finds the best semantically matching FAQ item for a given user query within the caller's tenant boundary.
+     */
+    findBestMatch(query: string, threshold?: number, tenantId?: string): Promise<FAQMatchResult | null>;
+}

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

@@ -0,0 +1,14 @@
+import type { IFAQAdapter } from '../../interfaces/faq.interface.js';
+export declare class UrlFaqAdapter implements IFAQAdapter {
+    private endpoint;
+    private headers?;
+    /**
+     * @param endpoint Remote URL returning FAQ JSON data
+     * @param headers Optional request headers (e.g. authorization tokens)
+     */
+    constructor(endpoint: string, headers?: Record<string, string>);
+    getFaqs(): Promise<Array<{
+        question: string;
+        answer: string;
+    }>>;
+}

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

@@ -0,0 +1,42 @@
+import type { ILLMProvider, ILLMRequest, ILLMResponse } from '../../interfaces/llm.interface.js';
+export interface CustomLLMConfig {
+    /**
+     * Full URL to the OpenAI-compatible chat completions endpoint.
+     * e.g., 'http://localhost:8000/v1/chat/completions' (vLLM)
+     * e.g., 'http://internal-llm.company.local:8080/v1/chat/completions'
+     */
+    endpoint?: string;
+    /**
+     * Model identifier expected by the inference server.
+     * e.g., 'llama-3.1-8b-instruct', 'mistral-large', 'qwen-2.5-72b'
+     */
+    model?: string;
+    /**
+     * Optional API key or bearer token. Left empty if running within a secured private VPC.
+     */
+    apiKey?: string | undefined;
+    /**
+     * Additional HTTP headers (e.g. corporate proxy headers, tenant IDs, authorization).
+     */
+    customHeaders?: Record<string, string> | undefined;
+    /**
+     * Sampling temperature (defaults to 0.1 for deterministic RAG answers).
+     */
+    temperature?: number | undefined;
+}
+/**
+ * Adapter for private, self-hosted, or internal enterprise LLM APIs.
+ * Works seamlessly with vLLM, LocalAI, HuggingFace TGI, LM Studio, Azure OpenAI,
+ * and any internal API gateway adhering to the OpenAI-compatible /v1/chat/completions spec.
+ */
+export declare class CustomLLMAdapter implements ILLMProvider {
+    protected endpoint: string;
+    protected model: string;
+    protected apiKey?: string | undefined;
+    protected customHeaders: Record<string, string>;
+    protected temperature: number;
+    constructor(config?: CustomLLMConfig);
+    static createFast(config?: Partial<CustomLLMConfig>): CustomLLMAdapter;
+    static createSmart(config?: Partial<CustomLLMConfig>): CustomLLMAdapter;
+    generate(request: ILLMRequest): Promise<ILLMResponse>;
+}

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

@@ -0,0 +1,10 @@
+import type { ILLMProvider, ILLMRequest, ILLMResponse } from '../../interfaces/llm.interface.js';
+export interface FallbackProviderOptions {
+    logFailover?: boolean;
+}
+export declare class FallbackLLMProvider implements ILLMProvider {
+    private providers;
+    private logFailover;
+    constructor(providers: ILLMProvider[], options?: FallbackProviderOptions);
+    generate(request: ILLMRequest): Promise<ILLMResponse>;
+}

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

@@ -0,0 +1,9 @@
+import type { ILLMProvider, ILLMRequest, ILLMResponse } from '../../interfaces/llm.interface.js';
+export declare class GeminiAdapter implements ILLMProvider {
+    private apiKey;
+    private model;
+    constructor(apiKey?: string, model?: string);
+    static createFast(apiKey?: string): GeminiAdapter;
+    static createSmart(apiKey?: string): GeminiAdapter;
+    generate(request: ILLMRequest): Promise<ILLMResponse>;
+}

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

@@ -0,0 +1,30 @@
+import { CustomLLMAdapter } from './custom.adapter.js';
+export interface OllamaConfig {
+    /**
+     * Base host for the Ollama instance (e.g. 'http://localhost:11434' or 'http://192.168.1.50:11434').
+     * Defaults to process.env.OLLAMA_HOST || 'http://localhost:11434'.
+     */
+    host?: string | undefined;
+    /**
+     * Model tag pulled in Ollama (e.g., 'llama3.2', 'deepseek-r1:8b', 'mistral', 'qwen2.5:7b').
+     * Defaults to process.env.OLLAMA_MODEL || 'llama3.2'.
+     */
+    model?: string | undefined;
+    /**
+     * Sampling temperature (defaults to 0.1).
+     */
+    temperature?: number | undefined;
+    /**
+     * Optional custom headers (e.g. if Ollama is behind an Nginx reverse proxy).
+     */
+    customHeaders?: Record<string, string> | undefined;
+}
+/**
+ * Dedicated adapter for self-hosted Ollama instances.
+ * Automatically targets Ollama's OpenAI-compatible /v1/chat/completions endpoint.
+ */
+export declare class OllamaAdapter extends CustomLLMAdapter {
+    constructor(config?: OllamaConfig);
+    static createFast(config?: Partial<OllamaConfig>): OllamaAdapter;
+    static createSmart(config?: Partial<OllamaConfig>): OllamaAdapter;
+}

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

@@ -0,0 +1,10 @@
+import type { ILLMProvider, ILLMRequest, ILLMResponse } from '../../interfaces/llm.interface.js';
+export declare class OpenAIAdapter implements ILLMProvider {
+    protected apiKey: string;
+    protected model: string;
+    protected endpoint: string;
+    constructor(apiKey?: string, 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

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

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

@@ -0,0 +1,22 @@
+import type { ILLMProvider, ILLMRequest, ILLMResponse } from '../../interfaces/llm.interface.js';
+export interface TieredLLMConfig {
+    fastProvider: ILLMProvider;
+    smartProvider: ILLMProvider;
+    classifier?: ((request: ILLMRequest) => 'fast' | 'smart') | undefined;
+}
+export declare class TieredLLMProvider implements ILLMProvider {
+    private fastProvider;
+    private smartProvider;
+    private customClassifier?;
+    constructor(config: TieredLLMConfig);
+    /**
+     * Determines whether the request requires high reasoning (smart) or standard execution (fast).
+     */
+    classifyComplexity(request: ILLMRequest): 'fast' | 'smart';
+    generate(request: ILLMRequest): Promise<ILLMResponse>;
+    /**
+     * Automatically constructs a TieredLLMProvider based on available configuration in environment variables.
+     * Enforces enterprise data privacy compliance by respecting ALLOW_PUBLIC_OPENSOURCE_LLM.
+     */
+    static createFromEnv(): TieredLLMProvider;
+}

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

@@ -0,0 +1,6 @@
+import type { IRulesAdapter } from '../../interfaces/rules.interface.js';
+export declare class StaticRulesAdapter implements IRulesAdapter {
+    private rules;
+    constructor(rules: string[]);
+    getActiveRules(tenantId?: string): Promise<string[]>;
+}

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

@@ -0,0 +1,33 @@
+import type { IVectorStoreAdapter, VectorDocument } from '../../interfaces/vector.interface.js';
+import { SMLEngine } from '../../core/sml-engine.js';
+import { type HybridScoredDocument } from '../../core/vector/hybrid-search.js';
+export declare class MemoryVectorAdapter implements IVectorStoreAdapter {
+    private smlEngine;
+    private documents;
+    private bm25Index;
+    constructor(smlEngine?: SMLEngine);
+    /**
+     * Adds documents to memory, computes their embeddings, and indexes them in BM25.
+     */
+    addDocuments(docs: Omit<VectorDocument, 'score'>[]): Promise<void>;
+    insert(doc: Omit<VectorDocument, 'score'>): Promise<void>;
+    /**
+     * Searches for the top-k most similar documents against the query vector,
+     * with optional metadata filtering (e.g. tenantId).
+     */
+    search(query: string, topK?: number, filter?: Record<string, any>): Promise<VectorDocument[]>;
+    /**
+     * Hybrid Search combining Dense ONNX Vector search with Sparse BM25 lexical search
+     * via Reciprocal Rank Fusion (RRF).
+     */
+    searchHybrid(query: string, topK?: number, filter?: Record<string, any>): Promise<HybridScoredDocument[]>;
+    /**
+     * Deletes a document by ID from both Dense memory and BM25 index.
+     */
+    deleteDocument(id: string, filter?: Record<string, any>): Promise<boolean>;
+    /**
+     * Clears all stored documents.
+     */
+    clear(filter?: Record<string, any>): Promise<void>;
+    private matchesFilter;
+}

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

@@ -0,0 +1,51 @@
+import { Pool } from 'pg';
+import type { IVectorStoreAdapter, VectorDocument } from '../../interfaces/vector.interface.js';
+export interface EmbeddingProvider {
+    getEmbedding(text: string): Promise<ArrayLike<number>>;
+}
+export interface PostgresVectorOptions {
+    connectionString?: string | undefined;
+    pool?: Pool | undefined;
+    tableName?: string | undefined;
+    modelName?: string | undefined;
+    dimensions?: number | undefined;
+    embeddingProvider?: EmbeddingProvider | undefined;
+    /** Disable after migrations have been applied by a database owner. */
+    autoMigrate?: boolean | undefined;
+    /** Optional approximate index. Exact search is the default. */
+    createHnswIndex?: boolean | undefined;
+}
+/** Persistent, tenant-scoped pgvector store. Every read/delete requires a tenant filter. */
+export declare class PostgresVectorAdapter implements IVectorStoreAdapter {
+    private readonly options;
+    private readonly pool;
+    private readonly table;
+    private readonly configTable;
+    private readonly manifests;
+    private readonly epochs;
+    private readonly modelName;
+    private readonly dimensions;
+    private readonly embeddings;
+    private initPromise;
+    constructor(options: PostgresVectorOptions);
+    init(): Promise<void>;
+    private initialize;
+    /** Upserts are atomic per batch and IDs are unique within a tenant. */
+    addDocuments(documents: Omit<VectorDocument, 'score'>[]): Promise<void>;
+    /** Atomically replaces all chunks; retries and older document revisions cannot overwrite newer work. */
+    replaceDocument(documentId: string, tenantId: string, version: number, documents: Omit<VectorDocument, 'score'>[]): Promise<'applied' | 'unchanged' | 'superseded'>;
+    getRevision(tenantId: string): Promise<string>;
+    private prepare;
+    private write;
+    private bumpRevision;
+    search(query: string, topK?: number, filter?: Record<string, any>): Promise<VectorDocument[]>;
+    /** PostgreSQL lexical search + dense search, fused with RRF. This is not BM25. */
+    searchHybrid(query: string, topK?: number, filter?: Record<string, any>): Promise<VectorDocument[]>;
+    deleteDocument(id: string, filter?: Record<string, any>): Promise<boolean>;
+    clear(filter?: Record<string, any>): Promise<void>;
+    close(): Promise<void>;
+    private tenant;
+    private vector;
+    private validateTopK;
+    private transaction;
+}

package/dist/api/auth.d.ts

@@ -0,0 +1,47 @@
+import type { RequestHandler } from 'express';
+export interface AuthTokenPayload {
+    userId: string;
+    tenantId: string;
+    roles: string[];
+    metadata?: Record<string, any> | undefined;
+    iss?: string | undefined;
+    aud?: string | undefined;
+    nbf?: number | undefined;
+    iat?: number | undefined;
+    exp?: number | undefined;
+}
+export interface AuthMiddlewareOptions {
+    jwtSecret?: string | undefined;
+    issuer?: string | undefined;
+    audience?: string | undefined;
+    apiKeys?: Record<string, AuthTokenPayload> | undefined;
+    allowDevAnonymous?: boolean | undefined;
+}
+declare global {
+    namespace Express {
+        interface Request {
+            auth?: AuthTokenPayload | undefined;
+        }
+    }
+}
+/**
+ * Creates a cryptographically signed HMAC-SHA256 JWT token using native Node.js crypto.
+ * Zero external dependencies.
+ */
+export declare function createAuthToken(payload: Omit<AuthTokenPayload, 'iat'>, secret?: string, expiresInSeconds?: number): string;
+/**
+ * Verifies and decodes an HMAC-SHA256 JWT token using native Node.js crypto.
+ */
+export declare function verifyAuthToken(token: string, secret?: string, options?: {
+    issuer?: string | undefined;
+    audience?: string | undefined;
+}): AuthTokenPayload;
+/**
+ * Express middleware that enforces trusted server-side authentication.
+ * Prevents client-controlled role spoofing (P0 security barrier).
+ */
+export declare function createAuthMiddleware(options: AuthMiddlewareOptions): RequestHandler;
+/**
+ * Route-level RBAC Guard: Ensures the authenticated user possesses at least one of the required roles.
+ */
+export declare function requireRoles(requiredRoles: string[]): RequestHandler;

package/dist/api/middleware.d.ts

@@ -0,0 +1,3 @@
+import type { Request, Response, NextFunction } from 'express';
+import { RAGEngine } from '../core/engine.js';
+export declare function createRagMiddleware(engine: RAGEngine): (req: Request, res: Response, next: NextFunction) => Promise<Response<any, Record<string, any>> | undefined>;

package/dist/api/rate-limit.d.ts

@@ -0,0 +1,8 @@
+import type { Redis } from 'ioredis';
+import type { RequestHandler } from 'express';
+/** Atomic fixed-window tenant limit shared by all API instances. */
+export declare function createTenantRateLimiter(redis: Pick<Redis, 'eval'>, options: {
+    limit: number;
+    windowMs: number;
+    prefix?: string;
+}): RequestHandler;

package/dist/api/routes.d.ts

@@ -0,0 +1,9 @@
+import { Router, type RequestHandler } from 'express';
+import { RAGEngine } from '../core/engine.js';
+import { type AuthMiddlewareOptions } from './auth.js';
+export interface ApiRouteOptions {
+    rateLimiter?: RequestHandler | undefined;
+    auth?: AuthMiddlewareOptions | undefined;
+    enforceAuth?: boolean | undefined;
+}
+export declare function createApiRoutes(engine: RAGEngine, options?: ApiRouteOptions): Router;

package/dist/api/server.d.ts

@@ -0,0 +1 @@
+import 'dotenv/config';