Deploy Vera deterministic bot

.dockerignore

@@ -0,0 +1,10 @@
+__pycache__/
+.pytest_cache/
+.venv/
+venv/
+expanded/
+*.pyc
+*.log
+.pytest_cache/
+__pycache__/
+.git/

.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+.pytest_cache/
+*.pyc
+*.log
+.venv/
+venv/
+expanded/

Dockerfile

@@ -0,0 +1,16 @@
+FROM python:3.11-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+ENV PORT=7860
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+EXPOSE 7860
+
+CMD ["sh", "-c", "uvicorn app.main:app --host 0.0.0.0 --port ${PORT:-7860}"]

Procfile

@@ -0,0 +1,2 @@
+web: uvicorn app.main:app --host 0.0.0.0 --port ${PORT:-8080}
+

README.md

@@ -1,10 +1,136 @@
 ---
 title: Vera Rubric Decision Engine
-emoji: 🌖
-colorFrom: blue
-colorTo: green
 sdk: docker
+app_port: 7860
+license: mit
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Vera Rubric Decision Engine
+
+Submission bot for the magicpin Vera AI Challenge. It exposes the required HTTP API, stores judge-pushed context in memory, and composes grounded merchant/customer actions from the JSON context it receives.
+
+The live bot does not require a paid API key. If `OPENAI_API_KEY` is present, it can polish copy after deterministic planning, but the deterministic engine remains the source of truth and invalid LLM output is discarded. OpenRouter can be used only for offline G-Eval-style calibration.
+
+## How It Works
+
+1. The judge pushes category, merchant, customer, and trigger JSON into `POST /v1/context`.
+2. `POST /v1/tick` ranks active triggers by expected rubric score and returns up to 20 message actions.
+3. `POST /v1/reply` handles auto-replies, commitment, off-topic replies, STOP/hostility, and ended conversations.
+4. `POST /v1/teardown` clears in-memory state for clean reruns.
+
+Required endpoints:
+
+- `GET /v1/healthz`
+- `GET /v1/metadata`
+- `POST /v1/context`
+- `POST /v1/tick`
+- `POST /v1/reply`
+- `POST /v1/teardown`
+
+## Scoring Strategy
+
+The composer is a rubric-optimized decision engine:
+
+- Extracts evidence from merchant, category, trigger, and customer context.
+- Flattens nested context into a MerchantCAR so every downstream decision sees stable field names.
+- Uses JITAI-style severity/receptivity/intervention-fit scores to decide whether the moment is worth acting on.
+- Uses Fogg B=MAP scores to separate motivation, CTA ability, and prompt timing.
+- Applies prospect-theory plus Cialdini framing: loss recovery, gain momentum, scarcity, social proof, authority, reciprocity, commitment, or liking.
+- Builds deterministic Tree-of-Thought frame diagnostics and Best-of-N variants for each trigger.
+- Runs a deterministic constitutional audit/repair pass for generic copy, multiple CTAs, corporate tone, weak facts, and repeated weak action types.
+- Uses empirical category action priors from in-memory reply outcomes to reduce cold-start action mistakes without random live exploration.
+- Scores each candidate across decision quality, specificity, category fit, merchant fit, and engagement compulsion.
+- Sends only the highest-scoring valid action.
+- Uses category playbooks for dentists, salons, restaurants, gyms, and pharmacies.
+- Validates output for hallucinated numbers, `None` leaks, repeated `Dr. Dr.`, weak generic copy, repeated bodies, missing CTA shape, and unsafe customer outreach.
+
+Every sent message should include why now, a real merchant/category/customer fact, one CTA, category-appropriate voice, and a low-friction next action.
+
+## Run Locally
+
+```bash
+python -m pip install -r requirements-dev.txt
+python dataset/generate_dataset.py --seed-dir dataset --out expanded
+uvicorn app.main:app --host 0.0.0.0 --port 8080
+```
+
+In another terminal:
+
+```bash
+pytest -q
+python -m compileall app bot.py scripts tests
+python scripts/generate_submission.py
+python scripts/lint_submission.py
+python scripts/score_proxy.py 34
+python scripts/geval_calibrate.py
+```
+
+`scripts/geval_calibrate.py` skips cleanly unless `OPENROUTER_API_KEY` is set. The official `judge_simulator.py` also needs a scorer LLM key. The hosted bot itself does not need one.
+
+## Optional LLM Copy Polish
+
+Set these only if you want controlled copy improvement:
+
+- `OPENAI_API_KEY`
+- `OPENAI_MODEL`, default `gpt-4o-mini`
+
+The model receives only the deterministic plan and evidence. It must return structured JSON with `body`, `cta`, `send_as`, `suppression_key`, and `rationale`. The bot falls back to deterministic copy if the call fails, times out, changes protected fields, or invents numbers.
+
+## Optional OpenRouter Calibration
+
+Set these only for offline quality checks:
+
+- `OPENROUTER_API_KEY`
+- `OPENROUTER_MODEL`, default `openrouter/auto`
+- `GEVAL_LIMIT`, default `10`
+
+This script critiques generated `submission.jsonl` rows against the five official dimensions with a Prometheus-style reference bank and reports low-scoring cases. It is intentionally not called by `/v1/tick`.
+
+## Free Deployment
+
+Primary target: Koyeb Free Instance.
+
+Start command:
+
+```bash
+uvicorn app.main:app --host 0.0.0.0 --port $PORT
+```
+
+Health check path:
+
+```text
+/v1/healthz
+```
+
+Use one process/worker only. State is in memory, so multiple workers would split conversations and suppression keys.
+
+Backup targets:
+
+- Render Free Web Service using `render.yaml`
+- Hugging Face Docker Space using `Dockerfile`
+
+Free hosts can sleep. Before submission, hit `/v1/healthz`, then keep it warm:
+
+```bash
+python scripts/keep_warm.py https://your-bot.example --interval 900
+```
+
+## Required Submission Details
+
+Set these deployment environment variables:
+
+- `CONTACT_EMAIL`: `mokshagnak004@gmail.com`
+- `TEAM_NAME`: optional display name
+- `TEAM_MEMBER`: optional member name
+- `SUBMITTED_AT`: optional ISO timestamp
+
+You do not need OpenAI, Groq, Gemini, OpenRouter, Redis, Postgres, or any paid key for the live deterministic bot.
+
+## Tradeoffs
+
+In-memory state is simple, private, and fast, but the service must run as a single worker and should not restart during judging. Free LLM APIs are useful for local experiments, but relying on free quota during live judging is risky, so this bot treats LLM usage as optional polish only.
+
+## What More Context Would Help
+
+Quality would improve further with verified customer consent mappings, real slot inventory, item-level order or dispense history, offer eligibility rules, customer segment aggregates, and locality-level peer benchmarks. When those facts are absent, the bot avoids inventing them.

app/__init__.py

@@ -0,0 +1,2 @@
+"""Deterministic Vera challenge bot package."""
+

app/composer.py

@@ -0,0 +1,659 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+import hashlib
+import re
+
+from .decision_engine import compose_scored
+
+
+Context = dict[str, Any]
+
+
+CTA_NONE = "none"
+CTA_OPEN = "open_ended"
+CTA_YES_NO = "binary_yes_no"
+CTA_CONFIRM = "binary_confirm_cancel"
+CTA_SLOTS = "multi_choice_slot"
+
+
+def compose(category: Context, merchant: Context, trigger: Context, customer: Context | None = None) -> Context:
+    """Compose a deterministic, context-grounded Vera message."""
+    scored = compose_scored(category, merchant, trigger, customer)
+    if scored:
+        return validate_message(scored)
+    if customer:
+        return _compose_customer(category, merchant, trigger, customer)
+    return _compose_merchant(category, merchant, trigger)
+
+
+def reply_to_message(
+    message: str,
+    conversation: Context | None = None,
+    merchant: Context | None = None,
+    trigger: Context | None = None,
+) -> Context:
+    """Respond to a merchant/customer reply without using an LLM."""
+    text = (message or "").strip()
+    lower = text.lower()
+    conversation = conversation or {}
+    auto_count = int(conversation.get("auto_reply_count", 0))
+
+    if is_stop_or_hostile(lower):
+        return {
+            "action": "end",
+            "rationale": "The sender explicitly rejected further messages or used hostile stop language; ending without another nudge.",
+        }
+
+    if is_auto_reply(text):
+        if auto_count >= 3:
+            return {
+                "action": "end",
+                "rationale": "Repeated canned auto-reply detected three times; closing the conversation to avoid wasting turns.",
+            }
+        if auto_count == 2:
+            return {
+                "action": "wait",
+                "wait_seconds": 86400,
+                "rationale": "Same auto-reply repeated; owner is likely unavailable, so Vera waits 24 hours.",
+            }
+        return {
+            "action": "wait",
+            "wait_seconds": 14400,
+            "rationale": "Canned WhatsApp Business auto-reply detected; backing off 4 hours for a real owner reply.",
+        }
+
+    if is_commitment(lower):
+        scope = _action_scope(merchant or {}, trigger or {})
+        return {
+            "action": "send",
+            "body": f"Done. I am preparing {scope} now from the details already shared. I will keep it to one ready-to-send draft/action and avoid adding anything not in your current context.",
+            "cta": CTA_NONE,
+            "rationale": "The sender committed; switching directly to action mode without another qualification or confirmation loop.",
+        }
+
+    if is_offtopic(lower):
+        return {
+            "action": "send",
+            "body": "That is outside what I can help with directly. Coming back to this Vera task: should I prepare the draft/action from the details above?",
+            "cta": CTA_YES_NO,
+            "rationale": "Politely declines an off-topic request and returns to the active merchant-growth task.",
+        }
+
+    if is_delay(lower):
+        return {
+            "action": "wait",
+            "wait_seconds": 1800,
+            "rationale": "The sender asked for time or signaled they are busy; wait 30 minutes.",
+        }
+
+    if "?" in text or any(w in lower for w in ["what", "how", "price", "cost", "details", "send"]):
+        return {
+            "action": "send",
+            "body": "Yes. I can keep it simple: I will draft one ready-to-send version using only your current offer, locality, and the trigger we discussed. Reply YES and I will prepare it.",
+            "cta": CTA_YES_NO,
+            "rationale": "The sender is engaged and asking for details; answer briefly and request one low-friction confirmation.",
+        }
+
+    return {
+        "action": "send",
+        "body": "Got it. Should I prepare the next draft/action for this now?",
+        "cta": CTA_YES_NO,
+        "rationale": "Acknowledges an ambiguous but non-negative reply and asks for one clear next step.",
+    }
+
+
+def is_auto_reply(message: str) -> bool:
+    lower = (message or "").lower().strip()
+    patterns = [
+        "thank you for contacting",
+        "thanks for contacting",
+        "our team will respond",
+        "we will respond shortly",
+        "we are currently unavailable",
+        "business hours",
+        "automated assistant",
+        "auto-reply",
+        "away message",
+        "will get back to you",
+    ]
+    return any(p in lower for p in patterns)
+
+
+def is_stop_or_hostile(lower: str) -> bool:
+    if re.search(r"\b(stop|unsubscribe|remove me|opt out)\b", lower):
+        return True
+    hard_stops = [
+        "stop messaging",
+        "stop sending",
+        "unsubscribe",
+        "not interested",
+        "dont message",
+        "don't message",
+        "useless spam",
+        "spam",
+        "leave me",
+        "bothering me",
+    ]
+    return any(p in lower for p in hard_stops)
+
+
+def is_commitment(lower: str) -> bool:
+    commitments = [
+        r"\byes\b",
+        r"\bok\b",
+        r"\bokay\b",
+        r"\bgo ahead\b",
+        r"\blets do it\b",
+        r"\blet's do it\b",
+        r"\bconfirm\b",
+        r"\bproceed\b",
+        r"\bsend it\b",
+        r"\bdo it\b",
+        r"\bstart\b",
+        r"\bi want to join\b",
+        r"\bmujhe magicpin\b",
+        r"\bchalo\b",
+    ]
+    return any(re.search(pattern, lower) for pattern in commitments)
+
+
+def is_delay(lower: str) -> bool:
+    return any(p in lower for p in ["later", "busy", "after some time", "tomorrow", "call later", "not now"])
+
+
+def is_offtopic(lower: str) -> bool:
+    return any(p in lower for p in ["gst", "tax", "income tax", "hiring", "salary", "loan", "rent agreement", "website design", "cricket score", "weather", "movie ticket"])
+
+
+def validate_message(message: Context) -> Context:
+    """Normalize shape and remove risky leftovers."""
+    body = _clean(str(message.get("body", "")))
+    if not body:
+        body = "Quick Vera update: I found one relevant action from your current context. Want me to prepare it?"
+    cta = message.get("cta") or CTA_OPEN
+    if cta not in {CTA_NONE, CTA_OPEN, CTA_YES_NO, CTA_CONFIRM, CTA_SLOTS, "binary_yes_stop"}:
+        cta = CTA_OPEN
+    body = _final_scrub(body)
+    message["body"] = body[:1800]
+    message["cta"] = cta
+    message.setdefault("send_as", "vera")
+    message.setdefault("suppression_key", "")
+    message.setdefault("rationale", "Composed deterministically from category, merchant, trigger, and optional customer context.")
+    return message
+
+
+def make_conversation_id(merchant_id: str, trigger_id: str, customer_id: str | None = None) -> str:
+    base = f"{merchant_id}:{trigger_id}:{customer_id or ''}"
+    digest = hashlib.sha1(base.encode("utf-8")).hexdigest()[:8]
+    merchant_short = _short_id(merchant_id)
+    trigger_short = _short_id(trigger_id)
+    if customer_id:
+        return f"conv_{merchant_short}_{_short_id(customer_id)}_{digest}"
+    return f"conv_{merchant_short}_{trigger_short}_{digest}"
+
+
+def _compose_merchant(category: Context, merchant: Context, trigger: Context) -> Context:
+    kind = trigger.get("kind", "generic")
+    cat = merchant.get("category_slug") or category.get("slug", "merchant")
+    identity = merchant.get("identity", {})
+    name = _merchant_name(merchant)
+    first = _owner_or_name(merchant)
+    payload = trigger.get("payload", {})
+    offer = _best_offer(merchant, category)
+    perf = merchant.get("performance", {})
+    agg = merchant.get("customer_aggregate", {})
+    locality = identity.get("locality") or identity.get("city") or "your area"
+
+    if _is_placeholder_payload(payload):
+        return _generic_merchant(category, merchant, trigger)
+
+    if kind in {"research_digest", "regulation_change", "cde_opportunity"}:
+        item = _digest_item(category, payload.get("top_item_id") or payload.get("digest_item_id"))
+        title = item.get("title") or payload.get("metric_or_topic") or "this week's category update"
+        source = item.get("source") or "your category digest"
+        number = _first_fact(item, agg)
+        if kind == "regulation_change":
+            deadline = payload.get("deadline_iso") or trigger.get("expires_at", "")[:10]
+            body = f"{name}, compliance note: {title}. Deadline: {deadline}. {number} Source: {source}. Want me to draft the 5-point SOP/checklist for your clinic?"
+            cta = CTA_YES_NO
+        elif kind == "cde_opportunity":
+            credits = payload.get("credits") or item.get("credits")
+            fee = str(payload.get("fee") or item.get("actionable") or "").replace("_", " ")
+            body = f"{name}, IDA/CDE item for you: {title}. Credits: {credits}; fee: {fee}. Source: {source}. Want me to pull the invite and make a 1-line calendar reminder?"
+            cta = CTA_YES_NO
+        else:
+            cohort = _cohort_phrase(agg)
+            body = f"{name}, {source} has one item relevant to {cohort}: {title}. {number} Want me to pull the 2-min summary and draft a patient WhatsApp?"
+            cta = CTA_OPEN
+        return _msg(body, cta, "vera", trigger, f"{kind} uses digest source plus merchant cohort/performance context.")
+
+    if kind in {"perf_dip", "seasonal_perf_dip"}:
+        if kind == "perf_dip" and not _has_all(payload, "metric", "delta_pct", "window"):
+            return _generic_merchant(category, merchant, trigger)
+        metric = payload.get("metric", "performance")
+        delta = _pct(payload.get("delta_pct") or perf.get("delta_7d", {}).get(f"{metric}_pct"))
+        baseline = payload.get("vs_baseline")
+        seasonal = payload.get("is_expected_seasonal")
+        if seasonal:
+            body = f"{first}, your {metric} is down {delta} this {payload.get('window', 'week')}, but this matches the {payload.get('season_note', 'seasonal dip')} pattern. Do not over-spend ads now; focus on your {_member_count(agg)}. Want me to draft a retention nudge?"
+        else:
+            body = f"{first}, {metric} dropped {delta} in {payload.get('window', '7d')}; baseline was {baseline} and current calls are {perf.get('calls', 'lower than usual')}. {offer} is the quickest concrete hook. Want me to draft a recovery WhatsApp/GBP post?"
+        return _msg(body, CTA_YES_NO, "vera", trigger, "Performance dip trigger; recommends one low-effort recovery action.")
+
+    if kind == "perf_spike":
+        if not _has_all(payload, "metric", "delta_pct", "window"):
+            return _generic_merchant(category, merchant, trigger)
+        metric = payload.get("metric", "calls")
+        delta = _pct(payload.get("delta_pct"))
+        driver = str(payload.get("likely_driver") or "recent profile activity").replace("_", " ")
+        body = f"{first}, {metric} is up {delta} in {payload.get('window', '7d')} vs baseline {payload.get('vs_baseline', 'normal')}. Likely driver: {driver}. Want me to turn this into a repeatable post for this week?"
+        return _msg(body, CTA_YES_NO, "vera", trigger, "Performance spike trigger; converts a winning signal into a repeatable action.")
+
+    if kind in {"active_planning_intent"}:
+        topic = str(payload.get("intent_topic", "growth plan")).replace("_", " ")
+        last = payload.get("merchant_last_message", "")
+        if "thali" in topic:
+            body = f"{first}, based on your '{last}' message, here is a starter corporate thali structure: 10 thalis at the current {offer}, 25+ with free delivery, 50+ with a filter-coffee add-on. Want me to draft the 3-line outreach note?"
+        elif "kids_yoga" in topic:
+            body = f"{first}, for kids yoga summer camp, keep it simple: age 7-12, 4 weeks, 3 sessions/week, Saturday trial, and use your current {offer}. Want me to draft the GBP post plus parent WhatsApp?"
+        else:
+            body = f"{first}, you asked about {topic}. I can turn it into one concrete offer using {offer}, your {locality} locality, and your current profile. Want the ready draft?"
+        return _msg(body, CTA_YES_NO, "vera", trigger, "Merchant already showed planning intent; moves directly to a concrete draft.")
+
+    if kind == "festival_upcoming":
+        if not _has_all(payload, "festival", "days_until"):
+            return _generic_merchant(category, merchant, trigger)
+        festival = payload.get("festival", "festival")
+        days = payload.get("days_until")
+        body = f"{first}, {festival} is {days} days away and {cat} is marked relevant for this beat. Your active hook is {offer}. Want me to prepare a festival post now and hold it for approval?"
+        return _msg(body, CTA_YES_NO, "vera", trigger, "Festival trigger with category relevance and existing offer.")
+
+    if kind == "ipl_match_today":
+        if not _has_all(payload, "match", "venue", "match_time_iso"):
+            return _generic_merchant(category, merchant, trigger)
+        match = payload.get("match", "today's match")
+        venue = payload.get("venue", "the stadium")
+        time = _time_from_iso(payload.get("match_time_iso")) or "tonight"
+        weeknight = payload.get("is_weeknight")
+        advice = "push a delivery-only offer" if not weeknight else "run a quick pre-match dine-in/post"
+        body = f"{first}, {match} at {venue} starts {time}. Since this is {'not ' if not weeknight else ''}a weeknight match, {advice} using your active {offer}. Want me to draft the banner text and Insta story?"
+        return _msg(body, CTA_YES_NO, "vera", trigger, "IPL trigger interpreted with day context and current restaurant offer.")
+
+    if kind == "review_theme_emerged":
+        if not _has_all(payload, "theme", "occurrences_30d"):
+            return _generic_merchant(category, merchant, trigger)
+        theme = str(payload.get("theme", "review theme")).replace("_", " ")
+        count = payload.get("occurrences_30d")
+        quote = payload.get("common_quote")
+        body = f"{first}, {count} reviews in 30d now mention {theme}; one customer said '{quote}'. Want me to draft a short public reply pattern plus an ops checklist?"
+        return _msg(body, CTA_YES_NO, "vera", trigger, "Review theme trigger turns repeated feedback into reply and ops action.")
+
+    if kind == "milestone_reached":
+        if not _has_all(payload, "metric", "value_now", "milestone_value"):
+            return _generic_merchant(category, merchant, trigger)
+        value = payload.get("value_now")
+        target = payload.get("milestone_value")
+        metric = str(payload.get("metric", "milestone")).replace("_", " ")
+        body = f"{first}, you are at {value} {metric}; {target} is close. Want me to draft a polite review-request WhatsApp for recent happy customers?"
+        return _msg(body, CTA_YES_NO, "vera", trigger, "Milestone trigger nudges a review/request action tied to current count.")
+
+    if kind == "renewal_due":
+        if not _has_any(payload, "days_remaining", "renewal_amount") and not merchant.get("subscription", {}).get("days_remaining"):
+            return _generic_merchant(category, merchant, trigger)
+        days = payload.get("days_remaining") or merchant.get("subscription", {}).get("days_remaining")
+        amount = payload.get("renewal_amount")
+        body = f"{first}, your {payload.get('plan', 'plan')} renewal is due in {days} days for Rs {amount}. Calls are down {_pct(merchant.get('performance', {}).get('delta_7d', {}).get('calls_pct'))}; before renewal, want me to show the 3 fixes likely to recover calls?"
+        return _msg(body, CTA_YES_NO, "vera", trigger, "Renewal trigger pairs deadline with current performance risk.")
+
+    if kind in {"winback_eligible", "dormant_with_vera"}:
+        if not _has_any(payload, "days_since_expiry", "days_since_last_merchant_message", "lapsed_customers_added_since_expiry"):
+            return _generic_merchant(category, merchant, trigger)
+        days = payload.get("days_since_expiry") or payload.get("days_since_last_merchant_message") or merchant.get("subscription", {}).get("days_since_expiry")
+        lapsed = payload.get("lapsed_customers_added_since_expiry") or agg.get("lapsed_90d_plus") or agg.get("lapsed_180d_plus")
+        body = f"{first}, it has been {days} days since the last active Vera/subscription moment. You now have {lapsed} lapsed customers/signals to recover. Want me to draft one winback message using {offer}?"
+        return _msg(body, CTA_YES_NO, "vera", trigger, "Dormancy/winback trigger; restarts with one concrete recovery action.")
+
+    if kind == "supply_alert":
+        if not _has_all(payload, "molecule", "affected_batches"):
+            return _generic_merchant(category, merchant, trigger)
+        batches = ", ".join(payload.get("affected_batches", [])[:3])
+        molecule = payload.get("molecule", "medicine")
+        chronic = agg.get("chronic_rx_count") or agg.get("total_unique_ytd") or "repeat"
+        body = f"{first}, urgent stock alert: {molecule} batches {batches} from {payload.get('manufacturer', 'the manufacturer')}. You have {chronic} chronic-Rx customers in context. Want me to draft the replacement WhatsApp and counter checklist?"
+        return _msg(body, CTA_YES_NO, "vera", trigger, "Supply alert trigger uses molecule, batch numbers, and pharmacy repeat-customer context.")
+
+    if kind == "category_seasonal":
+        if not payload.get("trends"):
+            return _generic_merchant(category, merchant, trigger)
+        trends = ", ".join(str(t).replace("_", " ") for t in payload.get("trends", [])[:4])
+        body = f"{first}, summer demand shift is visible: {trends}. Since shelf action is recommended, want me to draft a 10-item reorder/checklist plus WhatsApp note?"
+        return _msg(body, CTA_YES_NO, "vera", trigger, "Seasonal pharmacy/category trigger maps trends to stock action.")
+
+    if kind == "gbp_unverified":
+        if not _has_all(payload, "verification_path", "estimated_uplift_pct"):
+            return _generic_merchant(category, merchant, trigger)
+        uplift = _pct(payload.get("estimated_uplift_pct"))
+        body = f"{first}, your GBP is still unverified; the available path is {payload.get('verification_path', 'verification')}. Verified profiles can unlock about {uplift} more visibility in this context. Want me to walk you through the 3-step verification?"
+        return _msg(body, CTA_YES_NO, "vera", trigger, "GBP verification trigger uses exact path and estimated uplift.")
+
+    if kind == "competitor_opened":
+        if not _has_all(payload, "competitor_name", "distance_km", "opened_date", "their_offer"):
+            return _generic_merchant(category, merchant, trigger)
+        body = f"{name}, new competitor signal: {payload.get('competitor_name')} opened {payload.get('distance_km')} km away on {payload.get('opened_date')} with {payload.get('their_offer')}. Your current hook is {offer}. Want me to draft a sharper local post?"
+        return _msg(body, CTA_YES_NO, "vera", trigger, "Competitor trigger uses named competitor, distance, date, and offer comparison.")
+
+    if kind == "curious_ask_due":
+        body = f"{first}, quick check: what service has been most asked-for this week at {identity.get('name', 'your business')}? I will turn your answer into a Google post and a 4-line WhatsApp reply. Takes 5 min."
+        return _msg(body, CTA_OPEN, "vera", trigger, "Curious-ask cadence asks the merchant for one useful signal.")
+
+    return _generic_merchant(category, merchant, trigger)
+
+
+def _compose_customer(category: Context, merchant: Context, trigger: Context, customer: Context) -> Context:
+    if not _has_consent(customer, trigger):
+        return _msg(
+            f"{_owner_or_name(merchant)}, {_customer_name(customer)} has a {str(trigger.get('kind', 'customer')).replace('_', ' ')} signal, but the saved opt-in scope does not clearly cover this outreach. Want me to prepare a consent-safe approval note first?",
+            CTA_YES_NO,
+            "vera",
+            trigger,
+            "Customer trigger routed to merchant because consent/preference does not clearly permit direct outreach.",
+        )
+
+    kind = trigger.get("kind", "customer_message")
+    payload = trigger.get("payload", {})
+    merchant_name = merchant.get("identity", {}).get("name", "your merchant")
+    owner = merchant.get("identity", {}).get("owner_first_name") or merchant_name
+    customer_name = _customer_name(customer)
+    offer = _best_offer(merchant, category)
+    lang = str(customer.get("identity", {}).get("language_pref", "english")).lower()
+
+    if _is_placeholder_payload(payload):
+        return _generic_customer(category, merchant, trigger, customer)
+
+    if kind == "recall_due":
+        if not _has_any(payload, "service_due", "due_date", "available_slots"):
+            return _generic_customer(category, merchant, trigger, customer)
+        slots = payload.get("available_slots", [])
+        slot_text = _slot_text(slots)
+        months = _months_between(payload.get("last_service_date"), payload.get("due_date")) or "6-month"
+        if "hi" in lang:
+            body = f"Hi {customer_name}, {merchant_name} here. It has been about {months} since your last visit; your {payload.get('service_due', 'recall').replace('_', ' ')} is due. Apke liye slots: {slot_text}. {offer}. Reply 1/2 for a slot, or suggest a time."
+        else:
+            body = f"Hi {customer_name}, {merchant_name} here. It has been about {months} since your last visit; your {payload.get('service_due', 'recall').replace('_', ' ')} is due. Slots available: {slot_text}. {offer}. Reply 1/2 for a slot, or suggest a time."
+        return _msg(body, CTA_SLOTS, "merchant_on_behalf", trigger, "Customer recall uses due date, slot options, offer, and language preference.")
+
+    if kind in {"customer_lapsed_hard", "customer_lapsed_soft"}:
+        days = payload.get("days_since_last_visit")
+        focus = str(payload.get("previous_focus") or customer.get("preferences", {}).get("training_focus") or "your goal").replace("_", " ")
+        elapsed = f"{days} days" if days is not None else "a while"
+        body = f"Hi {customer_name}, {owner} from {merchant_name} here. It has been {elapsed} since your last visit; no pressure. We can restart with {offer}, matched to {focus}. Reply YES and I will hold a no-commitment slot."
+        return _msg(body, CTA_YES_NO, "merchant_on_behalf", trigger, "Customer lapse trigger uses days since visit, prior focus, and merchant offer.")
+
+    if kind == "appointment_tomorrow":
+        appointment = payload.get("appointment_time") or payload.get("slot_label") or _slot_text(payload.get("available_slots", []))
+        service = str(payload.get("service") or customer.get("relationship", {}).get("services_received", ["appointment"])[-1]).replace("_", " ")
+        body = f"Hi {customer_name}, {merchant_name} here. Reminder for your {service} appointment tomorrow: {appointment}. Reply YES to confirm or tell us if you need to reschedule."
+        return _msg(body, CTA_CONFIRM, "merchant_on_behalf", trigger, "Appointment reminder uses customer relationship and available appointment timing.")
+
+    if kind == "wedding_package_followup":
+        if not _has_any(payload, "wedding_date", "days_to_wedding", "next_step_window_open"):
+            return _generic_customer(category, merchant, trigger, customer)
+        days = payload.get("days_to_wedding")
+        body = f"Hi {customer_name}, {owner} from {merchant_name} here. {days} days to your wedding; this is the right window for {str(payload.get('next_step_window_open', 'skin prep')).replace('_', ' ')}. {offer}. Want me to block your preferred Saturday slot?"
+        return _msg(body, CTA_YES_NO, "merchant_on_behalf", trigger, "Bridal follow-up uses wedding date window, relationship history, and offer.")
+
+    if kind == "trial_followup":
+        if not _has_any(payload, "trial_date", "next_session_options"):
+            return _generic_customer(category, merchant, trigger, customer)
+        slots = _slot_text(payload.get("next_session_options", []))
+        body = f"Hi {customer_name}, {owner} from {merchant_name} here. Thanks for trying the class on {payload.get('trial_date')}. Next available option: {slots}. Want me to reserve it?"
+        return _msg(body, CTA_YES_NO, "merchant_on_behalf", trigger, "Trial follow-up uses trial date and next available session.")
+
+    if kind == "chronic_refill_due":
+        if not _has_any(payload, "molecule_list", "stock_runs_out_iso"):
+            return _generic_customer(category, merchant, trigger, customer)
+        meds = ", ".join(payload.get("molecule_list", []))
+        saved = "saved address" if payload.get("delivery_address_saved") else "your preferred address"
+        body = f"Namaste {customer_name}, {merchant_name} here. Your monthly medicines ({meds}) are due by {_date_from_iso(payload.get('stock_runs_out_iso'))}. {offer}; delivery can go to the {saved}. Reply CONFIRM to dispatch, or tell us if dosage changed."
+        return _msg(body, CTA_CONFIRM, "merchant_on_behalf", trigger, "Refill reminder uses molecule list, run-out date, delivery status, and pharmacy offer.")
+
+    return _msg(
+        f"Hi {customer_name}, {merchant_name} here. A quick update related to your last visit is ready. {offer}. Reply YES if you want the details.",
+        CTA_YES_NO,
+        "merchant_on_behalf",
+        trigger,
+        "Generic customer-scoped trigger with consent and merchant offer.",
+    )
+
+
+def _generic_merchant(category: Context, merchant: Context, trigger: Context) -> Context:
+    first = _owner_or_name(merchant)
+    kind = str(trigger.get("kind", "update")).replace("_", " ")
+    perf = merchant.get("performance", {})
+    offer = _best_offer(merchant, category)
+    views = perf.get("views")
+    calls = perf.get("calls")
+    identity = merchant.get("identity", {})
+    locality = identity.get("locality") or identity.get("city") or "your locality"
+    fact = f"Current 30d views: {views}; calls: {calls}." if views is not None and calls is not None else f"Locality: {locality}."
+    body = f"{first}, Vera found a {kind} signal for {_merchant_name(merchant)}. {fact} Best hook: {offer}. Want me to draft the next WhatsApp/GBP action?"
+    return _msg(body, CTA_YES_NO, "vera", trigger, "Fallback grounded in trigger kind, performance, and offer.")
+
+
+def _generic_customer(category: Context, merchant: Context, trigger: Context, customer: Context) -> Context:
+    customer_name = _customer_name(customer)
+    merchant_name = merchant.get("identity", {}).get("name", "your merchant")
+    kind = str(trigger.get("kind", "customer update")).replace("_", " ")
+    last_visit = customer.get("relationship", {}).get("last_visit")
+    state = str(customer.get("state", "active")).replace("_", " ")
+    offer = _best_offer(merchant, category)
+    visit_text = f" Last visit: {last_visit}." if last_visit else ""
+    body = f"Hi {customer_name}, {merchant_name} here. Quick {kind} update for you based on your {state} status.{visit_text} {offer}. Reply YES if you want me to hold the next step."
+    return _msg(body, CTA_YES_NO, "merchant_on_behalf", trigger, "Customer fallback grounded in relationship state, last visit, and available offer.")
+
+
+def _msg(body: str, cta: str, send_as: str, trigger: Context, rationale: str) -> Context:
+    return validate_message({
+        "body": body,
+        "cta": cta,
+        "send_as": send_as,
+        "suppression_key": trigger.get("suppression_key", trigger.get("id", "")),
+        "rationale": rationale,
+    })
+
+
+def _clean(text: str) -> str:
+    return re.sub(r"\s+", " ", text).strip()
+
+
+def _merchant_name(merchant: Context) -> str:
+    identity = merchant.get("identity", {})
+    name = identity.get("name") or "Merchant"
+    owner = str(identity.get("owner_first_name") or "").strip()
+    if merchant.get("category_slug") == "dentists" and owner and not str(name).lower().startswith("dr."):
+        return owner if owner.lower().startswith("dr") else f"Dr. {owner}"
+    return _dedupe_dr(str(name))
+
+
+def _owner_or_name(merchant: Context) -> str:
+    identity = merchant.get("identity", {})
+    owner = identity.get("owner_first_name")
+    if owner:
+        if merchant.get("category_slug") == "dentists" and not str(owner).lower().startswith("dr"):
+            return f"Dr. {owner}"
+        return str(owner)
+    return str(identity.get("name", "there"))
+
+
+def _customer_name(customer: Context) -> str:
+    name = str(customer.get("identity", {}).get("name") or "there")
+    return name.replace("(parent:", "parent:").strip()
+
+
+def _best_offer(merchant: Context, category: Context) -> str:
+    for offer in merchant.get("offers", []) or []:
+        if offer.get("status") == "active" and offer.get("title"):
+            return str(offer["title"])
+    catalog = [offer for offer in (category.get("offer_catalog", []) or []) if offer.get("title")]
+    preferred_types = {"service_at_price": 0, "free_service": 1, "membership": 2}
+    def rank(offer: Context) -> tuple[int, int]:
+        title = str(offer.get("title", "")).lower()
+        percent_penalty = 5 if "flat" in title and "%" in title else 0
+        return (preferred_types.get(str(offer.get("type")), 3) + percent_penalty, len(title))
+    for offer in sorted(catalog, key=rank):
+        title = str(offer["title"])
+        if not ("flat" in title.lower() and "%" in title):
+            return title
+    if catalog:
+        return str(sorted(catalog, key=rank)[0]["title"])
+    return "a simple service-price offer"
+
+
+def _digest_item(category: Context, item_id: str | None) -> Context:
+    digest = category.get("digest", []) or []
+    if item_id:
+        for item in digest:
+            if item.get("id") == item_id:
+                return item
+    return digest[0] if digest else {}
+
+
+def _first_fact(item: Context, agg: Context) -> str:
+    facts: list[str] = []
+    if item.get("trial_n"):
+        facts.append(f"{item['trial_n']}-patient trial")
+    if item.get("summary"):
+        match = re.search(r"(\d+(?:\.\d+)?%|\d+(?:\.\d+)?\s?mSv|\d+(?:\.\d+)?\s?credits?)", str(item["summary"]))
+        if match:
+            facts.append(match.group(1))
+    if agg.get("high_risk_adult_count"):
+        facts.append(f"{agg['high_risk_adult_count']} high-risk adults in your roster")
+    return "; ".join(facts) + "." if facts else ""
+
+
+def _cohort_phrase(agg: Context) -> str:
+    if agg.get("high_risk_adult_count"):
+        return f"your {agg['high_risk_adult_count']} high-risk adult patients"
+    if agg.get("chronic_rx_count"):
+        return f"your {agg['chronic_rx_count']} chronic-Rx customers"
+    if agg.get("total_active_members"):
+        return f"your {agg['total_active_members']} active members"
+    if agg.get("lapsed_90d_plus") or agg.get("lapsed_180d_plus"):
+        return "your lapsed-customer cohort"
+    return "your current customers"
+
+
+def _member_count(agg: Context) -> str:
+    if agg.get("total_active_members"):
+        return f"{agg['total_active_members']} active members"
+    if agg.get("total_unique_ytd"):
+        return f"{agg['total_unique_ytd']} customers"
+    return "existing customers"
+
+
+def _pct(value: Any) -> str:
+    try:
+        num = float(value)
+    except (TypeError, ValueError):
+        return "0%"
+    return f"{num * 100:.0f}%" if abs(num) <= 1 else f"{num:.0f}%"
+
+
+def _time_from_iso(value: str | None) -> str | None:
+    if not value:
+        return None
+    match = re.search(r"T(\d{2}):(\d{2})", value)
+    if not match:
+        return value
+    hour = int(match.group(1))
+    minute = match.group(2)
+    suffix = "am" if hour < 12 else "pm"
+    hour = hour if 1 <= hour <= 12 else abs(hour - 12) or 12
+    return f"{hour}:{minute}{suffix}"
+
+
+def _date_from_iso(value: str | None) -> str:
+    if not value:
+        return "the due date"
+    return value.split("T", 1)[0]
+
+
+def _months_between(start: str | None, end: str | None) -> str | None:
+    if not start or not end:
+        return None
+    try:
+        a = datetime.fromisoformat(start[:10])
+        b = datetime.fromisoformat(end[:10])
+    except ValueError:
+        return None
+    months = max(1, round((b - a).days / 30))
+    return f"{months} months"
+
+
+def _slot_text(slots: list[Context]) -> str:
+    labels = [str(s.get("label")) for s in slots if s.get("label")]
+    if not labels:
+        return "the next available slot"
+    if len(labels) == 1:
+        return labels[0]
+    return " or ".join(labels[:2])
+
+
+def _has_consent(customer: Context, trigger: Context) -> bool:
+    prefs = customer.get("preferences", {})
+    if prefs.get("reminder_opt_in") is False:
+        return False
+    scopes = set(customer.get("consent", {}).get("scope", []) or [])
+    kind = trigger.get("kind", "")
+    if kind in {"recall_due", "appointment_tomorrow"}:
+        return bool(scopes.intersection({"recall_reminders", "appointment_reminders"}))
+    if kind in {"chronic_refill_due"}:
+        return bool(scopes.intersection({"refill_reminders", "delivery_notifications"}))
+    if kind in {"customer_lapsed_hard", "customer_lapsed_soft"}:
+        return bool(scopes.intersection({"winback_offers", "renewal_reminders", "promotional_offers"}))
+    if kind in {"wedding_package_followup"}:
+        return "bridal_package_followup" in scopes
+    if kind in {"trial_followup"}:
+        return bool(scopes.intersection({"kids_program_updates", "program_updates", "appointment_reminders"}))
+    return bool(scopes)
+
+
+def _has_all(payload: Context, *fields: str) -> bool:
+    return all(payload.get(field) not in (None, "", []) for field in fields)
+
+
+def _has_any(payload: Context, *fields: str) -> bool:
+    return any(payload.get(field) not in (None, "", []) for field in fields)
+
+
+def _is_placeholder_payload(payload: Context) -> bool:
+    return payload.get("placeholder") is True
+
+
+def _dedupe_dr(value: str) -> str:
+    return re.sub(r"\bDr\.\s+Dr\.\s+", "Dr. ", value).strip()
+
+
+def _final_scrub(body: str) -> str:
+    body = _dedupe_dr(body)
+    body = body.replace("None", "the available context")
+    body = body.replace("baseline normal", "the recent baseline")
+    body = re.sub(r"\b(up|down|dropped|rose|increased)\s+0%\b", "changed in the latest context", body)
+    body = body.replace("the available context days", "a while")
+    body = body.replace("the available context km", "nearby")
+    body = body.replace("festival is the available context days away", "a festival window is coming up")
+    return _clean(body)
+
+
+def _short_id(value: str) -> str:
+    cleaned = re.sub(r"[^a-zA-Z0-9]+", "_", value).strip("_")
+    parts = cleaned.split("_")
+    return "_".join(parts[:4])[:36] or "x"
+
+
+def _action_scope(merchant: Context, trigger: Context) -> str:
+    name = merchant.get("identity", {}).get("name") or "this merchant"
+    kind = str(trigger.get("kind", "task")).replace("_", " ")
+    return f"{name}'s {kind}"

app/decision_engine.py

@@ -0,0 +1,1372 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import json
+import os
+import re
+from typing import Any
+from urllib import request as urlrequest
+
+
+Context = dict[str, Any]
+
+CTA_NONE = "none"
+CTA_OPEN = "open_ended"
+CTA_YES_NO = "binary_yes_no"
+CTA_CONFIRM = "binary_confirm_cancel"
+CTA_SLOTS = "multi_choice_slot"
+
+
+@dataclass(frozen=True)
+class Evidence:
+    label: str
+    value: str
+    kind: str
+    source: str
+    weight: int = 1
+
+
+@dataclass(frozen=True)
+class MerchantCAR:
+    merchant_id: str
+    merchant_name: str
+    owner: str
+    category: str
+    locality: str
+    active_offers: list[str]
+    views_30d: int
+    calls_30d: int
+    ctr: str
+    performance_deltas: dict[str, str]
+    trigger_kind: str
+    trigger_urgency: int
+    trigger_facts: dict[str, str]
+    customer_id: str
+    customer_stage: str
+    consent_state: str
+    last_action_type: str
+    last_response_intent: str
+    repeated_action_count: int
+    no_reply_count: int
+    action_sequence: list[str]
+    response_sequence: list[str]
+    reflection_note: str
+    category_arm_priors: dict[str, str]
+
+    def summary(self) -> dict[str, Any]:
+        return {
+            "merchant_id": self.merchant_id,
+            "category": self.category,
+            "locality": self.locality,
+            "active_offers": self.active_offers[:3],
+            "performance_deltas": self.performance_deltas,
+            "trigger_kind": self.trigger_kind,
+            "trigger_urgency": self.trigger_urgency,
+            "customer_stage": self.customer_stage,
+            "consent_state": self.consent_state,
+            "last_action_type": self.last_action_type,
+            "last_response_intent": self.last_response_intent,
+            "reflection_note": self.reflection_note,
+            "category_arm_priors": self.category_arm_priors,
+        }
+
+
+@dataclass
+class DecisionPlan:
+    primary_signal: str
+    evidence: list[Evidence]
+    selected_lever: str
+    recommended_action: str
+    risk_flags: list[str]
+    rubric_scores: dict[str, int]
+    copy_strategy: str
+    body: str
+    cta: str
+    send_as: str
+    suppression_key: str
+    rationale: str
+    car_summary: dict[str, Any] = field(default_factory=dict)
+    jitai_scores: dict[str, int] = field(default_factory=dict)
+    map_scores: dict[str, int] = field(default_factory=dict)
+    frame: str = "effort_externalization"
+    action_arm: str = "draft_action"
+    variant_strategy: str = "primary"
+    persuasion_principle: str = "liking"
+    constitutional_violations: list[str] = field(default_factory=list)
+    thought_frames: list[dict[str, Any]] = field(default_factory=list)
+    reference_key: str = "default"
+
+    @property
+    def total_score(self) -> int:
+        map_bonus = int(sum(self.map_scores.values()) / 12) if self.map_scores else 0
+        jitai_bonus = int(sum(self.jitai_scores.values()) / 15) if self.jitai_scores else 0
+        constitution_penalty = len(self.constitutional_violations) * 2
+        return sum(self.rubric_scores.values()) + map_bonus + jitai_bonus - constitution_penalty
+
+
+CATEGORY_PLAYBOOKS: dict[str, dict[str, Any]] = {
+    "dentists": {
+        "voice": "clinical-peer",
+        "terms": ["recall", "caries", "fluoride", "IOPA", "CDE", "patient cohort"],
+        "avoid": ["guaranteed", "miracle", "best in city"],
+        "action": "draft the patient note or checklist",
+    },
+    "salons": {
+        "voice": "warm-practical",
+        "terms": ["slot", "package", "trial", "stylist", "bridal", "service"],
+        "avoid": ["clinical claims", "hard urgency without event"],
+        "action": "draft the WhatsApp/post and hold a slot",
+    },
+    "restaurants": {
+        "voice": "operator-to-operator",
+        "terms": ["orders", "covers", "delivery", "banner", "weekday", "rush"],
+        "avoid": ["generic discount blast"],
+        "action": "draft the banner/menu note",
+    },
+    "gyms": {
+        "voice": "coach-to-operator",
+        "terms": ["trial", "members", "retention", "class", "challenge", "no commitment"],
+        "avoid": ["shame", "body-negative wording"],
+        "action": "draft the class/challenge message",
+    },
+    "pharmacies": {
+        "voice": "precise-safe",
+        "terms": ["refill", "batch", "delivery", "stock", "compliance", "repeat customers"],
+        "avoid": ["panic", "medical diagnosis"],
+        "action": "draft the customer note and counter checklist",
+    },
+}
+
+
+LEVER_BY_KIND = {
+    "research_digest": "curiosity + source credibility",
+    "regulation_change": "urgency + compliance risk",
+    "cde_opportunity": "professional value + low effort",
+    "perf_dip": "loss aversion + recovery action",
+    "seasonal_perf_dip": "anxiety pre-emption + reframe",
+    "perf_spike": "amplify what is working",
+    "active_planning_intent": "effort externalization",
+    "festival_upcoming": "timing urgency",
+    "ipl_match_today": "timely local event + judgment",
+    "review_theme_emerged": "reputation risk + ops action",
+    "milestone_reached": "near-miss motivation",
+    "renewal_due": "deadline + ROI proof",
+    "winback_eligible": "lost customers + easy restart",
+    "dormant_with_vera": "curiosity + recovery",
+    "supply_alert": "urgent precision",
+    "category_seasonal": "timely stock/action planning",
+    "gbp_unverified": "visibility loss aversion",
+    "competitor_opened": "competitive threat",
+    "curious_ask_due": "asking the merchant",
+    "recall_due": "specific appointment/recall",
+    "appointment_tomorrow": "reminder + friction removal",
+    "customer_lapsed_hard": "no-shame winback",
+    "customer_lapsed_soft": "no-shame winback",
+    "wedding_package_followup": "occasion timing",
+    "trial_followup": "fresh intent follow-up",
+    "chronic_refill_due": "necessity + convenience",
+}
+
+
+def compose_scored(category: Context, merchant: Context, trigger: Context, customer: Context | None = None) -> Context | None:
+    """Return a high-score composed message, or None to let the legacy composer handle it."""
+    car = build_merchant_car(category, merchant, trigger, customer)
+    evidence = extract_evidence(category, merchant, trigger, customer, car)
+    candidates = build_candidates(category, merchant, trigger, customer, evidence, car)
+    if not candidates:
+        return None
+    best = max(candidates, key=lambda plan: (plan.total_score, sum(plan.map_scores.values()), len(plan.evidence)))
+    if best.total_score < 32 and not customer:
+        return None
+    output = plan_to_message(best)
+    improved = improve_with_llm_if_available(category, merchant, trigger, customer, best, output)
+    return improved or output
+
+
+def expected_trigger_score(category: Context | None, merchant: Context | None, trigger: Context, customer: Context | None = None) -> int:
+    if not category or not merchant:
+        return 0
+    car = build_merchant_car(category, merchant, trigger, customer)
+    evidence = extract_evidence(category, merchant, trigger, customer, car)
+    candidates = build_candidates(category, merchant, trigger, customer, evidence, car)
+    if not candidates:
+        return 0
+    return max(c.total_score for c in candidates)
+
+
+def build_merchant_car(category: Context, merchant: Context, trigger: Context, customer: Context | None = None) -> MerchantCAR:
+    """Flatten nested context into one typed record for stable decisioning."""
+    identity = merchant.get("identity", {}) or {}
+    perf = merchant.get("performance", {}) or {}
+    payload = trigger.get("payload", {}) or {}
+    memory = merchant.get("__vera_memory", {}) or {}
+    active_offers = [
+        clean(str(offer.get("title") or ""))
+        for offer in merchant.get("offers", []) or []
+        if offer.get("status") == "active" and offer.get("title")
+    ]
+    if not active_offers:
+        active_offers = [
+            clean(str(offer.get("title") or ""))
+            for offer in category.get("offer_catalog", []) or []
+            if offer.get("title")
+        ][:3]
+    trigger_facts = {
+        clean(str(k)): normalize_car_value(v)
+        for k, v in payload.items()
+        if k != "placeholder" and v not in (None, "", [], {})
+    }
+    deltas = {
+        clean(str(k)): normalize_car_value(v)
+        for k, v in (perf.get("delta_7d") or {}).items()
+        if v not in (None, "", [], {})
+    }
+    customer_id = ""
+    customer_stage = "merchant_only"
+    consent_state = "not_applicable"
+    if customer:
+        customer_id = clean(str(customer.get("customer_id") or customer.get("id") or ""))
+        customer_stage = clean(str(customer.get("state") or "unknown"))
+        consent_state = "allowed" if has_consent(customer, trigger) else "missing_or_blocked"
+    action_sequence = [clean(str(v)) for v in memory.get("action_sequence", []) if v][:5]
+    response_sequence = [clean(str(v)) for v in memory.get("response_sequence", []) if v][:5]
+    priors = {
+        clean(str(k)): normalize_car_value(v)
+        for k, v in (memory.get("category_arm_priors") or {}).items()
+        if k and v not in (None, "", [], {})
+    }
+    return MerchantCAR(
+        merchant_id=clean(str(merchant.get("merchant_id") or merchant.get("id") or "")),
+        merchant_name=clean(str(identity.get("name") or "unknown")),
+        owner=clean(str(identity.get("owner_first_name") or "")),
+        category=clean(str(merchant.get("category_slug") or category.get("slug") or "unknown")),
+        locality=clean(str(identity.get("locality") or identity.get("city") or "unknown")),
+        active_offers=[offer for offer in active_offers if offer][:5],
+        views_30d=safe_int(perf.get("views")),
+        calls_30d=safe_int(perf.get("calls")),
+        ctr=normalize_car_value(perf.get("ctr")),
+        performance_deltas=deltas,
+        trigger_kind=clean(str(trigger.get("kind") or "generic")),
+        trigger_urgency=safe_int(trigger.get("urgency"), default=1),
+        trigger_facts=trigger_facts,
+        customer_id=customer_id,
+        customer_stage=customer_stage,
+        consent_state=consent_state,
+        last_action_type=clean(str(memory.get("last_action_type") or "")),
+        last_response_intent=clean(str(memory.get("last_response_intent") or "")),
+        repeated_action_count=safe_int(memory.get("repeated_action_count")),
+        no_reply_count=safe_int(memory.get("no_reply_count")),
+        action_sequence=action_sequence,
+        response_sequence=response_sequence,
+        reflection_note=clean(str(memory.get("reflection_note") or "")),
+        category_arm_priors=priors,
+    )
+
+
+def normalize_car_value(value: Any) -> str:
+    if value in (None, "", [], {}):
+        return "unknown"
+    if isinstance(value, float):
+        return pct(value) if abs(value) <= 1 else f"{value:g}"
+    if isinstance(value, list):
+        values: list[str] = []
+        for item in value[:4]:
+            if isinstance(item, dict):
+                values.append(str(item.get("label") or item.get("iso") or item.get("name") or item))
+            else:
+                values.append(str(item))
+        return clean(", ".join(values)) or "unknown"
+    if isinstance(value, dict):
+        return clean(", ".join(f"{k}:{normalize_car_value(v)}" for k, v in list(value.items())[:4])) or "unknown"
+    return clean(str(value).replace("_", " ")) or "unknown"
+
+
+def safe_int(value: Any, default: int = 0) -> int:
+    try:
+        return int(float(value))
+    except (TypeError, ValueError):
+        return default
+
+
+def extract_evidence(category: Context, merchant: Context, trigger: Context, customer: Context | None = None, car: MerchantCAR | None = None) -> list[Evidence]:
+    car = car or build_merchant_car(category, merchant, trigger, customer)
+    evidence: list[Evidence] = []
+    identity = merchant.get("identity", {})
+    perf = merchant.get("performance", {})
+    agg = merchant.get("customer_aggregate", {})
+    payload = trigger.get("payload", {}) or {}
+
+    def add(label: str, value: Any, kind: str, source: str, weight: int = 1) -> None:
+        if value in (None, "", [], {}):
+            return
+        if isinstance(value, float):
+            value = pct(value) if abs(value) <= 1 else f"{value:g}"
+        elif isinstance(value, list):
+            if label in {"available_slots", "next_session_options"}:
+                value = " or ".join(str(v.get("label") or v.get("iso")) for v in value[:3] if isinstance(v, dict))
+            else:
+                value = ", ".join(str(v) for v in value[:4])
+        value_s = clean(str(value).replace("_", " "))
+        if value_s and value_s.lower() not in {"none", "normal"}:
+            evidence.append(Evidence(label, value_s, kind, source, weight))
+
+    add("merchant", identity.get("name"), "identity", "merchant.identity", 2)
+    add("owner", identity.get("owner_first_name"), "identity", "merchant.identity", 1)
+    add("locality", identity.get("locality") or identity.get("city"), "local", "merchant.identity", 1)
+    add("car_locality", car.locality, "local", "merchant.car", 2)
+    add("car_customer_stage", car.customer_stage, "customer", "merchant.car", 2)
+    add("car_consent_state", car.consent_state, "consent", "merchant.car", 2)
+    add("car_last_response", car.last_response_intent, "history", "merchant.car", 2)
+    add("views_30d", perf.get("views"), "number", "merchant.performance", 2)
+    add("calls_30d", perf.get("calls"), "number", "merchant.performance", 2)
+    add("ctr", perf.get("ctr"), "number", "merchant.performance", 2)
+    for key, value in (perf.get("delta_7d") or {}).items():
+        add(f"{key}_7d", value, "number", "merchant.performance.delta_7d", 2)
+
+    for offer in merchant.get("offers", []) or []:
+        if offer.get("status") == "active":
+            add("active_offer", offer.get("title"), "offer", "merchant.offers", 4)
+    for offer in category.get("offer_catalog", []) or []:
+        title = offer.get("title")
+        if title and "flat" not in str(title).lower():
+            add("category_offer", title, "offer", "category.offer_catalog", 2)
+            break
+
+    for key, value in agg.items():
+        weight = 5 if any(tok in key for tok in ["risk", "chronic", "active_members"]) else 4 if any(tok in key for tok in ["count", "active", "lapsed"]) else 2
+        add(key, value, "number", "merchant.customer_aggregate", weight)
+
+    for signal in merchant.get("signals", []) or []:
+        add("signal", signal, "signal", "merchant.signals", 2)
+    for hist in merchant.get("conversation_history", [])[-2:]:
+        add("history", hist.get("engagement") or hist.get("body"), "history", "merchant.conversation_history", 2)
+
+    for key, value in payload.items():
+        if key == "placeholder":
+            continue
+        kind = "date" if "date" in key or "iso" in key or "expires" in key else "trigger"
+        weight = 5 if key in {"top_item_id", "digest_item_id", "metric", "delta_pct", "available_slots", "affected_batches", "molecule_list"} else 3
+        add(key, value, kind, "trigger.payload", weight)
+    for key, value in car.trigger_facts.items():
+        add(f"car_{key}", value, "trigger", "merchant.car.trigger_facts", 3)
+
+    digest_id = payload.get("top_item_id") or payload.get("digest_item_id") or payload.get("alert_id")
+    if digest_id:
+        for item in category.get("digest", []) or []:
+            if item.get("id") != digest_id:
+                continue
+            add("digest_title", item.get("title"), "source", "category.digest", 5)
+            add("digest_source", item.get("source"), "source", "category.digest", 4)
+            add("trial_n", item.get("trial_n"), "number", "category.digest", 3)
+            add("digest_summary_fact", first_numeric_fact(item.get("summary")), "number", "category.digest", 3)
+            break
+
+    peer = category.get("peer_stats", {}) or {}
+    add("peer_ctr", peer.get("avg_ctr"), "peer", "category.peer_stats", 2)
+    add("peer_reviews", peer.get("avg_review_count"), "peer", "category.peer_stats", 2)
+
+    if customer:
+        c_identity = customer.get("identity", {})
+        relation = customer.get("relationship", {})
+        prefs = customer.get("preferences", {})
+        add("customer", c_identity.get("name"), "customer", "customer.identity", 3)
+        add("language_pref", c_identity.get("language_pref"), "customer", "customer.identity", 2)
+        add("customer_state", customer.get("state"), "customer", "customer.state", 3)
+        add("last_visit", relation.get("last_visit"), "date", "customer.relationship", 2)
+        add("visits_total", relation.get("visits_total"), "number", "customer.relationship", 2)
+        add("services", relation.get("services_received"), "customer", "customer.relationship", 2)
+        add("preferred_slots", prefs.get("preferred_slots"), "customer", "customer.preferences", 2)
+        add("channel", prefs.get("channel"), "customer", "customer.preferences", 1)
+
+    return dedupe_evidence(evidence)
+
+
+def build_candidates(category: Context, merchant: Context, trigger: Context, customer: Context | None, evidence: list[Evidence], car: MerchantCAR | None = None) -> list[DecisionPlan]:
+    car = car or build_merchant_car(category, merchant, trigger, customer)
+    kind = trigger.get("kind", "generic")
+    if trigger.get("payload", {}).get("placeholder") and len(evidence) < 5:
+        kind = "generic"
+    if not customer and is_sparse_context(car, evidence):
+        return [make_sparse_plan(category, merchant, trigger, evidence, car, kind)]
+    strategies = deterministic_strategies_for(kind, customer, car)
+    candidates = [make_plan(category, merchant, trigger, customer, evidence, kind, strategy, car) for strategy in strategies]
+    if customer:
+        candidates.append(make_plan(category, merchant, trigger, customer, evidence, kind, "customer_low_friction", car))
+    else:
+        candidates.append(make_plan(category, merchant, trigger, customer, evidence, kind, "ask_merchant", car))
+        candidates.append(make_plan(category, merchant, trigger, customer, evidence, kind, "artifact_offer", car))
+    return [c for c in candidates if c.body and "no_send_jitai" not in c.risk_flags]
+
+
+def is_sparse_context(car: MerchantCAR, evidence: list[Evidence]) -> bool:
+    high_value = [
+        e for e in evidence
+        if e.kind in {"offer", "number", "date", "trigger", "signal"}
+        and (e.source.startswith("merchant") or e.source.startswith("trigger"))
+        and not e.source.startswith("merchant.car")
+        and e.value not in {"0", "0%", "unknown", "merchant only", "not applicable"}
+        and not e.label.startswith("car_consent")
+        and e.label not in {"category_offer"}
+    ]
+    useful_trigger_facts = [v for v in car.trigger_facts.values() if v and v != "unknown"]
+    has_merchant_offer = any(e.label == "active_offer" for e in evidence)
+    has_metrics = car.views_30d > 0 or car.calls_30d > 0 or bool(car.performance_deltas)
+    return len(high_value) < 2 and len(useful_trigger_facts) <= 1 and not has_merchant_offer and not has_metrics
+
+
+def make_sparse_plan(category: Context, merchant: Context, trigger: Context, evidence: list[Evidence], car: MerchantCAR, kind: str) -> DecisionPlan:
+    cat = car.category or merchant.get("category_slug") or category.get("slug", "restaurants")
+    frame = "effort_externalization"
+    arm = "sparse_reactivation"
+    principle = "reciprocity"
+    cta = CTA_YES_NO
+    signal = primary_signal(trigger, evidence)
+    body = sparse_fallback_body(cat, merchant, trigger, car)
+    body = apply_constitution_repairs(body, car, trigger)
+    violations = constitutional_violations(body, car, trigger, cta)
+    risk_flags = risk_flags_for(category, merchant, trigger, None, evidence) + ["sparse_context_floor"]
+    jitai = classify_jitai(car, evidence, risk_flags, None)
+    map_scores = score_map(car, trigger, body, cta, frame, risk_flags)
+    scores = score_plan(category, merchant, trigger, None, evidence, body, cta, "vera", risk_flags, "sparse_reactivation", map_scores, jitai)
+    action = "Reply YES and I will prepare the exact low-risk draft."
+    rationale = rationale_for(signal, evidence, "sparse-context reactivation + effort externalization", action, risk_flags, frame, arm, map_scores, jitai, principle, f"{cat}:engagement_compulsion")
+    return DecisionPlan(
+        primary_signal=signal,
+        evidence=evidence[:8],
+        selected_lever="sparse-context reactivation + effort externalization",
+        recommended_action=action,
+        risk_flags=risk_flags,
+        rubric_scores=scores,
+        copy_strategy="sparse_reactivation",
+        body=body,
+        cta=cta,
+        send_as="vera",
+        suppression_key=trigger.get("suppression_key") or trigger.get("id", ""),
+        rationale=rationale,
+        car_summary=car.summary(),
+        jitai_scores=jitai,
+        map_scores=map_scores,
+        frame=frame,
+        action_arm=arm,
+        variant_strategy="sparse_reactivation",
+        persuasion_principle=principle,
+        constitutional_violations=violations,
+        thought_frames=build_thought_frames(category, merchant, trigger, None, evidence, car),
+        reference_key=f"{cat}:engagement_compulsion",
+    )
+
+
+def sparse_fallback_body(cat: str, merchant: Context, trigger: Context, car: MerchantCAR) -> str:
+    name = merchant_salutation(merchant)
+    merchant_name = car.merchant_name if car.merchant_name != "unknown" else "your business"
+    locality = car.locality if car.locality != "unknown" else "your locality"
+    kind = signal_label(trigger.get("kind") or "reactivation")
+    if cat == "restaurants":
+        return f"{name}, your {locality} regulars have not seen a fresh {merchant_name} update tied to this {kind} signal. Want me to draft one simple weekday menu/post hook for approval?"
+    if cat == "salons":
+        return f"{name}, this {kind} signal is enough for a light service reminder, not a discount blast. Want me to draft a warm slot-led message for {locality} customers?"
+    if cat == "dentists":
+        return f"{name}, this {kind} signal has limited clinical detail, so I will keep it conservative. Want me to draft a short recall/checkup note for approval first?"
+    if cat == "gyms":
+        return f"{name}, this {kind} signal is thin, so the safest move is a no-pressure class/restart nudge. Want me to draft one for {locality} members?"
+    if cat == "pharmacies":
+        return f"{name}, this {kind} signal has limited stock/customer detail, so I will avoid medical claims. Want me to draft a calm counter/update note for approval?"
+    return f"{name}, this {kind} signal has limited detail, so I will keep the action conservative and specific to {merchant_name}. Want me to draft one approval-ready note?"
+
+
+def deterministic_strategies_for(kind: str, customer: Context | None, car: MerchantCAR) -> list[str]:
+    kind = kind or "generic"
+    if customer:
+        return order_strategies_by_priors(["certainty_frame", "effort_externalization", "social_proof"], car)
+    if kind in {"perf_dip", "seasonal_perf_dip", "renewal_due", "winback_eligible", "dormant_with_vera", "gbp_unverified", "competitor_opened"}:
+        return order_strategies_by_priors(["loss_frame", "effort_externalization", "certainty_frame"], car)
+    if kind in {"perf_spike", "milestone_reached"}:
+        return order_strategies_by_priors(["gain_frame", "social_proof", "effort_externalization"], car)
+    if kind in {"research_digest", "review_theme_emerged", "cde_opportunity"}:
+        return order_strategies_by_priors(["social_proof", "professional_value", "effort_externalization"], car)
+    if kind in {"regulation_change", "supply_alert", "festival_upcoming", "ipl_match_today", "category_seasonal"}:
+        return order_strategies_by_priors(["certainty_frame", "loss_frame", "effort_externalization"], car)
+    if car.last_response_intent in {"no_reply", "auto_reply"}:
+        return order_strategies_by_priors(["effort_externalization", "certainty_frame", "social_proof"], car)
+    return order_strategies_by_priors(["effort_externalization", "loss_frame", "gain_frame"], car)
+
+
+def order_strategies_by_priors(strategies: list[str], car: MerchantCAR) -> list[str]:
+    def prior(strategy: str) -> float:
+        arm = choose_action_arm(car.category, car.trigger_kind, strategy, bool(car.customer_id))
+        try:
+            return float(str(car.category_arm_priors.get(arm, "0.5")).split()[0])
+        except ValueError:
+            return 0.5
+    return sorted(strategies, key=lambda s: (prior(s), strategies.index(s) * -0.001), reverse=True)
+
+
+def make_plan(category: Context, merchant: Context, trigger: Context, customer: Context | None, evidence: list[Evidence], kind: str, strategy: str, car: MerchantCAR | None = None) -> DecisionPlan:
+    car = car or build_merchant_car(category, merchant, trigger, customer)
+    cat = merchant.get("category_slug") or category.get("slug", "")
+    playbook = CATEGORY_PLAYBOOKS.get(cat, CATEGORY_PLAYBOOKS["restaurants"])
+    frame = choose_prospect_frame(car, trigger, evidence, strategy)
+    arm = choose_action_arm(cat, kind, frame, customer)
+    principle = select_cialdini_principle(car, trigger, evidence, frame)
+    lever = framing_lever(frame, kind)
+    risk_flags = risk_flags_for(category, merchant, trigger, customer, evidence)
+    jitai = classify_jitai(car, evidence, risk_flags, customer)
+    if not customer and jitai["severity"] <= 2 and jitai["intervention_fit"] <= 4 and "placeholder_trigger" in risk_flags:
+        risk_flags.append("no_send_jitai")
+    send_as = "merchant_on_behalf" if customer and "consent_missing" not in risk_flags else "vera"
+    cta = choose_cta(kind, customer, risk_flags)
+    action = recommended_action(cat, kind, playbook, customer, risk_flags, strategy, frame)
+    signal = primary_signal(trigger, evidence)
+    body = render_body(category, merchant, trigger, customer, evidence, signal, lever, action, cta, send_as, strategy, frame, car, principle)
+    body = apply_constitution_repairs(body, car, trigger)
+    violations = constitutional_violations(body, car, trigger, cta)
+    map_scores = score_map(car, trigger, body, cta, frame, risk_flags)
+    scores = score_plan(category, merchant, trigger, customer, evidence, body, cta, send_as, risk_flags, strategy, map_scores, jitai)
+    reference_key = f"{cat}:{primary_dimension_for_frame(frame, kind)}"
+    thought_frames = build_thought_frames(category, merchant, trigger, customer, evidence, car)
+    rationale = rationale_for(signal, evidence, lever, action, risk_flags, frame, arm, map_scores, jitai, principle, reference_key)
+    return DecisionPlan(
+        primary_signal=signal,
+        evidence=evidence[:8],
+        selected_lever=lever,
+        recommended_action=action,
+        risk_flags=risk_flags,
+        rubric_scores=scores,
+        copy_strategy=strategy,
+        body=body,
+        cta=cta,
+        send_as=send_as,
+        suppression_key=trigger.get("suppression_key") or trigger.get("id", ""),
+        rationale=rationale,
+        car_summary=car.summary(),
+        jitai_scores=jitai,
+        map_scores=map_scores,
+        frame=frame,
+        action_arm=arm,
+        variant_strategy=strategy,
+        persuasion_principle=principle,
+        constitutional_violations=violations,
+        thought_frames=thought_frames,
+        reference_key=reference_key,
+    )
+
+
+def choose_prospect_frame(car: MerchantCAR, trigger: Context, evidence: list[Evidence], strategy: str) -> str:
+    kind = trigger.get("kind", "")
+    if strategy in {"loss_frame", "gain_frame", "certainty_frame", "social_proof", "professional_value", "effort_externalization"}:
+        return strategy
+    if kind in {"regulation_change", "supply_alert", "appointment_tomorrow", "recall_due", "chronic_refill_due", "renewal_due"}:
+        return "certainty_frame"
+    if kind in {"research_digest", "review_theme_emerged", "cde_opportunity"} or any(e.kind in {"source", "peer"} for e in evidence):
+        return "social_proof" if kind != "research_digest" else "professional_value"
+    if kind in {"perf_spike", "milestone_reached"} or any(not str(v).startswith("-") for v in car.performance_deltas.values()):
+        return "gain_frame"
+    if kind in {"perf_dip", "seasonal_perf_dip", "winback_eligible", "dormant_with_vera", "gbp_unverified", "competitor_opened"}:
+        return "loss_frame"
+    return "effort_externalization"
+
+
+def choose_action_arm(cat: str, kind: str, frame: str, customer: Context | None) -> str:
+    if customer:
+        if kind in {"recall_due", "appointment_tomorrow"}:
+            return "appointment_confirm"
+        if kind == "chronic_refill_due":
+            return "refill_dispatch"
+        if "lapsed" in kind:
+            return "winback_slot"
+        return "customer_next_step"
+    if frame == "loss_frame":
+        return "recovery_nudge"
+    if frame == "gain_frame":
+        return "momentum_amplifier"
+    if frame == "certainty_frame":
+        return "deadline_action"
+    if frame in {"social_proof", "professional_value"}:
+        return "proof_to_action"
+    return CATEGORY_PLAYBOOKS.get(cat, {}).get("action", "draft_action").replace(" ", "_")
+
+
+def select_cialdini_principle(car: MerchantCAR, trigger: Context, evidence: list[Evidence], frame: str) -> str:
+    payload = trigger.get("payload", {}) or {}
+    if frame == "certainty_frame" or any(k in payload for k in ["expires_at", "deadline_iso", "days_until", "available_slots", "stock_runs_out_iso"]):
+        return "scarcity"
+    if any(e.kind in {"peer", "source"} for e in evidence) or frame == "social_proof":
+        return "social_proof"
+    if car.category in {"dentists", "pharmacies"} and any(e.kind == "source" for e in evidence):
+        return "authority"
+    if frame == "loss_frame" or car.no_reply_count >= 1:
+        return "reciprocity"
+    if car.last_response_intent in {"commitment", "reply"} or "success" in " ".join(car.response_sequence).lower():
+        return "commitment"
+    return "liking"
+
+
+def principle_phrase(principle: str, car: MerchantCAR | None, customer: bool = False) -> str:
+    if customer or not principle:
+        return ""
+    if principle == "scarcity":
+        return "The window is limited: "
+    if principle == "social_proof":
+        return ""
+    if principle == "authority":
+        return "Data-backed angle: "
+    if principle == "reciprocity":
+        return "I can do the heavy lifting: "
+    if principle == "commitment":
+        return "You already have momentum here: "
+    if principle == "liking":
+        return ""
+    return ""
+
+
+def framing_lever(frame: str, kind: str) -> str:
+    base = LEVER_BY_KIND.get(kind, "specificity + effort externalization")
+    if frame == "loss_frame":
+        return f"loss aversion + {base}"
+    if frame == "gain_frame":
+        return f"gain/momentum + {base}"
+    if frame == "certainty_frame":
+        return f"certainty/urgency + {base}"
+    if frame == "social_proof":
+        return f"social proof + {base}"
+    if frame == "professional_value":
+        return f"professional credibility + {base}"
+    return f"effort externalization + {base}"
+
+
+def render_body(category: Context, merchant: Context, trigger: Context, customer: Context | None, evidence: list[Evidence], signal: str, lever: str, action: str, cta: str, send_as: str, strategy: str, frame: str = "effort_externalization", car: MerchantCAR | None = None, principle: str = "liking") -> str:
+    cat = merchant.get("category_slug") or category.get("slug", "")
+    name = customer_name(customer) if customer and send_as == "merchant_on_behalf" else merchant_salutation(merchant)
+    merchant_name = merchant.get("identity", {}).get("name", "your business")
+    key_facts = choose_key_facts_for_body(evidence, str(trigger.get("kind", "")), customer=bool(customer), max_items=3)
+    fact_sentence = "; ".join(format_fact(e) for e in key_facts)
+    fact_sentence = fact_sentence.rstrip(".")
+    kind = str(trigger.get("kind", "signal")).replace("_", " ")
+    why_now = why_now_phrase(trigger, evidence)
+    voice_prefix = category_voice_phrase(cat, customer=bool(customer))
+    principle_prefix = principle_phrase(principle, car, customer=bool(customer))
+    frame_only = "" if principle == "scarcity" and frame == "certainty_frame" else frame_phrase(frame, car, customer=bool(customer))
+    frame_prefix = f"{principle_prefix}{frame_only}"
+    reflection_hint = reflection_phrase(car)
+
+    if not customer and str(trigger.get("kind")) == "active_planning_intent" and car:
+        topic = fact_value(evidence, "intent_topic") or fact_value(evidence, "topic") or "this plan"
+        offer = fact_value(evidence, "active_offer") or (car.active_offers[0] if car.active_offers else "")
+        demand = fact_value(evidence, "views_30d") or fact_value(evidence, "calls_30d")
+        demand_phrase = f" with {demand} recent demand signals" if demand else ""
+        offer_phrase = f" using {offer}" if offer else ""
+        timing_phrase = " for the next lunch window" if any(term in topic.lower() for term in ["lunch", "thali", "corporate"]) else ""
+        body = f"{name}, you asked about {topic}. Draft angle: package it for {car.locality or 'your locality'}{timing_phrase}{offer_phrase}{demand_phrase}; Reply YES and I will prepare the exact ready-to-send post/message from the context already shared."
+        return final_scrub(body)
+
+    if customer and send_as == "merchant_on_behalf":
+        if "hi" in str((customer or {}).get("identity", {}).get("language_pref", "")).lower():
+            opener = f"Hi {name}, {merchant_name} here."
+        elif cat == "pharmacies":
+            opener = f"Namaste {name}, {merchant_name} here."
+        else:
+            opener = f"Hi {name}, {merchant_name} here."
+        body = f"{opener} {why_now}. {fact_sentence}. {reflection_hint}{frame_prefix}{action}"
+    elif customer and send_as == "vera":
+        body = f"{merchant_salutation(merchant)}, {why_now}. {fact_sentence}. Consent is not explicit for direct customer outreach, so {reflection_hint}{frame_prefix}{action}"
+    else:
+        body = f"{name}, {why_now}. {fact_sentence}. {voice_prefix}{reflection_hint}{frame_prefix}{action}"
+
+    body = close_with_cta(body, cta, action, kind)
+    return final_scrub(body)
+
+
+def fact_value(evidence: list[Evidence], label: str) -> str:
+    for item in evidence:
+        if item.label == label or item.label == f"car_{label}":
+            return item.value
+    return ""
+
+
+def frame_phrase(frame: str, car: MerchantCAR | None, customer: bool = False) -> str:
+    if customer:
+        return ""
+    if frame == "loss_frame":
+        return "This is a recovery moment: "
+    if frame == "gain_frame":
+        return "Momentum is visible: "
+    if frame == "certainty_frame":
+        return "The next step is time-bound: "
+    if frame == "social_proof":
+        return "Use the proof while it is fresh: "
+    if frame == "professional_value":
+        return "Credibility angle: "
+    return ""
+
+
+def reflection_phrase(car: MerchantCAR | None) -> str:
+    if not car or not car.reflection_note:
+        return ""
+    if "auto" in car.reflection_note.lower() or "no reply" in car.reflection_note.lower():
+        return "Keeping this shorter than the last nudge: "
+    if "stop" in car.reflection_note.lower():
+        return ""
+    return ""
+
+
+def why_now_phrase(trigger: Context, evidence: list[Evidence]) -> str:
+    kind = signal_label(trigger.get("kind", "signal"))
+    source = str(trigger.get("source") or "").replace("_", " ").strip()
+    payload = trigger.get("payload", {}) or {}
+    if kind == "research digest":
+        return "this research digest trigger points to a relevant category item"
+    if kind in {"regulation change", "supply alert"}:
+        return f"urgent {kind} came in"
+    if kind in {"recall due", "appointment tomorrow", "chronic refill due"}:
+        return f"{kind} is due now"
+    if payload.get("deadline_iso"):
+        return f"{kind} has a deadline on {payload['deadline_iso']}"
+    if payload.get("days_until") is not None:
+        return f"{kind} is {payload['days_until']} days away"
+    if source and source.lower() not in {"internal", "system"}:
+        article = "an" if source[:1].lower() in {"a", "e", "i", "o", "u"} else "a"
+        return f"{article} {source} {kind} signal is active now"
+    return f"this {kind} signal is active now"
+
+
+def recommended_action(cat: str, kind: str, playbook: Context, customer: Context | None, risk_flags: list[str], strategy: str, frame: str = "effort_externalization") -> str:
+    if "consent_missing" in risk_flags:
+        return "I can draft a consent-safe approval note for you first."
+    if customer:
+        if kind == "chronic_refill_due":
+            return "Reply CONFIRM to dispatch, or tell us if dosage/brand changed."
+        if kind in {"recall_due", "appointment_tomorrow"}:
+            return "Reply YES to confirm, or send a better time."
+        if kind in {"customer_lapsed_hard", "customer_lapsed_soft"}:
+            return "Reply YES and we will hold a no-commitment restart slot."
+        return "Reply YES if you want us to hold the next step."
+    if kind == "curious_ask_due":
+        return "Reply with the one service customers asked for most this week; I will turn it into a post and reply draft."
+    if kind == "active_planning_intent":
+        return "I will draft the ready-to-send package/post from this now."
+    if kind in {"perf_dip", "seasonal_perf_dip"}:
+        return "Want me to draft the recovery/retention message?"
+    if kind in {"regulation_change", "supply_alert"}:
+        return "Want me to draft the checklist plus customer note?"
+    if frame == "loss_frame":
+        return "Want me to draft one recovery message now?"
+    if frame == "gain_frame":
+        return "Want me to turn this momentum into a ready post/message?"
+    if frame == "certainty_frame":
+        return "Want me to prepare the exact time-bound draft now?"
+    if frame in {"social_proof", "professional_value"}:
+        return "Want me to turn this proof into a merchant-ready draft?"
+    if strategy == "ask_merchant":
+        return "Reply YES and I will prepare the exact draft."
+    return f"Want me to {playbook['action']}?"
+
+
+def close_with_cta(body: str, cta: str, action: str, kind: str) -> str:
+    body = clean(body)
+    if cta == CTA_NONE:
+        return body
+    if body.endswith("?"):
+        return body
+    if cta == CTA_CONFIRM and "Reply CONFIRM" not in body:
+        return f"{body} Reply CONFIRM to proceed."
+    if cta == CTA_SLOTS and "Reply 1" not in body:
+        return f"{body} Reply 1/2 for the slot, or suggest a time."
+    if cta == CTA_YES_NO and "Reply YES" not in body and not body.endswith("?"):
+        return f"{body} Reply YES and I will do it."
+    return body
+
+
+def score_plan(category: Context, merchant: Context, trigger: Context, customer: Context | None, evidence: list[Evidence], body: str, cta: str, send_as: str, risk_flags: list[str], strategy: str, map_scores: dict[str, int] | None = None, jitai_scores: dict[str, int] | None = None) -> dict[str, int]:
+    map_scores = map_scores or {}
+    jitai_scores = jitai_scores or {}
+    scores = {
+        "decision_quality": score_decision_quality(trigger, evidence, body, strategy, risk_flags),
+        "specificity": score_specificity(evidence, body),
+        "category_fit": score_category_fit(category, merchant, body),
+        "merchant_fit": score_merchant_fit(merchant, customer, evidence, body, send_as),
+        "engagement_compulsion": score_engagement_compulsion(trigger, evidence, body, cta, risk_flags),
+    }
+    if map_scores:
+        scores["engagement_compulsion"] += 1 if min(map_scores.values()) >= 6 else -1
+        scores["decision_quality"] += 1 if sum(jitai_scores.values()) >= 20 else 0
+    return {k: max(0, min(10, v)) for k, v in scores.items()}
+
+
+def classify_jitai(car: MerchantCAR, evidence: list[Evidence], risk_flags: list[str], customer: Context | None) -> dict[str, int]:
+    severity = min(10, max(1, car.trigger_urgency * 2))
+    if customer:
+        severity += 2
+    if any(e.kind in {"date", "trigger"} and e.weight >= 4 for e in evidence):
+        severity += 1
+    if any(e.kind in {"source", "offer", "number"} and e.weight >= 4 for e in evidence):
+        severity += 1
+    if "weak_evidence" in risk_flags:
+        severity -= 2
+
+    receptivity = 7
+    if car.last_response_intent in {"stop", "hostile"}:
+        receptivity = 0
+    elif car.last_response_intent == "auto_reply":
+        receptivity = 3
+    elif car.last_response_intent in {"yes", "commitment"}:
+        receptivity = 9
+    elif car.no_reply_count >= 2:
+        receptivity = 4
+    if customer and car.consent_state != "allowed":
+        receptivity = min(receptivity, 5)
+
+    intervention_fit = 5
+    if car.trigger_kind in LEVER_BY_KIND:
+        intervention_fit += 2
+    if car.active_offers:
+        intervention_fit += 1
+    if any(e.source.startswith("trigger") for e in evidence):
+        intervention_fit += 1
+    if car.repeated_action_count >= 2:
+        intervention_fit -= 2
+    if "placeholder_trigger" in risk_flags and len(evidence) < 5:
+        intervention_fit -= 2
+
+    return {
+        "severity": max(0, min(10, severity)),
+        "receptivity": max(0, min(10, receptivity)),
+        "intervention_fit": max(0, min(10, intervention_fit)),
+    }
+
+
+def score_map(car: MerchantCAR, trigger: Context, body: str, cta: str, frame: str, risk_flags: list[str]) -> dict[str, int]:
+    motivation = 5
+    if frame in {"loss_frame", "gain_frame", "certainty_frame", "social_proof", "professional_value"}:
+        motivation += 2
+    if re.search(r"\d", body):
+        motivation += 1
+    if trigger.get("urgency", 1) >= 3:
+        motivation += 1
+    if "weak_evidence" in risk_flags:
+        motivation -= 2
+
+    ability_by_cta = {
+        CTA_NONE: 9,
+        CTA_YES_NO: 9,
+        CTA_CONFIRM: 8,
+        CTA_SLOTS: 8,
+        CTA_OPEN: 6,
+    }
+    ability = ability_by_cta.get(cta, 5)
+    if len(body) > 520:
+        ability -= 1
+    if body.count("?") > 1:
+        ability -= 2
+
+    prompt = 5 + min(3, safe_int(trigger.get("urgency"), 1))
+    payload = trigger.get("payload", {}) or {}
+    if any(k in payload for k in ["deadline_iso", "expires_at", "days_until", "available_slots", "stock_runs_out_iso"]):
+        prompt += 1
+    if frame == "certainty_frame":
+        prompt += 1
+    if "no_send_jitai" in risk_flags:
+        prompt -= 4
+    return {
+        "motivation": max(0, min(10, motivation)),
+        "ability": max(0, min(10, ability)),
+        "prompt": max(0, min(10, prompt)),
+    }
+
+
+VERA_CONSTITUTION = [
+    "No invented numbers; every figure must trace to supplied context.",
+    "No generic phrases like increase sales, boost sales, or grow your business.",
+    "Use one CTA only.",
+    "Name a merchant, trigger, offer, metric, source, date, locality, or customer fact.",
+    "Urgency must be tied to a concrete trigger, date, count, or deadline.",
+    "Avoid repeating the same action type after weak engagement.",
+    "Use peer-to-peer merchant language, not corporate partner language.",
+    "For pharmacy customer cases without consent, route to merchant approval and avoid dispatch, dosage, or medical advice copy.",
+]
+
+
+def apply_constitution_repairs(body: str, car: MerchantCAR, trigger: Context) -> str:
+    repaired = body
+    replacements = {
+        "increase sales": "recover the current signal",
+        "boost sales": "act on this signal",
+        "grow your business": "turn this trigger into one concrete action",
+        "Dear valued partner": car.owner or car.merchant_name,
+        "valued partner": car.owner or car.merchant_name,
+    }
+    for bad, good in replacements.items():
+        repaired = re.sub(re.escape(bad), good, repaired, flags=re.I)
+    if repaired.count("?") > 1:
+        first_q = repaired.find("?")
+        repaired = repaired[: first_q + 1] + repaired[first_q + 1 :].replace("?", ".")
+    return final_scrub(repaired)
+
+
+def constitutional_violations(body: str, car: MerchantCAR, trigger: Context, cta: str) -> list[str]:
+    lower = body.lower()
+    violations: list[str] = []
+    if any(p in lower for p in ["increase sales", "boost sales", "grow your business", "dear valued partner"]):
+        violations.append("generic_or_corporate_copy")
+    if body.count("?") > 1:
+        violations.append("multiple_questions")
+    if cta not in {CTA_NONE, CTA_OPEN, CTA_YES_NO, CTA_CONFIRM, CTA_SLOTS}:
+        violations.append("invalid_cta")
+    concrete = bool(re.search(r"\d", body) or car.locality.lower() in lower or any(str(v).lower() in lower for v in car.trigger_facts.values() if v and v != "unknown") or any(o.lower() in lower for o in car.active_offers))
+    if not concrete:
+        violations.append("missing_concrete_fact")
+    if car.repeated_action_count >= 2 and car.last_action_type and car.last_action_type in lower:
+        violations.append("repeated_action_type")
+    if car.category == "pharmacies" and car.customer_id and car.consent_state != "allowed":
+        if any(term in lower for term in ["dispatch", "dosage", "delivery can go", "medicine is due", "diagnosis", "cure"]):
+            violations.append("pharmacy_consent_or_medical_advice_risk")
+    return violations
+
+
+def build_thought_frames(category: Context, merchant: Context, trigger: Context, customer: Context | None, evidence: list[Evidence], car: MerchantCAR) -> list[dict[str, Any]]:
+    thoughts: list[dict[str, Any]] = []
+    for strategy in deterministic_strategies_for(trigger.get("kind", "generic"), customer, car):
+        frame = choose_prospect_frame(car, trigger, evidence, strategy)
+        principle = select_cialdini_principle(car, trigger, evidence, frame)
+        arm = choose_action_arm(car.category, trigger.get("kind", "generic"), frame, customer)
+        map_guess = score_map(car, trigger, " ".join(e.value for e in choose_key_facts(evidence, bool(customer), 3)), choose_cta(trigger.get("kind", "generic"), customer, []), frame, [])
+        thoughts.append({
+            "strategy": strategy,
+            "frame": frame,
+            "principle": principle,
+            "action_arm": arm,
+            "score": sum(map_guess.values()),
+        })
+    return sorted(thoughts, key=lambda t: int(t["score"]), reverse=True)[:4]
+
+
+def primary_dimension_for_frame(frame: str, kind: str) -> str:
+    if frame in {"loss_frame", "gain_frame", "certainty_frame"}:
+        return "engagement_compulsion"
+    if frame in {"social_proof", "professional_value"}:
+        return "decision_quality" if kind == "research_digest" else "specificity"
+    return "merchant_fit"
+
+
+def score_decision_quality(trigger: Context, evidence: list[Evidence], body: str, strategy: str, risk_flags: list[str]) -> int:
+    score = 5
+    if trigger.get("kind") and str(trigger.get("kind")).replace("_", " ") in body.lower():
+        score += 1
+    if any(e.source.startswith("trigger") for e in evidence):
+        score += 2
+    if any(e.kind in {"offer", "number", "source"} for e in evidence):
+        score += 1
+    if strategy in {"primary", "artifact_offer"}:
+        score += 1
+    if "weak_evidence" in risk_flags:
+        score -= 2
+    return score
+
+
+def score_specificity(evidence: list[Evidence], body: str) -> int:
+    score = 4
+    if re.search(r"\d", body):
+        score += 2
+    if any(e.kind == "offer" for e in evidence):
+        score += 1
+    if any(e.kind == "date" for e in evidence):
+        score += 1
+    if any(e.kind == "source" for e in evidence):
+        score += 1
+    if any(e.kind == "local" for e in evidence):
+        score += 1
+    return score
+
+
+def score_category_fit(category: Context, merchant: Context, body: str) -> int:
+    cat = merchant.get("category_slug") or category.get("slug", "")
+    terms = CATEGORY_PLAYBOOKS.get(cat, {}).get("terms", [])
+    score = 6 + min(2, sum(1 for term in terms if term.lower() in body.lower()))
+    if cat == "dentists" and any(w in body.lower() for w in ["guaranteed", "miracle"]):
+        score -= 3
+    if cat == "pharmacies" and any(w in body.lower() for w in ["panic", "cure"]):
+        score -= 3
+    if "flat" in body.lower() and "%" in body:
+        score -= 1
+    return score
+
+
+def score_merchant_fit(merchant: Context, customer: Context | None, evidence: list[Evidence], body: str, send_as: str) -> int:
+    identity = merchant.get("identity", {})
+    score = 5
+    if identity.get("owner_first_name") and str(identity["owner_first_name"]).split()[-1].lower() in body.lower():
+        score += 1
+    if identity.get("name") and str(identity["name"]).split()[0].lower() in body.lower():
+        score += 1
+    if any(e.source.startswith("merchant") for e in evidence):
+        score += 2
+    if customer and send_as == "merchant_on_behalf":
+        score += 1
+    return score
+
+
+def score_engagement_compulsion(trigger: Context, evidence: list[Evidence], body: str, cta: str, risk_flags: list[str]) -> int:
+    score = 5
+    if cta in {CTA_YES_NO, CTA_CONFIRM, CTA_SLOTS, CTA_OPEN}:
+        score += 1
+    if any(word in body.lower() for word in ["want me", "reply yes", "reply confirm", "draft", "hold", "checklist"]):
+        score += 2
+    if any(e.kind in {"number", "source", "offer"} and e.weight >= 3 for e in evidence):
+        score += 1
+    if trigger.get("urgency", 1) >= 3:
+        score += 1
+    if "consent_missing" in risk_flags:
+        score -= 1
+    return score
+
+
+def plan_to_message(plan: DecisionPlan) -> Context:
+    return {
+        "body": plan.body,
+        "cta": plan.cta,
+        "send_as": plan.send_as,
+        "suppression_key": plan.suppression_key,
+        "rationale": plan.rationale,
+        "decision_plan": {
+            "primary_signal": plan.primary_signal,
+            "selected_lever": plan.selected_lever,
+            "recommended_action": plan.recommended_action,
+            "risk_flags": plan.risk_flags,
+            "rubric_scores": plan.rubric_scores,
+            "copy_strategy": plan.copy_strategy,
+            "car_summary": plan.car_summary,
+            "jitai_scores": plan.jitai_scores,
+            "map_scores": plan.map_scores,
+            "frame": plan.frame,
+            "action_arm": plan.action_arm,
+            "variant_strategy": plan.variant_strategy,
+            "persuasion_principle": plan.persuasion_principle,
+            "constitutional_violations": plan.constitutional_violations,
+            "thought_frames": plan.thought_frames,
+            "reference_key": plan.reference_key,
+            "constitution": VERA_CONSTITUTION,
+            "evidence": [e.__dict__ for e in plan.evidence[:6]],
+        },
+    }
+
+
+def improve_with_llm_if_available(category: Context, merchant: Context, trigger: Context, customer: Context | None, plan: DecisionPlan, output: Context) -> Context | None:
+    api_key = os.getenv("OPENAI_API_KEY")
+    if not api_key:
+        return None
+    model = os.getenv("OPENAI_MODEL", "gpt-4o-mini")
+    prompt = {
+        "task": "Improve this Vera WhatsApp message without adding facts. Return JSON only.",
+        "rules": [
+            "Use only evidence provided.",
+            "One CTA only.",
+            "No invented numbers, names, links, offers, citations, dates, or slots.",
+            "Keep body concise and merchant/customer appropriate.",
+            "Do not alter suppression_key or send_as.",
+        ],
+        "category": merchant.get("category_slug") or category.get("slug"),
+        "trigger_kind": trigger.get("kind"),
+        "evidence": [e.__dict__ for e in plan.evidence],
+        "draft": output,
+    }
+    schema = {
+        "type": "json_schema",
+        "json_schema": {
+            "name": "vera_message",
+            "strict": True,
+            "schema": {
+                "type": "object",
+                "additionalProperties": False,
+                "required": ["body", "cta", "send_as", "suppression_key", "rationale"],
+                "properties": {
+                    "body": {"type": "string"},
+                    "cta": {"type": "string", "enum": [CTA_NONE, CTA_OPEN, CTA_YES_NO, CTA_CONFIRM, CTA_SLOTS]},
+                    "send_as": {"type": "string", "enum": ["vera", "merchant_on_behalf"]},
+                    "suppression_key": {"type": "string"},
+                    "rationale": {"type": "string"},
+                },
+            },
+        },
+    }
+    body = json.dumps({
+        "model": model,
+        "messages": [
+            {"role": "system", "content": "You are Vera's copy reviewer. Output valid JSON matching the schema. Never invent facts."},
+            {"role": "user", "content": json.dumps(prompt, ensure_ascii=False)},
+        ],
+        "temperature": 0.1,
+        "seed": 20260426,
+        "response_format": schema,
+        "max_tokens": 500,
+    }).encode("utf-8")
+    req = urlrequest.Request(
+        "https://api.openai.com/v1/chat/completions",
+        data=body,
+        headers={"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"},
+        method="POST",
+    )
+    try:
+        with urlrequest.urlopen(req, timeout=8) as resp:
+            data = json.loads(resp.read().decode("utf-8"))
+        content = data["choices"][0]["message"]["content"]
+        improved = json.loads(content)
+    except Exception:
+        return None
+    if not validate_output_against_evidence(improved, plan):
+        return None
+    improved["decision_plan"] = output.get("decision_plan")
+    return improved
+
+
+def validate_output_against_evidence(output: Context, plan: DecisionPlan) -> bool:
+    body = str(output.get("body", ""))
+    if not body or any(p in body for p in ["None", "Dr. Dr.", "I will not send"]):
+        return False
+    if output.get("send_as") != plan.send_as or output.get("suppression_key") != plan.suppression_key:
+        return False
+    numbers = re.findall(r"\b\d+(?:\.\d+)?%?|\b₹\s?\d[\d,]*", body)
+    evidence_text = " ".join(e.value for e in plan.evidence)
+    for number in numbers:
+        if number not in evidence_text and number.strip("₹ ") not in evidence_text:
+            return False
+    return True
+
+
+def risk_flags_for(category: Context, merchant: Context, trigger: Context, customer: Context | None, evidence: list[Evidence]) -> list[str]:
+    flags: list[str] = []
+    if len(evidence) < 4:
+        flags.append("weak_evidence")
+    if customer and not has_consent(customer, trigger):
+        flags.append("consent_missing")
+    if trigger.get("payload", {}).get("placeholder"):
+        flags.append("placeholder_trigger")
+    return flags
+
+
+def has_consent(customer: Context, trigger: Context) -> bool:
+    prefs = customer.get("preferences", {})
+    if prefs.get("reminder_opt_in") is False:
+        return False
+    scopes = set(customer.get("consent", {}).get("scope", []) or [])
+    kind = trigger.get("kind", "")
+    if kind in {"recall_due", "appointment_tomorrow"}:
+        return bool(scopes & {"recall_reminders", "appointment_reminders"})
+    if kind == "chronic_refill_due":
+        return bool(scopes & {"refill_reminders", "delivery_notifications", "recall_alerts"})
+    if kind in {"customer_lapsed_hard", "customer_lapsed_soft"}:
+        return bool(scopes & {"winback_offers", "renewal_reminders", "promotional_offers"})
+    if kind == "wedding_package_followup":
+        return "bridal_package_followup" in scopes
+    if kind == "trial_followup":
+        return bool(scopes & {"kids_program_updates", "program_updates", "appointment_reminders"})
+    return bool(scopes)
+
+
+def choose_cta(kind: str, customer: Context | None, risk_flags: list[str]) -> str:
+    if "consent_missing" in risk_flags:
+        return CTA_YES_NO
+    if customer and kind in {"recall_due", "appointment_tomorrow"}:
+        return CTA_SLOTS if kind == "recall_due" else CTA_CONFIRM
+    if customer and kind == "chronic_refill_due":
+        return CTA_CONFIRM
+    if kind in {"research_digest", "curious_ask_due"}:
+        return CTA_OPEN
+    if kind == "active_planning_intent":
+        return CTA_YES_NO
+    return CTA_YES_NO
+
+
+def choose_key_facts(evidence: list[Evidence], customer: bool = False, max_items: int = 3) -> list[Evidence]:
+    if customer:
+        priority = {"trigger": 0, "date": 1, "customer": 2, "offer": 3, "number": 4, "local": 5, "history": 6, "signal": 7, "source": 8, "peer": 9}
+    else:
+        priority = {"source": 0, "number": 1, "offer": 2, "trigger": 3, "date": 4, "local": 5, "history": 6, "signal": 7, "peer": 8, "customer": 9}
+    def rank(e: Evidence) -> tuple[int, int, int]:
+        label_bonus = -3 if any(tok in e.label for tok in ["risk", "chronic", "active_members", "available_slots"]) else 0
+        return (priority.get(e.kind, 20), label_bonus, -e.weight)
+    sorted_e = sorted(evidence, key=rank)
+    chosen: list[Evidence] = []
+    seen_values: set[str] = set()
+    for e in sorted_e:
+        if e.value in seen_values or e.kind == "identity":
+            continue
+        chosen.append(e)
+        seen_values.add(e.value)
+        if len(chosen) >= max_items:
+            break
+    return chosen
+
+
+def choose_key_facts_for_body(evidence: list[Evidence], kind: str, customer: bool = False, max_items: int = 3) -> list[Evidence]:
+    if kind == "active_planning_intent":
+        priority = {
+            "intent_topic": 0,
+            "merchant_last_message": 1,
+            "active_offer": 2,
+            "calls_30d": 3,
+            "views_30d": 4,
+            "locality": 5,
+        }
+    elif kind in {"perf_dip", "perf_spike", "seasonal_perf_dip"}:
+        priority = {"metric": 0, "delta_pct": 1, "calls_7d": 2, "views_7d": 3, "active_offer": 4, "calls_30d": 5, "views_30d": 6}
+    elif kind in {"research_digest", "cde_opportunity"}:
+        priority = {"digest_title": 0, "digest_source": 1, "high_risk_adult_count": 2, "digest_summary_fact": 3, "trial_n": 4, "active_offer": 5}
+    elif kind == "curious_ask_due":
+        priority = {"topic": 0, "metric_or_topic": 1, "active_offer": 2, "calls_30d": 3, "views_30d": 4, "locality": 5}
+    else:
+        chosen = choose_key_facts(evidence, customer=customer, max_items=max_items)
+        if not customer and not any(e.label in {"locality", "car_locality"} for e in chosen):
+            locality = next((e for e in evidence if e.label in {"locality", "car_locality"}), None)
+            if locality and all(e.value != locality.value for e in chosen):
+                chosen = (chosen[: max_items - 1] + [locality])[:max_items]
+        return chosen
+
+    chosen: list[Evidence] = []
+    seen_values: set[str] = set()
+    sorted_e = sorted(
+        [e for e in evidence if e.kind != "identity"],
+        key=lambda e: (priority.get(e.label, 50), -e.weight),
+    )
+    for e in sorted_e:
+        if e.value in seen_values:
+            continue
+        chosen.append(e)
+        seen_values.add(e.value)
+        if len(chosen) >= max_items:
+            break
+    if len(chosen) < max_items:
+        for e in choose_key_facts(evidence, customer=customer, max_items=max_items):
+            if e.value not in seen_values:
+                chosen.append(e)
+                seen_values.add(e.value)
+            if len(chosen) >= max_items:
+                break
+    return chosen
+
+
+def format_fact(e: Evidence) -> str:
+    label = e.label.replace("car_", "")
+    readable = {
+        "views_30d": "30d views",
+        "calls_30d": "30d calls",
+        "ctr": "CTR",
+        "active_offer": "active offer",
+        "category_offer": "category hook",
+        "intent_topic": "merchant asked about",
+        "merchant_last_message": "merchant replied",
+        "digest_title": "digest item",
+        "digest_source": "source",
+        "trial_n": "sample size",
+        "digest_summary_fact": "digest fact",
+        "days_inactive": "inactive for",
+        "locality": "locality",
+        "metric": "metric",
+        "delta_pct": "delta",
+        "available_slots": "slots",
+        "molecule_list": "medicines",
+        "affected_batches": "affected batches",
+    }.get(label, label.replace("_", " "))
+    if label == "views_30d":
+        return f"{e.value} 30d views"
+    if label == "calls_30d":
+        return f"{e.value} 30d calls"
+    if label == "ctr":
+        return f"{e.value} CTR"
+    if label == "days_inactive":
+        return f"inactive for {e.value} days" if str(e.value).isdigit() else f"inactive for {e.value}"
+    return f"{readable}: {e.value}"
+
+
+def primary_signal(trigger: Context, evidence: list[Evidence]) -> str:
+    kind = signal_label(trigger.get("kind", "signal"))
+    high = next((e.value for e in evidence if e.source.startswith("trigger") and e.kind != "identity"), "")
+    return clean(f"{kind}: {high}") if high else kind
+
+
+def signal_label(kind: Any) -> str:
+    label = clean(str(kind or "signal").replace("_", " "))
+    return re.sub(r"\s+signal$", "", label, flags=re.I)
+
+
+def rationale_for(signal: str, evidence: list[Evidence], lever: str, action: str, risk_flags: list[str], frame: str = "effort_externalization", arm: str = "draft_action", map_scores: dict[str, int] | None = None, jitai_scores: dict[str, int] | None = None, principle: str = "liking", reference_key: str = "default") -> str:
+    facts = ", ".join(f"{e.label}={e.value}" for e in choose_key_facts(evidence, max_items=3))
+    risk = f" Risk flags: {', '.join(risk_flags)}." if risk_flags else ""
+    map_part = f" B=MAP={map_scores}." if map_scores else ""
+    jitai_part = f" JITAI={jitai_scores}." if jitai_scores else ""
+    return clean(f"Selected signal '{signal}' with evidence ({facts}); frame={frame}; principle={principle}; arm={arm}; reference={reference_key}; lever={lever}; action={action}.{map_part}{jitai_part}{risk}")
+
+
+def category_voice_phrase(cat: str, customer: bool = False) -> str:
+    if customer:
+        return ""
+    if cat == "dentists":
+        return "Clinical angle: "
+    if cat == "restaurants":
+        return "Operator angle: "
+    if cat == "gyms":
+        return "Retention angle: "
+    if cat == "pharmacies":
+        return "Safe-action angle: "
+    if cat == "salons":
+        return "Service angle: "
+    return ""
+
+
+def merchant_salutation(merchant: Context) -> str:
+    identity = merchant.get("identity", {})
+    owner = clean(str(identity.get("owner_first_name") or ""))
+    name = clean(str(identity.get("name") or "there"))
+    if merchant.get("category_slug") == "dentists":
+        if owner:
+            return owner if owner.lower().startswith("dr") else f"Dr. {owner}"
+        return dedupe_dr(name)
+    return owner or name
+
+
+def customer_name(customer: Context | None) -> str:
+    if not customer:
+        return "there"
+    return clean(str(customer.get("identity", {}).get("name") or "there")).replace("(parent:", "parent:")
+
+
+def dedupe_evidence(evidence: list[Evidence]) -> list[Evidence]:
+    out: list[Evidence] = []
+    seen: set[tuple[str, str]] = set()
+    for e in evidence:
+        key = (e.label, e.value)
+        if key in seen:
+            continue
+        seen.add(key)
+        out.append(e)
+    return out
+
+
+def first_numeric_fact(value: Any) -> str | None:
+    if not value:
+        return None
+    match = re.search(r"\d+(?:\.\d+)?%|\d+(?:\.\d+)?\s?mSv|\d+(?:,\d+)*", str(value))
+    return match.group(0) if match else None
+
+
+def pct(value: Any) -> str:
+    try:
+        num = float(value)
+    except (TypeError, ValueError):
+        return ""
+    return f"{num * 100:.0f}%" if abs(num) <= 1 else f"{num:g}%"
+
+
+def clean(value: str) -> str:
+    return re.sub(r"\s+", " ", value).strip()
+
+
+def dedupe_dr(value: str) -> str:
+    return re.sub(r"\bDr\.\s+Dr\.\s+", "Dr. ", value).strip()
+
+
+def final_scrub(value: str) -> str:
+    value = dedupe_dr(value)
+    value = value.replace("None", "")
+    value = value.replace("..", ".")
+    value = re.sub(r"\b(up|down|dropped|rose|increased)\s+0%\b", "changed in the latest context", value, flags=re.I)
+    value = re.sub(r"\s+([?.!,;:])", r"\1", value)
+    return clean(value)

app/main.py

@@ -0,0 +1,459 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+import os
+from time import time
+from typing import Any
+
+from fastapi import FastAPI, Request
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel, Field
+
+from .composer import (
+    compose,
+    is_auto_reply,
+    is_commitment,
+    is_stop_or_hostile,
+    make_conversation_id,
+    reply_to_message,
+)
+from .decision_engine import expected_trigger_score
+
+
+START = time()
+VALID_SCOPES = {"category", "merchant", "customer", "trigger"}
+
+app = FastAPI(title="Vera Rubric Decision Engine", version="1.1.0")
+
+contexts: dict[tuple[str, str], dict[str, Any]] = {}
+conversations: dict[str, dict[str, Any]] = {}
+suppressed: dict[str, str] = {}
+merchant_opt_out: set[str] = set()
+merchant_auto_replies: dict[str, dict[str, Any]] = {}
+merchant_action_memory: dict[str, dict[str, Any]] = {}
+category_arm_pool: dict[str, dict[str, list[float]]] = {}
+
+
+class ContextBody(BaseModel):
+    scope: str
+    context_id: str
+    version: int
+    payload: dict[str, Any]
+    delivered_at: str | None = None
+
+
+class TickBody(BaseModel):
+    now: str
+    available_triggers: list[str] = Field(default_factory=list)
+    limit: int = 20
+
+
+class ReplyBody(BaseModel):
+    conversation_id: str
+    merchant_id: str | None = None
+    customer_id: str | None = None
+    from_role: str
+    message: str
+    received_at: str | None = None
+    turn_number: int = 1
+
+
+@app.exception_handler(RequestValidationError)
+async def validation_exception_handler(request: Request, exc: RequestValidationError):
+    return JSONResponse(
+        status_code=400,
+        content={
+            "accepted": False,
+            "reason": "malformed",
+            "details": exc.errors(),
+            "path": request.url.path,
+        },
+    )
+
+
+@app.get("/v1/healthz")
+async def healthz() -> dict[str, Any]:
+    counts = {scope: 0 for scope in VALID_SCOPES}
+    for scope, _ in contexts:
+        counts[scope] = counts.get(scope, 0) + 1
+    return {
+        "status": "ok",
+        "uptime_seconds": int(time() - START),
+        "contexts_loaded": counts,
+        "conversations": len(conversations),
+    }
+
+
+@app.get("/v1/metadata")
+async def metadata() -> dict[str, Any]:
+    return {
+        "team_name": os.getenv("TEAM_NAME", "Vera Rubric Decision Engine"),
+        "team_members": [os.getenv("TEAM_MEMBER", "Mokshagna")],
+        "model": os.getenv("OPENAI_MODEL", "none-runtime-deterministic"),
+        "approach": "FastAPI stateful bot with CAR normalization, JITAI classification, B=MAP engagement gating, prospect/Cialdini framing, deterministic Tree-of-Thoughts/Best-of-N scoring, constitutional audit, empirical action priors, and optional validated LLM copy polish",
+        "runtime_llm_required": False,
+        "optional_llm_copy_polish": bool(os.getenv("OPENAI_API_KEY")),
+        "offline_openrouter_calibration": "available via scripts/geval_calibrate.py; never required by live /v1/tick",
+        "contact_email": os.getenv("CONTACT_EMAIL", "mokshagnak004@gmail.com"),
+        "version": "1.1.0",
+        "submitted_at": os.getenv("SUBMITTED_AT", _now_iso()),
+    }
+
+
+@app.post("/v1/context")
+async def push_context(body: ContextBody):
+    if body.scope not in VALID_SCOPES:
+        return JSONResponse(
+            status_code=400,
+            content={"accepted": False, "reason": "invalid_scope", "details": f"scope must be one of {sorted(VALID_SCOPES)}"},
+        )
+
+    key = (body.scope, body.context_id)
+    current = contexts.get(key)
+    if current and current["version"] > body.version:
+        return JSONResponse(
+            status_code=409,
+            content={"accepted": False, "reason": "stale_version", "current_version": current["version"]},
+        )
+    if current and current["version"] == body.version:
+        return {
+            "accepted": True,
+            "ack_id": f"ack_{body.context_id}_v{body.version}",
+            "stored_at": current.get("stored_at", _now_iso()),
+            "idempotent": True,
+        }
+
+    contexts[key] = {"version": body.version, "payload": body.payload, "stored_at": _now_iso()}
+    return {"accepted": True, "ack_id": f"ack_{body.context_id}_v{body.version}", "stored_at": contexts[key]["stored_at"]}
+
+
+@app.post("/v1/tick")
+async def tick(body: TickBody) -> dict[str, Any]:
+    actions: list[dict[str, Any]] = []
+    trigger_ids = body.available_triggers or [context_id for scope, context_id in contexts if scope == "trigger"]
+    limit = max(1, min(20, int(body.limit or 20)))
+    ranked = sorted(
+        (_trigger_record(tid) for tid in trigger_ids),
+        key=lambda item: _trigger_score(item[1]) if item else -999,
+        reverse=True,
+    )
+
+    for item in ranked:
+        if not item or len(actions) >= limit:
+            continue
+        trigger_id, trigger = item
+        merchant_id = trigger.get("merchant_id") or trigger.get("payload", {}).get("merchant_id")
+        customer_id = trigger.get("customer_id") or trigger.get("payload", {}).get("customer_id")
+        suppression_key = _safe_suppression_key(trigger, merchant_id, body.now)
+        if not merchant_id or merchant_id in merchant_opt_out:
+            continue
+        trigger_version = str(contexts.get(("trigger", trigger_id), {}).get("version", "0"))
+        if suppressed.get(suppression_key) == trigger_version:
+            continue
+        if _is_expired(trigger, body.now):
+            continue
+
+        merchant = _payload("merchant", merchant_id)
+        if not merchant:
+            continue
+        merchant = {**merchant, "__vera_memory": _merchant_memory_snapshot(merchant_id)}
+        category = _payload("category", merchant.get("category_slug") or trigger.get("payload", {}).get("category"))
+        if not category:
+            continue
+        customer = _payload("customer", customer_id) if customer_id else None
+        if customer_id and not customer:
+            continue
+
+        composed = compose(category, merchant, trigger, customer)
+        if composed.get("cta") == "none" and trigger.get("scope") == "customer":
+            continue
+        if _merchant_has_recent_body(merchant_id, composed.get("body", "")):
+            _record_response(merchant_id, "no_reply")
+            continue
+
+        conversation_id = make_conversation_id(merchant_id, trigger_id, customer_id)
+        if conversation_id in conversations and conversations[conversation_id].get("ended"):
+            continue
+
+        action = {
+            "conversation_id": conversation_id,
+            "merchant_id": merchant_id,
+            "customer_id": customer_id,
+            "send_as": composed["send_as"],
+            "trigger_id": trigger_id,
+            "template_name": _template_name(composed["send_as"], trigger.get("kind")),
+            "template_params": _template_params(composed["body"]),
+            "body": composed["body"],
+            "cta": composed["cta"],
+            "suppression_key": suppression_key,
+            "rationale": composed["rationale"],
+            "decision_plan": composed.get("decision_plan", {}),
+        }
+        suppressed[suppression_key] = trigger_version
+        conversations[conversation_id] = {
+            "merchant_id": merchant_id,
+            "customer_id": customer_id,
+            "trigger_id": trigger_id,
+            "action_arm": composed.get("decision_plan", {}).get("action_arm", _template_name(composed["send_as"], trigger.get("kind"))),
+            "turns": [{"from": "vera", "body": composed["body"], "ts": body.now}],
+            "auto_reply_count": 0,
+            "last_auto_reply": None,
+            "last_body": composed["body"],
+            "ended": False,
+        }
+        _record_action_sent(merchant_id, conversations[conversation_id]["action_arm"])
+        actions.append(action)
+
+    return {"actions": actions}
+
+
+@app.post("/v1/reply")
+async def reply(body: ReplyBody) -> dict[str, Any]:
+    conv = conversations.setdefault(
+        body.conversation_id,
+        {
+            "merchant_id": body.merchant_id,
+            "customer_id": body.customer_id,
+            "trigger_id": None,
+            "turns": [],
+            "auto_reply_count": 0,
+            "last_auto_reply": None,
+            "last_body": "",
+            "ended": False,
+        },
+    )
+    conv["merchant_id"] = conv.get("merchant_id") or body.merchant_id
+    conv["customer_id"] = conv.get("customer_id") or body.customer_id
+    if conv.get("ended"):
+        return {
+            "action": "end",
+            "rationale": "Conversation was already closed; refusing to send another message on the same conversation_id.",
+        }
+    conv.setdefault("turns", []).append({"from": body.from_role, "body": body.message, "ts": body.received_at or _now_iso()})
+
+    lower = (body.message or "").lower()
+    merchant_id = body.merchant_id or conv.get("merchant_id")
+    if is_auto_reply(body.message):
+        if conv.get("last_auto_reply") == body.message:
+            conv["auto_reply_count"] = int(conv.get("auto_reply_count", 0)) + 1
+        else:
+            conv["auto_reply_count"] = max(1, int(conv.get("auto_reply_count", 0)))
+        conv["last_auto_reply"] = body.message
+        if merchant_id:
+            mx_auto = merchant_auto_replies.setdefault(merchant_id, {"last": None, "count": 0})
+            if mx_auto.get("last") == body.message:
+                mx_auto["count"] = int(mx_auto.get("count", 0)) + 1
+            else:
+                mx_auto["last"] = body.message
+                mx_auto["count"] = 1
+            conv["auto_reply_count"] = max(int(conv.get("auto_reply_count", 0)), int(mx_auto.get("count", 0)))
+
+    merchant = _payload("merchant", merchant_id)
+    trigger = _payload("trigger", conv.get("trigger_id")) or {}
+    result = reply_to_message(body.message, conv, merchant, trigger)
+
+    if result.get("action") == "send" and result.get("body") == conv.get("last_body"):
+        result = {"action": "wait", "wait_seconds": 1800, "rationale": "Avoiding repeated body in the same conversation."}
+
+    if result.get("action") == "end":
+        conv["ended"] = True
+        if merchant_id and is_stop_or_hostile(lower):
+            merchant_opt_out.add(merchant_id)
+            _record_response(merchant_id, "stop")
+        elif merchant_id:
+            _record_response(merchant_id, "end")
+    elif result.get("action") == "send":
+        conv["last_body"] = result.get("body", "")
+        conv.setdefault("turns", []).append({"from": "vera", "body": result.get("body"), "ts": _now_iso()})
+        if merchant_id:
+            _record_response(merchant_id, "commitment" if is_commitment(lower) else "reply")
+    elif merchant_id and is_auto_reply(body.message):
+        _record_response(merchant_id, "auto_reply")
+    elif merchant_id:
+        _record_response(merchant_id, "reply")
+
+    return result
+
+
+@app.post("/v1/teardown")
+async def teardown() -> dict[str, Any]:
+    contexts.clear()
+    conversations.clear()
+    suppressed.clear()
+    merchant_opt_out.clear()
+    merchant_auto_replies.clear()
+    merchant_action_memory.clear()
+    category_arm_pool.clear()
+    return {"status": "ok", "cleared": True, "at": _now_iso()}
+
+
+def _payload(scope: str, context_id: str | None) -> dict[str, Any] | None:
+    if not context_id:
+        return None
+    record = contexts.get((scope, context_id))
+    return record.get("payload") if record else None
+
+
+def _trigger_record(trigger_id: str) -> tuple[str, dict[str, Any]] | None:
+    trigger = _payload("trigger", trigger_id)
+    if not trigger:
+        return None
+    return trigger_id, trigger
+
+
+def _trigger_score(trigger: dict[str, Any]) -> int:
+    score = int(trigger.get("urgency", 1)) * 10
+    kind = trigger.get("kind", "")
+    merchant_id = trigger.get("merchant_id") or trigger.get("payload", {}).get("merchant_id")
+    merchant = _payload("merchant", merchant_id)
+    category = _payload("category", merchant.get("category_slug")) if merchant else None
+    customer_id = trigger.get("customer_id") or trigger.get("payload", {}).get("customer_id")
+    customer = _payload("customer", customer_id) if customer_id else None
+    proxy = expected_trigger_score(category, merchant, trigger, customer) if merchant and category else 0
+    score += proxy
+    if trigger.get("scope") == "customer":
+        score += 12
+    if kind in {"supply_alert", "regulation_change", "active_planning_intent", "perf_dip", "renewal_due"}:
+        score += 10
+    if kind in {"curious_ask_due", "festival_upcoming", "milestone_reached"}:
+        score -= 2
+    return score
+
+
+def _safe_suppression_key(trigger: dict[str, Any], merchant_id: str, now_value: str) -> str:
+    raw = str(trigger.get("suppression_key") or "").strip()
+    kind = str(trigger.get("kind") or "generic").strip() or "generic"
+    trigger_id = str(trigger.get("id") or "").strip()
+    if raw and raw not in {kind, f"{merchant_id}:{kind}", f"{kind}:{merchant_id}"}:
+        return raw
+    date_part = (str(trigger.get("expires_at") or now_value).split("T")[0]) or "undated"
+    unique = trigger_id or str(abs(hash(json_fingerprint(trigger.get("payload", {})))))
+    return f"{merchant_id}:{kind}:{date_part}:{unique}"
+
+
+def json_fingerprint(value: Any) -> str:
+    try:
+        import json
+        return json.dumps(value, sort_keys=True, separators=(",", ":"))
+    except TypeError:
+        return str(value)
+
+
+def _is_expired(trigger: dict[str, Any], now_value: str) -> bool:
+    expires = trigger.get("expires_at")
+    if not expires:
+        return False
+    try:
+        exp = datetime.fromisoformat(expires.replace("Z", "+00:00"))
+        now = datetime.fromisoformat(now_value.replace("Z", "+00:00"))
+    except ValueError:
+        return False
+    return exp < now
+
+
+def _template_name(send_as: str, kind: str | None) -> str:
+    prefix = "merchant" if send_as == "merchant_on_behalf" else "vera"
+    safe_kind = (kind or "generic").replace("-", "_")
+    return f"{prefix}_{safe_kind}_v1"
+
+
+def _template_params(body: str) -> list[str]:
+    if len(body) <= 160:
+        return [body]
+    return [body[:120].strip(), body[120:360].strip()]
+
+
+def _merchant_has_recent_body(merchant_id: str, body: str) -> bool:
+    if not body:
+        return False
+    for conv in conversations.values():
+        if conv.get("merchant_id") == merchant_id and conv.get("last_body") == body and not conv.get("ended"):
+            return True
+    return False
+
+
+def _merchant_memory_snapshot(merchant_id: str) -> dict[str, Any]:
+    memory = merchant_action_memory.get(merchant_id, {})
+    merchant = _payload("merchant", merchant_id) or {}
+    category = merchant.get("category_slug", "")
+    return {
+        "last_action_type": memory.get("last_action_type", ""),
+        "last_response_intent": memory.get("last_response_intent", ""),
+        "repeated_action_count": int(memory.get("repeated_action_count", 0)),
+        "no_reply_count": int(memory.get("no_reply_count", 0)),
+        "action_sequence": list(memory.get("action_sequence", []))[-5:],
+        "response_sequence": list(memory.get("response_sequence", []))[-5:],
+        "reflection_note": memory.get("reflection_note", ""),
+        "category_arm_priors": _category_arm_priors(category),
+    }
+
+
+def _record_action_sent(merchant_id: str, action_arm: str) -> None:
+    memory = merchant_action_memory.setdefault(
+        merchant_id,
+        {"action_sequence": [], "response_sequence": [], "repeated_action_count": 0, "no_reply_count": 0},
+    )
+    if memory.get("last_action_type") == action_arm:
+        memory["repeated_action_count"] = int(memory.get("repeated_action_count", 0)) + 1
+    else:
+        memory["repeated_action_count"] = 1
+    memory["last_action_type"] = action_arm
+    memory["last_response_intent"] = memory.get("last_response_intent", "")
+    sequence = list(memory.get("action_sequence", []))
+    sequence.append(action_arm)
+    memory["action_sequence"] = sequence[-8:]
+
+
+def _record_response(merchant_id: str, intent: str) -> None:
+    memory = merchant_action_memory.setdefault(
+        merchant_id,
+        {"action_sequence": [], "response_sequence": [], "repeated_action_count": 0, "no_reply_count": 0},
+    )
+    memory["last_response_intent"] = intent
+    if intent in {"auto_reply", "no_reply"}:
+        memory["no_reply_count"] = int(memory.get("no_reply_count", 0)) + 1
+        memory["reflection_note"] = "Previous action met auto/no reply; shorten CTA and switch away from repeated action."
+    elif intent in {"commitment", "reply"}:
+        memory["no_reply_count"] = 0
+        memory["reflection_note"] = "Previous action got engagement; keep concrete artifact handoff and avoid asking another broad question."
+    elif intent == "stop":
+        memory["reflection_note"] = "Merchant opted out; do not send further messages."
+    sequence = list(memory.get("response_sequence", []))
+    sequence.append(intent)
+    memory["response_sequence"] = sequence[-8:]
+    _record_category_reward(merchant_id, str(memory.get("last_action_type") or ""), intent)
+
+
+def _record_category_reward(merchant_id: str, action_arm: str, intent: str) -> None:
+    if not action_arm:
+        return
+    merchant = _payload("merchant", merchant_id) or {}
+    category = merchant.get("category_slug")
+    if not category:
+        return
+    reward = {
+        "commitment": 0.95,
+        "reply": 0.7,
+        "end": 0.25,
+        "auto_reply": 0.2,
+        "no_reply": 0.2,
+        "stop": 0.0,
+    }.get(intent, 0.5)
+    pool = category_arm_pool.setdefault(category, {})
+    values = list(pool.get(action_arm, []))
+    values.append(reward)
+    pool[action_arm] = values[-20:]
+
+
+def _category_arm_priors(category: str) -> dict[str, float]:
+    pool = category_arm_pool.get(category, {})
+    priors: dict[str, float] = {}
+    for arm, rewards in pool.items():
+        if rewards:
+            priors[arm] = round(sum(rewards) / len(rewards), 3)
+    return priors
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")

bot.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+from app.composer import compose as _compose
+
+
+def compose(category: dict, merchant: dict, trigger: dict, customer: dict | None = None) -> dict:
+    """Offline challenge contract: deterministic compose(category, merchant, trigger, customer?)."""
+    return _compose(category, merchant, trigger, customer)
+

challenge-brief.md

@@ -0,0 +1,544 @@
+# magicpin AI Challenge — Build a Merchant AI Assistant ("Vera")
+
+**Status**: Brief — designed to be loaded as standalone context in a fresh AI session.
+**Last updated**: 2026-04-26
+**Audience**: Challenge participants + the AI judge that will evaluate submissions.
+
+> **Read me first** — this document is fully self-contained. A reader (human or LLM) starting cold should be able to understand the company, the product, the challenge, the framework, the dataset, and the evaluation rubric without needing any other reference.
+
+---
+
+## 1. The challenge in one sentence
+
+> Build an AI chatbot that engages and assists merchants on WhatsApp the way **Vera** (magicpin's merchant-AI assistant) does — but better. Same base dataset for every participant. AI judges the outcome.
+
+---
+
+## 2. About magicpin (background, ~30 sec read)
+
+magicpin is one of India's largest local-commerce platforms — a network of ~100,000 merchant partners across 50+ Indian cities (restaurants, salons, gyms, dentists, retailers, car dealers, etc.). Customers discover merchants on the magicpin app/web, transact, and earn cashback. Merchants benefit from visibility, walk-ins, and online orders.
+
+magicpin runs a marketing-assistant product called **Vera** that talks to merchants over WhatsApp, helps them grow their Google Business Profile (GBP), runs campaigns for them, and answers customer questions on their behalf. Vera is the product you're rebuilding.
+
+---
+
+## 3. About Vera (the product you're rebuilding)
+
+### What Vera does today
+- Talks to ~6,000-10,000 merchants per day over WhatsApp
+- Helps them improve their Google Business Profile (photos, hours, posts, reviews)
+- Runs marketing campaigns for them (festival, news, local events)
+- Recommends pricing, offers, and content
+- Answers customers' questions about merchants on their behalf
+
+### Live engagement shape (real numbers — Apr 23-25, 2026)
+
+| Metric | Apr 23 | Apr 24 | Apr 25 |
+|---|---:|---:|---:|
+| Merchants who engaged with Vera | 6,917 | 10,158 | 5,181 |
+| Total messages mx ↔ Vera | 34,022 | 47,651 | 23,712 |
+| Avg messages per engaged merchant | 4.9 | 4.7 | 4.6 |
+| Customers who engaged with Vera | 720 | 707 | 681 |
+| Unique merchants customers asked about | 580 | 514 | 466 |
+| Total messages cx ↔ Vera | 3,713 | 4,839 | 4,695 |
+| Avg messages per customer | 5.2 | 6.8 | 6.9 |
+
+### Today's biggest pain points (your opportunities to outperform Vera)
+
+1. **Auto-reply pollution**: 40-70% of "merchant replies" are the merchant's own WhatsApp Business canned auto-reply ("Thank you for contacting…"). Production Vera detects this but burns 2-3 turns each time. **Better detection + faster routing wins**.
+2. **Intent-handoff failures**: When a merchant says "I want to join," production Vera often goes back to qualifying questions instead of starting the action. **Better intent detection wins**.
+3. **Generic copy**: discount-style offers ("10% off") rarely engage Indian merchants. Service+price ("Haircut @ ₹99", "Dental Cleaning @ ₹299") works better. **Compelling, category-correct copy wins**.
+4. **Low engagement frequency**: Functional nudges (renewal due, profile incomplete) are inherently rare. To engage merchants 3-5×/week needs *curiosity-driven* and *knowledge-driven* conversations, not just reminder-style. **Diversified conversation portfolio wins**.
+
+---
+
+## 4. The 4-context framework (what your bot must work with)
+
+Every message Vera sends — whether to the merchant or the merchant's customer — is composed from **four context layers**. Your bot will receive these as structured input and must produce the next message.
+
+```
+your_bot.compose(category, merchant, trigger, customer?) → message
+```
+
+### 4.1 CategoryContext
+
+Slow-changing knowledge pack about *the kind of business this is*. Shared across all merchants in the vertical.
+
+```python
+@dataclass
+class CategoryContext:
+    slug: str                          # "dentists", "salons", "restaurants", ...
+    offer_catalog: list[OfferTemplate] # canonical service+price patterns for this vertical
+    voice: VoiceProfile                # tone, allowed vocabulary, taboos
+    peer_stats: PeerStats              # benchmarks: avg rating, avg reviews, typical CTR
+    digest: list[DigestItem]           # weekly research / compliance / trend items, source-cited
+    patient_content_library: list[ContentItem]  # content the merchant can reshare with customers
+    seasonal_beats: list[SeasonalBeat] # e.g., "exam-stress bruxism spikes Nov-Feb"
+    trend_signals: list[TrendSignal]   # e.g., "clear aligners Delhi searches +62% YoY"
+```
+
+**Example for `dentists`**:
+- voice: technical terms welcome ("fluoride varnish at 3-month recall"), legal taboos ("cure", "guaranteed"), peer tone not hype
+- offer_catalog: `["Dental Cleaning @ ₹299", "Free Consultation", "Teeth Whitening @ ₹1,499"]`
+- peer_stats: `{avg_rating: 4.4, avg_reviews: 62, avg_ctr: 0.030}` (South Delhi solo practices)
+- digest: this week's items from JIDA / DCI / Dental Tribune India / IDA Delhi calendar
+- seasonal_beats: `[{month: "Nov-Feb", note: "exam-stress bruxism spike"}, {month: "Oct-Dec", note: "wedding whitening peak"}]`
+
+### 4.2 MerchantContext
+
+The specific business's current state. Refreshed daily for performance, real-time for conversation history.
+
+```python
+@dataclass
+class MerchantContext:
+    merchant_id: str
+    identity: Identity                # name, place_id, locality, city, verified, languages
+    subscription: Subscription        # status, days_remaining, plan
+    performance: PerformanceSnapshot  # views/calls/CTR/leads/directions, 30d + 7d deltas
+    offers: list[MerchantOffer]       # active + paused offers from their catalog
+    conversation_history: ConversationHistory  # last N turns w/ Vera, w/ engagement tags
+    customer_aggregate: CustomerAggregate  # active count, lapsed count, retention %
+    signals: list[DerivedSignal]      # "stale_posts", "ctr_below_peer", "dormant", ...
+```
+
+**Running example — Dr. Meera's Dental Clinic**:
+- identity: name="Dr. Meera's Dental Clinic", city="Delhi", locality="Lajpat Nagar", verified=true
+- subscription: status="active", days_remaining=82, plan="Pro"
+- performance (30d): views=2410, calls=18, directions=45, ctr=0.021
+- offers: `["Dental Cleaning @ ₹299"]` active; `["Deep Cleaning @ ₹499"]` expired 2mo ago
+- customer_aggregate: 540 unique patients YTD, 78 lapsed >180 days, 38% 6mo retention
+- signals: `["stale_posts" (last post 22d ago), "ctr_below_peer_median" (peer median 0.030)]`
+
+### 4.3 TriggerContext
+
+The *event* that prompts this message right now. Every message must have one.
+
+```python
+@dataclass
+class TriggerContext:
+    id: str
+    scope: Literal["merchant", "customer"]
+    kind: str                # "research_digest", "recall_due", "perf_spike", ...
+    source: Literal["external", "internal"]
+    payload: dict
+    urgency: int             # 1-5
+    suppression_key: str     # for dedup
+    expires_at: datetime
+```
+
+**External triggers** (happen outside the merchant's account):
+- `festival_upcoming` (Diwali in 4 days)
+- `weather_heatwave` (42°C today in Delhi)
+- `local_news_event` (Mumbai-Pune expressway closed 3h)
+- `category_research_digest_release` (JIDA Oct issue dropped)
+- `regulation_change` (DCI radiograph dose limit revised)
+- `competitor_opened` (new dentist 1.3km away on GBP)
+- `category_trend_movement` ("clear aligners Delhi" searches +62%)
+
+**Internal triggers** (happen within the merchant's data):
+- `perf_spike` (yesterday's views +28% vs avg)
+- `perf_dip` (calls dropped 40% week-over-week)
+- `milestone_reached` (crossed 100 reviews)
+- `dormant_with_vera` (no merchant message in 14 days)
+- `customer_lapsed_soft` (a customer's 6mo recall window opens)
+- `appointment_tomorrow` (booking exists for next day)
+- `review_theme_emerged` (3 reviews this week mention "wait time")
+- `scheduled_recurring` (weekly Friday curious-ask cadence)
+
+**Example trigger for Dr. Meera**:
+```json
+{
+  "id": "trg_2026_04_26_research_digest_dentists",
+  "scope": "merchant",
+  "kind": "research_digest",
+  "source": "external",
+  "payload": {
+    "category": "dentists",
+    "top_item": {
+      "title": "3-mo fluoride recall cuts caries recurrence 38% better than 6-mo",
+      "source": "JIDA Oct 2026, p.14",
+      "trial_n": 2100,
+      "patient_segment": "high-risk adults"
+    }
+  },
+  "urgency": 2,
+  "suppression_key": "research:dentists:2026-W17",
+  "expires_at": "2026-05-03T00:00:00Z"
+}
+```
+
+### 4.4 CustomerContext (optional — only for customer-facing messages)
+
+When the bot sends a message *on behalf of the merchant* to one of the merchant's own customers, this is populated.
+
+```python
+@dataclass
+class CustomerContext:
+    customer_id: str
+    merchant_id: str           # which merchant this customer belongs to
+    identity: CustomerIdentity # name, phone, language preference
+    relationship: Relationship # first_visit, last_visit, visits_total, services_received
+    state: Literal["new", "active", "lapsed_soft", "lapsed_hard", "churned"]
+    preferences: Preferences   # preferred_time, channel, opt-in scope
+    consent: Consent           # when + how they opted in to merchant outreach
+```
+
+**Example — Priya, a patient of Dr. Meera**:
+- identity: name="Priya", phone="<redacted>", language_pref="hi-en mix"
+- relationship: first_visit="2025-11-04", last_visit="2026-05-12", visits_total=4, services=["cleaning", "cleaning", "whitening", "cleaning"]
+- state: "lapsed_soft" (5mo since last visit)
+- preferences: weekday evening slots (derived from booking history)
+- consent: opted in via merchant on 2025-11-04, scope=["recall_reminders", "appointment_reminders"]
+
+---
+
+## 5. The composition you must implement
+
+```
+def compose(
+    category: CategoryContext,
+    merchant: MerchantContext,
+    trigger: TriggerContext,
+    customer: Optional[CustomerContext] = None
+) -> ComposedMessage:
+    """
+    Returns:
+        body              — the WhatsApp message body
+        cta               — the call-to-action (binary YES/STOP, open-ended, none)
+        send_as           — "vera" (merchant-facing) or "merchant_on_behalf" (customer-facing)
+        suppression_key   — for dedup
+        rationale         — short explanation of why this message, what it should achieve
+    """
+```
+
+### Constraints your bot must respect
+
+1. **WhatsApp 24h session window** — the *first* outbound to a merchant or customer must use a pre-approved template (use any sensible template structure with `{{1}}/{{2}}/…` parameters; we won't actually call Meta). Subsequent messages within 24h of a merchant reply can be free-form.
+2. **Body length** — no hard cap; keep it concise and context-appropriate for readability.
+3. **Single primary CTA** — binary choice (YES/STOP) for action triggers; no CTA acceptable for pure-information triggers.
+4. **URLs** — allowed when they add clear value to the merchant.
+5. **Specificity wins** — anchor on a verifiable fact the merchant can check (number, date, headline). "X% off" is generic; "Haircut @ ₹99" is specific.
+6. **Voice match** — peer/colleague tone, not promotional; technical vocabulary OK if category allows.
+7. **Hindi-English code-mix is fine** — and often preferred for Indian merchant audiences. Match the merchant's language.
+8. **Don't fabricate** — if data isn't in the contexts, don't invent it. No fake offers, no fake research citations, no fake competitor names.
+
+---
+
+## 6. The base dataset (provided to every participant)
+
+Every participant gets the same JSON dataset:
+
+```
+dataset/
+├── categories/
+│   ├── dentists.json
+│   ├── salons.json
+│   ├── restaurants.json
+│   ├── gyms.json
+│   └── pharmacies.json        # 5 fully-populated CategoryContexts
+├── merchants/
+│   ├── m_001_drmeera_dentist_delhi.json
+│   ├── m_002_studio11_salon_hyderabad.json
+│   ├── m_003_pizzajunction_restaurant_delhi.json
+│   ├── ...                    # 50 fully-populated MerchantContexts (10 per category)
+│   └── m_050_*.json
+├── customers/
+│   ├── c_001_priya_for_m001.json
+│   ├── c_002_rohit_for_m001.json
+│   ├── ...                    # 200 customer profiles, distributed across merchants
+│   └── c_200_*.json
+└── triggers/
+    ├── trg_external_001_diwali.json
+    ├── trg_external_002_heatwave_delhi.json
+    ├── trg_internal_001_recall_due_priya.json
+    ├── trg_internal_002_perf_spike_m003.json
+    ├── ...                    # 100 sample triggers covering all kinds
+    └── trg_100_*.json
+```
+
+Each trigger references one merchant (via `payload.merchant_id`) and optionally one customer. Participants can compose any (category, merchant, trigger) or (category, merchant, trigger, customer) combination from this set.
+
+A canonical "submission test set" is **30 specific (merchant, trigger) pairs** that all participants must produce a message for. This gives the AI judge a like-for-like comparison.
+
+---
+
+## 7. What participants submit
+
+A single Python module + a JSONL file:
+
+### 7.1 `bot.py` (your code)
+
+```python
+def compose(category: dict, merchant: dict, trigger: dict, customer: dict | None) -> dict:
+    """
+    Inputs are the dicts loaded from the dataset JSON.
+    Return a dict with keys: body, cta, send_as, suppression_key, rationale.
+    Free to use any LLM, any prompting strategy, any retrieval.
+    Must be deterministic given the same inputs (set temperature=0 if using LLMs).
+    Must complete in < 30s per call.
+    """
+    ...
+```
+
+### 7.2 `submission.jsonl` (30 lines, one per test pair)
+
+```json
+{"test_id": "T01", "body": "Hi Dr. Meera, JIDA's Oct issue ...", "cta": "open_ended", "send_as": "vera", "suppression_key": "...", "rationale": "..."}
+```
+
+### 7.3 `README.md` (1 page max)
+
+Briefly: your approach, what tradeoffs you made, what additional context would have helped you most.
+
+### 7.4 Optional: `conversation_handlers.py`
+
+If you want to demonstrate multi-turn handling (replying to merchant responses), implement:
+
+```python
+def respond(state: ConversationState, merchant_message: str) -> dict:
+    """Given the conversation so far + the merchant's latest message, produce the reply."""
+    ...
+```
+
+Multi-turn capability is a tiebreaker, not a requirement.
+
+---
+
+## 8. Evaluation methodology (how AI judges)
+
+Submissions are scored by an LLM judge across **5 dimensions**, each 0-10. Total = 50.
+
+| Dimension | What the judge looks for |
+|---|---|
+| **Specificity** | Does the message anchor on a concrete, verifiable fact from the contexts (number, date, headline, peer stat)? Penalty for generic "10% off" / "increase your sales" framings. |
+| **Category fit** | Does the voice, vocabulary, and offer format match the category? Dentist messages should sound clinical-peer, not retail-promo. |
+| **Merchant fit** | Is the message personalized to *this specific* merchant's state (their numbers, their offers, their conversation history)? Is the language preference honored? |
+| **Trigger relevance** | Does the message clearly communicate *why now* — the specific trigger that prompted it? Not "you should improve your profile" generically. |
+| **Engagement compulsion** | Would a real merchant want to reply? Does it use one or more compulsion levers (curiosity, social proof, loss aversion, effort externalization, single-binary CTA)? |
+
+### The twist — post-submission context injection
+
+After submissions close, the judge injects **additional context that participants didn't see**:
+- New `digest` items added to category contexts (recent research/news/regulations)
+- Updated `performance` snapshots on merchant contexts (their numbers shifted)
+- New `triggers` (events that happened "after" submission)
+- For 5 of the 30 test pairs: a populated `CustomerContext` is added (testing customer-facing capability)
+
+The judge then asks the bot to produce **follow-up messages** for these enriched scenarios. Bots that adapt well to new context (without hallucinating, without going off-voice) score higher.
+
+### Replay test
+
+For the 10 highest-scoring submissions, the judge runs a **simulated multi-turn replay**:
+- Judge plays the merchant.
+- Bot composes the first message.
+- Judge generates a plausible merchant reply (sometimes engaged, sometimes auto-reply, sometimes a hard "not interested", sometimes a curveball question).
+- Bot must respond.
+- 3-5 turns deep.
+- Judge scores how the conversation flows: did the bot detect auto-reply? Did it route action requests correctly? Did it know when to gracefully exit?
+
+---
+
+## 9. Reference: real Vera conversation patterns (anonymized excerpts)
+
+These are real conversations from production Vera — provided as reference, not as the bar to clear (you should aim higher).
+
+### Pattern A — Real intent, real value exchange (the gold standard)
+
+```
+[USER]  Hi Vera. Please update my google profile.
+[VERA]  Hi! Priya, Vera se bol rahi hoon. Aapka Google profile abhi 62.5% complete hai
+        — description, website aur business hours missing hain. Kya aap yeh details
+        share kar sakte hain taaki main sab update kar sakun?
+[USER]  Ok please check & update the profile.
+[VERA]  Done! Maine aapka Google profile update kar diya hai:
+        - Business hours — daily 9 AM se 10 PM
+        - Description — restaurant description add kar diya
+        - Google Post — ek welcome post bhi publish kar diya
+[USER]  I can't see my profile is updated yet. It is showing temporarily closed.
+[VERA]  Google ke changes mein 24-48 ghante lagte hain. Kyunki aapka profile abhi
+        unverified hai, Google har update review karta hai. Tab tak main aur
+        cheezein add kar sakti hoon...
+```
+**What's right**: Hindi-English mix, specific numbers (62.5%, 24-48 ghante), Vera does work + reports back, handles uncertainty honestly.
+
+### Pattern B — Auto-reply detection + graceful exit
+
+```
+[VERA]     Studio11 Family Salon ka Google profile check kar rahi thi — aapki 4.9★
+           rating hai 298 reviews ke saath... business description missing hai.
+[MERCHANT] Aapki jaankari ke liye bahut-bahut shukriya. Main aapki yeh sabhi baatein
+           aur sujhaav hamari team tak pahuncha deti hoon.   ← merchant's auto-reply
+[VERA]     Samajh gayi. Team tak pahunchane se pehle, kya aap khud dekhna chahingi
+           ki exact kya missing hai Google pe? 2 minute ka kaam hai. Chalega?
+[MERCHANT] Aapki madad ke liye shukriya, lekin main ek automated assistant hoon...
+[VERA]     Koi baat nahi, samajh gayi. Main owner/manager se directly connect kar
+           lungi. Aapka salon accha chal raha hai — best wishes! 🙂
+```
+**What's right**: Vera tried once after detecting auto-reply, then stopped wasting turns. Polite exit.
+
+### Pattern C — Strong specificity hook
+
+```
+[VERA] Quick nudge: your dashboard shows 6,777 missed searches in Sector 14
+       for makeup services — people are looking but not finding you. Want me
+       to show how your listing would appear?
+```
+**What's right**: "6,777" is verifiable; "Sector 14" is local; "missed searches" frames as loss aversion.
+
+### Pattern D — Intent-handoff failure (DON'T do this)
+
+```
+[MERCHANT] Mujhe magicpin judrna hai.   ← "I want to join magicpin" — clear intent
+[VERA]     Badhiya! Aapke liye simple rakhti hoon: agar aapko 10-15 naye customers
+           regular milne lagen to helpful hoga na?   ← went back to qualifying
+```
+**What's wrong**: Merchant said yes; Vera asked another qualification question. Lost momentum. Your bot should detect explicit intent and route to action immediately.
+
+---
+
+## 10. Compulsion levers — what makes merchants reply
+
+These are the levers that drive engagement. Use one or more per message:
+
+1. **Specificity / verifiability** — concrete number, date, headline, source citation
+2. **Loss aversion** — "you're missing X" / "before this window closes"
+3. **Social proof** — "3 dentists in your locality did Y this month"
+4. **Effort externalization** — "I've drafted X — just say go" / "5-min setup"
+5. **Curiosity** — "want to see who?" / "want the full list?"
+6. **Reciprocity** — "I noticed Y about your account, thought you'd want to know"
+7. **Asking the merchant** — "what's your most-asked treatment this week?"
+8. **Single binary commitment** — Reply YES / STOP, not multi-choice
+
+Production Vera's biggest miss is **#3 social proof** and **#7 asking the merchant** — these families barely fire today and would unlock a lot of engagement.
+
+---
+
+## 11. Anti-patterns the judge will penalize
+
+- Generic offers ("Flat 30% off") when service+price is available ("Haircut @ ₹99")
+- Multiple CTAs in one message ("Reply YES for X, NO for Y, MAYBE for Z")
+- Buried call-to-action (the "what to do" should land in the last sentence)
+- Promotional tone ("AMAZING DEAL!") for categories that need clinical/peer voice (dentists, doctors, lawyers)
+- Hallucinated data (citing a "JIDA paper" not in the context, naming a competitor not in the context)
+- Long preambles ("I hope you're doing well. I'm reaching out today to…")
+- Re-introducing yourself after the first message
+- Ignoring the language preference ("hi-en mix" merchant getting pure English)
+- Sending the same message verbatim that was sent before (anti-repetition)
+
+---
+
+## 12. Open challenges (these are intentional — extra credit)
+
+1. **Detect auto-replies** vs. real merchant replies and route differently. (Hint: same message verbatim 3+ times = auto-reply.)
+2. **Handle intent transitions** — when the merchant says "yes I want to join" / "let's do it" / "go ahead", switch from pitch mode to action mode immediately.
+3. **Multi-turn cadence planning** — within a 24h session window, what's the optimal sequence of nudges?
+4. **Language detection per turn** — merchant might switch from English to Hindi mid-conversation.
+5. **Knowing when to stop** — gracefully exit when the merchant signals not-interested or after 3 unanswered nudges.
+
+---
+
+## 13. Suggested approach (one of many — you decide)
+
+The challenge is LLM-agnostic. Most participants will:
+
+1. **Build a prompt template** that takes the 4 contexts as structured input and asks an LLM to compose. Likely best with a frontier model (Claude / GPT / Gemini / DeepSeek).
+2. **Add a routing layer** — different trigger kinds may want different prompt variants (research-digest framing vs recall-reminder framing vs perf-dip framing).
+3. **Add post-LLM validation** — check the output for CTA shape and language match. Re-prompt if it fails.
+4. **For multi-turn**: maintain a small conversation state with what was already said, what the merchant signaled, what the next best move is.
+
+You can also use retrieval (e.g., embed the category digest items, retrieve the most relevant for the trigger), tool use (e.g., let the LLM call a "lookup peer stat" function), or any other architecture.
+
+---
+
+## 14. Logistics (placeholders — fill in for your run)
+
+- **Eligibility**: <e.g., undergrad/grad CS or related, India-based or remote>
+- **Team size**: solo or pairs
+- **Submission window**: <e.g., 14 days from launch>
+- **Deliverables**: as in §7
+- **Compute reimbursement**: <e.g., ₹X for API costs>
+- **Prizes**: <top 1 / top 3 / honorable mentions>
+- **Selection outcomes**: <e.g., top N invited to final on-site round>
+
+---
+
+## 15. Dataset privacy + ethics
+
+- The base dataset is **synthetic but realistic** — generated from anonymized templates, no real PII.
+- Merchant names in samples are altered; phone numbers redacted.
+- Participants must **not scrape** real magicpin / Google data; must not impersonate magicpin in any external test.
+- All bot output is for the challenge only; not for real merchant outreach.
+
+---
+
+## 16. What gets shared with the judge in the new session
+
+When a fresh AI session starts to evaluate submissions, the judge gets:
+
+1. **This brief** (the entire document you're reading) — full context.
+2. **The base dataset** (categories/, merchants/, customers/, triggers/).
+3. **The post-submission context injections** (new digest items, updated performance, new triggers, optional customer contexts).
+4. **The submitted bot artifacts** (`bot.py`, `submission.jsonl`, optional `conversation_handlers.py`, `README.md`).
+5. **The 5-dimension rubric** (§8) and the replay-test instructions.
+
+That's everything the judge needs. No prior context from this session is required.
+
+---
+
+## Appendix A — Composition example (so the judge knows what good looks like)
+
+**Inputs**:
+- Category: `dentists` (voice=peer/clinical, peer_stats.avg_ctr=0.030, digest top item="JIDA Oct trial: 3-mo fluoride recall cuts caries 38% better")
+- Merchant: Dr. Meera, Lajpat Nagar Delhi, CTR 2.1% (below peer), high-risk-adult patient cohort, last Vera touch 2 days ago (engaged)
+- Trigger: `research_digest_release` (urgency 2, external)
+- Customer: none
+
+**Good composed message** (the bar):
+
+```
+Dr. Meera, JIDA's Oct issue landed. One item relevant to your high-risk adult
+patients — 2,100-patient trial showed 3-month fluoride recall cuts caries
+recurrence 38% better than 6-month. Worth a look (2-min abstract). Want me to
+pull it + draft a patient-ed WhatsApp you can share?  — JIDA Oct 2026 p.14
+```
+
+**Why it scores well**:
+- Specificity: "2,100-patient", "38% better", "JIDA Oct 2026 p.14"
+- Category fit: clinical vocabulary, source citation, peer tone
+- Merchant fit: "your high-risk adult patients" (derived from customer aggregate)
+- Trigger relevance: explicitly references the digest as the reason for messaging
+- Engagement compulsion: curiosity ("Worth a look"), reciprocity ("I'll pull it for you"), low-friction CTA
+
+---
+
+## Appendix B — Customer-facing composition example
+
+**Inputs**:
+- Category: `dentists` (customer-facing voice rules: no "guaranteed", no medical claims)
+- Merchant: Dr. Meera (active offer "Dental Cleaning @ ₹299", available slots Wed 6pm + Thu 5pm)
+- Trigger: `recall_due` (scope=customer, urgency=3, internal)
+- Customer: Priya (lapsed_soft, weekday-evening preference, hi-en mix language)
+
+**Good composed message** (sent from merchant's WA number, drafted by bot):
+
+```
+Hi Priya, Dr. Meera's clinic here 🦷 It's been 5 months since your last visit —
+your 6-month cleaning recall is due. Apke liye 2 slots ready hain: Wed 6 Nov,
+6pm ya Thu 7 Nov, 5pm. ₹299 cleaning + complimentary fluoride. Reply 1 for
+Wed, 2 for Thu, or tell us a time that works.
+```
+
+**Why it scores well**:
+- send_as = `merchant_on_behalf` (correctly attributed)
+- Category fit: clinical, no overclaims
+- Merchant fit: real catalog price, real open slots
+- Trigger relevance: explicitly names the 6-month recall
+- Customer fit: name, language mix, evening preference honored, multi-choice slot offer (allowed for booking flows)
+
+---
+
+## End of brief
+
+This document is everything the next session needs. Save it as `challenge-brief.md` and load it into the judge session along with the dataset and the submitted bot artifacts.
+
+Good luck. Build something better than today's Vera.

challenge-testing-brief.md

@@ -0,0 +1,557 @@
+# magicpin AI Challenge — Testing & Evaluation Brief
+
+**Status**: Companion to `challenge-brief.md`. Defines the technical contract between candidate bots and magicpin's judging system.
+**Last updated**: 2026-04-26
+**Audience**: Candidates building the bot + magicpin engineers running the harness.
+
+> **Read this with `challenge-brief.md`** — that brief defines what the bot must do (the 4-context framework, composition contract, evaluation rubric). This brief defines *how the bot is tested* (HTTP API, judge harness, scoring touchpoints).
+
+---
+
+## 1. The high-level model
+
+```
+   ┌──────────────────────────┐                    ┌────────────────────────────┐
+   │  magicpin Judge Harness  │                    │  Candidate Bot (your code) │
+   │  (LLM playing merchant + │                    │  HTTP server, public URL   │
+   │   context injector +     │ ──── HTTP/JSON ──► │  Stateful per-conversation │
+   │   scorer)                │ ◄──── HTTP/JSON ── │                            │
+   └──────────────────────────┘                    └────────────────────────────┘
+```
+
+Two information flows:
+
+1. **Judge → Bot**: pushes incremental context across all 4 dimensions (category, merchant, trigger, customer) over time. Mimics how production data updates flow into Vera.
+2. **Bot → Judge**: the bot proactively initiates conversations, and the judge plays the merchant (or customer) role, replying realistically. The bot must handle the full conversation.
+
+The bot is **stateful** (must remember context pushed earlier and conversations in flight). The judge is the source of truth for what's happened.
+
+---
+
+## 2. Endpoints the candidate must expose
+
+All endpoints are HTTPS, JSON in/out, UTF-8. Total surface: **5 endpoints**.
+
+### 2.1 `POST /v1/context` — receive a context push
+
+The judge calls this whenever it wants the bot to know about new or updated context. Could be the initial base dataset, or an incremental update mid-test.
+
+**Request body**:
+```json
+{
+  "scope": "category" | "merchant" | "customer" | "trigger",
+  "context_id": "dentists" | "m_001_drmeera" | "c_001_priya" | "trg_2026_04_26_research_digest",
+  "version": 3,
+  "payload": { /* the full context object — see §3 */ },
+  "delivered_at": "2026-04-26T10:00:00Z"
+}
+```
+
+**Behavior**:
+- **Idempotent** by `(context_id, version)`. Re-posting the same version is a no-op.
+- A higher `version` for the same `context_id` **replaces** the prior version atomically.
+- Bot must persist context until the test ends. Storing in memory is fine; just don't restart between calls.
+
+**Response (200)**:
+```json
+{ "accepted": true, "ack_id": "ack_abc123", "stored_at": "2026-04-26T10:00:00.123Z" }
+```
+
+**Response (409)** — version conflict (you already have a higher version):
+```json
+{ "accepted": false, "reason": "stale_version", "current_version": 5 }
+```
+
+**Response (400)** — malformed:
+```json
+{ "accepted": false, "reason": "invalid_scope", "details": "..." }
+```
+
+### 2.2 `POST /v1/tick` — periodic wake-up; bot can initiate
+
+The judge calls this every **N seconds of simulated time** (default: every 5 simulated minutes). The bot inspects its current context state and decides whether to send any proactive messages.
+
+**Request body**:
+```json
+{
+  "now": "2026-04-26T10:30:00Z",
+  "available_triggers": ["trg_2026_04_26_research_digest", "trg_2026_04_26_recall_priya"]
+}
+```
+
+`available_triggers` is a hint listing trigger context_ids the judge considers "active right now". The bot can use any subset (or none).
+
+**Response (200)**:
+```json
+{
+  "actions": [
+    {
+      "conversation_id": "conv_001",
+      "merchant_id": "m_001_drmeera",
+      "customer_id": null,
+      "send_as": "vera",
+      "trigger_id": "trg_2026_04_26_research_digest",
+      "template_name": "vera_research_digest_v1",
+      "template_params": ["Dr. Meera", "JIDA Oct issue", "..."],
+      "body": "Dr. Meera, JIDA's Oct issue landed...",
+      "cta": "open_ended",
+      "suppression_key": "research:dentists:2026-W17",
+      "rationale": "External research digest with merchant-relevant clinical anchor; merchant is a dentist with high-risk-adult patient cohort"
+    }
+  ]
+}
+```
+
+`actions` MAY be an empty list — the bot is free to decide nothing's worth sending this tick.
+
+`conversation_id`:
+- If you want to start a new conversation, generate any unique string.
+- Reusing an existing `conversation_id` is invalid here — use `/v1/reply` to continue an existing conversation.
+
+### 2.3 `POST /v1/reply` — receive a reply from the simulated merchant/customer
+
+The judge calls this with the merchant's (or customer's) reply to a previous bot message. The bot must respond synchronously with its next move.
+
+**Request body**:
+```json
+{
+  "conversation_id": "conv_001",
+  "merchant_id": "m_001_drmeera",
+  "customer_id": null,
+  "from_role": "merchant",
+  "message": "Yes, send me the abstract",
+  "received_at": "2026-04-26T10:45:00Z",
+  "turn_number": 2
+}
+```
+
+**Response (200)** — three valid `action` values:
+
+```json
+{ "action": "send",
+  "body": "Sending now — also drafted a 90-sec patient-ed WhatsApp...",
+  "cta": "open_ended",
+  "rationale": "Honoring the merchant's accept; adding the next-best-step (patient-ed) as low-friction follow-on" }
+```
+
+```json
+{ "action": "wait",
+  "wait_seconds": 1800,
+  "rationale": "Merchant asked for time; back off 30 min" }
+```
+
+```json
+{ "action": "end",
+  "rationale": "Merchant said not interested; gracefully exiting conversation" }
+```
+
+The bot has **30 seconds** to respond. After 30s the judge marks this turn as `timeout` and proceeds.
+
+### 2.4 `GET /v1/healthz` — liveness probe
+
+**Response (200)**:
+```json
+{ "status": "ok", "uptime_seconds": 3600, "contexts_loaded": { "category": 5, "merchant": 50, "customer": 200, "trigger": 100 } }
+```
+
+The judge polls this every 60s during the test window. Three consecutive failures = bot disqualified for that test slot.
+
+### 2.5 `GET /v1/metadata` — bot identity
+
+**Response (200)**:
+```json
+{
+  "team_name": "Team Alpha",
+  "team_members": ["Alice", "Bob"],
+  "model": "claude-opus-4-7",
+  "approach": "single-prompt composer with retrieval over digest items",
+  "contact_email": "team@example.com",
+  "version": "1.2.0",
+  "submitted_at": "2026-04-26T08:00:00Z"
+}
+```
+
+---
+
+## 3. Context payload schemas (what the judge pushes to `/v1/context`)
+
+Each `scope` has a fixed payload shape. These mirror the dataclasses defined in `challenge-brief.md` §4.
+
+### 3.1 `scope: "category"`
+```json
+{
+  "slug": "dentists",
+  "offer_catalog": [{ "title": "Dental Cleaning @ ₹299", "value": "299", "audience": "new_user" }],
+  "voice": { "tone": "peer_clinical", "vocab_allowed": ["fluoride varnish", "caries"], "taboos": ["cure", "guaranteed"] },
+  "peer_stats": { "avg_rating": 4.4, "avg_reviews": 62, "avg_ctr": 0.030, "scope": "delhi_solo_practices" },
+  "digest": [
+    { "id": "d_2026W17_jida_fluoride", "kind": "research",
+      "title": "3-mo fluoride recall cuts caries 38% better than 6-mo",
+      "source": "JIDA Oct 2026, p.14", "trial_n": 2100, "patient_segment": "high_risk_adults",
+      "summary": "..." }
+  ],
+  "patient_content_library": [
+    { "id": "pc_001", "title": "3 things your teeth tell you about your heart", "channel": "whatsapp", "body": "..." }
+  ],
+  "seasonal_beats": [{ "month_range": "Nov-Feb", "note": "exam-stress bruxism spike" }],
+  "trend_signals": [{ "query": "clear aligners delhi", "delta_yoy": 0.62, "segment_age": "28-45" }]
+}
+```
+
+### 3.2 `scope: "merchant"`
+```json
+{
+  "merchant_id": "m_001_drmeera",
+  "category_slug": "dentists",
+  "identity": { "name": "Dr. Meera's Dental Clinic", "city": "Delhi", "locality": "Lajpat Nagar",
+                "place_id": "ChIJ...", "verified": true, "languages": ["en", "hi"] },
+  "subscription": { "status": "active", "plan": "Pro", "days_remaining": 82 },
+  "performance": {
+    "window_days": 30,
+    "views": 2410, "calls": 18, "directions": 45, "ctr": 0.021,
+    "delta_7d": { "views_pct": 0.18, "calls_pct": -0.05 }
+  },
+  "offers": [
+    { "id": "o_meera_001", "title": "Dental Cleaning @ ₹299", "status": "active" },
+    { "id": "o_meera_002", "title": "Deep Cleaning @ ₹499", "status": "expired" }
+  ],
+  "conversation_history": [
+    { "ts": "2026-04-24T10:00:00Z", "from": "vera", "body": "...", "engagement": "merchant_replied" }
+  ],
+  "customer_aggregate": { "total_unique_ytd": 540, "lapsed_180d_plus": 78, "retention_6mo_pct": 0.38 },
+  "signals": ["stale_posts:22d", "ctr_below_peer_median", "high_risk_adult_cohort"]
+}
+```
+
+### 3.3 `scope: "customer"`
+```json
+{
+  "customer_id": "c_001_priya",
+  "merchant_id": "m_001_drmeera",
+  "identity": { "name": "Priya", "phone_redacted": "<phone>", "language_pref": "hi-en mix" },
+  "relationship": {
+    "first_visit": "2025-11-04", "last_visit": "2026-05-12", "visits_total": 4,
+    "services_received": ["cleaning", "cleaning", "whitening", "cleaning"]
+  },
+  "state": "lapsed_soft",
+  "preferences": { "preferred_slots": "weekday_evening", "channel": "whatsapp" },
+  "consent": { "opted_in_at": "2025-11-04", "scope": ["recall_reminders", "appointment_reminders"] }
+}
+```
+
+### 3.4 `scope: "trigger"`
+```json
+{
+  "id": "trg_2026_04_26_research_digest_dentists",
+  "scope": "merchant",
+  "kind": "research_digest",
+  "source": "external",
+  "merchant_id": "m_001_drmeera",
+  "customer_id": null,
+  "payload": {
+    "category": "dentists",
+    "top_item_id": "d_2026W17_jida_fluoride"
+  },
+  "urgency": 2,
+  "suppression_key": "research:dentists:2026-W17",
+  "expires_at": "2026-05-03T00:00:00Z"
+}
+```
+
+For `scope: "customer"` triggers (e.g., `recall_due`), `customer_id` is populated.
+
+---
+
+## 4. The judge harness behavior — full lifecycle
+
+### Phase 1 — Warmup (T-15 min before scoring window opens)
+
+1. Judge calls `GET /v1/healthz` and `GET /v1/metadata` to verify the bot is reachable.
+2. Judge POSTs the **base dataset** to `/v1/context`:
+    - 5 category contexts
+    - 50 merchant contexts
+    - 200 customer contexts
+    - 0 triggers (triggers come during the test window)
+3. Judge waits 60s for the bot to settle, then re-checks `/healthz`.
+4. If `contexts_loaded` reflects all 255 base contexts, warmup passes.
+
+### Phase 2 — Test window (T0 to T0 + 60 simulated minutes)
+
+The judge advances simulated time in **5-minute ticks**. At each tick:
+
+1. Judge POSTs any new/updated contexts that "happened" during this tick (incremental updates).
+2. Judge calls `POST /v1/tick` with current simulated time + currently-active triggers.
+3. Bot returns `actions[]` — zero or more proactive sends.
+4. For each action:
+    - Judge logs it (with rationale).
+    - Judge invokes a sub-LLM playing the merchant/customer role.
+    - The sub-LLM replies with a plausible response (sometimes engaged, sometimes auto-reply, sometimes hard "no", sometimes a question).
+    - Judge POSTs that reply to `/v1/reply`.
+    - Bot returns next action — `send`, `wait`, or `end`.
+    - Repeat up to 5 turns or until bot ends.
+
+### Phase 3 — Adaptive context injection (interleaved during Phase 2)
+
+Between ticks, the judge injects **post-submission context** the bot didn't see during development:
+
+- New `digest` items (5 new research/compliance items per category context, posted as a new `version`)
+- Updated `performance` snapshots (10 merchants get new perf numbers — some spikes, some dips)
+- New `triggers` (15 new triggers spread across the test window)
+- For 5 specific merchants: a new `customer` context is pushed mid-test with a `recall_due` trigger 2 minutes later
+
+Bots that incorporate the new context in subsequent sends score higher. Bots that ignore it (sending stale composition) score lower. Bots that hallucinate (invent context that wasn't pushed) score lowest.
+
+### Phase 4 — Replay test (top 10 only)
+
+For the 10 highest-scoring bots from Phase 2, the judge runs **3 deep-dive scenarios** as standalone replays:
+
+1. **Auto-reply hell** — judge plays a merchant whose phone is on WA Business with a canned auto-reply; sends the same canned text 4 times in a row. Bot must detect and exit gracefully.
+2. **Intent transition** — judge plays an engaged merchant who, after 2 turns of qualification, says "ok let's do it". Bot must switch from qualifying to action immediately (not ask another qualifying question).
+3. **Hostile / off-topic** — judge plays a merchant who replies with abuse, then asks an unrelated question ("can you also help me file my GST?"). Bot must stay on-mission politely.
+
+Each replay: 5 turns, scored on conversation flow only.
+
+### Phase 5 — Scoring + report (T0 + 90 min)
+
+Judge aggregates:
+- Phase 2 scores (per the 5-dimension rubric in §8 of the main brief)
+- Phase 3 adaptation bonus (max +5 per dimension)
+- Phase 4 replay scores (top 10 only; max +30)
+- Operational penalties (timeouts, healthz failures, malformed responses; max -20)
+
+Sends each team a per-message scorecard with judge rationale.
+
+---
+
+## 5. Rate limits + timeouts
+
+| Limit | Value |
+|---|---|
+| Max requests/sec from judge to bot | 10 |
+| Per-call timeout (judge waits this long) | 30 s |
+| `/v1/context` payload size cap | 500 KB |
+| `/v1/tick` action count cap | 20 actions per tick |
+| Healthz failures before disqualification | 3 consecutive |
+| Total test window | 60 simulated minutes (real-time ~30-45 min) |
+
+If your bot needs more than 30s for `/v1/tick`, return an empty `actions: []` immediately and process work asynchronously — but you can't catch up later, so design for the budget.
+
+---
+
+## 6. Where to deploy
+
+Deploy your bot anywhere that gives you a **public URL**:
+- Any cloud (AWS, GCP, Azure, Render, Fly, Railway, Replit, …)
+- ngrok tunnel to localhost
+- Any hosting that exposes HTTP endpoints
+
+Requirements:
+- Must respond at the URL pattern `https://<your-host>/v1/*` (or `http://` for local testing)
+- Submit your public URL via the submission portal
+
+---
+
+## 7. Reference implementation skeleton
+
+A minimal-viable bot in ~80 lines of Python (FastAPI). Save as `bot.py`:
+
+```python
+import os, time
+from datetime import datetime
+from fastapi import FastAPI, Request, HTTPException
+from pydantic import BaseModel
+from typing import Any
+
+app = FastAPI()
+START = time.time()
+
+# In-memory stores (use Redis/SQLite for production-grade)
+contexts: dict[tuple[str, str], dict] = {}    # (scope, context_id) -> {version, payload}
+conversations: dict[str, list] = {}           # conversation_id -> [turns]
+
+
+@app.get("/v1/healthz")
+async def healthz():
+    counts = {"category": 0, "merchant": 0, "customer": 0, "trigger": 0}
+    for (scope, _), _ in contexts.items():
+        counts[scope] = counts.get(scope, 0) + 1
+    return {"status": "ok", "uptime_seconds": int(time.time() - START), "contexts_loaded": counts}
+
+
+@app.get("/v1/metadata")
+async def metadata():
+    return {"team_name": "Team Alpha", "team_members": ["Alice"], "model": "gpt-4o-mini",
+            "approach": "single-prompt composer", "contact_email": "alice@example.com",
+            "version": "0.1.0", "submitted_at": "2026-04-26T08:00:00Z"}
+
+
+class CtxBody(BaseModel):
+    scope: str
+    context_id: str
+    version: int
+    payload: dict[str, Any]
+    delivered_at: str
+
+@app.post("/v1/context")
+async def push_context(body: CtxBody):
+    key = (body.scope, body.context_id)
+    cur = contexts.get(key)
+    if cur and cur["version"] >= body.version:
+        return {"accepted": False, "reason": "stale_version", "current_version": cur["version"]}
+    contexts[key] = {"version": body.version, "payload": body.payload}
+    return {"accepted": True, "ack_id": f"ack_{body.context_id}_v{body.version}",
+            "stored_at": datetime.utcnow().isoformat() + "Z"}
+
+
+class TickBody(BaseModel):
+    now: str
+    available_triggers: list[str] = []
+
+@app.post("/v1/tick")
+async def tick(body: TickBody):
+    actions = []
+    for trg_id in body.available_triggers:
+        trg = contexts.get(("trigger", trg_id), {}).get("payload")
+        if not trg: continue
+        merchant_id = trg.get("merchant_id")
+        merchant = contexts.get(("merchant", merchant_id), {}).get("payload")
+        category = contexts.get(("category", merchant.get("category_slug")), {}).get("payload") if merchant else None
+        if not (merchant and category): continue
+        # YOUR COMPOSER GOES HERE — call your LLM with the 4 contexts
+        body_text = f"Hi {merchant['identity']['name']}, ..."  # replace with real composition
+        actions.append({
+            "conversation_id": f"conv_{merchant_id}_{trg_id}",
+            "merchant_id": merchant_id, "customer_id": None,
+            "send_as": "vera", "trigger_id": trg_id,
+            "template_name": "vera_generic_v1",
+            "template_params": [merchant['identity']['name'], "...", "..."],
+            "body": body_text, "cta": "open_ended",
+            "suppression_key": trg.get("suppression_key", ""),
+            "rationale": "Composed from category+merchant+trigger"
+        })
+    return {"actions": actions}
+
+
+class ReplyBody(BaseModel):
+    conversation_id: str
+    merchant_id: str | None = None
+    customer_id: str | None = None
+    from_role: str
+    message: str
+    received_at: str
+    turn_number: int
+
+@app.post("/v1/reply")
+async def reply(body: ReplyBody):
+    conversations.setdefault(body.conversation_id, []).append({"from": body.from_role, "msg": body.message})
+    # YOUR REPLY-COMPOSER GOES HERE
+    return {"action": "send", "body": "Got it, here's what's next...", "cta": "open_ended",
+            "rationale": "acknowledged + advanced"}
+```
+
+Run: `uvicorn bot:app --host 0.0.0.0 --port 8080`
+
+This is a working skeleton. The composer logic is stubbed — replace the `# YOUR COMPOSER GOES HERE` blocks with your LLM call.
+
+---
+
+## 9. Local self-test before submitting
+
+Magicpin provides a `judge_simulator.py` that runs a mini version of the harness against your endpoint. Use it during development:
+
+```bash
+export BOT_URL=http://localhost:8080
+python judge_simulator.py
+```
+
+Each scenario prints the judge's prompts + your bot's responses + a mock score. Iterate until you're happy, then submit your URL.
+
+---
+
+## 10. Failure modes the judge handles
+
+| Failure | Judge behavior | Penalty |
+|---|---|---|
+| `/v1/healthz` returns non-200 (3× in a row) | Mark bot offline; skip remaining ticks | -10 (operational) |
+| `/v1/tick` times out (>30s) | Skip this tick's actions; continue | -1 per timeout |
+| `/v1/reply` times out | Mark turn as `bot_silent`; judge plays next merchant turn after 30s | -1 per timeout |
+| Bot returns malformed JSON | Logged, scored as 0 for that action | -2 per malformed |
+| Bot returns `action: send` with empty body | Treated as malformed | -2 |
+| Bot returns the same body verbatim it sent before in the same conversation | Anti-repetition flag | -2 per repeat |
+
+---
+
+## 11. Security + privacy
+
+- All payloads are synthetic — no real PII.
+- Bots **must not** transmit any payload data outside the test environment (no calls to non-LLM external APIs with merchant/customer fields).
+- Bots **may** use commercial LLM APIs (OpenAI, Anthropic, Google, DeepSeek, etc.) — those are necessary for composition.
+- Bots **must not** persist context data after the test ends. magicpin will issue a `POST /v1/teardown` (optional) at end of test; on receiving it, wipe state.
+
+---
+
+## 12. Pre-flight checklist for candidates
+
+Before submitting:
+
+- [ ] Endpoint reachable from the public internet (HTTPS or HTTP)
+- [ ] All 5 endpoints implemented and returning correct schemas
+- [ ] `/v1/context` is idempotent on `(scope, context_id, version)`
+- [ ] `/v1/tick` returns within 30s even if it has nothing to send (returns `{"actions": []}`)
+- [ ] `/v1/reply` returns within 30s for any conversation
+- [ ] Bot persists context across calls (in-memory is fine; no restarts during test)
+- [ ] `judge_simulator.py` passes locally with non-zero scores
+- [ ] Submitted URL via submission portal
+- [ ] Compute budget set (rate limits, LLM API quota, etc.) so the bot survives 60-min test
+
+---
+
+## 13. What the judge logs (for transparency)
+
+Every test produces a per-team artifact:
+
+```
+results/<team_name>/
+├── conversations.jsonl      # all turns, both sides, with timestamps
+├── context_pushes.jsonl     # every context push, with bot's ack
+├── scoring.json             # 5-dimension scores per action + per conversation
+├── timeline.html            # visual timeline of the test window
+├── replay_*.jsonl           # phase 4 replay transcripts (top 10 only)
+└── final_report.md          # aggregated score + judge's qualitative feedback
+```
+
+Candidates receive their own artifact bundle within 48h of the test. Top scorers' bundles (with consent) become reference material for the next cohort.
+
+---
+
+## 14. FAQ
+
+**Q: Can the bot use external tools / function calling during composition?**
+Yes. Your LLM can call any tool you implement internally. You can't call out to non-LLM external APIs that receive merchant/customer payloads (privacy rule §11).
+
+**Q: What if my bot needs more than 30s to compose a really good message?**
+Two options: (a) speed it up; (b) at `/v1/tick`, return immediately with `{"actions": []}` and skip the cycle. Don't try to background-process and return late — late responses are dropped.
+
+**Q: Can I send multiple messages in one tick to the same merchant?**
+Yes, but only one `action` per `(merchant_id, conversation_id)` pair per tick. Use a follow-up tick to send more.
+
+**Q: Does the judge see my bot's `rationale` field?**
+Yes — it's included in the scoring rubric ("did the rationale match the actual output?"). High-quality rationales help the judge interpret edge cases generously.
+
+**Q: What language do replies have to be in?**
+Match the merchant's `identity.languages` field. Default is English. Hindi-English code-mix is encouraged where the language pref says `hi`.
+
+**Q: Can my bot refuse to send when nothing's worth saying?**
+Yes — return `{"actions": []}` from `/v1/tick`. Restraint is rewarded; spam is penalized.
+
+**Q: What if the judge pushes a context for a merchant I've never seen before, mid-conversation?**
+Treat it as a normal new merchant. The bot should be ready for any context to arrive at any time.
+
+**Q: Is there a way to query the judge for clarification mid-test?**
+No. The bot has only the contexts it's been pushed. This is intentional — production Vera doesn't get clarifications either.
+
+---
+
+## End of testing brief
+
+The two briefs together (`challenge-brief.md` for *what to build* and this one for *how it's tested*) are the complete spec. A team should be able to read both end-to-end in 30 minutes and start coding.

dataset/categories/dentists.json

@@ -0,0 +1,129 @@
+{
+  "slug": "dentists",
+  "display_name": "Dentists",
+  "voice": {
+    "tone": "peer_clinical",
+    "register": "respectful_collegial",
+    "code_mix": "hindi_english_natural",
+    "vocab_allowed": [
+      "fluoride varnish", "scaling", "caries", "occlusion", "bruxism",
+      "endodontic", "periodontal", "implant", "aligner", "veneer",
+      "OPG", "IOPA", "RCT", "CAD/CAM", "zirconia", "PFM"
+    ],
+    "vocab_taboo": [
+      "guaranteed", "100% safe", "completely cure", "miracle", "best in city",
+      "doctor approved" ,"FDA-approved (use only when actually applicable)"
+    ],
+    "salutation_examples": ["Dr. {first_name}", "Doc"],
+    "tone_examples": [
+      "Worth a look — JIDA Oct 2026 p.14",
+      "This one likely affects your high-risk adult cohort",
+      "If your case-mix is mostly cosmetic, may not be relevant"
+    ]
+  },
+  "offer_catalog": [
+    { "id": "den_001", "title": "Dental Cleaning @ ₹299", "value": "299", "audience": "new_user", "type": "service_at_price" },
+    { "id": "den_002", "title": "Free Consultation", "value": "0", "audience": "new_user", "type": "free_service" },
+    { "id": "den_003", "title": "Teeth Whitening @ ₹1,499", "value": "1499", "audience": "new_user", "type": "service_at_price" },
+    { "id": "den_004", "title": "Root Canal @ ₹2,999 (single rooted)", "value": "2999", "audience": "new_user", "type": "service_at_price" },
+    { "id": "den_005", "title": "Free Smile Analysis + Digital Scan", "value": "0", "audience": "new_user", "type": "free_service" },
+    { "id": "den_006", "title": "Aligner Consultation @ ₹499", "value": "499", "audience": "new_user", "type": "service_at_price" },
+    { "id": "den_007", "title": "Pediatric Dental Checkup @ ₹199", "value": "199", "audience": "new_user", "type": "service_at_price" },
+    { "id": "den_008", "title": "Annual Family Dental Plan @ ₹4,999", "value": "4999", "audience": "repeat_user", "type": "membership" }
+  ],
+  "peer_stats": {
+    "scope": "metro_solo_practices_2026",
+    "avg_rating": 4.4,
+    "avg_review_count": 62,
+    "avg_views_30d": 1820,
+    "avg_calls_30d": 12,
+    "avg_directions_30d": 38,
+    "avg_ctr": 0.030,
+    "avg_photos": 9,
+    "avg_post_freq_days": 14,
+    "retention_6mo_pct": 0.42
+  },
+  "digest": [
+    {
+      "id": "d_2026W17_jida_fluoride",
+      "kind": "research",
+      "title": "3-month fluoride varnish recall outperforms 6-month for high-risk adult caries",
+      "source": "JIDA Oct 2026, p.14",
+      "trial_n": 2100,
+      "patient_segment": "high_risk_adults",
+      "summary": "Multi-center Indian trial shows 38% lower caries recurrence with 3-month vs 6-month recall in adults with active decay history. No effect in low-risk patients.",
+      "actionable": "Reassess recall interval for adults flagged high-risk in your charting"
+    },
+    {
+      "id": "d_2026W17_dci_radiograph",
+      "kind": "compliance",
+      "title": "DCI revised radiograph dose limits effective 2026-12-15",
+      "source": "Dental Council of India circular 2026-11-04",
+      "summary": "Maximum dose per IOPA exposure drops from 1.5 mSv to 1.0 mSv. E-speed film passes at the new limit; D-speed does not. Digital RVG sensors unaffected.",
+      "actionable": "Audit your X-ray setup before Dec 15; document E-speed or RVG in your SOPs"
+    },
+    {
+      "id": "d_2026W17_ida_webinar",
+      "kind": "cde",
+      "title": "IDA Delhi: Digital impressions — 2026 state of the art",
+      "source": "IDA Delhi chapter calendar",
+      "date": "2026-05-02T19:00:00+05:30",
+      "credits": 2,
+      "summary": "Speaker: Dr. R. Mehta. Covers Primescan 2, Trios 5, and CAD/CAM workflow ROI for solo practices.",
+      "actionable": "Free for IDA members; ₹500 for non-members"
+    },
+    {
+      "id": "d_2026W17_aligner_trend",
+      "kind": "trend",
+      "title": "Clear aligner consultations searches +62% YoY in metros",
+      "source": "Practo + Google Trends, Apr 2026",
+      "summary": "'Clear aligners near me' query growth concentrated in 28-45 age band; female-skewed. Pricing pressure as DIY aligner brands hit the market.",
+      "actionable": "Position your supervised-aligner offer against DIY in your GBP description"
+    },
+    {
+      "id": "d_2026W17_e_max_press",
+      "kind": "tech",
+      "title": "Dentsply launches IPS e.max Press for zirconia crowns in India at ₹3,200/unit (Delhi labs)",
+      "source": "Dentsply India launch note 2026-04-18",
+      "summary": "Better aesthetic, similar fracture resistance to standard zirconia. Two Delhi labs (Dental Direkt, Siam Dental) confirmed stocking. Shared-lease scanner deals available.",
+      "actionable": "Worth comparing if crown work is >15% of monthly revenue"
+    }
+  ],
+  "patient_content_library": [
+    {
+      "id": "pc_oral_heart",
+      "title": "3 things your teeth tell you about your heart",
+      "channel": "whatsapp",
+      "length_seconds": 90,
+      "body": "Periodontal disease shares inflammation pathways with cardiovascular disease. Bleeding gums, persistent bad breath, and loose teeth in middle age are early signals. A 2024 meta-analysis of 18 studies found periodontal patients had 22% higher CVD events. The simplest action: scaling every 6 months reduces both gum and inflammation markers."
+    },
+    {
+      "id": "pc_kid_brushing",
+      "title": "Why your child resists brushing — and what to try this week",
+      "channel": "whatsapp",
+      "length_seconds": 60,
+      "body": "Most resistance under age 7 is sensory, not behavioural. Try: (1) a softer brush than you think necessary, (2) brushing in front of a mirror so they see what's happening, (3) two minutes of music as the timer. If resistance persists past 4 weeks, it's worth a pediatric dental consult."
+    },
+    {
+      "id": "pc_aligner_vs_braces",
+      "title": "Aligners or braces? What I tell my patients in their 30s",
+      "channel": "whatsapp",
+      "length_seconds": 75,
+      "body": "Aligners work for ~70% of cases — mild-to-moderate crowding, spacing, and minor rotations. Braces still win for severe rotations, deep bites, and skeletal corrections. The tell: if you can't keep aligners on for 22 hours/day, braces are the safer choice."
+    }
+  ],
+  "seasonal_beats": [
+    { "month_range": "Nov-Feb", "note": "exam-stress bruxism spike — ortho consults rise 30% in 18-24 cohort" },
+    { "month_range": "Oct-Dec", "note": "wedding whitening peak — bookings 2x baseline; ladies' segment dominant" },
+    { "month_range": "Jan", "note": "new-year resolution surge — annual check-up bookings +40%" },
+    { "month_range": "Apr-Jun", "note": "school holiday window — pediatric appointments +50%" }
+  ],
+  "trend_signals": [
+    { "query": "clear aligners delhi", "delta_yoy": 0.62, "segment_age": "28-45", "skew": "female" },
+    { "query": "teeth whitening price", "delta_yoy": 0.41, "segment_age": "all", "skew": "balanced" },
+    { "query": "dental implants near me", "delta_yoy": 0.18, "segment_age": "45-65", "skew": "male" },
+    { "query": "kids first dental visit", "delta_yoy": 0.27, "segment_age": "parents_25-40", "skew": "female" }
+  ],
+  "regulatory_authorities": ["Dental Council of India (DCI)", "Indian Dental Association (IDA)"],
+  "professional_journals": ["JIDA", "Indian Journal of Dental Research", "Dental Tribune India"]
+}

dataset/categories/gyms.json

@@ -0,0 +1,125 @@
+{
+  "slug": "gyms",
+  "display_name": "Gyms & Fitness",
+  "voice": {
+    "tone": "energetic_disciplined",
+    "register": "coach_to_member",
+    "code_mix": "english_primary_some_hindi",
+    "vocab_allowed": [
+      "footfall", "membership churn", "PT sessions", "PR (personal record)",
+      "1RM", "EMOM", "AMRAP", "split", "cut", "bulk", "BMR", "VO2max",
+      "functional", "HIIT", "CrossFit", "yoga", "pilates"
+    ],
+    "vocab_taboo": [
+      "guaranteed weight loss", "shred in 7 days", "miracle transformation",
+      "fastest results"
+    ],
+    "salutation_examples": ["Hi {first_name}", "{gym_name} team", "Coach"],
+    "tone_examples": [
+      "Quick check — your weekday 7-9pm slot has been at 90%+ capacity all month",
+      "Footfall pattern: April drop-off is normal; bookings recover by 2nd week May"
+    ]
+  },
+  "offer_catalog": [
+    { "id": "gym_001", "title": "3 FREE Trial Classes", "value": "0", "audience": "new_user", "type": "free_trial" },
+    { "id": "gym_002", "title": "First Month @ ₹499", "value": "499", "audience": "new_user", "type": "service_at_price" },
+    { "id": "gym_003", "title": "Personal Training Demo @ ₹199", "value": "199", "audience": "new_user", "type": "service_at_price" },
+    { "id": "gym_004", "title": "Annual Membership @ ₹14,999 (save ₹6,000)", "value": "14999", "audience": "new_user", "type": "service_at_price" },
+    { "id": "gym_005", "title": "Couple/Family Plan @ ₹999/month", "value": "999", "audience": "new_user", "type": "service_at_price" },
+    { "id": "gym_006", "title": "Free Body Composition Analysis", "value": "0", "audience": "all", "type": "free_service" },
+    { "id": "gym_007", "title": "Refer-a-friend: 1 month free for both", "value": "free_addon", "audience": "repeat_user", "type": "free_addon" },
+    { "id": "gym_008", "title": "Yoga + Strength Combo @ ₹1,499/month", "value": "1499", "audience": "new_user", "type": "service_at_price" }
+  ],
+  "peer_stats": {
+    "scope": "metro_neighbourhood_gyms_2026",
+    "avg_rating": 4.5,
+    "avg_review_count": 56,
+    "avg_views_30d": 1100,
+    "avg_calls_30d": 18,
+    "avg_directions_30d": 42,
+    "avg_ctr": 0.045,
+    "avg_photos": 16,
+    "avg_post_freq_days": 12,
+    "monthly_churn_pct": 0.08,
+    "trial_to_paid_pct": 0.32
+  },
+  "digest": [
+    {
+      "id": "d_2026W17_resolution_window",
+      "kind": "seasonal",
+      "title": "Post-Jan resolution window closing — last 2 weeks of high trial-walk-ins",
+      "source": "magicpin gym data, Apr 2026",
+      "summary": "Gym trial walk-ins spike Jan 1-15, taper through Mar; April-June hits the lowest acquisition window of the year. Most gyms over-spend on ads now; underspend in October pre-holiday window.",
+      "actionable": "Pause acquisition spend in May; double down Sept-Oct"
+    },
+    {
+      "id": "d_2026W17_pt_demand",
+      "kind": "trend",
+      "title": "Personal Training inquiries +38% YoY in 30-50 corporate cohort",
+      "source": "Multi-gym aggregate Apr 2026",
+      "summary": "Driven by health-check-up findings (rising HbA1c, BP, cholesterol). Demand is for 2x/week PT, not full-program. ₹3,000-5,000/month sweet spot.",
+      "actionable": "Package a '2x/week PT @ ₹3,499' option separate from full membership"
+    },
+    {
+      "id": "d_2026W17_yoga_studio_competition",
+      "kind": "compete",
+      "title": "Boutique yoga/pilates studios opening fast in metro neighbourhoods",
+      "source": "Industry watch Apr 2026",
+      "summary": "Reformer pilates studios at ₹6,000-8,000/month membership are pulling 30-45 women from traditional gyms. Don't compete on price; compete on coach quality + community.",
+      "actionable": "Add one yoga or pilates class to your weekly schedule if you don't have one"
+    },
+    {
+      "id": "d_2026W17_creatine_safety_bulletin",
+      "kind": "research",
+      "title": "ICMR creatine supplementation safety bulletin — adolescent guidance",
+      "source": "ICMR, Apr 2026",
+      "summary": "Creatine monohydrate at 3-5g/day deemed safe for healthy adults; cautioned against under-18 use without medical supervision. Reinforces what most coaches already practice.",
+      "actionable": "Update your store / counter recommendations; flag under-18 customers"
+    },
+    {
+      "id": "d_2026W17_class_schedule_optimization",
+      "kind": "tech",
+      "title": "Schedule density study — peak slots underutilized in mornings",
+      "source": "magicpin internal Apr 2026",
+      "summary": "Across 200+ partner gyms, 6-8am weekday slots run at 60% capacity vs 90%+ for 6-9pm. Adding a 7am class typically doesn't cannibalize evenings.",
+      "actionable": "Consider one new 7am class — yoga or HIIT pulls best in that slot"
+    }
+  ],
+  "patient_content_library": [
+    {
+      "id": "pc_first_30_days",
+      "title": "First 30 days at the gym — what actually changes",
+      "channel": "whatsapp",
+      "length_seconds": 60,
+      "body": "Week 1-2: nervous-system adaptation, lifts feel easier (not muscle gain — coordination). Week 3-4: small visible changes, sleep improves. Real strength/aesthetic changes start at week 8-12. Most people quit at week 3 expecting visible change. Trust the process."
+    },
+    {
+      "id": "pc_pt_or_solo",
+      "title": "PT or solo? A 5-question test",
+      "channel": "whatsapp",
+      "length_seconds": 45,
+      "body": "Solo if: you've trained before, you can read program structure, you don't get injured easily. PT if: you're new, recovering from injury, training for a specific event, or have inconsistent form. Hybrid (PT 1-2x/month + solo): the smartest middle path for most members."
+    },
+    {
+      "id": "pc_protein_basics",
+      "title": "How much protein do you actually need?",
+      "channel": "whatsapp",
+      "length_seconds": 50,
+      "body": "Sedentary adults: 0.8g/kg body weight. Active adults: 1.2-1.6g/kg. Strength training: 1.6-2.2g/kg. For a 70kg active person, that's 84-112g/day — roughly 4 fistful-portions of protein. Indian-veg diets often fall short; supplement with paneer, dal, tofu before adding powders."
+    }
+  ],
+  "seasonal_beats": [
+    { "month_range": "Jan", "note": "resolution surge — trial walk-ins 4x baseline; convert window" },
+    { "month_range": "Apr-Jun", "note": "lowest acquisition window — focus on retention, not acquisition" },
+    { "month_range": "Aug-Oct", "note": "wedding-prep + festival window — repeat clients return to shape up" },
+    { "month_range": "Nov-Dec", "note": "holiday slowdown — class density drops 25%; right time to renovate or pilot new programs" }
+  ],
+  "trend_signals": [
+    { "query": "gym near me", "delta_yoy": 0.05, "segment_age": "all", "skew": "balanced" },
+    { "query": "personal trainer cost", "delta_yoy": 0.38, "segment_age": "30-50", "skew": "balanced" },
+    { "query": "yoga classes near me", "delta_yoy": 0.42, "segment_age": "25-55", "skew": "female" },
+    { "query": "weight loss program", "delta_yoy": 0.28, "segment_age": "30-50", "skew": "female" }
+  ],
+  "regulatory_authorities": ["FSSAI (for supplement sales)", "Local Municipal Corp (premises)"],
+  "professional_journals": ["Indian Journal of Sports Medicine"]
+}

dataset/categories/pharmacies.json

@@ -0,0 +1,124 @@
+{
+  "slug": "pharmacies",
+  "display_name": "Pharmacies & Medical Stores",
+  "voice": {
+    "tone": "trustworthy_precise",
+    "register": "neighbourhood_pharmacist",
+    "code_mix": "hindi_english_natural",
+    "vocab_allowed": [
+      "OTC", "schedule H", "schedule X", "generic", "branded", "molecule",
+      "MRP", "expiry", "batch", "PCR retail", "pharmacist counsel"
+    ],
+    "vocab_taboo": [
+      "miracle cure", "guaranteed result", "100% safe", "doctor recommended (without disclosure)",
+      "best price (without supporting data)"
+    ],
+    "salutation_examples": ["Hi {pharmacist_name}", "{pharmacy_name} team"],
+    "tone_examples": [
+      "Quick check — your repeat-prescription customer count is up 18% this month",
+      "Heads up: a generic alternative for {molecule} just got approved — likely 30% lower MRP"
+    ]
+  },
+  "offer_catalog": [
+    { "id": "phr_001", "title": "Flat 20% OFF on medicines", "value": "20%", "audience": "new_user", "type": "percentage_discount" },
+    { "id": "phr_002", "title": "Free Home Delivery > ₹499", "value": "free_delivery", "audience": "new_user", "type": "free_addon" },
+    { "id": "phr_003", "title": "Annual Health Card @ ₹399 (15% off all year)", "value": "399", "audience": "repeat_user", "type": "membership" },
+    { "id": "phr_004", "title": "Free BP & Sugar Check", "value": "0", "audience": "all", "type": "free_service" },
+    { "id": "phr_005", "title": "Senior Citizen 15% OFF (60+ age)", "value": "15%", "audience": "senior", "type": "percentage_discount" },
+    { "id": "phr_006", "title": "Diabetic Care Combo: Glucometer + 50 strips @ ₹999", "value": "999", "audience": "new_user", "type": "service_at_price" },
+    { "id": "phr_007", "title": "Free Pharmacist Consultation (10 min)", "value": "0", "audience": "all", "type": "free_service" },
+    { "id": "phr_008", "title": "Subscription refill reminder + delivery (chronic Rx)", "value": "0", "audience": "repeat_user", "type": "free_service" }
+  ],
+  "peer_stats": {
+    "scope": "metro_neighbourhood_pharmacies_2026",
+    "avg_rating": 4.6,
+    "avg_review_count": 42,
+    "avg_views_30d": 1400,
+    "avg_calls_30d": 22,
+    "avg_directions_30d": 58,
+    "avg_ctr": 0.038,
+    "avg_photos": 6,
+    "avg_post_freq_days": 21,
+    "delivery_share_pct": 0.35,
+    "repeat_customer_pct": 0.62
+  },
+  "digest": [
+    {
+      "id": "d_2026W17_generic_metformin",
+      "kind": "supply",
+      "title": "Generic metformin SR price drop after 4 new approvals",
+      "source": "DGCI release Apr 2026",
+      "summary": "Three major Indian players got SR-formulation approval; wholesale price down 22% effective next month. Branded retail likely flat for now (margin will absorb).",
+      "actionable": "Audit your shelf — switching diabetic refills to generic now saves the patient ~₹120/month and improves your repeat-buy stickiness"
+    },
+    {
+      "id": "d_2026W17_schedule_h1_compliance",
+      "kind": "compliance",
+      "title": "FDA enforcement audit on Schedule H1 antibiotic dispensing — Q2",
+      "source": "FDA India inspector circular Apr 2026",
+      "summary": "Tighter Q2 audit cycle on H1 antibiotic dispensing — proper Rx capture, register entries, batch tracking. ₹50,000+ penalties for missing entries.",
+      "actionable": "Audit your H1 register; ensure pharmacist signature + Rx photocopy on file for every dispense in last 90 days"
+    },
+    {
+      "id": "d_2026W17_summer_demand",
+      "kind": "seasonal",
+      "title": "Summer demand shift: ORS, sunscreen, anti-fungal up 40%; cold/cough down 60%",
+      "source": "Multi-pharmacy aggregate Apr 2026",
+      "summary": "Standard April-Jun pattern: ORS sachets, sunscreen, anti-fungal creams, deodorant peak; respiratory medication tapers off. Restock + shelf-rearrange.",
+      "actionable": "Move ORS + sunscreen to counter visibility; cold/cough to back shelf"
+    },
+    {
+      "id": "d_2026W17_chronic_subscription",
+      "kind": "tech",
+      "title": "Chronic-Rx subscription retention 3.2x higher than walk-in",
+      "source": "magicpin pharmacy data Apr 2026",
+      "summary": "Pharmacies with WhatsApp-based refill reminder + auto-delivery for chronic patients see 88% 12-month retention vs 27% for walk-in-only chronic customers.",
+      "actionable": "Set up the WhatsApp reminder — covers diabetic, hypertensive, thyroid Rx"
+    },
+    {
+      "id": "d_2026W17_atorvastatin_recall",
+      "kind": "alert",
+      "title": "Voluntary recall: Specific atorvastatin batches by manufacturer X",
+      "source": "CDSCO alert Apr 2026",
+      "summary": "Two batches (numbers in alert) flagged for sub-potency. Customers should be informed; replacement available via distributor return chain. No safety risk for patients beyond suboptimal LDL control.",
+      "actionable": "Pull the batches; WhatsApp affected customers from your repeat-Rx list"
+    }
+  ],
+  "patient_content_library": [
+    {
+      "id": "pc_generic_branded",
+      "title": "Generic vs branded medicines — what's actually different?",
+      "channel": "whatsapp",
+      "length_seconds": 60,
+      "body": "The active molecule is identical and regulator-tested. Difference is in the binders, fillers, and brand markup. Generic is typically 40-60% cheaper. Two cases where brand may help: (1) very narrow-therapeutic-index drugs (some thyroid, blood thinners) where bioequivalence varies, (2) extended-release formulations. Otherwise, generic is the rational choice."
+    },
+    {
+      "id": "pc_storage",
+      "title": "Where to NOT store your medicines",
+      "channel": "whatsapp",
+      "length_seconds": 45,
+      "body": "Three places: (1) bathroom — humidity wrecks tablet integrity. (2) car glove box — temperature swings degrade most molecules in a month. (3) refrigerator door — temperature varies too much; use the main shelf if cold storage is needed. The kitchen at room temperature, away from sunlight, is best."
+    },
+    {
+      "id": "pc_summer_basics",
+      "title": "Summer first-aid: what every Indian household should have",
+      "channel": "whatsapp",
+      "length_seconds": 50,
+      "body": "Five items: ORS sachets (heat-stroke is sudden), broad-spectrum sunscreen SPF 50+ (apply 30 min before sun), anti-fungal cream (sweat triggers infections), Vaseline (chafing relief), and a thermometer. Skip energy drinks marketed as 'summer drinks' — sugar load is counterproductive when dehydrated."
+    }
+  ],
+  "seasonal_beats": [
+    { "month_range": "Apr-Jun", "note": "summer surge — ORS, sunscreen, anti-fungal, deodorant" },
+    { "month_range": "Jul-Aug", "note": "monsoon — anti-bacterial, anti-fungal, immunity supplements peak" },
+    { "month_range": "Oct-Nov", "note": "festival sweets → blood sugar spike — diabetic monitoring needs surge" },
+    { "month_range": "Dec-Jan", "note": "respiratory peak — cough/cold/anti-allergic 2x baseline" }
+  ],
+  "trend_signals": [
+    { "query": "medicine home delivery", "delta_yoy": 0.42, "segment_age": "all", "skew": "balanced" },
+    { "query": "generic medicine", "delta_yoy": 0.34, "segment_age": "30-65", "skew": "balanced" },
+    { "query": "diabetes care kit", "delta_yoy": 0.28, "segment_age": "40-65", "skew": "balanced" },
+    { "query": "blood pressure monitor", "delta_yoy": 0.18, "segment_age": "45-70", "skew": "balanced" }
+  ],
+  "regulatory_authorities": ["CDSCO", "State FDA", "Drug Controller General of India (DCGI)"],
+  "professional_journals": ["Pharmabiz", "ChemistryView India", "IPA Bulletin"]
+}

dataset/categories/restaurants.json

@@ -0,0 +1,118 @@
+{
+  "slug": "restaurants",
+  "display_name": "Restaurants & Cafes",
+  "voice": {
+    "tone": "warm_busy_practical",
+    "register": "fellow_operator",
+    "code_mix": "hindi_english_natural",
+    "vocab_allowed": [
+      "footfall", "covers", "AOV", "RPC", "table turnover", "reservations",
+      "GRO", "weekend brunch", "happy hour", "thali", "biryani", "tandoor"
+    ],
+    "vocab_taboo": [
+      "best food in city", "guaranteed packed house", "miracle marketing",
+      "viral guarantee"
+    ],
+    "salutation_examples": ["Hi {chef_or_owner_first_name}", "{restaurant_name} team"],
+    "tone_examples": [
+      "Quick one — IPL match nights have been 1.5x your weekday avg this season",
+      "Spotted: 'biryani delivery' searches in your sublocality up 28% this week"
+    ]
+  },
+  "offer_catalog": [
+    { "id": "res_001", "title": "Flat 30% OFF on total bill (limit ₹500)", "value": "30%", "audience": "new_user", "type": "percentage_discount" },
+    { "id": "res_002", "title": "Buy 1 Pizza Get 1 Free (Tue-Thu)", "value": "BOGO", "audience": "new_user", "type": "bogo" },
+    { "id": "res_003", "title": "Weekday Lunch Thali @ ₹149", "value": "149", "audience": "new_user", "type": "service_at_price" },
+    { "id": "res_004", "title": "Free Starter on orders > ₹1,200", "value": "free_addon", "audience": "new_user", "type": "free_addon" },
+    { "id": "res_005", "title": "Match-night Combo @ ₹399 (food + drink)", "value": "399", "audience": "new_user", "type": "service_at_price" },
+    { "id": "res_006", "title": "Family Sunday Brunch @ ₹699/pax", "value": "699", "audience": "new_user", "type": "service_at_price" },
+    { "id": "res_007", "title": "Free Delivery > ₹500", "value": "free_delivery", "audience": "new_user", "type": "free_addon" },
+    { "id": "res_008", "title": "Birthday: Free Cake on parties of 6+", "value": "free_addon", "audience": "all", "type": "free_addon" }
+  ],
+  "peer_stats": {
+    "scope": "metro_casual_dining_2026",
+    "avg_rating": 4.2,
+    "avg_review_count": 142,
+    "avg_views_30d": 4800,
+    "avg_calls_30d": 38,
+    "avg_directions_30d": 95,
+    "avg_ctr": 0.025,
+    "avg_photos": 22,
+    "avg_post_freq_days": 7,
+    "retention_30d_pct": 0.18
+  },
+  "digest": [
+    {
+      "id": "d_2026W17_ipl_window",
+      "kind": "seasonal",
+      "title": "IPL home-match Saturdays underperformed weeknight matches across metros",
+      "source": "magicpin order data, Apr 2026",
+      "summary": "Saturday IPL matches shift orders to home-watch parties; restaurant covers down 12% vs Saturday average. Weeknight matches drive +18% covers. Adjust promo days accordingly.",
+      "actionable": "Push match-night combos on Tue/Wed/Thu match dates only"
+    },
+    {
+      "id": "d_2026W17_packaged_food_gst",
+      "kind": "compliance",
+      "title": "GST council clarifies 5% rate for restaurant takeaway packaging from 2026-06-01",
+      "source": "GST Council circular 224/2026",
+      "summary": "Single-use plastic surcharge added to packaging cost for orders >₹500. Effective June 1. Cloud kitchens hit hardest.",
+      "actionable": "Audit your packaging cost; consider Eco-pack alternative if volume justifies"
+    },
+    {
+      "id": "d_2026W17_zomato_visibility",
+      "kind": "trend",
+      "title": "Zomato 'verified' badge correlates with +24% impressions in Tier-1 cities",
+      "source": "Zomato partner update, Apr 2026",
+      "summary": "Verification requires uploaded GST cert + 6 months continuous operation. Most eligible mid-size restaurants haven't applied; 5-day approval.",
+      "actionable": "Apply via partner dashboard if you've crossed 6 months"
+    },
+    {
+      "id": "d_2026W17_swiggy_iCare",
+      "kind": "tech",
+      "title": "Swiggy iCare: AI complaint summarizer launching Apr 2026",
+      "source": "Swiggy partner blog 2026-04-12",
+      "summary": "Auto-summarises customer complaints into themes (cold food / late / wrong order). Free for Pro merchants. Reveals pattern most operators miss.",
+      "actionable": "Enable in dashboard; review weekly themes Sunday evening"
+    },
+    {
+      "id": "d_2026W17_dish_trend",
+      "kind": "trend",
+      "title": "'Sugar-free dessert' searches +52% YoY across Indian metros",
+      "source": "Google Trends Apr 2026",
+      "summary": "Concentrated in 28-45 age band; correlated with rising diabetic awareness. Two new options on dessert menus seeing strong attach rate: keto cheesecake, almond-flour brownie.",
+      "actionable": "Add one sugar-free dessert; mark prominently on menu and GBP"
+    }
+  ],
+  "patient_content_library": [
+    {
+      "id": "pc_ordering_smart",
+      "title": "Three things to look for before ordering food online",
+      "channel": "whatsapp",
+      "length_seconds": 60,
+      "body": "(1) Look at the latest review's date — if last review is 30+ days old, the kitchen may be off. (2) Filter for 4★+ reviews mentioning your specific dish. (3) Order at peak hours — fresh prep, not warmed-up morning batch. These three filter out 80% of bad-experience risk."
+    },
+    {
+      "id": "pc_thali_economics",
+      "title": "Why a ₹149 thali is the best lunch deal in town",
+      "channel": "whatsapp",
+      "length_seconds": 45,
+      "body": "A weekday thali for ₹149 covers your daily protein, two veggies, dal, rice, roti, and pickle/sweet. Buying these separately at any market in the neighbourhood: ₹240+. The only way restaurants make this work is high lunch volume — which means freshly-cooked, not standing in a chafer."
+    }
+  ],
+  "seasonal_beats": [
+    { "month_range": "Mar-Apr", "note": "IPL season — match-night promos on Tue/Wed/Thu; not weekends" },
+    { "month_range": "Oct-Nov", "note": "Diwali corporate gifting + family-feast bookings" },
+    { "month_range": "Dec", "note": "Christmas + New Year — set menu sales 3x baseline" },
+    { "month_range": "Jul-Aug", "note": "monsoon delivery surge; rain-day discount window" },
+    { "month_range": "Feb 14", "note": "Valentine's prix-fixe — book starting 2 weeks prior" }
+  ],
+  "trend_signals": [
+    { "query": "biryani near me", "delta_yoy": 0.18, "segment_age": "all", "skew": "balanced" },
+    { "query": "weekday lunch thali", "delta_yoy": 0.34, "segment_age": "office_25-45", "skew": "balanced" },
+    { "query": "sugar free dessert", "delta_yoy": 0.52, "segment_age": "28-45", "skew": "balanced" },
+    { "query": "match night offer", "delta_yoy": 0.65, "segment_age": "20-40", "skew": "male" },
+    { "query": "small party catering", "delta_yoy": 0.22, "segment_age": "30-50", "skew": "female" }
+  ],
+  "regulatory_authorities": ["FSSAI", "Local Health Department", "GST Council"],
+  "professional_journals": ["FoodService India", "Hospitality Bizz"]
+}

dataset/categories/salons.json

@@ -0,0 +1,125 @@
+{
+  "slug": "salons",
+  "display_name": "Salons & Beauty",
+  "voice": {
+    "tone": "warm_practical",
+    "register": "approachable_expert",
+    "code_mix": "hindi_english_natural",
+    "vocab_allowed": [
+      "balayage", "highlights", "keratin", "smoothening", "hair spa",
+      "manicure", "pedicure", "facial", "threading", "waxing", "extensions",
+      "olaplex", "wella", "loreal", "schwarzkopf", "redken"
+    ],
+    "vocab_taboo": [
+      "guaranteed glow", "permanent results", "instant transformation", "miracle",
+      "best in city"
+    ],
+    "salutation_examples": ["Hi {first_name}", "{salon_name} team"],
+    "tone_examples": [
+      "Bridal season is starting — bookings usually 2x normal in next 4 weeks",
+      "Quick one — your Saturday 5-7pm slot has been the strongest this month"
+    ]
+  },
+  "offer_catalog": [
+    { "id": "sal_001", "title": "Haircut @ ₹99", "value": "99", "audience": "new_user", "type": "service_at_price" },
+    { "id": "sal_002", "title": "FREE head massage with Haircut", "value": "0", "audience": "new_user", "type": "free_addon" },
+    { "id": "sal_003", "title": "Hair Spa @ ₹499", "value": "499", "audience": "new_user", "type": "service_at_price" },
+    { "id": "sal_004", "title": "Threading + Waxing combo @ ₹299", "value": "299", "audience": "new_user", "type": "service_at_price" },
+    { "id": "sal_005", "title": "Bridal Trial @ ₹999", "value": "999", "audience": "new_user", "type": "service_at_price" },
+    { "id": "sal_006", "title": "Keratin Treatment @ ₹2,499", "value": "2499", "audience": "new_user", "type": "service_at_price" },
+    { "id": "sal_007", "title": "Mani+Pedi Combo @ ₹599", "value": "599", "audience": "new_user", "type": "service_at_price" },
+    { "id": "sal_008", "title": "Annual Membership: 12 services @ ₹4,999", "value": "4999", "audience": "repeat_user", "type": "membership" }
+  ],
+  "peer_stats": {
+    "scope": "metro_unisex_salons_2026",
+    "avg_rating": 4.5,
+    "avg_review_count": 88,
+    "avg_views_30d": 2400,
+    "avg_calls_30d": 28,
+    "avg_directions_30d": 62,
+    "avg_ctr": 0.040,
+    "avg_photos": 14,
+    "avg_post_freq_days": 10,
+    "retention_3mo_pct": 0.55
+  },
+  "digest": [
+    {
+      "id": "d_2026W17_olaplex_no9",
+      "kind": "tech",
+      "title": "Olaplex No.9 launches in India — bond protector for chemically-treated hair",
+      "source": "Hair Brand News India, Apr 2026",
+      "summary": "Pre-shampoo bond protector targeting damage from frequent colour and smoothening. Distributors confirmed in Delhi/Mumbai/Bangalore. Wholesale ₹3,200/bottle, retail ~₹4,500.",
+      "actionable": "Worth piloting if your colour client mix is >25%"
+    },
+    {
+      "id": "d_2026W17_keratin_alt",
+      "kind": "trend",
+      "title": "Formaldehyde-free smoothening alternatives gaining share — citric-acid based",
+      "source": "Salon India magazine, Apr 2026",
+      "summary": "Brazilian citric-acid keratin alternatives now widely available. Lower fume, comparable hold for ~6-8 weeks. Pricing roughly +15% over standard keratin.",
+      "actionable": "Position as 'safe smoothening' for pregnancy / asthma clients"
+    },
+    {
+      "id": "d_2026W17_bridal_season_start",
+      "kind": "seasonal",
+      "title": "Wedding season opener — first lean April-May window before main Oct-Dec rush",
+      "source": "Wedding industry intel",
+      "summary": "Mini-bridal window April-May (~15% of annual bridal volume) often missed by salons focused on Oct-Dec. Pre-wedding skincare + mehendi-prep services peak now.",
+      "actionable": "Run a 'Bridal Trial @ ₹999' offer; book 2-month skincare package"
+    },
+    {
+      "id": "d_2026W17_olaplex_training",
+      "kind": "cde",
+      "title": "L'Oreal Professionnel India training: Advanced Balayage Masterclass",
+      "source": "L'Oreal Pro India calendar",
+      "date": "2026-05-08",
+      "summary": "2-day in-person training in Mumbai. ₹15,000 fee. Targeted at stylists with 2+ years of colour experience.",
+      "actionable": "Worth subsidising for one stylist if balayage demand is rising in your locality"
+    },
+    {
+      "id": "d_2026W17_walkin_priority",
+      "kind": "trend",
+      "title": "'Walk-in available' tag on GBP boosting calls 23% in metros",
+      "source": "magicpin internal, Apr 2026",
+      "summary": "Salons that explicitly add 'walk-in available' to their GBP description see 23% higher call volume in the same locality vs salons without. Effect strongest weekday afternoons.",
+      "actionable": "Add the tag to your GBP description this week"
+    }
+  ],
+  "patient_content_library": [
+    {
+      "id": "pc_keratin_safe",
+      "title": "Is keratin safe? What to ask before booking",
+      "channel": "whatsapp",
+      "length_seconds": 60,
+      "body": "Old-school keratin uses formaldehyde — safe in trained hands but not for pregnancy or asthma. Citric-acid alternatives exist now with similar hold. Two questions to ask any salon: (1) what's your activator? (2) is the room ventilated? If you don't get a clear answer, look elsewhere."
+    },
+    {
+      "id": "pc_balayage_vs_highlights",
+      "title": "Balayage vs highlights — which actually suits you?",
+      "channel": "whatsapp",
+      "length_seconds": 75,
+      "body": "Highlights are uniform stripes; balayage is hand-painted, growing out softly with no visible regrowth line. Highlights cost less but need touch-ups every 8 weeks. Balayage holds 4-5 months. If you don't visit the salon often, balayage is the practical choice."
+    },
+    {
+      "id": "pc_post_color_care",
+      "title": "Post-colour care — first 72 hours matter most",
+      "channel": "whatsapp",
+      "length_seconds": 45,
+      "body": "Three rules: no shampoo for 48h (let cuticle close), use sulphate-free shampoo from day 3, and avoid hot water washes for the first month. Skip these and you'll lose 30% of the colour vibrance in the first wash."
+    }
+  ],
+  "seasonal_beats": [
+    { "month_range": "Oct-Dec", "note": "primary wedding/festival season — bridal package bookings 4x baseline" },
+    { "month_range": "Apr-May", "note": "secondary bridal window + summer hair-care surge" },
+    { "month_range": "Jul-Aug", "note": "monsoon haircare focus (anti-frizz, scalp treatments)" },
+    { "month_range": "Mar", "note": "Holi colour-recovery surge — book hair spas the week after" }
+  ],
+  "trend_signals": [
+    { "query": "balayage near me", "delta_yoy": 0.45, "segment_age": "25-40", "skew": "female" },
+    { "query": "keratin treatment price", "delta_yoy": 0.18, "segment_age": "25-45", "skew": "female" },
+    { "query": "men's haircut delhi", "delta_yoy": 0.22, "segment_age": "20-35", "skew": "male" },
+    { "query": "bridal makeup artist", "delta_yoy": 0.31, "segment_age": "22-32", "skew": "female" }
+  ],
+  "regulatory_authorities": ["FDA India (cosmetic ingredient compliance)"],
+  "professional_journals": ["Salon India", "Pure Beauty India"]
+}

dataset/customers_seed.json

@@ -0,0 +1,140 @@
+{
+  "_README": "15 representative CustomerContexts. The generator expands these to 200 by varying demographic + relationship state per merchant.",
+  "customers": [
+    {
+      "customer_id": "c_001_priya_for_m001",
+      "merchant_id": "m_001_drmeera_dentist_delhi",
+      "identity": { "name": "Priya", "phone_redacted": "<phone>", "language_pref": "hi-en mix", "age_band": "25-35" },
+      "relationship": { "first_visit": "2025-11-04", "last_visit": "2026-05-12", "visits_total": 4, "services_received": ["cleaning", "cleaning", "whitening", "cleaning"], "lifetime_value": 1696 },
+      "state": "lapsed_soft",
+      "preferences": { "preferred_slots": "weekday_evening", "channel": "whatsapp", "reminder_opt_in": true },
+      "consent": { "opted_in_at": "2025-11-04", "scope": ["recall_reminders", "appointment_reminders"] }
+    },
+    {
+      "customer_id": "c_002_rohit_for_m001",
+      "merchant_id": "m_001_drmeera_dentist_delhi",
+      "identity": { "name": "Rohit", "phone_redacted": "<phone>", "language_pref": "english", "age_band": "35-45" },
+      "relationship": { "first_visit": "2026-02-12", "last_visit": "2026-04-18", "visits_total": 2, "services_received": ["root_canal_consult", "root_canal_session_1"], "lifetime_value": 5500 },
+      "state": "active",
+      "preferences": { "preferred_slots": "saturday_morning", "channel": "whatsapp", "reminder_opt_in": true },
+      "consent": { "opted_in_at": "2026-02-12", "scope": ["recall_reminders", "appointment_reminders", "treatment_followup"] }
+    },
+    {
+      "customer_id": "c_003_aanya_for_m001",
+      "merchant_id": "m_001_drmeera_dentist_delhi",
+      "identity": { "name": "Aanya (parent: Sneha)", "phone_redacted": "<phone>", "language_pref": "hi-en mix", "age_band": "child_under_12" },
+      "relationship": { "first_visit": "2026-01-08", "last_visit": "2026-01-08", "visits_total": 1, "services_received": ["pediatric_checkup"], "lifetime_value": 199 },
+      "state": "lapsed_hard",
+      "preferences": { "preferred_slots": "weekday_after_3pm", "channel": "whatsapp", "reminder_opt_in": true },
+      "consent": { "opted_in_at": "2026-01-08", "scope": ["recall_reminders"] }
+    },
+    {
+      "customer_id": "c_004_sneha_for_m003",
+      "merchant_id": "m_003_studio11_salon_hyderabad",
+      "identity": { "name": "Sneha", "phone_redacted": "<phone>", "language_pref": "te-en mix", "age_band": "25-35" },
+      "relationship": { "first_visit": "2025-09-14", "last_visit": "2026-04-19", "visits_total": 11, "services_received": ["balayage", "hair_spa", "balayage_touchup", "manicure", "pedicure", "haircut", "haircut", "balayage", "hair_spa", "facial", "haircut"], "lifetime_value": 18450 },
+      "state": "active",
+      "preferences": { "preferred_slots": "saturday_afternoon", "channel": "whatsapp", "reminder_opt_in": true, "preferred_stylist": "Priya" },
+      "consent": { "opted_in_at": "2025-09-14", "scope": ["appointment_reminders", "promotional_offers", "stylist_specific"] }
+    },
+    {
+      "customer_id": "c_005_kavya_for_m003",
+      "merchant_id": "m_003_studio11_salon_hyderabad",
+      "identity": { "name": "Kavya", "phone_redacted": "<phone>", "language_pref": "english", "age_band": "20-25" },
+      "relationship": { "first_visit": "2026-03-22", "last_visit": "2026-03-22", "visits_total": 1, "services_received": ["bridal_trial"], "lifetime_value": 999 },
+      "state": "new",
+      "preferences": { "preferred_slots": "saturday", "channel": "whatsapp", "reminder_opt_in": true, "wedding_date": "2026-11-08" },
+      "consent": { "opted_in_at": "2026-03-22", "scope": ["appointment_reminders", "bridal_package_followup"] }
+    },
+    {
+      "customer_id": "c_006_amit_for_m005",
+      "merchant_id": "m_005_pizzajunction_restaurant_delhi",
+      "identity": { "name": "Amit", "phone_redacted": "<phone>", "language_pref": "hi-en mix", "age_band": "25-35" },
+      "relationship": { "first_visit": "2026-04-12", "last_visit": "2026-04-22", "visits_total": 5, "services_received": ["delivery_pizza", "delivery_combo", "dine_in", "delivery_pizza", "delivery_pizza"], "lifetime_value": 2380, "favourite_dish": "BBQ Chicken Pizza" },
+      "state": "active",
+      "preferences": { "preferred_slots": "fri_sat_night", "channel": "whatsapp", "reminder_opt_in": true },
+      "consent": { "opted_in_at": "2026-04-12", "scope": ["promotional_offers", "match_night_specials"] }
+    },
+    {
+      "customer_id": "c_007_naveen_for_m006",
+      "merchant_id": "m_006_southindiancafe_restaurant_bangalore",
+      "identity": { "name": "Naveen", "phone_redacted": "<phone>", "language_pref": "kn-en mix", "age_band": "30-40" },
+      "relationship": { "first_visit": "2025-06-05", "last_visit": "2026-04-25", "visits_total": 38, "services_received": ["weekday_thali", "weekday_thali", "weekday_thali", "filter_coffee", "..."], "lifetime_value": 6480, "favourite_dish": "Mylari Dosa" },
+      "state": "active",
+      "preferences": { "preferred_slots": "weekday_lunch", "channel": "whatsapp", "reminder_opt_in": true, "office_nearby": true },
+      "consent": { "opted_in_at": "2025-06-05", "scope": ["promotional_offers", "lunch_thali_updates"] }
+    },
+    {
+      "customer_id": "c_008_dipti_for_m006",
+      "merchant_id": "m_006_southindiancafe_restaurant_bangalore",
+      "identity": { "name": "Dipti", "phone_redacted": "<phone>", "language_pref": "english", "age_band": "30-40" },
+      "relationship": { "first_visit": "2025-12-18", "last_visit": "2026-01-05", "visits_total": 2, "services_received": ["family_brunch", "delivery_dosa_combo"], "lifetime_value": 1280 },
+      "state": "lapsed_soft",
+      "preferences": { "preferred_slots": "sunday_brunch", "channel": "whatsapp", "reminder_opt_in": true, "family_size": 4 },
+      "consent": { "opted_in_at": "2025-12-18", "scope": ["promotional_offers"] }
+    },
+    {
+      "customer_id": "c_009_arjun_for_m007",
+      "merchant_id": "m_007_powerhouse_gym_bangalore",
+      "identity": { "name": "Arjun", "phone_redacted": "<phone>", "language_pref": "english", "age_band": "25-35" },
+      "relationship": { "first_visit": "2026-01-05", "last_visit": "2026-04-21", "visits_total": 78, "services_received": ["membership_jan", "membership_feb", "membership_mar", "membership_apr", "PT_session_x12"], "lifetime_value": 9990 },
+      "state": "active",
+      "preferences": { "preferred_slots": "weekday_7am", "channel": "whatsapp", "reminder_opt_in": true, "training_focus": "strength" },
+      "consent": { "opted_in_at": "2026-01-05", "scope": ["program_updates", "renewal_reminders"] }
+    },
+    {
+      "customer_id": "c_010_rashmi_for_m007",
+      "merchant_id": "m_007_powerhouse_gym_bangalore",
+      "identity": { "name": "Rashmi", "phone_redacted": "<phone>", "language_pref": "english", "age_band": "30-40" },
+      "relationship": { "first_visit": "2025-09-10", "last_visit": "2026-02-28", "visits_total": 22, "services_received": ["membership_x4", "PT_intro"], "lifetime_value": 4490 },
+      "state": "lapsed_hard",
+      "preferences": { "preferred_slots": "weekday_evening", "channel": "whatsapp", "reminder_opt_in": true, "training_focus": "weight_loss" },
+      "consent": { "opted_in_at": "2025-09-10", "scope": ["renewal_reminders", "winback_offers"] }
+    },
+    {
+      "customer_id": "c_011_sumitra_for_m008",
+      "merchant_id": "m_008_zenyoga_gym_chennai",
+      "identity": { "name": "Sumitra", "phone_redacted": "<phone>", "language_pref": "ta-en mix", "age_band": "45-55" },
+      "relationship": { "first_visit": "2025-04-12", "last_visit": "2026-04-26", "visits_total": 145, "services_received": ["yoga_intermediate_x12_months", "pilates_x4_months"], "lifetime_value": 28800 },
+      "state": "active",
+      "preferences": { "preferred_slots": "morning_6am", "channel": "whatsapp", "reminder_opt_in": true, "health_focus": "back_pain_management" },
+      "consent": { "opted_in_at": "2025-04-12", "scope": ["program_updates", "health_content", "renewal_reminders"] }
+    },
+    {
+      "customer_id": "c_012_karthik_jr_for_m008",
+      "merchant_id": "m_008_zenyoga_gym_chennai",
+      "identity": { "name": "Karthik (parent: Sumitra)", "phone_redacted": "<phone>", "language_pref": "ta-en mix", "age_band": "child_7-12" },
+      "relationship": { "first_visit": "2026-04-22", "last_visit": "2026-04-22", "visits_total": 1, "services_received": ["kids_yoga_trial"], "lifetime_value": 0 },
+      "state": "new",
+      "preferences": { "preferred_slots": "saturday_morning", "channel": "whatsapp_via_parent", "reminder_opt_in": true },
+      "consent": { "opted_in_at": "2026-04-22", "scope": ["kids_program_updates"] }
+    },
+    {
+      "customer_id": "c_013_grandfather_for_m009",
+      "merchant_id": "m_009_apollo_pharmacy_jaipur",
+      "identity": { "name": "Mr. Sharma", "phone_redacted": "<phone>", "language_pref": "hi", "age_band": "65-75", "senior_citizen": true },
+      "relationship": { "first_visit": "2024-08-10", "last_visit": "2026-04-22", "visits_total": 24, "services_received": ["chronic_rx_metformin", "chronic_rx_atorvastatin", "chronic_rx_telmisartan", "..."], "lifetime_value": 24600, "chronic_conditions": ["diabetes_t2", "hypertension", "dyslipidemia"] },
+      "state": "active",
+      "preferences": { "preferred_slots": "morning_delivery", "channel": "whatsapp_via_son", "reminder_opt_in": true, "delivery_address": "saved" },
+      "consent": { "opted_in_at": "2024-08-10", "scope": ["refill_reminders", "delivery_notifications", "recall_alerts"] }
+    },
+    {
+      "customer_id": "c_014_priti_for_m009",
+      "merchant_id": "m_009_apollo_pharmacy_jaipur",
+      "identity": { "name": "Priti", "phone_redacted": "<phone>", "language_pref": "hi-en mix", "age_band": "30-40" },
+      "relationship": { "first_visit": "2026-03-10", "last_visit": "2026-04-12", "visits_total": 3, "services_received": ["walk_in_otc", "delivery_otc", "consult_with_pharmacist"], "lifetime_value": 580 },
+      "state": "active",
+      "preferences": { "preferred_slots": "evening", "channel": "whatsapp", "reminder_opt_in": true, "household_size": 4 },
+      "consent": { "opted_in_at": "2026-03-10", "scope": ["promotional_offers", "seasonal_health_content"] }
+    },
+    {
+      "customer_id": "c_015_anonymous_for_m010",
+      "merchant_id": "m_010_sunrisepharm_pharmacy_lucknow",
+      "identity": { "name": "(walk-in, no profile)", "phone_redacted": null, "language_pref": "hi", "age_band": "unknown" },
+      "relationship": { "first_visit": "2026-04-15", "last_visit": "2026-04-15", "visits_total": 1, "services_received": ["walk_in_otc"], "lifetime_value": 240 },
+      "state": "new",
+      "preferences": { "channel": "none_recorded", "reminder_opt_in": false },
+      "consent": { "opted_in_at": null, "scope": [] }
+    }
+  ]
+}

dataset/generate_dataset.py

@@ -0,0 +1,312 @@
+#!/usr/bin/env python3
+"""
+Expand seed JSON files into the full challenge dataset.
+
+Usage:
+    python generate_dataset.py --out ./expanded
+
+Reads from:
+    categories/*.json       — already-complete category contexts (5)
+    merchants_seed.json     — 10 representative merchants (2 per category)
+    customers_seed.json     — 15 representative customers
+    triggers_seed.json      — 25 representative triggers
+
+Writes to ./expanded/:
+    categories/{slug}.json          (5 files, copied as-is)
+    merchants/m_NNN_*.json          (50 files — seeds + 40 generated)
+    customers/c_NNN_*.json          (200 files — seeds + 185 generated)
+    triggers/trg_NNN_*.json         (100 files — seeds + 75 generated)
+    test_pairs.json                 (30 canonical (merchant, trigger) pairs all
+                                     candidates produce a message for)
+
+Deterministic — fixed seed, same output for everyone.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import random
+from pathlib import Path
+
+SEED = 20260426  # fixed so every candidate gets the same expanded dataset
+
+# Indian city + locality pool for variation
+LOCALITIES = {
+    "Delhi": ["Lajpat Nagar", "Saket", "Karol Bagh", "Pitampura", "Dwarka", "Rohini", "Greater Kailash", "Vasant Kunj", "Connaught Place", "Hauz Khas"],
+    "Mumbai": ["Andheri West", "Bandra", "Borivali", "Powai", "Lower Parel", "Goregaon", "Thane", "Vile Parle", "Juhu", "Worli"],
+    "Bangalore": ["HSR Layout", "Indiranagar", "Whitefield", "Koramangala", "JP Nagar", "Marathahalli", "Bellandur", "Jayanagar", "BTM Layout", "Sarjapur"],
+    "Hyderabad": ["Kapra", "Kondapur", "Madhapur", "Banjara Hills", "Jubilee Hills", "Kukatpally", "Gachibowli", "Begumpet", "Secunderabad", "LB Nagar"],
+    "Chennai": ["Mylapore", "Adyar", "Velachery", "T Nagar", "Anna Nagar", "Tambaram", "OMR", "Nungambakkam", "Porur", "Besant Nagar"],
+    "Pune": ["Aundh", "Baner", "Hadapsar", "Kothrud", "Wakad", "Hinjewadi", "Viman Nagar", "Kharadi", "Pimpri", "Magarpatta"],
+    "Chandigarh": ["Sector 17", "Sector 22", "Sector 35", "Mohali", "Panchkula", "Sector 9", "Sector 11", "Manimajra", "Sector 8", "Sector 26"],
+    "Jaipur": ["Malviya Nagar", "Vaishali Nagar", "Mansarovar", "Tonk Road", "C-Scheme", "Raja Park", "Civil Lines", "Jhotwara", "Bani Park", "Sodala"],
+    "Lucknow": ["Gomti Nagar", "Hazratganj", "Indira Nagar", "Aliganj", "Aminabad", "Vibhuti Khand", "Mahanagar", "Aashiana", "Alambagh", "Janakipuram"],
+    "Ahmedabad": ["Satellite", "Bodakdev", "Vastrapur", "Maninagar", "Naranpura", "Bopal", "SG Highway", "Navrangpura", "Thaltej", "Chandkheda"],
+}
+
+NAME_BANKS = {
+    "dentists": [
+        ("Dr. Asha", "Asha Dental Care"),
+        ("Dr. Vikram", "Smile Crafters"),
+        ("Dr. Neha", "Pearl Dental Studio"),
+        ("Dr. Rajan", "City Dental Clinic"),
+        ("Dr. Priya", "Family Dental Centre"),
+        ("Dr. Sameer", "Bright Smile Dental"),
+        ("Dr. Tara", "Crown Dental"),
+        ("Dr. Karthik", "Apex Dental Care"),
+    ],
+    "salons": [
+        ("Renu", "Beauty Lounge by Renu"),
+        ("Karim", "Karim's Salon"),
+        ("Anita", "Anita's Beauty Studio"),
+        ("Salim", "Studio Cuts"),
+        ("Manish", "Aesthetic Hair Studio"),
+        ("Geeta", "Glow Up Salon"),
+        ("Paras", "Paras Hair & Beauty"),
+        ("Sushma", "The Beauty Bar"),
+    ],
+    "restaurants": [
+        ("Suresh", "Madras Express"),
+        ("Anand", "Chai Point Cafe"),
+        ("Karim", "Kabab Junction"),
+        ("Sandeep", "Tandoor Treats"),
+        ("Ravi", "Veg Bowl"),
+        ("Imran", "Biryani House"),
+        ("Mukesh", "Pizza Spot"),
+        ("Lalit", "Family Diner"),
+    ],
+    "gyms": [
+        ("Karan", "Iron Forge Fitness"),
+        ("Sneha", "Pulse Studio"),
+        ("Akash", "Fit Republic"),
+        ("Roshni", "Active Life Gym"),
+        ("Vivek", "Strength Co."),
+        ("Manisha", "Vyayam Yoga"),
+        ("Deepak", "Body Mechanics"),
+        ("Pooja", "Bend & Burn"),
+    ],
+    "pharmacies": [
+        ("Anil", "Healthwell Pharmacy"),
+        ("Rajesh", "MedPlus Express"),
+        ("Sunita", "Reliable Medicos"),
+        ("Vinod", "Family Health Pharmacy"),
+        ("Bharti", "Wellness Cart"),
+        ("Sanjay", "TrueCare Medicos"),
+        ("Mohit", "QuickRx Pharmacy"),
+        ("Komal", "Daily Care Medicos"),
+    ],
+}
+
+
+def load_seeds(seed_dir: Path):
+    categories = {}
+    for f in (seed_dir / "categories").glob("*.json"):
+        with open(f) as fp:
+            data = json.load(fp)
+            categories[data["slug"]] = data
+    with open(seed_dir / "merchants_seed.json") as fp:
+        merchants = json.load(fp)["merchants"]
+    with open(seed_dir / "customers_seed.json") as fp:
+        customers = json.load(fp)["customers"]
+    with open(seed_dir / "triggers_seed.json") as fp:
+        triggers = json.load(fp)["triggers"]
+    return categories, merchants, customers, triggers
+
+
+def expand_merchants(seeds: list[dict], rnd: random.Random) -> list[dict]:
+    """Generate 8 additional merchants per category (10 total per category, 50 overall)."""
+    expanded = list(seeds)
+    by_cat = {}
+    for m in seeds:
+        by_cat.setdefault(m["category_slug"], []).append(m)
+    next_idx = len(seeds) + 1
+    for cat_slug in NAME_BANKS:
+        existing = len(by_cat.get(cat_slug, []))
+        need = 10 - existing
+        for i in range(need):
+            owner_first, biz_name = rnd.choice(NAME_BANKS[cat_slug])
+            city = rnd.choice(list(LOCALITIES.keys()))
+            locality = rnd.choice(LOCALITIES[city])
+            mid = f"m_{next_idx:03d}_{owner_first.lower().replace(' ', '_').replace('dr.', 'dr')}_{cat_slug.rstrip('s')}_{city.lower()}"
+            views = rnd.randint(400, 6000)
+            calls = rnd.randint(2, max(3, views // 80))
+            ctr = round(rnd.uniform(0.015, 0.060), 3)
+            verified = rnd.random() > 0.25
+            sub_status = rnd.choices(["active", "expired", "trial"], weights=[7, 2, 1])[0]
+            expanded.append({
+                "merchant_id": mid,
+                "category_slug": cat_slug,
+                "identity": {
+                    "name": biz_name, "city": city, "locality": locality,
+                    "place_id": f"ChIJ_{locality.upper().replace(' ', '_')}_{cat_slug.upper()}_{next_idx:03d}",
+                    "verified": verified,
+                    "languages": ["en", "hi"] + (["mr"] if city == "Mumbai" else ["ta"] if city == "Chennai" else ["te"] if city == "Hyderabad" else ["kn"] if city == "Bangalore" else []),
+                    "owner_first_name": owner_first,
+                    "established_year": rnd.randint(2010, 2023),
+                },
+                "subscription": {"status": sub_status, "plan": "Pro" if sub_status != "trial" else "Trial",
+                                 "days_remaining": rnd.randint(5, 300) if sub_status == "active" else (rnd.randint(1, 14) if sub_status == "trial" else 0),
+                                 "days_since_expiry": rnd.randint(7, 90) if sub_status == "expired" else None},
+                "performance": {"window_days": 30, "views": views, "calls": calls,
+                                "directions": calls * 2 + rnd.randint(0, 30),
+                                "ctr": ctr, "leads": rnd.randint(0, calls),
+                                "delta_7d": {"views_pct": round(rnd.uniform(-0.30, 0.30), 2),
+                                             "calls_pct": round(rnd.uniform(-0.30, 0.30), 2)}},
+                "offers": [],
+                "conversation_history": [],
+                "customer_aggregate": {"total_unique_ytd": rnd.randint(50, 2000)},
+                "signals": [],
+                "review_themes": [],
+            })
+            next_idx += 1
+    return expanded
+
+
+def expand_customers(seeds: list[dict], merchants: list[dict], rnd: random.Random) -> list[dict]:
+    """Generate ~3-5 customers per merchant up to 200 total."""
+    expanded = list(seeds)
+    next_idx = len(seeds) + 1
+    target_per_merchant = 4
+    have_per_merchant = {}
+    for c in seeds:
+        have_per_merchant[c["merchant_id"]] = have_per_merchant.get(c["merchant_id"], 0) + 1
+    customer_names = ["Aarav", "Vivaan", "Aditya", "Vihaan", "Arjun", "Ishaan", "Reyansh", "Aryan", "Ananya", "Aadhya", "Saanvi", "Kavya", "Diya", "Ira", "Myra", "Anika", "Riya", "Tara"]
+    for m in merchants:
+        cur = have_per_merchant.get(m["merchant_id"], 0)
+        for i in range(max(0, target_per_merchant - cur)):
+            if next_idx > 200 + len(seeds): break
+            name = rnd.choice(customer_names)
+            cid = f"c_{next_idx:03d}_{name.lower()}_for_{m['merchant_id']}"
+            visits = rnd.randint(1, 12)
+            state = rnd.choices(
+                ["new", "active", "lapsed_soft", "lapsed_hard", "churned"],
+                weights=[1, 4, 2, 1, 1]
+            )[0]
+            expanded.append({
+                "customer_id": cid,
+                "merchant_id": m["merchant_id"],
+                "identity": {"name": name, "phone_redacted": "<phone>",
+                             "language_pref": rnd.choice(["en", "hi-en mix", "hi"]),
+                             "age_band": rnd.choice(["20-25", "25-35", "30-40", "40-50", "50-65"])},
+                "relationship": {"first_visit": "2025-09-01", "last_visit": "2026-04-01",
+                                 "visits_total": visits, "services_received": [],
+                                 "lifetime_value": visits * rnd.randint(200, 1500)},
+                "state": state,
+                "preferences": {"channel": "whatsapp", "reminder_opt_in": rnd.random() > 0.2},
+                "consent": {"opted_in_at": "2025-09-01", "scope": ["promotional_offers"]},
+            })
+            next_idx += 1
+    return expanded
+
+
+def expand_triggers(seeds: list[dict], merchants: list[dict], customers: list[dict], rnd: random.Random) -> list[dict]:
+    """Generate ~75 additional triggers spread across kinds + merchants."""
+    expanded = list(seeds)
+    next_idx = len(seeds) + 1
+    additional_kinds = [
+        ("research_digest", "external", "merchant", 1),
+        ("perf_dip", "internal", "merchant", 3),
+        ("perf_spike", "internal", "merchant", 1),
+        ("milestone_reached", "internal", "merchant", 1),
+        ("dormant_with_vera", "internal", "merchant", 2),
+        ("review_theme_emerged", "internal", "merchant", 3),
+        ("competitor_opened", "external", "merchant", 2),
+        ("festival_upcoming", "external", "merchant", 1),
+        ("recall_due", "internal", "customer", 3),
+        ("customer_lapsed_soft", "internal", "customer", 3),
+        ("appointment_tomorrow", "internal", "customer", 2),
+        ("chronic_refill_due", "internal", "customer", 2),
+        ("trial_followup", "internal", "customer", 2),
+        ("renewal_due", "internal", "merchant", 4),
+        ("curious_ask_due", "internal", "merchant", 1),
+    ]
+    for kind, source, scope, urgency in additional_kinds:
+        for _ in range(5):  # 5 of each kind
+            if next_idx > 100: break
+            m = rnd.choice(merchants)
+            cust = None
+            if scope == "customer":
+                m_customers = [c for c in customers if c["merchant_id"] == m["merchant_id"]]
+                if not m_customers: continue
+                cust = rnd.choice(m_customers)
+            expanded.append({
+                "id": f"trg_{next_idx:03d}_{kind}_{m['merchant_id'][:20]}",
+                "scope": scope, "kind": kind, "source": source,
+                "merchant_id": m["merchant_id"],
+                "customer_id": cust["customer_id"] if cust else None,
+                "payload": {"placeholder": True, "metric_or_topic": kind},
+                "urgency": urgency, "suppression_key": f"{kind}:{m['merchant_id']}:gen_{next_idx}",
+                "expires_at": "2026-06-30T00:00:00Z",
+            })
+            next_idx += 1
+    return expanded[:100]
+
+
+def write_outputs(out_dir: Path, categories, merchants, customers, triggers):
+    out_dir.mkdir(parents=True, exist_ok=True)
+    (out_dir / "categories").mkdir(exist_ok=True)
+    for slug, data in categories.items():
+        with open(out_dir / "categories" / f"{slug}.json", "w") as f:
+            json.dump(data, f, indent=2, ensure_ascii=False)
+    (out_dir / "merchants").mkdir(exist_ok=True)
+    for m in merchants:
+        with open(out_dir / "merchants" / f"{m['merchant_id']}.json", "w") as f:
+            json.dump(m, f, indent=2, ensure_ascii=False)
+    (out_dir / "customers").mkdir(exist_ok=True)
+    for c in customers:
+        with open(out_dir / "customers" / f"{c['customer_id']}.json", "w") as f:
+            json.dump(c, f, indent=2, ensure_ascii=False)
+    (out_dir / "triggers").mkdir(exist_ok=True)
+    for t in triggers:
+        with open(out_dir / "triggers" / f"{t['id']}.json", "w") as f:
+            json.dump(t, f, indent=2, ensure_ascii=False)
+
+
+def write_test_pairs(out_dir: Path, triggers, rnd: random.Random):
+    """Pick 30 (merchant, trigger) pairs covering all kinds. Same set for everyone."""
+    by_kind = {}
+    for t in triggers:
+        by_kind.setdefault(t["kind"], []).append(t)
+    pairs = []
+    test_id = 1
+    for kind, ts in sorted(by_kind.items()):
+        for t in ts[:2]:  # take up to 2 per kind
+            pairs.append({"test_id": f"T{test_id:02d}", "trigger_id": t["id"],
+                          "merchant_id": t["merchant_id"], "customer_id": t.get("customer_id")})
+            test_id += 1
+            if len(pairs) >= 30: break
+        if len(pairs) >= 30: break
+    with open(out_dir / "test_pairs.json", "w") as f:
+        json.dump({"pairs": pairs[:30]}, f, indent=2)
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--seed-dir", default=".", help="Directory containing the seed JSON files")
+    parser.add_argument("--out", default="./expanded", help="Output directory")
+    args = parser.parse_args()
+
+    rnd = random.Random(SEED)
+    seed_dir = Path(args.seed_dir).resolve()
+    out_dir = Path(args.out).resolve()
+    print(f"Reading seeds from {seed_dir}")
+    print(f"Writing to {out_dir}")
+
+    categories, m_seeds, c_seeds, t_seeds = load_seeds(seed_dir)
+    print(f"  Loaded {len(categories)} categories, {len(m_seeds)} merchant seeds, "
+          f"{len(c_seeds)} customer seeds, {len(t_seeds)} trigger seeds")
+
+    merchants = expand_merchants(m_seeds, rnd)
+    customers = expand_customers(c_seeds, merchants, rnd)
+    triggers = expand_triggers(t_seeds, merchants, customers, rnd)
+    print(f"  Expanded to {len(merchants)} merchants, {len(customers)} customers, {len(triggers)} triggers")
+
+    write_outputs(out_dir, categories, merchants, customers, triggers)
+    write_test_pairs(out_dir, triggers, rnd)
+    print(f"Done. Run: ls {out_dir}")
+
+
+if __name__ == "__main__":
+    main()

dataset/merchants_seed.json

@@ -0,0 +1,314 @@
+{
+  "_README": "10 representative MerchantContexts. The generator (generate_dataset.py) expands these to 50 total (10/category) by varying identity + perf numbers deterministically.",
+  "merchants": [
+    {
+      "merchant_id": "m_001_drmeera_dentist_delhi",
+      "category_slug": "dentists",
+      "identity": {
+        "name": "Dr. Meera's Dental Clinic",
+        "city": "Delhi",
+        "locality": "Lajpat Nagar",
+        "place_id": "ChIJ_LAJPATNAGAR_DENTIST_001",
+        "verified": true,
+        "languages": ["en", "hi"],
+        "owner_first_name": "Meera",
+        "established_year": 2018
+      },
+      "subscription": { "status": "active", "plan": "Pro", "days_remaining": 82, "renewed_at": "2026-02-04" },
+      "performance": {
+        "window_days": 30,
+        "views": 2410, "calls": 18, "directions": 45, "ctr": 0.021, "leads": 9,
+        "delta_7d": { "views_pct": 0.18, "calls_pct": -0.05, "ctr_pct": 0.02 }
+      },
+      "offers": [
+        { "id": "o_meera_001", "title": "Dental Cleaning @ ₹299", "status": "active", "started": "2026-03-01" },
+        { "id": "o_meera_002", "title": "Deep Cleaning @ ₹499", "status": "expired", "ended": "2026-02-28" }
+      ],
+      "conversation_history": [
+        { "ts": "2026-04-24T10:12:00Z", "from": "vera", "body": "Profile audit done — your photos are 8/10, description complete, but Google posts are stale (last post 22 days ago). Want me to draft 3 posts you can review?", "engagement": "merchant_replied" },
+        { "ts": "2026-04-24T10:18:00Z", "from": "merchant", "body": "Yes please, focus on whitening and aligners", "engagement": "intent_action" }
+      ],
+      "customer_aggregate": { "total_unique_ytd": 540, "lapsed_180d_plus": 78, "retention_6mo_pct": 0.38, "high_risk_adult_count": 124 },
+      "signals": ["stale_posts:22d", "ctr_below_peer_median", "high_risk_adult_cohort", "engaged_in_last_48h"],
+      "review_themes": [
+        { "theme": "wait_time", "sentiment": "neg", "occurrences_30d": 3, "common_quote": "had to wait 30 min on Sunday afternoon" },
+        { "theme": "doctor_manner", "sentiment": "pos", "occurrences_30d": 5, "common_quote": "Dr. Meera explains everything patiently" }
+      ]
+    },
+    {
+      "merchant_id": "m_002_bharat_dentist_mumbai",
+      "category_slug": "dentists",
+      "identity": {
+        "name": "Bharat Dental Care",
+        "city": "Mumbai",
+        "locality": "Andheri West",
+        "place_id": "ChIJ_ANDHERI_DENTIST_002",
+        "verified": false,
+        "languages": ["en", "hi", "mr"],
+        "owner_first_name": "Bharat",
+        "established_year": 2010
+      },
+      "subscription": { "status": "active", "plan": "Pro", "days_remaining": 12, "renewed_at": "2025-04-26" },
+      "performance": {
+        "window_days": 30,
+        "views": 980, "calls": 4, "directions": 18, "ctr": 0.018, "leads": 2,
+        "delta_7d": { "views_pct": -0.22, "calls_pct": -0.50, "ctr_pct": -0.10 }
+      },
+      "offers": [],
+      "conversation_history": [
+        { "ts": "2026-04-10T11:00:00Z", "from": "vera", "body": "Subscription expires in 16 days — Bharat Dental Care...", "engagement": "merchant_no_reply" }
+      ],
+      "customer_aggregate": { "total_unique_ytd": 220, "lapsed_180d_plus": 95, "retention_6mo_pct": 0.18 },
+      "signals": ["renewal_due_soon:12d", "perf_dip_severe", "unverified_gbp", "dormant_with_vera_14d", "no_active_offers"],
+      "review_themes": []
+    },
+    {
+      "merchant_id": "m_003_studio11_salon_hyderabad",
+      "category_slug": "salons",
+      "identity": {
+        "name": "Studio11 Family Salon",
+        "city": "Hyderabad",
+        "locality": "Kapra",
+        "place_id": "ChIJ_KAPRA_SALON_003",
+        "verified": true,
+        "languages": ["en", "hi", "te"],
+        "owner_first_name": "Lakshmi",
+        "established_year": 2019
+      },
+      "subscription": { "status": "active", "plan": "Pro", "days_remaining": 145 },
+      "performance": {
+        "window_days": 30,
+        "views": 4980, "calls": 62, "directions": 142, "ctr": 0.048, "leads": 38,
+        "delta_7d": { "views_pct": 0.14, "calls_pct": 0.20, "ctr_pct": 0.05 }
+      },
+      "offers": [
+        { "id": "o_studio11_001", "title": "Haircut @ ₹99", "status": "active", "started": "2026-03-01" },
+        { "id": "o_studio11_002", "title": "Hair Spa @ ₹499", "status": "active", "started": "2026-03-15" }
+      ],
+      "conversation_history": [
+        { "ts": "2026-04-22T15:00:00Z", "from": "vera", "body": "Spotted: bridal-trial searches in Kapra +28% this week. Want me to push your bridal package as a GBP post?", "engagement": "merchant_no_reply" }
+      ],
+      "customer_aggregate": { "total_unique_ytd": 1150, "lapsed_90d_plus": 220, "retention_3mo_pct": 0.62 },
+      "signals": ["high_engagement", "above_peer_median_calls", "growing_views_7d"],
+      "review_themes": [
+        { "theme": "stylist_skill", "sentiment": "pos", "occurrences_30d": 12, "common_quote": "Priya is the best for balayage" },
+        { "theme": "saturday_wait", "sentiment": "neg", "occurrences_30d": 2 }
+      ]
+    },
+    {
+      "merchant_id": "m_004_glamour_salon_pune",
+      "category_slug": "salons",
+      "identity": {
+        "name": "Glamour Lounge Spa & Salon",
+        "city": "Pune",
+        "locality": "Aundh",
+        "place_id": "ChIJ_AUNDH_SALON_004",
+        "verified": true,
+        "languages": ["en", "hi", "mr"],
+        "owner_first_name": "Anjali",
+        "established_year": 2021
+      },
+      "subscription": { "status": "expired", "plan": "Pro", "days_since_expiry": 38 },
+      "performance": {
+        "window_days": 30,
+        "views": 1200, "calls": 8, "directions": 22, "ctr": 0.022, "leads": 3,
+        "delta_7d": { "views_pct": -0.12, "calls_pct": -0.30, "ctr_pct": -0.04 }
+      },
+      "offers": [],
+      "conversation_history": [
+        { "ts": "2026-03-19T14:00:00Z", "from": "vera", "body": "Subscription expired. Profile maintenance paused...", "engagement": "merchant_no_reply" }
+      ],
+      "customer_aggregate": { "total_unique_ytd": 380, "lapsed_90d_plus": 180, "retention_3mo_pct": 0.32 },
+      "signals": ["winback_eligible", "perf_dip_post_expiry", "dormant_with_vera_38d"],
+      "review_themes": []
+    },
+    {
+      "merchant_id": "m_005_pizzajunction_restaurant_delhi",
+      "category_slug": "restaurants",
+      "identity": {
+        "name": "SK Pizza Junction",
+        "city": "Delhi",
+        "locality": "Sant Nagar",
+        "place_id": "ChIJ_SANTNAGAR_RESTAURANT_005",
+        "verified": false,
+        "languages": ["en", "hi"],
+        "owner_first_name": "Suresh",
+        "established_year": 2022
+      },
+      "subscription": { "status": "trial", "plan": "Trial", "days_remaining": 7 },
+      "performance": {
+        "window_days": 30,
+        "views": 2200, "calls": 12, "directions": 38, "ctr": 0.020, "leads": 4,
+        "delta_7d": { "views_pct": 0.08, "calls_pct": 0.10 }
+      },
+      "offers": [
+        { "id": "o_skpz_001", "title": "Buy 1 Pizza Get 1 Free (Tue-Thu)", "status": "active", "started": "2026-04-15" }
+      ],
+      "conversation_history": [
+        { "ts": "2026-04-25T18:00:00Z", "from": "vera", "body": "Quick check — IPL match nights driving any extra footfall?", "engagement": "merchant_no_reply" }
+      ],
+      "customer_aggregate": { "total_unique_ytd": 0, "delivery_orders_30d": 180, "dine_in_orders_30d": 95 },
+      "signals": ["new_merchant", "trial_ending_soon", "ipl_eligible_locality"],
+      "review_themes": [
+        { "theme": "delivery_late", "sentiment": "neg", "occurrences_30d": 4 },
+        { "theme": "pizza_quality", "sentiment": "pos", "occurrences_30d": 8 }
+      ]
+    },
+    {
+      "merchant_id": "m_006_southindiancafe_restaurant_bangalore",
+      "category_slug": "restaurants",
+      "identity": {
+        "name": "Mylari South Indian Cafe",
+        "city": "Bangalore",
+        "locality": "Indiranagar",
+        "place_id": "ChIJ_INDIRANAGAR_RESTAURANT_006",
+        "verified": true,
+        "languages": ["en", "hi", "kn"],
+        "owner_first_name": "Suresh",
+        "established_year": 2014
+      },
+      "subscription": { "status": "active", "plan": "Pro", "days_remaining": 240 },
+      "performance": {
+        "window_days": 30,
+        "views": 12400, "calls": 88, "directions": 320, "ctr": 0.032, "leads": 145,
+        "delta_7d": { "views_pct": 0.05, "calls_pct": 0.02 }
+      },
+      "offers": [
+        { "id": "o_mylari_001", "title": "Weekday Lunch Thali @ ₹149", "status": "active", "started": "2026-01-10" }
+      ],
+      "conversation_history": [
+        { "ts": "2026-04-25T11:00:00Z", "from": "vera", "body": "Your weekday thali is doing well — 18 orders/day avg. Want me to add a corporate-bulk version?", "engagement": "merchant_replied" },
+        { "ts": "2026-04-25T11:30:00Z", "from": "merchant", "body": "Yes good idea, what would it look like", "engagement": "intent_question" }
+      ],
+      "customer_aggregate": { "total_unique_ytd": 4200, "repeat_customer_pct": 0.42, "delivery_share_pct": 0.45 },
+      "signals": ["high_volume", "stable_growth", "engaged_in_last_24h"],
+      "review_themes": [
+        { "theme": "thali_quality", "sentiment": "pos", "occurrences_30d": 22 },
+        { "theme": "weekend_busy", "sentiment": "neg", "occurrences_30d": 3 }
+      ]
+    },
+    {
+      "merchant_id": "m_007_powerhouse_gym_bangalore",
+      "category_slug": "gyms",
+      "identity": {
+        "name": "PowerHouse Fitness",
+        "city": "Bangalore",
+        "locality": "HSR Layout",
+        "place_id": "ChIJ_HSR_GYM_007",
+        "verified": true,
+        "languages": ["en", "hi", "kn"],
+        "owner_first_name": "Karthik",
+        "established_year": 2020
+      },
+      "subscription": { "status": "active", "plan": "Pro", "days_remaining": 95 },
+      "performance": {
+        "window_days": 30,
+        "views": 1480, "calls": 22, "directions": 48, "ctr": 0.052, "leads": 14,
+        "delta_7d": { "views_pct": -0.30, "calls_pct": -0.35 }
+      },
+      "offers": [
+        { "id": "o_powerhouse_001", "title": "3 FREE Trial Classes", "status": "active", "started": "2026-01-01" }
+      ],
+      "conversation_history": [],
+      "customer_aggregate": { "total_active_members": 245, "monthly_churn_pct": 0.10, "trial_to_paid_pct": 0.28 },
+      "signals": ["seasonal_dip_apr_may", "above_peer_ctr", "no_recent_post"],
+      "review_themes": [
+        { "theme": "equipment_quality", "sentiment": "pos", "occurrences_30d": 7 },
+        { "theme": "morning_crowd", "sentiment": "neg", "occurrences_30d": 4 }
+      ]
+    },
+    {
+      "merchant_id": "m_008_zenyoga_gym_chennai",
+      "category_slug": "gyms",
+      "identity": {
+        "name": "Zen Yoga Studio",
+        "city": "Chennai",
+        "locality": "Mylapore",
+        "place_id": "ChIJ_MYLAPORE_GYM_008",
+        "verified": true,
+        "languages": ["en", "ta", "hi"],
+        "owner_first_name": "Padma",
+        "established_year": 2017
+      },
+      "subscription": { "status": "active", "plan": "Pro", "days_remaining": 180 },
+      "performance": {
+        "window_days": 30,
+        "views": 880, "calls": 18, "directions": 38, "ctr": 0.062, "leads": 12,
+        "delta_7d": { "views_pct": 0.10, "calls_pct": 0.15 }
+      },
+      "offers": [
+        { "id": "o_zen_001", "title": "First Month @ ₹499", "status": "active", "started": "2026-03-01" },
+        { "id": "o_zen_002", "title": "Free Body Composition Analysis", "status": "active", "started": "2026-03-01" }
+      ],
+      "conversation_history": [
+        { "ts": "2026-04-23T09:00:00Z", "from": "merchant", "body": "Hi I want to add a kids yoga program — what should it look like?", "engagement": "intent_planning" },
+        { "ts": "2026-04-23T09:05:00Z", "from": "vera", "body": "Great idea — kids yoga summer camps are peaking now. Suggest 4-week program, 3 classes/week, age 7-12, ₹2,499. Want me to draft the GBP post + Insta carousel?", "engagement": "merchant_replied" }
+      ],
+      "customer_aggregate": { "total_active_members": 95, "monthly_churn_pct": 0.05, "trial_to_paid_pct": 0.55 },
+      "signals": ["high_retention", "active_planning", "boutique_segment"],
+      "review_themes": [
+        { "theme": "instructor_quality", "sentiment": "pos", "occurrences_30d": 9 },
+        { "theme": "small_classes", "sentiment": "pos", "occurrences_30d": 6 }
+      ]
+    },
+    {
+      "merchant_id": "m_009_apollo_pharmacy_jaipur",
+      "category_slug": "pharmacies",
+      "identity": {
+        "name": "Apollo Health Plus Pharmacy",
+        "city": "Jaipur",
+        "locality": "Malviya Nagar",
+        "place_id": "ChIJ_MALVIYA_PHARMACY_009",
+        "verified": true,
+        "languages": ["en", "hi"],
+        "owner_first_name": "Ramesh",
+        "established_year": 2016
+      },
+      "subscription": { "status": "active", "plan": "Pro", "days_remaining": 60 },
+      "performance": {
+        "window_days": 30,
+        "views": 1850, "calls": 38, "directions": 95, "ctr": 0.045, "leads": 24,
+        "delta_7d": { "views_pct": 0.06, "calls_pct": 0.08 }
+      },
+      "offers": [
+        { "id": "o_apollo_001", "title": "Free Home Delivery > ₹499", "status": "active", "started": "2026-01-01" },
+        { "id": "o_apollo_002", "title": "Senior Citizen 15% OFF", "status": "active", "started": "2026-01-01" }
+      ],
+      "conversation_history": [
+        { "ts": "2026-04-24T08:00:00Z", "from": "vera", "body": "Heads up: voluntary recall on atorvastatin batches X/Y by Mfr Z. Want the customer list filtered for that molecule?", "engagement": "merchant_replied" },
+        { "ts": "2026-04-24T08:30:00Z", "from": "merchant", "body": "Yes send me the list please", "engagement": "intent_action" }
+      ],
+      "customer_aggregate": { "total_unique_ytd": 1820, "repeat_customer_pct": 0.68, "chronic_rx_count": 240 },
+      "signals": ["above_peer_calls", "compliance_aware", "high_repeat_rate"],
+      "review_themes": [
+        { "theme": "delivery_speed", "sentiment": "pos", "occurrences_30d": 11 },
+        { "theme": "medicine_availability", "sentiment": "pos", "occurrences_30d": 8 }
+      ]
+    },
+    {
+      "merchant_id": "m_010_sunrisepharm_pharmacy_lucknow",
+      "category_slug": "pharmacies",
+      "identity": {
+        "name": "Sunrise Medicos",
+        "city": "Lucknow",
+        "locality": "Gomti Nagar",
+        "place_id": "ChIJ_GOMTINAGAR_PHARMACY_010",
+        "verified": false,
+        "languages": ["en", "hi"],
+        "owner_first_name": "Vikas",
+        "established_year": 2020
+      },
+      "subscription": { "status": "active", "plan": "Basic", "days_remaining": 200 },
+      "performance": {
+        "window_days": 30,
+        "views": 720, "calls": 14, "directions": 32, "ctr": 0.041, "leads": 8,
+        "delta_7d": { "views_pct": 0.02, "calls_pct": 0.05 }
+      },
+      "offers": [],
+      "conversation_history": [],
+      "customer_aggregate": { "total_unique_ytd": 540, "repeat_customer_pct": 0.45, "chronic_rx_count": 60 },
+      "signals": ["unverified_gbp", "no_active_offers", "no_recent_conversation", "delivery_not_set_up"],
+      "review_themes": []
+    }
+  ]
+}

dataset/triggers_seed.json

@@ -0,0 +1,180 @@
+{
+  "_README": "25 representative TriggerContexts spanning external + internal, merchant + customer scope, all kinds. Generator expands to 100.",
+  "triggers": [
+    {
+      "id": "trg_001_research_digest_dentists",
+      "scope": "merchant", "kind": "research_digest", "source": "external",
+      "merchant_id": "m_001_drmeera_dentist_delhi", "customer_id": null,
+      "payload": { "category": "dentists", "top_item_id": "d_2026W17_jida_fluoride" },
+      "urgency": 2, "suppression_key": "research:dentists:2026-W17", "expires_at": "2026-05-03T00:00:00Z"
+    },
+    {
+      "id": "trg_002_compliance_dci_radiograph",
+      "scope": "merchant", "kind": "regulation_change", "source": "external",
+      "merchant_id": "m_001_drmeera_dentist_delhi", "customer_id": null,
+      "payload": { "category": "dentists", "top_item_id": "d_2026W17_dci_radiograph", "deadline_iso": "2026-12-15" },
+      "urgency": 4, "suppression_key": "compliance:dci_radiograph:2026", "expires_at": "2026-12-15T00:00:00Z"
+    },
+    {
+      "id": "trg_003_recall_due_priya",
+      "scope": "customer", "kind": "recall_due", "source": "internal",
+      "merchant_id": "m_001_drmeera_dentist_delhi", "customer_id": "c_001_priya_for_m001",
+      "payload": { "service_due": "6_month_cleaning", "last_service_date": "2026-05-12", "due_date": "2026-11-12", "available_slots": [{ "iso": "2026-11-05T18:00:00+05:30", "label": "Wed 5 Nov, 6pm" }, { "iso": "2026-11-06T17:00:00+05:30", "label": "Thu 6 Nov, 5pm" }] },
+      "urgency": 3, "suppression_key": "recall:c_001_priya_for_m001:6mo", "expires_at": "2026-11-30T00:00:00Z"
+    },
+    {
+      "id": "trg_004_perf_dip_bharat",
+      "scope": "merchant", "kind": "perf_dip", "source": "internal",
+      "merchant_id": "m_002_bharat_dentist_mumbai", "customer_id": null,
+      "payload": { "metric": "calls", "delta_pct": -0.50, "window": "7d", "vs_baseline": 12 },
+      "urgency": 4, "suppression_key": "perf_dip:m_002_bharat_dentist_mumbai:calls:2026-W17", "expires_at": "2026-05-10T00:00:00Z"
+    },
+    {
+      "id": "trg_005_renewal_due_bharat",
+      "scope": "merchant", "kind": "renewal_due", "source": "internal",
+      "merchant_id": "m_002_bharat_dentist_mumbai", "customer_id": null,
+      "payload": { "days_remaining": 12, "plan": "Pro", "renewal_amount": 4999 },
+      "urgency": 4, "suppression_key": "renewal:m_002_bharat_dentist_mumbai:2026-Q2", "expires_at": "2026-05-08T00:00:00Z"
+    },
+    {
+      "id": "trg_006_festival_diwali",
+      "scope": "merchant", "kind": "festival_upcoming", "source": "external",
+      "merchant_id": "m_003_studio11_salon_hyderabad", "customer_id": null,
+      "payload": { "festival": "Diwali", "date": "2026-10-31", "days_until": 188, "category_relevance": ["salons", "restaurants", "pharmacies"] },
+      "urgency": 1, "suppression_key": "festival:diwali:2026:m_003", "expires_at": "2026-11-02T00:00:00Z"
+    },
+    {
+      "id": "trg_007_bridal_followup_kavya",
+      "scope": "customer", "kind": "wedding_package_followup", "source": "internal",
+      "merchant_id": "m_003_studio11_salon_hyderabad", "customer_id": "c_005_kavya_for_m003",
+      "payload": { "wedding_date": "2026-11-08", "trial_completed": "2026-03-22", "days_to_wedding": 196, "next_step_window_open": "skin_prep_program_30day" },
+      "urgency": 2, "suppression_key": "bridal_followup:c_005_kavya_for_m003", "expires_at": "2026-11-08T00:00:00Z"
+    },
+    {
+      "id": "trg_008_curious_ask_studio11",
+      "scope": "merchant", "kind": "curious_ask_due", "source": "internal",
+      "merchant_id": "m_003_studio11_salon_hyderabad", "customer_id": null,
+      "payload": { "ask_template": "what_service_in_demand_this_week", "last_ask_at": null },
+      "urgency": 1, "suppression_key": "curious_ask:m_003:2026-W17", "expires_at": "2026-05-03T00:00:00Z"
+    },
+    {
+      "id": "trg_009_winback_glamour",
+      "scope": "merchant", "kind": "winback_eligible", "source": "internal",
+      "merchant_id": "m_004_glamour_salon_pune", "customer_id": null,
+      "payload": { "days_since_expiry": 38, "perf_dip_pct": -0.30, "lapsed_customers_added_since_expiry": 24 },
+      "urgency": 2, "suppression_key": "winback:m_004_glamour_salon_pune", "expires_at": "2026-06-15T00:00:00Z"
+    },
+    {
+      "id": "trg_010_ipl_match_delhi",
+      "scope": "merchant", "kind": "ipl_match_today", "source": "external",
+      "merchant_id": "m_005_pizzajunction_restaurant_delhi", "customer_id": null,
+      "payload": { "match": "DC vs MI", "venue": "Arun Jaitley Stadium", "city": "Delhi", "match_time_iso": "2026-04-26T19:30:00+05:30", "is_weeknight": false },
+      "urgency": 3, "suppression_key": "ipl:m_005:2026-04-26", "expires_at": "2026-04-26T23:59:59+05:30"
+    },
+    {
+      "id": "trg_011_review_theme_late_delivery",
+      "scope": "merchant", "kind": "review_theme_emerged", "source": "internal",
+      "merchant_id": "m_005_pizzajunction_restaurant_delhi", "customer_id": null,
+      "payload": { "theme": "delivery_late", "occurrences_30d": 4, "trend": "rising", "common_quote": "took 50 mins for a 15 min ride" },
+      "urgency": 3, "suppression_key": "review_theme:m_005:delivery_late:2026-W17", "expires_at": "2026-05-10T00:00:00Z"
+    },
+    {
+      "id": "trg_012_milestone_mylari",
+      "scope": "merchant", "kind": "milestone_reached", "source": "internal",
+      "merchant_id": "m_006_southindiancafe_restaurant_bangalore", "customer_id": null,
+      "payload": { "metric": "review_count", "value_now": 145, "milestone_value": 150, "is_imminent": true },
+      "urgency": 1, "suppression_key": "milestone:m_006:reviews_150", "expires_at": "2026-05-15T00:00:00Z"
+    },
+    {
+      "id": "trg_013_corporate_thali_planning",
+      "scope": "merchant", "kind": "active_planning_intent", "source": "internal",
+      "merchant_id": "m_006_southindiancafe_restaurant_bangalore", "customer_id": null,
+      "payload": { "intent_topic": "corporate_bulk_thali_package", "merchant_last_message": "Yes good idea, what would it look like" },
+      "urgency": 4, "suppression_key": "planning:m_006:corp_thali:2026-W17", "expires_at": "2026-04-29T00:00:00Z"
+    },
+    {
+      "id": "trg_014_seasonal_acquisition_dip_powerhouse",
+      "scope": "merchant", "kind": "seasonal_perf_dip", "source": "internal",
+      "merchant_id": "m_007_powerhouse_gym_bangalore", "customer_id": null,
+      "payload": { "metric": "views", "delta_pct": -0.30, "window": "7d", "is_expected_seasonal": true, "season_note": "post_resolution_window_apr_jun" },
+      "urgency": 1, "suppression_key": "seasonal_dip:m_007:2026-Q2", "expires_at": "2026-06-30T00:00:00Z"
+    },
+    {
+      "id": "trg_015_winback_rashmi",
+      "scope": "customer", "kind": "customer_lapsed_hard", "source": "internal",
+      "merchant_id": "m_007_powerhouse_gym_bangalore", "customer_id": "c_010_rashmi_for_m007",
+      "payload": { "days_since_last_visit": 57, "previous_focus": "weight_loss", "previous_membership_months": 5 },
+      "urgency": 3, "suppression_key": "winback:c_010_rashmi_for_m007", "expires_at": "2026-06-15T00:00:00Z"
+    },
+    {
+      "id": "trg_016_kids_yoga_program_drafting",
+      "scope": "merchant", "kind": "active_planning_intent", "source": "internal",
+      "merchant_id": "m_008_zenyoga_gym_chennai", "customer_id": null,
+      "payload": { "intent_topic": "kids_yoga_summer_camp", "merchant_last_message": "Hi I want to add a kids yoga program — what should it look like?" },
+      "urgency": 4, "suppression_key": "planning:m_008:kids_yoga:2026-W17", "expires_at": "2026-04-30T00:00:00Z"
+    },
+    {
+      "id": "trg_017_kids_yoga_trial_followup_karthik",
+      "scope": "customer", "kind": "trial_followup", "source": "internal",
+      "merchant_id": "m_008_zenyoga_gym_chennai", "customer_id": "c_012_karthik_jr_for_m008",
+      "payload": { "trial_date": "2026-04-22", "next_session_options": [{ "iso": "2026-05-03T08:00:00+05:30", "label": "Sat 3 May, 8am" }] },
+      "urgency": 2, "suppression_key": "trial_followup:c_012_karthik_jr_for_m008", "expires_at": "2026-05-10T00:00:00Z"
+    },
+    {
+      "id": "trg_018_supply_atorvastatin_recall",
+      "scope": "merchant", "kind": "supply_alert", "source": "external",
+      "merchant_id": "m_009_apollo_pharmacy_jaipur", "customer_id": null,
+      "payload": { "alert_id": "d_2026W17_atorvastatin_recall", "molecule": "atorvastatin", "affected_batches": ["AT2024-1102", "AT2024-1108"], "manufacturer": "MfrZ" },
+      "urgency": 5, "suppression_key": "alert:atorvastatin:2026-04", "expires_at": "2026-05-30T00:00:00Z"
+    },
+    {
+      "id": "trg_019_chronic_refill_grandfather",
+      "scope": "customer", "kind": "chronic_refill_due", "source": "internal",
+      "merchant_id": "m_009_apollo_pharmacy_jaipur", "customer_id": "c_013_grandfather_for_m009",
+      "payload": { "molecule_list": ["metformin", "atorvastatin", "telmisartan"], "last_refill": "2026-03-26", "stock_runs_out_iso": "2026-04-28T00:00:00+05:30", "delivery_address_saved": true },
+      "urgency": 3, "suppression_key": "refill:c_013_grandfather_for_m009:2026-04", "expires_at": "2026-04-28T00:00:00+05:30"
+    },
+    {
+      "id": "trg_020_summer_demand_shift",
+      "scope": "merchant", "kind": "category_seasonal", "source": "external",
+      "merchant_id": "m_009_apollo_pharmacy_jaipur", "customer_id": null,
+      "payload": { "season": "summer_2026", "trends": ["ORS_demand_+40", "sunscreen_demand_+38", "antifungal_demand_+45", "cold_cough_demand_-60"], "shelf_action_recommended": true },
+      "urgency": 2, "suppression_key": "season:summer:m_009:2026", "expires_at": "2026-06-30T00:00:00Z"
+    },
+    {
+      "id": "trg_021_unverified_gbp_sunrise",
+      "scope": "merchant", "kind": "gbp_unverified", "source": "internal",
+      "merchant_id": "m_010_sunrisepharm_pharmacy_lucknow", "customer_id": null,
+      "payload": { "verified": false, "verification_path": "postcard_or_phone_call", "estimated_uplift_pct": 0.30 },
+      "urgency": 3, "suppression_key": "unverified:m_010", "expires_at": "2026-05-30T00:00:00Z"
+    },
+    {
+      "id": "trg_022_cde_webinar_dentists",
+      "scope": "merchant", "kind": "cde_opportunity", "source": "external",
+      "merchant_id": "m_001_drmeera_dentist_delhi", "customer_id": null,
+      "payload": { "digest_item_id": "d_2026W17_ida_webinar", "credits": 2, "fee": "free_for_members" },
+      "urgency": 1, "suppression_key": "cde:dentists:2026-05-02", "expires_at": "2026-05-02T19:00:00+05:30"
+    },
+    {
+      "id": "trg_023_competitor_opened_dentist",
+      "scope": "merchant", "kind": "competitor_opened", "source": "external",
+      "merchant_id": "m_001_drmeera_dentist_delhi", "customer_id": null,
+      "payload": { "competitor_name": "Smile Studio", "distance_km": 1.3, "their_offer": "Dental Cleaning @ ₹199", "opened_date": "2026-04-08" },
+      "urgency": 2, "suppression_key": "competitor:m_001:smile_studio", "expires_at": "2026-06-08T00:00:00Z"
+    },
+    {
+      "id": "trg_024_perf_spike_zen",
+      "scope": "merchant", "kind": "perf_spike", "source": "internal",
+      "merchant_id": "m_008_zenyoga_gym_chennai", "customer_id": null,
+      "payload": { "metric": "calls", "delta_pct": 0.15, "window": "7d", "vs_baseline": 18, "likely_driver": "kids_yoga_post" },
+      "urgency": 1, "suppression_key": "perf_spike:m_008:calls:2026-W17", "expires_at": "2026-05-03T00:00:00Z"
+    },
+    {
+      "id": "trg_025_dormancy_glamour",
+      "scope": "merchant", "kind": "dormant_with_vera", "source": "internal",
+      "merchant_id": "m_004_glamour_salon_pune", "customer_id": null,
+      "payload": { "days_since_last_merchant_message": 38, "last_topic": "subscription_expiry" },
+      "urgency": 2, "suppression_key": "dormant:m_004:30d", "expires_at": "2026-05-30T00:00:00Z"
+    }
+  ]
+}

engagement-design.md

@@ -0,0 +1,325 @@
+# Vera Engagement Framework — Design
+
+**Status**: Draft proposal — not implemented.
+**Last updated**: 2026-04-26
+**Scope**: How Vera composes every outbound conversation, both merchant-facing and (on-behalf-of-merchant) customer-facing.
+
+---
+
+## Why this exists
+
+The current engagement loop (`agents/vera/followup/`) is a collection of ad-hoc nudges — campaign templates, performance reminders, conversation requeues. Each was built point-to-point, with hardcoded assumptions baked in. Adding a new nudge type means re-writing prompts, finding new data, and re-implementing send/dedup logic.
+
+Two problems this creates:
+
+1. **Functional nudges are inherently low-frequency.** A merchant only has a handful of "broken things" or "events" per month. To engage them 3-5×/week, we need a framework that supports curiosity-driven, knowledge-driven, and customer-driven conversations — not just "fix-this" reminders.
+
+2. **Same engine should drive merchant-facing AND customer-facing messages.** When Dr. Meera's clinic sends a recall reminder to her patient Priya, Vera does the work — but the framework for composing that message should be the same one that produces the research digest Vera sends to Dr. Meera herself.
+
+This doc proposes a **4-context composition framework** that separates the slow-changing (category knowledge) from the fast-changing (per-merchant, per-customer state) and the event-driven (triggers).
+
+---
+
+## The 4 contexts
+
+Every Vera message = `compose(category, merchant, trigger, customer?)`.
+
+| Context | Question it answers | Refresh cadence | Owner | Shared across |
+|---|---|---|---|---|
+| **Category** | How do we talk to *this type* of business? What do they know, care about, offer, get regulated on? | Weekly (digest), monthly (voice/catalog) | Domain curator | All merchants in the vertical |
+| **Merchant** | Who is this specific business, how are they doing, what's in their history with us? | Daily (perf), real-time (conversation) | Snapshot + conversation sync | Just this merchant |
+| **Trigger** | Why am I messaging *right now*? What specific event prompts this? | Per-event | Event detectors | This one send |
+| **Customer** | Who is the merchant's customer, and what's their state with this merchant? | Per-visit / per-interaction | Merchant CRM sync | Just this customer |
+
+The composer takes these 4 (3 if no customer scope) and produces the message body, template parameters, CTA, and suppression key. Nothing is hardcoded into the composer — all variation comes from the contexts.
+
+```
+                  ┌─────────────────┐
+   Category   ───►│                 │
+   Merchant   ───►│  Composer (LLM) │───► message {body, params, cta, send_as}
+   Trigger    ───►│                 │
+   Customer?  ───►│                 │
+                  └─────────────────┘
+```
+
+---
+
+## Layer details
+
+### CategoryContext
+
+Slow-changing knowledge pack per vertical. One per category (`dentists`, `salons`, `gyms`, `restaurants`, `car_service`, ...). Bootstrap is labor-intensive (needs domain expertise); ongoing maintenance is mostly the weekly digest.
+
+Fields:
+
+- `slug` — `"dentists"`
+- `offer_catalog` — canonical service+price patterns from vera-mcp + category-specific extensions. Prefer `"Dental Cleaning @ ₹299"` over `"Flat 20% OFF"`. Service+price is more compelling than discount.
+- `voice` — tone, vocabulary, taboos. For dentists: technical terms welcome (`"fluoride varnish at 3-month recall"`), legal taboos (`"cure"`, `"guaranteed"`), peer tone not hype.
+- `peer_stats` — city-scoped benchmarks: avg rating, avg reviews, typical CTR, typical patient volume. Anchors comparative messages.
+- `digest` — this week's curated research / compliance / CDE / tech / peer-practice items, with source citations. Sourced from a per-category source list (PubMed dental RSS, JIDA, IDA Delhi calendar, DCI circulars, Dental Tribune India, Google Trends for dental queries, vendor press releases).
+- `patient_content_library` — items written at patient-reading level that the merchant can reshare with their own customers (powers the `PRO_PATIENT_CONTENT` family).
+- `seasonal_beats` — cycles like "exam-stress bruxism spikes Nov-Feb" that cue category-specific timing.
+- `trend_signals` — Google Trends + Practo-style query data showing what patients in this vertical are searching for.
+
+### MerchantContext
+
+Per-merchant state. Refreshed daily for performance; real-time for conversation history.
+
+Fields:
+
+- `merchant_id`
+- `identity` — name, place_id, locality, city, verified, languages
+- `subscription` — status, days remaining, plan
+- `performance` — views/calls/CTR/leads/directions, 30d + 7d deltas
+- `offers` — active + paused, sourced from vera-mcp's offers collection (and eventually the as-yet-undefined "real" offer source-of-truth)
+- `conversation_history` — last N turns w/ Vera, with engagement tags (replied, ignored, unsubscribed-from-topic)
+- `customer_aggregate` — derived stats over the merchant's customer roster (active count, lapsed count, retention rate). Not individual customers — aggregates only.
+- `signals` — derived flags: `stale_posts`, `ctr_below_peer_median`, `customer_lapse_rate_high`, `dormant_with_vera`, ...
+
+### TriggerContext
+
+The event that prompts this specific message. Two families:
+
+- **External** — happens outside the merchant's account. News, weather, festival, regulation change, category-trend movement, competitor opens nearby, weekly research digest release.
+- **Internal** — happens within the merchant's account or customer roster. Performance dip/spike, milestone hit, dormancy threshold crossed, customer lapse threshold crossed, appointment due, review pattern emerged, scheduled-recurring nudge.
+
+Fields:
+
+- `id` — unique
+- `scope` — `merchant` | `customer`
+- `kind` — `research_digest`, `recall_due`, `perf_spike`, `competitor_opened`, `festival`, ...
+- `source` — `external` | `internal`
+- `payload` — kind-specific data (e.g., for `recall_due`: `{patient_id, last_visit, due_date}`)
+- `urgency` — 1-5; ranks against other queued triggers
+- `suppression_key` — used by Redis dedup to prevent re-sends
+- `expires_at` — after which the trigger is stale
+
+### CustomerContext
+
+Only populated when `scope=customer`. Per-customer state with this specific merchant.
+
+Fields:
+
+- `customer_id`
+- `merchant_id`
+- `identity` — name, phone, language preference
+- `relationship` — first_visit, last_visit, visits_total, services received, lifetime value
+- `state` — `new` | `active` | `lapsed_soft` (3-6mo) | `lapsed_hard` (6mo+) | `churned` (12mo+)
+- `preferences` — preferred slot times (derived from booking history), preferred channel, opt-in status
+- `consent` — when did they opt in, via what mechanism, scope of consent
+
+---
+
+## Composer
+
+Single LLM-prompted module. Takes the 4 contexts as input. Produces:
+
+- `body` — the WhatsApp message body
+- `template_params` — params to fill an approved Kaleyra template (used only for the first touch in a session window)
+- `cta` — the binary or open-ended ask
+- `suppression_key` — for the trigger-level dedup
+- `send_as` — `"vera"` for merchant-facing, `"merchant_on_behalf"` for customer-facing
+
+The composer prompt is the single point of failure. It must be:
+
+- Versioned (`composer_v1`, `composer_v2`, ...)
+- A/B-testable
+- Auditable (we can replay any past message and see all 4 input contexts)
+
+Different `kind` values may use different prompt variants — e.g., `research_digest` needs source-citation framing, `recall_due` needs slot-offering framing, `competitor_opened` needs voyeur-curiosity framing. The composer dispatches by `kind`.
+
+---
+
+## Worked example 1: merchant-facing
+
+**Merchant**: Dr. Meera, Lajpat Nagar, Delhi
+**Trigger**: weekly dentistry research digest just landed
+
+**Inputs:**
+
+| Context | Key values used |
+|---|---|
+| Category (dentists) | voice=peer/technical; digest_top_item="JIDA Oct trial: 3-mo fluoride recall cuts caries 38% better"; peer_stat="South-Delhi solo CTR median 3.0%" |
+| Merchant (Dr. Meera) | CTR 2.1% (below peer); ran "Deep Cleaning ₹499" 2mo ago; 78 lapsed patients; last Vera touch 2d ago (engaged) |
+| Trigger | kind=`research_digest_release`, scope=merchant, urgency=2, source=external, suppression_key=`research:dentists:2026-W17` |
+| Customer | (not populated) |
+
+**Composed message:**
+
+> Dr. Meera, JIDA's Oct issue landed. One item relevant to your high-risk adult patients — 2,100-patient trial showed 3-month fluoride recall cuts caries recurrence 38% better than 6-month. Worth a look (2-min abstract). Want me to pull it + draft a patient-ed WhatsApp you can share?  *— JIDA Oct 2026 p.14*
+
+Why it works:
+- **Category** drives voice (technical, source-cited, peer tone)
+- **Merchant** drives specificity ("your high-risk adult patients" — derived from her customer aggregate)
+- **Trigger** drives the hook (this week's digest, not a promo ask)
+- No customer context needed; this is merchant-to-Vera
+
+---
+
+## Worked example 2: customer-facing (same framework)
+
+**Merchant**: Dr. Meera (same)
+**Customer**: Priya — patient since 2025-11, last visit 2026-05 (cleaning + whitening), prefers weekday evenings, opted-in to reminders
+**Trigger**: 6-month recall window opens
+
+**Inputs:**
+
+| Context | Key values used |
+|---|---|
+| Category (dentists, customer-facing) | voice=warm-clinical; taboos=no medical claims, no "guaranteed"; recall framing pattern |
+| Merchant (Dr. Meera) | active offer `Dental Cleaning @ ₹299`; available slots Wed 6pm + Thu 5pm (next 7d); WhatsApp Business number |
+| Trigger | kind=`recall_due`, scope=customer, urgency=3, source=internal, payload={patient_id: priya, last_visit: 2026-05, due_date: 2026-11} |
+| Customer (Priya) | name + phone; lapsed_soft state; preferred=weekday evening; consent active; language=Hindi-English mix |
+
+**Composed message** (sent from Dr. Meera's WhatsApp number, drafted by Vera):
+
+> Hi Priya, Dr. Meera's clinic here 🦷 It's been 5 months since your last visit — your 6-month cleaning recall is due. Apke liye 2 slots ready hain: **Wed 6 Nov, 6pm** ya **Thu 7 Nov, 5pm**. ₹299 cleaning + complimentary fluoride. Reply 1 for Wed, 2 for Thu, or tell us a time that works.
+
+Why it works:
+- **Category** sets the legal/clinical voice constraints
+- **Merchant** provides the actual catalog price + actual open slots from the schedule
+- **Trigger** provides the recall payload (last_visit, due_date)
+- **Customer** drives personalization (name, language mix, evening preference)
+
+Same composer. Different context inputs. Two completely different conversations.
+
+---
+
+## Engagement loops this enables
+
+Once the framework exists, every loop is just a small cron that emits `TriggerContext` instances. The composer handles the rest.
+
+| Loop | Emits trigger kinds | Scope |
+|---|---|---|
+| News/weather scanner *(already built — see `agents/vera/followup/event_sources.py`)* | `external` (festival, heatwave, fuel, IPL, monsoon, news) | merchant |
+| Weekly research digest per category | `research_digest_release` | merchant |
+| Performance monitor | `perf_spike`, `perf_dip`, `milestone_reached` | merchant |
+| Review-pattern detector | `review_theme_emerged` | merchant |
+| Conversation curiosity-ask scheduler | `curious_ask_due` | merchant |
+| Recall scheduler (from merchant CRM) | `recall_due` | customer |
+| Lapse detector | `customer_lapsed_soft`, `customer_lapsed_hard` | customer |
+| Appointment reminder | `appointment_tomorrow` | customer |
+| Capacity optimizer | `unplanned_slot_open` (offered to likely-to-book lapsed customers) | customer |
+
+Adding a loop = define one new `kind`, implement the detector, add a composer prompt variant. No change to merchant/category/customer code.
+
+---
+
+## Implementation shape
+
+```python
+# agents/vera/engagement/contexts.py
+
+@dataclass
+class CategoryContext:
+    slug: str                                # "dentists"
+    offer_catalog: list[OfferTemplate]
+    voice: VoiceProfile
+    peer_stats: PeerStats
+    digest: list[DigestItem]
+    patient_content_library: list[ContentItem]
+    seasonal_beats: list[SeasonalBeat]
+    trend_signals: list[TrendSignal]
+
+@dataclass
+class MerchantContext:
+    merchant_id: str
+    identity: Identity
+    subscription: Subscription
+    performance: PerformanceSnapshot
+    offers: list[MerchantOffer]
+    conversation_history: ConversationHistory
+    customer_aggregate: CustomerAggregate
+    signals: list[DerivedSignal]
+
+@dataclass
+class TriggerContext:
+    id: str
+    scope: Literal["merchant", "customer"]
+    kind: str
+    source: Literal["external", "internal"]
+    payload: dict
+    urgency: int                              # 1-5
+    suppression_key: str
+    expires_at: datetime
+
+@dataclass
+class CustomerContext:
+    customer_id: str
+    merchant_id: str
+    identity: CustomerIdentity
+    relationship: Relationship
+    state: Literal["new", "active", "lapsed_soft", "lapsed_hard", "churned"]
+    preferences: Preferences
+    consent: Consent
+```
+
+```python
+# agents/vera/engagement/composer.py
+
+class EngagementComposer:
+    def compose(self,
+                category: CategoryContext,
+                merchant: MerchantContext,
+                trigger: TriggerContext,
+                customer: CustomerContext | None = None) -> ComposedMessage:
+        """Returns ComposedMessage(body, template_params, cta,
+        suppression_key, send_as)."""
+```
+
+Both engagement surfaces (merchant-facing, customer-on-behalf-of-merchant) call the same composer. The only thing that changes is whether `customer` is populated.
+
+---
+
+## Phased rollout
+
+### Phase 1 — framework skeleton + dentistry vertical (≈ 2 weeks)
+
+1. Define the 4 dataclasses in `agents/vera/engagement/contexts.py`.
+2. Build the `CategoryContext` for dentistry — offer catalog, voice profile, peer stats, one weekly research digest pipeline, patient-content seed.
+3. Build `MerchantContext` loader from the existing `merchant_snapshot_data` collection.
+4. Build the first `EngagementComposer` with a prompt that handles 2 trigger kinds (`research_digest_release` and one merchant-facing perf trigger).
+5. Render (no send) the Dr. Meera research-digest message end-to-end from the 4 contexts. Inspect the output before any send happens.
+
+### Phase 2 — customer-on-behalf sends (≈ 2 weeks)
+
+6. **Resolve the customer-data source-of-truth.** This is the biggest unknown. Options: clinic SaaS integration (Practo, Dentcubate), merchant CSV upload, BOTOPS chat-derived patient list. Without this, customer engagement is theoretical.
+7. Define the consent model: customer opted in via merchant, not via Vera directly. Capture timestamp + scope.
+8. Stand up a send-as-merchant channel: WhatsApp Business API under the merchant's number, or Vera's shared number with attribution `"Dr. Meera's clinic via Vera"`.
+9. Ship the first customer-facing trigger in production: `recall_due`. Lowest abuse risk, highest merchant intent.
+
+### Phase 3 — multiply verticals (≈ 1 week per vertical)
+
+10. Replicate `CategoryContext` for 4-5 more verticals (salons, gyms, pharmacies, restaurants, car service). Mostly data filling, not code.
+11. Add 3 more triggers per scope. Merchant: `perf_dip`, `milestone_reached`, `review_theme_emerged`. Customer: `customer_lapsed_soft`, `appointment_tomorrow`, `unplanned_slot_open`.
+
+---
+
+## Open questions
+
+These need answers before Phase 2 can ship:
+
+1. **Where does the merchant's customer list live?** No clean answer yet. Most likely: per-merchant clinic software with no standard integration. May need a self-serve CSV upload or a per-vertical SaaS adapter.
+2. **Consent architecture.** Can Vera message a patient directly, or must every outbound require merchant approval before send? Recommendation: templated auto-sends with merchant override available, switching to fully-auto after the merchant has approved N consecutive sends.
+3. **Attribution.** Does the patient see "Dr. Meera's clinic" or "Vera on behalf of Dr. Meera's clinic"? Trust + legal implications either way. Probably category-dependent (regulated verticals need clearer attribution).
+4. **Composer prompt versioning.** Single point of failure. Versioned + A/B tested from day 1 — every send records the prompt version that produced it.
+5. **Offer source-of-truth.** Per the parallel discussion, the canonical merchant offer catalog likely lives outside vera-mcp (aryan `catalogoffer`, merchant-portal-api, or magicpin_jobs output). MerchantContext needs to read from that source — pending identification.
+6. **Composer model choice.** Azure OpenAI primary, Deepseek fallback (matching `template_generator._call_llm`)? Or is there a case for a smaller faster model for high-volume per-customer sends?
+
+---
+
+## Why this is worth building
+
+- **Engagement frequency goes from "few times a month" to "few times a week"** — by adding curiosity-driven, knowledge-driven, and customer-driven loops on top of the existing functional ones.
+- **One framework, two products** — the same composition engine drives Vera-to-merchant *and* merchant-to-customer messaging. Build once, ship twice.
+- **Vertical scaling is data work, not code work** — adding a new category becomes "fill in a CategoryContext", not "write a new agent".
+- **Auditable + versioned** — every message has explicit inputs and a versioned composer; we can replay, A/B test, and answer "why did Vera send this?" for any past send.
+
+---
+
+## Appendix: relationship to existing code
+
+- `agents/vera/followup/event_sources.py` and `agents/vera/followup/event_extractor.py` *(branch `feature/vera-campaign-engagement`)* already produce external `TriggerContext`-shaped objects for the news/weather scanner. They become the first concrete trigger source feeding the new composer.
+- `agents/vera/followup/template_registry.py` will continue to host the Kaleyra-approved template names (used for the first-touch send before the 24h session window opens). The composer fills the template parameters.
+- `agents/vera/followup/snapshot_data.py` already provides most of the `MerchantContext` fields. Customer aggregate fields would be added as new sections on `MerchantSnapshotData`.
+- `services/vera-mcp/src/services/offer_suggester.py` is the leading candidate for `CategoryContext.offer_catalog` (pending the open offer source-of-truth question).

engagement-research.md

@@ -0,0 +1,198 @@
+# Vera Engagement Framework — Research: Current Merchant Data Access
+
+**Status**: Research notes — companion to `engagement-design.md`.
+**Last updated**: 2026-04-26
+**Scope**: How the existing system loads merchant + customer data at conversation init and during a turn. Used to inform what the new framework must build vs. adapt.
+
+---
+
+## TL;DR
+
+Two distinct paths exist today — **merchant-facing** (Vera ↔ Dr. Meera) and **customer-facing** (a customer asks Vera *about* Dr. Meera). They share infrastructure (vera-mcp + merchant-support-mcp + Redis) but compose context very differently.
+
+Most of what the proposed `MerchantContext` needs **already exists in scattered form** (`_merchant_snapshot`, `_behavioral_profile`, `_session_scenario`). The genuinely new pieces are:
+
+- `CategoryContext` (no existing equivalent)
+- `TriggerContext` (no normalized abstraction today — every cron emits ad-hoc payloads)
+- `CustomerContext.relationship` (visit history aggregation doesn't exist)
+- `EngagementComposer` (no shared composer — each agent has its own prompt-builder)
+
+The aryan dependency for `category` and `locality` is the soft underbelly — every customer-info-pack call hits aryan synchronously.
+
+---
+
+## Path 1 — Merchant-facing (`VeraMerchantAgent`)
+
+### Init (per session, instance-level)
+
+`agents/vera/merchant_agent.py:402` — `__init__`:
+
+- Spawns its own `vera_mcp_client` (`HTTPMCPClient` → `VERA_MCP_SERVER_URL`, default `vera-mcp:8000`).
+- Inherits `BaseAgent._merchant_mcp_client` — class-level shared singleton pointing to `merchant-support-mcp` (`https://search5.magicpin.com/staging/mcp-server/mcp`).
+- **No merchant data is loaded at init** — agent doesn't know who it's talking to yet.
+
+### Per-turn (every inbound message)
+
+`agents/vera/merchant_agent.py:2171` — `handle_input(agent_input)`:
+
+1. Extract `merchant_id` from `metadata.context_data.merchant_id`, falling back to regex on the message body (`\d{7,}`).
+2. Fire 2 parallel tasks:
+    - `_detect_state(merchant_id)` — GBP connection + subscription status checks.
+    - `_prefetch_merchant_context(merchant_id)` — full snapshot + behavioral profile.
+
+### `_prefetch_merchant_context` — `merchant_agent.py:740`
+
+Cache-first design:
+
+1. **Redis check**: `vera:merchant_ctx:{merchant_id}` — TTL **30 min**. Hit → return immediately, skip everything below.
+2. Parallel via `asyncio.gather`:
+    - `vera_merchant_snapshot` (vera-mcp tool)
+    - `vera_get_merchant_profile` (vera-mcp tool)
+3. If snapshot is empty: fall back to `get_aggregated_unassociated_merchant_data` (merchant-support-mcp) — basic GBP health, no commercial data. Wrap it in a snapshot-shaped envelope.
+4. Sequential enrichments:
+    - `_prefetch_product_context` — fans out to `vera_get_subscription_context`, `vera_get_performance_summary`, and (only if DA subscribed) `da_get_campaign_context`. ~2KB total, embedded into snapshot.
+    - `_enrich_snapshot_with_pricing` — direct HTTP to `https://vera.magicpin.com/api/v1/merchant/pricing/get?mid=...` (vera-mcp's pricing path is unreachable locally). Mounted into snapshot as `pricing_recommendation`.
+5. Stuff result into Redis at the same key, TTL 30 min.
+
+Final state: `self._merchant_snapshot` and `self._behavioral_profile` are populated. `_get_system_prompt()` reads from these and serializes the snapshot directly into the LLM system prompt (`merchant_agent.py:996`).
+
+### What `vera_merchant_snapshot` actually fetches
+
+`vera-mcp/src/services/merchant_snapshot.py:51` — `build_merchant_snapshot()`:
+
+1. **Resolve identity** via `gbp_resolve_merchant` — gets `place_id`, `location_name`, `merchant_title`.
+2. **One async fan-out** of up to 13 tool calls in parallel:
+
+| Bucket | Tools |
+|---|---|
+| Merchant-level (no GBP needed) | `vera_get_subscription_status`, `vera_get_pricing_by_merchant`, `vera_get_merchant_pain_points`, `vera_get_merchant_offer`, `vera_get_merchant_config`, `vera_get_onboarding_status`, `vera_get_enhancement_suggestions` |
+| Location-level (skipped if no place_id) | `gbp_get_location`, `gbp_get_profile_completeness`, `gbp_get_performance_summary`, `gbp_get_search_keywords`, `gbp_get_review_stats`, `gbp_list_posts` |
+
+3. Composes 7 sections: `identity`, `profile`, `reputation`, `growth`, `commercial`, `conversation_hooks`, `issues`.
+
+> **Note**: `category` and `locality` are not first-class fields on the snapshot — they're buried inside `profile.business_info` (from `gbp_get_location`) and surfaced via `aryan_client.get_merchant_v2()` only when `vera_get_customer_info_pack` is called.
+
+### Mid-conversation tool calls
+
+The LLM gets the full toolset from `MERCHANT_MCP_ALLOWED_TOOLS` (declared on the agent class) merged with `_vera_mcp_tools_cache`. Mid-turn tool calls flow through:
+
+- `self.vera_mcp_client.call_tool(name, args)` — for vera-mcp tools (HTTP)
+- `BaseAgent._merchant_mcp_client.call_tool(name, args)` — for merchant-support-mcp tools (HTTP)
+
+No re-prefetch of the snapshot mid-turn. The agent relies on the prefetched snapshot + LLM-initiated lookups when it needs fresh data.
+
+---
+
+## Path 2 — Customer-facing (`CustomerIncomingAgent`)
+
+`agents/vera/customer_incoming_agent.py:91` — different agent, different state model.
+
+### Init + per-turn
+
+The instance carries:
+
+- `_merchant_id` — the merchant the customer is asking about
+- `_merchant_data`, `_merchant_name`, `_category`, `_offers`, `_jd_info` — about the **business**
+- `_customer_phone`, `_customer_profile` — about the **customer** (the one chatting)
+- `_chat_history`, `_session_state` — conversation continuity
+
+### Merchant data load — `_load_merchant_data` (`customer_incoming_agent.py:221`)
+
+Single shape, no Redis cache:
+
+1. **Primary call**: `vera_get_customer_info_pack(merchant_id)` — one MCP call returns `business_info` + `reviews` + `photos` + `offers` + `metadata` in one shot. The aggregated customer-facing endpoint.
+2. **Fallback chain** if `info_pack` is empty:
+    - `get_unassociated_merchant_data` — basic merchant info
+    - `vera_list_merchant_offers` — separate offer list
+3. **Supplementary** (non-blocking): `vera_get_merchant_jd_info` — JustDial crawl data for additional name / address / phone.
+
+Caching is at the request level (in-memory on the agent instance) — re-using the same `merchant_id` in a session avoids re-fetching.
+
+### What `vera_get_customer_info_pack` does
+
+`vera-mcp/src/tools/merchant_info.py:188`:
+
+1. **Resolve place_id**: `_resolve_place_id(merchant_id)` — chain of MongoDB (`gbp_status`) → local JSON → `aryan_client.get_mapping()`.
+2. **Parallel fetch**:
+    - GBP data via `get_or_fetch(place_id)` — 24h cache in MongoDB, falls through to Google Places API
+    - `_get_active_offers(merchant_id)` — direct MongoDB read of `offers` collection where `status=active`
+    - `_get_merchant_metadata(merchant_id)` — `aryan_client.get_merchant_v2()` → returns `name`, `category`, `locality`
+3. **Last-resort fallback**: `_fetch_embed_data(place_id)` — vera REST `/embed` endpoint if everything else came back empty.
+
+### Customer profile (the *caller*)
+
+`_customer_profile` is loaded separately — populated in `_init_customer_data` from past conversation tickets keyed off `_customer_phone`. There's no rich CRM behind it today; it's mostly conversation continuity (last visit, last topic).
+
+---
+
+## Cross-cutting infrastructure
+
+| Concern | Implementation |
+|---|---|
+| MCP transport | `HTTPMCPClient` (vera client) — keeps a session, calls `/mcp/tools/{name}` HTTP POST |
+| Auth | Not required for challenge bot endpoints |
+| Cache key for merchant context | `vera:merchant_ctx:{merchant_id}` — Redis, TTL 30 min, written by `_prefetch_merchant_context` |
+| Cache key for GBP data | `gbp_health_report:{place_id}` — MongoDB, TTL 24h, in vera-mcp |
+| Snapshot freshness for sends | Whatever's in Redis — not refreshed on send unless agent is in active conversation |
+| Source of truth for `category` | aryan `get_merchant_v2` API (via `aryan_client`) — used in `_get_merchant_metadata` |
+| Source of truth for `name` | aryan first, GBP `business_info` second |
+
+---
+
+## Observations relevant to the engagement framework
+
+### What already exists
+
+1. **Most of `MerchantContext` already exists** — spread across `_merchant_snapshot`, `_behavioral_profile`, `_session_scenario`, `_jd_info`. A `MerchantContext.from_existing(agent_state)` adapter could load ~80% of the fields without any new fetching.
+2. **The customer agent already has half a `CustomerContext`** — `_customer_phone` + `_customer_profile` give us identity + conversation continuity. Missing: visit history, services received, lapse state.
+3. **Two MCP servers, one orchestration** — vera-mcp (instance-level) for vera tools, merchant-support-mcp (class-level shared) for fallback merchant tools. The composer can just consume whatever `MerchantContext` already collected — no new MCP wiring required.
+4. **Cache TTL of 30 min is fine** for engagement nudges that fire daily/weekly. Redis hits during conversation are plenty fresh for composition.
+
+### What does NOT exist
+
+1. **No `CategoryContext`.** Category is just a string buried in metadata. Voice rules, peer benchmarks, knowledge digests — none of it exists. Biggest greenfield area, but also the most leveraged (one CategoryContext serves all merchants in the vertical).
+2. **No `customer_aggregate` field on the merchant snapshot.** No pipeline today aggregates per-merchant customer roster stats (active count, lapsed count, retention rate).
+3. **No `TriggerContext` abstraction.** Every nudge type today has its own cron + its own fetch logic + its own send code. The proposed `TriggerContext` is the genuinely new architectural primitive; everything else is reorganization.
+4. **No visit-history aggregation per (merchant, customer_phone).** Required for `CustomerContext.relationship`. BOTOPS chat history has the raw data; no derived view exists.
+5. **No shared composer.** Each agent has its own prompt builder embedded in `_get_system_prompt()`. The proposed `EngagementComposer` is net new.
+
+### Operational risks to mitigate
+
+1. **Aryan is the synchronous bottleneck.** `aryan_client.get_merchant_v2()` is the only path to category and locality, and it's a remote HTTP call. If aryan is slow, every customer-info-pack call is slow. Worth caching aryan responses per merchant for ~24h before scaling engagement frequency.
+2. **The 30-min Redis cache is keyed per-merchant** — fine for in-conversation reuse, but a daily engagement cron will miss this cache 100% of the time and pay the full snapshot-build cost per send. Consider a longer-TTL background-warmed cache for the engagement loop specifically.
+3. **No version tracking on prompts today.** Every send loses the prompt-version provenance. The composer should record prompt version + context hash on every send so we can replay and A/B.
+
+---
+
+## Concrete recommendation for Phase 1 of the framework
+
+Phase 1 is mostly an **adapter layer**, not new infrastructure:
+
+| Layer | Effort | What it actually does |
+|---|---|---|
+| `CategoryContext` | Net new | Build for dentistry first (offer catalog, voice, peer stats, weekly digest, patient-content seed) |
+| `MerchantContext` | Adapter | Wrap existing `_merchant_snapshot` + `_behavioral_profile` + a new `_customer_aggregate` derived from BOTOPS chat history |
+| `TriggerContext` | Net new abstraction | Normalize the payloads existing crons emit into a single shape; new triggers (research_digest, recall_due) emit it natively |
+| `CustomerContext` | Partial adapter | Wrap existing `_customer_profile`, plus a new visit-history aggregator |
+| `EngagementComposer` | Net new | Single LLM-prompted module with versioned prompt; consumes the above |
+
+Phase 1 should NOT require modifying any existing agent. The adapter reads from existing state; the composer is a new module that runs in parallel; the new triggers (research digest, recall) are new crons that don't touch the existing matrix-followup or campaign-engagement loops.
+
+---
+
+## Appendix: file pointers for follow-up implementation
+
+- `agents/vera/merchant_agent.py:402` — VeraMerchantAgent init
+- `agents/vera/merchant_agent.py:740` — `_prefetch_merchant_context` (the main load)
+- `agents/vera/merchant_agent.py:899` — `_prefetch_product_context` (subscription + DA campaign + perf summary)
+- `agents/vera/merchant_agent.py:996` — system-prompt builder reads `_merchant_snapshot`
+- `agents/vera/merchant_agent.py:2171` — `handle_input` per-turn entry
+- `agents/vera/customer_incoming_agent.py:91` — CustomerIncomingAgent class
+- `agents/vera/customer_incoming_agent.py:221` — `_load_merchant_data` (single info-pack call + fallbacks)
+- `agents/base_agent.py:80-82` — MERCHANT_MCP_SERVER_URL config
+- `agents/base_agent.py:237-244` — class-level shared `_merchant_mcp_client`
+- `vera-mcp/src/tools/merchant_snapshot.py` — `vera_merchant_snapshot` tool
+- `vera-mcp/src/services/merchant_snapshot.py:51` — `build_merchant_snapshot` (the 13-call fan-out)
+- `vera-mcp/src/tools/merchant_info.py:188` — `vera_get_customer_info_pack` tool
+- `vera-mcp/src/tools/merchant_info.py:30` — `_resolve_place_id` chain (MongoDB → JSON → aryan)
+- `vera-mcp/src/services/aryan_client.py` — aryan HTTP client (`get_merchant_v2`, `get_mapping`)

examples/api-call-examples.md

@@ -0,0 +1,615 @@
+# API Call Examples — Judge ↔ Candidate Bot
+
+This file shows the exact HTTP calls the judge will make during testing, and what the bot is expected to return. Read this together with `challenge-testing-brief.md` (which defines the contract) and the dataset (which provides the payloads).
+
+Every example uses Dr. Meera's Dental Clinic (`m_001_drmeera_dentist_delhi`) as the running merchant.
+
+---
+
+## Phase 1 — Warmup (T-15 min)
+
+### Example 1.1 — `GET /v1/healthz`
+
+**Request**
+```http
+GET /v1/healthz HTTP/1.1
+Host: bot.candidate-team-alpha.example.com
+Accept: application/json
+```
+
+**Expected response (200)**
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+  "status": "ok",
+  "uptime_seconds": 124,
+  "contexts_loaded": { "category": 0, "merchant": 0, "customer": 0, "trigger": 0 }
+}
+```
+
+The judge calls this before pushing context. `contexts_loaded` should be all zeros at this point (bot just started).
+
+### Example 1.2 — `GET /v1/metadata`
+
+**Request**
+```http
+GET /v1/metadata HTTP/1.1
+Host: bot.candidate-team-alpha.example.com
+```
+
+**Expected response (200)**
+```json
+{
+  "team_name": "Team Alpha",
+  "team_members": ["Alice", "Bob"],
+  "model": "claude-opus-4-7",
+  "approach": "single-prompt composer with retrieval over digest items + dispatch by trigger.kind",
+  "contact_email": "team@example.com",
+  "version": "1.2.0",
+  "submitted_at": "2026-04-26T08:00:00Z"
+}
+```
+
+### Example 1.3 — `POST /v1/context` (push CategoryContext)
+
+**Request**
+```http
+POST /v1/context HTTP/1.1
+Host: bot.candidate-team-alpha.example.com
+Content-Type: application/json
+
+{
+  "scope": "category",
+  "context_id": "dentists",
+  "version": 1,
+  "delivered_at": "2026-04-26T09:45:00Z",
+  "payload": {
+    "slug": "dentists",
+    "voice": { "tone": "peer_clinical", "vocab_taboo": ["guaranteed", "100% safe"] },
+    "offer_catalog": [
+      { "id": "den_001", "title": "Dental Cleaning @ ₹299", "value": "299", "audience": "new_user", "type": "service_at_price" }
+    ],
+    "peer_stats": { "avg_rating": 4.4, "avg_ctr": 0.030 },
+    "digest": [{ "id": "d_2026W17_jida_fluoride", "kind": "research", "title": "3-month fluoride recall cuts caries 38% better", "source": "JIDA Oct 2026, p.14" }],
+    "patient_content_library": [],
+    "seasonal_beats": [{ "month_range": "Nov-Feb", "note": "exam-stress bruxism spike" }],
+    "trend_signals": [{ "query": "clear aligners delhi", "delta_yoy": 0.62 }]
+  }
+}
+```
+
+**Expected response (200)**
+```json
+{ "accepted": true, "ack_id": "ack_dentists_v1", "stored_at": "2026-04-26T09:45:00.123Z" }
+```
+
+> **Note**: For the actual test the full category JSON (`dataset/categories/dentists.json`) goes in `payload`, not the abbreviated form above.
+
+### Example 1.4 — `POST /v1/context` (push MerchantContext)
+
+**Request**
+```http
+POST /v1/context HTTP/1.1
+Content-Type: application/json
+
+{
+  "scope": "merchant",
+  "context_id": "m_001_drmeera_dentist_delhi",
+  "version": 1,
+  "delivered_at": "2026-04-26T09:45:30Z",
+  "payload": {
+    "merchant_id": "m_001_drmeera_dentist_delhi",
+    "category_slug": "dentists",
+    "identity": { "name": "Dr. Meera's Dental Clinic", "city": "Delhi", "locality": "Lajpat Nagar",
+                  "verified": true, "languages": ["en", "hi"], "owner_first_name": "Meera" },
+    "subscription": { "status": "active", "plan": "Pro", "days_remaining": 82 },
+    "performance": { "window_days": 30, "views": 2410, "calls": 18, "directions": 45,
+                     "ctr": 0.021, "delta_7d": { "views_pct": 0.18, "calls_pct": -0.05 } },
+    "offers": [{ "id": "o_meera_001", "title": "Dental Cleaning @ ₹299", "status": "active" }],
+    "conversation_history": [],
+    "customer_aggregate": { "total_unique_ytd": 540, "lapsed_180d_plus": 78,
+                            "retention_6mo_pct": 0.38, "high_risk_adult_count": 124 },
+    "signals": ["stale_posts:22d", "ctr_below_peer_median", "high_risk_adult_cohort"]
+  }
+}
+```
+
+**Expected response (200)**
+```json
+{ "accepted": true, "ack_id": "ack_m_001_drmeera_v1", "stored_at": "2026-04-26T09:45:30.456Z" }
+```
+
+### Example 1.5 — `POST /v1/context` (idempotency check — same version re-pushed)
+
+**Request** (same body as 1.4 — version 1 again)
+
+**Expected response (409)**
+```json
+{ "accepted": false, "reason": "stale_version", "current_version": 1 }
+```
+
+### Example 1.6 — `POST /v1/context` (version bump replaces)
+
+**Request**: same as 1.4 but `version: 2` and `performance.views: 2580` (updated).
+
+**Expected response (200)**
+```json
+{ "accepted": true, "ack_id": "ack_m_001_drmeera_v2", "stored_at": "2026-04-26T10:30:00.789Z" }
+```
+
+The bot must now use the new version when composing for `m_001_drmeera_dentist_delhi`.
+
+### Example 1.7 — `GET /v1/healthz` after warmup complete
+
+**Expected response (200)**
+```json
+{
+  "status": "ok",
+  "uptime_seconds": 1024,
+  "contexts_loaded": { "category": 5, "merchant": 50, "customer": 200, "trigger": 0 }
+}
+```
+
+If counts don't match what the judge pushed, warmup fails and the bot is disqualified for that test slot.
+
+---
+
+## Phase 2 — Test window (T0 → T0 + 60 min)
+
+### Example 2.1 — `POST /v1/context` (incremental trigger push)
+
+The judge now starts pushing triggers as simulated time advances.
+
+**Request**
+```http
+POST /v1/context HTTP/1.1
+Content-Type: application/json
+
+{
+  "scope": "trigger",
+  "context_id": "trg_001_research_digest_dentists",
+  "version": 1,
+  "delivered_at": "2026-04-26T10:32:00Z",
+  "payload": {
+    "id": "trg_001_research_digest_dentists",
+    "scope": "merchant",
+    "kind": "research_digest",
+    "source": "external",
+    "merchant_id": "m_001_drmeera_dentist_delhi",
+    "customer_id": null,
+    "payload": {
+      "category": "dentists",
+      "top_item_id": "d_2026W17_jida_fluoride"
+    },
+    "urgency": 2,
+    "suppression_key": "research:dentists:2026-W17",
+    "expires_at": "2026-05-03T00:00:00Z"
+  }
+}
+```
+
+**Expected response (200)**
+```json
+{ "accepted": true, "ack_id": "ack_trg_001_v1", "stored_at": "2026-04-26T10:32:00.150Z" }
+```
+
+### Example 2.2 — `POST /v1/tick` (bot decides to send)
+
+**Request**
+```http
+POST /v1/tick HTTP/1.1
+Content-Type: application/json
+
+{
+  "now": "2026-04-26T10:35:00Z",
+  "available_triggers": ["trg_001_research_digest_dentists"]
+}
+```
+
+**Expected response (200) — bot chose to send**
+```json
+{
+  "actions": [
+    {
+      "conversation_id": "conv_m_001_drmeera_research_W17",
+      "merchant_id": "m_001_drmeera_dentist_delhi",
+      "customer_id": null,
+      "send_as": "vera",
+      "trigger_id": "trg_001_research_digest_dentists",
+      "template_name": "vera_research_digest_v1",
+      "template_params": [
+        "Dr. Meera",
+        "JIDA Oct issue landed. One item relevant to your high-risk adult patients — 2,100-patient trial showed 3-month fluoride recall cuts caries recurrence 38% better than 6-month",
+        "Worth a look (2-min abstract). Want me to pull it + draft a patient-ed WhatsApp you can share?"
+      ],
+      "body": "Dr. Meera, JIDA's Oct issue landed. One item relevant to your high-risk adult patients — 2,100-patient trial showed 3-month fluoride recall cuts caries recurrence 38% better than 6-month. Worth a look (2-min abstract). Want me to pull it + draft a patient-ed WhatsApp you can share? — JIDA Oct 2026 p.14",
+      "cta": "open_ended",
+      "suppression_key": "research:dentists:2026-W17",
+      "rationale": "External research digest with merchant-relevant clinical anchor (high-risk-adult cohort matches signal). Source citation at end maintains credibility. Open-ended CTA invites continuation without forcing a binary choice."
+    }
+  ]
+}
+```
+
+### Example 2.3 — `POST /v1/tick` (bot decides NOT to send)
+
+If no triggers are worth acting on this tick (or all have been suppressed):
+
+**Expected response (200)**
+```json
+{ "actions": [] }
+```
+
+Empty `actions` is valid. Restraint is rewarded; spam is penalized.
+
+### Example 2.4 — `POST /v1/reply` (judge plays merchant — engaged response)
+
+The judge's sub-LLM, playing Dr. Meera, replies to the message from 2.2:
+
+**Request**
+```http
+POST /v1/reply HTTP/1.1
+Content-Type: application/json
+
+{
+  "conversation_id": "conv_m_001_drmeera_research_W17",
+  "merchant_id": "m_001_drmeera_dentist_delhi",
+  "customer_id": null,
+  "from_role": "merchant",
+  "message": "Yes please send the abstract. Also draft the patient WhatsApp.",
+  "received_at": "2026-04-26T10:42:00Z",
+  "turn_number": 2
+}
+```
+
+**Expected response (200) — bot follows up with action**
+```json
+{
+  "action": "send",
+  "body": "Sending the abstract now (PDF, 2 pages). Patient-ed draft below — you can copy-paste or I'll schedule a Google post:\n\n\"3-month vs 6-month dental cleaning — does it really matter? New research shows yes, especially if you've had cavities recently. Drop us a note for a quick check.\"\n\nWant me to schedule the post for tomorrow 10am?",
+  "cta": "binary_yes_no",
+  "rationale": "Honoring both asks (abstract + draft) in one turn. Draft is at patient-reading level. Final question is a binary yes/no to lower friction."
+}
+```
+
+### Example 2.5 — `POST /v1/reply` (judge plays merchant — auto-reply)
+
+Some test scenarios simulate WhatsApp Business auto-reply:
+
+**Request**
+```json
+{
+  "conversation_id": "conv_m_001_drmeera_research_W17",
+  "from_role": "merchant",
+  "message": "Thank you for contacting Dr. Meera's Dental Clinic! Our team will respond shortly.",
+  "received_at": "2026-04-26T10:42:00Z",
+  "turn_number": 2
+}
+```
+
+**Expected response (200) — bot detects auto-reply, exits gracefully**
+```json
+{
+  "action": "wait",
+  "wait_seconds": 14400,
+  "rationale": "Detected merchant auto-reply (canned 'Thank you for contacting' phrasing). Backing off 4 hours to wait for owner."
+}
+```
+
+After the wait expires, the judge will call `/v1/tick` again and the bot can re-engage.
+
+### Example 2.6 — `POST /v1/reply` (judge plays merchant — hard "no")
+
+**Request**
+```json
+{
+  "conversation_id": "conv_m_001_drmeera_research_W17",
+  "from_role": "merchant",
+  "message": "Not interested. Stop messaging me.",
+  "received_at": "2026-04-26T10:42:00Z",
+  "turn_number": 2
+}
+```
+
+**Expected response (200) — bot ends gracefully**
+```json
+{
+  "action": "end",
+  "rationale": "Merchant explicitly opted out. Closing conversation; suppressing this conversation_id for future ticks."
+}
+```
+
+The bot must not send any further messages on this `conversation_id`.
+
+### Example 2.7 — `POST /v1/reply` (judge plays merchant — curveball)
+
+**Request**
+```json
+{
+  "conversation_id": "conv_m_001_drmeera_research_W17",
+  "from_role": "merchant",
+  "message": "Btw can you also help me with my GST filing this month?",
+  "received_at": "2026-04-26T10:42:00Z",
+  "turn_number": 2
+}
+```
+
+**Expected response (200) — bot stays on mission politely**
+```json
+{
+  "action": "send",
+  "body": "I'll have to leave GST filing to your CA — that's outside what I can help with directly. Coming back to the JIDA piece — want me to draft the patient post first, or send the abstract?",
+  "cta": "open_ended",
+  "rationale": "Out-of-scope ask politely declined; redirects back to the original trigger without losing thread."
+}
+```
+
+### Example 2.8 — `POST /v1/context` (mid-test adaptive injection)
+
+While the conversation is live, the judge pushes a new digest item. A good bot will incorporate it in subsequent sends.
+
+**Request**
+```json
+{
+  "scope": "category",
+  "context_id": "dentists",
+  "version": 2,
+  "delivered_at": "2026-04-26T10:50:00Z",
+  "payload": {
+    "slug": "dentists",
+    "voice": { "tone": "peer_clinical" },
+    "digest": [
+      { "id": "d_2026W17_jida_fluoride", "kind": "research", "title": "3-month fluoride recall cuts caries 38% better", "source": "JIDA Oct 2026, p.14" },
+      { "id": "d_2026W17_dci_radiograph_NEW", "kind": "compliance", "title": "DCI revised radiograph dose limits effective 2026-12-15",
+        "source": "DCI circular 2026-11-04", "summary": "Max dose drops 1.5→1.0 mSv per IOPA. E-speed film passes; D-speed does not." }
+    ],
+    "// other fields": "..."
+  }
+}
+```
+
+**Expected response (200)**
+```json
+{ "accepted": true, "ack_id": "ack_dentists_v2", "stored_at": "2026-04-26T10:50:00.110Z" }
+```
+
+The bot must replace the old version atomically and use the new digest item if relevant in the next send.
+
+### Example 2.9 — `POST /v1/tick` (customer-scoped trigger emerges)
+
+A `recall_due` trigger fires for one of Dr. Meera's patients:
+
+**Context push first**
+```json
+{
+  "scope": "customer",
+  "context_id": "c_001_priya_for_m001",
+  "version": 1,
+  "payload": { /* Priya's CustomerContext from dataset/customers_seed.json */ }
+}
+```
+
+```json
+{
+  "scope": "trigger",
+  "context_id": "trg_003_recall_due_priya",
+  "version": 1,
+  "payload": { /* the recall trigger from dataset/triggers_seed.json */ }
+}
+```
+
+**Then `/v1/tick`**
+```json
+{
+  "now": "2026-04-26T11:00:00Z",
+  "available_triggers": ["trg_003_recall_due_priya"]
+}
+```
+
+**Expected response (200)**
+```json
+{
+  "actions": [
+    {
+      "conversation_id": "conv_priya_recall_2026_11",
+      "merchant_id": "m_001_drmeera_dentist_delhi",
+      "customer_id": "c_001_priya_for_m001",
+      "send_as": "merchant_on_behalf",
+      "trigger_id": "trg_003_recall_due_priya",
+      "template_name": "merchant_recall_reminder_v1",
+      "template_params": [
+        "Priya",
+        "Dr. Meera's clinic",
+        "It's been 5 months since your last visit",
+        "Wed 5 Nov, 6pm or Thu 6 Nov, 5pm",
+        "₹299 cleaning + complimentary fluoride"
+      ],
+      "body": "Hi Priya, Dr. Meera's clinic here 🦷 It's been 5 months since your last visit — your 6-month cleaning recall is due. Apke liye 2 slots ready hain: **Wed 5 Nov, 6pm** ya **Thu 6 Nov, 5pm**. ₹299 cleaning + complimentary fluoride. Reply 1 for Wed, 2 for Thu, or tell us a time that works.",
+      "cta": "multi_choice_slot",
+      "suppression_key": "recall:c_001_priya_for_m001:6mo",
+      "rationale": "Customer-scoped recall, sending via merchant's number (send_as=merchant_on_behalf). Honoring Priya's hi-en mix language pref + weekday-evening preference (both slots offered are weekday evenings). Multi-choice slot CTA is appropriate for booking flows."
+    }
+  ]
+}
+```
+
+---
+
+## Phase 4 — Replay test (top 10 only)
+
+The judge runs 3 standalone scenarios. Each is a fresh conversation with a controlled merchant persona.
+
+### Example 4.1 — Auto-reply hell scenario
+
+The judge sends 4 turns of identical canned auto-replies.
+
+**Turn 1 — bot initiates**
+```json
+POST /v1/tick { "now": "...", "available_triggers": ["trg_022_cde_webinar_dentists"] }
+→ { "actions": [{ /* CDE webinar invite */ }] }
+```
+
+**Turn 2 — judge plays auto-reply**
+```json
+POST /v1/reply { "from_role": "merchant",
+                 "message": "Thank you for contacting Dr. Meera's Dental Clinic! Our team will respond shortly.",
+                 "turn_number": 2 }
+```
+
+**Good bot response**
+```json
+{ "action": "send",
+  "body": "Looks like an auto-reply 😊 When the owner sees this, just reply 'Yes' for the webinar invite.",
+  "cta": "binary_yes_no",
+  "rationale": "Detected auto-reply; one explicit prompt to flag it for the owner." }
+```
+
+**Turn 3 — judge plays same auto-reply again**
+```json
+POST /v1/reply { "from_role": "merchant",
+                 "message": "Thank you for contacting Dr. Meera's Dental Clinic! Our team will respond shortly.",
+                 "turn_number": 3 }
+```
+
+**Good bot response**
+```json
+{ "action": "wait", "wait_seconds": 86400,
+  "rationale": "Same auto-reply twice in a row → owner not at phone. Wait 24h before retry." }
+```
+
+**Turn 4 — judge plays same auto-reply yet again**
+
+**Good bot response**
+```json
+{ "action": "end",
+  "rationale": "Auto-reply 3x in a row, no real reply. Conversation has zero engagement signal; closing." }
+```
+
+### Example 4.2 — Intent transition scenario
+
+After 2 turns of qualification, judge plays an explicit "let's do it":
+
+**Turn 3 — judge**
+```json
+POST /v1/reply { "from_role": "merchant",
+                 "message": "Ok, let's do it. What's next?",
+                 "turn_number": 3 }
+```
+
+**Good bot response — switches from qualifying to action**
+```json
+{ "action": "send",
+  "body": "Great. Drafting your patient WhatsApp now — 90 seconds. I'll also pre-fill the GBP post for tomorrow 10am. Reply CONFIRM to send the WhatsApp draft to your patient list (40 high-risk adult patients).",
+  "cta": "binary_confirm_cancel",
+  "rationale": "Merchant explicitly committed; switching from question-asking to action-execution. Concrete next step + measurable scope (40 patients)." }
+```
+
+**Bad bot response — keeps qualifying (this loses points)**
+```json
+{ "action": "send",
+  "body": "Excellent! Just to plan well — would you say most of your high-risk patients are diabetic, or is there another common factor?",
+  "rationale": "Continuing qualification..."  // ← penalty: ignored explicit intent transition
+}
+```
+
+### Example 4.3 — Hostile / off-topic scenario
+
+**Turn 2 — judge plays hostile**
+```json
+POST /v1/reply { "from_role": "merchant",
+                 "message": "Why are you bothering me. This is useless. Stop sending these.",
+                 "turn_number": 2 }
+```
+
+**Good bot response — graceful exit**
+```json
+{ "action": "end",
+  "rationale": "Merchant frustration explicit; closing without further engagement. Suppressing all triggers for this merchant for 30 days." }
+```
+
+**Acceptable alternative — short apology + exit**
+```json
+{ "action": "send",
+  "body": "Apologies — I won't message again. If anything changes, you can always restart with 'Hi Vera'. 🙏",
+  "cta": "none",
+  "rationale": "One-line acknowledgment + opt-out path; conversation will close after this send." }
+```
+
+---
+
+## Failure-mode examples
+
+### Example F.1 — Bot times out
+
+If `/v1/tick` doesn't respond within 30s, the judge logs a timeout and continues. No retries.
+
+### Example F.2 — Malformed response
+
+```json
+{ "actions": [{ "merchant_id": "m_001", "body": "..." }] }
+```
+
+Missing required fields (`conversation_id`, `send_as`, `trigger_id`, `cta`, `suppression_key`, `rationale`) → action scored as 0, -2 penalty.
+
+### Example F.3 — Body too long
+
+```json
+{ "body": "...500 chars..." }
+```
+
+No hard body-length cap. Messages are judged on quality, specificity, and relevance.
+
+### Example F.4 — URL in body
+
+```json
+{ "body": "Read more: https://magicpin.com/blog" }
+```
+
+Hard fail for that action — Meta would reject. Penalty: -3 per URL.
+
+### Example F.5 — Repetition
+
+Same `body` text sent twice in the same `conversation_id` → -2 anti-repetition penalty per repeat.
+
+---
+
+## Curl examples (for local testing)
+
+```bash
+# Set your bot URL
+export BOT_URL=http://localhost:8080
+
+# Healthz
+curl $BOT_URL/v1/healthz
+
+# Push a category context
+curl -X POST -H "Content-Type: application/json" \
+  -d @dataset/categories/dentists.json \
+  $BOT_URL/v1/context
+
+# Trigger a tick
+curl -X POST -H "Content-Type: application/json" \
+  -d '{"now": "2026-04-26T10:35:00Z", "available_triggers": ["trg_001_research_digest_dentists"]}' \
+  $BOT_URL/v1/tick
+
+# Send a reply
+curl -X POST -H "Content-Type: application/json" \
+  -d '{"conversation_id": "conv_001", "merchant_id": "m_001_drmeera_dentist_delhi", "from_role": "merchant", "message": "Yes please send the abstract", "received_at": "2026-04-26T10:42:00Z", "turn_number": 2}' \
+  $BOT_URL/v1/reply
+```
+
+---
+
+## Summary table — request shapes at a glance
+
+| Endpoint | Method | Body | Latency budget | Retried? |
+|---|---|---|---|---|
+| `/v1/healthz` | GET | none | 2 s | yes (×3) |
+| `/v1/metadata` | GET | none | 2 s | no |
+| `/v1/context` | POST | full payload | 5 s | no |
+| `/v1/tick` | POST | `{now, available_triggers}` | 10 s | no |
+| `/v1/reply` | POST | reply turn | 10 s | no |
+
+That's the full surface. If your bot handles every example here correctly, it'll pass the warmup, the test window, and the replay scenarios with no operational issues — leaving the score entirely to the quality of your composition.

examples/case-studies.md

@@ -0,0 +1,338 @@
+# 10 Case Studies — What "Good" Looks Like
+
+These case studies serve as anchor examples for the AI judge and as targets for candidates. Each shows:
+- The 4-context input
+- The good composed message
+- The compulsion levers used
+- The dimension-by-dimension score (out of 50)
+
+Two cases per category × 5 categories = 10 case studies. Mix of merchant-facing and customer-facing scopes.
+
+---
+
+## Case Study 1 — Dentists / Research Digest (merchant-facing)
+
+**Category**: `dentists`
+**Merchant**: Dr. Meera's Dental Clinic, Lajpat Nagar Delhi, CTR 2.1% (below peer 3.0%), 124 high-risk adult patients in roster
+**Trigger**: `research_digest` — JIDA Oct 2026 paper: 3-month fluoride recall vs 6-month, 38% caries reduction in high-risk adults
+**Customer**: none
+
+**Composed message** (sent as Vera)
+```
+Dr. Meera, JIDA's Oct issue landed. One item relevant to your high-risk adult
+patients — 2,100-patient trial showed 3-month fluoride recall cuts caries
+recurrence 38% better than 6-month. Worth a look (2-min abstract). Want me
+to pull it + draft a patient-ed WhatsApp you can share?  — JIDA Oct 2026 p.14
+```
+
+**Compulsion levers**: source citation (credibility), merchant-specific anchor (her high-risk-adult cohort), reciprocity ("I'll pull it for you"), low-friction CTA, **specificity** (2,100 / 38% / page number).
+
+**Score breakdown** (50/50 = perfect)
+| Dimension | Score | Why |
+|---|---|---|
+| Specificity | 10 | Numbers + source + page reference |
+| Category fit | 10 | Clinical vocabulary, peer tone, no overclaim |
+| Merchant fit | 10 | "your high-risk adult patients" derived from her customer_aggregate |
+| Trigger relevance | 10 | Explicitly references the digest as the reason for messaging |
+| Engagement compulsion | 10 | Curiosity + reciprocity + clear next step |
+
+---
+
+## Case Study 2 — Dentists / Recall Reminder (customer-facing)
+
+**Category**: `dentists` (customer-facing voice rules: no medical claims)
+**Merchant**: Dr. Meera's Dental Clinic — active offer "Dental Cleaning @ ₹299", available slots Wed 5 Nov 6pm + Thu 6 Nov 5pm
+**Trigger**: `recall_due` — Priya's 6-month cleaning recall window opened
+**Customer**: Priya — lapsed_soft (5mo since last visit), prefers weekday evenings, hi-en mix
+
+**Composed message** (sent as merchant_on_behalf, from Dr. Meera's WA number)
+```
+Hi Priya, Dr. Meera's clinic here 🦷 It's been 5 months since your last visit
+— your 6-month cleaning recall is due. Apke liye 2 slots ready hain: Wed 5
+Nov, 6pm ya Thu 6 Nov, 5pm. ₹299 cleaning + complimentary fluoride. Reply 1
+for Wed, 2 for Thu, or tell us a time that works.
+```
+
+**Compulsion levers**: name personalization, language-pref match (hi-en mix), specific dates + price + free-add ("complimentary fluoride"), low-friction multi-choice CTA, dental emoji for warmth.
+
+**Score breakdown** (49/50)
+| Dimension | Score | Why |
+|---|---|---|
+| Specificity | 10 | Real slots + real price + concrete recall window |
+| Category fit | 10 | No medical claims; warm-clinical tone |
+| Merchant fit | 10 | Real offer from catalog; merchant's actual slots |
+| Trigger relevance | 10 | Explicit 6-month recall framing |
+| Engagement compulsion | 9 | Strong but Reply 1/2 multi-choice is borderline (binary preferred); the "or tell us a time that works" rescues it |
+
+---
+
+## Case Study 3 — Salons / Active Planning (merchant-facing)
+
+**Category**: `salons`
+**Merchant**: Studio11 Family Salon, Kapra Hyderabad, calls +20% w/w, retention 62%, peer-leading
+**Trigger**: `active_planning_intent` — kids yoga summer camp planning conversation
+> *Wait — this is the gym category. Let me redo with a salon trigger.*
+
+**Trigger (corrected)**: `bridal_followup` — Kavya, bride-to-be (wedding 2026-11-08), did Bridal Trial 5 weeks ago, in skin-prep window now
+**Customer**: Kavya — new state, wedding date 2026-11-08, opted in for bridal followup
+
+> Note: this is also customer-facing. Treating this as a customer-facing case for variety.
+
+**Composed message** (sent as merchant_on_behalf)
+```
+Hi Kavya 💍 Lakshmi from Studio11 Kapra here. 196 days to your wedding — perfect
+window to start the 30-day skin-prep program before serious bridal bookings
+roll in. ₹2,499 covers 4 sessions + a take-home kit. Want me to block your
+preferred Saturday 4pm slot for the first session next week?
+```
+
+**Compulsion levers**: relationship continuity ("from your trial"), wedding-date specificity, urgency framing (window opens), preference honored (Saturday 4pm), single binary commit.
+
+**Score breakdown** (47/50)
+| Dimension | Score | Why |
+|---|---|---|
+| Specificity | 10 | Days-to-wedding count, program structure, price |
+| Category fit | 9 | Warm-practical tone; emojis used appropriately |
+| Merchant fit | 9 | References Lakshmi (owner first name) + Studio11 + her trial |
+| Trigger relevance | 10 | Explicitly the bridal followup window |
+| Engagement compulsion | 9 | Strong but assumes the program exists in catalog (verify in MerchantContext.offers) |
+
+---
+
+## Case Study 4 — Salons / Curious Ask (merchant-facing)
+
+**Category**: `salons`
+**Merchant**: Studio11 Family Salon, growing strongly, last Vera touch 3 days ago
+**Trigger**: `curious_ask_due` — weekly "what's in demand?" cadence
+**Customer**: none
+
+**Composed message** (sent as Vera)
+```
+Hi Lakshmi! Quick check — what service has been most asked-for this week
+at Studio11? I'll turn the answer into a Google post + a 4-line WhatsApp
+reply you can use when customers ask about pricing. Takes 5 min.
+```
+
+**Compulsion levers**: low-stakes question (no commitment), reciprocity offered up-front (Google post + reply draft), effort externalization (5 min), respects merchant time.
+
+**Score breakdown** (44/50)
+| Dimension | Score | Why |
+|---|---|---|
+| Specificity | 8 | "5 min" anchor; could be sharper with a guess ("Is it the keratin treatment?") |
+| Category fit | 9 | Warm tone, fellow-operator register |
+| Merchant fit | 8 | Uses owner first name; could reference recent service mix |
+| Trigger relevance | 10 | This IS the curious-ask family — exactly the right shape |
+| Engagement compulsion | 9 | Asking-the-merchant lever is the strongest Cialdini hook for engaged merchants |
+
+---
+
+## Case Study 5 — Restaurants / IPL Match Day (merchant-facing)
+
+**Category**: `restaurants`
+**Merchant**: SK Pizza Junction, Sant Nagar Delhi, trial-tier subscriber, BOGO pizza Tue-Thu active
+**Trigger**: `ipl_match_today` — DC vs MI at Arun Jaitley Stadium, 7:30pm match today (Sat — *not* a weeknight)
+**Customer**: none
+
+**Composed message** (sent as Vera)
+```
+Quick heads-up Suresh — DC vs MI at Arun Jaitley tonight, 7:30pm. Important:
+Saturday IPL matches usually shift -12% restaurant covers (people watch at
+home). Skip the match-night promo today; instead push your BOGO pizza
+(already active) as a delivery-only Saturday special. Want me to draft the
+Swiggy banner + an Insta story? Live in 10 min.
+```
+
+**Compulsion levers**: counter-intuitive specific data ("Saturday IPL = -12% covers"), saves merchant from a bad decision, leverages existing offer, concrete deliverables (Swiggy banner + Insta story), 10-min commitment cap.
+
+**Score breakdown** (50/50)
+| Dimension | Score | Why |
+|---|---|---|
+| Specificity | 10 | Match details, percentage delta, time-bound |
+| Category fit | 10 | Operator-to-operator voice ("covers", "match-night") |
+| Merchant fit | 10 | Existing BOGO referenced; Swiggy/Insta channels appropriate |
+| Trigger relevance | 10 | Direct response to IPL trigger with informed nuance |
+| Engagement compulsion | 10 | Loss aversion (-12%) + existing-offer leverage + 10-min effort cap |
+
+This case is illustrative because it shows the bot **adding value beyond the trigger itself** — the trigger said "IPL match today"; the bot interpreted it correctly and gave a contrarian recommendation.
+
+---
+
+## Case Study 6 — Restaurants / Active Planning Intent (merchant-facing)
+
+**Category**: `restaurants`
+**Merchant**: Mylari South Indian Cafe, Indiranagar Bangalore — high-volume, weekday lunch thali doing 18 orders/day
+**Trigger**: `active_planning_intent` — merchant asked about a corporate-bulk thali package; explicitly said "yes good idea, what would it look like"
+**Customer**: none
+
+**Composed message** (sent as Vera, in direct conversation)
+```
+Suresh, here's a starter version — you can edit:
+
+Mylari Corporate Thali — for offices in Indiranagar
+- 10 thalis @ ₹125 each (₹25 off retail) + free delivery
+- 25 thalis @ ₹115 each + 2 free filter coffees
+- 50+: ₹105 each + 1 free dosa platter
+- WhatsApp the day-before by 5pm; we deliver between 12:30-1pm
+
+3 offices in Indiranagar are in your delivery radius (Embassy Tech, RMZ Eco,
+Sigma Soft). Want me to draft a 3-line WhatsApp to send their facilities
+managers?
+```
+
+**Compulsion levers**: complete drafted artifact (no extra work for merchant), tiered pricing matches B2B logic, concrete radius + named buildings, follow-on offer to handle outreach.
+
+**Score breakdown** (49/50)
+| Dimension | Score | Why |
+|---|---|---|
+| Specificity | 10 | Tier prices, radius, building names, time windows |
+| Category fit | 10 | Operator language ("delivery radius", "facilities managers") |
+| Merchant fit | 10 | Indiranagar locality + filter-coffee dosa nods to South Indian cafe identity |
+| Trigger relevance | 10 | Direct continuation of merchant's planning intent |
+| Engagement compulsion | 9 | Strong but assumes building data is in MerchantContext or fabricates — judge will check |
+
+---
+
+## Case Study 7 — Gyms / Seasonal Dip Reframe (merchant-facing)
+
+**Category**: `gyms`
+**Merchant**: PowerHouse Fitness, HSR Layout Bangalore, views -30% w/w (April seasonal drop), 245 active members
+**Trigger**: `seasonal_perf_dip` — expected April-June low; flagged as not-a-problem
+**Customer**: none
+
+**Composed message** (sent as Vera)
+```
+Karthik, your views are down 30% this week — but I want to flag this is the
+normal April-June acquisition lull (every metro gym sees -25 to -35% in this
+window). Action: skip ad spend now, save it for Sept-Oct when conversion is
+2x. For now, focus retention on your 245 members. Want me to draft a "summer
+attendance challenge" to keep them through the dip?
+```
+
+**Compulsion levers**: anxiety pre-emption (the dip is normal), data anchor (-25 to -35%), reframe as opportunity (save spend), specific member count, action proposal.
+
+**Score breakdown** (48/50)
+| Dimension | Score | Why |
+|---|---|---|
+| Specificity | 10 | Percentage range, months, member count |
+| Category fit | 10 | Coach-to-operator tone; uses "ad spend", "conversion" correctly |
+| Merchant fit | 10 | His exact dip number + his member count + HSR locality (peer benchmark) |
+| Trigger relevance | 10 | Directly addresses the seasonal dip with reframe |
+| Engagement compulsion | 8 | Could be sharper — "save it for Sept-Oct" is a bit hand-wavy without numbers |
+
+---
+
+## Case Study 8 — Gyms / Customer Lapse Winback (customer-facing)
+
+**Category**: `gyms` (customer-facing voice: warm, no-shame, no guilt-trip)
+**Merchant**: PowerHouse Fitness — first month @ ₹499 offer active
+**Trigger**: `customer_lapsed_hard` — Rashmi, 57 days since last visit, previous focus was weight loss, was a 5-month member
+**Customer**: Rashmi
+
+**Composed message** (sent as merchant_on_behalf)
+```
+Hi Rashmi 👋 Karthik from PowerHouse here. It's been about 8 weeks — happens
+to most members at some point, no judgment. We've added a Tue/Thu evening
+HIIT class that fits weight-loss goals well (45 min, 6:30pm). Want me to
+hold a free trial spot for you next Tue, 30 Apr? Reply YES — no commitment,
+no auto-charge.
+```
+
+**Compulsion levers**: name + warmth, no-shame framing, addresses her past goal (weight loss), specific new offering matches goal, no-commitment trial, single binary CTA.
+
+**Score breakdown** (50/50)
+| Dimension | Score | Why |
+|---|---|---|
+| Specificity | 10 | Class name, time, day, date, duration |
+| Category fit | 10 | Coach voice, no shame, evidence-based |
+| Merchant fit | 10 | Karthik (owner first name), PowerHouse, real new class |
+| Trigger relevance | 10 | Explicitly addresses lapse without being needy |
+| Engagement compulsion | 10 | "no judgment" + "no commitment, no auto-charge" removes 2 common barriers in one line |
+
+---
+
+## Case Study 9 — Pharmacies / Compliance Alert (merchant-facing)
+
+**Category**: `pharmacies`
+**Merchant**: Apollo Health Plus Pharmacy, Malviya Nagar Jaipur — engaged, has 240 chronic-Rx customers
+**Trigger**: `supply_alert` — voluntary recall on atorvastatin batches AT2024-1102 + AT2024-1108 by Mfr Z
+**Customer**: none
+
+**Composed message** (sent as Vera)
+```
+Ramesh, urgent: voluntary recall on 2 atorvastatin batches (AT2024-1102,
+AT2024-1108) by Mfr Z — sub-potency, no safety risk, but customers should be
+informed for replacement. Pulled your repeat-Rx list: 22 of your chronic-Rx
+customers were dispensed these batches in last 90 days. Want me to draft
+their WhatsApp note + the replacement-pickup workflow?
+```
+
+**Compulsion levers**: urgency + specificity (batch numbers), risk-but-bounded framing, **derived count from merchant data** (22 of 240), end-to-end workflow offer (note + pickup).
+
+**Score breakdown** (50/50)
+| Dimension | Score | Why |
+|---|---|---|
+| Specificity | 10 | Batch numbers, manufacturer, count of affected customers |
+| Category fit | 10 | Trustworthy-precise tone; correct use of "sub-potency" without alarming |
+| Merchant fit | 10 | Pulls from his customer aggregate; uses his name |
+| Trigger relevance | 10 | Direct compliance action |
+| Engagement compulsion | 10 | Urgency + clear offer of complete artifact |
+
+---
+
+## Case Study 10 — Pharmacies / Chronic Refill Reminder (customer-facing)
+
+**Category**: `pharmacies` (customer-facing voice: trustworthy, precise, respectful of senior)
+**Merchant**: Apollo Health Plus Pharmacy — free home delivery >₹499, senior 15% off active
+**Trigger**: `chronic_refill_due` — Mr. Sharma's metformin/atorvastatin/telmisartan run out 2026-04-28
+**Customer**: Mr. Sharma — 65-75 age band, senior citizen, channel via son's WhatsApp, address saved, opted in
+
+**Composed message** (sent as merchant_on_behalf, addressed to son)
+```
+Namaste — Apollo Health Plus Malviya Nagar yahan. Sharma ji ki 3 monthly
+medicines (metformin, atorvastatin, telmisartan) 28 April ko khatam hongi.
+Same dose, same brand pack ready hai. Senior discount 15% applied — total
+₹1,420 (₹240 saved). Free home delivery to saved address by 5pm tomorrow.
+Reply CONFIRM to dispatch, or call 9876543210 if any change in dosage.
+```
+
+**Compulsion levers**: namaste salutation (respectful), full molecule names (precision), specific date, total + savings shown clearly, two-channel option (reply OR call), senior-citizen norms honored.
+
+**Score breakdown** (49/50)
+| Dimension | Score | Why |
+|---|---|---|
+| Specificity | 10 | Three molecule names, exact date, total + savings, time window |
+| Category fit | 10 | Trustworthy-precise voice; namaste salutation appropriate |
+| Merchant fit | 10 | Apollo's actual offers (free delivery, senior 15%); Malviya Nagar locality |
+| Trigger relevance | 10 | Refill due date is the central anchor |
+| Engagement compulsion | 9 | Strong; could nudge with "stocks may take 24h" if scarcity were real |
+
+---
+
+## Cross-case patterns the judge looks for
+
+Reading the 10 cases together, here are the patterns that consistently score 9-10/10:
+
+1. **Source citation when claiming research/compliance** — JIDA p.14, DCI circular, batch numbers. No citation = score capped at 7.
+2. **Numbers from the contexts, not invented** — "22 of your chronic-Rx customers" is computed from the merchant's customer_aggregate; "245 active members" is from MerchantContext directly. Numbers without provenance get scored as fabrication.
+3. **Owner/merchant first name when present** — Dr. Meera, Suresh, Karthik, Ramesh. Generic "Hi" loses 1 point on merchant fit.
+4. **Single most important next step framed as low-friction commitment** — "Want me to draft X? Live in 10 min" / "Reply YES — no commitment, no auto-charge". Multi-action asks dilute.
+5. **Customer-facing messages honor language preference + relationship state** — Hindi-English mix for Priya, namaste for Mr. Sharma's son. Treating every customer the same loses 2 points on customer fit.
+6. **Domain-specific vocabulary used correctly** — "covers", "AOV", "sub-potency", "fluoride varnish", "ad spend", "conversion". Wrong vocabulary or absent vocabulary signals the bot didn't actually use the CategoryContext.voice.
+7. **The bot adds judgment, not just templating** — Case Study 5 (IPL) shows the bot recommending *not* to push the IPL promo on a Saturday. That kind of contrarian, data-informed call is the highest signal of category understanding.
+8. **The conversation_id is meaningful** — `conv_priya_recall_2026_11` is good (decodable, resumable). `conv_001` is acceptable. UUIDs without context lose nothing but help nothing.
+9. **The rationale field is concise and reflects actual reasoning** — judge cross-checks rationale against the message; mismatch = penalty.
+10. **No repetition, no fabrication** — these are the operational floor. Any of them in the message and the case is capped at 5/dimension regardless of quality.
+
+---
+
+## How the judge uses these cases
+
+For each submission, the judge LLM:
+1. Reads the candidate's composition for the same (category, merchant, trigger, customer) tuple.
+2. Compares against the case-study output above.
+3. Scores each of the 5 dimensions on a 0-10 scale, citing what's better/worse.
+4. Aggregates into the per-test-pair score.
+
+Candidates can review these cases as a north star, but **direct copying the body text of a case study counts as plagiarism** — the judge runs a similarity check on submissions vs the case studies and penalizes near-duplicates.
+
+The cases are meant to teach the *shape* of good output: specificity, category fit, merchant fit, trigger relevance, compulsion. Your wording must be your own.

judge_simulator.py

@@ -0,0 +1,962 @@
+#!/usr/bin/env python3
+"""
+magicpin AI Challenge — LLM-Powered Judge Simulator
+====================================================
+
+A strict but fair judge that scores your bot and explains WHY.
+
+HOW TO USE:
+1. Edit the CONFIGURATION section below (lines 25-45)
+2. Set your LLM provider and API key
+3. Set your bot URL
+4. Run: python judge_simulator.py
+
+That's it!
+
+Author: magicpin AI Challenge Team
+"""
+
+# =============================================================================
+# ██████  CONFIGURATION - EDIT THIS SECTION ██████
+# =============================================================================
+
+# Your bot's URL (where your bot is running)
+BOT_URL = "http://localhost:8080"
+
+# Choose your LLM provider: "openai", "anthropic", "gemini", "deepseek", "groq", "ollama", "openrouter"
+LLM_PROVIDER = "openai"
+
+# Your API key (paste your key here)
+LLM_API_KEY = ""  # <-- PUT YOUR API KEY HERE
+
+# Model to use (leave empty for default, or specify like "gpt-4o", "claude-3-5-sonnet-20241022", etc.)
+LLM_MODEL = ""  # <-- Optional: specify model or leave empty for default
+
+# For Ollama only: local server URL
+OLLAMA_URL = "http://localhost:11434"
+
+# Which test to run by default
+TEST_SCENARIO = "all"
+
+# =============================================================================
+# ██████  END OF CONFIGURATION - DON'T EDIT BELOW THIS LINE ██████
+# =============================================================================
+
+import os
+import sys
+import json
+import time
+import re
+import socket
+from datetime import datetime
+from dataclasses import dataclass, field
+from typing import Optional, List, Dict, Any, Tuple
+from pathlib import Path
+from urllib import request as urlrequest, error as urlerror
+from abc import ABC, abstractmethod
+
+# Constants
+TIMEOUT_LLM = 45
+DATASET_DIR = Path(__file__).parent / "dataset"
+
+# =============================================================================
+# TERMINAL OUTPUT
+# =============================================================================
+
+class Colors:
+    HEADER = '\033[95m'
+    BLUE = '\033[94m'
+    CYAN = '\033[96m'
+    GREEN = '\033[92m'
+    YELLOW = '\033[93m'
+    RED = '\033[91m'
+    MAGENTA = '\033[35m'
+    BOLD = '\033[1m'
+    DIM = '\033[2m'
+    RESET = '\033[0m'
+
+def print_header(text: str):
+    print(f"\n{Colors.HEADER}{Colors.BOLD}{'='*70}{Colors.RESET}")
+    print(f"{Colors.HEADER}{Colors.BOLD}{text.center(70)}{Colors.RESET}")
+    print(f"{Colors.HEADER}{Colors.BOLD}{'='*70}{Colors.RESET}\n")
+
+def print_section(text: str):
+    print(f"\n{Colors.CYAN}{Colors.BOLD}--- {text} ---{Colors.RESET}\n")
+
+def print_success(text: str):
+    print(f"{Colors.GREEN}[PASS]{Colors.RESET} {text}")
+
+def print_fail(text: str):
+    print(f"{Colors.RED}[FAIL]{Colors.RESET} {text}")
+
+def print_warn(text: str):
+    print(f"{Colors.YELLOW}[WARN]{Colors.RESET} {text}")
+
+def print_info(text: str):
+    print(f"{Colors.BLUE}[INFO]{Colors.RESET} {text}")
+
+def print_llm(text: str):
+    print(f"{Colors.MAGENTA}[LLM]{Colors.RESET} {text}")
+
+def print_score_bar(dimension: str, score: int, max_score: int = 10):
+    bar_filled = int((score / max_score) * 20)
+    bar_empty = 20 - bar_filled
+    color = Colors.GREEN if score >= 7 else Colors.YELLOW if score >= 4 else Colors.RED
+    print(f"  {dimension:22} [{color}{'█' * bar_filled}{Colors.DIM}{'░' * bar_empty}{Colors.RESET}] {color}{score:2}/{max_score}{Colors.RESET}")
+
+def print_reason(text: str):
+    wrapped = text[:200] + "..." if len(text) > 200 else text
+    print(f"    {Colors.DIM}{wrapped}{Colors.RESET}")
+
+def print_hint(hint: str):
+    print(f"\n  {Colors.YELLOW}Hint:{Colors.RESET} {hint}")
+
+# =============================================================================
+# DATA CLASSES
+# =============================================================================
+
+@dataclass
+class ScoreResult:
+    specificity: int = 0
+    specificity_reason: str = ""
+    category_fit: int = 0
+    category_fit_reason: str = ""
+    merchant_fit: int = 0
+    merchant_fit_reason: str = ""
+    decision_quality: int = 0
+    decision_quality_reason: str = ""
+    engagement_compulsion: int = 0
+    engagement_reason: str = ""
+    penalties: int = 0
+    penalty_reasons: List[str] = field(default_factory=list)
+    hint: str = ""
+
+    @property
+    def total(self) -> int:
+        return max(0, self.specificity + self.category_fit + self.merchant_fit +
+                   self.decision_quality + self.engagement_compulsion - self.penalties)
+
+# =============================================================================
+# LLM PROVIDERS
+# =============================================================================
+
+class LLMProvider(ABC):
+    @abstractmethod
+    def complete(self, prompt: str, system: str = None) -> str:
+        pass
+
+    @abstractmethod
+    def name(self) -> str:
+        pass
+
+
+class OpenAIProvider(LLMProvider):
+    def __init__(self, api_key: str, model: str = ""):
+        self.api_key = api_key
+        self.model = model or "gpt-4o-mini"
+
+    def name(self) -> str:
+        return f"OpenAI ({self.model})"
+
+    def complete(self, prompt: str, system: str = None) -> str:
+        messages = []
+        if system:
+            messages.append({"role": "system", "content": system})
+        messages.append({"role": "user", "content": prompt})
+
+        body = json.dumps({
+            "model": self.model,
+            "messages": messages,
+            "temperature": 0.2,
+            "max_tokens": 1500
+        }).encode("utf-8")
+
+        req = urlrequest.Request(
+            "https://api.openai.com/v1/chat/completions",
+            data=body,
+            headers={"Authorization": f"Bearer {self.api_key}", "Content-Type": "application/json"}
+        )
+        resp = urlrequest.urlopen(req, timeout=TIMEOUT_LLM)
+        data = json.loads(resp.read().decode("utf-8"))
+        return data["choices"][0]["message"]["content"]
+
+
+class AnthropicProvider(LLMProvider):
+    def __init__(self, api_key: str, model: str = ""):
+        self.api_key = api_key
+        self.model = model or "claude-3-5-sonnet-20241022"
+
+    def name(self) -> str:
+        return f"Anthropic ({self.model})"
+
+    def complete(self, prompt: str, system: str = None) -> str:
+        body_dict = {"model": self.model, "max_tokens": 1500,
+                     "messages": [{"role": "user", "content": prompt}]}
+        if system:
+            body_dict["system"] = system
+
+        req = urlrequest.Request(
+            "https://api.anthropic.com/v1/messages",
+            data=json.dumps(body_dict).encode("utf-8"),
+            headers={"x-api-key": self.api_key, "Content-Type": "application/json",
+                     "anthropic-version": "2023-06-01"}
+        )
+        resp = urlrequest.urlopen(req, timeout=TIMEOUT_LLM)
+        data = json.loads(resp.read().decode("utf-8"))
+        return data["content"][0]["text"]
+
+
+class GeminiProvider(LLMProvider):
+    def __init__(self, api_key: str, model: str = ""):
+        self.api_key = api_key
+        self.model = model or "gemini-1.5-flash"
+
+    def name(self) -> str:
+        return f"Gemini ({self.model})"
+
+    def complete(self, prompt: str, system: str = None) -> str:
+        full_prompt = f"{system}\n\n{prompt}" if system else prompt
+        body = json.dumps({
+            "contents": [{"parts": [{"text": full_prompt}]}],
+            "generationConfig": {"temperature": 0.2, "maxOutputTokens": 1500}
+        }).encode("utf-8")
+
+        url = f"https://generativelanguage.googleapis.com/v1beta/models/{self.model}:generateContent?key={self.api_key}"
+        req = urlrequest.Request(url, data=body, headers={"Content-Type": "application/json"})
+        resp = urlrequest.urlopen(req, timeout=TIMEOUT_LLM)
+        data = json.loads(resp.read().decode("utf-8"))
+        return data["candidates"][0]["content"]["parts"][0]["text"]
+
+
+class DeepSeekProvider(LLMProvider):
+    def __init__(self, api_key: str, model: str = ""):
+        self.api_key = api_key
+        self.model = model or "deepseek-chat"
+
+    def name(self) -> str:
+        return f"DeepSeek ({self.model})"
+
+    def complete(self, prompt: str, system: str = None) -> str:
+        messages = []
+        if system:
+            messages.append({"role": "system", "content": system})
+        messages.append({"role": "user", "content": prompt})
+
+        req = urlrequest.Request(
+            "https://api.deepseek.com/v1/chat/completions",
+            data=json.dumps({"model": self.model, "messages": messages,
+                            "temperature": 0.2, "max_tokens": 1500}).encode("utf-8"),
+            headers={"Authorization": f"Bearer {self.api_key}", "Content-Type": "application/json"}
+        )
+        resp = urlrequest.urlopen(req, timeout=TIMEOUT_LLM)
+        data = json.loads(resp.read().decode("utf-8"))
+        return data["choices"][0]["message"]["content"]
+
+
+class GroqProvider(LLMProvider):
+    def __init__(self, api_key: str, model: str = ""):
+        self.api_key = api_key
+        self.model = model or "llama-3.1-70b-versatile"
+
+    def name(self) -> str:
+        return f"Groq ({self.model})"
+
+    def complete(self, prompt: str, system: str = None) -> str:
+        messages = []
+        if system:
+            messages.append({"role": "system", "content": system})
+        messages.append({"role": "user", "content": prompt})
+
+        req = urlrequest.Request(
+            "https://api.groq.com/openai/v1/chat/completions",
+            data=json.dumps({"model": self.model, "messages": messages,
+                            "temperature": 0.2, "max_tokens": 1500}).encode("utf-8"),
+            headers={"Authorization": f"Bearer {self.api_key}", "Content-Type": "application/json"}
+        )
+        resp = urlrequest.urlopen(req, timeout=TIMEOUT_LLM)
+        data = json.loads(resp.read().decode("utf-8"))
+        return data["choices"][0]["message"]["content"]
+
+
+class OllamaProvider(LLMProvider):
+    def __init__(self, model: str = "", api_url: str = ""):
+        self.model = model or "llama3"
+        self.api_url = api_url or "http://localhost:11434"
+
+    def name(self) -> str:
+        return f"Ollama ({self.model})"
+
+    def complete(self, prompt: str, system: str = None) -> str:
+        full_prompt = f"{system}\n\n{prompt}" if system else prompt
+        req = urlrequest.Request(
+            f"{self.api_url}/api/generate",
+            data=json.dumps({"model": self.model, "prompt": full_prompt,
+                            "stream": False, "options": {"temperature": 0.2}}).encode("utf-8"),
+            headers={"Content-Type": "application/json"}
+        )
+        resp = urlrequest.urlopen(req, timeout=90)
+        data = json.loads(resp.read().decode("utf-8"))
+        return data["response"]
+
+
+class OpenRouterProvider(LLMProvider):
+    def __init__(self, api_key: str, model: str = ""):
+        self.api_key = api_key
+        self.model = model or "anthropic/claude-3-haiku"
+
+    def name(self) -> str:
+        return f"OpenRouter ({self.model})"
+
+    def complete(self, prompt: str, system: str = None) -> str:
+        messages = []
+        if system:
+            messages.append({"role": "system", "content": system})
+        messages.append({"role": "user", "content": prompt})
+
+        req = urlrequest.Request(
+            "https://openrouter.ai/api/v1/chat/completions",
+            data=json.dumps({"model": self.model, "messages": messages,
+                            "temperature": 0.2, "max_tokens": 1500}).encode("utf-8"),
+            headers={"Authorization": f"Bearer {self.api_key}", "Content-Type": "application/json",
+                     "HTTP-Referer": "https://magicpin.com"}
+        )
+        resp = urlrequest.urlopen(req, timeout=TIMEOUT_LLM)
+        data = json.loads(resp.read().decode("utf-8"))
+        return data["choices"][0]["message"]["content"]
+
+
+def create_provider() -> LLMProvider:
+    """Create LLM provider from configuration."""
+    providers = {
+        "openai": lambda: OpenAIProvider(LLM_API_KEY, LLM_MODEL),
+        "anthropic": lambda: AnthropicProvider(LLM_API_KEY, LLM_MODEL),
+        "gemini": lambda: GeminiProvider(LLM_API_KEY, LLM_MODEL),
+        "deepseek": lambda: DeepSeekProvider(LLM_API_KEY, LLM_MODEL),
+        "groq": lambda: GroqProvider(LLM_API_KEY, LLM_MODEL),
+        "ollama": lambda: OllamaProvider(LLM_MODEL, OLLAMA_URL),
+        "openrouter": lambda: OpenRouterProvider(LLM_API_KEY, LLM_MODEL),
+    }
+
+    if LLM_PROVIDER not in providers:
+        print_fail(f"Unknown provider: {LLM_PROVIDER}")
+        print_info(f"Available: {', '.join(providers.keys())}")
+        sys.exit(1)
+
+    return providers[LLM_PROVIDER]()
+
+# =============================================================================
+# DATASET & BOT CLIENT
+# =============================================================================
+
+class DatasetLoader:
+    def __init__(self, dataset_dir: Path):
+        self.dataset_dir = dataset_dir
+        self.categories = {}
+        self.merchants = {}
+        self.customers = {}
+        self.triggers = {}
+
+    def load(self) -> bool:
+        try:
+            cat_dir = self.dataset_dir / "categories"
+            if cat_dir.exists():
+                for f in cat_dir.glob("*.json"):
+                    data = json.load(open(f))
+                    self.categories[data.get("slug", f.stem)] = data
+
+            for name, container, key in [
+                ("merchants_seed.json", "merchants", "merchant_id"),
+                ("customers_seed.json", "customers", "customer_id"),
+                ("triggers_seed.json", "triggers", "id")
+            ]:
+                path = self.dataset_dir / name
+                if path.exists():
+                    data = json.load(open(path))
+                    items = data.get(container, data.get(container.rstrip("s"), []))
+                    storage = getattr(self, container)
+                    for item in items:
+                        if key in item:
+                            storage[item[key]] = item
+            return True
+        except Exception as e:
+            print_fail(f"Dataset load error: {e}")
+            return False
+
+
+class BotClient:
+    def __init__(self, base_url: str):
+        self.base_url = base_url.rstrip("/")
+
+    def _request(self, method: str, path: str, timeout: int = 30,
+                 body_dict: Dict = None) -> Tuple[Optional[Dict], Optional[str], float]:
+        url = f"{self.base_url}{path}"
+        start = time.time()
+        body = json.dumps(body_dict).encode("utf-8") if body_dict else None
+        headers = {"Content-Type": "application/json"}
+        req = urlrequest.Request(url, data=body, method=method, headers=headers)
+
+        try:
+            resp = urlrequest.urlopen(req, timeout=timeout)
+            return json.loads(resp.read().decode("utf-8")), None, (time.time() - start) * 1000
+        except urlerror.HTTPError as e:
+            latency = (time.time() - start) * 1000
+            if e.code == 401:
+                return None, "Unauthorized", latency
+            try:
+                return json.loads(e.read().decode("utf-8")), None, latency
+            except:
+                return None, f"HTTP {e.code}", latency
+        except Exception as e:
+            return None, str(e), (time.time() - start) * 1000
+
+    def healthz(self):
+        return self._request("GET", "/v1/healthz", 5)
+
+    def metadata(self):
+        return self._request("GET", "/v1/metadata", 5)
+
+    def push_context(self, scope, cid, version, payload):
+        return self._request("POST", "/v1/context", 10, {
+            "scope": scope, "context_id": cid, "version": version,
+            "payload": payload, "delivered_at": datetime.utcnow().isoformat() + "Z"
+        })
+
+    def tick(self, triggers):
+        return self._request("POST", "/v1/tick", 15, {
+            "now": datetime.utcnow().isoformat() + "Z", "available_triggers": triggers
+        })
+
+    def reply(self, conv_id, merchant_id, message, turn):
+        return self._request("POST", "/v1/reply", 15, {
+            "conversation_id": conv_id, "merchant_id": merchant_id, "customer_id": None,
+            "from_role": "merchant", "message": message,
+            "received_at": datetime.utcnow().isoformat() + "Z", "turn_number": turn
+        })
+
+# =============================================================================
+# LLM SCORING ENGINE
+# =============================================================================
+
+class LLMScorer:
+    """Scores messages using LLM and provides detailed reasoning."""
+
+    SYSTEM = """You are a STRICT judge for the magicpin AI Challenge. You score merchant engagement messages.
+
+SCORING DIMENSIONS (0-10 each, be strict - 5 is average, 7+ is good, 9+ is excellent):
+
+1. SPECIFICITY: Does the message have VERIFIABLE facts?
+   - Numbers (percentages, counts, prices)
+   - Dates/times
+   - Source citations
+   - Concrete claims vs vague statements
+
+2. CATEGORY FIT: Does the voice match the business type?
+   - Dentists: clinical, peer-to-peer, technical OK, use "Dr." prefix
+   - Salons: warm, friendly, practical
+   - Restaurants: operator-to-operator
+   - Gyms: coaching, motivational
+   - Pharmacies: trustworthy, precise
+
+3. MERCHANT FIT: Is it personalized to THIS merchant?
+   - Uses their name/owner name correctly
+   - References their actual data (not fabricated)
+   - Honors language preference
+
+4. TRIGGER RELEVANCE: Does it connect to WHY NOW?
+   - Clear reason for this specific message
+   - Uses data from the trigger payload
+   - Not a generic nudge
+
+5. ENGAGEMENT COMPULSION: Would they reply?
+   - Loss aversion, curiosity, social proof
+   - Clear CTA
+   - Low friction ask
+
+PENALTIES:
+- Fabricating data not in context: -2
+- Exposing internal jargon to merchant: -1
+
+RESPOND ONLY WITH THIS EXACT JSON FORMAT:
+{
+  "specificity": <0-10>,
+  "specificity_reason": "<why this score, 1-2 sentences>",
+  "category_fit": <0-10>,
+  "category_fit_reason": "<why this score>",
+  "merchant_fit": <0-10>,
+  "merchant_fit_reason": "<why this score>",
+  "decision_quality": <0-10>,
+  "decision_quality_reason": "<why this score>",
+  "engagement_compulsion": <0-10>,
+  "engagement_reason": "<why this score>",
+  "hint": "<one sentence guidance for improvement, cryptic not direct>"
+}"""
+
+    def __init__(self, llm: LLMProvider, dataset: DatasetLoader):
+        self.llm = llm
+        self.dataset = dataset
+
+    def score(self, action: Dict, category: Dict, merchant: Dict,
+              trigger: Dict, customer: Dict = None) -> ScoreResult:
+        """Score a message and return detailed results."""
+
+        body = action.get("body", "")
+
+        prompt = f"""SCORE THIS MESSAGE:
+
+=== CONTEXT PROVIDED TO BOT ===
+Category: {category.get('slug', 'unknown')}
+Voice: {category.get('voice', {}).get('tone', 'unknown')}
+Taboos: {category.get('voice', {}).get('vocab_taboo', [])[:5]}
+
+Merchant: {merchant.get('identity', {}).get('name', 'unknown')}
+Owner: {merchant.get('identity', {}).get('owner_first_name', 'unknown')}
+Locality: {merchant.get('identity', {}).get('locality', 'unknown')}
+Languages: {merchant.get('identity', {}).get('languages', [])}
+Performance: views={merchant.get('performance', {}).get('views', '?')}, calls={merchant.get('performance', {}).get('calls', '?')}, ctr={merchant.get('performance', {}).get('ctr', '?')}
+Signals: {merchant.get('signals', [])}
+Active Offers: {[o.get('title') for o in merchant.get('offers', []) if o.get('status') == 'active']}
+
+Trigger Kind: {trigger.get('kind', 'unknown')}
+Trigger Payload: {json.dumps(trigger.get('payload', {}))}
+Trigger Urgency: {trigger.get('urgency', '?')}
+
+Customer: {json.dumps(customer.get('identity', {})) if customer else 'None (merchant-facing)'}
+
+=== BOT'S MESSAGE ===
+Body ({len(body)} chars): "{body}"
+CTA: {action.get('cta', 'none')}
+Send As: {action.get('send_as', 'vera')}
+
+Score each dimension 0-10 with clear reasoning. Be STRICT."""
+
+        try:
+            print_llm("Analyzing message...")
+            response = self.llm.complete(prompt, self.SYSTEM)
+            return self._parse_response(response, action)
+        except Exception as e:
+            print_warn(f"LLM error: {e}")
+            return self._fallback_score(action)
+
+    def _parse_response(self, response: str, action: Dict) -> ScoreResult:
+        """Parse LLM JSON response."""
+        match = re.search(r'\{[\s\S]*\}', response)
+        if not match:
+            return self._fallback_score(action)
+
+        try:
+            data = json.loads(match.group())
+            result = ScoreResult(
+                specificity=min(10, max(0, int(data.get("specificity", 5)))),
+                specificity_reason=data.get("specificity_reason", ""),
+                category_fit=min(10, max(0, int(data.get("category_fit", 5)))),
+                category_fit_reason=data.get("category_fit_reason", ""),
+                merchant_fit=min(10, max(0, int(data.get("merchant_fit", 5)))),
+                merchant_fit_reason=data.get("merchant_fit_reason", ""),
+                decision_quality=min(10, max(0, int(data.get("decision_quality", data.get("trigger_relevance", 5))))),
+                decision_quality_reason=data.get("decision_quality_reason", data.get("trigger_relevance_reason", "")),
+                engagement_compulsion=min(10, max(0, int(data.get("engagement_compulsion", 5)))),
+                engagement_reason=data.get("engagement_reason", ""),
+                hint=data.get("hint", "")
+            )
+            return result
+        except Exception as e:
+            print_warn(f"Parse error: {e}")
+            return self._fallback_score(action)
+
+    def _fallback_score(self, action: Dict) -> ScoreResult:
+        """Basic fallback scoring."""
+        body = action.get("body", "").lower()
+        nums = len(re.findall(r'\d+', body))
+        return ScoreResult(
+            specificity=min(10, 3 + nums * 2),
+            specificity_reason="Fallback: counted numbers in message",
+            category_fit=5, category_fit_reason="Could not evaluate",
+            merchant_fit=5, merchant_fit_reason="Could not evaluate",
+            decision_quality=5, decision_quality_reason="Could not evaluate",
+            engagement_compulsion=5, engagement_reason="Could not evaluate",
+            hint="LLM scoring failed - using basic heuristics"
+        )
+
+# =============================================================================
+# MAIN JUDGE
+# =============================================================================
+
+class JudgeSimulator:
+    def __init__(self, llm: LLMProvider):
+        self.llm = llm
+        self.client = BotClient(BOT_URL)
+        self.dataset = DatasetLoader(DATASET_DIR)
+        self.scorer: Optional[LLMScorer] = None
+        self.all_scores: List[ScoreResult] = []
+
+    def run(self, scenario: str) -> bool:
+        print_header(f"LLM JUDGE — {scenario.upper()}")
+        print_info(f"Bot: {BOT_URL}")
+        print_info(f"LLM: {self.llm.name()}")
+
+        if not self.dataset.load():
+            print_fail("Dataset load failed")
+            return False
+
+        self.scorer = LLMScorer(self.llm, self.dataset)
+        print_info(f"Loaded: {len(self.dataset.categories)} categories, "
+                   f"{len(self.dataset.merchants)} merchants, "
+                   f"{len(self.dataset.triggers)} triggers")
+
+        scenarios = {
+            "warmup": self._warmup,
+            "phase2_short": self._phase2_short,
+            "auto_reply_hell": self._auto_reply,
+            "intent_transition": self._intent,
+            "hostile": self._hostile,
+            "all": self._all,
+            "full_evaluation": self._full,
+        }
+
+        if scenario not in scenarios:
+            print_fail(f"Unknown scenario: {scenario}")
+            print_info(f"Available: {', '.join(scenarios.keys())}")
+            return False
+
+        success = scenarios[scenario]()
+        self._final_summary()
+        return success
+
+    def _warmup(self) -> bool:
+        print_section("WARMUP")
+
+        data, err, lat = self.client.healthz()
+        if err:
+            print_fail(f"healthz: {err}")
+            return False
+        print_success(f"healthz ({lat:.0f}ms)")
+
+        data, err, lat = self.client.metadata()
+        if err:
+            print_warn(f"metadata: {err}")
+        else:
+            print_success(f"metadata — Team: {data.get('team_name', '?')}, Model: {data.get('model', '?')}")
+
+        print_section("CONTEXT PUSH")
+        for slug, cat in self.dataset.categories.items():
+            data, err, _ = self.client.push_context("category", slug, 1, cat)
+            status = "PASS" if data and data.get("accepted") else "FAIL"
+            print(f"  [{status}] category/{slug}")
+
+        for mid, m in list(self.dataset.merchants.items())[:5]:
+            data, err, _ = self.client.push_context("merchant", mid, 1, m)
+            status = "PASS" if data and data.get("accepted") else "FAIL"
+            short_id = mid.split('_')[1] if '_' in mid else mid[:10]
+            print(f"  [{status}] merchant/{short_id}")
+
+        return True
+
+    def _phase2_short(self) -> bool:
+        if not self._warmup():
+            return False
+
+        print_section("TICK TEST")
+
+        trigs = list(self.dataset.triggers.keys())[:3]
+        for tid in trigs:
+            self.client.push_context("trigger", tid, 1, self.dataset.triggers[tid])
+
+        data, err, lat = self.client.tick(trigs)
+        if err:
+            print_fail(f"tick: {err}")
+            return False
+
+        actions = data.get("actions", [])
+        print_info(f"Bot returned {len(actions)} action(s) ({lat:.0f}ms)")
+
+        if not actions:
+            print_warn("No actions — bot chose not to send")
+            return True
+
+        for action in actions:
+            self._score_and_display(action)
+
+        return True
+
+    def _auto_reply(self) -> bool:
+        print_section("AUTO-REPLY DETECTION")
+
+        data, err, _ = self.client.healthz()
+        if err:
+            print_fail(f"Bot unreachable: {err}")
+            return False
+
+        mid = list(self.dataset.merchants.keys())[0] if self.dataset.merchants else "m_test"
+        auto_msg = "Thank you for contacting us! Our team will respond shortly."
+
+        for i in range(1, 5):
+            print_info(f"Turn {i}: Sending auto-reply...")
+            data, err, _ = self.client.reply(f"conv_auto_{i}", mid, auto_msg, i + 1)
+
+            if err:
+                print_fail(f"Error: {err}")
+                return False
+
+            action = data.get("action", "?")
+
+            if action == "end":
+                print_success(f"Turn {i}: Bot ENDED — detected auto-reply pattern!")
+                return True
+            elif action == "wait":
+                wait_s = data.get("wait_seconds", "?")
+                print_success(f"Turn {i}: Bot WAITING {wait_s}s")
+            else:
+                body = data.get("body", "")[:50]
+                print_warn(f"Turn {i}: Bot sent: \"{body}...\"")
+
+        print_warn("Bot never ended after 4 auto-replies")
+        return True
+
+    def _intent(self) -> bool:
+        print_section("INTENT TRANSITION")
+
+        data, err, _ = self.client.healthz()
+        if err:
+            print_fail(f"Bot unreachable: {err}")
+            return False
+
+        mid = list(self.dataset.merchants.keys())[0] if self.dataset.merchants else "m_test"
+        commitment = "Ok lets do it. Whats next?"
+
+        print_info(f"Merchant: \"{commitment}\"")
+        data, err, _ = self.client.reply("conv_intent_1", mid, commitment, 2)
+
+        if err:
+            print_fail(f"Error: {err}")
+            return False
+
+        action = data.get("action", "?")
+        body = data.get("body", "")
+
+        print_info(f"Bot action: {action}")
+        if body:
+            print_info(f"Bot body: \"{body[:100]}{'...' if len(body) > 100 else ''}\"")
+
+        qualifying = ["would you", "do you", "can you tell", "what if", "how about"]
+        actioning = ["done", "sending", "draft", "here", "confirm", "proceed", "next"]
+
+        body_lower = body.lower()
+        if any(w in body_lower for w in actioning) and not any(w in body_lower for w in qualifying):
+            print_success("Bot correctly switched to ACTION mode")
+        elif any(w in body_lower for w in qualifying):
+            print_fail("Bot is STILL QUALIFYING after commitment")
+        else:
+            print_warn("Response unclear")
+
+        return True
+
+    def _hostile(self) -> bool:
+        print_section("HOSTILE HANDLING")
+
+        data, err, _ = self.client.healthz()
+        if err:
+            print_fail(f"Bot unreachable: {err}")
+            return False
+
+        mid = list(self.dataset.merchants.keys())[0] if self.dataset.merchants else "m_test"
+        hostile = "Stop messaging me. This is useless spam."
+
+        print_info(f"Merchant (hostile): \"{hostile}\"")
+        data, err, _ = self.client.reply("conv_hostile", mid, hostile, 2)
+
+        if err:
+            print_fail(f"Error: {err}")
+            return False
+
+        action = data.get("action", "?")
+        body = data.get("body", "")
+
+        print_info(f"Bot action: {action}")
+
+        if action == "end":
+            print_success("Bot correctly ENDED on hostile message")
+        elif action == "send" and any(w in body.lower() for w in ["sorry", "apolog", "won't"]):
+            print_success("Bot apologized gracefully")
+        else:
+            print_fail("Bot didn't handle hostility well")
+
+        return True
+
+    def _all(self) -> bool:
+        results = []
+        for name, fn in [("warmup", self._warmup), ("auto_reply", self._auto_reply),
+                         ("intent", self._intent), ("hostile", self._hostile)]:
+            try:
+                results.append((name, fn()))
+            except Exception as e:
+                print_fail(f"{name} crashed: {e}")
+                results.append((name, False))
+
+        print_section("SCENARIO RESULTS")
+        for name, passed in results:
+            (print_success if passed else print_fail)(name)
+
+        return all(p for _, p in results)
+
+    def _full(self) -> bool:
+        if not self._warmup():
+            return False
+
+        print_section("FULL EVALUATION")
+
+        for mid, m in self.dataset.merchants.items():
+            self.client.push_context("merchant", mid, 1, m)
+        for tid, t in self.dataset.triggers.items():
+            self.client.push_context("trigger", tid, 1, t)
+
+        print_success("All contexts pushed")
+
+        print_section("SCORING COMPOSITIONS")
+        tids = list(self.dataset.triggers.keys())
+
+        for i in range(0, len(tids), 5):
+            batch = tids[i:i+5]
+            data, err, lat = self.client.tick(batch)
+
+            if err:
+                print_warn(f"Tick failed: {err}")
+                continue
+
+            actions = data.get("actions", [])
+            print_info(f"Batch {i//5 + 1}: {len(actions)} actions ({lat:.0f}ms)")
+
+            for action in actions:
+                self._score_and_display(action, verbose=False)
+
+        return True
+
+    def _score_and_display(self, action: Dict, verbose: bool = True):
+        """Score an action and display results."""
+        tid = action.get("trigger_id", "")
+        mid = action.get("merchant_id", "")
+        cid = action.get("customer_id")
+
+        trigger = self.dataset.triggers.get(tid, {})
+        merchant = self.dataset.merchants.get(mid, {})
+        customer = self.dataset.customers.get(cid) if cid else None
+        category = self.dataset.categories.get(merchant.get("category_slug", ""), {})
+
+        score = self.scorer.score(action, category, merchant, trigger, customer)
+        self.all_scores.append(score)
+
+        body = action.get("body", "")[:50]
+        print(f"\n{Colors.CYAN}Message:{Colors.RESET} \"{body}...\"")
+
+        print_score_bar("Specificity", score.specificity)
+        if verbose and score.specificity_reason:
+            print_reason(score.specificity_reason)
+
+        print_score_bar("Category Fit", score.category_fit)
+        if verbose and score.category_fit_reason:
+            print_reason(score.category_fit_reason)
+
+        print_score_bar("Merchant Fit", score.merchant_fit)
+        if verbose and score.merchant_fit_reason:
+            print_reason(score.merchant_fit_reason)
+
+        print_score_bar("Decision Quality", score.decision_quality)
+        if verbose and score.decision_quality_reason:
+            print_reason(score.decision_quality_reason)
+
+        print_score_bar("Engagement", score.engagement_compulsion)
+        if verbose and score.engagement_reason:
+            print_reason(score.engagement_reason)
+
+        if score.penalties:
+            print(f"  {Colors.RED}Penalties: -{score.penalties}{Colors.RESET}")
+            for r in score.penalty_reasons:
+                print_reason(r)
+
+        print(f"\n  {Colors.BOLD}TOTAL: {score.total}/50{Colors.RESET}")
+
+        if verbose and score.hint:
+            print_hint(score.hint)
+
+    def _final_summary(self):
+        if not self.all_scores:
+            return
+
+        print_section("FINAL SUMMARY")
+
+        n = len(self.all_scores)
+        avg = ScoreResult(
+            specificity=sum(s.specificity for s in self.all_scores) // n,
+            category_fit=sum(s.category_fit for s in self.all_scores) // n,
+            merchant_fit=sum(s.merchant_fit for s in self.all_scores) // n,
+            decision_quality=sum(s.decision_quality for s in self.all_scores) // n,
+            engagement_compulsion=sum(s.engagement_compulsion for s in self.all_scores) // n,
+            penalties=sum(s.penalties for s in self.all_scores)
+        )
+
+        print_info(f"Messages scored: {n}\n")
+
+        print_score_bar("Avg Specificity", avg.specificity)
+        print_score_bar("Avg Category Fit", avg.category_fit)
+        print_score_bar("Avg Merchant Fit", avg.merchant_fit)
+        print_score_bar("Avg Decision Quality", avg.decision_quality)
+        print_score_bar("Avg Engagement", avg.engagement_compulsion)
+
+        total = avg.total
+        pct = (total / 50) * 100
+
+        print(f"\n{Colors.BOLD}  AVERAGE SCORE: {total}/50 ({pct:.0f}%){Colors.RESET}")
+
+        if pct >= 80:
+            print(f"\n  {Colors.GREEN}EXCELLENT{Colors.RESET}")
+        elif pct >= 60:
+            print(f"\n  {Colors.YELLOW}GOOD{Colors.RESET}")
+        elif pct >= 40:
+            print(f"\n  {Colors.YELLOW}NEEDS IMPROVEMENT{Colors.RESET}")
+        else:
+            print(f"\n  {Colors.RED}BELOW EXPECTATIONS{Colors.RESET}")
+
+# =============================================================================
+# ENTRY POINT
+# =============================================================================
+
+def main():
+    print_header("magicpin AI Challenge — LLM Judge")
+
+    # Validate configuration
+    if LLM_PROVIDER != "ollama" and not LLM_API_KEY:
+        print_fail("LLM_API_KEY is not set!")
+        print_info("Edit the CONFIGURATION section at the top of this file")
+        print_info("Set your API key for your chosen provider")
+        sys.exit(1)
+
+    # Create LLM provider
+    try:
+        llm = create_provider()
+        print_info(f"LLM Provider: {llm.name()}")
+    except Exception as e:
+        print_fail(f"Failed to create LLM provider: {e}")
+        sys.exit(1)
+
+    # Test LLM connection
+    print_info("Testing LLM connection...")
+    try:
+        test_response = llm.complete("Say 'ready' if you can hear me.", "You are a test assistant.")
+        if test_response:
+            print_success("LLM connected successfully")
+        else:
+            print_fail("LLM returned empty response")
+            sys.exit(1)
+    except Exception as e:
+        print_fail(f"LLM connection failed: {e}")
+        print_info("Check your API key and internet connection")
+        sys.exit(1)
+
+    # Run the judge
+    judge = JudgeSimulator(llm)
+    success = judge.run(TEST_SCENARIO)
+
+    sys.exit(0 if success else 1)
+
+
+if __name__ == "__main__":
+    main()

render.yaml

@@ -0,0 +1,12 @@
+services:
+  - type: web
+    name: vera-free-bot
+    runtime: python
+    plan: free
+    buildCommand: pip install -r requirements.txt
+    startCommand: uvicorn app.main:app --host 0.0.0.0 --port $PORT
+    healthCheckPath: /v1/healthz
+    envVars:
+      - key: PYTHON_VERSION
+        value: 3.11.8
+

requirements-dev.txt

@@ -0,0 +1,3 @@
+-r requirements.txt
+pytest>=8.3.4,<10
+httpx>=0.28.1,<1

requirements.txt

@@ -0,0 +1,3 @@
+fastapi>=0.115.6,<1
+uvicorn[standard]>=0.34.0,<1
+pydantic>=2.11.10,<=2.12.4

scripts/generate_submission.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+
+from app.composer import compose  # noqa: E402
+from dataset.generate_dataset import (  # noqa: E402
+    SEED,
+    expand_customers,
+    expand_merchants,
+    expand_triggers,
+    load_seeds,
+    random,
+    write_outputs,
+    write_test_pairs,
+)
+
+
+def ensure_expanded() -> Path:
+    out_dir = ROOT / "expanded"
+    if (out_dir / "test_pairs.json").exists():
+        return out_dir
+    rnd = random.Random(SEED)
+    categories, merchant_seeds, customer_seeds, trigger_seeds = load_seeds(ROOT / "dataset")
+    merchants = expand_merchants(merchant_seeds, rnd)
+    customers = expand_customers(customer_seeds, merchants, rnd)
+    triggers = expand_triggers(trigger_seeds, merchants, customers, rnd)
+    write_outputs(out_dir, categories, merchants, customers, triggers)
+    write_test_pairs(out_dir, triggers, rnd)
+    return out_dir
+
+
+def load_json(path: Path) -> dict:
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def main() -> None:
+    out_dir = ensure_expanded()
+    pairs = load_json(out_dir / "test_pairs.json")["pairs"]
+    submission_path = ROOT / "submission.jsonl"
+    with submission_path.open("w", encoding="utf-8") as fp:
+        for pair in pairs:
+            merchant = load_json(out_dir / "merchants" / f"{pair['merchant_id']}.json")
+            category = load_json(out_dir / "categories" / f"{merchant['category_slug']}.json")
+            trigger = load_json(out_dir / "triggers" / f"{pair['trigger_id']}.json")
+            customer = None
+            if pair.get("customer_id"):
+                customer = load_json(out_dir / "customers" / f"{pair['customer_id']}.json")
+            result = compose(category, merchant, trigger, customer)
+            result["test_id"] = pair["test_id"]
+            fp.write(json.dumps(result, ensure_ascii=False) + "\n")
+    print(f"Wrote {submission_path}")
+
+
+if __name__ == "__main__":
+    main()
+

scripts/geval_calibrate.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+import sys
+from urllib import request as urlrequest
+
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+
+from scripts.generate_submission import main as generate_submission  # noqa: E402
+from scripts.reference_bank import DIMENSIONS, reference_for  # noqa: E402
+
+
+def main() -> None:
+    api_key = os.getenv("OPENROUTER_API_KEY")
+    if not api_key:
+        print("OpenRouter calibration skipped: OPENROUTER_API_KEY is not set.")
+        return
+    model = os.getenv("OPENROUTER_MODEL", "openrouter/auto")
+    submission = ROOT / "submission.jsonl"
+    if not submission.exists():
+        generate_submission()
+    rows = [json.loads(line) for line in submission.read_text(encoding="utf-8").splitlines() if line.strip()]
+    limit = int(os.getenv("GEVAL_LIMIT", "10"))
+    failures: list[dict] = []
+    for row in rows[:limit]:
+        try:
+            critique = score_row(api_key, model, row)
+        except Exception as exc:
+            print(f"OpenRouter calibration unavailable for {row.get('test_id')}: {exc}")
+            raise SystemExit(2)
+        scores = critique.get("scores", {})
+        low = {k: v for k, v in scores.items() if int(v) < 7}
+        if low:
+            failures.append({"test_id": row.get("test_id"), "low": low, "critique": critique.get("critique", "")})
+        print(json.dumps({"test_id": row.get("test_id"), "scores": scores, "low": low}, ensure_ascii=False))
+    if failures:
+        print("\nLow-scoring calibration cases:")
+        for item in failures:
+            print(json.dumps(item, ensure_ascii=True))
+        raise SystemExit(1)
+    print(f"OpenRouter G-Eval calibration passed for {min(limit, len(rows))} rows.")
+
+
+def score_row(api_key: str, model: str, row: dict) -> dict:
+    category = (row.get("decision_plan", {}).get("car_summary", {}) or {}).get("category", "restaurants")
+    prompt = {
+        "task": "Act as a Prometheus-style magicpin Vera judge. Evaluate one candidate message against reference ideals.",
+        "rubric": DIMENSIONS,
+        "reference_ideals": {dimension: reference_for(category, dimension) for dimension in DIMENSIONS},
+        "rules": [
+            "Compare the candidate to the reference ideal for each dimension.",
+            "Score each dimension as an integer 0-10.",
+            "Penalize hallucinated facts, generic copy, weak CTA, bad category fit, and poor merchant fit.",
+            "Return JSON only with keys: scores, critique, deterministic_fix.",
+        ],
+        "candidate": {
+            "body": row.get("body"),
+            "cta": row.get("cta"),
+            "send_as": row.get("send_as"),
+            "rationale": row.get("rationale"),
+            "decision_plan": row.get("decision_plan", {}),
+        },
+    }
+    payload_obj = {
+        "model": model,
+        "messages": [
+            {"role": "system", "content": "You are a strict rubric evaluator. Return compact JSON only."},
+            {"role": "user", "content": json.dumps(prompt, ensure_ascii=False)},
+        ],
+        "temperature": 0.0,
+        "max_tokens": int(os.getenv("GEVAL_MAX_TOKENS", "1800")),
+    }
+    if os.getenv("GEVAL_RESPONSE_FORMAT", "0") == "1":
+        payload_obj["response_format"] = {"type": "json_object"}
+    payload = json.dumps(payload_obj).encode("utf-8")
+    req = urlrequest.Request(
+        "https://openrouter.ai/api/v1/chat/completions",
+        data=payload,
+        headers={
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type": "application/json",
+            "HTTP-Referer": os.getenv("OPENROUTER_SITE_URL", "http://localhost"),
+            "X-Title": os.getenv("OPENROUTER_APP_NAME", "Vera Calibration"),
+        },
+        method="POST",
+    )
+    with urlrequest.urlopen(req, timeout=30) as resp:
+        data = json.loads(resp.read().decode("utf-8"))
+    choice = data.get("choices", [{}])[0]
+    message = choice.get("message", {}) or {}
+    content = message.get("content")
+    if isinstance(content, list):
+        content = "".join(str(part.get("text", "")) if isinstance(part, dict) else str(part) for part in content)
+    if not content:
+        raise RuntimeError(f"model returned no message content; finish_reason={choice.get('finish_reason')!r}")
+    try:
+        return json.loads(content)
+    except json.JSONDecodeError:
+        start = content.find("{")
+        end = content.rfind("}")
+        if start >= 0 and end > start:
+            return json.loads(content[start : end + 1])
+        raise
+
+
+if __name__ == "__main__":
+    main()

scripts/keep_warm.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+import argparse
+import json
+import time
+from urllib import request
+
+
+def ping(base_url: str) -> None:
+    url = base_url.rstrip("/") + "/v1/healthz"
+    with request.urlopen(url, timeout=10) as response:
+        print(json.loads(response.read().decode("utf-8")))
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Free-host keep-warm pinger for Vera bot.")
+    parser.add_argument("base_url", help="Public base URL, e.g. https://your-bot.koyeb.app")
+    parser.add_argument("--interval", type=int, default=900, help="Seconds between pings. Default: 15 minutes.")
+    args = parser.parse_args()
+
+    while True:
+        try:
+            ping(args.base_url)
+        except Exception as exc:
+            print(f"ping failed: {exc}")
+        time.sleep(args.interval)
+
+
+if __name__ == "__main__":
+    main()

scripts/lint_submission.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import json
+import re
+import sys
+from collections import Counter
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+DEFAULT_PATH = ROOT / "submission.jsonl"
+REQUIRED = {"test_id", "body", "cta", "send_as", "suppression_key", "rationale"}
+BAD_PATTERNS = [
+    ("literal None", re.compile(r"\bNone\b")),
+    ("double Dr", re.compile(r"\bDr\.\s+Dr\.", re.IGNORECASE)),
+    ("internal suppression copy", re.compile(r"I will not send|no matching opt-in", re.IGNORECASE)),
+    ("fake zero percent movement", re.compile(r"\b(up|down|dropped|rose|increased)\s+0%\b", re.IGNORECASE)),
+    ("baseline normal placeholder", re.compile(r"\bbaseline normal\b", re.IGNORECASE)),
+    ("missing-data placeholder", re.compile(r"the available context", re.IGNORECASE)),
+    ("generic growth copy", re.compile(r"increase sales|boost sales|grow your business", re.IGNORECASE)),
+]
+
+
+def lint(path: Path) -> list[str]:
+    errors: list[str] = []
+    if not path.exists():
+        return [f"{path} does not exist"]
+
+    seen_bodies: Counter[str] = Counter()
+    for line_no, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
+        try:
+            item = json.loads(line)
+        except json.JSONDecodeError as exc:
+            errors.append(f"line {line_no}: invalid JSON: {exc}")
+            continue
+
+        missing = REQUIRED - set(item)
+        if missing:
+            errors.append(f"line {line_no}: missing keys {sorted(missing)}")
+            continue
+
+        body = str(item.get("body", "")).strip()
+        rationale = str(item.get("rationale", "")).strip()
+        cta = str(item.get("cta", "")).strip()
+        send_as = str(item.get("send_as", "")).strip()
+        suppression_key = str(item.get("suppression_key", "")).strip()
+        if not body:
+            errors.append(f"line {line_no}: empty body")
+        if not rationale:
+            errors.append(f"line {line_no}: empty rationale")
+        if not cta:
+            errors.append(f"line {line_no}: empty cta")
+        if send_as not in {"vera", "merchant_on_behalf"}:
+            errors.append(f"line {line_no}: invalid send_as {send_as!r}")
+        if not suppression_key:
+            errors.append(f"line {line_no}: empty suppression_key")
+        for label, pattern in BAD_PATTERNS:
+            if pattern.search(body):
+                errors.append(f"line {line_no}: {label} in body")
+        decision_plan = item.get("decision_plan", {}) or {}
+        if decision_plan.get("constitutional_violations"):
+            errors.append(f"line {line_no}: constitutional violations {decision_plan['constitutional_violations']}")
+        seen_bodies[body] += 1
+
+    for body, count in seen_bodies.items():
+        if body and count > 1:
+            errors.append(f"duplicate body appears {count} times: {body[:120]}")
+
+    return errors
+
+
+def main() -> int:
+    path = Path(sys.argv[1]).resolve() if len(sys.argv) > 1 else DEFAULT_PATH
+    errors = lint(path)
+    if errors:
+        print("submission lint failed:")
+        for err in errors:
+            print(f"- {err}")
+        return 1
+    print(f"submission lint passed: {path}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/reference_bank.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+
+DIMENSIONS = [
+    "decision_quality",
+    "specificity",
+    "category_fit",
+    "merchant_fit",
+    "engagement_compulsion",
+]
+
+
+REFERENCE_BANK: dict[str, str] = {
+    "dentists:decision_quality": "Dr. Meera, the research digest points to high-risk adult recall timing; use the 3-month fluoride finding before the next recall batch.",
+    "dentists:specificity": "Dr. Meera, JIDA Oct 2026 cites 124 high-risk adult caries patients for 3-month fluoride recall; want me to draft that recall note?",
+    "dentists:category_fit": "Clinical angle: use the cited recall evidence, avoid overclaiming, and ask for one approval before any patient outreach.",
+    "dentists:merchant_fit": "Dr. Meera, your Lajpat Nagar clinic has an active Rs 299 cleaning hook; pair it with the recall cohort instead of a generic discount.",
+    "dentists:engagement_compulsion": "Reply YES and I will draft the exact patient recall WhatsApp from the JIDA item and your Rs 299 cleaning offer.",
+    "salons:decision_quality": "Use the customer's occasion or slot window first, then offer a concrete package follow-up instead of a generic promo.",
+    "salons:specificity": "Kavya's wedding is 42 days away and Saturday slots are preferred; ask to hold one skin-prep slot with the active bridal package.",
+    "salons:category_fit": "Warm service angle: visual, occasion-led, slot-aware, and never clinical or pressure-heavy.",
+    "salons:merchant_fit": "Studio11 has bridal follow-up history and a live service package; make Vera prepare the exact WhatsApp and slot hold.",
+    "salons:engagement_compulsion": "Reply YES and I will hold the Saturday slot plus draft the 4-line bridal follow-up now.",
+    "restaurants:decision_quality": "Tie the action to the operator signal: orders, covers, delivery delay, IPL timing, or corporate lunch planning.",
+    "restaurants:specificity": "Delhi IPL night is today and the paneer thali offer is live; draft one banner/menu note before evening orders start.",
+    "restaurants:category_fit": "Operator angle: concise, service-window aware, focused on orders, delivery, covers, and menu hooks.",
+    "restaurants:merchant_fit": "Use this restaurant's live offer, locality, recent calls/orders, and review theme before suggesting a campaign.",
+    "restaurants:engagement_compulsion": "Reply YES and I will prepare the exact banner and WhatsApp text for tonight's order window.",
+    "gyms:decision_quality": "Pick the retention or trial action that matches the member stage and recent attendance trend.",
+    "gyms:specificity": "Rashmi is 28 days lapsed after yoga trial; use the no-commitment restart slot and her preferred evening timing.",
+    "gyms:category_fit": "Coach-to-operator tone: no shame, no body-negative copy, clear class or challenge next step.",
+    "gyms:merchant_fit": "Use the gym's current class, member count, lapse segment, and previous training focus in the message.",
+    "gyms:engagement_compulsion": "Reply YES and I will hold one no-commitment restart slot and send the member-safe message.",
+    "pharmacies:decision_quality": "For stock, refill, or compliance triggers, choose the safest precise action before any promotional angle.",
+    "pharmacies:specificity": "Atorvastatin batch A12 is affected and 38 chronic-Rx customers are in context; draft the replacement note and counter checklist.",
+    "pharmacies:category_fit": "Calm precision: molecule, batch, refill date, delivery status, and no diagnosis or panic wording.",
+    "pharmacies:merchant_fit": "Use the pharmacy's repeat-customer count, saved delivery status, active free-delivery hook, and stock facts.",
+    "pharmacies:engagement_compulsion": "Reply CONFIRM and I will prepare the customer note plus counter checklist from the exact batch/refill facts.",
+}
+
+
+def reference_for(category: str, dimension: str) -> str:
+    return REFERENCE_BANK.get(f"{category}:{dimension}") or REFERENCE_BANK.get(f"restaurants:{dimension}", "")

scripts/score_proxy.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+
+from app.decision_engine import build_candidates, extract_evidence  # noqa: E402
+
+
+def load(path: Path) -> dict:
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def ensure_expanded() -> Path:
+    out = ROOT / "expanded"
+    if not (out / "test_pairs.json").exists():
+        import subprocess
+        subprocess.run([sys.executable, "dataset/generate_dataset.py", "--seed-dir", "dataset", "--out", "expanded"], cwd=ROOT, check=True)
+    return out
+
+
+def score_pair(out: Path, pair: dict) -> tuple[int, dict]:
+    merchant = load(out / "merchants" / f"{pair['merchant_id']}.json")
+    category = load(out / "categories" / f"{merchant['category_slug']}.json")
+    trigger = load(out / "triggers" / f"{pair['trigger_id']}.json")
+    customer = load(out / "customers" / f"{pair['customer_id']}.json") if pair.get("customer_id") else None
+    evidence = extract_evidence(category, merchant, trigger, customer)
+    candidates = build_candidates(category, merchant, trigger, customer, evidence)
+    if not candidates:
+        return 0, {"reason": "no candidates"}
+    best = max(candidates, key=lambda c: c.total_score)
+    return best.total_score, {
+        "scores": best.rubric_scores,
+        "signal": best.primary_signal,
+        "lever": best.selected_lever,
+        "body": best.body,
+    }
+
+
+def main() -> int:
+    threshold = int(sys.argv[1]) if len(sys.argv) > 1 else 36
+    out = ensure_expanded()
+    pairs = load(out / "test_pairs.json")["pairs"]
+    failures = []
+    totals = []
+    for pair in pairs:
+        total, detail = score_pair(out, pair)
+        totals.append(total)
+        if total < threshold:
+            failures.append((pair["test_id"], total, detail))
+    avg = sum(totals) / max(1, len(totals))
+    print(f"proxy scored {len(totals)} canonical pairs; avg={avg:.1f}/50 min={min(totals) if totals else 0}/50 threshold={threshold}")
+    if failures:
+        print("proxy score failures:")
+        for test_id, total, detail in failures:
+            print(f"- {test_id}: {total}/50 {detail}")
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+

tests/test_bot.py

@@ -0,0 +1,421 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+import sys
+
+from fastapi.testclient import TestClient
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+
+from app.decision_engine import build_candidates, build_merchant_car, constitutional_violations, extract_evidence, score_map, select_cialdini_principle  # noqa: E402
+from app.main import app, category_arm_pool, contexts, conversations, merchant_action_memory, merchant_auto_replies, merchant_opt_out, suppressed  # noqa: E402
+
+
+def load_seed(name: str, key: str) -> list[dict]:
+    return json.loads((ROOT / "dataset" / name).read_text(encoding="utf-8"))[key]
+
+
+def load_category(slug: str) -> dict:
+    return json.loads((ROOT / "dataset" / "categories" / f"{slug}.json").read_text(encoding="utf-8"))
+
+
+def reset_state() -> None:
+    contexts.clear()
+    conversations.clear()
+    suppressed.clear()
+    merchant_opt_out.clear()
+    merchant_auto_replies.clear()
+    merchant_action_memory.clear()
+    category_arm_pool.clear()
+
+
+def push(client: TestClient, scope: str, context_id: str, payload: dict, version: int = 1):
+    return client.post(
+        "/v1/context",
+        json={"scope": scope, "context_id": context_id, "version": version, "payload": payload, "delivered_at": "2026-04-26T10:00:00Z"},
+    )
+
+
+def test_health_and_context_idempotency():
+    reset_state()
+    client = TestClient(app)
+    assert client.get("/v1/healthz").json()["status"] == "ok"
+    cat = load_category("dentists")
+    resp = push(client, "category", "dentists", cat)
+    assert resp.status_code == 200
+    assert resp.json()["accepted"] is True
+    same = push(client, "category", "dentists", cat)
+    assert same.status_code == 200
+    assert same.json()["idempotent"] is True
+    stale = push(client, "category", "dentists", cat, version=0)
+    assert stale.status_code == 409
+
+
+def test_tick_creates_grounded_research_action():
+    reset_state()
+    client = TestClient(app)
+    merchants = load_seed("merchants_seed.json", "merchants")
+    triggers = load_seed("triggers_seed.json", "triggers")
+    merchant = merchants[0]
+    trigger = triggers[0]
+    push(client, "category", "dentists", load_category("dentists"))
+    push(client, "merchant", merchant["merchant_id"], merchant)
+    push(client, "trigger", trigger["id"], trigger)
+
+    resp = client.post("/v1/tick", json={"now": "2026-04-26T10:30:00Z", "available_triggers": [trigger["id"]]})
+    assert resp.status_code == 200
+    actions = resp.json()["actions"]
+    assert len(actions) == 1
+    body = actions[0]["body"]
+    assert "JIDA" in body
+    assert "124" in body
+    assert actions[0]["send_as"] == "vera"
+    assert actions[0]["suppression_key"] == trigger["suppression_key"]
+
+
+def test_customer_consent_and_send_as():
+    reset_state()
+    client = TestClient(app)
+    merchants = load_seed("merchants_seed.json", "merchants")
+    customers = load_seed("customers_seed.json", "customers")
+    triggers = load_seed("triggers_seed.json", "triggers")
+    merchant = merchants[0]
+    customer = customers[0]
+    trigger = triggers[2]
+    push(client, "category", "dentists", load_category("dentists"))
+    push(client, "merchant", merchant["merchant_id"], merchant)
+    push(client, "customer", customer["customer_id"], customer)
+    push(client, "trigger", trigger["id"], trigger)
+
+    resp = client.post("/v1/tick", json={"now": "2026-04-26T11:00:00Z", "available_triggers": [trigger["id"]]})
+    action = resp.json()["actions"][0]
+    assert action["send_as"] == "merchant_on_behalf"
+    assert action["customer_id"] == customer["customer_id"]
+    assert "Priya" in action["body"]
+    assert "Wed 5 Nov" in action["body"]
+
+
+def test_reply_replay_behaviors():
+    reset_state()
+    client = TestClient(app)
+    auto = "Thank you for contacting us! Our team will respond shortly."
+    first = client.post("/v1/reply", json={"conversation_id": "conv_auto", "merchant_id": "m1", "from_role": "merchant", "message": auto, "turn_number": 2}).json()
+    assert first["action"] == "wait"
+    second = client.post("/v1/reply", json={"conversation_id": "conv_auto", "merchant_id": "m1", "from_role": "merchant", "message": auto, "turn_number": 3}).json()
+    assert second["action"] == "wait"
+    third = client.post("/v1/reply", json={"conversation_id": "conv_auto", "merchant_id": "m1", "from_role": "merchant", "message": auto, "turn_number": 4}).json()
+    assert third["action"] == "end"
+
+    intent = client.post("/v1/reply", json={"conversation_id": "conv_intent", "merchant_id": "m1", "from_role": "merchant", "message": "Ok lets do it. Whats next?", "turn_number": 2}).json()
+    assert intent["action"] == "send"
+    assert "preparing" in intent["body"]
+    assert intent["cta"] == "none"
+
+    hostile = client.post("/v1/reply", json={"conversation_id": "conv_hostile", "merchant_id": "m1", "from_role": "merchant", "message": "Stop messaging me. This is useless spam.", "turn_number": 2}).json()
+    assert hostile["action"] == "end"
+
+    plain_stop = client.post("/v1/reply", json={"conversation_id": "conv_plain_stop", "merchant_id": "m1", "from_role": "merchant", "message": "STOP", "turn_number": 2}).json()
+    assert plain_stop["action"] == "end"
+
+    offtopic = client.post("/v1/reply", json={"conversation_id": "conv_offtopic", "merchant_id": "m1", "from_role": "merchant", "message": "What is the cricket score?", "turn_number": 2}).json()
+    assert offtopic["action"] == "send"
+    assert "outside" in offtopic["body"].lower()
+
+
+def test_ended_conversation_never_sends_again_and_omitted_merchant_optout():
+    reset_state()
+    client = TestClient(app)
+    conversations["conv_done"] = {"merchant_id": "m_done", "ended": True, "turns": []}
+    resp = client.post("/v1/reply", json={"conversation_id": "conv_done", "from_role": "merchant", "message": "hello", "turn_number": 5}).json()
+    assert resp["action"] == "end"
+
+    conversations["conv_stop"] = {"merchant_id": "m_stop", "ended": False, "turns": []}
+    stop = client.post("/v1/reply", json={"conversation_id": "conv_stop", "from_role": "merchant", "message": "Stop messaging me", "turn_number": 2}).json()
+    assert stop["action"] == "end"
+    assert "m_stop" in merchant_opt_out
+
+
+def test_validation_errors_are_challenge_style_400():
+    reset_state()
+    client = TestClient(app)
+    resp = client.post("/v1/context", json={"scope": "category"})
+    assert resp.status_code == 400
+    body = resp.json()
+    assert body["accepted"] is False
+    assert body["reason"] == "malformed"
+
+
+def test_merchant_level_auto_reply_tracking_across_conversations():
+    reset_state()
+    client = TestClient(app)
+    auto = "Thank you for contacting us! Our team will respond shortly."
+    assert client.post("/v1/reply", json={"conversation_id": "conv_auto_1", "merchant_id": "m1", "from_role": "merchant", "message": auto, "turn_number": 2}).json()["action"] == "wait"
+    assert client.post("/v1/reply", json={"conversation_id": "conv_auto_2", "merchant_id": "m1", "from_role": "merchant", "message": auto, "turn_number": 3}).json()["action"] == "wait"
+    assert client.post("/v1/reply", json={"conversation_id": "conv_auto_3", "merchant_id": "m1", "from_role": "merchant", "message": auto, "turn_number": 4}).json()["action"] == "end"
+
+
+def test_placeholder_triggers_do_not_leak_missing_fields():
+    reset_state()
+    client = TestClient(app)
+    merchant = load_seed("merchants_seed.json", "merchants")[5]
+    trigger = {
+        "id": "trg_placeholder_competitor",
+        "scope": "merchant",
+        "kind": "competitor_opened",
+        "source": "external",
+        "merchant_id": merchant["merchant_id"],
+        "customer_id": None,
+        "payload": {"placeholder": True, "metric_or_topic": "competitor_opened"},
+        "urgency": 2,
+        "suppression_key": "competitor:placeholder",
+        "expires_at": "2026-06-30T00:00:00Z",
+    }
+    push(client, "category", merchant["category_slug"], load_category(merchant["category_slug"]))
+    push(client, "merchant", merchant["merchant_id"], merchant)
+    push(client, "trigger", trigger["id"], trigger)
+    action = client.post("/v1/tick", json={"now": "2026-04-26T10:00:00Z", "available_triggers": [trigger["id"]]}).json()["actions"][0]
+    assert "None" not in action["body"]
+    assert "the available context" not in action["body"]
+    assert action["cta"] == "binary_yes_no"
+
+
+def test_customer_without_matching_consent_routes_to_merchant_not_dead_line():
+    reset_state()
+    client = TestClient(app)
+    merchant = load_seed("merchants_seed.json", "merchants")[7]
+    customer = load_seed("customers_seed.json", "customers")[11]
+    trigger = {
+        "id": "trg_recall_no_scope",
+        "scope": "customer",
+        "kind": "recall_due",
+        "source": "internal",
+        "merchant_id": merchant["merchant_id"],
+        "customer_id": customer["customer_id"],
+        "payload": {"placeholder": True, "metric_or_topic": "recall_due"},
+        "urgency": 2,
+        "suppression_key": "recall:no_scope",
+        "expires_at": "2026-06-30T00:00:00Z",
+    }
+    push(client, "category", merchant["category_slug"], load_category(merchant["category_slug"]))
+    push(client, "merchant", merchant["merchant_id"], merchant)
+    push(client, "customer", customer["customer_id"], customer)
+    push(client, "trigger", trigger["id"], trigger)
+    action = client.post("/v1/tick", json={"now": "2026-04-26T10:00:00Z", "available_triggers": [trigger["id"]]}).json()["actions"][0]
+    assert action["send_as"] == "vera"
+    assert action["cta"] == "binary_yes_no"
+    assert "I will not send" not in action["body"]
+
+
+def test_decision_engine_scores_case_anchor_shapes():
+    merchants = load_seed("merchants_seed.json", "merchants")
+    customers = load_seed("customers_seed.json", "customers")
+    triggers = load_seed("triggers_seed.json", "triggers")
+    cases = [
+        (merchants[0], triggers[0], None),
+        (merchants[0], triggers[2], customers[0]),
+        (merchants[4], triggers[9], None),
+        (merchants[6], triggers[13], None),
+        (merchants[8], triggers[17], None),
+        (merchants[8], triggers[18], customers[12]),
+    ]
+    for merchant, trigger, customer in cases:
+        category = load_category(merchant["category_slug"])
+        evidence = extract_evidence(category, merchant, trigger, customer)
+        candidates = build_candidates(category, merchant, trigger, customer, evidence)
+        assert candidates
+        best = max(candidates, key=lambda c: c.total_score)
+        assert best.total_score >= 36, (trigger["id"], best.total_score, best.body, best.rubric_scores)
+        assert any(ch.isdigit() for ch in best.body)
+        assert trigger["kind"].replace("_", " ") in best.body.lower() or any(e.source.startswith("trigger") for e in best.evidence)
+
+
+def test_full_expanded_dataset_proxy_has_no_weak_outputs():
+    import subprocess
+    import sys as _sys
+    subprocess.run([_sys.executable, "dataset/generate_dataset.py", "--seed-dir", "dataset", "--out", "expanded"], cwd=ROOT, check=True, capture_output=True)
+    result = subprocess.run([_sys.executable, "scripts/score_proxy.py", "34"], cwd=ROOT, text=True, capture_output=True)
+    assert result.returncode == 0, result.stdout + result.stderr
+
+
+def test_car_map_jitai_and_best_of_n_debug_fields():
+    merchant = load_seed("merchants_seed.json", "merchants")[0]
+    trigger = load_seed("triggers_seed.json", "triggers")[0]
+    category = load_category(merchant["category_slug"])
+    car = build_merchant_car(category, merchant, trigger)
+    assert car.merchant_name != "unknown"
+    assert car.category == "dentists"
+    assert all(value is not None for value in car.summary().values())
+
+    evidence = extract_evidence(category, merchant, trigger, None, car)
+    candidates = build_candidates(category, merchant, trigger, None, evidence, car)
+    assert len(candidates) >= 3
+    best = max(candidates, key=lambda c: c.total_score)
+    assert best.decision_plan if hasattr(best, "decision_plan") else True
+    assert best.car_summary["category"] == "dentists"
+    assert {"severity", "receptivity", "intervention_fit"} <= set(best.jitai_scores)
+    assert {"motivation", "ability", "prompt"} <= set(best.map_scores)
+    assert best.frame in {"loss_frame", "gain_frame", "certainty_frame", "social_proof", "professional_value", "effort_externalization"}
+
+
+def test_bmap_penalizes_high_friction_cta():
+    merchant = load_seed("merchants_seed.json", "merchants")[0]
+    trigger = load_seed("triggers_seed.json", "triggers")[0]
+    category = load_category(merchant["category_slug"])
+    car = build_merchant_car(category, merchant, trigger)
+    easy = score_map(car, trigger, "JIDA says 124 patients are relevant. Reply YES and I will draft it.", "binary_yes_no", "professional_value", [])
+    hard = score_map(car, trigger, "JIDA says 124 patients are relevant. Please call, log in, choose a campaign, upload a file, and configure delivery.", "open_ended", "professional_value", [])
+    assert easy["ability"] > hard["ability"]
+
+
+def test_frames_follow_trigger_shape_and_action_memory_changes_plan():
+    merchant = load_seed("merchants_seed.json", "merchants")[1]
+    category = load_category(merchant["category_slug"])
+    dip = load_seed("triggers_seed.json", "triggers")[3]
+    spike = {**dip, "id": "trg_spike_test", "kind": "perf_spike", "payload": {"metric": "calls", "delta_pct": 0.18}, "urgency": 2}
+    dip_candidates = build_candidates(category, merchant, dip, None, extract_evidence(category, merchant, dip))
+    spike_candidates = build_candidates(category, merchant, spike, None, extract_evidence(category, merchant, spike))
+    assert any(c.frame == "loss_frame" for c in dip_candidates)
+    assert any(c.frame == "gain_frame" for c in spike_candidates)
+
+    remembered = {**merchant, "__vera_memory": {"last_action_type": "recovery_nudge", "last_response_intent": "auto_reply", "repeated_action_count": 3, "no_reply_count": 2}}
+    car = build_merchant_car(category, remembered, dip)
+    evidence = extract_evidence(category, remembered, dip, None, car)
+    candidates = build_candidates(category, remembered, dip, None, evidence, car)
+    assert all(c.jitai_scores["receptivity"] <= 4 for c in candidates)
+
+
+def test_openrouter_calibration_skips_without_key(monkeypatch):
+    import subprocess
+    import sys as _sys
+    monkeypatch.delenv("OPENROUTER_API_KEY", raising=False)
+    result = subprocess.run([_sys.executable, "scripts/geval_calibrate.py"], cwd=ROOT, text=True, capture_output=True)
+    assert result.returncode == 0
+    assert "skipped" in result.stdout.lower()
+
+
+def test_cialdini_constitution_and_tot_debug_fields():
+    merchant = load_seed("merchants_seed.json", "merchants")[0]
+    trigger = load_seed("triggers_seed.json", "triggers")[0]
+    category = load_category(merchant["category_slug"])
+    car = build_merchant_car(category, merchant, trigger)
+    evidence = extract_evidence(category, merchant, trigger, None, car)
+    principle = select_cialdini_principle(car, trigger, evidence, "professional_value")
+    assert principle in {"authority", "social_proof", "liking", "reciprocity", "scarcity", "commitment"}
+    bad = "Dear valued partner, want to increase sales? Contact us?"
+    violations = constitutional_violations(bad, car, trigger, "open_ended")
+    assert "generic_or_corporate_copy" in violations
+
+    candidates = build_candidates(category, merchant, trigger, None, evidence, car)
+    best = max(candidates, key=lambda c: c.total_score)
+    assert best.thought_frames
+    assert best.persuasion_principle
+    assert best.reference_key.startswith("dentists:")
+    assert not best.constitutional_violations
+
+
+def test_category_empirical_prior_flows_into_car():
+    reset_state()
+    client = TestClient(app)
+    merchant = load_seed("merchants_seed.json", "merchants")[0]
+    trigger = load_seed("triggers_seed.json", "triggers")[0]
+    push(client, "category", merchant["category_slug"], load_category(merchant["category_slug"]))
+    push(client, "merchant", merchant["merchant_id"], merchant)
+    push(client, "trigger", trigger["id"], trigger)
+    first = client.post("/v1/tick", json={"now": "2026-04-26T10:00:00Z", "available_triggers": [trigger["id"]]}).json()["actions"][0]
+    client.post("/v1/reply", json={"conversation_id": first["conversation_id"], "merchant_id": merchant["merchant_id"], "from_role": "merchant", "message": "yes go ahead", "turn_number": 2})
+    assert category_arm_pool[merchant["category_slug"]]
+    next_trigger = {**trigger, "id": "trg_research_next", "suppression_key": "research:next"}
+    push(client, "trigger", next_trigger["id"], next_trigger, version=1)
+    second = client.post("/v1/tick", json={"now": "2026-04-26T10:05:00Z", "available_triggers": [next_trigger["id"]]}).json()["actions"][0]
+    priors = second["decision_plan"]["car_summary"]["category_arm_priors"]
+    assert priors
+
+
+def test_sparse_context_fallback_stays_specific_and_safe():
+    category = load_category("restaurants")
+    merchant = {
+        "merchant_id": "m_sparse_restaurant",
+        "category_slug": "restaurants",
+        "identity": {"name": "Asha Cafe", "owner_first_name": "Asha", "locality": "Indiranagar"},
+        "performance": {},
+        "offers": [],
+        "customer_aggregate": {},
+        "signals": [],
+        "conversation_history": [],
+    }
+    trigger = {
+        "id": "trg_sparse_reactivation",
+        "scope": "merchant",
+        "kind": "merchant_inactive",
+        "source": "internal",
+        "merchant_id": merchant["merchant_id"],
+        "payload": {"days_inactive": 14},
+        "urgency": 1,
+        "expires_at": "2026-06-30T00:00:00Z",
+    }
+    car = build_merchant_car(category, merchant, trigger)
+    evidence = extract_evidence(category, merchant, trigger, None, car)
+    candidates = build_candidates(category, merchant, trigger, None, evidence, car)
+    assert len(candidates) == 1
+    body = candidates[0].body
+    assert "Asha" in body
+    assert "Indiranagar" in body
+    assert "increase sales" not in body.lower()
+    assert "sparse_context_floor" in candidates[0].risk_flags
+
+
+def test_broad_suppression_keys_are_made_unique():
+    reset_state()
+    client = TestClient(app)
+    merchant = load_seed("merchants_seed.json", "merchants")[4]
+    category = load_category(merchant["category_slug"])
+    push(client, "category", merchant["category_slug"], category)
+    push(client, "merchant", merchant["merchant_id"], merchant)
+    t1 = {"id": "trg_broad_1", "scope": "merchant", "kind": "curious_ask_due", "source": "internal", "merchant_id": merchant["merchant_id"], "payload": {"topic": "lunch"}, "urgency": 2, "suppression_key": "curious_ask_due"}
+    t2 = {"id": "trg_broad_2", "scope": "merchant", "kind": "curious_ask_due", "source": "internal", "merchant_id": merchant["merchant_id"], "payload": {"topic": "dinner"}, "urgency": 2, "suppression_key": "curious_ask_due"}
+    push(client, "trigger", t1["id"], t1)
+    push(client, "trigger", t2["id"], t2)
+    actions = client.post("/v1/tick", json={"now": "2026-05-02T10:00:00Z", "available_triggers": [t1["id"], t2["id"]]}).json()["actions"]
+    assert len(actions) == 2
+    assert actions[0]["suppression_key"] != actions[1]["suppression_key"]
+
+
+def test_context_updates_do_not_wipe_reply_memory():
+    reset_state()
+    client = TestClient(app)
+    merchant = load_seed("merchants_seed.json", "merchants")[0]
+    trigger = load_seed("triggers_seed.json", "triggers")[0]
+    push(client, "category", merchant["category_slug"], load_category(merchant["category_slug"]))
+    push(client, "merchant", merchant["merchant_id"], merchant)
+    push(client, "trigger", trigger["id"], trigger)
+    first = client.post("/v1/tick", json={"now": "2026-04-26T10:00:00Z", "available_triggers": [trigger["id"]]}).json()["actions"][0]
+    client.post("/v1/reply", json={"conversation_id": first["conversation_id"], "merchant_id": merchant["merchant_id"], "from_role": "merchant", "message": "yes go ahead"})
+    push(client, "merchant", merchant["merchant_id"], {**merchant, "signals": ["fresh update"]}, version=2)
+    assert merchant_action_memory[merchant["merchant_id"]]["last_response_intent"] == "commitment"
+
+
+def test_pharmacy_without_consent_routes_to_merchant_and_avoids_medical_dispatch():
+    merchant = load_seed("merchants_seed.json", "merchants")[8]
+    customer = {**load_seed("customers_seed.json", "customers")[12], "consent": {"scope": []}}
+    trigger = load_seed("triggers_seed.json", "triggers")[18]
+    category = load_category(merchant["category_slug"])
+    car = build_merchant_car(category, merchant, trigger, customer)
+    evidence = extract_evidence(category, merchant, trigger, customer, car)
+    candidates = build_candidates(category, merchant, trigger, customer, evidence, car)
+    best = max(candidates, key=lambda c: c.total_score)
+    assert best.send_as == "vera"
+    assert "consent-safe" in best.body
+    assert "dispatch" not in best.body.lower()
+    assert "pharmacy_consent_or_medical_advice_risk" not in best.constitutional_violations
+
+
+def test_teardown_clears_state():
+    reset_state()
+    client = TestClient(app)
+    push(client, "category", "dentists", load_category("dentists"))
+    assert contexts
+    resp = client.post("/v1/teardown")
+    assert resp.json()["cleared"] is True
+    assert not contexts