@retrivora-ai/rag-engine 0.1.0

package/src/config/UniversalProfiles.ts

@@ -0,0 +1,83 @@
+/**
+ * Pre-configured templates for popular AI and Vector services.
+ * Use these as defaults in the Universal Adapters.
+ */
+
+const OPENAI_BASE = {
+  chatPath: '/chat/completions',
+  embedPath: '/embeddings',
+  responseExtractPath: 'choices[0].message.content',
+  embedExtractPath: 'data[0].embedding',
+  chatPayloadTemplate: '{"model":"{{model}}","messages":{{messages}},"max_tokens":{{maxTokens}},"temperature":{{temperature}}}',
+};
+
+export const LLM_PROFILES = {
+  'openai-compatible': OPENAI_BASE,
+  'litellm': { 
+    ...OPENAI_BASE, 
+    chatPayloadTemplate: '{"model":"{{model}}","messages":{{messages}},"max_tokens":{{maxTokens}},"temperature":{{temperature}},"stream":false}' 
+  },
+  'anthropic-claude': {
+    chatPath: '/v1/messages',
+    responseExtractPath: 'content[0].text',
+    headers: { 'anthropic-version': '2023-06-01' },
+    chatPayloadTemplate: '{"model":"{{model}}","messages":{{messages}},"max_tokens":{{maxTokens}}}',
+  },
+  'google-gemini': {
+    chatPath: '/v1beta/models/{{model}}:generateContent',
+    responseExtractPath: 'candidates[0].content.parts[0].text',
+    chatPayloadTemplate: '{"contents":[{"parts":[{"text":"{{messages}}"}]}]}',
+  },
+  'github-copilot': {
+    ...OPENAI_BASE,
+    chatPayloadTemplate: '{"model":"{{model}}","messages":{{messages}},"temperature":{{temperature}}}',
+  },
+  'ollama-standard': {
+    chatPath: '/api/chat',
+    embedPath: '/api/embeddings',
+    responseExtractPath: 'message.content',
+    embedExtractPath: 'embedding',
+    chatPayloadTemplate: '{"model":"{{model}}","messages":{{messages}},"stream":false}',
+    embedPayloadTemplate: '{"model":"{{model}}","prompt":"{{input}}"}',
+  },
+};
+
+export const VECTOR_PROFILES = {
+  'pinecone-rest': {
+    queryPath: '/query',
+    upsertPath: '/vectors/upsert',
+    responseExtractPath: 'matches',
+    idPath: 'id',
+    scorePath: 'score',
+    contentPath: 'metadata.content',
+    metadataPath: 'metadata',
+    queryPayloadTemplate: '{"vector":{{vector}},"topK":{{topK}},"includeMetadata":true,"namespace":"{{namespace}}"}',
+  },
+  'mongodb-atlas': {
+    queryPath: '/action/aggregate',
+    responseExtractPath: 'documents',
+    idPath: '_id',
+    scorePath: 'score',
+    contentPath: 'content',
+    metadataPath: 'metadata',
+    queryPayloadTemplate: '{"collection":"{{index}}","database":"ai_db","dataSource":"Cluster0","pipeline":[{"$vectorSearch":{"index":"vector_index","path":"embedding","queryVector":{{vector}},"numCandidates":100,"limit":{{topK}}}},{"$project":{"_id":1,"content":1,"metadata":1,"score":{"$meta":"vectorSearchScore"}}}]}',
+  },
+  'chromadb': {
+    queryPath: '/api/v1/collections/{{index}}/query',
+    upsertPath: '/api/v1/collections/{{index}}/add',
+    responseExtractPath: 'matches',
+    idPath: 'id',
+    scorePath: 'distance',
+    contentPath: 'document',
+    metadataPath: 'metadata',
+  },
+  'qdrant': {
+    queryPath: '/collections/{{index}}/points/search',
+    upsertPath: '/collections/{{index}}/points',
+    responseExtractPath: 'result',
+    idPath: 'id',
+    scorePath: 'score',
+    contentPath: 'payload.content',
+    metadataPath: 'payload',
+  },
+};

