FAISS caching (Task 5), session persistence, streaming UX, suggestions as SSE event

api/rag_engine.py

@@ -318,29 +318,41 @@ def _parse_pptx_to_text(path: str) -> List[Tuple[str, str]]:
 # ----------------------------
 class VectorStore:
     """Simple in-memory vector store using FAISS (or fallback to list-based cosine similarity)."""
-    
-    def __init__(self):
+
+    def __init__(self, cached_index=None):
+        """
+        Initialize VectorStore with optional pre-built index.
+
+        Args:
+            cached_index: Optional dict with 'index', 'use_faiss', 'chunks' (for reuse)
+        """
         self.faiss = _safe_import_faiss()
         self.index = None
         self.chunks: List[Dict] = []
         self.use_faiss = False
-        
+
+        # If cached index provided, restore it
+        if cached_index:
+            self.index = cached_index.get("index")
+            self.use_faiss = cached_index.get("use_faiss", False)
+            self.chunks = cached_index.get("chunks", [])
+
     def build_index(self, chunks: List[Dict]):
         """Build FAISS index from chunks with embeddings."""
         self.chunks = chunks or []
         if not self.chunks:
             return
-        
+
         # Filter chunks that have embeddings
         chunks_with_emb = [c for c in self.chunks if c.get("embedding") is not None]
         if not chunks_with_emb:
             print("[rag_engine] No chunks with embeddings, using token-based retrieval")
             return
-        
+
         if self.faiss is None:
             print("[rag_engine] FAISS not available, using list-based cosine similarity")
             return
-        
+
         try:
             dim = len(chunks_with_emb[0]["embedding"])
             # Use L2 (Euclidean) index for FAISS
@@ -354,7 +366,20 @@ class VectorStore:
         except Exception as e:
             print(f"[rag_engine] FAISS index build failed: {repr(e)}, using list-based")
             self.use_faiss = False
-    
+
+    def get_cached(self) -> Optional[Dict]:
+        """
+        Export index for caching in session.
+        Returns: dict with 'index', 'use_faiss', 'chunks' or None if not built.
+        """
+        if self.index is None:
+            return None
+        return {
+            "index": self.index,
+            "use_faiss": self.use_faiss,
+            "chunks": self.chunks,
+        }
+
     def search(self, query_embedding: List[float], k: int) -> List[Tuple[float, Dict]]:
         """
         Search top-k chunks by vector similarity.
@@ -362,11 +387,11 @@ class VectorStore:
         """
         if not query_embedding or not self.chunks:
             return []
-        
+
         chunks_with_emb = [c for c in self.chunks if c.get("embedding") is not None]
         if not chunks_with_emb:
             return []
-        
+
         if self.use_faiss and self.index is not None:
             try:
                 import numpy as np
@@ -381,7 +406,7 @@ class VectorStore:
                 return results
             except Exception as e:
                 print(f"[rag_engine] FAISS search error: {repr(e)}, fallback to list-based")
-        
+
         # Fallback: list-based cosine similarity
         results: List[Tuple[float, Dict]] = []
         for chunk in chunks_with_emb:
