{"id":50925264,"url":"https://github.com/ajawad06/nust-faq-bot","last_synced_at":"2026-06-16T22:02:36.794Z","repository":{"id":347646886,"uuid":"1194739154","full_name":"ajawad06/nust-faq-bot","owner":"ajawad06","description":"An offline RAG chatbot for assisting with admission related queries for NUST.","archived":false,"fork":false,"pushed_at":"2026-05-26T10:22:39.000Z","size":49,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-26T12:17:50.987Z","etag":null,"topics":["faiss-vector-database","fastapi","ollama","python","qwen2-5","rag-chatbot"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ajawad06.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-28T18:45:35.000Z","updated_at":"2026-05-26T12:07:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ajawad06/nust-faq-bot","commit_stats":null,"previous_names":["ajawad06/nust-admitbot","ajawad06/nust-admission-bot"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ajawad06/nust-faq-bot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajawad06%2Fnust-faq-bot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajawad06%2Fnust-faq-bot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajawad06%2Fnust-faq-bot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajawad06%2Fnust-faq-bot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ajawad06","download_url":"https://codeload.github.com/ajawad06/nust-faq-bot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajawad06%2Fnust-faq-bot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34425024,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-16T02:00:06.860Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["faiss-vector-database","fastapi","ollama","python","qwen2-5","rag-chatbot"],"created_at":"2026-06-16T22:02:35.926Z","updated_at":"2026-06-16T22:02:36.789Z","avatar_url":"https://github.com/ajawad06.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NUST Admission Assistant\n\nAn offline NUST admissions chatbot that runs locally on your machine. It uses official FAQ data, a local FAISS index, and a FastAPI backend with a plain HTML/CSS/JS frontend.\n\n## Overview\n\nNUST Admission Assistant helps students get quick answers about:\n\n- NET and admission procedures\n- Eligibility criteria\n- Scholarships and financial aid\n- Hostels and accommodation\n- Undergraduate programmes\n- Reserved seats and related admission policies\n\nThe bot is designed to work without internet after setup. Normal FAQ questions are answered directly from the local FAQ data and semantic index, so responses are typically well under 10 seconds.\n\n## How It Works\n\n1. The student asks a question in the browser UI.\n2. The frontend sends the question to the local FastAPI backend at `/api/chat`.\n3. The chatbot first tries a fast direct/fuzzy FAQ match.\n4. If needed, it embeds the question with `all-MiniLM-L6-v2` and searches the offline FAISS index.\n5. The best local FAQ answer is returned with source chunks.\n\nOllama is no longer required for normal FAQ responses. It can still be enabled as an optional fallback by setting:\n\n```bash\nUSE_OLLAMA_FALLBACK=1\n```\n\n## Project Structure\n\n```text\nnust_admission_chatbot/\n|-- data/\n|   `-- faqs.json              # Official NUST FAQ Q\u0026A pairs\n|-- index/\n|   |-- faqs.index             # FAISS vector index\n|   `-- faqs_texts.json        # Raw indexed FAQ chunks\n|-- static/\n|   |-- index.html             # Browser chat UI\n|   |-- styles.css             # Frontend styling\n|   `-- app.js                 # Frontend chat logic\n|-- app.py                     # FastAPI backend\n|-- chatbot.py                 # Local FAQ query engine\n|-- build_index.py             # Rebuilds the FAISS index\n`-- requirements.txt\n```\n\n## Tech Stack\n\n| Component | Tool / Library |\n| --- | --- |\n| Backend | FastAPI |\n| Frontend | HTML, CSS, JavaScript |\n| Embeddings | `all-MiniLM-L6-v2` via sentence-transformers |\n| Vector search | FAISS (`faiss-cpu`) |\n| Optional LLM fallback | `qwen2.5:1.5b` via Ollama |\n| Language | Python |\n\n## Setup\n\n1. Create and activate a virtual environment.\n\n```bash\npython -m venv .venv\n.venv\\Scripts\\activate\n```\n\n2. Install dependencies.\n\n```bash\npip install -r requirements.txt\n```\n\n3. Build or rebuild the FAISS index if needed.\n\n```bash\npython build_index.py\n```\n\n4. Start the local FastAPI server.\n\n```bash\npython -m uvicorn app:app --host 127.0.0.1 --port 8000\n```\n\n5. Open the chatbot.\n\n```text\nhttp://127.0.0.1:8000/\n```\n\n## API Endpoints\n\n| Endpoint | Method | Description |\n| --- | --- | --- |\n| `/` | GET | Serves the local chat UI |\n| `/api/health` | GET | Checks local backend status and FAQ count |\n| `/api/chat` | POST | Answers a question from local FAQ data |\n\nExample request:\n\n```bash\ncurl -X POST http://127.0.0.1:8000/api/chat ^\n  -H \"Content-Type: application/json\" ^\n  -d \"{\\\"question\\\":\\\"Are there any quota seats?\\\"}\"\n```\n\n## Offline Notes\n\n- The FAQ data and FAISS index are stored locally.\n- The embedding model must already be available in the local Hugging Face cache.\n- The app sets offline Hugging Face environment flags in `chatbot.py` and `build_index.py`.\n- Internet is not required for normal chatbot use once dependencies, model files, and the index are present.\n\n## Performance\n\nThe chatbot avoids calling a local LLM for normal FAQ answers. Direct FAQ matches are usually answered in a few milliseconds after startup, while semantic FAQ matches are typically far below the 10 second target.\n\nFirst startup can take a few seconds because the embedding model is loaded into memory.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fajawad06%2Fnust-faq-bot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fajawad06%2Fnust-faq-bot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fajawad06%2Fnust-faq-bot/lists"}