Sync from GitHub via hub-sync

.env.example

@@ -0,0 +1,18 @@
+# Google Gemini API Key (get from https://aistudio.google.com/apikey)
+GOOGLE_API_KEY=your_google_api_key_here
+
+# Embedding model (default: all-MiniLM-L6-v2 from sentence-transformers, runs locally)
+EMBEDDING_MODEL=all-MiniLM-L6-v2
+
+# LLM model (default: gemini-2.0-flash)
+LLM_MODEL=gemini-2.0-flash
+
+# Vector store path
+VECTOR_STORE_PATH=data/vector_store
+
+# PDF source directory
+PDF_DIR=data/pdfs
+
+# Chunk size and overlap for text splitting
+CHUNK_SIZE=1000
+CHUNK_OVERLAP=200

.gitattributes

@@ -33,3 +33,36 @@ saved_model/**/* 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
+data/pdfs/StudyOceanPDFs/BIOLOGY_FLASHCARD_FOR_NEET.pdf filter=lfs diff=lfs merge=lfs -text
+data/pdfs/StudyOceanPDFs/CBSE_2026_Class_12_Physics_Set_2_Question_Paper_With_Solutions_PDF.pdf filter=lfs diff=lfs merge=lfs -text
+data/pdfs/StudyOceanPDFs/CENGAGE_IOC_CRUX_BY_studyoceanbooks.PDF filter=lfs diff=lfs merge=lfs -text
+data/pdfs/StudyOceanPDFs/COM_COLLISION_Short_Notes_1_.pdf filter=lfs diff=lfs merge=lfs -text
+data/pdfs/StudyOceanPDFs/Chemistry_Flash_Cards_Colourful_Complete.pdf filter=lfs diff=lfs merge=lfs -text
+data/pdfs/StudyOceanPDFs/Chemistry_Flashcard_for_JEE_NEET.pdf filter=lfs diff=lfs merge=lfs -text
+data/pdfs/StudyOceanPDFs/Chemistry_Formula_Booklet_Hashlearn.pdf filter=lfs diff=lfs merge=lfs -text
+data/pdfs/StudyOceanPDFs/Circular_dyanamic_short_notes_1_.pdf filter=lfs diff=lfs merge=lfs -text
+data/pdfs/StudyOceanPDFs/Circular_motion_in_kinematics_short_notes_1_.pdf filter=lfs diff=lfs merge=lfs -text
+data/pdfs/StudyOceanPDFs/Rotational_motion_short_notes_1_.pdf filter=lfs diff=lfs merge=lfs -text
+data/pdfs/StudyOceanPDFs/Thermal_properties_of_matter_short_notes_.pdf filter=lfs diff=lfs merge=lfs -text
+data/pdfs/StudyOceanPDFs/Units_measurements_and_errors_short_notes_1_.pdf filter=lfs diff=lfs merge=lfs -text
+data/pdfs/StudyOceanPDFs/Vertical_circular_motion_short_notes_1_.pdf filter=lfs diff=lfs merge=lfs -text
+data/pdfs/StudyOceanPDFs/Wave_motion_short_notes_1_.pdf filter=lfs diff=lfs merge=lfs -text
+data/pdfs/StudyOceanPDFs/Work_Power_Energy_Short_Notes_1_.pdf filter=lfs diff=lfs merge=lfs -text
+data/pdfs/StudyOceanPDFs/cbse_class_12_physics_set_1_question_paper_2026_1771575627702.pdf filter=lfs diff=lfs merge=lfs -text
+data/pdfs/StudyOceanPDFs/cbse_class_12_physics_set_2_question_paper_2026_1771575619105.pdf filter=lfs diff=lfs merge=lfs -text
+data/pdfs/StudyOceanPDFs/cbse_class_12_physics_set_3_question_paper_2026_1771575610905.pdf filter=lfs diff=lfs merge=lfs -text
+data/pdfs/StudyOceanPDFs/chapter_10.pdf filter=lfs diff=lfs merge=lfs -text
+data/pdfs/StudyOceanPDFs/chapter_11.pdf filter=lfs diff=lfs merge=lfs -text
+data/pdfs/StudyOceanPDFs/chapter_12.pdf filter=lfs diff=lfs merge=lfs -text
+data/pdfs/StudyOceanPDFs/chapter_13.pdf filter=lfs diff=lfs merge=lfs -text
+data/pdfs/StudyOceanPDFs/chapter_14.pdf filter=lfs diff=lfs merge=lfs -text
+data/pdfs/StudyOceanPDFs/chapter_15.pdf filter=lfs diff=lfs merge=lfs -text
+data/pdfs/StudyOceanPDFs/chapter_2.pdf filter=lfs diff=lfs merge=lfs -text
+data/pdfs/StudyOceanPDFs/chapter_3_1_.pdf filter=lfs diff=lfs merge=lfs -text
+data/pdfs/StudyOceanPDFs/chapter_4.pdf filter=lfs diff=lfs merge=lfs -text
+data/pdfs/StudyOceanPDFs/chapter_5.pdf filter=lfs diff=lfs merge=lfs -text
+data/pdfs/StudyOceanPDFs/chapter_6.pdf filter=lfs diff=lfs merge=lfs -text
+data/pdfs/StudyOceanPDFs/chapter_7.pdf filter=lfs diff=lfs merge=lfs -text
+data/pdfs/StudyOceanPDFs/vector_sheets_Cyan_notes_1_1_.pdf filter=lfs diff=lfs merge=lfs -text
+data/vector_store/index.faiss filter=lfs diff=lfs merge=lfs -text
+logo.png filter=lfs diff=lfs merge=lfs -text

.python-version

@@ -0,0 +1 @@
+3.10

.railwayignore

@@ -0,0 +1,13 @@
+.venv/
+venv/
+.env
+data/pdfs/
+__pycache__/
+*.pyc
+*.pyo
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+.ipynb_checkpoints/
+*.zip

COLAB_GUIDE.md

