README.md

metadata

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:

mkdir -p ~/.streamlit