package/src/config/serverConfig.ts

@@ -0,0 +1,142 @@
+/**
+ * serverConfig.ts — reads RagConfig from environment variables at runtime.
+ *
+ * This keeps secrets server-side and never exposes them to the browser.
+ * Consumer projects set these env vars in their .env.local file.
+ */
+
+import { RagConfig } from './RagConfig';
+
+const VECTOR_DB_PROVIDERS = ['pinecone', 'pgvector', 'mongodb', 'rest', 'universal_rest', 'custom'] as const;
+const LLM_PROVIDERS = ['openai', 'anthropic', 'ollama', 'rest', 'universal_rest', 'custom'] as const;
+const EMBEDDING_PROVIDERS = ['openai', 'ollama', 'rest', 'universal_rest', 'custom'] as const;
+
+function readString(env: Record<string, string | undefined>, name: string): string | undefined {
+  const value = env[name]?.trim();
+  return value ? value : undefined;
+}
+
+function readNumber(env: Record<string, string | undefined>, name: string, fallback: number): number {
+  const value = env[name];
+  if (!value) return fallback;
+
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) {
+    throw new Error(`[getRagConfig] ${name} must be a valid number`);
+  }
+
+  return parsed;
+}
+
+function readEnum<T extends readonly string[]>(
+  env: Record<string, string | undefined>,
+  name: string,
+  fallback: T[number],
+  allowed: T
+): T[number] {
+  const value = readString(env, name) ?? fallback;
+  if ((allowed as readonly string[]).includes(value)) {
+    return value as T[number];
+  }
+
+  throw new Error(`[getRagConfig] ${name} must be one of: ${allowed.join(', ')}`);
+}
+
+export function getRagConfig(env: Record<string, string | undefined> = process.env): RagConfig {
+  const projectId = readString(env, 'RAG_PROJECT_ID') ?? readString(env, 'NEXT_PUBLIC_PROJECT_ID') ?? 'default';
+  const vectorProvider = readEnum(env, 'VECTOR_DB_PROVIDER', 'pinecone', VECTOR_DB_PROVIDERS);
+  const llmProvider = readEnum(env, 'LLM_PROVIDER', 'openai', LLM_PROVIDERS);
+  const embeddingProvider = readEnum(env, 'EMBEDDING_PROVIDER', 'openai', EMBEDDING_PROVIDERS);
+  const embeddingDimensions = readNumber(env, 'EMBEDDING_DIMENSIONS', 1536);
+
+  // Build provider-specific vectorDb options
+  const vectorDbOptions: Record<string, unknown> = {};
+  if (vectorProvider === 'pinecone') {
+    vectorDbOptions.apiKey = readString(env, 'PINECONE_API_KEY') ?? '';
+    vectorDbOptions.environment = readString(env, 'PINECONE_ENVIRONMENT') ?? '';
+  } else if (vectorProvider === 'pgvector') {
+    vectorDbOptions.connectionString = readString(env, 'PGVECTOR_CONNECTION_STRING') ?? '';
+    vectorDbOptions.dimensions = embeddingDimensions;
+  } else if (vectorProvider === 'rest') {
+    vectorDbOptions.baseUrl = readString(env, 'VECTOR_DB_REST_URL') ?? '';
+    vectorDbOptions.headers = readString(env, 'VECTOR_DB_REST_API_KEY')
+      ? { 'api-key': readString(env, 'VECTOR_DB_REST_API_KEY') }
+      : {};
+  } else if (vectorProvider === 'universal_rest') {
+    vectorDbOptions.baseUrl = readString(env, 'VECTOR_BASE_URL') ?? readString(env, 'VECTOR_DB_REST_URL') ?? '';
+    vectorDbOptions.profile = readString(env, 'VECTOR_UNIVERSAL_PROFILE');
+    vectorDbOptions.headers = readString(env, 'VECTOR_DB_REST_API_KEY')
+      ? { Authorization: `Bearer ${readString(env, 'VECTOR_DB_REST_API_KEY')}` }
+      : {};
+  } else if (vectorProvider === 'mongodb') {
+    vectorDbOptions.uri = readString(env, 'MONGODB_URI') ?? '';
+    vectorDbOptions.database = readString(env, 'MONGODB_DB') ?? '';
+    vectorDbOptions.collection = readString(env, 'MONGODB_COLLECTION') ?? '';
+    vectorDbOptions.indexName = readString(env, 'MONGODB_INDEX_NAME') ?? 'vector_index';
+  }
+
+  const llmApiKeyByProvider: Record<string, string | undefined> = {
+    openai: readString(env, 'OPENAI_API_KEY'),
+    anthropic: readString(env, 'ANTHROPIC_API_KEY'),
+    ollama: undefined,
+    universal_rest: readString(env, 'LLM_API_KEY'),
+  };
+
+  const embeddingApiKeyByProvider: Record<string, string | undefined> = {
+    openai: readString(env, 'OPENAI_API_KEY'),
+    ollama: undefined,
+    custom: readString(env, 'EMBEDDING_API_KEY') ?? readString(env, 'OPENAI_API_KEY'),
+  };
+
+  return {
+    projectId,
+    vectorDb: {
+      provider: vectorProvider,
+      indexName: readString(env, 'VECTOR_DB_INDEX') ?? 'rag-index',
+      options: vectorDbOptions,
+    },
+    llm: {
+      provider: llmProvider,
+      model: readString(env, 'LLM_MODEL') ?? 'gpt-4o',
+      apiKey: llmApiKeyByProvider[llmProvider] ?? '',
+      baseUrl: readString(env, 'LLM_BASE_URL'),
+      systemPrompt: readString(env, 'LLM_SYSTEM_PROMPT'),
+      maxTokens: readNumber(env, 'LLM_MAX_TOKENS', 1024),
+      temperature: readNumber(env, 'LLM_TEMPERATURE', 0.7),
+      options: {
+        profile: readString(env, 'LLM_UNIVERSAL_PROFILE'),
+      },
+    },
+    embedding: {
+      provider: embeddingProvider,
+      model: readString(env, 'EMBEDDING_MODEL') ?? 'text-embedding-3-small',
+      apiKey: embeddingApiKeyByProvider[embeddingProvider],
+      baseUrl: readString(env, 'EMBEDDING_BASE_URL'),
+      dimensions: embeddingDimensions,
+      options: {
+        profile: readString(env, 'EMBEDDING_UNIVERSAL_PROFILE'),
+      },
+    },
+    ui: {
+      title: readString(env, 'NEXT_PUBLIC_UI_TITLE') ?? readString(env, 'UI_TITLE') ?? 'AI Assistant',
+      subtitle: readString(env, 'NEXT_PUBLIC_UI_SUBTITLE') ?? readString(env, 'UI_SUBTITLE') ?? 'Powered by RAG',
+      primaryColor: readString(env, 'NEXT_PUBLIC_PRIMARY_COLOR') ?? readString(env, 'UI_PRIMARY_COLOR') ?? '#10b981',
+      accentColor: readString(env, 'NEXT_PUBLIC_ACCENT_COLOR') ?? readString(env, 'UI_ACCENT_COLOR') ?? '#3b82f6',
+      logoUrl: readString(env, 'NEXT_PUBLIC_LOGO_URL') ?? readString(env, 'UI_LOGO_URL'),
+      placeholder: readString(env, 'NEXT_PUBLIC_PLACEHOLDER') ?? readString(env, 'UI_PLACEHOLDER') ?? 'Ask me anything…',
+      showSources: (readString(env, 'NEXT_PUBLIC_SHOW_SOURCES') ?? readString(env, 'UI_SHOW_SOURCES') ?? 'true') !== 'false',
+      welcomeMessage:
+        readString(env, 'NEXT_PUBLIC_WELCOME_MESSAGE') ??
+        readString(env, 'UI_WELCOME_MESSAGE') ??
+        'Hello! I\'m your AI assistant. Ask me anything about your documents.',
+      visualStyle: (readString(env, 'NEXT_PUBLIC_UI_VISUAL_STYLE') ?? readString(env, 'UI_VISUAL_STYLE') ?? 'glass') as 'glass' | 'solid',
+      borderRadius: (readString(env, 'NEXT_PUBLIC_UI_BORDER_RADIUS') ?? readString(env, 'UI_BORDER_RADIUS') ?? 'xl') as 'none' | 'sm' | 'md' | 'lg' | 'xl' | 'full',
+    },
+    rag: {
+      topK: readNumber(env, 'RAG_TOP_K', 5),
+      scoreThreshold: readNumber(env, 'RAG_SCORE_THRESHOLD', 0),
+      chunkSize: readNumber(env, 'RAG_CHUNK_SIZE', 1000),
+      chunkOverlap: readNumber(env, 'RAG_CHUNK_OVERLAP', 200),
+    },
+  };
+}

