Improve RAG init & docs

QUICKSTART.md

@@ -75,9 +75,11 @@ Create `.env` in the project root:
 OPENAI_API_KEY=sk-your-actual-api-key-here
 ```
 
-### 5. Add Documents
+### 5. Add Documents / Processed Data
 
-Place your PDF, TXT, DOCX, or DOC files in the `documents/` folder.
+- **Local development:** copy your PDF/TXT/DOC/DOCX files into the `documents/` folder before running `uv run python backend/main.py`.
+- **Deploying to Hugging Face Spaces:** large PDFs should be uploaded via the Space UI (Files & versions → Upload). Git pushes can’t include big binaries.
+- If you have a pre-generated `processed_documents.json`, keep it in the project root (it’s copied by the Dockerfile). The backend logs will print whether this file and the `documents/` folder exist at startup.
 
 ### 6. Run the Application
 
@@ -117,6 +119,11 @@ npm start
 **"No documents found"**
 - Check that files are in the `documents/` folder
 - Supported formats: PDF, TXT, DOCX, DOC
+- On Hugging Face Spaces, make sure you uploaded the PDFs (or a `processed_documents.json`) via the **Files and versions** tab. Watch the build/startup logs for messages such as `[RAG Init] processed_documents.json exists? True`.
+
+**"RAG system not initialized" (on Spaces)**
+- Ensure `processed_documents.json` is present in the repo **and** not excluded by `.dockerignore`.
+- Upload your source PDFs (or processed data) in the Space UI, then restart the Space so the startup hook can detect them.
 
 **Frontend can't connect to backend**
 - Ensure backend is running on port 8000

app.py

@@ -23,8 +23,14 @@ app.add_middleware(
 )
 
 # Mount the backend API
+print("[root_app] Mounting backend application at /api")
 app.mount("/api", backend_app)
 
+
+@app.on_event("startup")
+async def root_startup_event():
+    print("[root_app] Startup event triggered")
+
 # Serve React frontend
 frontend_path = Path(__file__).parent / "frontend" / "build"
 

backend/main.py

@@ -1,3 +1,4 @@
+import asyncio
 from fastapi import FastAPI, HTTPException, Query
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import FileResponse, JSONResponse
@@ -30,47 +31,62 @@ app.add_middleware(
 # Initialize RAG system
 rag_system = None
 rag_ready = False
+_rag_init_lock = asyncio.Lock()
 
 class QuestionRequest(BaseModel):
     question: str
     use_history: Optional[bool] = True
 
+
 class QuestionResponse(BaseModel):
     answer: str
     sources: List[str]
 
+
+async def initialize_rag_system(force: bool = False) -> None:
+    """Initialize the RAG system if data is available."""
+    global rag_system, rag_ready
+
+    async with _rag_init_lock:
+        if not force and rag_system is not None and rag_ready:
+            return
+
+        try:
+            rag_ready = False
+            print(f"[RAG Init] Starting initialization (force={force})")
+            rag_system = RAGSystem()
+            docs_folder = Path("documents")
+            processed_json = Path("processed_documents.json")
+
+            print(f"[RAG Init] processed_documents.json exists? {processed_json.exists()}")
+            print(f"[RAG Init] documents folder exists? {docs_folder.exists()}")
+
+            if docs_folder.exists() and any(docs_folder.glob("*.pdf")):
+                print("[RAG Init] PDFs detected, processing...")
+                num_docs = rag_system.process_and_index_documents(str(docs_folder))
+                print(f"[RAG Init] ✓ Processed and indexed {num_docs} documents")
+                rag_ready = True
+            elif processed_json.exists():
+                print("[RAG Init] processed_documents.json found. Using existing summaries.")
+                rag_ready = True
+            else:
+                print("[RAG Init] No PDFs or processed_documents.json found. RAG remains uninitialized.")
+                rag_ready = False
+        except Exception as exc:
+            print(f"[RAG Init] Initialization failed: {exc}")
+            import traceback
+            traceback.print_exc()
+            rag_ready = False
+            raise
+
+
 @app.on_event("startup")
 async def startup_event():
     """Process and index all PDFs on startup"""
-    global rag_system
-    global rag_ready
     try:
-        rag_ready = False
-        print("[startup_event] Initializing RAG system...")
-        rag_system = RAGSystem()
-        docs_folder = Path("documents")
-        processed_json = Path("processed_documents.json")
-
-        print(f"[startup_event] processed_documents.json exists? {processed_json.exists()}")
-        print(f"[startup_event] documents folder exists? {docs_folder.exists()}")
-
-        if docs_folder.exists() and any(docs_folder.glob("*.pdf")):
-            print("[startup_event] PDFs detected, processing...")
-            num_docs = rag_system.process_and_index_documents(str(docs_folder))
-            print(f"[startup_event] ✓ Processed and indexed {num_docs} documents")
-            rag_ready = True
+        await initialize_rag_system(force=True)
+        if rag_ready:
             print("[startup_event] RAG system ready.")
-        else:
-            print("[startup_event] No PDF files found in documents folder")
-            if processed_json.exists():
-                print(
-                    "[startup_event] processed_documents.json found, but no PDFs to process. "
-                    "Ensure processed data is uploaded if you expect answers."
-                )
-                rag_ready = True
-            else:
-                print("[startup_event] No processed_documents.json available; RAG system may remain uninitialized.")
-                rag_ready = False
     except Exception as e:
         print(f"[startup_event] Warning: Could not initialize RAG system: {e}")
         import traceback
@@ -89,10 +105,12 @@ async def ask_question(request: QuestionRequest):
     """Answer a question using RAG with multi-turn chat history"""
     global rag_system, rag_ready
     if rag_system is None or not rag_ready:
-        raise HTTPException(
-            status_code=503,
-            detail="RAG system not initialized. Upload PDFs or processed_documents.json, then restart the Space."
-        )
+        await initialize_rag_system()
+        if rag_system is None or not rag_ready:
+            raise HTTPException(
+                status_code=503,
+                detail="RAG system not initialized. Upload PDFs or processed_documents.json, then restart the Space."
+            )
     
     if not request.question.strip():
         raise HTTPException(status_code=400, detail="Question cannot be empty")