@@ -0,0 +1,112 @@
+# 🎓 Study Ocean RAG — Google Colab Guide
+
+> Your laptop stays cool. Colab's **T4 GPU** does all the heavy lifting.
+
+---
+
+## 📋 One-Time Setup (First Time Only)
+
+### 1. Upload ZIP to Google Drive
+1. Go to [drive.google.com](https://drive.google.com)
+2. Create a folder: `MyDrive/StudyOcean/`
+3. Upload `StudyOceanPDFs.zip` into that folder
+4. ⏳ Wait for upload to complete (6 GB — may take 15–30 min on slow wifi)
+
+### 2. Get a Gemini API Key (Free)
+1. Go to [aistudio.google.com/apikey](https://aistudio.google.com/apikey)
+2. Click **Create API Key**
+3. Copy the key — you'll paste it into the notebook
+
+### 3. Open the Notebook in Colab
+1. Go to [colab.research.google.com](https://colab.research.google.com)
+2. Click **File → Upload notebook**
+3. Upload `StudyOcean_RAG_Colab.ipynb` from this folder
+
+### 4. Set T4 GPU Runtime
+> **This is critical — without it, ingestion will be very slow!**
+1. In Colab: **Runtime → Change runtime type**
+2. Set Hardware accelerator = **T4 GPU**
+3. Click **Save**
+
+---
+
+## 🚀 Running the Pipeline
+
+### First Time (Fresh Ingestion)
+Run cells in order: **Steps 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → 9 → 10**
+
+| Step | What it does | Time |
+|------|-------------|------|
+| 1 | Verify T4 GPU + mount Drive | 30s |
+| 2 | Install packages | 2–3 min |
+| 3 | Configure settings (paste API key here!) | instant |
+| 4 | Extract PDFs from ZIP | 5–10 min |
+| 5 | Ingest PDFs & build vector store | **30–60 min** |
+| 6 | Save vector store to Drive | 2–5 min |
+| 7 | Test retrieval | instant |
+| 8 | Build RAG chain | instant |
+| 9 | Test full pipeline | 5s |
+| 10 | Launch Gradio chat UI | instant |
+
+### Future Sessions (Vector Store Already Built)
+Run cells: **Steps 1 → 2 → 3 → 11 → 8 → 10**
+
+| Step | What it does | Time |
+|------|-------------|------|
+| 11 | Load saved vector store from Drive | 1–2 min |
+| 8 | Build RAG chain | instant |
+| 10 | Launch Gradio chat UI | instant |
+
+---
+
+## 💻 Running Locally (After Ingestion)
+
+Once the vector store is built, you can run the chat locally:
+
+### Option A — Download via Colab (Step 12)
+- Run **Step 12** in the notebook
+- It downloads `vector_store_export.zip` to your computer
+- Extract it to: `Study_Ocean Rag/data/vector_store/`
+
+### Option B — Download from Google Drive
+- Go to Drive → `StudyOcean/vector_store/`
+- Download the folder
+- Place it at: `Study_Ocean Rag/data/vector_store/`
+
+### Then run locally:
+```bash
+# Make sure .env has your GOOGLE_API_KEY
+python main.py chat    # Web UI at http://localhost:7860
+# OR
+python main.py ask     # Terminal Q&A
+```
+
+---
+
+## ⚡ Performance on T4 GPU
+
+| Task | CPU (your laptop) | T4 GPU (Colab) |
+|------|------------------|----------------|
+| Embedding batch size | 64 | 256 |
+| ~10,000 chunks | ~45 min | ~8 min |
+| ~50,000 chunks | ~4 hours | ~35 min |
+| ~100,000 chunks | ~8 hours | ~70 min |
+
+---
+
+## ❓ Troubleshooting
+
+**"ZIP not found" error**
+→ Update `ZIP_DRIVE_PATH` in Step 3 to match your actual Drive path
+
+**"CUDA not available"**  
+→ You forgot to set T4 GPU runtime! Runtime → Change runtime type → T4 GPU
+
+**Colab session disconnects during ingestion**  
+→ The vector store saves in batches. Re-run from Step 5 — FAISS will rebuild from scratch. Save to Drive often.
+
+**"Invalid API key"**  
+→ Make sure you pasted the full Gemini API key in Step 3
+
+**Gradio link doesn't work**  
+→ Gradio public links expire after 72 hours. Re-run Step 10 to get a new link.

Dockerfile

@@ -0,0 +1,24 @@
+# Use an official Python runtime as a parent image
+FROM python:3.11-slim
+
+# Hugging Face Spaces require running as a non-root user
+RUN useradd -m -u 1000 user
+USER user
+ENV PATH="/home/user/.local/bin:$PATH"
+
+# Set the working directory
+WORKDIR /app
+
+# Copy requirements and install dependencies
+COPY --chown=user ./requirements.txt requirements.txt
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir -r requirements.txt
+
+# Copy the rest of the application
+COPY --chown=user . /app
+
+# Expose the port that Hugging Face Spaces expects (7860)
+EXPOSE 7860
+
+# Command to run the FastAPI app
+CMD ["uvicorn", "api:app", "--host", "0.0.0.0", "--port", "7860"]

Procfile

@@ -0,0 +1 @@
+web: uvicorn api:app --host 0.0.0.0 --port $PORT

README.md

@@ -1,10 +1,8 @@
 ---
-title: Study-Ocean-AI Mentor
-emoji: 📚
-colorFrom: green
-colorTo: blue
+title: Study Ocean RAG
+emoji: 🌊
+colorFrom: blue
+colorTo: indigo
 sdk: docker
-pinned: false
+app_port: 7860
 ---
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

StudyOcean_RAG_Colab.ipynb

@@ -0,0 +1,743 @@
+{
+ "nbformat": 4,
+ "nbformat_minor": 0,
+ "metadata": {
+  "colab": {
+   "provenance": [],
+   "gpuType": "T4",
+   "name": "StudyOcean_RAG_Colab.ipynb"
+  },
+  "kernelspec": {
+   "name": "python3",
+   "display_name": "Python 3"
+  },
+  "language_info": {
+   "name": "python"
+  },
+  "accelerator": "GPU"
+ },
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# 🎓 Study Ocean AI Mentor — Google Colab Pipeline\n",
+    "\n",
+    "> **Run this notebook on Colab with T4 GPU**  \n",
+    "> Runtime → Change runtime type → **T4 GPU**\n",
+    "\n",
+    "### What this notebook does:\n",
+    "1. ✅ Mounts your Google Drive\n",
+    "2. ✅ Installs all dependencies (with `faiss-gpu` for T4 acceleration)\n",
+    "3. ✅ Extracts PDFs from `StudyOceanPDFs.zip`\n",
+    "4. ✅ Runs the ingestion pipeline (GPU-accelerated embeddings)\n",
+    "5. ✅ Saves the FAISS vector store back to Google Drive\n",
+    "6. ✅ Launches the Gradio chat UI with a public shareable link\n",
+    "\n",
+    "---\n",
+    "### 📋 Before you start:\n",
+    "- Upload `StudyOceanPDFs.zip` to your **Google Drive** (e.g., `MyDrive/StudyOcean/StudyOceanPDFs.zip`)\n",
+    "- Get your **Google Gemini API key** from https://aistudio.google.com/apikey\n",
+    "- Set runtime to **T4 GPU**: Runtime → Change runtime type → T4 GPU\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 🔧 Step 1 — Verify GPU & Mount Google Drive"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# ── Verify T4 GPU is available ───────────────────────────────\n",
+    "import subprocess\n",
+    "result = subprocess.run(['nvidia-smi'], capture_output=True, text=True)\n",
+    "print(result.stdout if result.returncode == 0 else \"⚠️ No GPU found! Go to Runtime → Change runtime type → T4 GPU\")\n",
+    "\n",
+    "import torch\n",
+    "print(f\"\\n🔥 PyTorch CUDA available: {torch.cuda.is_available()}\")\n",
+    "if torch.cuda.is_available():\n",
+    "    print(f\"   GPU: {torch.cuda.get_device_name(0)}\")\n",
+    "    print(f\"   VRAM: {torch.cuda.get_device_properties(0).total_memory / 1e9:.1f} GB\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# ── Mount Google Drive ────────────────────────────────────────\n",
+    "from google.colab import drive\n",
+    "drive.mount('/content/drive')\n",
+    "print(\"✅ Google Drive mounted at /content/drive\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 📦 Step 2 — Install Dependencies"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# ── Install all packages ──────────────────────────────────────\n",
+    "# Using faiss-gpu for T4 GPU acceleration during similarity search\n",
+    "!pip install -q \\\n",
+    "    langchain \\\n",
+    "    langchain-community \\\n",
+    "    langchain-core \\\n",
+    "    langchain-google-genai \\\n",
+    "    langchain-huggingface \\\n",
+    "    pymupdf \\\n",
+    "    faiss-gpu \\\n",
+    "    sentence-transformers \\\n",
+    "    google-generativeai \\\n",
+    "    python-dotenv \\\n",
+    "    gradio \\\n",
+    "    tiktoken \\\n",
+    "    accelerate\n",
+    "\n",
+    "print(\"\\n✅ All packages installed!\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## ⚙️ Step 3 — Configure Settings\n",
+    "\n",
+    "> **Edit the variables in this cell before running!**"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import os\n",
+    "\n",
+    "# ════════════════════════════════════════════════════════\n",
+    "#              ✏️  EDIT THESE SETTINGS\n",
+    "# ════════════════════════════════════════════════════════\n",
+    "\n",
+    "# Your Google Gemini API key — get it from https://aistudio.google.com/apikey\n",
+    "GOOGLE_API_KEY = \"\"  # ← PASTE YOUR KEY HERE\n",
+    "\n",
+    "# Path to StudyOceanPDFs.zip in your Google Drive\n",
+    "ZIP_DRIVE_PATH = \"/content/drive/MyDrive/StudyOcean/StudyOceanPDFs.zip\"\n",
+    "\n",
+    "# Where to save the vector store in Google Drive (so it persists!)\n",
+    "VECTOR_STORE_DRIVE_PATH = \"/content/drive/MyDrive/StudyOcean/vector_store\"\n",
+    "\n",
+    "# Embedding model — 'cuda' will use the T4 GPU!\n",
+    "EMBEDDING_MODEL = \"all-MiniLM-L6-v2\"   # Fast & accurate\n",
+    "EMBEDDING_DEVICE = \"cuda\"               # ← T4 GPU acceleration\n",
+    "\n",
+    "# Gemini LLM model\n",
+    "LLM_MODEL = \"gemini-2.0-flash\"\n",
+    "\n",
+    "# Text splitting config\n",
+    "CHUNK_SIZE    = 1000\n",
+    "CHUNK_OVERLAP = 200\n",
+    "\n",
+    "# RAG retrieval\n",
+    "TOP_K = 5\n",
+    "\n",
+    "# ════════════════════════════════════════════════════════\n",
+    "\n",
+    "# Local working paths (inside Colab VM)\n",
+    "PDF_DIR          = \"/content/studyocean_pdfs\"\n",
+    "VECTOR_STORE_LOCAL = \"/content/vector_store\"\n",
+    "\n",
+    "os.makedirs(PDF_DIR, exist_ok=True)\n",
+    "os.makedirs(VECTOR_STORE_LOCAL, exist_ok=True)\n",
+    "\n",
+    "# Set the API key as env var for LangChain\n",
+    "os.environ[\"GOOGLE_API_KEY\"] = GOOGLE_API_KEY\n",
+    "\n",
+    "print(\"✅ Configuration set!\")\n",
+    "print(f\"   ZIP source:    {ZIP_DRIVE_PATH}\")\n",
+    "print(f\"   PDF extract:   {PDF_DIR}\")\n",
+    "print(f\"   Vector store:  {VECTOR_STORE_LOCAL}\")\n",
+    "print(f\"   Drive backup:  {VECTOR_STORE_DRIVE_PATH}\")\n",
+    "print(f\"   Embedding GPU: {EMBEDDING_DEVICE}\")\n",
+    "print(f\"   LLM:           {LLM_MODEL}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 📂 Step 4 — Extract PDFs from ZIP"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import zipfile\n",
+    "import time\n",
+    "\n",
+    "# Check if zip exists\n",
+    "if not os.path.exists(ZIP_DRIVE_PATH):\n",
+    "    print(f\"❌ ZIP not found at: {ZIP_DRIVE_PATH}\")\n",
+    "    print(\"   Please upload StudyOceanPDFs.zip to your Google Drive\")\n",
+    "    print(\"   Then update ZIP_DRIVE_PATH in Step 3.\")\n",
+    "    raise FileNotFoundError(f\"ZIP not found: {ZIP_DRIVE_PATH}\")\n",
+    "\n",
+    "zip_size_gb = os.path.getsize(ZIP_DRIVE_PATH) / 1e9\n",
+    "print(f\"📦 Found ZIP: {zip_size_gb:.2f} GB\")\n",
+    "print(f\"   Extracting to {PDF_DIR} ...\")\n",
+    "print(\"   (This may take a few minutes for large archives)\")\n",
+    "\n",
+    "start = time.time()\n",
+    "with zipfile.ZipFile(ZIP_DRIVE_PATH, 'r') as zf:\n",
+    "    zf.extractall(PDF_DIR)\n",
+    "elapsed = time.time() - start\n",
+    "\n",
+    "# Count extracted PDFs\n",
+    "pdf_count = sum(\n",
+    "    1 for root, _, files in os.walk(PDF_DIR)\n",
+    "    for f in files if f.lower().endswith('.pdf')\n",
+    ")\n",
+    "\n",
+    "print(f\"\\n✅ Extraction complete in {elapsed:.1f}s\")\n",
+    "print(f\"   Found {pdf_count} PDF files\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 🔍 Step 5 — PDF Ingestion Pipeline (GPU-Accelerated)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import fitz  # PyMuPDF\n",
+    "from langchain.text_splitter import RecursiveCharacterTextSplitter\n",
+    "from langchain_community.vectorstores import FAISS\n",
+    "from langchain_huggingface import HuggingFaceEmbeddings\n",
+    "from langchain.docstore.document import Document\n",
+    "\n",
+    "\n",
+    "def collect_pdf_paths(pdf_dir):\n",
+    "    \"\"\"Recursively collect all PDF paths.\"\"\"\n",
+    "    paths = []\n",
+    "    for root, _, files in os.walk(pdf_dir):\n",
+    "        for f in files:\n",
+    "            if f.lower().endswith('.pdf'):\n",
+    "                paths.append(os.path.join(root, f))\n",
+    "    return sorted(paths)\n",
+    "\n",
+    "\n",
+    "def extract_text(pdf_path):\n",
+    "    \"\"\"Extract text from a PDF using PyMuPDF.\"\"\"\n",
+    "    text = \"\"\n",
+    "    try:\n",
+    "        doc = fitz.open(pdf_path)\n",
+    "        for page in doc:\n",
+    "            text += page.get_text()\n",
+    "        doc.close()\n",
+    "    except Exception as e:\n",
+    "        print(f\"  ⚠ Error reading {os.path.basename(pdf_path)}: {e}\")\n",
+    "    return text\n",
+    "\n",
+    "\n",
+    "def build_documents(pdf_paths):\n",
+    "    \"\"\"Extract and chunk all PDFs into LangChain Documents.\"\"\"\n",
+    "    splitter = RecursiveCharacterTextSplitter(\n",
+    "        chunk_size=CHUNK_SIZE,\n",
+    "        chunk_overlap=CHUNK_OVERLAP,\n",
+    "        separators=[\"\\n\\n\", \"\\n\", \". \", \" \", \"\"],\n",
+    "    )\n",
+    "    all_docs = []\n",
+    "    skipped = 0\n",
+    "\n",
+    "    for i, path in enumerate(pdf_paths, 1):\n",
+    "        rel = os.path.relpath(path, PDF_DIR)\n",
+    "        parts = rel.replace(\"\\\\\", \"/\").split(\"/\")\n",
+    "        subject = parts[0] if len(parts) > 1 else \"General\"\n",
+    "\n",
+    "        if i % 50 == 0 or i == 1:\n",
+    "            print(f\"  [{i}/{len(pdf_paths)}] {rel}\")\n",
+    "\n",
+    "        text = extract_text(path)\n",
+    "        if not text.strip():\n",
+    "            skipped += 1\n",
+    "            continue\n",
+    "\n",
+    "        chunks = splitter.create_documents(\n",
+    "            texts=[text],\n",
+    "            metadatas=[{\"source\": rel, \"filename\": os.path.basename(path), \"subject\": subject}]\n",
+    "        )\n",
+    "        all_docs.extend(chunks)\n",
+    "\n",
+    "    print(f\"\\n  Skipped (image/scanned PDFs): {skipped}\")\n",
+    "    return all_docs\n",
+    "\n",
+    "\n",
+    "# ── Step 5a: Collect PDFs ────────────────────────────────────\n",
+    "print(\"=\" * 60)\n",
+    "print(\"📄 PHASE 1: Collecting & chunking PDFs\")\n",
+    "print(\"=\" * 60)\n",
+    "pdf_paths = collect_pdf_paths(PDF_DIR)\n",
+    "print(f\"   {len(pdf_paths)} PDFs found\")\n",
+    "\n",
+    "t0 = time.time()\n",
+    "documents = build_documents(pdf_paths)\n",
+    "t_extract = time.time() - t0\n",
+    "\n",
+    "print(f\"\\n✅ Created {len(documents)} chunks in {t_extract:.1f}s\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# ── Step 5b: Load Embedding Model onto T4 GPU ────────────────\n",
+    "print(\"=\" * 60)\n",
+    "print(f\"🧠 PHASE 2: Loading embedding model on {EMBEDDING_DEVICE.upper()}\")\n",
+    "print(\"=\" * 60)\n",
+    "\n",
+    "import torch\n",
+    "device = EMBEDDING_DEVICE if torch.cuda.is_available() else \"cpu\"\n",
+    "if device == \"cpu\" and EMBEDDING_DEVICE == \"cuda\":\n",
+    "    print(\"⚠️  CUDA not available, falling back to CPU\")\n",
+    "\n",
+    "embeddings = HuggingFaceEmbeddings(\n",
+    "    model_name=EMBEDDING_MODEL,\n",
+    "    model_kwargs={\"device\": device},\n",
+    "    encode_kwargs={\"normalize_embeddings\": True, \"batch_size\": 256},  # Larger batch on GPU!\n",
+    ")\n",
+    "\n",
+    "print(f\"✅ Embedding model loaded on {device.upper()}\")\n",
+    "print(f\"   Model: {EMBEDDING_MODEL}\")\n",
+    "print(f\"   Batch size: 256 (optimized for T4)\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# ── Step 5c: Build FAISS Vector Store ───────────────────────\n",
+    "print(\"=\" * 60)\n",
+    "print(f\"📊 PHASE 3: Building FAISS vector store ({len(documents)} chunks)\")\n",
+    "print(\"=\" * 60)\n",
+    "\n",
+    "BATCH_SIZE = 1000  # Larger batches since we have GPU\n",
+    "vector_store = None\n",
+    "t0 = time.time()\n",
+    "\n",
+    "total_batches = (len(documents) + BATCH_SIZE - 1) // BATCH_SIZE\n",
+    "for i in range(0, len(documents), BATCH_SIZE):\n",
+    "    batch = documents[i : i + BATCH_SIZE]\n",
+    "    batch_num = (i // BATCH_SIZE) + 1\n",
+    "\n",
+    "    elapsed = time.time() - t0\n",
+    "    rate = (i + 1) / elapsed if elapsed > 0 else 0\n",
+    "    eta = (len(documents) - i) / rate if rate > 0 else 0\n",
+    "    print(f\"  Batch {batch_num:3d}/{total_batches} | {len(batch)} chunks | \"\n",
+    "          f\"ETA: {eta/60:.1f} min\")\n",
+    "\n",
+    "    if vector_store is None:\n",
+    "        vector_store = FAISS.from_documents(batch, embeddings)\n",
+    "    else:\n",
+    "        batch_store = FAISS.from_documents(batch, embeddings)\n",
+    "        vector_store.merge_from(batch_store)\n",
+    "\n",
+    "t_embed = time.time() - t0\n",
+    "print(f\"\\n✅ Vector store built in {t_embed/60:.1f} minutes\")\n",
+    "print(f\"   Total vectors: {vector_store.index.ntotal}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 💾 Step 6 — Save Vector Store to Google Drive"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import shutil\n",
+    "\n",
+    "# Save locally first\n",
+    "print(\"💾 Saving vector store locally...\")\n",
+    "vector_store.save_local(VECTOR_STORE_LOCAL)\n",
+    "print(f\"   ✅ Saved to {VECTOR_STORE_LOCAL}\")\n",
+    "\n",
+    "# Copy to Google Drive for persistence\n",
+    "print(\"\\n☁️  Copying to Google Drive...\")\n",
+    "os.makedirs(VECTOR_STORE_DRIVE_PATH, exist_ok=True)\n",
+    "\n",
+    "for fname in os.listdir(VECTOR_STORE_LOCAL):\n",
+    "    src = os.path.join(VECTOR_STORE_LOCAL, fname)\n",
+    "    dst = os.path.join(VECTOR_STORE_DRIVE_PATH, fname)\n",
+    "    shutil.copy2(src, dst)\n",
+    "    size = os.path.getsize(dst) / 1e6\n",
+    "    print(f\"   ✅ {fname}  ({size:.1f} MB)\")\n",
+    "\n",
+    "print(f\"\\n🎉 Vector store saved to Google Drive!\")\n",
+    "print(f\"   Path: {VECTOR_STORE_DRIVE_PATH}\")\n",
+    "print(f\"   Total vectors: {vector_store.index.ntotal}\")\n",
+    "print(\"\\n📌 You can now download this folder to your laptop\")\n",
+    "print(\"   and place it at: Study_Ocean Rag/data/vector_store/\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 🧪 Step 7 — Test the Vector Store (Quick Sanity Check)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# ── Quick retrieval test ─────────────────────────────────────\n",
+    "test_question = \"What is Newton's second law of motion?\"\n",
+    "print(f\"🔍 Test query: '{test_question}'\\n\")\n",
+    "\n",
+    "results = vector_store.similarity_search(test_question, k=3)\n",
+    "for i, doc in enumerate(results, 1):\n",
+    "    print(f\"--- Result {i} ---\")\n",
+    "    print(f\"Subject : {doc.metadata.get('subject', 'N/A')}\")\n",
+    "    print(f\"File    : {doc.metadata.get('filename', 'N/A')}\")\n",
+    "    print(f\"Preview : {doc.page_content[:200]}...\")\n",
+    "    print()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 🤖 Step 8 — Build the RAG Chain (Gemini + FAISS)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from langchain_google_genai import ChatGoogleGenerativeAI\n",
+    "from langchain.chains import RetrievalQA\n",
+    "from langchain.prompts import PromptTemplate\n",
+    "\n",
+    "# Validate API key\n",
+    "if not GOOGLE_API_KEY or GOOGLE_API_KEY == \"\":\n",
+    "    print(\"❌ GOOGLE_API_KEY is not set! Go back to Step 3 and paste your key.\")\n",
+    "    raise ValueError(\"Missing GOOGLE_API_KEY\")\n",
+    "\n",
+    "# ── Student Mentor Prompt ────────────────────────────────────\n",
+    "MENTOR_PROMPT = PromptTemplate(\n",
+    "    input_variables=[\"context\", \"question\"],\n",
+    "    template=\"\"\"You are **Study Ocean AI Mentor** — a friendly, patient, and knowledgeable tutor who helps students understand their study material deeply.\n",
+    "\n",
+    "Your role:\n",
+    "- Solve student doubts with clear, step-by-step explanations\n",
+    "- Use simple language that students can easily understand\n",
+    "- Provide examples and analogies when helpful\n",
+    "- If the answer is in the context, use it; if not, say so honestly\n",
+    "- Encourage students and make learning enjoyable\n",
+    "\n",
+    "**Guidelines:**\n",
+    "1. Start with a brief, direct answer, then explain in detail\n",
+    "2. Use bullet points, numbered steps, or tables for clarity\n",
+    "3. For math/science problems, show the solution step by step\n",
+    "4. Mention which topic/chapter the information relates to when possible\n",
+    "5. If the topic isn't covered, say: \"This isn't in your study materials, but here's what I know...\"\n",
+    "\n",
+    "---\n",
+    "📚 **Relevant Study Material:**\n",
+    "{context}\n",
+    "\n",
+    "---\n",
+    "🙋 **Student's Question:** {question}\n",
+    "\n",
+    "---\n",
+    "🎓 **Mentor's Response:**\n",
+    "\"\"\"\n",
+    ")\n",
+    "\n",
+    "# ── Initialize LLM ───────────────────────────────────────────\n",
+    "llm = ChatGoogleGenerativeAI(\n",
+    "    model=LLM_MODEL,\n",
+    "    google_api_key=GOOGLE_API_KEY,\n",
+    "    temperature=0.3,\n",
+    "    max_output_tokens=2048,\n",
+    "    convert_system_message_to_human=True,\n",
+    ")\n",
+    "\n",
+    "# ── Build RAG Chain ──────────────────────────────────────────\n",
+    "retriever = vector_store.as_retriever(\n",
+    "    search_type=\"similarity\",\n",
+    "    search_kwargs={\"k\": TOP_K},\n",
+    ")\n",
+    "\n",
+    "rag_chain = RetrievalQA.from_chain_type(\n",
+    "    llm=llm,\n",
+    "    chain_type=\"stuff\",\n",
+    "    retriever=retriever,\n",
+    "    return_source_documents=True,\n",
+    "    chain_type_kwargs={\"prompt\": MENTOR_PROMPT},\n",
+    ")\n",
+    "\n",
+    "print(\"✅ RAG Chain ready!\")\n",
+    "print(f\"   LLM: {LLM_MODEL}\")\n",
+    "print(f\"   Retriever: top-{TOP_K} chunks\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 🧪 Step 9 — Test the Full RAG Pipeline"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def ask(question):\n",
+    "    \"\"\"Ask the mentor a question.\"\"\"\n",
+    "    print(f\"\\n🙋 Question: {question}\")\n",
+    "    print(\"🔍 Searching study material...\\n\")\n",
+    "    result = rag_chain.invoke({\"query\": question})\n",
+    "    print(\"🎓 Mentor's Answer:\")\n",
+    "    print(\"─\" * 60)\n",
+    "    print(result[\"result\"])\n",
+    "    print(\"─\" * 60)\n",
+    "    print(\"\\n📖 Sources:\")\n",
+    "    seen = set()\n",
+    "    for doc in result.get(\"source_documents\", []):\n",
+    "        key = doc.metadata.get(\"source\", \"?\")\n",
+    "        if key not in seen:\n",
+    "            seen.add(key)\n",
+    "            print(f\"  [{doc.metadata.get('subject','?')}] {doc.metadata.get('filename','?')}\")\n",
+    "\n",
+    "# Test it!\n",
+    "ask(\"Explain Newton's laws of motion with examples\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 🌐 Step 10 — Launch Gradio Chat UI (Public Link)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import gradio as gr\n",
+    "\n",
+    "CUSTOM_CSS = \"\"\"\n",
+    ".gradio-container {\n",
+    "    max-width: 900px !important;\n",
+    "    margin: auto !important;\n",
+    "    font-family: 'Inter', 'Segoe UI', sans-serif !important;\n",
+    "}\n",
+    ".header-section {\n",
+    "    text-align: center;\n",
+    "    padding: 20px 0 10px;\n",
+    "    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);\n",
+    "    border-radius: 16px;\n",
+    "    margin-bottom: 20px;\n",
+    "    color: white;\n",
+    "}\n",
+    ".header-section h1 { font-size: 2em; margin: 0; color: white !important; }\n",
+    ".header-section p  { opacity: 0.9; margin: 5px 0 0; font-size: 1.05em; color: #e8e8ff !important; }\n",
+    ".chatbot { border-radius: 12px !important; min-height: 450px !important; }\n",
+    ".primary-btn {\n",
+    "    background: linear-gradient(135deg, #667eea, #764ba2) !important;\n",
+    "    border: none !important; color: white !important;\n",
+    "    border-radius: 10px !important; font-weight: 600 !important;\n",
+    "}\n",
+    ".primary-btn:hover { opacity: 0.9 !important; transform: translateY(-1px); }\n",
+    "\"\"\"\n",
+    "\n",
+    "def format_sources(docs):\n",
+    "    if not docs: return \"\"\n",
+    "    seen, lines = set(), [\"\\n\\n---\\n📖 **Sources Referenced:**\\n\"]\n",
+    "    for doc in docs:\n",
+    "        key = f\"{doc.metadata.get('subject','?')}/{doc.metadata.get('source','?')}\"\n",
+    "        if key not in seen:\n",
+    "            seen.add(key)\n",
+    "            lines.append(f\"**•** `{doc.metadata.get('subject','?')}` → _{doc.metadata.get('filename','?')}_\")\n",
+    "    return \"\\n\".join(lines)\n",
+    "\n",
+    "def respond(message, history):\n",
+    "    if not message.strip():\n",
+    "        return \"\", history\n",
+    "    result = rag_chain.invoke({\"query\": message})\n",
+    "    answer = result[\"result\"] + format_sources(result.get(\"source_documents\", []))\n",
+    "    history.append((message, answer))\n",
+    "    return \"\", history\n",
+    "\n",
+    "def clear_chat():\n",
+    "    return [], \"\"\n",
+    "\n",
+    "with gr.Blocks(css=CUSTOM_CSS, title=\"Study Ocean AI Mentor\", theme=gr.themes.Soft()) as demo:\n",
+    "    gr.HTML(\"\"\"\n",
+    "    <div class=\"header-section\">\n",
+    "        <h1>🎓 Study Ocean AI Mentor</h1>\n",
+    "        <p>Ask any doubt from your study material — I'll explain it step by step!</p>\n",
+    "    </div>\n",
+    "    \"\"\")\n",
+    "    chatbot = gr.Chatbot(\n",
+    "        label=\"💬 Chat with Your Mentor\",\n",
+    "        elem_classes=[\"chatbot\"],\n",
+    "        height=480,\n",
+    "        show_copy_button=True,\n",
+    "        bubble_full_width=False,\n",
+    "        avatar_images=(None, \"https://api.dicebear.com/7.x/bottts/svg?seed=mentor&backgroundColor=6366f1\"),\n",
+    "    )\n",
+    "    with gr.Row():\n",
+    "        msg = gr.Textbox(\n",
+    "            placeholder=\"Type your doubt here... e.g., 'Explain Newton's third law'\",\n",
+    "            scale=5, lines=1, max_lines=3, show_label=False, container=False,\n",
+    "        )\n",
+    "        submit_btn = gr.Button(\"Ask 🚀\", elem_classes=[\"primary-btn\"], scale=1)\n",
+    "    with gr.Row():\n",
+    "        clear_btn = gr.Button(\"🗑️ Clear Chat\", size=\"sm\")\n",
+    "\n",
+    "    gr.Examples(\n",
+    "        examples=[\n",
+    "            \"What are Newton's laws of motion? Explain with examples.\",\n",
+    "            \"Explain the difference between mitosis and meiosis.\",\n",
+    "            \"What is the Pythagorean theorem and how do I apply it?\",\n",
+    "            \"Explain the concept of supply and demand in economics.\",\n",
+    "            \"What are the key features of the Indian Constitution?\",\n",
+    "        ],\n",
+    "        inputs=msg, label=\"💡 Try these example questions:\",\n",
+    "    )\n",
+    "\n",
+    "    msg.submit(respond, [msg, chatbot], [msg, chatbot])\n",
+    "    submit_btn.click(respond, [msg, chatbot], [msg, chatbot])\n",
+    "    clear_btn.click(clear_chat, outputs=[chatbot, msg])\n",
+    "\n",
+    "# Launch with share=True to get a public Gradio URL!\n",
+    "demo.launch(share=True, debug=False)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## 💻 Step 11 — Use Pre-built Vector Store (Skip Re-ingestion)\n",
+    "\n",
+    "> **Run this cell INSTEAD of Steps 4–6 if you already have a saved vector store on Drive**\n",
+    "> This lets you skip the ~1 hour ingestion on future sessions!"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# ── Load existing vector store from Drive ────────────────────\n",
+    "# ⚠️ Only run this cell if you've already done ingestion before!\n",
+    "# Skip this if running ingestion fresh (Steps 4-6).\n",
+    "\n",
+    "from langchain_community.vectorstores import FAISS\n",
+    "from langchain_huggingface import HuggingFaceEmbeddings\n",
+    "import torch, os\n",
+    "\n",
+    "device = \"cuda\" if torch.cuda.is_available() else \"cpu\"\n",
+    "print(f\"🔧 Loading embeddings on {device.upper()}...\")\n",
+    "\n",
+    "embeddings = HuggingFaceEmbeddings(\n",
+    "    model_name=EMBEDDING_MODEL,\n",
+    "    model_kwargs={\"device\": device},\n",
+    "    encode_kwargs={\"normalize_embeddings\": True},\n",
+    ")\n",
+    "\n",
+    "# Try Drive path first, fall back to local\n",
+    "store_path = VECTOR_STORE_DRIVE_PATH if os.path.exists(VECTOR_STORE_DRIVE_PATH) else VECTOR_STORE_LOCAL\n",
+    "print(f\"📂 Loading vector store from: {store_path}\")\n",
+    "\n",
+    "vector_store = FAISS.load_local(\n",
+    "    store_path,\n",
+    "    embeddings,\n",
+    "    allow_dangerous_deserialization=True,\n",
+    ")\n",
+    "\n",
+    "print(f\"✅ Loaded! Total vectors: {vector_store.index.ntotal}\")\n",
+    "print(\"   Now run Steps 8 → 10 to start chatting!\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## 📥 Step 12 — Download Vector Store to Your Laptop\n",
+    "\n",
+    "> Run this to zip and download the vector store directly to your PC (no Drive needed)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import shutil\n",
+    "from google.colab import files\n",
+    "\n",
+    "# Zip the vector store\n",
+    "print(\"📦 Zipping vector store...\")\n",
+    "zip_path = \"/content/vector_store_export.zip\"\n",
+    "shutil.make_archive(\"/content/vector_store_export\", 'zip', VECTOR_STORE_LOCAL)\n",
+    "\n",
+    "size_mb = os.path.getsize(zip_path) / 1e6\n",
+    "print(f\"   ZIP size: {size_mb:.1f} MB\")\n",
+    "\n",
+    "# Download to local machine\n",
+    "print(\"⬇️  Downloading to your computer...\")\n",
+    "files.download(zip_path)\n",
+    "print(\"\\n✅ Download started!\")\n",
+    "print(\"   Extract to: Study_Ocean Rag/data/vector_store/\")\n",
+    "print(\"   Then run locally: python main.py chat\")"
+   ]
+  }
+ ]
+}

