From 10441ba3347ddfded86af4766371da89ce6fe650 Mon Sep 17 00:00:00 2001
From: webdevcody <webdevcody@gmail.com>
Date: Thu, 8 Jan 2026 17:14:15 -0500
Subject: [PATCH 1/3] refactor vector search to chat widget

---
 src/fn/rag-chat.ts                            |  36 ++++
 src/hooks/use-rag-chat.ts                     | 134 +++++++++++++
 src/lib/openai-chat.ts                        | 146 ++++++++++++++
 src/routes/admin/vector-search.tsx            | 189 +++---------------
 .../-components/chat-container.tsx            |  75 +++++++
 .../vector-search/-components/chat-input.tsx  |  63 ++++++
 .../-components/chat-message.tsx              |  57 ++++++
 .../-components/source-videos-panel.tsx       |  96 +++++++++
 src/use-cases/rag-chat.ts                     | 178 +++++++++++++++++
 9 files changed, 818 insertions(+), 156 deletions(-)
 create mode 100644 src/fn/rag-chat.ts
 create mode 100644 src/hooks/use-rag-chat.ts
 create mode 100644 src/lib/openai-chat.ts
 create mode 100644 src/routes/admin/vector-search/-components/chat-container.tsx
 create mode 100644 src/routes/admin/vector-search/-components/chat-input.tsx
 create mode 100644 src/routes/admin/vector-search/-components/chat-message.tsx
 create mode 100644 src/routes/admin/vector-search/-components/source-videos-panel.tsx
 create mode 100644 src/use-cases/rag-chat.ts