package/src/handlers/index.ts

@@ -0,0 +1,202 @@
+/**
+ * createChatHandler — factory that returns a Next.js App Router POST handler
+ * for the RAG chat endpoint.
+ *
+ * Use this when you want to mount the RAG chat API inside your OWN Next.js app
+ * (i.e. you installed @rag/ai-accelerator as a package and want the API route
+ * to live at your project's /api/chat).
+ *
+ * Usage — in your project's `src/app/api/chat/route.ts`:
+ *
+ *   import { createChatHandler } from '@rag/ai-accelerator/handlers';
+ *   import myConfig from '@/config/ragConfig';
+ *   export const POST = createChatHandler(myConfig);
+ *
+ * Or with env-based config:
+ *
+ *   import { createChatHandler } from '@rag/ai-accelerator/handlers';
+ *   import { getRagConfig } from '@rag/ai-accelerator';
+ *   export const POST = createChatHandler(getRagConfig());
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { RAGPipeline } from '../rag/RAGPipeline';
+import { RagConfig } from '../config/RagConfig';
+import { ChatMessage, ILLMProvider } from '../llm/ILLMProvider';
+import { IVectorDB } from '../vectordb/IVectorDB';
+import { DocumentParser } from '../utils/DocumentParser';
+
+export interface CustomAdapters {
+  vectorDB?: IVectorDB;
+  llmProvider?: ILLMProvider;
+  embeddingProvider?: ILLMProvider;
+}
+
+export function createChatHandler(config: RagConfig, adapters?: CustomAdapters) {
+  let pipeline: RAGPipeline | null = null;
+
+  function getPipeline(): RAGPipeline {
+    if (!pipeline) pipeline = new RAGPipeline(config, adapters);
+    return pipeline;
+  }
+
+  return async function POST(req: NextRequest) {
+    try {
+      const body = await req.json();
+      const { message, history = [], namespace } = body as {
+        message: string;
+        history?: ChatMessage[];
+        namespace?: string;
+      };
+
+      if (!message?.trim()) {
+        return NextResponse.json({ error: 'message is required' }, { status: 400 });
+      }
+
+      const rag = getPipeline();
+      const result = await rag.ask(message, history, namespace);
+      return NextResponse.json(result);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : 'Internal server error';
+      return NextResponse.json({ error: message }, { status: 500 });
+    }
+  };
+}
+
+/**
+ * createIngestHandler — factory for the document ingestion endpoint.
+ *
+ * Usage — in your project's `src/app/api/ingest/route.ts`:
+ *
+ *   import { createIngestHandler } from '@rag/ai-accelerator/handlers';
+ *   export const POST = createIngestHandler(myConfig, { vectorDB: new MyCustomDB() });
+ */
+export function createIngestHandler(config: RagConfig, adapters?: CustomAdapters) {
+  let pipeline: RAGPipeline | null = null;
+
+  function getPipeline(): RAGPipeline {
+    if (!pipeline) pipeline = new RAGPipeline(config, adapters);
+    return pipeline;
+  }
+
+  return async function POST(req: NextRequest) {
+    try {
+      const body = await req.json();
+      const { documents, namespace } = body as {
+        documents: Array<{ docId: string; content: string; metadata?: Record<string, unknown> }>;
+        namespace?: string;
+      };
+
+      if (!Array.isArray(documents) || documents.length === 0) {
+        return NextResponse.json(
+          { error: 'documents array is required and must not be empty' },
+          { status: 400 }
+        );
+      }
+
+      const rag = getPipeline();
+      const results = await rag.ingest(documents, namespace);
+      const totalChunks = results.reduce((sum, r) => sum + r.chunksIngested, 0);
+      return NextResponse.json({ results, totalChunks });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : 'Internal server error';
+      return NextResponse.json({ error: message }, { status: 500 });
+    }
+  };
+}
+
+/**
+ * createHealthHandler — factory for the health-check endpoint.
+ *
+ * Usage — in your project's `src/app/api/health/route.ts`:
+ *
+ *   import { createHealthHandler } from '@rag/ai-accelerator/handlers';
+ *   export const GET = createHealthHandler(myConfig, { vectorDB: new MyCustomDB() });
+ */
+export function createHealthHandler(config: RagConfig, adapters?: CustomAdapters) {
+  let pipeline: RAGPipeline | null = null;
+
+  function getPipeline(): RAGPipeline {
+    if (!pipeline) pipeline = new RAGPipeline(config, adapters);
+    return pipeline;
+  }
+
+  return async function GET() {
+    try {
+      const rag = getPipeline();
+      const health = await rag.health();
+      const status = health.vectorDB && health.llm ? 'ok' : 'degraded';
+      return NextResponse.json({
+        status,
+        ...health,
+        project: config.projectId,
+        timestamp: new Date().toISOString(),
+      });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : 'Unknown error';
+      return NextResponse.json(
+        { status: 'error', error: message, timestamp: new Date().toISOString() },
+        { status: 500 }
+      );
+    }
+  };
+}
+
+/**
+ * createUploadHandler — factory for the file upload ingestion endpoint.
+ *
+ * Usage — in your project's `src/app/api/upload/route.ts`:
+ *
+ *   import { createUploadHandler } from '@rag/ai-accelerator/handlers';
+ *   export const POST = createUploadHandler(myConfig);
+ */
+export function createUploadHandler(config: RagConfig, adapters?: CustomAdapters) {
+  let pipeline: RAGPipeline | null = null;
+
+  function getPipeline(): RAGPipeline {
+    if (!pipeline) pipeline = new RAGPipeline(config, adapters);
+    return pipeline;
+  }
+
+  return async function POST(req: NextRequest) {
+    try {
+      const formData = await req.formData();
+      const files = formData.getAll('files') as File[];
+      const namespace = (formData.get('namespace') as string) || undefined;
+
+      if (!files || files.length === 0) {
+        return NextResponse.json({ error: 'No files provided' }, { status: 400 });
+      }
+
+      const documents = await Promise.all(
+        files.map(async (file) => {
+          const content = await DocumentParser.parse(file, file.name, file.type);
+          return {
+            docId: file.name,
+            content,
+            metadata: {
+              fileName: file.name,
+              fileSize: file.size,
+              fileType: file.type,
+              uploadedAt: new Date().toISOString(),
+            },
+          };
+        })
+      );
+
+      const rag = getPipeline();
+      const results = await rag.ingest(documents, namespace);
+      const totalChunks = results.reduce((sum, r) => sum + r.chunksIngested, 0);
+
+      return NextResponse.json({
+        message: 'Upload successful',
+        filesProcessed: files.length,
+        totalChunks,
+        results,
+      });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : 'Upload failed';
+      return NextResponse.json({ error: message }, { status: 500 });
+    }
+  };
+}

