joskintola/naija-agent

# 🇳🇬 Naija Agent ### LLM-Powered User Modelling & Personalised Recommendation System **DSN × Bluechip Technologies — LLM Agent Challenge · Hackathon 3.0** --- ## 🔗 Live Application **naija-agent-production.up.r… --- ## 📌 Overview Naija Agent is a two-task LLM-based system that models Nigerian user behaviour and delivers personalised cross-domain recommendations. It is built on real data from **Yelp**, **Amazon Reviews**, and **Goodreads**, powered by **Claude claude-opus-4-5**, and contextualised deeply for Nigerian users, language, and culture. | Task | Description | |------|-------------| | **Task A — User Modelling** | Simulates how a specific user would review an unseen item — capturing their tone, rating behaviour, vocabulary, and Nigerian cultural context | | **Task B — Recommendation** | Delivers personalised cross-domain recommendations using chain-of-thought reasoning, handling cold-start users and multi-turn refinement | --- ## 🏗️ Architecture --- naija-agent/ ├── app/ │ ├── main.py # FastAPI endpoints — Task A and Task B │ ├── agent.py # AI brain — Claude API + prompt engineering │ ├── data.py # Dataset loader — Yelp, Amazon, Goodreads │ ├── index.html # Single-page frontend UI │ └── data/ │ ├── yelp_sample.json # 26 users, 452 Nigerian businesses │ ├── amazon_sample.json # 50 users, 473 products │ └── goodreads_sample.json # 46 users, 200 books ├── extract_data.py # One-time data extraction pipeline ├── requirements.txt # Python dependencies ├── Dockerfile # Container definition ├── docker-compose.yml # Multi-service orchestration └── README.md ## 📊 Datasets --- | Dataset | Source | Users | Items | Domain | |---------|--------|-------|-------|--------| | Yelp | Kaggle (yelp-dataset) | 26 | 452 businesses | Food & Restaurants | | Amazon Reviews | Kaggle (amazon-product-reviews) | 50 | 473 products | Products & Shopping | | Goodreads | Ka …