core/nigerian.py

"""Nigerian style layer — bonus marks via cultural contextualization.

The challenge brief awards extra credit for systems that *behave and sound
like Nigerians*. We treat this as a toggleable rendering layer, not as a
core dependency, for two reasons:

    1. Eval datasets are English Amazon reviews. Rendering everything in
       Nigerian register would hurt our ROUGE / BERTScore against the
       ground truth.
    2. Keeping it as a flag means we can showcase the capability without
       sacrificing benchmark scores. Best of both rubric worlds.

Two functions:

    naija_style_review(text)  → rewrites a generated review in Nigerian
                                English register, preserving sentiment,
                                rating intent, and key entities.

    naija_persona_examples()  → returns hand-crafted Nigerian personas the
                                judges can demo Task B against. These show
                                the system handling local taste profiles
                                (afrobeats, jollof, Nollywood, etc.) even
                                when the underlying catalog is Amazon-global.

Design note: the style layer renders output in rich, expressive Nigerian
Pidgin — confident and fluent across the whole text, the way a Nigerian
genuinely talks when giving a strong opinion. Sentiment, rating intent and
factual content are always preserved; only the register changes.
"""
from __future__ import annotations

from core.llm import LLMClient

NAIJA_STYLE_SYSTEM = """You are a stylist who rewrites text in rich, expressive Nigerian Pidgin English — the way a Nigerian would genuinely talk when sharing strong opinions. Rules:

- Keep the sentiment, rating intent, and all factual content unchanged. A positive review stays positive; a 2-star pan stays a pan; named items, authors, and plot facts stay accurate.
- Write FULLY in Nigerian Pidgin register — not standard English with a sprinkle. Lean into it confidently across the whole text.
- Use natural Pidgin grammar and vocabulary throughout. Examples of the texture wanted:
  · "This book sweet me die, I no fit drop am at all."
  · "Abeg, the storyline just dey drag, e tire me well well."
  · "Na correct work be this — the writer sabi wetin e dey do."
  · "I no go lie, the ending shock me, I no see am coming."
  · "The characters dey alive, you go feel like say you sabi them."
  · "E no make sense, I vex small as I read am finish."
  · "This one na better book, e make sense gan-gan."
- Common markers to use freely: "abeg", "sha", "na", "dey", "wetin", "e be like say", "no be small thing", "gan-gan", "well well", "I no go lie", "comot", "sabi", "vex", "sweet me", "make sense".
- Keep it authentic, not caricature — write like a real Nigerian sharing a genuine opinion, not a parody. It should read as natural Pidgin, fluent and confident.
- Do NOT add cultural references that weren't in the original (no jollof, Lagos traffic, etc. unless the source mentioned them).
- Length should stay roughly the same.
- Return ONLY the rewritten text. No preamble, no explanation."""


def naija_style_review(text: str, llm: LLMClient | None = None) -> str:
    """Rewrite an English review in Nigerian English register.

    Idempotent on already-Naija text in practice (the model leaves natural
    phrasings alone).
    """
    llm = llm or LLMClient()
    return llm.complete(
        prompt=f"Rewrite this review in Nigerian English register:\n\n{text}",
        system=NAIJA_STYLE_SYSTEM,
        model="bulk",
    ).strip()


# ──────────────────────────────────────────────────────────────────────────────
# Demo personas — used in the Streamlit UI to showcase cold-start handling
# ──────────────────────────────────────────────────────────────────────────────

NAIJA_DEMO_PERSONAS: list[dict] = [
    {
        "name": "Tunde — Lagos software engineer",
        "description": (
            "A 28-year-old software engineer in Lagos who reads mostly non-fiction "
            "(business biographies, productivity, AI/tech), watches African and "
            "international thrillers, and complains when books are padded or movies "
            "are too slow. Prefers concise, practical writing. Gives 5 stars only "
            "when something genuinely changed his thinking; defaults to 4. "
            "Frequently mentions 'value for time' and 'execution'."
        ),
        "stated_preferences": ["business biographies", "AI and tech books",
                               "fast-paced thrillers", "Nollywood crime dramas",
                               "concise practical writing"],
        "deal_breakers": ["padded chapters", "slow pacing", "academic jargon"],
    },
    {
        "name": "Ngozi — Abuja public health doctor",
        "description": (
            "A 35-year-old doctor in Abuja who reads literary fiction and African "
            "memoirs, watches character-driven dramas (West African and global), "
            "and dislikes anything that handles women's lives shallowly. Writes "
            "thoughtful, longer-than-average reviews. Rates with a tough 3.5 average. "
            "Often references 'emotional truth' and 'craft'."
        ),
        "stated_preferences": ["literary fiction", "African memoirs",
                               "character-driven dramas", "Adichie-adjacent voice"],
        "deal_breakers": ["shallow female characters", "trauma porn",
                          "lazy plotting"],
    },
    {
        "name": "Bayo — Ibadan undergraduate",
        "description": (
            "A 21-year-old student in Ibadan who reads YA fantasy, plays a lot of "
            "Afrobeats during study sessions, watches anime and Nollywood comedies, "
            "and writes short bursty reviews. Quick to give 5 stars when entertained. "
            "Mentions vibes, pacing, and whether something 'hits'."
        ),
        "stated_preferences": ["YA fantasy", "anime", "Nollywood comedies",
                               "fast-paced action"],
        "deal_breakers": ["long descriptive passages", "overly serious tone"],
    },
]


def naija_persona_examples() -> list[dict]:
    """Return demo personas for the Task B UI's cold-start showcase."""
    return [dict(p) for p in NAIJA_DEMO_PERSONAS]