--- license: llama3.1 base_model: meta-llama/Meta-Llama-3.1-8B-Instruct library_name: transformers pipeline_tag: text-generation language: - en - pcm - yo - ha - ig datasets: - Shinzmann/npa-corpus-v1 tags: - llama-3.1 - lora - qlora - gguf - llama-cpp - ollama - nigerian - nigerian-pidgin - reviews - recommendation - agent --- # NaijaReviewer-8B Llama 3.1 8B Instruct QLoRA fine-tuned on Nigerian product reviews. This repository contains **both** the merged HF-format weights (for `transformers` / Unsloth) and all GGUF quantisations (for `llama.cpp` / Ollama). It is the model behind the **Naija Persona Agent** — a Nigerian-context AI system for review simulation (Task A) and persona-aware recommendation (Task B), submitted to the DSN X BCT LLM Agent Challenge. - **Live application:** - **Source code:** - **Companion artifacts:** [GGUF-only repo](https://huggingface.co/Shinzmann/naija-reviewer-8b-v2-Q4_K_M-GGUF) · [LoRA adapter](https://huggingface.co/Shinzmann/naija-reviewer-8b-v2-lora) · [Training corpus](https://huggingface.co/datasets/Shinzmann/npa-corpus-v1) ## Headline numbers | Metric | NaijaReviewer-8B | Frontier baseline (Claude Sonnet 4) | |---|---|---| | Task A rating RMSE (lower is better) | **1.114** | 1.319 (15.5% higher) | | Task A BERTScore F1 | 0.858 | 0.857 | | Task A Nigerian-rater win-rate, 5 raters / 50 pairs | **48.5%** (CI [40.2, 56.9]) | 51.5% (statistical parity) | | Task B NDCG@10 vs 4 baselines | **0.588** (best in field) | 0.430 | | Parameters | **8B** | 70B-120B+ | | Per-call API cost | **Zero** (open weights) | $/1k tokens | ## What's in this repo | File set | Use | |---|---| | `model.safetensors`, `config.json`, tokenizer files | HF format. Load with `transformers` / Unsloth / vLLM / TGI. | | `naija-reviewer-8b-v2-Q4_K_M.gguf` | Recommended GGUF (~5 GB). Load with `llama.cpp` / Ollama. | | `naija-reviewer-8b-v2-Q5_K_M.gguf` | Higher-quality GGUF (~5.7 GB). | | `naija-reviewer-8b-v2-Q8_0.gguf` | Near-lossless GGUF (~8.5 GB). | | `Modelfile` | Ollama configuration with the correct Alpaca template and stop sequences. | The Q4_K_M GGUF is also available standalone in [its dedicated repo](https://huggingface.co/Shinzmann/naija-reviewer-8b-v2-Q4_K_M-GGUF), which is the file the production serverless endpoint pulls. ## Quick start ### transformers ```python from transformers import AutoModelForCausalLM, AutoTokenizer import torch tok = AutoTokenizer.from_pretrained("Shinzmann/naija-reviewer-8b-v2") model = AutoModelForCausalLM.from_pretrained( "Shinzmann/naija-reviewer-8b-v2", torch_dtype=torch.bfloat16, device_map="auto", ) prompt = ( "### Instruction\n" "Write a star rating and a short product review.\n\n" "### Input\n" "Persona: Tunde, 28, Lagos Bolt driver, code-mixed speaker, value-priority.\n" "Product: Tecno Spark 10 mobile phone, 4 GB RAM, 5000 mAh battery, NGN 145,000.\n\n" "### Response\n" ) inputs = tok(prompt, return_tensors="pt").to(model.device) out = model.generate(**inputs, max_new_tokens=220, eos_token_id=tok.eos_token_id, do_sample=True, temperature=0.7) print(tok.decode(out[0][inputs.input_ids.shape[1]:], skip_special_tokens=True)) ``` ### llama-cpp-python (GGUF) ```python from llama_cpp import Llama llm = Llama.from_pretrained( repo_id="Shinzmann/naija-reviewer-8b-v2", filename="naija-reviewer-8b-v2-Q4_K_M.gguf", n_ctx=4096, n_gpu_layers=-1, chat_format="llama-3", ) out = llm.create_chat_completion( messages=[{"role": "user", "content": "Write a Pidgin review of an Oraimo wireless earbud."}], max_tokens=256, temperature=0.7, ) print(out["choices"][0]["message"]["content"]) ``` ### Ollama ```bash huggingface-cli download Shinzmann/naija-reviewer-8b-v2 \ naija-reviewer-8b-v2-Q4_K_M.gguf Modelfile --local-dir . ollama create naija-reviewer-8b -f Modelfile ollama run naija-reviewer-8b ``` ## Prompt format Alpaca template, as used in training: ``` ### Instruction {instruction} ### Input {input} ### Response {response} ``` Stop sequences: `### Instruction`, `### Input`, `### Response`. The included Ollama `Modelfile` encodes these. For Nigerian-context use, pass the structured persona JSON (cognitive dimensions + register tier + aspect priorities) as the `### Input`. The production prompt templates are in the project repo at `app/prompts/`. ## Training | | | |---|---| | Base model | `meta-llama/Meta-Llama-3.1-8B-Instruct` | | Method | QLoRA via [Unsloth](https://github.com/unslothai/unsloth) | | Adapter | LoRA r=16, alpha=32, dropout=0.1, targets q/k/v/o/up/gate/down (0.52% trainable params) | | Loss | Response-only loss (gradients on the answer tokens only) | | Tokenisation | EOS-terminated training examples | | Schedule | 2 epochs, effective batch size 16, learning rate 2e-4 with cosine decay, sequence length 4096 | | Quantisation | Three GGUF builds: `Q4_K_M`, `Q5_K_M`, `Q8_0` | Training and validation loss curves are published in the project's `notebooks/03_training_results.ipynb` and reproduced in the Task A solution paper. ## Training data Trained on **`Shinzmann/npa-corpus-v1`** (~20,000 Alpaca-style instruction/response pairs), built from two real public sources plus synthetic expansion: - **Real Jumia reviews (~76k)** from the [`aymane-maghouti/Sentiment-Analysis-for-Jumia-Reviews`](https://github.com/aymane-maghouti/Sentiment-Analysis-for-Jumia-Reviews-and-Smartphone-Price-Prediction-System) public GitHub repository, used as Pipeline 1 seed. - **Real Jumia product catalogue (~18k)** from the [`Idowenst/jumia_dataset`](https://huggingface.co/datasets/Idowenst/jumia_dataset) HuggingFace dataset, used as Pipeline 2 seed. - **Synthetic expansion** by NVIDIA Nemotron and OpenAI models, persona-conditioned and stratified 90/5/5 by register tier. ## Intended use and limitations **Intended use.** Generation of Nigerian-context product reviews and ratings (Task A); persona-aware re-ranking of product recommendations (Task B); research on register-aware text generation in low-resource African contexts. **Limitations.** Trained primarily on Nigerian English and Nigerian Pidgin product reviews. The training corpus is partly synthetic; two independent generator pipelines and a held-out evaluation generated by a different model family were used to mitigate confounds, but residual bias remains possible. On a 3-arbiter LLM-as-Judge evaluation, frontier LLM judges showed a systematic preference for Claude Sonnet 4's prose register; Nigerian human raters scored the two systems at parity on the same pairs, which we read as evidence that single-judge LLM evaluation is insufficient on culturally-localised content. ## Citation ```bibtex @misc{naijareviewer8b2026, title = {NaijaReviewer-8B: A Nigerian-Context Open-Weight Fine-Tune for Persona-Aware Review Generation}, author = {Ashinze, Emmanuel and Uvere, Franca and Oyenekan, Esther}, year = {2026}, url = {https://huggingface.co/Shinzmann/naija-reviewer-8b-v2} } ``` ## License Subject to the [Llama 3.1 Community License](https://huggingface.co/meta-llama/Meta-Llama-3.1-8B-Instruct/blob/main/LICENSE). Released for research and non-commercial use; commercial use must comply with the upstream Llama 3.1 terms.