Israelbliz/User-Modeling-Agent

1---2title: User Modeling Agent3emoji: 📝4colorFrom: green5colorTo: red6sdk: docker7app_port: 78608pinned: false9---10 11# User Modeling Agent12 13**DSN × BCT LLM Agent Challenge 2026 — Task A.**14 15An agent that reads a person into a behavioural *persona*, then writes the16star rating and the review that person would leave for an unseen product —17and critiques and revises its own draft before returning it.18 19> Live demo: https://huggingface.co/spaces/Israelbliz/User-Modeling-Agent20 21> Code: https://huggingface.co/spaces/Israelbliz/User-Modeling-Agent/tree/main22 23---24 25## What it does26 27Given a **person** and **product details**, the agent produces:28 29- a **star rating** (1–5) the person would likely give, and30- a **written review** in that person's voice — tone, length, and quirks matched.31 32It is not a generic review generator. Every output is conditioned on a33specific person, and the rating is reasoned, not guessed.34 35## Three input modes36 37The same persona engine is fed by three input modes:38 39- **Compose a persona** — describe the person's reviewing voice in free text.40- **Dataset reader** — a real user from the data; the agent is scored against41  a genuinely held-out review.42- **Build from past reviews** — paste a few of the person's actual past43  reviews, and the agent builds the persona from them.44 45## The agentic workflow46 47The system is an agent, not a single prompt. It runs a five-step loop:48 491. **Build the persona.** A `PersonaEngine` extracts a structured persona —50   quantitative signals (average rating, rating spread, review length,51   domains, rating distribution) and a qualitative voice (tone, preferred52   themes, common complaints, a one-line voice descriptor) distilled by an53   LLM from sample reviews, with a deterministic fallback if that call fails.54 552. **Select grounding history.** For a real person, the agent picks the few56   past reviews most similar to the target item, so it writes from concrete57   evidence of how this person actually phrases things.58 593. **Generate the rating and review.** A single LLM call, with the rating60   reasoned in two explicit steps — first the persona *prior* (what this61   person usually gives), then the *item evidence* (what the title and62   description signal). The final rating is the prior adjusted by the63   evidence, so a generous reviewer still rates a poor item low and a64   critical reviewer still rates a strong item high.65 664. **Self-reflection — critique and revise.** A critic LLM audits the draft67   for rating–text consistency, voice match, and on-topic fit. If it objects,68   the agent rewrites with that feedback and re-checks — up to two cycles.69   This act → critique → revise loop is what makes it an agent.70 715. **Post-process.** The rating is clamped to range. An optional Nigerian72   Pidgin rendering layer can restyle the review while preserving meaning,73   sentiment, and rating.74 75## Reliability76 77- **Provider failover.** The agent runs a primary and a secondary LLM78  provider. If the primary fails — quota, rate limit or a transient service79  error — the same call is retried automatically on the secondary, so a live80  demo does not break when one provider is briefly unavailable.81- **Graceful degradation.** If an LLM call fails, the agent falls back to a82  deterministic persona rather than crashing.83 84## How it maps to the Task A rubric85 86- **Review Text Quality** — reviews are grounded in the person's real past87  reviews and self-critiqued for voice match.88- **Rating Accuracy** — the two-step prior-plus-evidence rating logic89  corrects the common failure of predicting from the user average alone.90- **Behavioural Fidelity** — persona-conditioned generation; the persona91  portrait is visible in the app for inspection.92- **Nigerian contextualization (bonus)** — a toggleable Nigerian Pidgin93  rendering layer; off by default so scored output stays standard English.94 95## Running locally96 97```bash98pip install -r requirements.txt99# set your keys in a .env file:100#   LLM_PROVIDER=openai101#   OPENAI_API_KEY=...102#   GEMINI_API_KEY=...103streamlit run app.py104```105 106`LLM_PROVIDER` sets the primary provider; the other provider, if its key is107present, is used as the automatic failover. The processed data108(`data/processed/*.parquet`) must be present.109 110## Project layout111 112```113core/                 shared engine — config, llm, persona, reflection, nigerian114task_a_user_modeling/ the User Modeling agent115scripts/              test harness (test_task_a.py)116data/processed/       Amazon Reviews 2023 — Books · Movies & TV · Kindle Store117app.py                Streamlit demo — three input modes118```119 120## Configuration121 122Set in a `.env` file (never commit it):123 124- `LLM_PROVIDER` — `openai` or `gemini` (the primary provider)125- `OPENAI_API_KEY` / `GEMINI_API_KEY` — both should be set so the unused one126  serves as the automatic failover127 128On a HuggingFace Space, set these as **Secrets** in Space settings.129 130## Notes and honest limitations131 132- The self-reflection critic checks internal consistency; it cannot catch a133  rating that is wrong but self-consistent.134- Rating prediction on hard cases (a critical user who loved something) is135  improved by the two-step logic but can still be ~0.5–1.0★ off.136- LLM output is non-deterministic; single-run results vary, so evaluation137  averages across many users.138 139## Credits140 141Built for the DSN × BCT LLM Agent Challenge 2026.142Author: Israel Akomodesegbe. Team: Winning Team. Dataset: Amazon Reviews 2023.143