api.py

@@ -0,0 +1,65 @@
+import os
+
+# memory saving trick for Render 512MB limit!
+os.environ["OMP_NUM_THREADS"] = "1"
+os.environ["MKL_NUM_THREADS"] = "1"
+os.environ["OPENBLAS_NUM_THREADS"] = "1"
+os.environ["VECLIB_MAXIMUM_THREADS"] = "1"
+os.environ["NUMEXPR_NUM_THREADS"] = "1"
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse
+from pydantic import BaseModel
+from rag_chain import get_chain, ask_question
+import uvicorn
+
+
+app = FastAPI(title="Study Ocean RAG API")
+
+# Allow requests from your frontend (CORS)
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],  # In production, replace with your frontend URL
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+@app.get("/")
+def serve_frontend():
+    return FileResponse("frontend_demo.html")
+
+@app.get("/logo.png")
+def serve_logo():
+    if os.path.exists("logo.png"):
+        return FileResponse("logo.png")
+    return {"error": "Logo not found"}
+
+print("🔄 Initializing Study Ocean AI Mentor...")
+chain = get_chain()
+print("✅ API Ready to answer student doubts!")
+
+class Query(BaseModel):
+    question: str
+
+@app.post("/api/ask")
+def ask(query: Query):
+    try:
+        # Pass the question to your LangChain RAG
+        result = ask_question(chain, query.question)
+        return {
+            "answer": result["answer"],
+            "sources": result["sources"]
+        }
+    except Exception as e:
+        import traceback
+        traceback.print_exc()
+        return {
+            "answer": f"Backend Error: {str(e)}",
+            "sources": []
+        }
+
+if __name__ == "__main__":
+    # Run the API on port 8000
+    uvicorn.run(app, host="0.0.0.0", port=8000)

