omarashour04/egypt-road-mobility-assistant-

RAG-based QA system for Egyptian traffic laws, driving licenses, and road rules — bilingual Arabic/English # 🚗 Egyptian Road & Mobility Assistant A bilingual (Arabic/English) Retrieval-Augmented Generation (RAG) system for answering questions about Egyptian traffic laws, driving licenses, vehicle registration, and road rules. Built as an NLP course project (Project 2 — Website Question Answering). --- ## Architecture ``` User Query │ ▼ Query Enhancer ──── HyDE (hypothetical document embedding) │ └── Bilingual translation (AR ↔ EN) ▼ FAISS Retriever ─── 3 parallel searches (raw + HyDE + translated) │ ▼ Cross-Encoder Reranker (ms-marco-MiniLM-L-6-v2) │ ▼ Qwen3:4b Generator (via Ollama) │ ▼ Answer + Sources + Session Memory ``` --- ## Domains Covered | Domain | Arabic | English | |--------|--------|---------| | Traffic Law | ✅ | ✅ | | Driving License | ✅ | ✅ | | Vehicle Registration | ✅ | ✅ | | Accident Liability | ✅ | ✅ | | Commercial Vehicles | ✅ | ✅ | | Driver Fitness | ✅ | ✅ | | International Driving | ✅ | ✅ | | Road Infrastructure | ✅ | ✅ | --- ## Setup ### Prerequisites - Python 3.11 - Ollama installed and running - Conda (recommended) ### 1. Clone the repo ```bash git clone github.com cd YOUR_REPO_NAME ``` ### 2. Create conda environment ```bash conda create -n traffic_qa python=3.11 conda activate traffic_qa ``` ### 3. Install dependencies ```bash pip install -r requirements.txt ``` ### 4. Pull Ollama models ```bash ollama pull qwen3:4b ollama pull qwen3-embedding:0.6b ``` ### 5. Scrape & index ```bash python run.py scrape # Collect data from sources (~15–30 min) python run.py index # Build FAISS index (~4 min) ``` ### 6. Start the API ```bash python run.py serve ``` API docs available at **localhost (Swagger UI) --- ## API Endpoints | Method | Endpoint | Description | |--------|----------|-------------| | `POST` | `/ask` | Ask a question (Arabic or English) | | `POST` | `/scrape` | Trigger a fresh scrape | | `GET` | `/health` | System health check | | `GET` | `/stats` …