joskintola/naija-agent
Domain:
natural language processingRecord type:
software
Creator:
jos
Host:
# 🇳🇬 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 …