Update README.md

README.md

@@ -1,19 +1,58 @@
----
-title: Handbook Chatbot
-emoji: 🚀
-colorFrom: red
-colorTo: red
-sdk: docker
-app_port: 8501
-tags:
-- streamlit
+title: "USTP Student Handbook Assistant"
+emoji: "📘"
+colorFrom: "purple"
+colorTo: "indigo"
+sdk: "streamlit"
+sdk_version: "1.39.0"
+app_file: src/streamlit_app.py
 pinned: false
-short_description: Streamlit template space
+license: "mit"
 ---
 
-# Welcome to Streamlit!
+# 📘 USTP Student Handbook Assistant (2023 Edition)
+
+This Streamlit app lets students, faculty, and staff **ask questions about the USTP Student Handbook (2023 Edition)** and get **accurate, page-referenced answers** directly from the document — powered by **FAISS**, **Sentence Transformers**, and **open-source LLMs** such as Mistral, Mixtral, and Qwen.
+
+---
+
+## 🚀 Features
+✅ Reads and indexes the *USTP Student Handbook 2023 Edition* PDF  
+✅ Fast semantic search with **FAISS vector database**  
+✅ Accurate citation with **printed page numbers**, not raw PDF indices  
+✅ Choose between **multiple open-source models** (Mistral, Mixtral, Qwen, etc.)  
+✅ Offline-safe — works even without API tokens  
+✅ Automatic local embedding with **MiniLM** for fast responses  
+✅ Caches index for instant re-use  
+
+---
 
-Edit `/src/streamlit_app.py` to customize this app to your heart's desire. :heart:
+## 🧠 LLM Integration (Optional)
+You can enhance the assistant’s responses with **Hugging Face Inference API** or run it completely **offline** using local models.
 
-If you have any questions, checkout our [documentation](https://docs.streamlit.io) and [community
-forums](https://discuss.streamlit.io).
+### 🔑 To configure:
+1. Create a `.env` file in the app root directory.  
+2. Add your Hugging Face token (optional): HF_TOKEN = your_huggingface_token
+3. Save the file and **restart the app**.
+
+> 💡 If you don’t provide a token, the app will automatically use a **local SentenceTransformer model** for embeddings.
+
+---
+
+## 🛠️ Deployment Notes
+- **Runtime:** Python SDK  
+- **SDK:** Streamlit  
+- **App file:** `src/streamlit_app.py`  
+- **PDF file:** Must be named `USTP Student Handbook 2023 Edition.pdf` and placed in the same directory.  
+- **Recommended visibility:** **Public** (for demo and student access)  
+- **Supported models:**  
+- `mistralai/Mistral-7B-Instruct-v0.3`  
+- `mistralai/Mixtral-8x7B-Instruct-v0.1`  
+- `Qwen/Qwen2.5-14B-Instruct`  
+
+---
+### ⚠️ “Permission denied: '/.streamlit'”
+If deploying in a restricted environment:
+- Set the working directory to a writable path (e.g., `/home/appuser/app`).
+- Or run:
+```bash
+mkdir -p ~/.streamlit