Micah-Shallom/hausa_topic_classification

Fine-tuned AfroXLMR-base on MasakhaNEWS for Hausa topic classification (F1 0.9277), with a FastAPI backend and frontend, featuring focal loss for improved accuracy. # Hausa News Topic Classifier A topic classification system for Hausa news using AfroXLMR-base, achieving a test F1 score of 0.9277. This project fine-tunes a transformer model on the MasakhaNEWS dataset and deploys it with a FastAPI backend (`server`) and a frontend (`client`), including an "Other" category for out-of-scope texts. ## Project Structure - **`client/`**: Frontend (e.g., React/Vue with pnpm). - **`server/`**: Backend (FastAPI with AfroXLMR-base model). ## Application ## Features - Classifies Hausa news into 7 topics: Business, Entertainment, Health, Politics, Religion, Sport, Technology. - Focal loss (α=0.25, γ=1.0), temperature scaling (T=1.5), and threshold (0.6) for "Other" category. - Real-time inference via API and interactive UI. ## Prerequisites - **Client**: Node.js, pnpm (`npm install -g pnpm`). - **Server**: Python 3.8+, dependencies (`fastapi`, `uvicorn`, `torch`, `transformers`, `numpy`). ## Installation 1. **Clone the Repository**: ```bash git clone github.com cd hausa-topic-classification ``` 2. **Install Client Dependencies**: ```bash cd client pnpm install ``` 3. **Install Server Dependencies**: ```bash cd ../server pip install fastapi uvicorn torch transformers numpy --index-url download.pytorch.org ``` 4. **Download Model Weights**: - Due to size (~1.04 GB), model files are not included. - Download from: Google Drive Link - Files: `config.json`, `model.safetensors`, `sentencepiece.bpe.model`, `special_tokens_map.json`, `tokenizer_config.json`, `tokenizer.json`. - Move them to `server/model/` directory: ```bash mkdir server/model mv /path/to/downloaded/files/* server/model/ ``` ## Usage 1. **Start the Server**: ```bash cd server uvicorn main:app --reload ``` - Runs on `localhost`. 2. **Start the Client**: ```bash cd client pnpm dev ``` - Typically runs on `localhost` (check client config). 3. **Test the API**: ```bash curl -X POST …