stephen-tembo-dev/lyric-safety-nlp

Explainable multilingual NLP tool that rates song lyric safety by age using Gemini + rule-based scoring, with Zambia language support (English, Bemba, Nyanja, Tonga) and local-lyrics fallback. # Song Safety Analyzer An explainable NLP project that evaluates whether song lyrics are appropriate for a target age. It combines: - Gemini-based semantic analysis - Multilingual lexical rule-based scoring - Language detection with confidence + support tiering - Age-based risk thresholds - Language-aware threshold calibration for low-resource scenarios - Transparent evidence and rationale in the final report ## Quick Start ```bash python -m venv venv # PowerShell .\venv\Scripts\Activate.ps1 pip install -r requirements.txt python song_analyzer.py --song "Minefields" --artist "Faouzia" --age 12 ``` ## Project Structure - `song_analyzer.py`: CLI entrypoint and backward-compatible `analyze_song_for_child(...)` function - `song_safety/config.py`: runtime settings from environment variables - `song_safety/clients.py`: LRCLIB lyrics client and Gemini API client - `song_safety/scoring.py`: lexical scoring, hybrid score combination, and policy engine - `song_safety/service.py`: orchestration service (`SongSafetyAnalyzer`) - `song_safety/reporting.py`: console report renderer - `song_safety/domain.py`: domain models and defaults - `song_safety/language.py`: language detection heuristics and support-tier mapping ## Requirements - Python 3.10+ - `requests` - Internet access (for LRCLIB and Gemini API) - Gemini API key ## Setup ### 1) Create and activate a virtual environment (recommended) PowerShell: ```powershell python -m venv venv .\venv\Scripts\Activate.ps1 ``` macOS/Linux: ```bash python3 -m venv venv source venv/bin/activate ``` ### 2) Install dependencies ```bash pip install -r requirements.txt ``` ### 3) Configure Gemini credentials Current terminal session only: PowerShell: ```powershell $env:GEMINI_API_KEY = "YOUR_GEMINI_API_KEY" $env:GEMINI_MODEL = "gemini-2.0-flash" ``` macOS/Linux: ```bash export GEMINI_API_KEY="YOUR_GEMINI_API_KEY" export GEMINI_MODEL="gemini-2.0-flash" ``` Persistent on Windows (new terminals): ```powershell setx GEMINI_A …