diff --git a/src/fn/rag-chat.ts b/src/fn/rag-chat.ts
new file mode 100644
index 00000000..5ecf14a5
--- /dev/null
+++ b/src/fn/rag-chat.ts
@@ -0,0 +1,36 @@
+import { createServerFn } from "@tanstack/react-start";
+import { adminMiddleware } from "~/lib/auth";
+import { z } from "zod";
+import { ragChatUseCase } from "~/use-cases/rag-chat";
+
+const videoSourceSchema = z.object({
+  segmentId: z.number(),
+  segmentTitle: z.string(),
+  segmentSlug: z.string(),
+  moduleTitle: z.string(),
+  chunkText: z.string(),
+  similarity: z.number(),
+});
+
+const conversationMessageSchema = z.object({
+  id: z.string(),
+  role: z.enum(["user", "assistant"]),
+  content: z.string(),
+  timestamp: z.string(),
+  sources: z.array(videoSourceSchema).optional(),
+});
+
+const ragChatInputSchema = z.object({
+  userMessage: z.string().min(1, "Message cannot be empty").max(2000, "Message too long"),
+  conversationHistory: z.array(conversationMessageSchema).max(20, "Too many messages in history"),
+});
+
+export const ragChatFn = createServerFn({ method: "POST" })
+  .middleware([adminMiddleware])
+  .inputValidator(ragChatInputSchema)
+  .handler(async ({ data }) => {
+    return ragChatUseCase({
+      userMessage: data.userMessage,
+      conversationHistory: data.conversationHistory,
+    });
+  });
diff --git a/src/hooks/use-rag-chat.ts b/src/hooks/use-rag-chat.ts
new file mode 100644
index 00000000..1bfcb61e
--- /dev/null
+++ b/src/hooks/use-rag-chat.ts
@@ -0,0 +1,134 @@
+import { useState, useCallback, useEffect } from "react";
+import { useMutation } from "@tanstack/react-query";
+import { ragChatFn } from "~/fn/rag-chat";
+import type { VideoSource, ConversationMessage } from "~/use-cases/rag-chat";
+
+export type { VideoSource, ConversationMessage };
+
+const STORAGE_KEY = "rag-chat-history";
+const SOURCES_STORAGE_KEY = "rag-chat-sources";
+
+function loadFromStorage<T>(key: string, fallback: T): T {
+  if (typeof window === "undefined") return fallback;
+  try {
+    const stored = sessionStorage.getItem(key);
+    if (stored) {
+      return JSON.parse(stored) as T;
+    }
+  } catch (error) {
+    console.error(`[RAG Chat] Failed to load from sessionStorage:`, error);
+  }
+  return fallback;
+}
+
+function saveToStorage<T>(key: string, value: T): void {
+  if (typeof window === "undefined") return;
+  try {
+    sessionStorage.setItem(key, JSON.stringify(value));
+  } catch (error) {
+    console.error(`[RAG Chat] Failed to save to sessionStorage:`, error);
+  }
+}
+
+function clearStorage(): void {
+  if (typeof window === "undefined") return;
+  try {
+    sessionStorage.removeItem(STORAGE_KEY);
+    sessionStorage.removeItem(SOURCES_STORAGE_KEY);
+  } catch (error) {
+    console.error(`[RAG Chat] Failed to clear sessionStorage:`, error);
+  }
+}
+
+export interface UseRagChatReturn {
+  messages: ConversationMessage[];
+  isLoading: boolean;
+  error: Error | null;
+  sendMessage: (content: string) => Promise<void>;
+  clearChat: () => void;
+  currentSources: VideoSource[];
+}
+
+export function useRagChat(): UseRagChatReturn {
+  const [messages, setMessages] = useState<ConversationMessage[]>(() =>
+    loadFromStorage<ConversationMessage[]>(STORAGE_KEY, [])
+  );
+  const [currentSources, setCurrentSources] = useState<VideoSource[]>(() =>
+    loadFromStorage<VideoSource[]>(SOURCES_STORAGE_KEY, [])
+  );
+
+  useEffect(() => {
+    saveToStorage(STORAGE_KEY, messages);
+  }, [messages]);
+
+  useEffect(() => {
+    saveToStorage(SOURCES_STORAGE_KEY, currentSources);
+  }, [currentSources]);
+
+  const mutation = useMutation({
+    mutationFn: async (userMessage: string) => {
+      const result = await ragChatFn({
+        data: {
+          userMessage,
+          conversationHistory: messages,
+        },
+      });
+      return result;
+    },
+    onMutate: (userMessage) => {
+      const userMsg: ConversationMessage = {
+        id: crypto.randomUUID(),
+        role: "user",
+        content: userMessage,
+        timestamp: new Date().toISOString(),
+      };
+      setMessages((prev) => [...prev, userMsg]);
+      setCurrentSources([]);
+    },
+    onSuccess: (result) => {
+      const assistantMsg: ConversationMessage = {
+        id: crypto.randomUUID(),
+        role: "assistant",
+        content: result.response,
+        timestamp: new Date().toISOString(),
+        sources: result.sources,
+      };
+      setMessages((prev) => [...prev, assistantMsg]);
+      setCurrentSources(result.sources);
+    },
+    onError: (error) => {
+      setMessages((prev) => {
+        const lastMessage = prev[prev.length - 1];
+        if (lastMessage?.role === "user") {
+          return prev.slice(0, -1);
+        }
+        return prev;
+      });
+      console.error("[RAG Chat] Error:", error);
+    },
+  });
+
+  const sendMessage = useCallback(
+    async (content: string) => {
+      if (!content.trim() || mutation.isPending) return;
+      await mutation.mutateAsync(content.trim());
+    },
+    [mutation]
+  );
+
+  const clearChat = useCallback(() => {
+    setMessages([]);
+    setCurrentSources([]);
+    clearStorage();
+    mutation.reset();
+  }, [mutation]);
+
+  return {
+    messages,
+    isLoading: mutation.isPending,
+    error: mutation.error,
+    sendMessage,
+    clearChat,
+    currentSources,
+  };
+}
diff --git a/src/lib/openai-chat.ts b/src/lib/openai-chat.ts
new file mode 100644
index 00000000..abb268d5
--- /dev/null
+++ b/src/lib/openai-chat.ts
@@ -0,0 +1,146 @@
+import OpenAI from "openai";
+import { env } from "~/utils/env";
+
+const openai = new OpenAI({
+  apiKey: env.OPENAI_API_KEY,
+});
+
+const CHAT_MODEL = "gpt-4o";
+const MAX_RETRIES = 3;
+const INITIAL_RETRY_DELAY_MS = 1000;
+
+export interface ChatMessage {
+  role: "system" | "user" | "assistant";
+  content: string;
+}
+
+export interface ChatCompletionOptions {
+  model?: "gpt-4o-mini" | "gpt-4o";
+  temperature?: number;
+  maxTokens?: number;
+}
+
+export interface ChatCompletionResult {
+  content: string;
+  usage?: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  };
+}
+
+class ChatCompletionError extends Error {
+  constructor(
+    message: string,
+    public readonly code?: string,
+    public readonly status?: number,
+    public readonly context?: Record<string, unknown>
+  ) {
+    super(message);
+    this.name = "ChatCompletionError";
+  }
+}
+
+async function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function withRetry<T>(
+  fn: () => Promise<T>,
+  context: Record<string, unknown>
+): Promise<T> {
+  let lastError: Error | undefined;
+
+  for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+
+      const isRetryable =
+        error instanceof OpenAI.APIError &&
+        (error.status === 429 ||
+          error.status === 500 ||
+          error.status === 502 ||
+          error.status === 503);
+
+      if (!isRetryable || attempt === MAX_RETRIES - 1) {
+        break;
+      }
+
+      const delay = INITIAL_RETRY_DELAY_MS * Math.pow(2, attempt);
+      console.warn(
+        `Chat completion API call failed (attempt ${attempt + 1}/${MAX_RETRIES}), retrying in ${delay}ms...`,
+        { error: lastError.message, ...context }
+      );
+      await sleep(delay);
+    }
+  }
+
+  if (lastError instanceof OpenAI.APIError) {
+    throw new ChatCompletionError(
+      `OpenAI API error: ${lastError.message}`,
+      lastError.code ?? undefined,
+      lastError.status,
+      context
+    );
+  }
+
+  throw new ChatCompletionError(
+    `Chat completion failed: ${lastError?.message ?? "Unknown error"}`,
+    undefined,
+    undefined,
+    context
+  );
+}
+
+export async function createChatCompletion(
+  messages: ChatMessage[],
+  options?: ChatCompletionOptions
+): Promise<ChatCompletionResult> {
+  if (!messages || !Array.isArray(messages) || messages.length === 0) {
+    throw new ChatCompletionError(
+      "Messages must be a non-empty array",
+      undefined,
+      undefined,
+      { messagesLength: messages?.length ?? 0 }
+    );
+  }
+
+  const model = options?.model ?? CHAT_MODEL;
+  const temperature = options?.temperature ?? 0.7;
+  const maxTokens = options?.maxTokens ?? 2048;
+
+  return withRetry(
+    async () => {
+      const response = await openai.chat.completions.create({
+        model,
+        messages,
+        temperature,
+        max_tokens: maxTokens,
+      });
+
+      const choice = response.choices[0];
+      if (!choice?.message?.content) {
+        throw new ChatCompletionError(
+          "Invalid API response: missing message content",
+          undefined,
+          undefined,
+          { choicesLength: response.choices.length }
+        );
+      }
+
+      return {
+        content: choice.message.content,
+        usage: response.usage
+          ? {
+              promptTokens: response.usage.prompt_tokens,
+              completionTokens: response.usage.completion_tokens,
+              totalTokens: response.usage.total_tokens,
+            }
+          : undefined,
+      };
+    },
+    { model, messagesCount: messages.length }
+  );
+}
diff --git a/src/routes/admin/vector-search.tsx b/src/routes/admin/vector-search.tsx
index e792f3b1..adb338d2 100644
--- a/src/routes/admin/vector-search.tsx
+++ b/src/routes/admin/vector-search.tsx
@@ -1,176 +1,53 @@
-import { createFileRoute, Link, useNavigate } from "@tanstack/react-router";
-import { useState, useEffect } from "react";
-import { useQuery } from "@tanstack/react-query";
-import { Search, Loader2, Video, BookOpen } from "lucide-react";
-import { Input } from "~/components/ui/input";
+import { useState } from "react";
+import { createFileRoute } from "@tanstack/react-router";
+import { Trash2 } from "lucide-react";
 import { Button } from "~/components/ui/button";
