ayoolaeni/Naija-Code-Switch

The finished application is an AI-powered chatbot that understands both English and Nigerian Pidgin even when they are mixed together in the same sentence making digital services easier and more natural for millions of Nigerian users. # Naija-Switch (engineering build) Implementation of the research brief in `README (1).md`.md>): a code-switch-aware chatbot for English-Nigerian Pidgin conversation. This file documents the engineering build that lives in this repo -- setup, how to run each pipeline stage, and exactly what runs today on a laptop versus what needs a GPU / real contributors / paid API access to reach the research design's full scale. ## Setup ```bash python -m venv .venv source .venv/Scripts/activate # Windows Git Bash; use .venv\Scripts\activate.bat on cmd pip install -r requirements.txt cp .env.example .env # then fill in HF_TOKEN to get live chat responses ``` `bitsandbytes` (QLoRA) is Linux-only in `requirements.txt` -- on Windows/macOS without a supported GPU, `train_lora.py` automatically falls back to full precision (see "Scope of this build" below). ## Running the chat app with Docker (recommended for handing this to someone else) The chat app (`src/app/ui.py`) is packaged as its own Docker image, separate from the full research environment above -- it only needs `streamlit`, `huggingface_hub`, and `python-dotenv` (no `torch`/`transformers`/`peft`, no GPU), so the image is small and builds fast. This is the easiest way for someone without Python installed to run the app. **One-time setup (whoever is running it):** 1. Install Docker Desktop and make sure it's running. 2. From the project folder: ```bash docker compose up -d --build ``` 3. Open localhost in a browser. That's it -- no `.env` file is required. With none present, the app runs on the deterministic `MockBackend` (see "Scope of this build" below), which proves the whole app works but doesn't call a real language model. **For live model responses:** copy `.env.example` to `.env` in the project folder and set `HF_TOKEN` (a free token from huggingface.co), then re-run `docker compose up -d --build`. `docker compose` reads `.env` automatically; nothing needs to be …