Initial clean LFS commit

.dockerignore

@@ -0,0 +1,9 @@
+# Never bake secrets or local cruft into the image
+.env
+.git
+.gitignore
+__pycache__/
+*.pyc
+.venv/
+venv/
+*.log

.gitattributes

@@ -0,0 +1,40 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text
+*.pdf filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text
+*.jpeg filter=lfs diff=lfs merge=lfs -text
+*.jpg filter=lfs diff=lfs merge=lfs -text
+*.faiss filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,12 @@
+# Secrets — NEVER commit (contains the Supabase service-role key + NVIDIA key)
+.env
+
+# Python
+__pycache__/
+*.pyc
+.venv/
+venv/
+*.log
+
+# Note: vector_db/, images/ and documents/ ARE committed on purpose so the
+# deployed app ships with the policy index already built.

Dockerfile

@@ -0,0 +1,21 @@
+# Docent AI — container image for free deployment (Hugging Face Spaces / Render / Fly.io)
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install Python dependencies first (better layer caching)
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy the whole project (includes the pre-built vector_db/ and images/)
+COPY . .
+
+# These dirs must exist at startup: StaticFiles mounts images/, and uploads
+# write into documents/ + vector_db/.
+RUN mkdir -p documents images vector_db
+
+# Hugging Face Spaces expects the app on port 7860 by default.
+EXPOSE 7860
+
+WORKDIR /app/backend
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -0,0 +1,182 @@
+---
+title: Docent AI Policy Chatbot
+emoji: 📚
+colorFrom: green
+colorTo: gray
+sdk: docker
+app_port: 7860
+pinned: false
+---
+
+# Docent AI — NVIDIA RAG Policy Chatbot
+
+A production-ready Retrieval-Augmented Generation (RAG) chatbot that answers questions strictly from uploaded policy PDFs. Powered by NVIDIA's `llama-3.3-70b-instruct` and LangChain, with Supabase-backed user accounts and persistent chat history.
+
+## Features
+
+- **User authentication** (Supabase email/password) — each user has their own private chats
+- **Persistent chat history** — conversations are stored in Supabase and reload on login
+- **Conversational memory** — follow-up questions ("what about for managers?") are understood using prior turns via a history-aware retriever
+- Upload one or many PDF documents; they are indexed and **persisted** in a FAISS vector store
+- Answers come **only from the documents** — the LLM is instructed never to hallucinate or use outside knowledge
+- Every answer shows **source file + page number** references (persisted with history)
+- Adding more PDFs at any time merges them into the existing index with no data loss
+
+## Project Structure
+
+```
+docent-ai-nvidia/
+├── .env                  # NVIDIA API key + Supabase keys
+├── supabase_schema.sql   # Run once in the Supabase SQL editor
+├── requirements.txt
+├── documents/            # Uploaded PDFs are stored here
+├── vector_db/            # Persisted FAISS index
+├── backend/
+│   ├── main.py           # FastAPI app + auth + history endpoints
+│   ├── rag.py            # History-aware RAG engine
+│   ├── db.py             # Supabase auth + chat persistence
+│   └── ingest.py         # PDF ingestion + FAISS management
+└── frontend/
+    ├── index.html
+    ├── style.css
+    └── script.js
+```
+
+## Setup
+
+### 1. Install dependencies
+
+```powershell
+cd c:\docent-ai-nvidia
+pip install -r requirements.txt
+```
+
+### 2. Verify `.env`
+
+The `.env` file should contain:
+
+```
+NVIDIA_API_KEY=nvapi-...
+SUPABASE_URL=https://<project-ref>.supabase.co
+SUPABASE_ANON_KEY=eyJ...
+SUPABASE_SERVICE_ROLE_KEY=eyJ...
+```
+
+### 3. Set up Supabase (one time)
+
+1. Open your project → **SQL Editor** → **New query**.
+2. Paste the contents of `supabase_schema.sql` and click **Run**. This creates the
+   `chat_sessions` and `messages` tables with row-level security.
+3. (Recommended for quick testing) Go to **Authentication → Providers → Email** and
+   turn **off** "Confirm email" so new sign-ups can log in immediately. Leave it on
+   in production and users will receive a confirmation email.
+
+### 4. Run the server
+
+From the project root:
+
+```powershell
+cd c:\docent-ai-nvidia
+run
+```
+
+Or double-click `run.bat`. Then open [http://localhost:8000](http://localhost:8000).
+
+### 5. Open the chatbot
+
+Go to [http://localhost:8000](http://localhost:8000) in your browser.
+
+## Deploy for free (Hugging Face Spaces)
+
+The repo ships a `Dockerfile` and the pre-built `vector_db/`, so the deployed app
+works out of the box. Hugging Face Spaces' free tier gives 16 GB RAM (enough for the
+heavy `faiss`/`langchain` deps) with no credit card.
+
+1. Create a free account at [huggingface.co](https://huggingface.co).
+2. **New → Space**: pick a name, **SDK = Docker** (Blank template), visibility Public.
+3. Push this project to the Space's git repo (or upload the files), e.g.:
+
+```bash
+git init
+git add .
+git commit -m "Docent AI"
+git remote add origin https://huggingface.co/spaces/<user>/<space-name>
+git push origin main
+```
+
+4. In the Space → **Settings → Variables and secrets**, add these **secrets**:
+   `NVIDIA_API_KEY`, `SUPABASE_URL`, `SUPABASE_ANON_KEY`, `SUPABASE_SERVICE_ROLE_KEY`.
+5. Run `supabase_schema.sql` in the Supabase SQL Editor and turn **off** "Confirm email".
+6. The Space builds and serves at `https://<user>-<space-name>.hf.space`.
+
+> `.env` is gitignored and never deployed — all keys come from Space secrets.
+> Runtime PDF uploads are ephemeral on free tiers (they reset on rebuild); the
+> committed `vector_db/` is what ships. Re-ingest locally and push to update it.
+
+## Usage
+
+1. **Upload PDFs** — drag-and-drop or click "Drop PDFs here" in the sidebar and click **Upload**.
+2. **Ask questions** — type in the chat box and press Enter.
+3. **See sources** — each answer shows which document and page the information came from.
+4. **Add more documents** — upload additional PDFs at any time; they are merged into the existing index.
+
+## API Reference
+
+All routes except `/` and `/config` require a Supabase access token in the
+`Authorization: Bearer <token>` header.
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/` | Serves the chat UI |
+| `GET` | `/config` | Public Supabase URL + anon key for the frontend |
+| `POST` | `/upload` | Upload one or more PDF files (auth) |
+| `GET` | `/documents` | List all ingested document filenames (auth) |
+| `GET` | `/sessions` | List the user's conversations (auth) |
+| `POST` | `/sessions` | Create a new conversation (auth) |
+| `GET` | `/sessions/{id}/messages` | Load a conversation's messages (auth) |
+| `DELETE` | `/sessions/{id}` | Delete a conversation (auth) |
+| `POST` | `/chat` | Send a question, get an answer + sources (auth) |
+
+### `/chat` request body
+
+```json
+{
+  "question": "What is the leave policy?",
+  "session_id": "optional-existing-session-uuid"
+}
+```
+
+If `session_id` is omitted, a new conversation is created automatically.
+
+### `/chat` response
+
+```json
+{
+  "answer": "According to the HR Policy document, employees are entitled to ...",
+  "sources": [
+    { "file": "hr-policy.pdf", "page": 4, "image_urls": [] }
+  ],
+  "session_id": "…",
+  "title": "What is the leave policy?"
+}
+```
+
+## How conversational memory works
+
+On each `/chat` call the backend loads the recent turns of that conversation from
+Supabase and (a) rewrites the follow-up into a standalone question for retrieval,
+and (b) passes the history to the LLM so references like "it" / "that policy"
+resolve correctly. The strict "answer only from the documents" rule still applies.
+
+## Tech Stack
+
+| Component | Library |
+|-----------|---------|
+| LLM | `langchain-nvidia-ai-endpoints` — `ChatNVIDIA` (`meta/llama-3.3-70b-instruct`) |
+| Embeddings | `NVIDIAEmbeddings` (`nvidia/nv-embedqa-e5-v5`) |
+| Vector store | `faiss-cpu` (persisted to disk) |
+| Auth & history | Supabase (Postgres + Auth) |
+| PDF loading | `pypdf` via `PyPDFLoader` |
+| Framework | `langchain` |
+| Backend | `fastapi` + `uvicorn` |
+| Frontend | HTML + CSS + Vanilla JS + `@supabase/supabase-js` |

backend/Untitled

@@ -0,0 +1 @@
+python ingest_all.py

backend/db.py

@@ -0,0 +1,132 @@
+"""
+Supabase integration: token verification + chat-history persistence.
+
+All database access here uses the *service-role* key, which bypasses Row Level
+Security. Because of that, every query is explicitly scoped to the
+authenticated user's id — never trust a client-supplied user id.
+"""
+import os
+from pathlib import Path
+from datetime import datetime, timezone
+
+from dotenv import load_dotenv
+from supabase import create_client, Client
+
+load_dotenv(Path(__file__).parent.parent / ".env")
+
+SUPABASE_URL      = os.environ.get("SUPABASE_URL", "").rstrip("/")
+SUPABASE_ANON_KEY = os.environ.get("SUPABASE_ANON_KEY", "")
+SERVICE_ROLE_KEY  = os.environ.get("SUPABASE_SERVICE_ROLE_KEY", "")
+
+_admin: Client | None = None
+
+
+def is_configured() -> bool:
+    return bool(SUPABASE_URL and SERVICE_ROLE_KEY and SUPABASE_ANON_KEY)
+
+
+def admin() -> Client:
+    """Lazily create and reuse a single service-role client."""
+    global _admin
+    if _admin is None:
+        if not is_configured():
+            raise RuntimeError(
+                "Supabase is not configured. Set SUPABASE_URL, SUPABASE_ANON_KEY "
+                "and SUPABASE_SERVICE_ROLE_KEY in your .env file."
+            )
+        _admin = create_client(SUPABASE_URL, SERVICE_ROLE_KEY)
+    return _admin
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+# ── Auth ────────────────────────────────────────────────────────────────────
+
+def verify_token(token: str):
+    """Validate a Supabase access token and return the user, or None."""
+    try:
+        res = admin().auth.get_user(token)
+        return res.user if res else None
+    except Exception:
+        return None
+
+
+# ── Sessions ──────────────────────────────────────────────────────────────────
+
+def create_session(user_id: str, title: str) -> dict:
+    res = (
+        admin()
+        .table("chat_sessions")
+        .insert({"user_id": user_id, "title": title[:80] or "New chat"})
+        .execute()
+    )
+    return res.data[0]
+
+
+def list_sessions(user_id: str) -> list[dict]:
+    res = (
+        admin()
+        .table("chat_sessions")
+        .select("id, title, created_at, updated_at")
+        .eq("user_id", user_id)
+        .order("updated_at", desc=True)
+        .execute()
+    )
+    return res.data or []
+
+
+def get_session(session_id: str, user_id: str) -> dict | None:
+    res = (
+        admin()
+        .table("chat_sessions")
+        .select("*")
+        .eq("id", session_id)
+        .eq("user_id", user_id)
+        .limit(1)
+        .execute()
+    )
+    return res.data[0] if res.data else None
+
+
+def touch_session(session_id: str) -> None:
+    admin().table("chat_sessions").update({"updated_at": _now()}).eq("id", session_id).execute()
+
+
+def rename_session(session_id: str, user_id: str, title: str) -> None:
+    admin().table("chat_sessions").update({"title": title[:80]}).eq("id", session_id).eq("user_id", user_id).execute()
+
+
+def delete_session(session_id: str, user_id: str) -> None:
+    # messages cascade-delete via the foreign key
+    admin().table("chat_sessions").delete().eq("id", session_id).eq("user_id", user_id).execute()
+
+
+# ── Messages ──────────────────────────────────────────────────────────────────
+
+def add_message(session_id: str, role: str, content: str, sources: list | None = None) -> dict:
+    res = (
+        admin()
+        .table("messages")
+        .insert({
+            "session_id": session_id,
+            "role": role,
+            "content": content,
+            "sources": sources or [],
+        })
+        .execute()
+    )
+    return res.data[0]
+
+
+def list_messages(session_id: str) -> list[dict]:
+    res = (
+        admin()
+        .table("messages")
+        .select("role, content, sources, created_at")
+        .eq("session_id", session_id)
+        .order("created_at")
+        .execute()
+    )
+    return res.data or []

backend/ingest.py

@@ -0,0 +1,139 @@
+import os
+import json
+from pathlib import Path
+from dotenv import load_dotenv
+from langchain_community.document_loaders import PyPDFLoader
+from langchain_text_splitters import RecursiveCharacterTextSplitter
+from langchain_nvidia_ai_endpoints import NVIDIAEmbeddings
+from langchain_community.vectorstores import FAISS
+
+load_dotenv(Path(__file__).parent.parent / ".env")
+
+VECTOR_DB_PATH = Path(__file__).parent.parent / "vector_db"
+DOCUMENTS_PATH = Path(__file__).parent.parent / "documents"
+IMAGES_PATH    = Path(__file__).parent.parent / "images"
+
+CHUNK_SIZE    = 1000
+CHUNK_OVERLAP = 200
+MIN_IMAGE_DIM = 80   # pixels — skip tiny icons / decorative elements
+
+
+def get_embeddings() -> NVIDIAEmbeddings:
+    return NVIDIAEmbeddings(
+        model="nvidia/nv-embedqa-e5-v5",
+        api_key=os.environ["NVIDIA_API_KEY"],
+        truncate="END",
+    )
+
+
+# ── Image extraction ──────────────────────────────────────────────────────────
+
+def extract_images_from_pdf(pdf_path: str) -> dict[int, list[str]]:
+    """
+    Extract images from every page of the PDF using PyMuPDF.
+    Returns a dict mapping  page_number (0-based) → [image_filename, ...]
+    Only images larger than MIN_IMAGE_DIM × MIN_IMAGE_DIM are kept.
+    """
+    try:
+        import fitz  # PyMuPDF
+    except ImportError:
+        return {}
+
+    pdf_name = Path(pdf_path).stem
+    page_images: dict[int, list[str]] = {}
+    doc = fitz.open(pdf_path)
+
+    for page_num in range(len(doc)):
+        page = doc[page_num]
+        img_list = page.get_images(full=True)
+        saved = []
+
+        for img_idx, img_info in enumerate(img_list):
+            xref = img_info[0]
+            try:
+                base = doc.extract_image(xref)
+            except Exception:
+                continue
+
+            w, h = base.get("width", 0), base.get("height", 0)
+            if w < MIN_IMAGE_DIM or h < MIN_IMAGE_DIM:
+                continue
+
+            ext = base.get("ext", "png")
+            filename = f"{pdf_name}_p{page_num + 1}_i{img_idx + 1}.{ext}"
+            dest = IMAGES_PATH / filename
+
+            if not dest.exists():
+                dest.write_bytes(base["image"])
+
+            saved.append(filename)
+
+        if saved:
+            page_images[page_num] = saved
+
+    doc.close()
+    return page_images
+
+
+# ── Text ingestion ────────────────────────────────────────────────────────────
+
+def load_and_split_pdf(pdf_path: str, page_images: dict[int, list[str]]) -> list:
+    loader = PyPDFLoader(pdf_path)
+    pages = loader.load()
+
+    splitter = RecursiveCharacterTextSplitter(
+        chunk_size=CHUNK_SIZE,
+        chunk_overlap=CHUNK_OVERLAP,
+        separators=["\n\n", "\n", ".", " ", ""],
+    )
+    chunks = splitter.split_documents(pages)
+
+    for chunk in chunks:
+        page_num = chunk.metadata.get("page", 0)   # PyPDFLoader uses 0-based page
+        chunk.metadata["source"] = Path(pdf_path).name
+        # Attach image filenames for this page (stored as JSON string)
+        imgs = page_images.get(page_num, [])
+        chunk.metadata["images"] = json.dumps(imgs)
+
+    return chunks
+
+
+def ingest_pdf(pdf_path: str) -> int:
+    """
+    Extract images, embed text chunks, merge into persisted FAISS index.
+    Returns the number of text chunks added.
+    """
+    page_images = extract_images_from_pdf(pdf_path)
+    chunks = load_and_split_pdf(pdf_path, page_images)
+
+    if not chunks:
+        return 0
+
+    embeddings = get_embeddings()
+    index_file = VECTOR_DB_PATH / "index.faiss"
+
+    if index_file.exists():
+        store = FAISS.load_local(
+            str(VECTOR_DB_PATH),
+            embeddings,
+            allow_dangerous_deserialization=True,
+        )
+        store.add_documents(chunks)
+    else:
+        store = FAISS.from_documents(chunks, embeddings)
+
+    store.save_local(str(VECTOR_DB_PATH))
+    return len(chunks)
+
+
+def load_vector_store() -> FAISS | None:
+    """Load the persisted FAISS index. Returns None if no index exists yet."""
+    index_file = VECTOR_DB_PATH / "index.faiss"
+    if not index_file.exists():
+        return None
+    embeddings = get_embeddings()
+    return FAISS.load_local(
+        str(VECTOR_DB_PATH),
+        embeddings,
+        allow_dangerous_deserialization=True,
+    )

backend/main.py

@@ -0,0 +1,200 @@
+import shutil
+from pathlib import Path
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI, UploadFile, File, HTTPException, Depends, Header
+from fastapi.staticfiles import StaticFiles
+from fastapi.responses import FileResponse
+from pydantic import BaseModel
+from dotenv import load_dotenv
+
+from ingest import ingest_pdf, load_vector_store, DOCUMENTS_PATH, IMAGES_PATH
+from rag import build_engine
+import db
+
+load_dotenv(Path(__file__).parent.parent / ".env")
+
+FRONTEND_PATH = Path(__file__).parent.parent / "frontend"
+
+# Global RAG state loaded once at startup and refreshed after uploads
+_engine = None
+
+
+def refresh_rag():
+    global _engine
+    store = load_vector_store()
+    _engine = build_engine(store) if store is not None else None
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    refresh_rag()
+    yield
+
+
+app = FastAPI(title="Docent AI — Policy Chatbot", lifespan=lifespan)
+
+# Serve frontend static files and extracted images
+app.mount("/static", StaticFiles(directory=str(FRONTEND_PATH)), name="static")
+app.mount("/images", StaticFiles(directory=str(IMAGES_PATH)), name="images")
+
+
+# ---------- Models ----------
+
+class ChatRequest(BaseModel):
+    question: str
+    session_id: str | None = None
+
+
+class ChatResponse(BaseModel):
+    answer: str
+    sources: list[dict]
+    session_id: str
+    title: str
+
+
+# ---------- Auth dependency ----------
+
+async def get_current_user(authorization: str | None = Header(default=None)):
+    if not authorization or not authorization.lower().startswith("bearer "):
+        raise HTTPException(status_code=401, detail="Not authenticated.")
+    token = authorization.split(" ", 1)[1].strip()
+    user = db.verify_token(token)
+    if user is None:
+        raise HTTPException(status_code=401, detail="Invalid or expired session.")
+    return user
+
+
+def _attach_image_urls(sources: list[dict]) -> list[dict]:
+    for src in sources:
+        src["image_urls"] = [f"/images/{fname}" for fname in src.get("images", [])]
+    return sources
+
+
+# ---------- Routes ----------
+
+@app.get("/")
+async def root():
+    return FileResponse(str(FRONTEND_PATH / "index.html"))
+
+
+@app.get("/config")
+async def config():
+    """Public config the frontend needs to initialise Supabase auth."""
+    return {
+        "supabaseUrl": db.SUPABASE_URL,
+        "supabaseAnonKey": db.SUPABASE_ANON_KEY,
+        "configured": db.is_configured(),
+    }
+
+
+@app.post("/upload")
+async def upload_documents(
+    files: list[UploadFile] = File(...),
+    user=Depends(get_current_user),
+):
+    """Accept one or more PDF files, ingest them into the FAISS store."""
+    if not files:
+        raise HTTPException(status_code=400, detail="No files provided.")
+
+    results = []
+    for upload in files:
+        if not upload.filename.lower().endswith(".pdf"):
+            results.append({"file": upload.filename, "status": "skipped — not a PDF"})
+            continue
+
+        dest = DOCUMENTS_PATH / upload.filename
+        with open(dest, "wb") as f:
+            shutil.copyfileobj(upload.file, f)
+
+        try:
+            chunks = ingest_pdf(str(dest))
+            results.append({"file": upload.filename, "status": "ingested", "chunks": chunks})
+        except Exception as e:
+            results.append({"file": upload.filename, "status": f"error: {e}"})
+
+    refresh_rag()
+    return {"results": results}
+
+
+@app.get("/documents")
+async def list_documents(user=Depends(get_current_user)):
+    """List all PDF filenames stored in the documents folder."""
+    pdfs = sorted(
+        p.name for p in DOCUMENTS_PATH.iterdir() if p.suffix.lower() == ".pdf"
+    )
+    return {"documents": pdfs}
+
+
+# ---------- Sessions / history ----------
+
+@app.get("/sessions")
+async def get_sessions(user=Depends(get_current_user)):
+    return {"sessions": db.list_sessions(user.id)}
+
+
+@app.post("/sessions")
+async def new_session(user=Depends(get_current_user)):
+    sess = db.create_session(user.id, "New chat")
+    return sess
+
+
+@app.get("/sessions/{session_id}/messages")
+async def get_session_messages(session_id: str, user=Depends(get_current_user)):
+    if db.get_session(session_id, user.id) is None:
+        raise HTTPException(status_code=404, detail="Conversation not found.")
+    messages = db.list_messages(session_id)
+    for m in messages:
+        if m.get("sources"):
+            _attach_image_urls(m["sources"])
+    return {"messages": messages}
+
+
+@app.delete("/sessions/{session_id}")
+async def remove_session(session_id: str, user=Depends(get_current_user)):
+    db.delete_session(session_id, user.id)
+    return {"ok": True}
+
+
+@app.post("/chat", response_model=ChatResponse)
+async def chat(req: ChatRequest, user=Depends(get_current_user)):
+    if not req.question.strip():
+        raise HTTPException(status_code=400, detail="Question cannot be empty.")
+
+    if _engine is None:
+        raise HTTPException(
+            status_code=503,
+            detail="No documents have been ingested yet. Please upload policy PDFs first.",
+        )
+
+    # Resolve or create the conversation
+    if req.session_id:
+        session = db.get_session(req.session_id, user.id)
+        if session is None:
+            raise HTTPException(status_code=404, detail="Conversation not found.")
+    else:
+        title = req.question.strip()[:60]
+        session = db.create_session(user.id, title)
+
+    session_id = session["id"]
+
+    # Load prior turns BEFORE storing the new question, to use as memory
+    history = db.list_messages(session_id)
+
+    db.add_message(session_id, "user", req.question)
+
+    try:
+        answer, sources = _engine.answer(req.question, history)
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"LLM error: {e}")
+
+    _attach_image_urls(sources)
+    db.add_message(session_id, "assistant", answer, sources)
+    db.touch_session(session_id)
+
+    return ChatResponse(
+        answer=answer,
+        sources=sources,
+        session_id=session_id,
+        title=session["title"],
+    )

backend/rag.py

@@ -0,0 +1,139 @@
+import os
+import json
+from pathlib import Path
+from dotenv import load_dotenv
+from langchain_nvidia_ai_endpoints import ChatNVIDIA
+from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
+from langchain_core.messages import HumanMessage, AIMessage
+from langchain_core.output_parsers import StrOutputParser
+from langchain_community.vectorstores import FAISS
+
+load_dotenv(Path(__file__).parent.parent / ".env")
+
+# A larger instruction-tuned model gives noticeably better policy reasoning and
+# more reliable "I don't know" refusals than the 8B model. Free on NVIDIA NIM.
+CHAT_MODEL = os.environ.get("CHAT_MODEL", "meta/llama-3.3-70b-instruct")
+RETRIEVE_K = 5
+HISTORY_TURNS = 6  # how many prior messages to feed back as conversation memory
+
+SYSTEM_PROMPT = """You are a strict policy assistant. Your ONLY job is to answer questions \
+using the document excerpts provided below as context.
+
+Rules you must NEVER break:
+1. Answer ONLY using information found in the context below.
+2. Do NOT use any outside knowledge, assumptions, or information not present in the context.
+3. Do NOT make up, infer, or guess any information that is not explicitly stated in the context.
+4. If the answer is not present in the context, respond with exactly:
+   "I don't have information about that in the provided documents."
+5. When answering, be concise and quote or closely paraphrase the relevant policy text.
+6. Do not greet the user or add filler phrases.
+7. The conversation history is provided only to resolve references (e.g. "it", "that policy").
+   You must STILL answer the latest question solely from the context excerpts below.
+
+Context from documents:
+{context}
+"""
+
+# Used to turn a follow-up question into a standalone one for retrieval.
+CONDENSE_PROMPT = """Given the conversation history and a follow-up question, rewrite the \
+follow-up as a single standalone question that can be understood without the history.
+Only output the rewritten question — no preamble, no explanation.
+If the question is already standalone, return it unchanged."""
+
+
+def format_docs(docs: list) -> str:
+    parts = []
+    for i, doc in enumerate(docs, 1):
+        source = doc.metadata.get("source", "unknown")
+        page = doc.metadata.get("page", "?")
+        parts.append(f"[Excerpt {i} | File: {source} | Page: {page}]\n{doc.page_content}")
+    return "\n\n---\n\n".join(parts)
+
+
+def _to_lc_messages(history: list[dict]) -> list:
+    """Convert stored {role, content} dicts into LangChain message objects."""
+    msgs = []
+    for h in history[-HISTORY_TURNS:]:
+        if h.get("role") == "user":
+            msgs.append(HumanMessage(content=h.get("content", "")))
+        elif h.get("role") == "assistant":
+            msgs.append(AIMessage(content=h.get("content", "")))
+    return msgs
+
+
+def _sources_from_docs(docs: list) -> list[dict]:
+    seen = set()
+    sources = []
+    for doc in docs:
+        source = doc.metadata.get("source", "unknown")
+        page = doc.metadata.get("page", "?")
+        key = (source, page)
+        if key in seen:
+            continue
+        seen.add(key)
+        raw_imgs = doc.metadata.get("images", "[]")
+        try:
+            images = json.loads(raw_imgs) if isinstance(raw_imgs, str) else raw_imgs
+        except Exception:
+            images = []
+        sources.append({"file": source, "page": page, "images": images})
+    return sources
+
+
+class RagEngine:
+    """Holds the retriever + LLM and answers questions with optional memory."""
+
+    def __init__(self, vector_store: FAISS):
+        self.retriever = vector_store.as_retriever(
+            search_type="similarity",
+            search_kwargs={"k": RETRIEVE_K},
+        )
+        self.llm = ChatNVIDIA(
+            model=CHAT_MODEL,
+            api_key=os.environ["NVIDIA_API_KEY"],
+            temperature=0.0,
+            max_tokens=1024,
+        )
+
+        self.answer_prompt = ChatPromptTemplate.from_messages([
+            ("system", SYSTEM_PROMPT),
+            MessagesPlaceholder("history"),
+            ("human", "{question}"),
+        ])
+
+        self.condense_prompt = ChatPromptTemplate.from_messages([
+            ("system", CONDENSE_PROMPT),
+            MessagesPlaceholder("history"),
+            ("human", "{question}"),
+        ])
+        self.condense_chain = self.condense_prompt | self.llm | StrOutputParser()
+
+    def _standalone_question(self, question: str, history_msgs: list) -> str:
+        if not history_msgs:
+            return question
+        try:
+            rewritten = self.condense_chain.invoke({"history": history_msgs, "question": question})
+            return rewritten.strip() or question
+        except Exception:
+            return question
+
+    def answer(self, question: str, history: list[dict] | None = None) -> tuple[str, list[dict]]:
+        """Return (answer_text, sources). History is a list of {role, content}."""
+        history_msgs = _to_lc_messages(history or [])
+        search_query = self._standalone_question(question, history_msgs)
+
+        docs = self.retriever.invoke(search_query)
+        context = format_docs(docs)
+        sources = _sources_from_docs(docs)
+
+        chain = self.answer_prompt | self.llm | StrOutputParser()
+        answer = chain.invoke({
+            "context": context,
+            "history": history_msgs,
+            "question": question,
+        })
+        return answer, sources
+
+
+def build_engine(vector_store: FAISS) -> RagEngine:
+    return RagEngine(vector_store)

documents/A011-Research-Honorarium-and-Conference-Assistance-Policy-V3.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:732dfcfa873e0cf2cbde055ed485e63e1636dbc6cf495f3c0381cca7fba45b77
+size 278891

documents/A013-Policy-for-Workload-Relief-of-PhD-Scholars-V2.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:461dfaa73def42665a09ca375fcbfe61b5e8fc1b8918b9f668eeee71df8e5295
+size 151344

documents/A014-Policy-for-Honorarium-on-Research-Project-Grants-V1-16-08-2021.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e59f2e75e468dc5822e3f10dbdcf3b086287149d4d9e42e9a0e1816929dc3a4e
+size 43067

documents/A014-Policy-for-Honorarium-on-Research-Project-Grants-V2-08-05-2023.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6575d4cc5e51aaf4071b4e034e0e90523dc0226829476fc317514673ccfa8569
+size 41673

documents/A015-Semester-Rules-for-Post-Graduate-Programs-V2.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9dd903284ad0afdec0f7353a6612984e0032bc177aed4d00bbd1901e502e3272
+size 86177

documents/A024-Policy-for-Transfer-of-Credit-Hours-Student-Mobility-12-08-2021-min.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3e37cfac63e5cffb5944bb76e64addc1421d0869adfbae5c8036311efca9f5a4
+size 55645

documents/A025-Admission-Policy-Fall-2021-12-08-2021-min.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9a06432fdba8ff6fae5b2e08388b80a64b190480d3ce1d41a862b5bf92df0b0a
+size 257233

documents/A026-Policy-for-Role-and-Responsibility-of-Academic-Advisor-V1.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e7e73aa5c6620d716af9de7fbe5ba26000c6a9ef0f88f8bf1f43c0d8b2ea8efd
+size 56946

documents/A028-Internship-Policy-and-Mechanism-V1.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:15369e7cb11dcbfe8f2d6c561f56b00168db88d921e335fc2b24053ec3935e68
+size 123415

documents/A07-Rules-Regulations-for-the-Degree-of-Masters-in-Science-V2.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:59edc50f8e4cd191758229ec2c24aa36682312d53a611a78f1f4a01cddba1850
+size 91612

documents/A08-Rules-and-Regulations-for-the-degree-of-PhD-V5.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7f25dc36501fa2a2b7f5244476dcc988a2cb9ea1fe31d59a9fb212a1434b5e43
+size 87795

documents/A21-Attendance-Policy-for-Online-Classes-Fall-2020-1-converted.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:739a16d52b647a3785dfedc8cf16db6e1440c370202864372b177c0d49d55c96
+size 140968

documents/Academic-Freedom-Policy.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:10bceaff7de2f7df9ca9230027f548b877591cb5add8ed19067fe21209d040ba
+size 117739

documents/Academic-Rules-Regulations.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4dcfbc2094a5bc28691a2f3d51fbe348d779aa9cb6beb2289656f8cef0a48dec
+size 388427

documents/Admission-Policy-2021-2022-12-06-2021-V0-converted-min.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6ccb2c3e47e98fb20c9bc8328043d48ebbeb490c4d153a2c58a424dc429d5849
+size 238362

documents/Admission-Policy-2022-2023-14-11-2022-min.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:883646c4c435e07dbfaa36be162f9dcd59648fe5f2195dd9a4c04c921fac551f
+size 267282

documents/Admission-Policy-2024-2025.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:abfaf5f0a3deb2e42b04cf2c88c98b806bf79be176c184c09d0fd5513075ade2
+size 446737

documents/Amendment_Policy_Sexual_Harassment-ACT-2022.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:01873b14d9030e5b007ffb5073c67d879aec7dc6c930f236203f794fd336cf56
+size 565207

documents/Annex-F-SSUET-MBA-Rules-Regulations-Ver-2.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:caea79e26388e183398432ba75ae3878828cd5bdefeb9a5258685d83427e9d5c
+size 107679

documents/Appeals-Procedure-Policy.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5758411fb218fde918eaa4a6a12f1bdee39e47ea6ded834e3089bc3e498d7fdd
+size 97719

documents/Application-Form-for-Publication-Honorarium-1-converted.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:cb934965735cb85aa66a87f4378d23a22695acb183bb20599251eacfb7ded13d
+size 115719

documents/Arrangements-to-Prevent-Fradulent-Claims-of-Degree-Policy (1).pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:cf4e78c65636f7a2c9d9470d2432720a8471304a21dd890293099e3676f005e8
+size 124016

documents/Arrangements-to-Prevent-Fradulent-Claims-of-Degree-Policy.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:cf4e78c65636f7a2c9d9470d2432720a8471304a21dd890293099e3676f005e8
+size 124016

documents/Conflict-of-Interest-Policy.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:37274cb945db6f812dad9c2807c58a6aa9e99c05cc51c9f37729ff7c59373118
+size 332389

documents/Environment-Health-and-Safety-Policy.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6c8cbafb6d312790c9cefe1162a1ae8bc884b4140aadaa8aaa77e9da34506c65
+size 49024

documents/Evaluation-of-University-Performance-by-Stakeholders-Policy.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:833a1f4a9435ed81817b51b1145a693338af5ecb6cd19f1b4373fdb4927346b9
+size 676313

documents/G009-Employee-Separation-Policy-and-Procedure-V1-14-02-2023.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:79b80a98f25cc42c40f7beb48d42119367b33e19130c5336263adc1846140f5d
+size 94130

documents/G023-Policy-and-Procedure-for-Flexible-Working-Hours-V1-12-11-21.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3fb33dbb16a65d5bcee5b9d73683a554cde4dcaa21305f5e2ee01eab196c1295
+size 80467

documents/G024-Policy-and-Procedure-for-Engaging-Interns.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:597098c0c8099a3d8666011f9a6e30b82c7713e350f47059687a3aac778ecd72
+size 58899

documents/G025-Policy-Against-Drug-and-Tobacco-Abuse-at-SSUET-12-08-2021-min (1).pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:45cb5427ee8c9eb9294a1e723d0c06ca876cce77fa569f8570cd019f26cda499
+size 193738

documents/G025-Policy-Against-Drug-and-Tobacco-Abuse-at-SSUET-12-08-2021-min.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:45cb5427ee8c9eb9294a1e723d0c06ca876cce77fa569f8570cd019f26cda499
+size 193738

documents/G029-Policy-and-Procedures-for-Engaging-Temporary-Teaching-Staff-V2_2.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c604be700b8fd9c8060f9f18e703a592f8216c9768fdc327c4eae40fafe16366
+size 151863

documents/G03-Policy-for-Students-with-Disabilities-V2-12-08-2021-min.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:fefa472f783ddd7ca6577a561adb31764fe2c799c0bf253d5a835df9ba902734
+size 190171

documents/G033-Onboarding-Staff-Induction-Policy-Procedures-V1-11-01-2023.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4f07680f54d654a8e8028d4f0dbb7a7060acb2793be03748dc5699a43817d4a5
+size 95270

documents/G051-Patent-Support-Policy-V1.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3bf4d928fdb0f211cbcc7f6083431ab9ecc0da92d39b63cb7ceeb1ff62e551a1
+size 529925

documents/G30-Policy-for-Authorization-of-Cellular-Phone-and-Calling-Cards-V1-07-12-21.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b271062192268c2a9bbeef1aed99d1846a09183be04281209ba764d9b394d458
+size 42092

documents/Grading-System.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e59b7656ccdd8c1448fe66fb6d4bf3ddc6a9d8de3d80932e304d821f9be6569e
+size 2263152

documents/HEC-Refund-Policy-2024.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6519e9bf56422db3be3855f61eefe92c5ca86973a11b047fe85b06ae757a1dd3
+size 279896

documents/Members-of-Inquiry-Committee-for-Protection-against-Sexual-Harassment-at-SSUET.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a23b704ee66fefbd1428bec9af9f2a6ad46ff635e6b466f06dd5f2fb8e9dc652
+size 25137