README.md

---
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
license: "mit"
---

# 📘 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  

---

## 🧠 LLM Integration (Optional)
You can enhance the assistant’s responses with **Hugging Face Inference API** or run it completely **offline** using local models.

### 🔑 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`  

---

## ⚙️ Troubleshooting

### ⚠️ “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