Faithama08/opinion-mining-nigeria

# ML Opinion Mining System for Nigerian Digital Services > Final Year Project — Amaogu Faith Ihedinma (21/52HA042) > Department of Computer Science, University of Ilorin > Supervisor: Prof. A.O. Bajeh --- ## What this project does An end-to-end machine learning system that: 1. **Classifies sentiment** (positive / negative / neutral) in Nigerian digital service reviews using transformer models fine-tuned on Nigerian language datasets 2. **Discovers recurring complaint themes** in negative reviews using BERTopic clustering 3. **Presents insights** on a web dashboard showing sentiment trends, issue clusters, and bank comparisons --- ## Quick start (running the demo locally) ### Prerequisites - Python 3.10+ - Node.js (only needed if regenerating docs — not for running the app) - Git ### 1. Clone and set up environment ```bash git clone github.com cd opinion-mining-nigeria python -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate pip install -r requirements.txt ``` ### 2. Copy environment variables ```bash cp .env.example .env # Edit .env if needed — defaults work for local demo ``` ### 3. Download datasets ```bash python src/preprocessing/prepare_datasets.py ``` ### 4. Run preprocessing on bank reviews ```bash python src/preprocessing/clean_bank_reviews.py ``` ### 5. Train baseline models (CPU, ~5 minutes) ```bash python src/models/train_baseline.py ``` ### 6. Fine-tune transformer (requires GPU — use Google Colab) See `notebooks/04_transformer_training.ipynb`. Download the saved model and place in `models/best_model/`. ### 7. Run batch inference on bank reviews ```bash python src/models/inference.py ``` ### 8. Run clustering ```bash python src/clustering/topic_model.py ``` ### 9. Start the API ```bash uvicorn api.main:app --reload --host 0.0.0.0 --port 8000 ``` ### 10. Open the dashboard Open `frontend/index.html` in your browser. All charts will load from `localhost:8000`. --- …