@retrivora-ai/rag-engine 1.0.3 → 1.0.5

package/dist/index-CSfaCeux.d.ts

@@ -0,0 +1,206 @@
+import { g as RagConfig, C as ChatMessage, b as ChatResponse, e as IngestDocument } from './RagConfig-BEmz4hVP.js';
+import { NextRequest, NextResponse } from 'next/server';
+
+interface ValidationError {
+    field: string;
+    message: string;
+    suggestion?: string;
+    severity: 'error' | 'warning';
+}
+/**
+ * ConfigValidator.ts — Comprehensive configuration validation.
+ * Uses a pluggable architecture to delegate provider-specific checks.
+ */
+declare class ConfigValidator {
+    /**
+     * Validates the entire RagConfig object.
+     */
+    static validate(config: RagConfig): Promise<ValidationError[]>;
+    private static validateVectorDbConfig;
+    private static validateLLMConfig;
+    private static validateEmbeddingConfig;
+    /**
+     * Temporary fallbacks for providers not yet migrated to the pluggable architecture.
+     */
+    private static fallbackVectorValidation;
+    private static fallbackLLMValidation;
+    private static fallbackEmbeddingValidation;
+    private static validateUIConfig;
+    private static validateRAGConfig;
+    private static isValidCSSColor;
+    static validateAndThrow(config: RagConfig): Promise<void>;
+}
+
+/**
+ * Interface for provider-specific configuration validation logic.
+ */
+interface IProviderValidator {
+    /**
+     * Validates the configuration for a specific provider.
+     * @param config - The configuration object to validate.
+     * @returns An array of validation errors (empty if valid).
+     */
+    validate(config: Record<string, unknown>): ValidationError[];
+}
+/**
+ * Result of a provider health check.
+ */
+interface HealthCheckResult {
+    healthy: boolean;
+    provider: string;
+    version?: string;
+    capabilities?: Record<string, unknown>;
+    error?: string;
+    timestamp: number;
+}
+/**
+ * Interface for provider-specific health checking logic.
+ */
+interface IProviderHealthChecker {
+    /**
+     * Performs a health check for a specific provider.
+     * @param config - The configuration object used to connect to the provider.
+     * @returns A promise that resolves to the health check result.
+     */
+    check(config: Record<string, unknown>): Promise<HealthCheckResult>;
+}
+
+/**
+ * VectorPlugin — main orchestrator class.
+ * This is the primary interface for host applications.
+ *
+ * Features:
+ * - Configuration resolution from host + environment
+ * - Configuration validation with detailed error messages
+ * - Provider health checks before initialization
+ * - Multi-provider support (Vector DBs & LLMs)
+ * - Per-tenant data isolation via namespacing
+ */
+declare class VectorPlugin {
+    private config;
+    private pipeline;
+    private validationPromise;
+    constructor(hostConfig?: Partial<RagConfig>);
+    /**
+     * Get the current resolved configuration.
+     */
+    getConfig(): RagConfig;
+    /**
+     * Perform pre-flight health checks on all configured providers.
+     * Useful to verify connectivity before running operations.
+     *
+     * @returns Health status for vector DB, LLM, and embedding providers
+     */
+    checkHealth(): Promise<{
+        vectorDb: HealthCheckResult;
+        llm: HealthCheckResult;
+        embedding?: HealthCheckResult;
+        allHealthy: boolean;
+    }>;
+    /**
+     * Run a chat query.
+     */
+    chat(message: string, history?: ChatMessage[], namespace?: string): Promise<ChatResponse>;
+    /**
+     * Run a streaming chat query.
+     */
+    chatStream(message: string, history?: ChatMessage[], namespace?: string): AsyncGenerator<string | ChatResponse, void, any>;
+    /**
+     * Ingest documents into the vector database.
+     */
+    ingest(documents: IngestDocument[], namespace?: string): Promise<Array<{
+        docId: string | number;
+        chunksIngested: number;
+    }>>;
+}
+
+/**
+ * Encode a payload as a Server-Sent Events frame.
+ *   data: <json>\n\n
+ */
+declare function sseFrame(payload: unknown): string;
+/** Encode a plain text chunk as an SSE frame. */
+declare function sseTextFrame(text: string): string;
+/** Encode the retrieval metadata as an SSE frame. */
+declare function sseMetaFrame(meta: unknown): string;
+/** Encode a stream error as an SSE frame. */
+declare function sseErrorFrame(message: string): string;
+/**
+ * createChatHandler — factory that returns a Next.js App Router POST handler.
+ *
+ * Accepts either a full/partial `RagConfig` **or** a pre-built `VectorPlugin`
+ * instance (preferred for singleton/multi-tenant setups).
+ *
+ * @example
+ * // Option A — pass config (plugin created once at module load time)
+ * export const POST = createChatHandler(getRagConfig());
+ *
+ * // Option B — pass a pre-built plugin (most flexible)
+ * const plugin = new VectorPlugin(getRagConfig());
+ * export const POST = createChatHandler(plugin);
+ */
+declare function createChatHandler(configOrPlugin?: Partial<RagConfig> | VectorPlugin): (req: NextRequest) => Promise<NextResponse<{
+    error: string;
+}> | NextResponse<ChatResponse>>;
+/**
+ * createStreamHandler — factory for a streaming SSE Next.js App Router POST handler.
+ *
+ * Streams the assistant response as Server-Sent Events (SSE). Each frame is a
+ * JSON object with a `type` discriminant:
+ *   - `{ type: "text",     text: "..." }`       — incremental text chunk
+ *   - `{ type: "metadata", sources: [...] }`    — retrieval metadata (last frame)
+ *   - `{ type: "error",    error: "..." }`       — stream-level error
+ *
+ * @example
+ * // src/app/api/chat/route.ts
+ * export const POST = createStreamHandler(getRagConfig());
+ *
+ * // Client-side parsing in useRagChat.ts:
+ * // const lines = chunk.split('\n');
+ * // for (const line of lines) {
+ * //   if (line.startsWith('data: ')) {
+ * //     const frame = JSON.parse(line.slice(6));
+ * //     if (frame.type === 'text') { ... }
+ * //   }
+ * // }
+ */
+declare function createStreamHandler(configOrPlugin?: Partial<RagConfig> | VectorPlugin): (req: NextRequest) => Promise<Response>;
+/**
+ * createIngestHandler — factory for the document ingestion endpoint.
+ */
+declare function createIngestHandler(configOrPlugin?: Partial<RagConfig> | VectorPlugin): (req: NextRequest) => Promise<NextResponse<{
+    error: string;
+}> | NextResponse<{
+    results: {
+        docId: string | number;
+        chunksIngested: number;
+    }[];
+}>>;
+/**
+ * createHealthHandler — factory for the health-check endpoint.
+ */
+declare function createHealthHandler(configOrPlugin?: Partial<RagConfig> | VectorPlugin): () => Promise<NextResponse<{
+    timestamp: string;
+    vectorDb: HealthCheckResult;
+    llm: HealthCheckResult;
+    embedding?: HealthCheckResult;
+    allHealthy: boolean;
+    status: string;
+}> | NextResponse<{
+    status: string;
+    error: string;
+}>>;
+/**
+ * createUploadHandler — factory for the file upload ingestion endpoint.
+ */
+declare function createUploadHandler(configOrPlugin?: Partial<RagConfig> | VectorPlugin): (req: NextRequest) => Promise<NextResponse<{
+    error: string;
+}> | NextResponse<{
+    message: string;
+    results: {
+        docId: string | number;
+        chunksIngested: number;
+    }[];
+}>>;
+
+export { ConfigValidator as C, type HealthCheckResult as H, type IProviderValidator as I, type ValidationError as V, type IProviderHealthChecker as a, VectorPlugin as b, createChatHandler as c, createHealthHandler as d, createIngestHandler as e, createStreamHandler as f, createUploadHandler as g, sseFrame as h, sseMetaFrame as i, sseTextFrame as j, sseErrorFrame as s };

