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

package/dist/interfaces/cache.interface.d.ts

@@ -0,0 +1,8 @@
+export interface ICacheAdapter {
+    get(key: string): Promise<any | null>;
+    set(key: string, value: any, ttlMs?: number): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    invalidate(patternOrKey: string | RegExp): Promise<number>;
+    clear(): Promise<void>;
+    size?(): number;
+}

package/dist/interfaces/engine-config.interface.d.ts

@@ -0,0 +1,73 @@
+import type { IIngestionBackend } from './ingestion.interface.js';
+import type { IJobQueue } from '../core/queue/job-queue.interface.js';
+import type { ConfirmationNonceStore } from '../core/security/nonce-store.js';
+import type { IVectorStoreAdapter } from './vector.interface.js';
+import type { IRulesAdapter } from './rules.interface.js';
+import type { IFAQAdapter } from './faq.interface.js';
+import type { ICacheAdapter } from './cache.interface.js';
+import type { IAgentTool } from './tool.interface.js';
+import type { ILLMProvider } from './llm.interface.js';
+import type { SecurityConfig } from '../core/security/security.types.js';
+import type { ResponseMetrics, TokenTrackerOptions } from '../core/metrics/token-tracker.js';
+export interface EngineConfig {
+    llmProvider: ILLMProvider;
+    confirmation?: {
+        secret?: string | undefined;
+        nonceStore?: ConfirmationNonceStore | undefined;
+    } | undefined;
+    security?: SecurityConfig | undefined;
+    smlConfig?: {
+        enabled: boolean;
+        modelName?: string | undefined;
+        matchThreshold?: number | undefined;
+    } | undefined;
+    inputs: {
+        vectorStore?: IVectorStoreAdapter | undefined;
+        rules?: IRulesAdapter | undefined;
+        faq?: IFAQAdapter | undefined;
+    };
+    tools?: {
+        registryFilePath: string;
+        items: IAgentTool[];
+    } | undefined;
+    cache?: {
+        enabled: boolean;
+        adapter?: ICacheAdapter | undefined;
+        filePath?: string | undefined;
+        minHitsToPersist?: number | undefined;
+        ttlMs?: number | undefined;
+        toolResultTtlMs?: number | undefined;
+        cacheToolResults?: boolean | undefined;
+    } | undefined;
+    retrieval?: {
+        strategy?: 'dense' | 'sparse' | 'hybrid' | undefined;
+        topK?: number | undefined;
+        minRelevanceScore?: number | undefined;
+    } | undefined;
+    metrics?: TokenTrackerOptions | undefined;
+    ingestion?: {
+        backend?: IIngestionBackend | undefined;
+        chunkSize?: number | undefined;
+        chunkOverlap?: number | undefined;
+        jobQueue?: IJobQueue | undefined;
+    } | undefined;
+}
+export interface RAGResponse {
+    answer: string;
+    intent: string;
+    resolvedBy: string;
+    sources?: string[] | undefined;
+    appliedRules?: string[] | undefined;
+    executedTools?: Array<{
+        name: string;
+        args: any;
+    }> | undefined;
+    confirmationRequests?: Array<{
+        toolName: string;
+        proposedArgs: unknown;
+        confirmationTicket: string;
+    }> | undefined;
+    securityWarning?: string | undefined;
+    latencyMs: number;
+    metrics?: ResponseMetrics | undefined;
+}

package/dist/interfaces/faq.interface.d.ts

@@ -0,0 +1,17 @@
+export interface FAQItem {
+    id?: string | undefined;
+    tenantId?: string | undefined;
+    question: string;
+    answer: string;
+    category?: string | undefined;
+    embedding?: number[] | undefined;
+}
+export interface FAQMatchResult {
+    question: string;
+    answer: string;
+    score: number;
+}
+export interface IFAQAdapter {
+    getFaqs(tenantId?: string): Promise<FAQItem[]>;
+    findBestMatch?(query: string, threshold?: number, tenantId?: string): Promise<FAQMatchResult | null>;
+}

package/dist/interfaces/ingestion.interface.d.ts

@@ -0,0 +1,14 @@
+import type { DocumentUploadPayload } from '../services/document-ingestion.service.js';
+import type { Job, JobStatus } from '../core/queue/job-queue.interface.js';
+export interface IIngestionBackend {
+    submitDocument(payload: DocumentUploadPayload): Promise<{
+        jobId: string;
+        status: JobStatus;
+    }>;
+    getJobStatus(jobId: string, tenantId?: string): Promise<Job | null>;
+    retryJob?(jobId: string, tenantId: string): Promise<void>;
+}
+export interface IngestionSettings {
+    chunkSize: number;
+    chunkOverlap: number;
+}

package/dist/interfaces/llm.interface.d.ts

