Upload 12 files

core/__init__.py

@@ -0,0 +1,19 @@
+"""User Modeling Agent — shared intelligence core.
+
+Modules:
+    config      : env-loaded settings
+    llm         : provider-agnostic LLM client (OpenAI / Gemini)
+    persona     : behavioral persona extraction from review history
+    nigerian    : optional style-transfer layer for Nigerian English register
+    reflection  : self-critique and refinement loop
+"""
+from core.config import settings
+from core.llm import LLMClient
+from core.persona import PersonaEngine, UserPersona
+
+__all__ = [
+    "settings",
+    "LLMClient",
+    "PersonaEngine",
+    "UserPersona",
+]

core/config.py

@@ -0,0 +1,87 @@
+"""Central configuration loaded from environment variables.
+
+All other modules import `settings` from here. Never call os.environ directly
+in agent code — keeps the surface small and testable.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+@dataclass(frozen=True)
+class Settings:
+    # LLM provider switch
+    llm_provider: str   # 'openai' or 'gemini'
+
+    # OpenAI
+    openai_api_key: str
+    openai_reasoning_model: str
+    openai_bulk_model: str
+
+    # Gemini
+    gemini_api_key: str
+    gemini_reasoning_model: str
+    gemini_bulk_model: str
+
+    # Convenience aliases (backward compat with older code that uses these)
+    reasoning_model: str
+    bulk_model: str
+
+    # Embeddings
+    sbert_model: str
+
+    # Paths
+    data_dir: Path
+    processed_dir: Path
+    chroma_persist_dir: Path
+
+    # Service ports
+    task_a_api_port: int
+    task_a_ui_port: int
+    task_b_api_port: int
+    task_b_ui_port: int
+
+
+def _build() -> Settings:
+    data_dir = Path(os.environ.get("DATA_DIR", "./data")).resolve()
+    provider = os.environ.get("LLM_PROVIDER", "openai").lower()
+
+    openai_reasoning = os.environ.get("OPENAI_REASONING_MODEL", "gpt-4o")
+    openai_bulk = os.environ.get("OPENAI_BULK_MODEL", "gpt-4o-mini")
+    gemini_reasoning = os.environ.get("GEMINI_REASONING_MODEL", "gemini-2.5-flash")
+    gemini_bulk = os.environ.get("GEMINI_BULK_MODEL", "gemini-2.5-flash-lite")
+
+    # Convenience aliases point to the active provider's models
+    if provider == "gemini":
+        active_reasoning, active_bulk = gemini_reasoning, gemini_bulk
+    else:
+        active_reasoning, active_bulk = openai_reasoning, openai_bulk
+
+    return Settings(
+        llm_provider=provider,
+        openai_api_key=os.environ.get("OPENAI_API_KEY", ""),
+        openai_reasoning_model=openai_reasoning,
+        openai_bulk_model=openai_bulk,
+        gemini_api_key=os.environ.get("GEMINI_API_KEY", ""),
+        gemini_reasoning_model=gemini_reasoning,
+        gemini_bulk_model=gemini_bulk,
+        reasoning_model=active_reasoning,
+        bulk_model=active_bulk,
+        sbert_model=os.environ.get("SBERT_MODEL", "sentence-transformers/all-MiniLM-L6-v2"),
+        data_dir=data_dir,
+        processed_dir=data_dir / "processed",
+        chroma_persist_dir=Path(os.environ.get("CHROMA_PERSIST_DIR", data_dir / "chroma")),
+        task_a_api_port=int(os.environ.get("TASK_A_API_PORT", 8001)),
+        task_a_ui_port=int(os.environ.get("TASK_A_UI_PORT", 8501)),
+        task_b_api_port=int(os.environ.get("TASK_B_API_PORT", 8002)),
+        task_b_ui_port=int(os.environ.get("TASK_B_UI_PORT", 8502)),
+    )
+
+
+settings = _build()

core/llm.py

@@ -0,0 +1,172 @@
+"""LLM client — provider-agnostic wrapper for OpenAI and Gemini.
+
+Why a wrapper:
+  - Two-tier model selection (reasoning vs bulk) without scattering model names
+  - Two-provider support (OpenAI / Gemini), switchable via LLM_PROVIDER env var
+  - Built-in retry on transient errors
+  - Pydantic-validated structured outputs
+  - Single chokepoint for logging / token accounting
+
+The provider is chosen at construction time from settings.llm_provider:
+  - 'openai' (default) → gpt-4o + gpt-4o-mini via langchain-openai
+  - 'gemini'           → gemini-2.5-flash + gemini-2.5-flash-lite via langchain-google-genai
+
+Both providers share the same interface, so calling code never needs to
+care which one is active.
+
+Usage:
+    llm = LLMClient()
+    answer = llm.complete("Why is the sky blue?", model="bulk")
+    parsed = llm.structured(prompt, ReviewOutput, model="reasoning")
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any, Type, TypeVar
+
+from langchain_core.language_models import BaseChatModel
+from langchain_core.output_parsers import PydanticOutputParser
+from langchain_core.prompts import ChatPromptTemplate
+from pydantic import BaseModel
+from tenacity import retry, stop_after_attempt, wait_exponential
+
+from core.config import settings
+
+log = logging.getLogger(__name__)
+
+T = TypeVar("T", bound=BaseModel)
+
+
+def _build_openai_models(temp_reasoning: float, temp_bulk: float) -> tuple[BaseChatModel, BaseChatModel]:
+    """Construct OpenAI reasoning + bulk models."""
+    from langchain_openai import ChatOpenAI
+    if not settings.openai_api_key:
+        raise RuntimeError(
+            "LLM_PROVIDER=openai but OPENAI_API_KEY not set. "
+            "Add it to .env or switch LLM_PROVIDER to 'gemini'."
+        )
+    reasoning = ChatOpenAI(
+        model=settings.openai_reasoning_model,
+        temperature=temp_reasoning,
+        api_key=settings.openai_api_key,
+    )
+    bulk = ChatOpenAI(
+        model=settings.openai_bulk_model,
+        temperature=temp_bulk,
+        api_key=settings.openai_api_key,
+    )
+    return reasoning, bulk
+
+
+def _build_gemini_models(temp_reasoning: float, temp_bulk: float) -> tuple[BaseChatModel, BaseChatModel]:
+    """Construct Gemini reasoning + bulk models."""
+    try:
+        from langchain_google_genai import ChatGoogleGenerativeAI
+    except ImportError as e:
+        raise ImportError(
+            "LLM_PROVIDER=gemini but langchain-google-genai is not installed. "
+            "Run: pip install langchain-google-genai"
+        ) from e
+
+    if not settings.gemini_api_key:
+        raise RuntimeError(
+            "LLM_PROVIDER=gemini but GEMINI_API_KEY not set. "
+            "Get a key at https://aistudio.google.com/apikey and add it to .env."
+        )
+    reasoning = ChatGoogleGenerativeAI(
+        model=settings.gemini_reasoning_model,
+        temperature=temp_reasoning,
+        google_api_key=settings.gemini_api_key,
+    )
+    bulk = ChatGoogleGenerativeAI(
+        model=settings.gemini_bulk_model,
+        temperature=temp_bulk,
+        google_api_key=settings.gemini_api_key,
+    )
+    return reasoning, bulk
+
+
+class LLMClient:
+    """Two-tier, two-provider LLM client.
+
+    Tier 'reasoning' → flagship model (gpt-4o / gemini-2.5-flash).
+      Used for: review generation, recommendation reasoning, persona summarization.
+    Tier 'bulk' → cheap/fast model (gpt-4o-mini / gemini-2.5-flash-lite).
+      Used for: tone classification, vocabulary fingerprinting, lightweight ops.
+    """
+
+    def __init__(self, temperature_reasoning: float = 0.7,
+                 temperature_bulk: float = 0.3,
+                 provider: str | None = None):
+        self.provider = (provider or settings.llm_provider).lower()
+        log.info(f"LLMClient initializing with provider={self.provider!r}")
+
+        if self.provider == "openai":
+            self._reasoning, self._bulk = _build_openai_models(
+                temperature_reasoning, temperature_bulk,
+            )
+        elif self.provider == "gemini":
+            self._reasoning, self._bulk = _build_gemini_models(
+                temperature_reasoning, temperature_bulk,
+            )
+        else:
+            raise ValueError(
+                f"Unknown LLM_PROVIDER={self.provider!r}; expected 'openai' or 'gemini'"
+            )
+
+    def _model(self, tier: str) -> BaseChatModel:
+        if tier == "reasoning":
+            return self._reasoning
+        if tier == "bulk":
+            return self._bulk
+        raise ValueError(f"Unknown tier {tier!r}; expected 'reasoning' or 'bulk'")
+
+    # ──────────────────────────────────────────────────────────────────
+    # Free-form completion
+    # ──────────────────────────────────────────────────────────────────
+    @retry(stop=stop_after_attempt(3), wait=wait_exponential(min=1, max=10))
+    def complete(self, prompt: str, model: str = "bulk",
+                 system: str | None = None) -> str:
+        messages: list[Any] = []
+        if system:
+            messages.append(("system", system))
+        messages.append(("human", "{input}"))
+        chain = ChatPromptTemplate.from_messages(messages) | self._model(model)
+        result = chain.invoke({"input": prompt})
+        # Both providers return BaseMessage with .content as str
+        content = result.content
+        if isinstance(content, list):
+            # Gemini occasionally returns list of content parts; flatten
+            content = "".join(p.get("text", "") if isinstance(p, dict) else str(p) for p in content)
+        return content
+
+    # ──────────────────────────────────────────────────────────────────
+    # Structured output — pydantic-validated
+    # ──────────────────────────────────────────────────────────────────
+    @retry(stop=stop_after_attempt(3), wait=wait_exponential(min=1, max=10))
+    def structured(self, prompt: str, schema: Type[T], model: str = "reasoning",
+                   system: str | None = None) -> T:
+        """Run prompt, parse output into the given Pydantic schema.
+
+        Uses LangChain's PydanticOutputParser. The schema's format instructions
+        are appended to the prompt automatically.
+        """
+        parser = PydanticOutputParser(pydantic_object=schema)
+        format_instructions = parser.get_format_instructions()
+
+        messages: list[Any] = []
+        if system:
+            messages.append(("system", system))
+        messages.append((
+            "human",
+            "{input}\n\n{format_instructions}"
+        ))
+        chain = (
+            ChatPromptTemplate.from_messages(messages)
+            | self._model(model)
+            | parser
+        )
+        return chain.invoke({
+            "input": prompt,
+            "format_instructions": format_instructions,
+        })

