@retrivora-ai/rag-engine 1.9.6 → 1.9.8

package/src/hooks/useRagChat.ts

@@ -63,6 +63,7 @@ export function useRagChat(
 ): UseRagChatReturn {
   const {
     apiUrl = '/api/chat',
+    retrivoraApiBase = '/api/retrivora',
     namespace,
     persist = true,
     onReply,
@@ -89,9 +90,13 @@ export function useRagChat(
 
       lastInputRef.current = trimmed;
 
+      const userMsgId = opts?.skipUserMessage
+        ? (messagesRef.current.filter((m) => m.role === 'user').pop()?.id || `user_${Date.now()}`)
+        : `user_${Date.now()}`;
+
       if (!opts?.skipUserMessage) {
         const userMessage: RagMessage = {
-          id: `user_${Date.now()}`,
+          id: userMsgId,
           role: 'user',
           content: trimmed,
           createdAt: new Date().toISOString(),
@@ -112,15 +117,22 @@ export function useRagChat(
 
       try {
         const history = messagesRef.current.map(({ role, content }) => ({ role, content }));
+        const assistantMessageId = `assistant_${Date.now()}`;
 
         const response = await fetch(apiUrl, {
           method: 'POST',
-          headers: { 'Content-Type': 'application/json' },
+          headers: { 
+            'Content-Type': 'application/json',
+            ...(options.headers || {})
+          },
           signal: controller.signal,
           body: JSON.stringify({
             message: trimmed,
             history,
             namespace: namespace ?? projectId,
+            sessionId: options.sessionId || 'default',
+            messageId: assistantMessageId,
+            userMessageId: userMsgId,
           }),
         });
 
@@ -177,7 +189,6 @@ export function useRagChat(
         // ─────────────────────────────────────────────────────────────────
 
         // Add a placeholder assistant message
-        const assistantMessageId = `assistant_${Date.now()}`;
         setMessages((prev) => [
           ...prev,
           {
@@ -193,58 +204,34 @@ export function useRagChat(
           if (done) break;
 
           buffer += decoder.decode(value, { stream: true });
+          const frames = parseSseChunk(buffer);
+          
+          // Clear processed frames from buffer (approximate by matching last found frame boundary)
+          const lastIndex = buffer.lastIndexOf('\n\n');
+          if (lastIndex !== -1) {
+            buffer = buffer.slice(lastIndex + 2);
+          }
 
-          const lastBoundary = buffer.lastIndexOf('\n\n');
-          if (lastBoundary === -1) continue;
-
-          const complete = buffer.slice(0, lastBoundary + 2);
-          buffer = buffer.slice(lastBoundary + 2);
-
-          let hasNonTextFrame = false;
-
-          for (const frame of parseSseChunk(complete)) {
-            if (frame.type === 'text' && frame.text) {
+          for (const frame of frames) {
+            if (frame.type === 'text') {
               assistantContent += frame.text;
               pendingContentRef.current = assistantContent;
-              // Schedule a batched RAF flush instead of immediate setMessages
               scheduleFlush(assistantMessageId);
-            } else if (frame.type === 'thinking' && frame.text) {
+            } else if (frame.type === 'thinking') {
               thinkingContent += frame.text;
               pendingThinkingRef.current = thinkingContent;
               scheduleFlush(assistantMessageId);
             } else if (frame.type === 'metadata') {
               sources = frame.sources ?? [];
-              thinkingMs = (frame as any).thinkingMs;
-              hasNonTextFrame = true;
+              thinkingMs = frame.thinkingMs;
             } else if (frame.type === 'ui_transformation') {
               uiTransformation = frame.data;
-              hasNonTextFrame = true;
             } else if (frame.type === 'observability') {
-              trace = (frame as SseObservabilityFrame).data;
-              hasNonTextFrame = true;
+              trace = frame.data;
             } else if (frame.type === 'error') {
-              setError(frame.error || 'Stream error');
+              throw new Error(frame.error);
             }
           }
-
-          // Flush non-text metadata immediately (sources, UI transform, trace)
-          if (hasNonTextFrame) {
-            pendingFlush = false; // cancel pending text flush — we'll do a full update
-            setMessages((prev) =>
-              prev.map((msg) =>
-                msg.id === assistantMessageId
-                  ? {
-                      ...msg,
-                      content: assistantContent,
-                      thinking: thinkingContent || undefined,
-                      thinkingMs: thinkingMs,
-                      sources: sources.length > 0 ? sources : msg.sources,
-                      uiTransformation: uiTransformation || (msg as RagMessage).uiTransformation,
-                    }
-                  : msg
-              )
-            );
-          }
         }
 
         // Process any remaining buffered data
@@ -254,9 +241,9 @@ export function useRagChat(
             else if (frame.type === 'thinking' && frame.text) thinkingContent += frame.text;
             else if (frame.type === 'metadata') {
               sources = frame.sources ?? [];
-              thinkingMs = (frame as any).thinkingMs;
+              thinkingMs = frame.thinkingMs;
             }
-            else if (frame.type === 'observability') trace = (frame as SseObservabilityFrame).data;
+            else if (frame.type === 'observability') trace = frame.data;
           }
         }
 
@@ -289,7 +276,7 @@ export function useRagChat(
         abortControllerRef.current = null;
       }
     },
-    [apiUrl, isLoading, namespace, onError, onReply, projectId, setMessages]
+    [apiUrl, isLoading, namespace, onError, onReply, projectId, setMessages, options.headers, options.sessionId]
   );
 
   const clear = useCallback(() => {
@@ -315,6 +302,73 @@ export function useRagChat(
     setIsLoading(false);
   }, []);
 
+  const loadHistory = useCallback(async (sessionId: string) => {
+    setIsLoading(true);
+    setError(null);
+    try {
+      const res = await fetch(`${retrivoraApiBase}/history?sessionId=${encodeURIComponent(sessionId)}`);
+      if (!res.ok) throw new Error(`Failed to load history: ${res.statusText}`);
+      const data = await res.json();
+      const loadedMessages = (data.history || []).map((msg: any) => ({
+        id: msg.id,
+        role: msg.role,
+        content: msg.content,
+        sources: msg.sources,
+        uiTransformation: msg.uiTransformation,
+        trace: msg.trace,
+        createdAt: msg.createdAt,
+      }));
+      setMessages(loadedMessages);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : 'Failed to load history';
+      setError(msg);
+      onError?.(msg);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [retrivoraApiBase, onError, setMessages]);
+
+  const clearHistory = useCallback(async (sessionId: string) => {
+    setIsLoading(true);
+    setError(null);
+    try {
+      const res = await fetch(`${retrivoraApiBase}/history/clear`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ sessionId }),
+      });
+      if (!res.ok) throw new Error(`Failed to clear history: ${res.statusText}`);
+      setMessages([]);
+      if (persist) localStorage.removeItem(storageKey);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : 'Failed to clear history';
+      setError(msg);
+      onError?.(msg);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [retrivoraApiBase, onError, persist, setMessages, storageKey]);
+
+  const submitFeedback = useCallback(async (messageId: string, rating: 'thumbs_up' | 'thumbs_down', comment?: string) => {
+    try {
+      const res = await fetch(`${retrivoraApiBase}/feedback`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          messageId,
+          sessionId: options.sessionId || 'default',
+          rating,
+          comment,
+        }),
+      });
+      if (!res.ok) throw new Error(`Failed to submit feedback: ${res.statusText}`);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : 'Failed to submit feedback';
+      onError?.(msg);
+      throw err;
+    }
+  }, [retrivoraApiBase, onError, options.sessionId]);
+
   return {
     messages,
     isLoading,
@@ -324,5 +378,8 @@ export function useRagChat(
     retry,
     setMessages,
     stop,
+    loadHistory,
+    clearHistory,
+    submitFeedback,
   };
 }

package/src/hooks/useStoredMessages.ts

@@ -32,12 +32,23 @@ export function useStoredMessages<T extends StoredMessage>(
   storageKey: string,
   persist: boolean
 ): [T[], React.Dispatch<React.SetStateAction<T[]>>] {
-  const [messages, setMessages] = React.useState<T[]>(() => (
-    persist ? (readStoredMessages(storageKey) as T[]) : []
-  ));
+  const [messages, setMessages] = React.useState<T[]>([]);
+  const isLoaded = React.useRef(false);
 
+  // Load from localStorage only on client-side mount to prevent hydration mismatch
   React.useEffect(() => {
-    if (!persist || typeof window === 'undefined') {
+    if (persist) {
+      const loaded = readStoredMessages(storageKey) as T[];
+      if (loaded.length > 0) {
+        setMessages(loaded);
+      }
+    }
+    isLoaded.current = true;
+  }, [storageKey, persist]);
+
+  // Save to localStorage only after initialization has completed to avoid overwriting with empty array
+  React.useEffect(() => {
+    if (!isLoaded.current || !persist || typeof window === 'undefined') {
       return;
     }
 

package/src/index.ts

@@ -1,3 +1,5 @@
+'use client';
+
 /**
  * Package entry point — public API exported to consumers of this npm package.
  * This entry point is CLIENT-SAFE and can be imported in React Client Components.
@@ -13,6 +15,11 @@ export { MessageBubble } from './components/MessageBubble';
 export { SourceCard } from './components/SourceCard';
 export { ObservabilityPanel } from './components/ObservabilityPanel';
 export { ConfigProvider, useConfig } from './components/ConfigProvider';
+export { Hero } from './components/Hero';
+export { Lifecycle } from './components/Lifecycle';
+export { ArchitectureCardsSection } from './components/ArchitectureCardsSection';
+export { Documentation } from './components/Documentation';
+export { AmbientBackground } from './components/AmbientBackground';
 
 // ── Headless Hooks ────────────────────────────────────────────
 export { useRagChat } from './hooks/useRagChat';

package/src/llm/LLMFactory.ts

@@ -4,6 +4,8 @@ import { OpenAIProvider } from './providers/OpenAIProvider';
 import { AnthropicProvider } from './providers/AnthropicProvider';
 import { OllamaProvider } from './providers/OllamaProvider';
 import { GeminiProvider } from './providers/GeminiProvider';
+import { GroqProvider } from './providers/GroqProvider';
+import { QwenProvider } from './providers/QwenProvider';
 import { UniversalLLMAdapter } from './providers/UniversalLLMAdapter';
 import { IProviderValidator, IProviderHealthChecker } from '../core/ProviderInterfaces';
 import { ProviderNotFoundException } from '../exceptions';
@@ -53,7 +55,7 @@ export class LLMFactory {
    */
   static listProviders(): string[] {
     return [
-      'openai', 'anthropic', 'ollama', 'gemini', 'rest', 'universal_rest', 'custom',
+      'openai', 'anthropic', 'ollama', 'gemini', 'groq', 'qwen', 'rest', 'universal_rest', 'custom',
       ...Array.from(customProviders.keys()),
     ];
   }
@@ -67,6 +69,10 @@ export class LLMFactory {
         return new OllamaProvider(llmConfig, embeddingConfig);
       case 'gemini':
         return new GeminiProvider(llmConfig, embeddingConfig);
+      case 'groq':
+        return new GroqProvider(llmConfig, embeddingConfig);
+      case 'qwen':
+        return new QwenProvider(llmConfig, embeddingConfig);
       case 'rest':
       case 'universal_rest':
       case 'custom':
@@ -83,11 +89,12 @@ export class LLMFactory {
           return new UniversalLLMAdapter(llmConfig);
         }
         throw new ProviderNotFoundException(
-          'LLM',
-          String(llmConfig.provider),
-          `[LLMFactory] Unknown provider "${llmConfig.provider}". ` +
-          `Built-in providers: ${LLMFactory.listProviders().join(', ')}. ` +
-          `Register a custom provider with LLMFactory.register().`
+          'llm',
+          llmConfig.provider ?? 'undefined',
+          {
+            message: `Unknown provider "${llmConfig.provider}". Register a custom provider with LLMFactory.register().`,
+            available: LLMFactory.listProviders()
+          }
         );
       }
     }
@@ -109,6 +116,8 @@ export class LLMFactory {
       case 'anthropic': return AnthropicProvider;
       case 'ollama': return OllamaProvider;
       case 'gemini': return GeminiProvider;
+      case 'groq': return GroqProvider;
+      case 'qwen': return QwenProvider;
       case 'rest':
       case 'universal_rest':
       case 'custom': return UniversalLLMAdapter as unknown as LLMProviderStatic;

package/src/llm/providers/GroqProvider.ts

@@ -0,0 +1,176 @@
+/**
+ * Groq LLM Provider
+ */
+
+import OpenAI from 'openai';
+import { ILLMProvider, EmbedOptions } from '../ILLMProvider';
+import { ChatMessage, ChatOptions } from '../../types';
+import { LLMConfig, EmbeddingConfig } from '../../config/RagConfig';
+import { IProviderValidator, IProviderHealthChecker, HealthCheckResult } from '../../core/ProviderInterfaces';
+import { ValidationError } from '../../core/ConfigValidator';
+import { buildSystemContent } from '../utils';
+
+export class GroqProvider implements ILLMProvider {
+  private readonly client: OpenAI;
+  private readonly llmConfig: LLMConfig;
+
+  constructor(llmConfig: LLMConfig, embeddingConfig?: EmbeddingConfig) {
+    void embeddingConfig;
+    const apiKey = llmConfig.apiKey || process.env.GROQ_API_KEY;
+    if (!apiKey) throw new Error('[GroqProvider] llmConfig.apiKey or GROQ_API_KEY environment variable is required');
+    
+    this.client = new OpenAI({
+      apiKey,
+      baseURL: llmConfig.baseUrl || 'https://api.groq.com/openai/v1',
+    });
+    this.llmConfig = llmConfig;
+  }
+
+  static getValidator(): IProviderValidator {
+    return {
+      validate(config: Record<string, unknown>): ValidationError[] {
+        const errors: ValidationError[] = [];
+        if (!config.apiKey && !process.env.GROQ_API_KEY) {
+          errors.push({
+            field: 'llm.apiKey',
+            message: 'Groq API key is required',
+            suggestion: 'Set GROQ_API_KEY environment variable',
+            severity: 'error',
+          });
+        }
+        if (!config.model) {
+          errors.push({
+            field: 'llm.model',
+            message: 'Groq model name is required',
+            suggestion: 'e.g., "llama-3.3-70b-versatile"',
+            severity: 'error',
+          });
+        }
+        return errors;
+      }
+    };
+  }
+
+  static getHealthChecker(): IProviderHealthChecker {
+    return {
+      async check(config: Record<string, unknown>): Promise<HealthCheckResult> {
+        const timestamp = Date.now();
+        const apiKey = (config.apiKey as string) || process.env.GROQ_API_KEY || '';
+        const modelName = config.model as string;
+        
+        try {
+          const OpenAI = await import('openai');
+          const client = new OpenAI.default({
+            apiKey,
+            baseURL: (config.baseUrl as string) || 'https://api.groq.com/openai/v1',
+          });
+          const models = await client.models.list();
+          const hasModel = models.data.some((m) => m.id === modelName);
+          return {
+            healthy: true,
+            provider: 'groq',
+            capabilities: { model: modelName, available: hasModel, totalModels: models.data.length },
+            timestamp,
+          };
+        } catch (error) {
+          return {
+            healthy: false,
+            provider: 'groq',
+            error: `Connection failed: ${error instanceof Error ? error.message : String(error)}`,
+            timestamp,
+          };
+        }
+      }
+    };
+  }
+
+  async chat(messages: ChatMessage[], context: string, options?: ChatOptions): Promise<string> {
+    const basePrompt =
+      options?.systemPrompt ??
+      this.llmConfig.systemPrompt ??
+      'You are a helpful assistant. Answer questions based on the provided context.';
+
+    const systemMessage: OpenAI.Chat.ChatCompletionSystemMessageParam = {
+      role: 'system',
+      content: buildSystemContent(basePrompt, context),
+    };
+
+    const formattedMessages: OpenAI.Chat.ChatCompletionMessageParam[] = [
+      systemMessage,
+      ...messages.map((m) => ({
+        role: m.role as 'user' | 'assistant',
+        content: m.content,
+      })),
+    ];
+
+    const completion = await this.client.chat.completions.create({
+      model: this.llmConfig.model,
+      messages: formattedMessages,
+      max_tokens: options?.maxTokens ?? this.llmConfig.maxTokens ?? 1024,
+      temperature: options?.temperature ?? this.llmConfig.temperature ?? 0.7,
+      stop: options?.stop,
+    });
+
+    return completion.choices[0]?.message?.content ?? '';
+  }
+  
+  async *chatStream(messages: ChatMessage[], context: string, options?: ChatOptions): AsyncIterable<string> {
+    const basePrompt =
+      options?.systemPrompt ??
+      this.llmConfig.systemPrompt ??
+      'You are a helpful assistant. Answer questions based on the provided context.';
+
+    const systemMessage: OpenAI.Chat.ChatCompletionSystemMessageParam = {
+      role: 'system',
+      content: buildSystemContent(basePrompt, context),
+    };
+
+    const formattedMessages: OpenAI.Chat.ChatCompletionMessageParam[] = [
+      systemMessage,
+      ...messages.map((m) => ({
+        role: m.role as 'user' | 'assistant',
+        content: m.content,
+      })),
+    ];
+
+    const stream = await this.client.chat.completions.create({
+      model: this.llmConfig.model,
+      messages: formattedMessages,
+      max_tokens: options?.maxTokens ?? this.llmConfig.maxTokens ?? 1024,
+      temperature: options?.temperature ?? this.llmConfig.temperature ?? 0.7,
+      stop: options?.stop,
+      stream: true,
+    });
+
+    if (!stream) {
+      throw new Error('[GroqProvider] completions.create stream is undefined');
+    }
+
+    for await (const chunk of stream) {
+      const content = chunk.choices[0]?.delta?.content || '';
+      if (content) yield content;
+    }
+  }
+
+  async embed(text: string, options?: EmbedOptions): Promise<number[]> {
+    void text;
+    void options;
+    throw new Error('[GroqProvider] Groq does not provide a native embedding API. Please configure "openai" or "gemini" for embeddings in RagConfig.');
+  }
+
+  async batchEmbed(texts: string[], options?: EmbedOptions): Promise<number[][]> {
+    void texts;
+    void options;
+    throw new Error('[GroqProvider] Groq does not provide a native embedding API. Please configure "openai" or "gemini" for embeddings in RagConfig.');
+  }
+
+  async ping(): Promise<boolean> {
+    try {
+      await this.client.models.list();
+      return true;
+    } catch (err) {
+      console.error('[GroqProvider] Ping failed:', err);
+      return false;
+    }
+  }
+}