package/dist/index-DFSy0CG6.d.mts

@@ -0,0 +1,206 @@
+import { g as RagConfig, C as ChatMessage, b as ChatResponse, e as IngestDocument } from './RagConfig-BEmz4hVP.mjs';
+import { NextRequest, NextResponse } from 'next/server';
+
+interface ValidationError {
+    field: string;
+    message: string;
+    suggestion?: string;
+    severity: 'error' | 'warning';
+}
+/**
+ * ConfigValidator.ts — Comprehensive configuration validation.
+ * Uses a pluggable architecture to delegate provider-specific checks.
+ */
+declare class ConfigValidator {
+    /**
+     * Validates the entire RagConfig object.
+     */
+    static validate(config: RagConfig): Promise<ValidationError[]>;
+    private static validateVectorDbConfig;
+    private static validateLLMConfig;
+    private static validateEmbeddingConfig;
+    /**
+     * Temporary fallbacks for providers not yet migrated to the pluggable architecture.
+     */
+    private static fallbackVectorValidation;
+    private static fallbackLLMValidation;
+    private static fallbackEmbeddingValidation;
+    private static validateUIConfig;
+    private static validateRAGConfig;
+    private static isValidCSSColor;
+    static validateAndThrow(config: RagConfig): Promise<void>;
+}
+
+/**
+ * Interface for provider-specific configuration validation logic.
+ */
+interface IProviderValidator {
+    /**
+     * Validates the configuration for a specific provider.
+     * @param config - The configuration object to validate.
+     * @returns An array of validation errors (empty if valid).
+     */
+    validate(config: Record<string, unknown>): ValidationError[];
+}
+/**
+ * Result of a provider health check.
+ */
+interface HealthCheckResult {
+    healthy: boolean;
+    provider: string;
+    version?: string;
+    capabilities?: Record<string, unknown>;
+    error?: string;
+    timestamp: number;
+}
+/**
+ * Interface for provider-specific health checking logic.
+ */
+interface IProviderHealthChecker {
+    /**
+     * Performs a health check for a specific provider.
+     * @param config - The configuration object used to connect to the provider.
+     * @returns A promise that resolves to the health check result.
+     */
+    check(config: Record<string, unknown>): Promise<HealthCheckResult>;
+}
+
+/**
+ * VectorPlugin — main orchestrator class.
+ * This is the primary interface for host applications.
+ *
+ * Features:
+ * - Configuration resolution from host + environment
+ * - Configuration validation with detailed error messages
+ * - Provider health checks before initialization
+ * - Multi-provider support (Vector DBs & LLMs)
+ * - Per-tenant data isolation via namespacing
+ */
+declare class VectorPlugin {
+    private config;
+    private pipeline;
+    private validationPromise;
+    constructor(hostConfig?: Partial<RagConfig>);
+    /**
+     * Get the current resolved configuration.
+     */
+    getConfig(): RagConfig;
+    /**
+     * Perform pre-flight health checks on all configured providers.
+     * Useful to verify connectivity before running operations.
+     *
+     * @returns Health status for vector DB, LLM, and embedding providers
+     */
+    checkHealth(): Promise<{
+        vectorDb: HealthCheckResult;
+        llm: HealthCheckResult;
+        embedding?: HealthCheckResult;
+        allHealthy: boolean;
+    }>;
+    /**
+     * Run a chat query.
+     */
+    chat(message: string, history?: ChatMessage[], namespace?: string): Promise<ChatResponse>;
+    /**
+     * Run a streaming chat query.
+     */
+    chatStream(message: string, history?: ChatMessage[], namespace?: string): AsyncGenerator<string | ChatResponse, void, any>;
+    /**
+     * Ingest documents into the vector database.
+     */
+    ingest(documents: IngestDocument[], namespace?: string): Promise<Array<{
+        docId: string | number;
+        chunksIngested: number;
+    }>>;
+}
+
+/**
+ * Encode a payload as a Server-Sent Events frame.
+ *   data: <json>\n\n
+ */
+declare function sseFrame(payload: unknown): string;
+/** Encode a plain text chunk as an SSE frame. */
+declare function sseTextFrame(text: string): string;
+/** Encode the retrieval metadata as an SSE frame. */
+declare function sseMetaFrame(meta: unknown): string;
+/** Encode a stream error as an SSE frame. */
+declare function sseErrorFrame(message: string): string;
+/**
+ * createChatHandler — factory that returns a Next.js App Router POST handler.
+ *
+ * Accepts either a full/partial `RagConfig` **or** a pre-built `VectorPlugin`
+ * instance (preferred for singleton/multi-tenant setups).
+ *
+ * @example
+ * // Option A — pass config (plugin created once at module load time)
+ * export const POST = createChatHandler(getRagConfig());
+ *
+ * // Option B — pass a pre-built plugin (most flexible)
+ * const plugin = new VectorPlugin(getRagConfig());
+ * export const POST = createChatHandler(plugin);
+ */
+declare function createChatHandler(configOrPlugin?: Partial<RagConfig> | VectorPlugin): (req: NextRequest) => Promise<NextResponse<{
+    error: string;
+}> | NextResponse<ChatResponse>>;
+/**
+ * createStreamHandler — factory for a streaming SSE Next.js App Router POST handler.
+ *
+ * Streams the assistant response as Server-Sent Events (SSE). Each frame is a
+ * JSON object with a `type` discriminant:
+ *   - `{ type: "text",     text: "..." }`       — incremental text chunk
+ *   - `{ type: "metadata", sources: [...] }`    — retrieval metadata (last frame)
+ *   - `{ type: "error",    error: "..." }`       — stream-level error
+ *
+ * @example
+ * // src/app/api/chat/route.ts
+ * export const POST = createStreamHandler(getRagConfig());
+ *
+ * // Client-side parsing in useRagChat.ts:
+ * // const lines = chunk.split('\n');
+ * // for (const line of lines) {
+ * //   if (line.startsWith('data: ')) {
+ * //     const frame = JSON.parse(line.slice(6));
+ * //     if (frame.type === 'text') { ... }
+ * //   }
+ * // }
+ */
+declare function createStreamHandler(configOrPlugin?: Partial<RagConfig> | VectorPlugin): (req: NextRequest) => Promise<Response>;
+/**
+ * createIngestHandler — factory for the document ingestion endpoint.
+ */
+declare function createIngestHandler(configOrPlugin?: Partial<RagConfig> | VectorPlugin): (req: NextRequest) => Promise<NextResponse<{
+    error: string;
+}> | NextResponse<{
+    results: {
+        docId: string | number;
+        chunksIngested: number;
+    }[];
+}>>;
+/**
+ * createHealthHandler — factory for the health-check endpoint.
+ */
+declare function createHealthHandler(configOrPlugin?: Partial<RagConfig> | VectorPlugin): () => Promise<NextResponse<{
+    timestamp: string;
+    vectorDb: HealthCheckResult;
+    llm: HealthCheckResult;
+    embedding?: HealthCheckResult;
+    allHealthy: boolean;
+    status: string;
+}> | NextResponse<{
+    status: string;
+    error: string;
+}>>;
+/**
+ * createUploadHandler — factory for the file upload ingestion endpoint.
+ */
+declare function createUploadHandler(configOrPlugin?: Partial<RagConfig> | VectorPlugin): (req: NextRequest) => Promise<NextResponse<{
+    error: string;
+}> | NextResponse<{
+    message: string;
+    results: {
+        docId: string | number;
+        chunksIngested: number;
+    }[];
+}>>;
+
+export { ConfigValidator as C, type HealthCheckResult as H, type IProviderValidator as I, type ValidationError as V, type IProviderHealthChecker as a, VectorPlugin as b, createChatHandler as c, createHealthHandler as d, createIngestHandler as e, createStreamHandler as f, createUploadHandler as g, sseFrame as h, sseMetaFrame as i, sseTextFrame as j, sseErrorFrame as s };