core/nigerian.py

@@ -0,0 +1,118 @@
+"""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]

core/persona.py

@@ -0,0 +1,291 @@
+"""Persona engine — turn a user's review history into a behavioral fingerprint.
+
+The persona is the spine of the whole system. Both tasks ask it different
+questions:
+
+    Task A: "Given this persona and this item, how would the user rate and review it?"
+    Task B: "Given this persona, what items would the user want next?"
+
+A persona has two layers:
+
+    1. Quantitative signals (computed deterministically from history)
+       - rating cadence: mean, std, distribution shape
+       - review length: mean, std
+       - vocabulary fingerprint: top distinctive terms
+       - domain mix: which categories the user engages with
+       - verified-purchase rate, helpful-vote signal
+
+    2. Qualitative summary (LLM-generated, cached)
+       - tone descriptor (snarky / earnest / analytical / casual / ...)
+       - common preferences (themes, styles)
+       - common complaints (deal-breakers)
+       - recommended audience for THIS user (one-liner persona pitch)
+
+The qualitative layer is what makes generated reviews feel like the actual
+user wrote them. Without it, you get generic LLM prose. With it, you get
+behavioral fidelity — which is one of Task A's three scored axes.
+"""
+from __future__ import annotations
+
+import logging
+from collections import Counter
+from dataclasses import dataclass, field, asdict
+from typing import Any
+
+import pandas as pd
+from pydantic import BaseModel, Field
+
+from core.llm import LLMClient
+
+log = logging.getLogger(__name__)
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Schemas
+# ──────────────────────────────────────────────────────────────────────────────
+
+class QualitativeSummary(BaseModel):
+    """LLM-generated qualitative layer of a persona."""
+    tone: str = Field(description="One-word tone descriptor: snarky, earnest, analytical, casual, enthusiastic, terse, verbose, etc.")
+    preferred_themes: list[str] = Field(description="3-5 themes/styles/qualities this user gravitates toward")
+    common_complaints: list[str] = Field(description="2-4 recurring deal-breakers or critique patterns")
+    voice_one_liner: str = Field(description="A single sentence describing this user's reviewing voice as if pitching them to a casting director")
+
+
+@dataclass
+class UserPersona:
+    """Complete persona — quantitative signals + qualitative summary + history."""
+    user_id: str
+
+    # Quantitative
+    n_reviews: int
+    avg_rating: float
+    std_rating: float
+    avg_review_length: float
+    std_review_length: float
+    verified_rate: float
+    domains: list[str]
+    n_domains: int
+    rating_distribution: dict[int, float]   # {1: 0.05, 2: 0.1, ..., 5: 0.4}
+    top_terms: list[str]                    # vocabulary fingerprint
+
+    # Qualitative (lazily filled by PersonaEngine.enrich)
+    tone: str = ""
+    preferred_themes: list[str] = field(default_factory=list)
+    common_complaints: list[str] = field(default_factory=list)
+    voice_one_liner: str = ""
+
+    # Sample history for retrieval/grounding (subset of training reviews)
+    history_samples: list[dict[str, Any]] = field(default_factory=list)
+
+    def to_prompt_block(self) -> str:
+        """Render the persona as a structured prompt section.
+
+        This text is what the LLM sees when generating reviews / recommendations.
+        Keeping it formatted consistently is what makes generation behaviorally
+        faithful.
+        """
+        dist = " ".join(f"{r}★:{p:.0%}" for r, p in sorted(self.rating_distribution.items()))
+        return (
+            f"USER PERSONA\n"
+            f"  Reviews written: {self.n_reviews}\n"
+            f"  Avg rating: {self.avg_rating:.2f} (±{self.std_rating:.2f})\n"
+            f"  Rating distribution: {dist}\n"
+            f"  Avg review length: {self.avg_review_length:.0f} words (±{self.std_review_length:.0f})\n"
+            f"  Verified-purchase rate: {self.verified_rate:.0%}\n"
+            f"  Active domains: {', '.join(self.domains)}\n"
+            f"  Vocabulary fingerprint: {', '.join(self.top_terms[:15])}\n"
+            f"  Tone: {self.tone or 'unspecified'}\n"
+            f"  Preferred themes: {', '.join(self.preferred_themes) or 'unspecified'}\n"
+            f"  Common complaints: {', '.join(self.common_complaints) or 'unspecified'}\n"
+            f"  Voice: {self.voice_one_liner or 'unspecified'}\n"
+        )
+
+    def as_dict(self) -> dict:
+        return asdict(self)
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Engine
+# ──────────────────────────────────────────────────────────────────────────────
+
+# A small set of generic English stopwords + Amazon-review noise. Keeping
+# this in-module avoids pulling in nltk's download flow.
+_STOPWORDS = set("""
+a an the and or but if then else when while of in on at by to for with from
+into onto over under is are was were be been being have has had do does did
+i you he she it we they me him her us them my your his its our their this
+that these those there here what which who whom whose how why so as too very
+just also more most some any all each every other another such no not nor only
+own same can will would could should might may must one two three really get
+got gets just like dont didnt isnt arent wasnt werent havent hadnt hasnt cant
+couldnt wouldnt shouldnt wont thats whats theres heres ive ill ive youve im
+""".split())
+
+
+class PersonaEngine:
+    """Build personas from review history.
+
+    Two entry points:
+        from_dataframe(user_id, training_reviews_df) -> UserPersona
+        enrich(persona) -> UserPersona   # adds qualitative summary via LLM
+    """
+
+    def __init__(self, llm: LLMClient | None = None,
+                 top_terms_k: int = 20,
+                 history_samples_k: int = 8):
+        self.llm = llm or LLMClient()
+        self.top_terms_k = top_terms_k
+        self.history_samples_k = history_samples_k
+
+    # ─────────────────────────── Quantitative ────────────────────────────
+    def from_dataframe(self, user_id: str,
+                       reviews: pd.DataFrame) -> UserPersona:
+        """Build a UserPersona from a DataFrame of one user's training reviews.
+
+        Expected columns: user_id, parent_asin, rating, text, verified_purchase,
+                          domain, timestamp.
+        """
+        user_reviews = reviews[reviews["user_id"] == user_id]
+        if user_reviews.empty:
+            raise ValueError(f"No reviews found for user_id={user_id!r}")
+
+        ratings = user_reviews["rating"].astype(float)
+        lengths = user_reviews["text"].fillna("").str.split().str.len()
+
+        # Rating distribution as proportions
+        dist = ratings.round().astype(int).value_counts(normalize=True).to_dict()
+        rating_dist = {int(k): float(v) for k, v in dist.items()}
+
+        # Vocabulary fingerprint: most common non-stopword tokens
+        top_terms = self._top_terms(user_reviews["text"].tolist())
+
+        # Sample history items for retrieval grounding — keep the most recent
+        history = user_reviews.sort_values("timestamp", ascending=False) \
+                              .head(self.history_samples_k)
+        history_samples = [
+            {
+                "parent_asin": row["parent_asin"],
+                "rating": float(row["rating"]),
+                "text": row["text"][:500],
+                "domain": row["domain"],
+            }
+            for _, row in history.iterrows()
+        ]
+
+        return UserPersona(
+            user_id=user_id,
+            n_reviews=len(user_reviews),
+            avg_rating=float(ratings.mean()),
+            std_rating=float(ratings.std()) if len(ratings) > 1 else 0.0,
+            avg_review_length=float(lengths.mean()),
+            std_review_length=float(lengths.std()) if len(lengths) > 1 else 0.0,
+            verified_rate=float(user_reviews["verified_purchase"].mean()),
+            domains=sorted(user_reviews["domain"].unique().tolist()),
+            n_domains=int(user_reviews["domain"].nunique()),
+            rating_distribution=rating_dist,
+            top_terms=top_terms,
+            history_samples=history_samples,
+        )
+
+    def _top_terms(self, texts: list[str]) -> list[str]:
+        """Most frequent content tokens, stopwords removed."""
+        counter: Counter = Counter()
+        for txt in texts:
+            if not isinstance(txt, str):
+                continue
+            tokens = [t.lower().strip(".,!?\"'()[]{}:;") for t in txt.split()]
+            tokens = [t for t in tokens
+                      if t and len(t) > 2 and t not in _STOPWORDS and t.isalpha()]
+            counter.update(tokens)
+        return [w for w, _ in counter.most_common(self.top_terms_k)]
+
+    # ─────────────────────────── Qualitative ─────────────────────────────
+    def enrich(self, persona: UserPersona) -> UserPersona:
+        """Add LLM-generated qualitative summary to an existing persona.
+
+        Uses the reasoning model (gpt-4o) — more reliable structured output
+        than the bulk model. If the LLM call still fails, falls back to a
+        deterministic summary derived from the writing samples so we never
+        end up with an empty Voice/Tone.
+        """
+        if not persona.history_samples:
+            log.warning(f"User {persona.user_id} has no history samples; skipping enrichment")
+            return self._apply_deterministic_fallback(persona)
+
+        sample_block = "\n\n".join(
+            f"[{i+1}] Rating: {s['rating']}★  Domain: {s['domain']}\n{s['text'][:400]}"
+            for i, s in enumerate(persona.history_samples)
+        )
+
+        prompt = (
+            f"Below are review samples from a single user. Read them carefully "
+            f"and infer their reviewing voice.\n\n"
+            f"{sample_block}\n\n"
+            f"Quantitative signals about this user:\n"
+            f"- Average rating: {persona.avg_rating:.2f} of 5\n"
+            f"- Average review length: {persona.avg_review_length:.0f} words\n"
+            f"- Vocabulary they use often: {', '.join(persona.top_terms[:15])}\n\n"
+            f"Produce a qualitative summary of their reviewer voice. "
+            f"Be concise and concrete. If the samples are too sparse or generic, "
+            f"infer the most plausible voice rather than refusing."
+        )
+
+        try:
+            summary = self.llm.structured(
+                prompt, QualitativeSummary, model="reasoning",
+                system="You are a behavioral analyst specializing in online review patterns. Always produce valid output.",
+            )
+            persona.tone = summary.tone or persona.tone
+            persona.preferred_themes = summary.preferred_themes or persona.preferred_themes
+            persona.common_complaints = summary.common_complaints or persona.common_complaints
+            persona.voice_one_liner = summary.voice_one_liner or persona.voice_one_liner
+        except Exception as e:
+            log.warning(f"LLM enrichment failed for {persona.user_id} ({type(e).__name__}); using deterministic fallback")
+            persona = self._apply_deterministic_fallback(persona)
+
+        return persona
+
+    @staticmethod
+    def _apply_deterministic_fallback(persona: UserPersona) -> UserPersona:
+        """Fill in tone/themes/voice from quantitative signals when LLM fails.
+
+        This isn't as rich as an LLM summary, but it guarantees downstream
+        query construction has SOMETHING to work with — much better than
+        an empty string.
+        """
+        # Tone bucket from avg rating
+        if persona.avg_rating >= 4.5:
+            tone = "enthusiastic"
+        elif persona.avg_rating >= 3.8:
+            tone = "earnest"
+        elif persona.avg_rating >= 3.0:
+            tone = "measured"
+        else:
+            tone = "critical"
+
+        # Use top distinctive terms as proxy themes (filter out true generics)
+        generic_terms = {"book", "read", "story", "movie", "film", "great", "good",
+                         "really", "much", "first", "next", "through", "about"}
+        candidate_themes = [t for t in persona.top_terms if t not in generic_terms][:5]
+        themes = candidate_themes or persona.top_terms[:3]
+
+        # Domain-grounded voice
+        domain_str = "/".join(persona.domains) if persona.domains else "general"
+        length_descriptor = (
+            "writes brief reviews" if persona.avg_review_length < 30
+            else "writes detailed reviews" if persona.avg_review_length > 150
+            else "writes moderate-length reviews"
+        )
+        voice = (
+            f"A {tone} {domain_str} reviewer who {length_descriptor} "
+            f"(avg {persona.avg_rating:.1f}★ over {persona.n_reviews} reviews)."
+        )
+
+        if not persona.tone:
+            persona.tone = tone
+        if not persona.preferred_themes:
+            persona.preferred_themes = themes
+        if not persona.voice_one_liner:
+            persona.voice_one_liner = voice
+        return persona

core/reflection.py

@@ -0,0 +1,322 @@
+"""Self-reflection — the act → critique → revise loop.
+
+This is what makes NaijaTaste AI an agent rather than a one-shot pipeline.
+After a first-pass output, the agent critiques its own work against the
+persona and, if the critique finds problems, revises.
+
+Two public entry points:
+
+  reflect_on_review(...)   — Task A: critique + refine a generated review
+  reflect_on_recommendations(...) — Task B: critique + refine a top-N list
+
+Each runs at most `max_iterations` revise cycles (default 2). The loop
+stops early once the critique passes (no blocking issues). Every cycle is
+logged so the paper can report how often refinement triggered and what it
+changed.
+
+Reference: Madaan et al. 2023, "Self-Refine: Iterative Refinement with
+Self-Feedback"; Shinn et al. 2023, "Reflexion".
+"""
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+from core.llm import LLMClient
+from core.persona import UserPersona
+
+log = logging.getLogger(__name__)
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Critique schemas
+# ──────────────────────────────────────────────────────────────────────────────
+
+class ReviewCritique(BaseModel):
+    """The critique LLM's assessment of a generated review (Task A)."""
+    rating_text_consistent: bool = Field(
+        description="True if the review text matches the star rating "
+                    "(e.g. a 4-star review doesn't read like a 2-star pan)"
+    )
+    voice_match: bool = Field(
+        description="True if the review sounds like THIS user — their length, "
+                    "register, vocabulary, and quirks"
+    )
+    on_topic: bool = Field(
+        description="True if the review is about the actual item, not generic filler"
+    )
+    issues: str = Field(
+        description="If any check failed, a specific 1-2 sentence description of what "
+                    "to fix. If all passed, the string 'none'."
+    )
+
+    @property
+    def passed(self) -> bool:
+        return self.rating_text_consistent and self.voice_match and self.on_topic
+
+
+class RecommendationCritique(BaseModel):
+    """The critique LLM's assessment of a top-N recommendation list (Task B)."""
+    titles_are_real: bool = Field(
+        description="True if the recommended items look like real products, "
+                    "not review-headline fragments"
+    )
+    well_matched: bool = Field(
+        description="True if the picks genuinely fit the persona's tastes"
+    )
+    reasoning_grounded: bool = Field(
+        description="True if each pick's reasoning cites specific persona signals, "
+                    "not generic filler"
+    )
+    diverse_enough: bool = Field(
+        description="True if the list isn't 10 near-identical items"
+    )
+    issues: str = Field(
+        description="If any check failed, a specific 1-2 sentence description of what "
+                    "to fix. If all passed, the string 'none'."
+    )
+
+    @property
+    def passed(self) -> bool:
+        return (self.titles_are_real and self.well_matched
+                and self.reasoning_grounded and self.diverse_enough)
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Reflection trace (for logging / paper reporting)
+# ──────────────────────────────────────────────────────────────────────────────
+
+@dataclass
+class ReflectionTrace:
+    """Record of what the reflection loop did — useful for the paper."""
+    iterations_run: int = 0
+    critiques: list[str] = field(default_factory=list)   # issues found each cycle
+    passed_final: bool = False
+    refined: bool = False  # True if at least one revision happened
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Task A — review reflection
+# ──────────────────────────────────────────────────────────────────────────────
+
+def _critique_review(llm: LLMClient, persona: UserPersona,
+                     item_title: str, item_domain: str,
+                     rating: float, review: str) -> ReviewCritique:
+    """One critique pass over a generated review."""
+    prompt = (
+        f"You are a strict editor checking whether an AI-generated review "
+        f"faithfully imitates a specific user. Be critical — your job is to "
+        f"catch problems, not to be nice.\n\n"
+        f"{'=' * 55}\n"
+        f"THE USER\n"
+        f"{'=' * 55}\n"
+        f"{persona.to_prompt_block()}\n\n"
+        f"{'=' * 55}\n"
+        f"ITEM REVIEWED\n"
+        f"{'=' * 55}\n"
+        f"Domain: {item_domain}\n"
+        f"Title: {item_title}\n\n"
+        f"{'=' * 55}\n"
+        f"THE GENERATED REVIEW (check this)\n"
+        f"{'=' * 55}\n"
+        f"Rating: {rating}\u2605\n"
+        f"Review: {review}\n\n"
+        f"{'=' * 55}\n"
+        f"YOUR CHECKS\n"
+        f"{'=' * 55}\n"
+        f"1. rating_text_consistent: Does the review TEXT match the {rating}-star "
+        f"rating? A 4-5 star review should read positive; a 1-2 star review should "
+        f"read negative; a 3 should read mixed.\n"
+        f"2. voice_match: Does it sound like THIS user? Check their typical review "
+        f"length ({persona.avg_review_length:.0f} words avg), tone ({persona.tone}), "
+        f"and quirks. A terse user given a long essay = fail. A user who writes in "
+        f"all-caps given lowercase = fail.\n"
+        f"3. on_topic: Is the review about the actual item, or is it generic filler "
+        f"that could apply to anything?\n\n"
+        f"If any check fails, describe specifically what to fix in 'issues'. "
+        f"If all pass, set 'issues' to 'none'."
+    )
+    return llm.structured(
+        prompt, ReviewCritique, model="reasoning",
+        system="You are a meticulous editor. Catch every inconsistency.",
+    )
+
+
+def _refine_review(llm: LLMClient, persona: UserPersona,
+                   item_title: str, item_domain: str,
+                   prev_rating: float, prev_review: str,
+                   critique_issues: str) -> tuple[float, str]:
+    """Regenerate a review given critique feedback. Returns (rating, review)."""
+
+    class RefinedReview(BaseModel):
+        rating: float = Field(description="Star rating 1.0-5.0")
+        review: str = Field(description="The improved review in the user's voice")
+
+    prompt = (
+        f"You previously wrote a review imitating a specific user, but an editor "
+        f"found problems. Rewrite the review to fix them.\n\n"
+        f"{'=' * 55}\n"
+        f"THE USER\n"
+        f"{'=' * 55}\n"
+        f"{persona.to_prompt_block()}\n\n"
+        f"ITEM: [{item_domain}] {item_title}\n\n"
+        f"YOUR PREVIOUS ATTEMPT:\n"
+        f"  Rating: {prev_rating}\u2605\n"
+        f"  Review: {prev_review}\n\n"
+        f"EDITOR'S FEEDBACK — fix these specific issues:\n"
+        f"  {critique_issues}\n\n"
+        f"Rewrite the review addressing the feedback. Keep what worked; fix what "
+        f"the editor flagged. Stay in the user's authentic voice."
+    )
+    result = llm.structured(
+        prompt, RefinedReview, model="reasoning",
+        system="You are an expert behavioral simulator revising your work based on feedback.",
+    )
+    return result.rating, result.review
+
+
+def reflect_on_review(llm: LLMClient, persona: UserPersona,
+                      item_title: str, item_domain: str,
+                      rating: float, review: str,
+                      max_iterations: int = 2) -> tuple[float, str, ReflectionTrace]:
+    """Critique a generated review and refine it if needed.
+
+    Returns: (final_rating, final_review, trace)
+
+    The loop:
+      1. Critique the current review.
+      2. If it passes → stop, return as-is.
+      3. If it fails → refine using the critique, then critique again.
+      4. Stop after max_iterations even if still imperfect.
+    """
+    trace = ReflectionTrace()
+    cur_rating, cur_review = rating, review
+
+    for i in range(max_iterations):
+        try:
+            critique = _critique_review(llm, persona, item_title, item_domain,
+                                        cur_rating, cur_review)
+        except Exception as e:
+            log.warning(f"Review critique failed ({type(e).__name__}); "
+                        f"keeping current review")
+            break
+
+        trace.iterations_run = i + 1
+        if critique.passed:
+            trace.critiques.append("passed")
+            trace.passed_final = True
+            log.info(f"Review reflection: passed on iteration {i + 1}")
+            break
+
+        trace.critiques.append(critique.issues)
+        log.info(f"Review reflection iter {i + 1}: issues = {critique.issues}")
+
+        # Refine
+        try:
+            cur_rating, cur_review = _refine_review(
+                llm, persona, item_title, item_domain,
+                cur_rating, cur_review, critique.issues,
+            )
+            trace.refined = True
+        except Exception as e:
+            log.warning(f"Review refine failed ({type(e).__name__}); "
+                        f"keeping pre-refine review")
+            break
+
+    return cur_rating, cur_review, trace
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Task B — recommendation reflection
+# ──────────────────────────────────────────────────────────────────────────────
+
+def _critique_recommendations(llm: LLMClient, persona: UserPersona,
+                              recommendations: list[dict],
+                              mode: str) -> RecommendationCritique:
+    """One critique pass over a recommendation list."""
+    rec_block = "\n".join(
+        f"  #{i+1} [{r['domain']}] {r['title']}\n     Why: {r['reasoning']}"
+        for i, r in enumerate(recommendations)
+    )
+    prompt = (
+        f"You are a strict reviewer checking the quality of a recommendation "
+        f"list. Be critical — catch problems.\n\n"
+        f"{'=' * 55}\n"
+        f"THE USER\n"
+        f"{'=' * 55}\n"
+        f"{persona.to_prompt_block()}\n\n"
+        f"{'=' * 55}\n"
+        f"THE RECOMMENDATIONS (mode: {mode})\n"
+        f"{'=' * 55}\n"
+        f"{rec_block}\n\n"
+        f"{'=' * 55}\n"
+        f"YOUR CHECKS\n"
+        f"{'=' * 55}\n"
+        f"1. titles_are_real: Do these look like real product titles? FAIL if any "
+        f"are review-headline fragments like 'Fast paced great read' or 'An "
+        f"enjoyable read' or 'Loved it!'.\n"
+        f"2. well_matched: Do the picks genuinely fit this user's tastes?\n"
+        f"3. reasoning_grounded: Does each 'Why' cite specific persona signals, "
+        f"or is it generic filler?\n"
+        f"4. diverse_enough: Is there real variety, or are these 10 near-identical "
+        f"items?\n\n"
+        f"If any check fails, describe specifically what to fix in 'issues' "
+        f"(e.g. 'items #4, #7, #9 have review-headline titles — replace them'). "
+        f"If all pass, set 'issues' to 'none'."
+    )
+    return llm.structured(
+        prompt, RecommendationCritique, model="reasoning",
+        system="You are a meticulous recommendation-quality auditor.",
+    )
+
+
+def reflect_on_recommendations(llm: LLMClient, persona: UserPersona,
+                               recommendations: list[dict], mode: str,
+                               refine_fn,
+                               max_iterations: int = 2,
+                               ) -> tuple[list[dict], ReflectionTrace]:
+    """Critique a recommendation list and refine if needed.
+
+    Unlike review reflection, refinement here can't just rewrite text — it
+    needs to re-run reranking with feedback. So the caller passes a
+    `refine_fn(issues: str) -> list[dict]` that re-runs the rerank with the
+    critique injected, and this function orchestrates the loop.
+
+    Returns: (final_recommendations, trace)
+    """
+    trace = ReflectionTrace()
+    cur_recs = recommendations
+
+    for i in range(max_iterations):
+        try:
+            critique = _critique_recommendations(llm, persona, cur_recs, mode)
+        except Exception as e:
+            log.warning(f"Recommendation critique failed ({type(e).__name__}); "
+                        f"keeping current list")
+            break
+
+        trace.iterations_run = i + 1
+        if critique.passed:
+            trace.critiques.append("passed")
+            trace.passed_final = True
+            log.info(f"Recommendation reflection: passed on iteration {i + 1}")
+            break
+
+        trace.critiques.append(critique.issues)
+        log.info(f"Recommendation reflection iter {i + 1}: issues = {critique.issues}")
+
+        # Refine via the caller-supplied function
+        try:
+            refined = refine_fn(critique.issues)
+            if refined:
+                cur_recs = refined
+                trace.refined = True
+        except Exception as e:
+            log.warning(f"Recommendation refine failed ({type(e).__name__}); "
+                        f"keeping pre-refine list")
+            break
+
+    return cur_recs, trace