app.py

@@ -0,0 +1,203 @@
+"""
+Study Ocean AI Mentor — Gradio Web Interface
+
+A beautiful, student-friendly chat interface for the RAG-based
+doubt-solving mentor. Built with Gradio for easy deployment.
+"""
+
+import gradio as gr
+from rag_chain import get_chain, ask_question
+
+# ─── Custom CSS for Premium Look ────────────────────────────
+CUSTOM_CSS = """
+/* Global */
+.gradio-container {
+    max-width: 900px !important;
+    margin: auto !important;
+    font-family: 'Inter', 'Segoe UI', sans-serif !important;
+}
+
+/* Header */
+.header-section {
+    text-align: center;
+    padding: 20px 0 10px;
+    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+    border-radius: 16px;
+    margin-bottom: 20px;
+    color: white;
+}
+
+.header-section h1 {
+    font-size: 2em;
+    margin: 0;
+    color: white !important;
+}
+
+.header-section p {
+    opacity: 0.9;
+    margin: 5px 0 0;
+    font-size: 1.05em;
+    color: #e8e8ff !important;
+}
+
+/* Chat area */
+.chatbot {
+    border-radius: 12px !important;
+    border: 1px solid #e2e8f0 !important;
+    min-height: 450px !important;
+}
+
+/* Source cards */
+.source-card {
+    background: #f8fafc;
+    border: 1px solid #e2e8f0;
+    border-radius: 8px;
+    padding: 10px 14px;
+    margin: 4px 0;
+    font-size: 0.9em;
+}
+
+.source-card strong {
+    color: #6366f1;
+}
+
+/* Override dark mode */
+.dark .source-card {
+    background: #1e293b;
+    border-color: #334155;
+}
+
+/* Buttons */
+.primary-btn {
+    background: linear-gradient(135deg, #667eea, #764ba2) !important;
+    border: none !important;
+    color: white !important;
+    border-radius: 10px !important;
+    font-weight: 600 !important;
+    padding: 10px 24px !important;
+}
+
+.primary-btn:hover {
+    opacity: 0.9 !important;
+    transform: translateY(-1px);
+    box-shadow: 0 4px 12px rgba(102, 126, 234, 0.4) !important;
+}
+"""
+
+# ─── Initialize chain on startup ────────────────────────────
+print("🔄 Initializing Study Ocean AI Mentor...")
+chain = get_chain()
+print("✅ Ready to answer student doubts!\n")
+
+
+def format_sources(sources: list) -> str:
+    """Format source documents into a readable string."""
+    if not sources:
+        return ""
+    
+    lines = ["\n\n---\n📖 **Sources Referenced:**\n"]
+    for i, src in enumerate(sources, 1):
+        lines.append(f"**{i}.** `{src['subject']}` → _{src['file']}_")
+    return "\n".join(lines)
+
+
+def respond(message: str, chat_history: list) -> tuple:
+    """Handle a student's question and return the mentor's response."""
+    if not message.strip():
+        return "", chat_history
+
+    # Get answer from RAG chain
+    result = ask_question(chain, message)
+    answer = result["answer"]
+    sources = result["sources"]
+
+    # Append source references to the answer
+    answer_with_sources = answer + format_sources(sources)
+
+    # Update chat history
+    chat_history.append((message, answer_with_sources))
+    
+    return "", chat_history
+
+
+def clear_chat():
+    """Clear the chat history."""
+    return [], ""
+
+
+# ─── Build Gradio Interface ─────────────────────────────────
+with gr.Blocks(title="Study Ocean AI Mentor") as app:
+    
+    # Header
+    gr.HTML("""
+    <div class="header-section">
+        <h1>🎓 Study Ocean AI Mentor</h1>
+        <p>Ask any doubt from your study material — I'll explain it step by step!</p>
+    </div>
+    """)
+
+    # Chatbot
+    chatbot = gr.Chatbot(
+        label="💬 Chat with Your Mentor",
+        elem_classes=["chatbot"],
+        height=480,
+        avatar_images=(None, "https://api.dicebear.com/7.x/bottts/svg?seed=mentor&backgroundColor=6366f1"),
+    )
+
+    # Input area
+    with gr.Row():
+        msg = gr.Textbox(
+            placeholder="Type your doubt here... e.g., 'Explain Newton's third law with examples'",
+            label="Your Question",
+            scale=5,
+            lines=1,
+            max_lines=3,
+            show_label=False,
+            container=False,
+        )
+        submit_btn = gr.Button("Ask 🚀", elem_classes=["primary-btn"], scale=1)
+
+    # Action buttons
+    with gr.Row():
+        clear_btn = gr.Button("🗑️ Clear Chat", size="sm")
+
+    # Example questions
+    gr.Examples(
+        examples=[
+            "What are Newton's laws of motion? Explain with examples.",
+            "Explain the difference between mitosis and meiosis.",
+            "What is the Pythagorean theorem and how do I use it?",
+            "Explain the concept of supply and demand in economics.",
+            "What are the key features of the Indian Constitution?",
+            "Solve: Find the derivative of f(x) = 3x² + 2x - 5",
+        ],
+        inputs=msg,
+        label="💡 Try these example questions:",
+    )
+
+    # Tips section
+    with gr.Accordion("📌 Tips for Better Answers", open=False):
+        gr.Markdown("""
+        - **Be specific**: Instead of "explain physics", ask "explain projectile motion with examples"
+        - **Mention the topic**: "In organic chemistry, what is an SN2 reaction?"  
+        - **Ask for steps**: "Solve step by step: integrate sin(x)cos(x) dx"
+        - **Request comparisons**: "Compare TCP and UDP protocols"
+        - **Ask for formulas**: "List all the trigonometric identities"
+        """)
+
+    # Event handlers
+    msg.submit(respond, [msg, chatbot], [msg, chatbot])
+    submit_btn.click(respond, [msg, chatbot], [msg, chatbot])
+    clear_btn.click(clear_chat, outputs=[chatbot, msg])
+
+
+# ─── Launch ─────────────────────────────────────────────────
+if __name__ == "__main__":
+    app.launch(
+        server_name="0.0.0.0",
+        server_port=7860,
+        share=False,
+        show_error=True,
+        css=CUSTOM_CSS,
+        theme=gr.themes.Soft(),
+    )