-import {
-  Card,
-  CardContent,
-  CardDescription,
-  CardHeader,
-  CardTitle,
-} from "~/components/ui/card";
-import { Badge } from "~/components/ui/badge";
+import { Card } from "~/components/ui/card";
 import { PageHeader } from "./-components/page-header";
 import { Page } from "./-components/page";
-import { searchTranscriptsFn } from "~/fn/vector-search";
 import { assertIsAdminFn } from "~/fn/auth";
-import { z } from "zod";
-
-const searchParamsSchema = z.object({
-  q: z.string().optional(),
-});
+import { useRagChat } from "~/hooks/use-rag-chat";
+import { ChatContainer } from "./vector-search/-components/chat-container";
+import { ChatInput } from "./vector-search/-components/chat-input";
+import { SourceVideosPanel } from "./vector-search/-components/source-videos-panel";
 
 export const Route = createFileRoute("/admin/vector-search")({
   beforeLoad: () => assertIsAdminFn(),
-  component: VectorSearchPage,
-  validateSearch: searchParamsSchema,
+  component: CourseAssistantPage,
 });
 
-function VectorSearchPage() {
-  const { q: searchTerm = "" } = Route.useSearch();
-  const navigate = useNavigate({ from: Route.fullPath });
-  const [query, setQuery] = useState(searchTerm);
-
-  useEffect(() => {
-    setQuery(searchTerm);
-  }, [searchTerm]);
-
-  const { data, isLoading, isFetching } = useQuery({
-    queryKey: ["admin", "vector-search", searchTerm],
-    queryFn: () =>
-      searchTranscriptsFn({ data: { query: searchTerm, limit: 20 } }),
-    enabled: searchTerm.length > 0,
-  });
-
-  const handleSearch = () => {
-    if (query.trim()) {
-      navigate({ search: { q: query.trim() } });
-    }
-  };
-
-  const handleKeyDown = (e: React.KeyboardEvent) => {
-    if (e.key === "Enter") {
-      handleSearch();
-    }
-  };
+function CourseAssistantPage() {
+  const [inputValue, setInputValue] = useState("");
+  const { messages, isLoading, sendMessage, clearChat, currentSources } =
+    useRagChat();
 
   return (
     <Page>
       <PageHeader
-        title="Vector Search"
-        highlightedWord="Search"
-        description="Search course transcripts using semantic similarity. Find videos that discuss specific topics."
+        title="Course Assistant"
+        highlightedWord="Assistant"
+        description="Ask questions about course content. The AI searches video transcripts to provide informed answers."
+        actions={
+          messages.length > 0 ? (
+            <Button variant="outline" onClick={clearChat}>
+              <Trash2 className="h-4 w-4 mr-2" />
+              Clear Chat
+            </Button>
+          ) : null
+        }
       />
 
-      <div className="flex gap-2 mb-8 items-center">
-        <div className="relative flex-1 max-w-2xl">
-          <Search className="absolute left-4 top-1/2 -translate-y-1/2 h-5 w-5 text-muted-foreground" />
-          <Input
-            placeholder="Search transcripts..."
-            value={query}
-            onChange={(e) => setQuery(e.target.value)}
-            onKeyDown={handleKeyDown}
-            className="pl-12 h-12 text-lg"
-          />
+      <div className="grid grid-cols-1 lg:grid-cols-3 gap-6">
+        <div className="lg:col-span-2">
+          <Card className="flex flex-col">
+            <ChatContainer messages={messages} isLoading={isLoading} onSelectPrompt={setInputValue} />
+            <ChatInput onSend={sendMessage} isLoading={isLoading} value={inputValue} onChange={setInputValue} />
+          </Card>
         </div>
-        <Button
-          onClick={handleSearch}
-          disabled={isLoading || !query.trim()}
-          size="icon"
-          className="h-12 w-12 shrink-0"
-        >
-          {isFetching ? (
-            <Loader2 className="h-5 w-5 animate-spin" />
-          ) : (
-            <Search className="h-5 w-5" />
-          )}
-        </Button>
-      </div>
-
-      {searchTerm && (
-        <div className="mb-4 text-sm text-muted-foreground">
-          Showing results for: <span className="font-medium">{searchTerm}</span>
+        <div className="lg:col-span-1">
+          <SourceVideosPanel sources={currentSources} />
         </div>
-      )}
-
-      {isLoading && (
-        <div className="flex items-center justify-center h-64">
-          <Loader2 className="h-8 w-8 animate-spin text-muted-foreground" />
-        </div>
-      )}
-
-      {data && data.length > 0 && (
-        <div className="space-y-4">
-          {data.map((result, index) => (
-            <Card key={`${result.id}-${index}`}>
-              <CardHeader className="pb-2">
-                <div className="flex items-start justify-between">
-                  <div className="flex-1">
-                    <CardTitle className="text-lg flex items-center gap-2">
-                      <Video className="h-4 w-4 text-theme-500" />
-                      {result.segmentTitle}
-                    </CardTitle>
-                    <CardDescription className="flex items-center gap-2 mt-1">
-                      <BookOpen className="h-3 w-3" />
-                      {result.moduleTitle}
-                    </CardDescription>
-                  </div>
-                  <Badge
-                    variant={
-                      result.similarity > 0.8
-                        ? "default"
-                        : result.similarity > 0.6
-                          ? "secondary"
-                          : "outline"
-                    }
-                  >
-                    {(result.similarity * 100).toFixed(1)}% match
-                  </Badge>
-                </div>
-              </CardHeader>
-              <CardContent>
-                <p className="text-sm text-muted-foreground mb-4 line-clamp-3">
-                  {result.chunkText}
-                </p>
-                <Link
-                  to="/learn/$slug"
-                  params={{ slug: result.segmentSlug }}
-                  className="text-sm text-theme-500 hover:text-theme-600 hover:underline inline-flex items-center gap-1"
-                >
-                  Go to video →
-                </Link>
-              </CardContent>
-            </Card>
-          ))}
-        </div>
-      )}
-
-      {data && data.length === 0 && searchTerm && (
-        <div className="flex flex-col items-center justify-center h-64 text-center">
-          <Search className="h-12 w-12 text-muted-foreground mb-4" />
-          <h3 className="text-lg font-semibold mb-2">No results found</h3>
-          <p className="text-sm text-muted-foreground max-w-md">
-            No transcripts matched your search for "{searchTerm}". Try a
-            different query or check that transcripts have been vectorized.
-          </p>
-        </div>
-      )}
-
-      {!searchTerm && (
-        <div className="flex flex-col items-center justify-center h-64 text-center">
-          <Search className="h-12 w-12 text-muted-foreground mb-4" />
-          <h3 className="text-lg font-semibold mb-2">
-            Search course transcripts
-          </h3>
-          <p className="text-sm text-muted-foreground max-w-md">
-            Enter a topic or keyword to find videos that discuss it. This uses
-            semantic search to find relevant content even if the exact words
-            don't match.
-          </p>
-        </div>
-      )}
+      </div>
     </Page>
   );
 }
diff --git a/src/routes/admin/vector-search/-components/chat-container.tsx b/src/routes/admin/vector-search/-components/chat-container.tsx
new file mode 100644
index 00000000..7126f74d
--- /dev/null
+++ b/src/routes/admin/vector-search/-components/chat-container.tsx
@@ -0,0 +1,75 @@
+import { useEffect, useRef } from "react";
+import { MessageSquare, Loader2 } from "lucide-react";
+import { ChatMessage } from "./chat-message";
+import type { ConversationMessage } from "~/hooks/use-rag-chat";
+
+interface ChatContainerProps {
+  messages: ConversationMessage[];
+  isLoading: boolean;
+  onSelectPrompt: (prompt: string) => void;
+}
+
+const EXAMPLE_PROMPTS = [
+  "What topics are covered in this course?",
+  "How do I get started with the first module?",
+  "Can you explain the main concepts?",
+  "What prerequisites do I need?",
+];
+
+export function ChatContainer({ messages, isLoading, onSelectPrompt }: ChatContainerProps) {
+  const scrollRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (scrollRef.current) {
+      scrollRef.current.scrollTop = scrollRef.current.scrollHeight;
+    }
+  }, [messages, isLoading]);
+
+  if (messages.length === 0) {
+    return (
+      <div className="flex h-[500px] flex-col items-center justify-center text-center p-8">
+        <MessageSquare className="h-12 w-12 text-muted-foreground mb-4" />
+        <h3 className="text-lg font-semibold mb-2">Course Assistant</h3>
+        <p className="text-sm text-muted-foreground max-w-md mb-6">
+          Ask questions about the course content. I'll search through video
+          transcripts to find relevant information and help answer your
+          questions.
+        </p>
+        <div className="flex flex-wrap gap-2 justify-center">
+          {EXAMPLE_PROMPTS.map((prompt) => (
+            <button
+              key={prompt}
+              className="text-xs px-3 py-1.5 rounded-full bg-muted hover:bg-muted/80 text-muted-foreground transition-colors"
+              onClick={() => onSelectPrompt(prompt)}
+            >
+              {prompt}
+            </button>
+          ))}
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div
+      ref={scrollRef}
+      className="flex h-[500px] flex-col gap-4 overflow-y-auto p-4"
+    >
+      {messages.map((message) => (
+        <ChatMessage key={message.id} message={message} />
+      ))}
+      {isLoading && (
+        <div className="flex gap-3">
+          <div className="flex h-8 w-8 shrink-0 items-center justify-center rounded-full bg-muted">
+            <Loader2 className="h-4 w-4 animate-spin" />
+          </div>
+          <div className="flex items-center rounded-lg bg-muted px-4 py-3">
+            <span className="text-sm text-muted-foreground">
+              Searching transcripts and generating response...
+            </span>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/src/routes/admin/vector-search/-components/chat-input.tsx b/src/routes/admin/vector-search/-components/chat-input.tsx
new file mode 100644
index 00000000..3f47657a
--- /dev/null
+++ b/src/routes/admin/vector-search/-components/chat-input.tsx
@@ -0,0 +1,63 @@
+import { useRef, useEffect, KeyboardEvent } from "react";
+import { Send, Loader2 } from "lucide-react";
+import { Button } from "~/components/ui/button";
+import { Textarea } from "~/components/ui/textarea";
+
+interface ChatInputProps {
+  onSend: (message: string) => void;
+  isLoading: boolean;
+  value: string;
+  onChange: (value: string) => void;
+}
+
+export function ChatInput({ onSend, isLoading, value, onChange }: ChatInputProps) {
+  const textareaRef = useRef<HTMLTextAreaElement>(null);
+
+  useEffect(() => {
+    if (textareaRef.current) {
+      textareaRef.current.style.height = "auto";
+      textareaRef.current.style.height = `${Math.min(textareaRef.current.scrollHeight, 150)}px`;
+    }
+  }, [value]);
+
+  const handleSubmit = () => {
+    if (!value.trim() || isLoading) return;
+    onSend(value.trim());
+    onChange("");
+  };
+
+  const handleKeyDown = (e: KeyboardEvent<HTMLTextAreaElement>) => {
+    if (e.key === "Enter" && !e.shiftKey) {
+      e.preventDefault();
+      handleSubmit();
+    }
+  };
+
+  return (
+    <div className="flex gap-2 border-t p-4">
+      <Textarea
+        ref={textareaRef}
+        data-chat-input
+        placeholder="Ask a question about the course content..."
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        onKeyDown={handleKeyDown}
+        disabled={isLoading}
+        className="min-h-[44px] max-h-[150px] resize-none"
+        rows={1}
+      />
+      <Button
+        onClick={handleSubmit}
+        disabled={!value.trim() || isLoading}
+        size="icon"
+        className="h-11 w-11 shrink-0"
+      >
+        {isLoading ? (
+          <Loader2 className="h-4 w-4 animate-spin" />
+        ) : (
+          <Send className="h-4 w-4" />
+        )}
+      </Button>
+    </div>
+  );
+}
diff --git a/src/routes/admin/vector-search/-components/chat-message.tsx b/src/routes/admin/vector-search/-components/chat-message.tsx
new file mode 100644
index 00000000..3886bb06
--- /dev/null
+++ b/src/routes/admin/vector-search/-components/chat-message.tsx
@@ -0,0 +1,57 @@
+import { User, Bot } from "lucide-react";
+import Markdown from "react-markdown";
+import { Badge } from "~/components/ui/badge";
+import type { ConversationMessage } from "~/hooks/use-rag-chat";
+
+interface ChatMessageProps {
+  message: ConversationMessage;
+}
+
+export function ChatMessage({ message }: ChatMessageProps) {
+  const isUser = message.role === "user";
+
+  return (
+    <div className={`flex gap-3 ${isUser ? "flex-row-reverse" : "flex-row"}`}>
+      <div
+        className={`flex h-8 w-8 shrink-0 items-center justify-center rounded-full ${
+          isUser ? "bg-theme-500 text-white" : "bg-muted"
+        }`}
+      >
+        {isUser ? <User className="h-4 w-4" /> : <Bot className="h-4 w-4" />}
+      </div>
+      <div
+        className={`flex max-w-[80%] flex-col gap-2 rounded-lg px-4 py-3 ${
+          isUser
+            ? "bg-theme-500 text-white"
+            : "bg-muted"
+        }`}
+      >
+        <div className={`prose prose-sm max-w-none ${isUser ? "prose-invert" : "dark:prose-invert"}`}>
+          {isUser ? (
+            <p className="m-0">{message.content}</p>
+          ) : (
+            <Markdown>{message.content}</Markdown>
+          )}
+        </div>
+        {message.sources && message.sources.length > 0 && (
+          <div className="flex flex-wrap gap-1 pt-2 border-t border-border/50">
+            {message.sources.slice(0, 3).map((source) => (
+              <Badge
+                key={source.segmentId}
+                variant="secondary"
+                className="text-xs"
+              >
+                {source.segmentTitle}
+              </Badge>
+            ))}
+            {message.sources.length > 3 && (
+              <Badge variant="outline" className="text-xs">
+                +{message.sources.length - 3} more
+              </Badge>
+            )}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
diff --git a/src/routes/admin/vector-search/-components/source-videos-panel.tsx b/src/routes/admin/vector-search/-components/source-videos-panel.tsx
new file mode 100644
index 00000000..027a042c
--- /dev/null
+++ b/src/routes/admin/vector-search/-components/source-videos-panel.tsx
@@ -0,0 +1,96 @@
+import { Link } from "@tanstack/react-router";
+import { Video, BookOpen, ExternalLink } from "lucide-react";
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "~/components/ui/card";
+import { Badge } from "~/components/ui/badge";
+import type { VideoSource } from "~/hooks/use-rag-chat";
+
+interface SourceVideosPanelProps {
+  sources: VideoSource[];
+}
+
+export function SourceVideosPanel({ sources }: SourceVideosPanelProps) {
+  if (sources.length === 0) {
+    return (
+      <Card>
+        <CardHeader>
+          <CardTitle className="text-base">Source Videos</CardTitle>
+          <CardDescription>
+            Relevant videos will appear here as you chat
+          </CardDescription>
+        </CardHeader>
+        <CardContent>
+          <div className="flex flex-col items-center justify-center py-8 text-center">
+            <Video className="h-8 w-8 text-muted-foreground mb-2" />
+            <p className="text-sm text-muted-foreground">
+              Ask a question to see related videos
+            </p>
+          </div>
+        </CardContent>
+      </Card>
+    );
+  }
+
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle className="text-base">Source Videos</CardTitle>
+        <CardDescription>
+          {sources.length} video{sources.length !== 1 ? "s" : ""} found relevant
+          to your question
+        </CardDescription>
+      </CardHeader>
+      <CardContent className="space-y-3">
+        {sources.map((source) => (
+          <div
+            key={source.segmentId}
+            className="rounded-lg border p-3 space-y-2"
+          >
+            <div className="flex items-start justify-between gap-2">
+              <div className="flex-1 min-w-0">
+                <div className="flex items-center gap-2 mb-1">
+                  <Video className="h-3.5 w-3.5 text-theme-500 shrink-0" />
+                  <span className="text-sm font-medium truncate">
+                    {source.segmentTitle}
+                  </span>
+                </div>
+                <div className="flex items-center gap-2 text-xs text-muted-foreground">
+                  <BookOpen className="h-3 w-3 shrink-0" />
+                  <span className="truncate">{source.moduleTitle}</span>
+                </div>
+              </div>
+              <Badge
+                variant={
+                  source.similarity > 0.8
+                    ? "default"
+                    : source.similarity > 0.6
+                      ? "secondary"
+                      : "outline"
+                }
+                className="shrink-0"
+              >
+                {(source.similarity * 100).toFixed(0)}%
+              </Badge>
+            </div>
+            <p className="text-xs text-muted-foreground line-clamp-2">
+              {source.chunkText}
+            </p>
+            <Link
+              to="/learn/$slug"
+              params={{ slug: source.segmentSlug }}
+              className="inline-flex items-center gap-1 text-xs text-theme-500 hover:text-theme-600 hover:underline"
+            >
+              Go to video
+              <ExternalLink className="h-3 w-3" />
+            </Link>
+          </div>
+        ))}
+      </CardContent>
+    </Card>
+  );
+}
diff --git a/src/use-cases/rag-chat.ts b/src/use-cases/rag-chat.ts
new file mode 100644
index 00000000..1b592cef
--- /dev/null
+++ b/src/use-cases/rag-chat.ts
@@ -0,0 +1,178 @@
+import { generateEmbedding } from "~/lib/openai";
+import { createChatCompletion, type ChatMessage } from "~/lib/openai-chat";
+import { searchByEmbedding, type SearchResult } from "~/data-access/transcript-chunks";
+
+const CONTEXT_CHUNK_LIMIT = 10;
+const MAX_HISTORY_MESSAGES = 10;
+
+export interface VideoSource {
+  segmentId: number;
+  segmentTitle: string;
+  segmentSlug: string;
+  moduleTitle: string;
+  chunkText: string;
+  similarity: number;
+}
+
+export interface ConversationMessage {
+  id: string;
+  role: "user" | "assistant";
+  content: string;
+  timestamp: string;
+  sources?: VideoSource[];
+}
+
+export interface RagChatInput {
+  userMessage: string;
+  conversationHistory: ConversationMessage[];
+}
+
+export interface RagChatResult {
+  response: string;
+  sources: VideoSource[];
+}
+
+const SYSTEM_PROMPT = `You are a helpful course assistant for an online learning platform. Your role is to answer questions about the course content based on the provided transcript excerpts from video lessons.
+
+IMPORTANT GUIDELINES:
+1. Answer questions based on the provided context from video transcripts
+2. Each source includes a relevance percentage - use sources with higher relevance as primary references, but also consider lower-relevance sources if they contain useful information
+3. When referencing information, mention which video it comes from (e.g., "In the video about [topic]...")
+4. Be concise but thorough in your explanations
+5. If the context contains related information, share it even if it's not a perfect match to the question
+6. Only say you don't have information if the context truly contains nothing relevant to the question
+7. Format your responses using markdown for better readability:
+   - Use **bold** for emphasis
+   - Use bullet points for lists
+   - Use code blocks for any code snippets mentioned in transcripts
+
+Answer the user's question based on the context provided. If multiple videos discuss the topic, synthesize the information while crediting each source.`;
+
+function formatContextForPrompt(searchResults: SearchResult[]): string {
+  if (searchResults.length === 0) {
+    return "No relevant course content found for this query.";
+  }
+
+  return searchResults
+    .map((result, index) => {
+      return `[Source ${index + 1}]
+Video: "${result.segmentTitle}" (Module: ${result.moduleTitle})
+Relevance: ${(result.similarity * 100).toFixed(1)}%
+Content:
+${result.chunkText}`;
+    })
+    .join("\n\n---\n\n");
+}
+
+function searchResultsToSources(searchResults: SearchResult[]): VideoSource[] {
+  const uniqueSources = new Map<number, VideoSource>();
+
+  for (const result of searchResults) {
+    if (!uniqueSources.has(result.segmentId)) {
+      uniqueSources.set(result.segmentId, {
+        segmentId: result.segmentId,
+        segmentTitle: result.segmentTitle,
+        segmentSlug: result.segmentSlug,
+        moduleTitle: result.moduleTitle,
+        chunkText: result.chunkText,
+        similarity: result.similarity,
+      });
+    }
+  }
+
+  return Array.from(uniqueSources.values()).sort(
+    (a, b) => b.similarity - a.similarity
+  );
+}
+
+function buildMessages(
+  systemPrompt: string,
+  context: string,
+  userMessage: string,
+  conversationHistory: ConversationMessage[]
+): ChatMessage[] {
+  const messages: ChatMessage[] = [
+    {
+      role: "system",
+      content: systemPrompt,
+    },
+  ];
+
+  const recentHistory = conversationHistory.slice(-MAX_HISTORY_MESSAGES);
+  for (const msg of recentHistory) {
+    messages.push({
+      role: msg.role,
+      content: msg.content,
+    });
+  }
+
+  const userMessageWithContext = `CONTEXT FROM COURSE TRANSCRIPTS:
+---
+${context}
+---
+
+USER QUESTION: ${userMessage}`;
+
+  messages.push({
+    role: "user",
+    content: userMessageWithContext,
+  });
+
+  return messages;
+}
+
+export async function ragChatUseCase(input: RagChatInput): Promise<RagChatResult> {
+  const { userMessage, conversationHistory } = input;
+
+  console.log("[RAG Chat] Starting RAG chat", {
+    userMessageLength: userMessage.length,
+    historyLength: conversationHistory.length,
+  });
+
+  const startTime = Date.now();
+
+  console.log("[RAG Chat] Generating embedding for user message...");
+  const embedding = await generateEmbedding(userMessage);
+
+  console.log("[RAG Chat] Searching for relevant chunks...");
+  const searchResults = await searchByEmbedding(embedding, CONTEXT_CHUNK_LIMIT);
+
+  console.log("[RAG Chat] Found relevant chunks", {
+    totalResults: searchResults.length,
+    topSimilarity: searchResults[0]?.similarity ?? 0,
+    results: searchResults.map((r) => ({
+      title: r.segmentTitle,
+      similarity: r.similarity,
+    })),
+  });
+
+  const context = formatContextForPrompt(searchResults);
+  const sources = searchResultsToSources(searchResults);
+
+  const messages = buildMessages(
+    SYSTEM_PROMPT,
+    context,
+    userMessage,
+    conversationHistory
+  );
+
+  console.log("[RAG Chat] Calling chat completion...");
+  const completion = await createChatCompletion(messages, {
+    model: "gpt-4o",
+    temperature: 0.7,
+    maxTokens: 2048,
+  });
+
+  const durationMs = Date.now() - startTime;
+  console.log("[RAG Chat] Completed", {
+    durationMs,
+    responseLength: completion.content.length,
+    sourcesCount: sources.length,
+    usage: completion.usage,
+  });
+
+  return {
+    response: completion.content,
+    sources,
+  };
+}

From 4ea41685b06ca526901292ba52641d5607c575ca Mon Sep 17 00:00:00 2001
From: webdevcody <webdevcody@gmail.com>
Date: Thu, 8 Jan 2026 17:21:30 -0500
Subject: [PATCH 2/3] feat: Enhance message validation and state management in
 rag-chat

- Introduced a maximum message content length of 2000 characters for user messages and conversation history to prevent overflow.
- Updated the `ragChat` input schema to enforce the new content length restriction.
- Implemented a ref to manage conversation messages more effectively, ensuring the latest messages are used during API calls.
- Improved state management by synchronizing the messages reference with the current state, enhancing performance and reliability.
---
 src/fn/rag-chat.ts        | 15 ++++++++++++---
 src/hooks/use-rag-chat.ts | 15 ++++++++++++---
 2 files changed, 24 insertions(+), 6 deletions(-)

diff --git a/src/fn/rag-chat.ts b/src/fn/rag-chat.ts
index 5ecf14a5..759cb8cc 100644
--- a/src/fn/rag-chat.ts
+++ b/src/fn/rag-chat.ts
@@ -12,17 +12,26 @@ const videoSourceSchema = z.object({
   similarity: z.number(),
 });
 
+const MAX_MESSAGE_CONTENT_LENGTH = 2000;
+
 const conversationMessageSchema = z.object({
   id: z.string(),
   role: z.enum(["user", "assistant"]),
-  content: z.string(),
+  content: z
+    .string()
+    .max(MAX_MESSAGE_CONTENT_LENGTH, "Message content too long"),
   timestamp: z.string(),
   sources: z.array(videoSourceSchema).optional(),
 });
 
 const ragChatInputSchema = z.object({
-  userMessage: z.string().min(1, "Message cannot be empty").max(2000, "Message too long"),
-  conversationHistory: z.array(conversationMessageSchema).max(20, "Too many messages in history"),
+  userMessage: z
+    .string()
+    .min(1, "Message cannot be empty")
+    .max(MAX_MESSAGE_CONTENT_LENGTH, "Message too long"),
+  conversationHistory: z
+    .array(conversationMessageSchema)
+    .max(20, "Too many messages in history"),
 });
 
 export const ragChatFn = createServerFn({ method: "POST" })
diff --git a/src/hooks/use-rag-chat.ts b/src/hooks/use-rag-chat.ts
index 1bfcb61e..b63101f0 100644
--- a/src/hooks/use-rag-chat.ts
+++ b/src/hooks/use-rag-chat.ts
@@ -1,4 +1,4 @@
-import { useState, useCallback, useEffect } from "react";
+import { useState, useCallback, useEffect, useRef } from "react";
 import { useMutation } from "@tanstack/react-query";
 import { ragChatFn } from "~/fn/rag-chat";
 import type { VideoSource, ConversationMessage } from "~/use-cases/rag-chat";
@@ -56,6 +56,11 @@ export function useRagChat(): UseRagChatReturn {
   const [currentSources, setCurrentSources] = useState<VideoSource[]>(() =>
     loadFromStorage<VideoSource[]>(SOURCES_STORAGE_KEY, [])
   );
+  const messagesRef = useRef<ConversationMessage[]>(messages);
+
+  useEffect(() => {
+    messagesRef.current = messages;
+  }, [messages]);
 
   useEffect(() => {
     saveToStorage(STORAGE_KEY, messages);
@@ -70,7 +75,7 @@ export function useRagChat(): UseRagChatReturn {
       const result = await ragChatFn({
         data: {
           userMessage,
-          conversationHistory: messages,
+          conversationHistory: messagesRef.current,
         },
       });
       return result;
@@ -82,7 +87,11 @@ export function useRagChat(): UseRagChatReturn {
         content: userMessage,
         timestamp: new Date().toISOString(),
       };
-      setMessages((prev) => [...prev, userMsg]);
+      setMessages((prev) => {
+        const newMessages = [...prev, userMsg];
+        messagesRef.current = newMessages;
+        return newMessages;
+      });
       setCurrentSources([]);
     },
     onSuccess: (result) => {

From 3d70b6d0e7776a408242976e939b3f405b2024e9 Mon Sep 17 00:00:00 2001
From: webdevcody <webdevcody@gmail.com>
Date: Thu, 8 Jan 2026 17:49:51 -0500
Subject: [PATCH 3/3] feat: Enhance conversation history management and
 validation in useRagChat

- Introduced Zod schemas for validating video sources and conversation messages, ensuring data integrity when loading from session storage.
- Implemented a trimming function to manage conversation history length, preventing excessive data storage and improving performance.
- Updated loadFromStorage function to include schema validation, enhancing error handling and debugging capabilities.
- Added maximum length checks for user messages to enforce content restrictions and improve user experience.
---
 src/hooks/use-rag-chat.ts | 85 +++++++++++++++++++++++++++++++++------
 1 file changed, 73 insertions(+), 12 deletions(-)

diff --git a/src/hooks/use-rag-chat.ts b/src/hooks/use-rag-chat.ts
index b63101f0..5b639a4b 100644
--- a/src/hooks/use-rag-chat.ts
+++ b/src/hooks/use-rag-chat.ts
@@ -1,5 +1,6 @@
 import { useState, useCallback, useEffect, useRef } from "react";
 import { useMutation } from "@tanstack/react-query";
+import { z } from "zod";
 import { ragChatFn } from "~/fn/rag-chat";
 import type { VideoSource, ConversationMessage } from "~/use-cases/rag-chat";
 
@@ -7,13 +8,44 @@ export type { VideoSource, ConversationMessage };
 
 const STORAGE_KEY = "rag-chat-history";
 const SOURCES_STORAGE_KEY = "rag-chat-sources";
+const MAX_MESSAGE_LENGTH = 2000;
+const MAX_HISTORY_LENGTH = 20000;
 
-function loadFromStorage<T>(key: string, fallback: T): T {
+const videoSourceSchema = z.object({
+  segmentId: z.number(),
+  segmentTitle: z.string(),
+  segmentSlug: z.string(),
+  moduleTitle: z.string(),
+  chunkText: z.string(),
+  similarity: z.number(),
+});
+
+const conversationMessageSchema = z.object({
+  id: z.string(),
+  role: z.enum(["user", "assistant"]),
+  content: z.string(),
+  timestamp: z.string(),
+  sources: z.array(videoSourceSchema).optional(),
+});
+
+const conversationMessagesSchema = z.array(conversationMessageSchema);
+const videoSourcesSchema = z.array(videoSourceSchema);
+
+function loadFromStorage<T>(
+  key: string,
+  fallback: T,
+  schema: z.ZodType<T>
+): T {
   if (typeof window === "undefined") return fallback;
   try {
     const stored = sessionStorage.getItem(key);
     if (stored) {
-      return JSON.parse(stored) as T;
+      const parsed = JSON.parse(stored);
+      const result = schema.safeParse(parsed);
+      if (result.success) {
+        return result.data;
+      }
+      console.error(`[RAG Chat] Validation failed for ${key}:`, result.error);
     }
   } catch (error) {
     console.error(`[RAG Chat] Failed to load from sessionStorage:`, error);
@@ -40,6 +72,29 @@ function clearStorage(): void {
   }
 }
 
+function trimConversationHistory(
+  history: ConversationMessage[],
+  maxLength: number
+): ConversationMessage[] {
+  if (history.length === 0) return history;
+
+  const truncateMessage = (msg: ConversationMessage): ConversationMessage => ({
+    ...msg,
+    content: msg.content.slice(0, MAX_MESSAGE_LENGTH),
+    sources: undefined,
+  });
+
+  let trimmed = history.map(truncateMessage);
+  let serialized = JSON.stringify(trimmed);
+
+  while (serialized.length > maxLength && trimmed.length > 0) {
+    trimmed = trimmed.slice(1);
+    serialized = JSON.stringify(trimmed);
+  }
+
+  return trimmed;
+}
+
 export interface UseRagChatReturn {
   messages: ConversationMessage[];
   isLoading: boolean;
@@ -51,10 +106,10 @@ export interface UseRagChatReturn {
 
 export function useRagChat(): UseRagChatReturn {
   const [messages, setMessages] = useState<ConversationMessage[]>(() =>
-    loadFromStorage<ConversationMessage[]>(STORAGE_KEY, [])
+    loadFromStorage<ConversationMessage[]>(STORAGE_KEY, [], conversationMessagesSchema)
   );
   const [currentSources, setCurrentSources] = useState<VideoSource[]>(() =>
-    loadFromStorage<VideoSource[]>(SOURCES_STORAGE_KEY, [])
+    loadFromStorage<VideoSource[]>(SOURCES_STORAGE_KEY, [], videoSourcesSchema)
   );
   const messagesRef = useRef<ConversationMessage[]>(messages);
 
@@ -72,10 +127,14 @@ export function useRagChat(): UseRagChatReturn {
 
   const mutation = useMutation({
     mutationFn: async (userMessage: string) => {
+      const trimmedHistory = trimConversationHistory(
+        messagesRef.current,
+        MAX_HISTORY_LENGTH
+      );
       const result = await ragChatFn({
         data: {
           userMessage,
-          conversationHistory: messagesRef.current,
+          conversationHistory: trimmedHistory,
         },
       });
       return result;
@@ -87,11 +146,7 @@ export function useRagChat(): UseRagChatReturn {
         content: userMessage,
         timestamp: new Date().toISOString(),
       };
-      setMessages((prev) => {
-        const newMessages = [...prev, userMsg];
-        messagesRef.current = newMessages;
-        return newMessages;
-      });
+      setMessages((prev) => [...prev, userMsg]);
       setCurrentSources([]);
     },
     onSuccess: (result) => {
@@ -119,8 +174,14 @@ export function useRagChat(): UseRagChatReturn {
 
   const sendMessage = useCallback(
     async (content: string) => {
-      if (!content.trim() || mutation.isPending) return;
-      await mutation.mutateAsync(content.trim());
+      const trimmed = content.trim();
+      if (!trimmed || mutation.isPending) return;
+      if (trimmed.length > MAX_MESSAGE_LENGTH) {
+        throw new Error(
+          `Message exceeds maximum length of ${MAX_MESSAGE_LENGTH} characters`
+        );
+      }
+      await mutation.mutateAsync(trimmed);
     },
     [mutation]
   );