package/src/hooks/useHydrated.ts

@@ -0,0 +1,13 @@
+'use client';
+
+import * as React from 'react';
+
+const emptySubscribe = () => () => {};
+
+export function useHydrated(): boolean {
+  return React.useSyncExternalStore(
+    emptySubscribe,
+    () => true,
+    () => false
+  );
+}

package/src/hooks/useRagChat.ts

@@ -0,0 +1,167 @@
+'use client';
+
+/**
+ * useRagChat — headless React hook for the RAG chat pipeline.
+ *
+ * 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.
+ *
+ * Usage:
+ *   const { messages, send, clear, isLoading, error } = useRagChat('my-project');
+ *
+ * Then build any UI on top of the returned state.
+ */
+
+import { useState, useCallback, useRef, useEffect } from 'react';
+import axios from 'axios';
+import { VectorMatch } from '@/vectordb/IVectorDB';
+import { useStoredMessages } from './useStoredMessages';
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export type MessageRole = 'user' | 'assistant';
+
+export interface RagMessage {
+  id: string;
+  role: MessageRole;
+  content: string;
+  /** Retrieved source chunks (assistant messages only) */
+  sources?: VectorMatch[];
+  /** ISO timestamp */
+  createdAt: string;
+}
+
+export interface UseRagChatOptions {
+  /** Override the chat API endpoint (default: /api/chat) */
+  apiUrl?: string;
+  /** Override project namespace */
+  namespace?: string;
+  /** Persist chat history to localStorage (default: true) */
+  persist?: boolean;
+  /** Called after each successful assistant reply */
+  onReply?: (message: RagMessage) => void;
+  /** Called on error */
+  onError?: (error: string) => void;
+}
+
+export interface UseRagChatReturn {
+  /** All messages in the current conversation */
+  messages: RagMessage[];
+  /** Whether a response is in flight */
+  isLoading: boolean;
+  /** Current error message, or null */
+  error: string | null;
+  /** Send a user message */
+  send: (text: string) => Promise<void>;
+  /** Clear the conversation (and localStorage if persist=true) */
+  clear: () => void;
+  /** Retry the last failed send */
+  retry: () => Promise<void>;
+  /** Programmatically set the conversation (e.g. to restore from a DB) */
+  setMessages: React.Dispatch<React.SetStateAction<RagMessage[]>>;
+}
+
+// ─── Hook ─────────────────────────────────────────────────────────────────────
+
+export function useRagChat(
+  projectId: string,
+  options: UseRagChatOptions = {}
+): UseRagChatReturn {
+  const {
+    apiUrl = '/api/chat',
+    namespace,
+    persist = true,
+    onReply,
+    onError,
+  } = options;
+  const storageKey = `rag_chat_${projectId}`;
+
+  const [messages, setMessages] = useStoredMessages<RagMessage>(storageKey, persist);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const lastInputRef = useRef<string>('');
+  const messagesRef = useRef<RagMessage[]>(messages);
+
+  useEffect(() => {
+    messagesRef.current = messages;
+  }, [messages]);
+
+  // ── Core send function ────────────────────────────────────────────────────
+  const sendMessage = useCallback(
+    async (text: string, options?: { skipUserMessage?: boolean }) => {
+      const trimmed = text.trim();
+      if (!trimmed || isLoading) return;
+
+      lastInputRef.current = trimmed;
+
+      if (!options?.skipUserMessage) {
+        const userMessage: RagMessage = {
+          id: `user_${Date.now()}`,
+          role: 'user',
+          content: trimmed,
+          createdAt: new Date().toISOString(),
+        };
+
+        setMessages((prev) => [...prev, userMessage]);
+      }
+      setError(null);
+      setIsLoading(true);
+
+      try {
+        const history = messagesRef.current.map(({ role, content }) => ({ role, content }));
+
+        const { data } = await axios.post(apiUrl, {
+          message: trimmed,
+          history,
+          namespace: namespace ?? projectId,
+        });
+
+        const assistantMessage: RagMessage = {
+          id: `assistant_${Date.now()}`,
+          role: 'assistant',
+          content: data.reply,
+          sources: data.sources,
+          createdAt: new Date().toISOString(),
+        };
+
+        setMessages((prev) => [...prev, assistantMessage]);
+        onReply?.(assistantMessage);
+      } catch (err) {
+        const msg = axios.isAxiosError(err)
+          ? (err.response?.data?.error ?? err.message)
+          : 'Something went wrong. Please try again.';
+        setError(msg);
+        onError?.(msg);
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [apiUrl, isLoading, namespace, onError, onReply, projectId, setMessages]
+  );
+
+  const clear = useCallback(() => {
+    setMessages([]);
+    setError(null);
+    if (persist) localStorage.removeItem(storageKey);
+  }, [persist, setMessages, storageKey]);
+
+  const retry = useCallback(async () => {
+    if (lastInputRef.current) {
+      const latestMessage = messagesRef.current[messagesRef.current.length - 1];
+      await sendMessage(lastInputRef.current, {
+        skipUserMessage: latestMessage?.role === 'user' && latestMessage.content === lastInputRef.current,
+      });
+    }
+  }, [sendMessage]);
+
+  return {
+    messages,
+    isLoading,
+    error,
+    send: sendMessage,
+    clear,
+    retry,
+    setMessages,
+  };
+}

package/src/hooks/useStoredMessages.ts

@@ -0,0 +1,53 @@
+'use client';
+
+import * as React from 'react';
+
+export interface StoredMessage {
+  id: string;
+  role: 'user' | 'assistant';
+  content: string;
+  createdAt?: string;
+  sources?: unknown;
+}
+
+function readStoredMessages(storageKey: string): StoredMessage[] {
+  if (typeof window === 'undefined') {
+    return [];
+  }
+
+  const saved = window.localStorage.getItem(storageKey);
+  if (!saved) {
+    return [];
+  }
+
+  try {
+    const parsed = JSON.parse(saved);
+    return Array.isArray(parsed) ? (parsed as StoredMessage[]) : [];
+  } catch {
+    return [];
+  }
+}
+
+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[]) : []
+  ));
+
+  React.useEffect(() => {
+    if (!persist || typeof window === 'undefined') {
+      return;
+    }
+
+    if (messages.length === 0) {
+      window.localStorage.removeItem(storageKey);
+      return;
+    }
+
+    window.localStorage.setItem(storageKey, JSON.stringify(messages));
+  }, [messages, persist, storageKey]);
+
+  return [messages, setMessages];
+}