package/dist/index.d.mts

@@ -1,8 +1,7 @@
 import React$1, { ReactNode } from 'react';
-import { C as ChatMessage } from './DocumentChunker-C-sCZPhi.mjs';
-export { a as ChatOptions, b as Chunk, c as ChunkOptions, E as EmbedOptions, I as ILLMProvider } from './DocumentChunker-C-sCZPhi.mjs';
-import { V as VectorMatch, U as UIConfig } from './RagConfig-DRJO4hGU.mjs';
-export { C as ChatResponse, E as EmbeddingConfig, a as EmbeddingProvider, I as IngestDocument, L as LLMConfig, b as LLMProvider, R as RAGConfig, c as RagConfig, d as UpsertDocument, e as VectorDBConfig, f as VectorDBProvider } from './RagConfig-DRJO4hGU.mjs';
+import { C as ChatMessage, V as VectorMatch, U as UIConfig } from './RagConfig-BEmz4hVP.mjs';
+export { a as ChatOptions, b as ChatResponse, E as EmbedOptions, c as EmbeddingConfig, d as EmbeddingProvider, I as ILLMProvider, e as IngestDocument, L as LLMConfig, f as LLMProvider, R as RAGConfig, g as RagConfig, h as UpsertDocument, i as VectorDBConfig, j as VectorDBProvider } from './RagConfig-BEmz4hVP.mjs';
+export { C as Chunk, a as ChunkOptions } from './DocumentChunker-Dh9TvmGG.mjs';
 
 interface ChatWidgetProps {
     /** Position of the floating button. Defaults to bottom-right. */

package/dist/index.d.ts

@@ -1,8 +1,7 @@
 import React$1, { ReactNode } from 'react';
-import { C as ChatMessage } from './DocumentChunker-C-sCZPhi.js';
-export { a as ChatOptions, b as Chunk, c as ChunkOptions, E as EmbedOptions, I as ILLMProvider } from './DocumentChunker-C-sCZPhi.js';
-import { V as VectorMatch, U as UIConfig } from './RagConfig-DRJO4hGU.js';
-export { C as ChatResponse, E as EmbeddingConfig, a as EmbeddingProvider, I as IngestDocument, L as LLMConfig, b as LLMProvider, R as RAGConfig, c as RagConfig, d as UpsertDocument, e as VectorDBConfig, f as VectorDBProvider } from './RagConfig-DRJO4hGU.js';
+import { C as ChatMessage, V as VectorMatch, U as UIConfig } from './RagConfig-BEmz4hVP.js';
+export { a as ChatOptions, b as ChatResponse, E as EmbedOptions, c as EmbeddingConfig, d as EmbeddingProvider, I as ILLMProvider, e as IngestDocument, L as LLMConfig, f as LLMProvider, R as RAGConfig, g as RagConfig, h as UpsertDocument, i as VectorDBConfig, j as VectorDBProvider } from './RagConfig-BEmz4hVP.js';
+export { C as Chunk, a as ChunkOptions } from './DocumentChunker-Dh9TvmGG.js';
 
 interface ChatWidgetProps {
     /** Position of the floating button. Defaults to bottom-right. */