KingDavid2908/naija-soul

The backend for the hackhathon # Naija Soul **DSN × BCT Hackathon 3.0 — LLM Agent Challenge** A culturally-grounded multi-agent behavioral intelligence platform for user modeling (Task A) and personalized recommendation (Task B), powered by Mistral, LangGraph, YarnGPT, and Google Gemini. --- ## Architecture ``` Frontend (Next.js / TypeScript) — Vercel │ │ HTTP ▼ AI Backend (Python / FastAPI) — Render │ ├── Mistral (mistral-large-latest) — LLM reasoning ├── Google Gemini (gemini-embedding-2) — Embeddings (memory + product search) ├── YarnGPT API — Nigerian TTS ├── Geoapify Geocoding + Places — Dynamic city resolution + business data ├── Calendarific API — Nigerian holidays + cultural festivals └── Open-Meteo — Weather context (past, present, future) ``` --- ## Prerequisites - Python 3.11+ - Mistral API key - YarnGPT API key - Calendarific API key - Geoapify API key - Google Gemini API key (free tier) --- ## Local Setup ```bash # 1. Clone the repository git clone github.com cd naija-soul # 2. Create virtual environment python -m venv venv # 3. Activate it # Windows: venv\Scripts\activate # macOS / Linux: source venv/bin/activate # 4. Install dependencies pip install -r requirements.txt # 5. Create .env file with your keys (copy from .env.example) cp .env.example .env # then edit .env with your API keys # 6. Run the server uvicorn app.main:app --reload --port 10000 ``` The API will be available at `localhost`. Visit `localhost` for the interactive Swagger UI. --- ## API Endpoints ### Health Check ```bash curl localhost ``` Response: ```json { "status": "ok" } ``` ### POST /simulate-review — Task A: User Modeling Simulates a realistic user review in Nigerian English/Pidgin/Yoruba/Igbo/Hausa, with optional audio narration. **Request fields:** | Field | Type | Required | Description | |---|---|---|---| | `user_id` | string …