config.py

@@ -0,0 +1,30 @@
+"""
+Configuration module for Study Ocean RAG Student Mentor.
+Loads environment variables and provides default settings.
+"""
+
+import os
+from dotenv import load_dotenv
+
+load_dotenv()
+
+# ─── API Keys ────────────────────────────────────────────────
+GOOGLE_API_KEY = os.getenv("GOOGLE_API_KEY", "")
+
+# ─── Model Configuration ────────────────────────────────────
+EMBEDDING_MODEL = os.getenv("EMBEDDING_MODEL", "all-MiniLM-L6-v2")
+LLM_MODEL = os.getenv("LLM_MODEL", "gemini-2.0-flash")
+
+# ─── Paths ───────────────────────────────────────────────────
+BASE_DIR = os.path.dirname(os.path.abspath(__file__))
+PDF_DIR = os.path.join(BASE_DIR, os.getenv("PDF_DIR", "data/pdfs"))
+VECTOR_STORE_PATH = os.path.join(BASE_DIR, os.getenv("VECTOR_STORE_PATH", "data/vector_store"))
+
+# ─── Text Splitting ─────────────────────────────────────────
+CHUNK_SIZE = int(os.getenv("CHUNK_SIZE", "1000"))
+CHUNK_OVERLAP = int(os.getenv("CHUNK_OVERLAP", "200"))
+
+# ─── RAG Parameters ─────────────────────────────────────────
+TOP_K_RESULTS = 2          # Number of relevant chunks to retrieve (lowered for faster responses)
+TEMPERATURE = 0.3          # LLM temperature (lower = more focused)
+MAX_OUTPUT_TOKENS = 2048   # Max tokens in LLM response