@@ -0,0 +1,22 @@
+import type { IAgentTool } from './tool.interface.js';
+export interface ILLMRequest {
+    systemPrompt: string;
+    userPrompt: string;
+    tools?: IAgentTool[];
+    complexity?: 'fast' | 'smart';
+}
+export interface ILLMResponse {
+    content: string;
+    toolCalls?: Array<{
+        name: string;
+        arguments: Record<string, any>;
+    }>;
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens?: number;
+    };
+}
+export interface ILLMProvider {
+    generate(request: ILLMRequest): Promise<ILLMResponse>;
+}

package/dist/interfaces/query-context.interface.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Multi-tenant and user execution context for queries and tool actions.
+ */
+export interface QueryContext {
+    /**
+     * Unique identifier of the tenant / organization (for multi-tenant isolation).
+     */
+    tenantId?: string | undefined;
+    /**
+     * Unique identifier of the requesting user.
+     */
+    userId?: string | undefined;
+    /**
+     * RBAC roles assigned to the requesting user (e.g. ['admin', 'manager', 'read_only']).
+     */
+    roles?: string[] | undefined;
+    /**
+     * Arbitrary contextual metadata passed through the pipeline.
+     */
+    metadata?: Record<string, any> | undefined;
+    /**
+     * Set to true to bypass cache lookup.
+     */
+    skipCache?: boolean | undefined;
+    /**
+     * @deprecated Ignored. Mutations require a signed confirmationTicket.
+     */
+    confirmedAction?: boolean | undefined;
+    /**
+     * Cryptographically signed HMAC-SHA256 confirmation ticket for destructive/mutating operations (P0 security).
+     */
+    confirmationTicket?: string | undefined;
+}

package/dist/interfaces/rules.interface.d.ts

@@ -0,0 +1,3 @@
+export interface IRulesAdapter {
+    getActiveRules(tenantId?: string): Promise<string[]>;
+}

package/dist/interfaces/tool.interface.d.ts

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+import type { QueryContext } from './query-context.interface.js';
+export interface ToolParameterSchema {
+    type: 'object';
+    properties: Record<string, {
+        type: 'string' | 'number' | 'boolean' | 'array';
+        description: string;
+        enum?: string[];
+    }>;
+    required?: string[];
+}
+export interface IAgentTool<TArgs = any, TResult = any> {
+    name: string;
+    description: string;
+    parameters?: ToolParameterSchema | undefined;
+    cacheResultTTL?: number | undefined;
+    /**
+     * Optional Zod schema for strict runtime validation of arguments before execution.
+     */
+    zodSchema?: z.ZodSchema<TArgs> | undefined;
+    /**
+     * Flag declaring if this tool mutates system state (e.g. updating stock, making payments).
+     * If true, requires explicit confirmation or appropriate permissions.
+     */
+    isMutating?: boolean | undefined;
+    /**
+     * Role-Based Access Control: List of roles allowed to invoke this tool.
+     * If defined, caller context.roles must include at least one matching role.
+     */
+    requiredRoles?: string[] | undefined;
+    /**
+     * If true, execution requires a valid single-use context.confirmationTicket.
+     */
+    requiresConfirmation?: boolean | undefined;
+    /**
+     * The business logic function to execute.
+     */
+    execute: (args: TArgs, context?: QueryContext) => Promise<TResult>;
+}
+export interface ToolAuditLog {
+    timestamp: string;
+    toolName: string;
+    tenantId?: string | undefined;
+    userId?: string | undefined;
+    args: any;
+    isMutating: boolean;
+    status: 'SUCCESS' | 'VALIDATION_FAILED' | 'UNAUTHORIZED' | 'CONFIRMATION_REQUIRED' | 'EXECUTION_FAILED';
+    error?: string | undefined;
+    durationMs: number;
+}

package/dist/interfaces/vector.interface.d.ts

@@ -0,0 +1,15 @@
+export interface VectorDocument {
+    id: string;
+    content: string;
+    metadata?: Record<string, any> | undefined;
+    version?: number | undefined;
+    score?: number | undefined;
+}
+export interface IVectorStoreAdapter {
+    getRevision?(tenantId: string): Promise<string>;
+    search(query: string, topK?: number, filter?: Record<string, any>): Promise<VectorDocument[]>;
+    searchHybrid?(query: string, topK?: number, filter?: Record<string, any>): Promise<VectorDocument[]>;
+    addDocuments?(docs: Omit<VectorDocument, 'score'>[]): Promise<void>;
+    deleteDocument?(id: string, filter?: Record<string, any>): Promise<boolean>;
+    clear?(filter?: Record<string, any>): Promise<void>;
+}

package/dist/scripts/migrate-vector.d.ts

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