package/src/index.ts

@@ -0,0 +1,27 @@
+/**
+ * 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.
+ *
+ * Usage:
+ *   import { ChatWidget, ConfigProvider, useRagChat } from '@rag/ai-accelerator';
+ */
+
+// ── React Components ─────────────────────────────────────────
+export { ChatWidget } from './components/ChatWidget';
+export { ChatWindow } from './components/ChatWindow';
+export { MessageBubble } from './components/MessageBubble';
+export { SourceCard } from './components/SourceCard';
+export { ConfigProvider, useConfig } from './components/ConfigProvider';
+
+// ── Headless Hooks ────────────────────────────────────────────
+export { useRagChat } from './hooks/useRagChat';
+
+// ── Types (Interfaces/Types only, no Node.js deps) ─────────────
+export type { RagConfig, VectorDBConfig, LLMConfig, EmbeddingConfig, UIConfig, RAGConfig } from './config/RagConfig';
+export type { IVectorDB, VectorMatch, UpsertDocument } from './vectordb/IVectorDB';
+export type { ILLMProvider, ChatMessage, ChatOptions, EmbedOptions } from './llm/ILLMProvider';
+export type { IngestDocument, ChatResponse } from './rag/RAGPipeline';
+export type { Chunk, ChunkOptions } from './rag/DocumentChunker';
+export type { ClientConfig } from './components/ConfigProvider';
+export type { RagMessage, UseRagChatOptions, UseRagChatReturn } from './hooks/useRagChat';
+