@@ -472,6 +497,7 @@ def retrieve_relevant_chunks(
     allowed_doc_types: Optional[List[str]] = None,
     use_vector_search: bool = True,  # NEW: enable/disable vector search
     vector_similarity_threshold: float = 0.3,  # L2-based similarity: 1/(1+dist), rarely reaches 0.7
+    cached_index: Optional[Dict] = None,  # NEW: pre-built FAISS index for caching
 ) -> Tuple[str, List[Dict]]:
     """
     Enhanced retrieval with vector similarity + token overlap rerank.
@@ -526,14 +552,17 @@ def retrieve_relevant_chunks(
     # Vector search path (if enabled and embeddings available)
     # ----------------------------
     chunks_with_emb = [c for c in filtered if c.get("embedding") is not None]
-    
+
     if use_vector_search and chunks_with_emb:
         try:
             query_emb = get_chunk_embedding(query)
             if query_emb:
-                # Build vector store and search
-                store = VectorStore()
-                store.build_index(chunks_with_emb)
+                # Use cached index if provided; otherwise build a new one
+                if cached_index:
+                    store = VectorStore(cached_index=cached_index)
+                else:
+                    store = VectorStore()
+                    store.build_index(chunks_with_emb)
                 vector_results = store.search(query_emb, k=k * 3)  # Get 3x candidates for reranker
 
                 # Filter by similarity threshold

api/server.py

@@ -15,7 +15,7 @@ from fastapi.middleware.cors import CORSMiddleware
 from fastapi.security import HTTPBasic, HTTPBasicCredentials
 from pydantic import BaseModel
 
-from api.config import DEFAULT_COURSE_TOPICS, DEFAULT_MODEL
+from api.config import DEFAULT_COURSE_TOPICS, DEFAULT_MODEL, async_client
 from api.syllabus_utils import extract_course_topics_from_file
 from api.rag_engine import build_rag_chunks_from_file, retrieve_relevant_chunks
 from api.clare_core import (
@@ -243,6 +243,21 @@ def _run_preload_in_background():
 
 _run_preload_in_background()
 
+def _build_faiss_index(chunks: List[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
+    """Build and cache FAISS index from chunks. Returns cached index dict or None."""
+    if not chunks:
+        return None
+    from api.rag_engine import VectorStore
+    try:
+        vs = VectorStore()
+        vs.build_index(chunks)
+        cached = vs.get_cached()
+        return cached
+    except Exception as e:
+        log.error("failed to build FAISS index: %r", e)
+        return None
+
+
 def _get_session(session_id: str) -> Dict[str, Any]:
     if session_id not in SESSIONS:
         SESSIONS[session_id] = {
@@ -259,8 +274,13 @@ def _get_session(session_id: str) -> Dict[str, Any]:
             "profile_bio": "",
             "init_answers": {},
             "init_dismiss_until": 0,
+            "faiss_index": None,  # Cached FAISS index (built at init and on upload)
         }
 
+        # Build initial FAISS index with MODULE10_CHUNKS_CACHE
+        initial_chunks = MODULE10_CHUNKS_CACHE
+        SESSIONS[session_id]["faiss_index"] = _build_faiss_index(initial_chunks)
+
     if "uploaded_files" not in SESSIONS[session_id]:
         SESSIONS[session_id]["uploaded_files"] = []
 
@@ -268,6 +288,7 @@ def _get_session(session_id: str) -> Dict[str, Any]:
     SESSIONS[session_id].setdefault("profile_bio", "")
     SESSIONS[session_id].setdefault("init_answers", {})
     SESSIONS[session_id].setdefault("init_dismiss_until", 0)
+    SESSIONS[session_id].setdefault("faiss_index", None)
 
     return SESSIONS[session_id]
 
@@ -794,12 +815,14 @@ async def chat(req: ChatReq):
         log.debug("rag skipped - message too short")
         rag_context_text, rag_used_chunks = "", []
     else:
+        # Use cached FAISS index if available (no rebuild on each query)
         rag_context_text, rag_used_chunks = retrieve_relevant_chunks(
             msg,
             MODULE10_CHUNKS_CACHE + sess["rag_chunks"],
             allowed_source_files=allowed_files,
             allowed_doc_types=allowed_doc_types,
             max_context_chars=2000,
+            cached_index=sess.get("faiss_index"),
         )
         log.debug("faiss rag | chunks_returned=%d | context_chars=%d", len(rag_used_chunks), len(rag_context_text))
         if rag_used_chunks:
@@ -950,6 +973,29 @@ async def chat(req: ChatReq):
                 run_id=None,
             )
 
+            # Generate follow-up suggestions (not blocking, sent after final message)
+            try:
+                log.debug("generating suggestions...")
+                suggestions = await asyncio.wait_for(
+                    generate_suggested_questions(
+                        user_message=msg,
+                        assistant_reply=full_text,
+                        language=resolved_lang,
+                        model_name=model_name,
+                    ),
+                    timeout=30.0,  # Max 30 seconds for suggestions
+                )
+                log.debug("suggestions generated | count=%d | data=%r", len(suggestions) if suggestions else 0, suggestions)
+                if suggestions and len(suggestions) > 0:
+                    yield f"data: {json.dumps({'suggested_questions': suggestions, 'type': 'suggestions', 'is_final': True})}\n\n"
+                    log.info("suggestions sent | count=%d", len(suggestions))
+                else:
+                    log.debug("no suggestions returned")
+            except asyncio.TimeoutError:
+                log.warning("suggestions generation timed out (>30s)")
+            except Exception as e:
+                log.warning("suggestions generation failed: %r", e)
+
             log.info("chat streamed | session=%s | chars=%d | total_ms=%.0f",
                      session_id, len(full_text), total_ms)
 
@@ -979,7 +1025,9 @@ async def quiz_start(req: QuizStartReq):
     resolved_lang = detect_language(quiz_instruction, req.language_preference)
 
     rag_context_text, rag_used_chunks = retrieve_relevant_chunks(
-        "Module 10 quiz", sess["rag_chunks"]
+        "Module 10 quiz",
+        MODULE10_CHUNKS_CACHE + sess["rag_chunks"],
+        cached_index=sess.get("faiss_index"),
     )
 
     # ✅ NEW: same hint for quiz start as well
@@ -1284,6 +1332,11 @@ async def upload(
                         session_id, len(combined), MAX_UPLOAD_CHUNKS)
             combined = combined[:MAX_UPLOAD_CHUNKS]
         sess["rag_chunks"] = combined
+
+        # REBUILD FAISS index with merged chunks (MODULE10 + new uploads)
+        all_chunks = MODULE10_CHUNKS_CACHE + sess["rag_chunks"]
+        sess["faiss_index"] = _build_faiss_index(all_chunks)
+        log.debug("[upload] rebuilt FAISS index with %d total chunks", len(all_chunks))
     except Exception as e:
         print(f"[upload] rag build error: {repr(e)}")
         new_chunks = []

web/src/App.tsx

@@ -166,6 +166,42 @@ function hydrateSavedChats(raw: any): SavedChat[] {
     .filter(Boolean) as SavedChat[];
 }
 
+// ✅ localStorage helpers for ongoing session state (refresh persistence)
+function sessionStorageKey(session_id: string) {
+  return `session_state::${session_id}`;
+}
+
+function hydrateSessionState(raw: any) {
+  if (!raw) return null;
+  try {
+    return {
+      askMessages: Array.isArray(raw.askMessages)
+        ? raw.askMessages.map((m: any) => ({
+            ...m,
+            timestamp: m?.timestamp ? new Date(m.timestamp) : new Date(),
+          }))
+        : [],
+      reviewMessages: Array.isArray(raw.reviewMessages)
+        ? raw.reviewMessages.map((m: any) => ({
+            ...m,
+            timestamp: m?.timestamp ? new Date(m.timestamp) : new Date(),
+          }))
+        : [],
+      quizMessages: Array.isArray(raw.quizMessages)
+        ? raw.quizMessages.map((m: any) => ({
+            ...m,
+            timestamp: m?.timestamp ? new Date(m.timestamp) : new Date(),
+          }))
+        : [],
+      uploadedFiles: Array.isArray(raw.uploadedFiles) ? raw.uploadedFiles : [],
+      learningMode: raw.learningMode || "concept",
+      language: raw.language || "Auto",
+    };
+  } catch {
+    return null;
+  }
+}
+
 
 function App() {
   const [isDarkMode, setIsDarkMode] = useState(() => {
@@ -173,7 +209,22 @@ function App() {
     return saved === "dark" || (!saved && window.matchMedia("(prefers-color-scheme: dark)").matches);
   });
 
-  const [user, setUser] = useState<User | null>(null);
+  const [user, setUser] = useState<User | null>(() => {
+    // Restore user from localStorage on page load
+    try {
+      const saved = localStorage.getItem("user_session");
+      if (saved) {
+        const parsed = JSON.parse(saved);
+        return {
+          login_id: parsed.login_id,
+          session_id: parsed.session_id,
+        } as User;
+      }
+    } catch {
+      // ignore
+    }
+    return null;
+  });
 
 
   // -------------------------
@@ -343,6 +394,27 @@ function App() {
 
   const [savedChats, setSavedChats] = useState<SavedChat[]>([]);
 
+  // ✅ persist user session to localStorage
+  useEffect(() => {
+    if (user?.login_id && user?.session_id) {
+      try {
+        localStorage.setItem("user_session", JSON.stringify({
+          login_id: user.login_id,
+          session_id: user.session_id,
+        }));
+      } catch {
+        // ignore
+      }
+    } else {
+      // Clear user session when logged out
+      try {
+        localStorage.removeItem("user_session");
+      } catch {
+        // ignore
+      }
+    }
+  }, [user?.login_id, user?.session_id]);
+
   // ✅ load saved chats after login
   useEffect(() => {
     if (!user?.login_id) return;
@@ -369,6 +441,47 @@ function App() {
     }
   }, [savedChats, user?.login_id]);
 
+  // ✅ restore session state from localStorage on login
+  useEffect(() => {
+    if (!user?.session_id) return;
+    try {
+      const raw = localStorage.getItem(sessionStorageKey(user.session_id));
+      if (!raw) return;
+      const state = hydrateSessionState(JSON.parse(raw));
+      if (!state) return;
+
+      // Restore session state
+      if (state.askMessages.length > 0) setAskMessages(state.askMessages);
+      if (state.reviewMessages.length > 0) setReviewMessages(state.reviewMessages);
+      if (state.quizMessages.length > 0) setQuizMessages(state.quizMessages);
+      if (state.uploadedFiles.length > 0) setUploadedFiles(state.uploadedFiles);
+      if (state.learningMode) setLearningMode(state.learningMode);
+      if (state.language) setLanguage(state.language);
+    } catch {
+      // ignore restore errors
+    }
+  }, [user?.session_id]);
+
+  // ✅ persist session state to localStorage whenever messages/state change
+  useEffect(() => {
+    if (!user?.session_id) return;
+    try {
+      localStorage.setItem(
+        sessionStorageKey(user.session_id),
+        JSON.stringify({
+          askMessages,
+          reviewMessages,
+          quizMessages,
+          uploadedFiles,
+          learningMode,
+          language,
+        })
+      );
+    } catch {
+      // ignore
+    }
+  }, [askMessages, reviewMessages, quizMessages, uploadedFiles, learningMode, language, user?.session_id]);
+
   const [groupMembers] = useState<GroupMember[]>([
     { id: "clare", name: "Clare AI", email: "clare@ai.assistant", isAI: true },
     { id: "1", name: "Sarah Johnson", email: "sarah.j@university.edu" },
@@ -811,12 +924,47 @@ function App() {
     try {
       const docType = getCurrentDocTypeForChat();
 
+      // Create message with empty content (will be filled as tokens arrive)
+      const messageId = (Date.now() + 1).toString();
+      const assistantMessage: Message = {
+        id: messageId,
+        role: "assistant",
+        content: "",
+        timestamp: new Date(),
+        references: undefined,
+        sender: spaceType === "group" ? groupMembers.find((m) => m.isAI) : undefined,
+      };
+
+      // Add empty message immediately so user sees typing indicator
+      if (chatMode === "ask") setAskMessages((prev) => [...prev, assistantMessage]);
+      else if (chatMode === "review") setReviewMessages((prev) => [...prev, assistantMessage]);
+      else setQuizMessages((prev) => [...prev, assistantMessage]);
+
+      // Hide typing indicator immediately (message will fill with tokens)
+      setIsTyping(false);
+
+      // Stream response with token callback
       const r = await apiChat({
         session_id: user.session_id,
         message: effectiveContent,
         learning_mode: learningMode,
         language_preference: mapLanguagePref(language),
         doc_type: docType,
+      }, (token: string) => {
+        // Update message content as tokens arrive
+        if (chatMode === "ask") {
+          setAskMessages((prev) =>
+            prev.map((m) => m.id === messageId ? { ...m, content: m.content + token } : m)
+          );
+        } else if (chatMode === "review") {
+          setReviewMessages((prev) =>
+            prev.map((m) => m.id === messageId ? { ...m, content: m.content + token } : m)
+          );
+        } else {
+          setQuizMessages((prev) =>
+            prev.map((m) => m.id === messageId ? { ...m, content: m.content + token } : m)
+          );
+        }
       });
 
       const normalizeRefs = (raw: any): string[] => {
@@ -838,21 +986,17 @@ function App() {
 
       const refs = normalizeRefs((r as any).refs ?? (r as any).references);
 
-      const assistantMessage: Message = {
-        id: (Date.now() + 1).toString(),
-        role: "assistant",
+      // Update message with final content, refs, and suggestions
+      const finalMessage: Message = {
+        ...assistantMessage,
         content: r.reply || "",
-        timestamp: new Date(),
         references: refs.length ? refs : undefined,
-        sender: spaceType === "group" ? groupMembers.find((m) => m.isAI) : undefined,
         suggestedQuestions: (r as any).suggested_questions?.length ? (r as any).suggested_questions : undefined,
       };
 
-      setIsTyping(false);
-
-      if (chatMode === "ask") setAskMessages((prev) => [...prev, assistantMessage]);
-      else if (chatMode === "review") setReviewMessages((prev) => [...prev, assistantMessage]);
-      else setQuizMessages((prev) => [...prev, assistantMessage]);
+      if (chatMode === "ask") setAskMessages((prev) => prev.map((m) => m.id === messageId ? finalMessage : m));
+      else if (chatMode === "review") setReviewMessages((prev) => prev.map((m) => m.id === messageId ? finalMessage : m));
+      else setQuizMessages((prev) => prev.map((m) => m.id === messageId ? finalMessage : m));
     } catch (e: any) {
       setIsTyping(false);
       toast.error(e?.message || "Something went wrong. Please try again.");