@retrivora-ai/rag-engine 1.0.4 → 1.0.5

package/src/hooks/useRagChat.ts

@@ -5,7 +5,12 @@
  *
  * Use this when you want to build a COMPLETELY CUSTOM UI but still leverage
  * the RAG backend. The hook handles all state: messages, loading, errors,
- * localStorage persistence, and the /api/chat round-trip via Axios.
+ * localStorage persistence, and the /api/chat round-trip.
+ *
+ * Consumes the SSE stream format produced by `createStreamHandler`:
+ *   data: { type: "text",     text: "..." }
+ *   data: { type: "metadata", sources: [...] }
+ *   data: { type: "error",    error: "..." }
  *
  * Usage:
  *   const { messages, send, clear, isLoading, error } = useRagChat('my-project');
@@ -14,7 +19,7 @@
  */
 
 import { useState, useCallback, useRef, useEffect } from 'react';
-import { VectorMatch } from '@/types';
+import { VectorMatch } from '../types';
 import { useStoredMessages } from './useStoredMessages';
 
 // ─── Types ────────────────────────────────────────────────────────────────────
@@ -61,6 +66,36 @@ export interface UseRagChatReturn {
   setMessages: React.Dispatch<React.SetStateAction<RagMessage[]>>;
 }
 
+// ─── SSE Frame Parser ──────────────────────────────────────────────────────────
+
+interface SseTextFrame  { type: 'text';     text: string }
+interface SseMetaFrame  { type: 'metadata'; sources?: VectorMatch[] }
+interface SseErrorFrame { type: 'error';    error: string }
+type SseFrame = SseTextFrame | SseMetaFrame | SseErrorFrame;
+
+/**
+ * Parse all complete SSE frames from a raw chunk string.
+ * Handles cases where a single `read()` value contains multiple frames.
+ */
+function parseSseChunk(raw: string): SseFrame[] {
+  const frames: SseFrame[] = [];
+  // Split on double-newline (SSE frame boundary)
+  for (const block of raw.split('\n\n')) {
+    for (const line of block.split('\n')) {
+      if (!line.startsWith('data: ')) continue;
+      try {
+        const frame = JSON.parse(line.slice(6)) as SseFrame;
+        if (frame && typeof frame === 'object' && 'type' in frame) {
+          frames.push(frame);
+        }
+      } catch {
+        // Ignore malformed frames
+      }
+    }
+  }
+  return frames;
+}
+
 // ─── Hook ─────────────────────────────────────────────────────────────────────
 
 export function useRagChat(
@@ -88,13 +123,13 @@ export function useRagChat(
 
   // ── Core send function ────────────────────────────────────────────────────
   const sendMessage = useCallback(
-    async (text: string, options?: { skipUserMessage?: boolean }) => {
+    async (text: string, opts?: { skipUserMessage?: boolean }) => {
       const trimmed = text.trim();
       if (!trimmed || isLoading) return;
 
       lastInputRef.current = trimmed;
 
-      if (!options?.skipUserMessage) {
+      if (!opts?.skipUserMessage) {
         const userMessage: RagMessage = {
           id: `user_${Date.now()}`,
           role: 'user',
@@ -133,8 +168,10 @@ export function useRagChat(
         const decoder = new TextDecoder();
         let assistantContent = '';
         let sources: VectorMatch[] = [];
+        // Buffer for partial SSE frames that arrive split across reads
+        let buffer = '';
 
-        // Add a placeholder assistant message that we will update
+        // Add a placeholder assistant message that we will update incrementally
         const assistantMessageId = `assistant_${Date.now()}`;
         setMessages((prev) => [
           ...prev,
@@ -150,41 +187,43 @@ export function useRagChat(
           const { done, value } = await reader.read();
           if (done) break;
 
-          const chunk = decoder.decode(value, { stream: true });
-          
-          // Handle protocol tokens
-          if (chunk.includes('__METADATA__')) {
-            const [text, metadataStr] = chunk.split('__METADATA__');
-            if (text) assistantContent += text;
-            try {
-              const meta = JSON.parse(metadataStr);
-              sources = meta.sources || [];
-            } catch {
-              console.warn('[useRagChat] Failed to parse metadata');
-            }
-          } else if (chunk.includes('__ERROR__')) {
-            const [text, errorStr] = chunk.split('__ERROR__');
-            if (text) assistantContent += text;
-            try {
-              const err = JSON.parse(errorStr);
-              setError(err.error || 'Stream error');
-            } catch {
-              setError('An error occurred during streaming');
+          buffer += decoder.decode(value, { stream: true });
+
+          // Only process complete frames (ending with \n\n)
+          const lastBoundary = buffer.lastIndexOf('\n\n');
+          if (lastBoundary === -1) continue; // Wait for more data
+
+          const complete = buffer.slice(0, lastBoundary + 2);
+          buffer = buffer.slice(lastBoundary + 2);
+
+          for (const frame of parseSseChunk(complete)) {
+            if (frame.type === 'text') {
+              assistantContent += frame.text;
+            } else if (frame.type === 'metadata') {
+              sources = frame.sources ?? [];
+            } else if (frame.type === 'error') {
+              setError(frame.error || 'Stream error');
             }
-          } else {
-            assistantContent += chunk;
           }
 
-          // Update the specific message
-          setMessages((prev) => 
-            prev.map((msg) => 
-              msg.id === assistantMessageId 
-                ? { ...msg, content: assistantContent, sources: sources.length > 0 ? sources : msg.sources } 
+          // Update the assistant message with accumulated content
+          setMessages((prev) =>
+            prev.map((msg) =>
+              msg.id === assistantMessageId
+                ? { ...msg, content: assistantContent, sources: sources.length > 0 ? sources : msg.sources }
                 : msg
             )
           );
         }
 
+        // Process any remaining buffered data
+        if (buffer.trim()) {
+          for (const frame of parseSseChunk(buffer)) {
+            if (frame.type === 'text') assistantContent += frame.text;
+            else if (frame.type === 'metadata') sources = frame.sources ?? [];
+          }
+        }
+
         const finalAssistantMessage: RagMessage = {
           id: assistantMessageId,
           role: 'assistant',

package/src/server.ts

@@ -17,7 +17,7 @@ export type { BatchOptions, BatchResult } from './core/BatchProcessor';
 // ── Core Orchestration ─────────────────────────────────────────
 export { VectorPlugin } from './core/VectorPlugin';
 export { Pipeline } from './core/Pipeline';
-export { ConfigResolver } from './core/ConfigResolver';
+export { ConfigResolver, resetConfigCache } from './core/ConfigResolver';
 export { ProviderRegistry } from './core/ProviderRegistry';
 export { ConfigValidator } from './core/ConfigValidator';
 export { ProviderHealthCheck } from './core/ProviderHealthCheck';
@@ -54,4 +54,14 @@ export { OllamaProvider } from './llm/providers/OllamaProvider';
 export { UniversalLLMAdapter } from './llm/providers/UniversalLLMAdapter';
 
 // ── Next.js Route Handler Factories ───────────────────────────
-export { createChatHandler, createIngestHandler, createHealthHandler, createUploadHandler } from './handlers';
+export {
+  createChatHandler,
+  createStreamHandler,
+  createIngestHandler,
+  createHealthHandler,
+  createUploadHandler,
+  sseFrame,
+  sseTextFrame,
+  sseMetaFrame,
+  sseErrorFrame,
+} from './handlers';

package/dist/DocumentChunker-C-sCZPhi.d.mts

@@ -1,102 +0,0 @@
-/**
- * Generic LLM Provider interface.
- * Covers both chat completion and embedding generation so a single
- * provider can handle both responsibilities when appropriate.
- */
-interface ChatMessage {
-    role: 'user' | 'assistant' | 'system';
-    content: string;
-}
-interface ChatOptions {
-    /** Override max tokens for this specific call */
-    maxTokens?: number;
-    /** Override temperature for this specific call */
-    temperature?: number;
-    /** Stop sequences */
-    stop?: string[];
-}
-interface EmbedOptions {
-    /** Override model for this specific embed call */
-    model?: string;
-    /** Specify the task type for models that require prefixes (e.g. nomic-embed-text) */
-    taskType?: 'query' | 'document';
-}
-interface ILLMProvider {
-    /**
-     * Send a chat completion request.
-     * @param messages – the full conversation history
-     * @param context  – retrieved RAG context to inject
-     * @param options  – optional per-call overrides
-     * @returns        – the assistant's reply text
-     */
-    chat(messages: ChatMessage[], context: string, options?: ChatOptions): Promise<string>;
-    /**
-     * Send a streaming chat completion request.
-     * @returns – an async iterable of text chunks
-     */
-    chatStream?(messages: ChatMessage[], context: string, options?: ChatOptions): AsyncIterable<string>;
-    /**
-     * Generate an embedding vector for the given text.
-     * @param text    – text to embed
-     * @param options – optional overrides
-     * @returns       – float array (the embedding)
-     */
-    embed(text: string, options?: EmbedOptions): Promise<number[]>;
-    /**
-     * Generate embedding vectors for multiple texts in a single batch.
-     * @param texts   – array of texts to embed
-     * @param options – optional overrides
-     * @returns       – array of float arrays
-     */
-    batchEmbed(texts: string[], options?: EmbedOptions): Promise<number[][]>;
-    /**
-     * Check if the provider endpoint is reachable.
-     */
-    ping(): Promise<boolean>;
-}
-
-/**
- * DocumentChunker — splits long text into overlapping chunks
- * suitable for vector embedding and retrieval.
- *
- * Strategy: sentence-aware sliding window
- *   1. Split on sentence boundaries
- *   2. Accumulate sentences into chunks up to `chunkSize` characters
- *   3. Carry over `chunkOverlap` characters from the previous chunk
- */
-interface Chunk {
-    id: string;
-    content: string;
-    metadata?: Record<string, unknown>;
-}
-interface ChunkOptions {
-    /** Target chunk size in characters (default 1000) */
-    chunkSize?: number;
-    /** Overlap between consecutive chunks in characters (default 200) */
-    chunkOverlap?: number;
-    /** Source document identifier used as ID prefix */
-    docId?: string | number;
-    /** Extra metadata to attach to every chunk */
-    metadata?: Record<string, unknown>;
-    /** Characters used to split text, in order of priority */
-    separators?: string[];
-}
-declare class DocumentChunker {
-    private readonly chunkSize;
-    private readonly chunkOverlap;
-    private readonly separators;
-    constructor(chunkSize?: number, chunkOverlap?: number, separators?: string[]);
-    /**
-     * Split a single text string into overlapping chunks using a recursive strategy.
-     * Preserves structural boundaries (Markdown headers) where possible.
-     */
-    chunk(text: string, options?: ChunkOptions): Chunk[];
-    private recursiveSplit;
-    chunkMany(documents: Array<{
-        content: string;
-        docId?: string | number;
-        metadata?: Record<string, unknown>;
-    }>): Chunk[];
-}
-
-export { type ChatMessage as C, DocumentChunker as D, type EmbedOptions as E, type ILLMProvider as I, type ChatOptions as a, type Chunk as b, type ChunkOptions as c };

package/dist/DocumentChunker-C-sCZPhi.d.ts

@@ -1,102 +0,0 @@
-/**
- * Generic LLM Provider interface.
- * Covers both chat completion and embedding generation so a single
- * provider can handle both responsibilities when appropriate.
- */
-interface ChatMessage {
-    role: 'user' | 'assistant' | 'system';
-    content: string;
-}
-interface ChatOptions {
-    /** Override max tokens for this specific call */
-    maxTokens?: number;
-    /** Override temperature for this specific call */
-    temperature?: number;
-    /** Stop sequences */
-    stop?: string[];
-}
-interface EmbedOptions {
-    /** Override model for this specific embed call */
-    model?: string;
-    /** Specify the task type for models that require prefixes (e.g. nomic-embed-text) */
-    taskType?: 'query' | 'document';
-}
-interface ILLMProvider {
-    /**
-     * Send a chat completion request.
-     * @param messages – the full conversation history
-     * @param context  – retrieved RAG context to inject
-     * @param options  – optional per-call overrides
-     * @returns        – the assistant's reply text
-     */
-    chat(messages: ChatMessage[], context: string, options?: ChatOptions): Promise<string>;
-    /**
-     * Send a streaming chat completion request.
-     * @returns – an async iterable of text chunks
-     */
-    chatStream?(messages: ChatMessage[], context: string, options?: ChatOptions): AsyncIterable<string>;
-    /**
-     * Generate an embedding vector for the given text.
-     * @param text    – text to embed
-     * @param options – optional overrides
-     * @returns       – float array (the embedding)
-     */
-    embed(text: string, options?: EmbedOptions): Promise<number[]>;
-    /**
-     * Generate embedding vectors for multiple texts in a single batch.
-     * @param texts   – array of texts to embed
-     * @param options – optional overrides
-     * @returns       – array of float arrays
-     */
-    batchEmbed(texts: string[], options?: EmbedOptions): Promise<number[][]>;
-    /**
-     * Check if the provider endpoint is reachable.
-     */
-    ping(): Promise<boolean>;
-}
-
-/**
- * DocumentChunker — splits long text into overlapping chunks
- * suitable for vector embedding and retrieval.
- *
- * Strategy: sentence-aware sliding window
- *   1. Split on sentence boundaries
- *   2. Accumulate sentences into chunks up to `chunkSize` characters
- *   3. Carry over `chunkOverlap` characters from the previous chunk
- */
-interface Chunk {
-    id: string;
-    content: string;
-    metadata?: Record<string, unknown>;
-}
-interface ChunkOptions {
-    /** Target chunk size in characters (default 1000) */
-    chunkSize?: number;
-    /** Overlap between consecutive chunks in characters (default 200) */
-    chunkOverlap?: number;
-    /** Source document identifier used as ID prefix */
-    docId?: string | number;
-    /** Extra metadata to attach to every chunk */
-    metadata?: Record<string, unknown>;
-    /** Characters used to split text, in order of priority */
-    separators?: string[];
-}
-declare class DocumentChunker {
-    private readonly chunkSize;
-    private readonly chunkOverlap;
-    private readonly separators;
-    constructor(chunkSize?: number, chunkOverlap?: number, separators?: string[]);
-    /**
-     * Split a single text string into overlapping chunks using a recursive strategy.
-     * Preserves structural boundaries (Markdown headers) where possible.
-     */
-    chunk(text: string, options?: ChunkOptions): Chunk[];
-    private recursiveSplit;
-    chunkMany(documents: Array<{
-        content: string;
-        docId?: string | number;
-        metadata?: Record<string, unknown>;
-    }>): Chunk[];
-}
-
-export { type ChatMessage as C, DocumentChunker as D, type EmbedOptions as E, type ILLMProvider as I, type ChatOptions as a, type Chunk as b, type ChunkOptions as c };

package/dist/index-B2mutkgp.d.ts

@@ -1,116 +0,0 @@
-import { c as RagConfig, C as ChatResponse } from './RagConfig-DRJO4hGU.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>;
-}
-
-/**
- * createChatHandler — factory that returns a Next.js App Router POST handler
- */
-declare function createChatHandler(config?: Partial<RagConfig>): (req: NextRequest) => Promise<NextResponse<{
-    error: string;
-}> | NextResponse<ChatResponse>>;
-/**
- * createStreamHandler — factory that returns a streaming Next.js App Router POST handler
- */
-declare function createStreamHandler(config?: Partial<RagConfig>): (req: NextRequest) => Promise<Response>;
-/**
- * createIngestHandler — factory for the document ingestion endpoint.
- */
-declare function createIngestHandler(config?: Partial<RagConfig>): (req: NextRequest) => Promise<NextResponse<{
-    error: string;
-}> | NextResponse<{
-    results: {
-        docId: string | number;
-        chunksIngested: number;
-    }[];
-}>>;
-/**
- * createHealthHandler — factory for the health-check endpoint.
- */
-declare function createHealthHandler(config?: Partial<RagConfig>): () => 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(config?: Partial<RagConfig>): (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, createHealthHandler as b, createChatHandler as c, createIngestHandler as d, createUploadHandler as e, createStreamHandler as f };

package/dist/index-Bjy0es5a.d.mts

@@ -1,116 +0,0 @@
-import { c as RagConfig, C as ChatResponse } from './RagConfig-DRJO4hGU.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>;
-}
-
-/**
- * createChatHandler — factory that returns a Next.js App Router POST handler
- */
-declare function createChatHandler(config?: Partial<RagConfig>): (req: NextRequest) => Promise<NextResponse<{
-    error: string;
-}> | NextResponse<ChatResponse>>;
-/**
- * createStreamHandler — factory that returns a streaming Next.js App Router POST handler
- */
-declare function createStreamHandler(config?: Partial<RagConfig>): (req: NextRequest) => Promise<Response>;
-/**
- * createIngestHandler — factory for the document ingestion endpoint.
- */
-declare function createIngestHandler(config?: Partial<RagConfig>): (req: NextRequest) => Promise<NextResponse<{
-    error: string;
-}> | NextResponse<{
-    results: {
-        docId: string | number;
-        chunksIngested: number;
-    }[];
-}>>;
-/**
- * createHealthHandler — factory for the health-check endpoint.
- */
-declare function createHealthHandler(config?: Partial<RagConfig>): () => 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(config?: Partial<RagConfig>): (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, createHealthHandler as b, createChatHandler as c, createIngestHandler as d, createUploadHandler as e, createStreamHandler as f };