Ak-Dan/naija-persona-agent

# Purpose: Gives judges and developers the shortest path to run, inspect, and extend the application. # Nigerian Context-Aware LLM Agent Challenge This repository contains a runnable FastAPI and LangGraph skeleton for two independently runnable tasks: - **Task A:** simulate a review and star rating from a user persona and product metadata. - **Task B:** generate a ranked recommendation list with cold-start handling, Nigerian context injection, and session-aware chat. The implementation is deliberately conservative: it runs from a cold clone without requiring a live ChromaDB instance or model downloads. External integrations are wrapped behind typed adapters in `core/`, and deterministic fallbacks keep the API usable for judging. ## Run In Under 15 Minutes ```powershell python -m venv .venv .\.venv\Scripts\Activate.ps1 pip install -r requirements.txt Copy-Item .env.example .env uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload ``` Open: - API docs: localhost - Health check: localhost Smoke test Task A: ```powershell python scripts/run_task_a.py ``` Smoke test Task B: ```powershell python scripts/run_task_b.py ``` Build a demo measurable pipeline: ```powershell python scripts/index_corpus.py --demo python scripts/build_bm25_index.py python scripts/evaluate_task_a.py --max-examples 12 python scripts/evaluate_task_b.py ``` This writes normalized indexes to `data/indexed/` and metric reports to `reports/`. Both directories are ignored by git because they are generated artifacts. ## Ingest Real Data The ingestion script accepts CSV, JSONL, NDJSON, or JSON arrays. It normalizes common Amazon, Goodreads, and Yelp field names into one schema. ```powershell python scripts/index_corpus.py ` --amazon data/raw/amazon_reviews.jsonl ` --goodreads data/raw/goodreads_reviews.jsonl ` --yelp data/raw/yelp_reviews.jsonl ``` For custom files: ```powershell python scripts/index_corpus.py --source amazon:data/raw/my_amazon.csv …