data/pdfs/StudyOceanPDFs/BIOLOGY_FLASHCARD_FOR_NEET.pdf

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

data/pdfs/StudyOceanPDFs/CBSE_2026_Class_12_Physics_Set_2_Question_Paper_With_Solutions_PDF.pdf

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

data/pdfs/StudyOceanPDFs/CENGAGE_IOC_CRUX_BY_studyoceanbooks.PDF

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

data/pdfs/StudyOceanPDFs/COM_COLLISION_Short_Notes_1_.pdf

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

data/pdfs/StudyOceanPDFs/Chemistry_Flash_Cards_Colourful_Complete.pdf

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

data/pdfs/StudyOceanPDFs/Chemistry_Flashcard_for_JEE_NEET.pdf

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

data/pdfs/StudyOceanPDFs/Chemistry_Formula_Booklet_Hashlearn.pdf

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

data/pdfs/StudyOceanPDFs/Circular_dyanamic_short_notes_1_.pdf

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

data/pdfs/StudyOceanPDFs/Circular_motion_in_kinematics_short_notes_1_.pdf

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

data/pdfs/StudyOceanPDFs/Rotational_motion_short_notes_1_.pdf

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

data/pdfs/StudyOceanPDFs/Thermal_properties_of_matter_short_notes_.pdf

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

data/pdfs/StudyOceanPDFs/Units_measurements_and_errors_short_notes_1_.pdf

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

data/pdfs/StudyOceanPDFs/Vertical_circular_motion_short_notes_1_.pdf

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

data/pdfs/StudyOceanPDFs/Wave_motion_short_notes_1_.pdf

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

data/pdfs/StudyOceanPDFs/Work_Power_Energy_Short_Notes_1_.pdf

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

data/pdfs/StudyOceanPDFs/cbse_class_12_physics_set_1_question_paper_2026_1771575627702.pdf

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

data/pdfs/StudyOceanPDFs/cbse_class_12_physics_set_2_question_paper_2026_1771575619105.pdf

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

data/pdfs/StudyOceanPDFs/cbse_class_12_physics_set_3_question_paper_2026_1771575610905.pdf

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

data/pdfs/StudyOceanPDFs/chapter_10.pdf

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

data/pdfs/StudyOceanPDFs/chapter_11.pdf

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

data/pdfs/StudyOceanPDFs/chapter_12.pdf

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

data/pdfs/StudyOceanPDFs/chapter_13.pdf

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

data/pdfs/StudyOceanPDFs/chapter_14.pdf

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

data/pdfs/StudyOceanPDFs/chapter_15.pdf

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

data/pdfs/StudyOceanPDFs/chapter_2.pdf

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

data/pdfs/StudyOceanPDFs/chapter_3_1_.pdf

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

data/pdfs/StudyOceanPDFs/chapter_4.pdf

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

data/pdfs/StudyOceanPDFs/chapter_5.pdf

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

data/pdfs/StudyOceanPDFs/chapter_6.pdf

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

data/pdfs/StudyOceanPDFs/chapter_7.pdf

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

data/pdfs/StudyOceanPDFs/vector_sheets_Cyan_notes_1_1_.pdf

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

data/vector_store/index.faiss

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

data/vector_store/index.pkl

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

frontend_demo.html

@@ -0,0 +1,267 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Study Ocean | AI Mentor</title>
+    <!-- GSAP for Gen-Z Animations -->
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.2/gsap.min.js"></script>
+    <link href="https://fonts.googleapis.com/css2?family=Outfit:wght@300;500;700&display=swap" rel="stylesheet">
+    
+    <!-- MathJax for rendering Math Equations ($ and $$) -->
+    <script>
+      MathJax = {
+        tex: { inlineMath: [['$', '$'], ['\\(', '\\)']] }
+      };
+    </script>
+    <script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml.js"></script>
+    
+    <style>
+        :root {
+            --bg-color: #050505;
+            --glass-bg: rgba(255, 255, 255, 0.03);
+            --glass-border: rgba(255, 255, 255, 0.05);
+            --accent: #8b5cf6;
+            --accent-glow: rgba(139, 92, 246, 0.5);
+            --text-main: #f8fafc;
+            --text-muted: #94a3b8;
+        }
+
+        body, html {
+            margin: 0; padding: 0;
+            background-color: var(--bg-color);
+            font-family: 'Outfit', sans-serif;
+            color: var(--text-main);
+            height: 100vh;
+            overflow: hidden;
+            display: flex;
+            justify-content: center;
+            align-items: center;
+            background-image: 
+                radial-gradient(circle at 15% 50%, rgba(139, 92, 246, 0.15), transparent 25%),
+                radial-gradient(circle at 85% 30%, rgba(56, 189, 248, 0.15), transparent 25%);
+        }
+
+        .chat-container {
+            width: 100%;
+            max-width: 900px;
+            height: 85vh;
+            background: var(--glass-bg);
+            backdrop-filter: blur(20px);
+            border: 1px solid var(--glass-border);
+            border-radius: 24px;
+            display: flex;
+            flex-direction: column;
+            box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.5);
+            overflow: hidden;
+            position: relative;
+        }
+
+        /* Animated top bar */
+        .header {
+            padding: 24px;
+            border-bottom: 1px solid var(--glass-border);
+            display: flex;
+            align-items: center;
+            gap: 15px;
+        }
+
+        .ai-avatar {
+            width: 55px;
+            height: 55px;
+            border-radius: 50%;
+            object-fit: cover;
+            border: 2px solid var(--accent);
+            box-shadow: 0 0 15px var(--accent-glow);
+            animation: pulse 2s infinite alternate;
+        }
+
+        .header-text h1 { margin: 0; font-size: 1.5rem; font-weight: 700; }
+        .header-text p { margin: 0; font-size: 0.9rem; color: var(--text-muted); }
+
+        .chat-history {
+            flex-grow: 1;
+            padding: 24px;
+            overflow-y: auto;
+            display: flex;
+            flex-direction: column;
+            gap: 20px;
+        }
+
+        .message {
+            max-width: 80%;
+            padding: 16px 20px;
+            border-radius: 20px;
+            font-size: 1.05rem;
+            line-height: 1.5;
+            opacity: 0;
+            transform: translateY(20px);
+        }
+
+        .user-msg {
+            align-self: flex-end;
+            background: linear-gradient(135deg, #3b82f6, var(--accent));
+            border-bottom-right-radius: 4px;
+        }
+
+        .ai-msg {
+            align-self: flex-start;
+            background: rgba(255, 255, 255, 0.05);
+            border: 1px solid var(--glass-border);
+            border-bottom-left-radius: 4px;
+        }
+
+        .input-area {
+            padding: 20px 24px;
+            border-top: 1px solid var(--glass-border);
+            display: flex;
+            gap: 15px;
+        }
+
+        input {
+            flex-grow: 1;
+            background: rgba(0,0,0,0.3);
+            border: 1px solid var(--glass-border);
+            padding: 18px 24px;
+            border-radius: 100px;
+            color: white;
+            font-size: 1rem;
+            font-family: 'Outfit';
+            outline: none;
+            transition: border-color 0.3s ease;
+        }
+
+        input:focus {
+            border-color: var(--accent);
+            box-shadow: 0 0 15px rgba(139, 92, 246, 0.2);
+        }
+
+        button {
+            background: var(--text-main);
+            color: var(--bg-color);
+            border: none;
+            border-radius: 100px;
+            padding: 0 30px;
+            font-weight: 700;
+            font-family: 'Outfit';
+            font-size: 1rem;
+            cursor: pointer;
+            transition: transform 0.2s ease, box-shadow 0.2s ease;
+        }
+
+        button:hover {
+            transform: scale(1.05);
+            box-shadow: 0 0 20px rgba(255,255,255,0.3);
+        }
+
+        .typing-indicator { display: none; color: var(--text-muted); font-style: italic; }
+
+        @keyframes pulse {
+            0% { box-shadow: 0 0 10px var(--accent-glow); }
+            100% { box-shadow: 0 0 25px var(--accent-glow); }
+        }
+
+        /* Custom Scrollbar */
+        ::-webkit-scrollbar { width: 8px; }
+        ::-webkit-scrollbar-track { background: transparent; }
+        ::-webkit-scrollbar-thumb { background: rgba(255,255,255,0.1); border-radius: 10px; }
+    </style>
+</head>
+<body>
+
+    <div class="chat-container">
+        <div class="header">
+            <img src="logo.png" class="ai-avatar" alt="Study Ocean Logo">
+            <div class="header-text">
+                <h1>Study Ocean Mentor</h1>
+                <p>AI strictly trained on your PDFs</p>
+            </div>
+        </div>
+
+        <div class="chat-history" id="chat-history">
+            <div class="message ai-msg">
+                Hey! I'm your Study Ocean Mentor. Ask me any doubt from your materials, and I'll explain it clearly. 🌊
+            </div>
+        </div>
+
+        <div class="input-area">
+            <input type="text" id="user-input" placeholder="e.g. Explain Newton's laws of motion...">
+            <button id="send-btn">Ask</button>
+        </div>
+    </div>
+
+    <script>
+        // Initial entrance animation using GSAP
+        gsap.from(".chat-container", { y: 50, opacity: 0, duration: 1, ease: "power3.out" });
+        gsap.to(".ai-msg", { y: 0, opacity: 1, duration: 0.5, delay: 0.5 });
+
+        const history = document.getElementById("chat-history");
+        const input = document.getElementById("user-input");
+        const sendBtn = document.getElementById("send-btn");
+
+        function appendMessage(text, isUser) {
+            const msgDiv = document.createElement("div");
+            msgDiv.className = `message ${isUser ? 'user-msg' : 'ai-msg'}`;
+            // Simple markdown handling for bold text
+            msgDiv.innerHTML = text.replace(/\*\*(.*?)\*\*/g, '<strong>$1</strong>').replace(/\n/g, '<br>');
+            history.appendChild(msgDiv);
+
+            // Animate message appearing
+            gsap.to(msgDiv, { y: 0, opacity: 1, duration: 0.4, ease: "back.out(1.7)" });
+            history.scrollTop = history.scrollHeight;
+            
+            // Trigger MathJax to render the equations
+            if (window.MathJax) {
+                MathJax.typesetPromise([msgDiv]).catch((err) => console.log(err.message));
+            }
+            
+            return msgDiv;
+        }
+
+        async function sendMessage() {
+            const text = input.value.trim();
+            if(!text) return;
+
+            input.value = "";
+            appendMessage(text, true);
+
+            // Add loading state
+            const loadingMsg = appendMessage("Thinking...", false);
+            gsap.to(loadingMsg, { opacity: 0.5, repeat: -1, yoyo: true, duration: 0.5 });
+
+            try {
+                // Call the FastAPI Backend
+                const response = await fetch("/api/ask", {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json" },
+                    body: JSON.stringify({ question: text })
+                });
+
+                const data = await response.json();
+                
+                // Format response
+                let finalAnswer = data.answer;
+
+                // Replace loading message
+                gsap.killTweensOf(loadingMsg);
+                loadingMsg.innerHTML = finalAnswer.replace(/\*\*(.*?)\*\*/g, '<strong>$1</strong>').replace(/\n/g, '<br>');
+                gsap.to(loadingMsg, { opacity: 1, duration: 0.2 });
+                
+                // Render MathJax for the loaded answer
+                if (window.MathJax) {
+                    MathJax.typesetPromise([loadingMsg]).catch((err) => console.log(err.message));
+                }
+
+            } catch(e) {
+                gsap.killTweensOf(loadingMsg);
+                loadingMsg.innerHTML = "❌ Failed to connect to backend. Is the FastAPI server running on port 8000?";
+                gsap.to(loadingMsg, { opacity: 1, duration: 0.2 });
+            }
+            history.scrollTop = history.scrollHeight;
+        }
+
+        sendBtn.addEventListener("click", sendMessage);
+        input.addEventListener("keypress", (e) => { if(e.key === "Enter") sendMessage(); });
+    </script>
+</body>
+</html>

ingest.py

@@ -0,0 +1,171 @@
+"""
+PDF Ingestion & Vector Store Builder for Study Ocean RAG.
+
+This module:
+1. Recursively scans the PDF directory for all .pdf files
+2. Extracts text from each PDF using PyMuPDF (faster & more reliable)
+3. Splits text into overlapping chunks
+4. Generates embeddings using a local sentence-transformer model
+5. Stores embeddings in a FAISS vector store for fast retrieval
+"""
+
+import os
+import sys
+import time
+import fitz  # PyMuPDF
+from langchain.text_splitter import RecursiveCharacterTextSplitter
+from langchain_community.vectorstores import FAISS
+from langchain_huggingface import HuggingFaceEmbeddings
+
+import config
+
+
+def collect_pdf_paths(pdf_dir: str) -> list[str]:
+    """Recursively collect all PDF file paths from the given directory."""
+    pdf_paths = []
+    for root, _, files in os.walk(pdf_dir):
+        for file in files:
+            if file.lower().endswith(".pdf"):
+                pdf_paths.append(os.path.join(root, file))
+    return sorted(pdf_paths)
+
+
+def extract_text_from_pdf(pdf_path: str) -> str:
+    """Extract all text from a PDF using PyMuPDF."""
+    text = ""
+    try:
+        doc = fitz.open(pdf_path)
+        for page_num in range(len(doc)):
+            page = doc[page_num]
+            text += page.get_text()
+        doc.close()
+    except Exception as e:
+        print(f"  ⚠ Error reading {os.path.basename(pdf_path)}: {e}")
+    return text
+
+
+def build_documents(pdf_paths: list[str]) -> list:
+    """
+    Extract text from all PDFs and split into chunks.
+    Each chunk carries metadata about its source PDF and page info.
+    """
+    text_splitter = RecursiveCharacterTextSplitter(
+        chunk_size=config.CHUNK_SIZE,
+        chunk_overlap=config.CHUNK_OVERLAP,
+        separators=["\n\n", "\n", ". ", " ", ""],
+        length_function=len,
+    )
+
+    all_documents = []
+    for i, pdf_path in enumerate(pdf_paths, 1):
+        filename = os.path.basename(pdf_path)
+        relative_path = os.path.relpath(pdf_path, config.PDF_DIR)
+        # Derive subject from folder structure
+        parts = relative_path.replace("\\", "/").split("/")
+        subject = parts[0] if len(parts) > 1 else "General"
+
+        print(f"  [{i}/{len(pdf_paths)}] Processing: {relative_path}")
+        
+        text = extract_text_from_pdf(pdf_path)
+        if not text.strip():
+            print(f"    ⚠ No text extracted (might be scanned/image PDF)")
+            continue
+
+        # Create chunks with rich metadata
+        chunks = text_splitter.create_documents(
+            texts=[text],
+            metadatas=[{
+                "source": relative_path,
+                "filename": filename,
+                "subject": subject,
+            }]
+        )
+        all_documents.extend(chunks)
+
+    return all_documents
+
+
+def create_vector_store(documents: list, embeddings) -> FAISS:
+    """Create a FAISS vector store from documents."""
+    print(f"\n📊 Creating vector store with {len(documents)} chunks...")
+    
+    # Process in batches to avoid memory issues
+    batch_size = 500
+    vector_store = None
+    
+    for i in range(0, len(documents), batch_size):
+        batch = documents[i:i + batch_size]
+        batch_num = (i // batch_size) + 1
+        total_batches = (len(documents) + batch_size - 1) // batch_size
+        print(f"  Embedding batch {batch_num}/{total_batches} ({len(batch)} chunks)...")
+        
+        if vector_store is None:
+            vector_store = FAISS.from_documents(batch, embeddings)
+        else:
+            batch_store = FAISS.from_documents(batch, embeddings)
+            vector_store.merge_from(batch_store)
+    
+    return vector_store
+
+
+def run_ingestion():
+    """Main ingestion pipeline."""
+    print("=" * 60)
+    print("🎓 Study Ocean RAG — PDF Ingestion Pipeline")
+    print("=" * 60)
+
+    # 1. Collect PDFs
+    print(f"\n📁 Scanning for PDFs in: {config.PDF_DIR}")
+    pdf_paths = collect_pdf_paths(config.PDF_DIR)
+    
+    if not pdf_paths:
+        print("❌ No PDF files found! Make sure your PDFs are in the data/pdfs directory.")
+        print("   Extract StudyOceanPDFs.zip into data/pdfs/ first.")
+        sys.exit(1)
+    
+    print(f"   Found {len(pdf_paths)} PDF files\n")
+
+    # 2. Extract and chunk
+    print("📄 Extracting text and creating chunks...")
+    start_time = time.time()
+    documents = build_documents(pdf_paths)
+    extract_time = time.time() - start_time
+    print(f"\n   ✅ Created {len(documents)} text chunks in {extract_time:.1f}s")
+
+    if not documents:
+        print("❌ No text could be extracted from any PDF. Exiting.")
+        sys.exit(1)
+
+    # 3. Initialize embeddings
+    print(f"\n🧠 Loading embedding model: {config.EMBEDDING_MODEL}")
+    embeddings = HuggingFaceEmbeddings(
+        model_name=config.EMBEDDING_MODEL,
+        model_kwargs={"device": "cpu"},
+        encode_kwargs={"normalize_embeddings": True, "batch_size": 64},
+    )
+
+    # 4. Build vector store
+    start_time = time.time()
+    vector_store = create_vector_store(documents, embeddings)
+    embed_time = time.time() - start_time
+    print(f"   ✅ Vector store created in {embed_time:.1f}s")
+
+    # 5. Save to disk
+    os.makedirs(config.VECTOR_STORE_PATH, exist_ok=True)
+    print(f"\n💾 Saving vector store to: {config.VECTOR_STORE_PATH}")
+    vector_store.save_local(config.VECTOR_STORE_PATH)
+    print("   ✅ Vector store saved successfully!")
+
+    # Summary
+    print("\n" + "=" * 60)
+    print("✅ INGESTION COMPLETE")
+    print(f"   PDFs processed:  {len(pdf_paths)}")
+    print(f"   Chunks created:  {len(documents)}")
+    print(f"   Extract time:    {extract_time:.1f}s")
+    print(f"   Embedding time:  {embed_time:.1f}s")
+    print(f"   Store location:  {config.VECTOR_STORE_PATH}")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    run_ingestion()

main.py

@@ -0,0 +1,107 @@
+"""
+Study Ocean RAG — Main Entry Point
+
+Usage:
+    python main.py ingest    # Ingest PDFs and build vector store
+    python main.py chat      # Launch the Gradio web UI
+    python main.py ask       # Ask a single question in the terminal
+"""
+
+import sys
+
+
+def print_banner():
+    print("""
+╔══════════════════════════════════════════════════════════╗
+║           🎓 Study Ocean AI Mentor                      ║
+║       RAG-based Student Doubt Solver                    ║
+╠══════════════════════════════════════════════════════════╣
+║                                                          ║
+║  Commands:                                               ║
+║    python main.py ingest  — Process PDFs & build index   ║
+║    python main.py chat    — Launch web chat interface     ║
+║    python main.py ask     — Ask a question in terminal   ║
+║                                                          ║
+╚══════════════════════════════════════════════════════════╝
+    """)
+
+
+def run_ingest():
+    """Run the PDF ingestion pipeline."""
+    from ingest import run_ingestion
+    run_ingestion()
+
+
+def run_chat():
+    """Launch the Gradio web interface."""
+    from app import app
+    print("\n🌐 Starting Study Ocean AI Mentor web interface...")
+    print("   Open http://localhost:7860 in your browser\n")
+    app.launch(
+        server_name="0.0.0.0",
+        server_port=7860,
+        share=False,
+        show_error=True,
+    )
+
+
+def run_ask():
+    """Interactive terminal Q&A mode."""
+    from rag_chain import get_chain, ask_question
+
+    print("\n🎓 Study Ocean AI Mentor — Terminal Mode")
+    print("   Type your question and press Enter.")
+    print("   Type 'quit' or 'exit' to stop.\n")
+
+    chain = get_chain()
+
+    while True:
+        try:
+            question = input("\n🙋 Your doubt: ").strip()
+        except (KeyboardInterrupt, EOFError):
+            print("\n\n👋 Goodbye! Keep studying! 📚")
+            break
+
+        if question.lower() in ("quit", "exit", "q"):
+            print("\n👋 Goodbye! Keep studying! 📚")
+            break
+
+        if not question:
+            print("   ⚠ Please type a question.")
+            continue
+
+        print("\n🔍 Searching study material...\n")
+        result = ask_question(chain, question)
+
+        print("─" * 50)
+        print(f"\n🎓 Mentor's Answer:\n")
+        print(result["answer"])
+
+        if result["sources"]:
+            print(f"\n📖 Sources:")
+            for i, src in enumerate(result["sources"], 1):
+                print(f"   {i}. [{src['subject']}] {src['file']}")
+        print("\n" + "─" * 50)
+
+
+def main():
+    if len(sys.argv) < 2:
+        print_banner()
+        sys.exit(0)
+
+    command = sys.argv[1].lower()
+
+    if command == "ingest":
+        run_ingest()
+    elif command == "chat":
+        run_chat()
+    elif command == "ask":
+        run_ask()
+    else:
+        print(f"❌ Unknown command: {command}")
+        print_banner()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "study-ocean-rag"
+version = "0.1.0"
+description = "AI Student Mentor - RAG-based doubt solver using study materials"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "ipykernel>=7.2.0",
+    "langchain>=0.3.0",
+    "langchain-community>=0.3.0",
+    "langchain-core>=0.3.0",
+    "langchain-google-genai>=2.1.0",
+    "langchain-huggingface>=0.1.0",
+    "pymupdf>=1.27.2.2",
+    "pypdf>=6.10.1",
+    "faiss-cpu>=1.9.0",
+    "chromadb>=0.6.0",
+    "sentence-transformers>=3.4.0",
+    "google-generativeai>=0.8.0",
+    "python-dotenv>=1.1.0",
+    "gradio>=5.0.0",
+    "tiktoken>=0.9.0",
+]