Initial commit made full working prodduct for the challeneg but forgot to maintain a repo so committed after everything's done

.env.sample

@@ -0,0 +1,12 @@
+# ── Vera Message Engine Environment ──
+# Copy this file to .env and fill in your keys.
+
+# Cerebras API (Diagnostician — llama3.1-8b)
+CEREBRAS_API_KEY=your_cerebras_api_key_here
+
+# Groq API (Copywriter — llama-3.3-70b-versatile + Prompt Guard)
+GROQ_API_KEY=your_groq_api_key_here
+
+# Server
+HOST=0.0.0.0
+PORT=8000

.gitignore

@@ -0,0 +1,44 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+dist/
+build/
+*.egg
+.eggs/
+
+# Virtual environments
+venv/
+.venv/
+env/
+ENV/
+
+# Environment variables
+.env
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Database
+*.db
+*.sqlite3
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+
+# Docker
+.dockerignore
+
+
+# Personal files
+Context/

Dockerfile

@@ -0,0 +1,20 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+RUN apt-get update && apt-get install -y --no-install-recommends curl && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY database.py security.py llm_pipeline.py main.py ./
+
+RUN mkdir -p /app/data
+ENV VERA_DB_PATH=/app/data/vera_state.db
+
+EXPOSE 8000
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+    CMD curl -f http://localhost:8000/v1/healthz || exit 1
+
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000", "--log-level", "info", "--workers", "1"]

README.md

@@ -0,0 +1,73 @@
+# Vera Message Engine
+
+**Stateful, deterministic message engine for merchant engagement — magicpin AI Challenge 2026**
+
+## Architecture
+
+```
+Request → Payload Limiter → Security Shield (Prompt Guard) → State Manager (SQLite) → Tri-Model Pipeline → Response
+```
+
+### Tri-Model Pipeline
+
+| Step | Provider | Model | Role |
+|------|----------|-------|------|
+| 1. Diagnostician | Cerebras | llama3.1-8b | Extracts the ONE critical signal from merchant state |
+| 2. Copywriter | Groq | llama-3.3-70b-versatile | Crafts high-compulsion message with specific CTA |
+| Shield | Groq | llama-prompt-guard-2-86m | Blocks prompt injections before DB/LLM access |
+
+### Category Routing (Pillar 5)
+
+Dynamic system prompts tuned to merchant vertical:
+- **Dentists/Pharmacies**: Clinical, utility-first, compliance-aware
+- **Salons**: Visual, timely, aesthetic-focused
+- **Restaurants**: Urgent, occasion-driven, locally grounded
+- **Gyms**: Motivational, seasonal-dip reframing
+
+## Setup
+
+```bash
+# 1. Clone and enter the project
+cd VeraAgent
+
+# 2. Copy and fill environment variables
+cp .env.sample .env
+# Edit .env with your Cerebras and Groq API keys
+
+# 3. Install dependencies
+pip install -r requirements.txt
+
+# 4. Run the server
+python main.py
+```
+
+## Docker
+
+```bash
+docker build -t vera-engine .
+docker run -p 8000:8000 --env-file .env vera-engine
+```
+
+## Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/v1/healthz` | Health check (200 OK) |
+| GET | `/v1/metadata` | Bot identity and capabilities |
+| POST | `/v1/context` | Idempotent merchant context ingestion |
+| POST | `/v1/tick` | Time simulation + proactive message generation |
+| POST | `/v1/reply` | Reply handling + contextual response generation |
+
+## Design Decisions
+
+- **SQLite with WAL mode**: Zero-latency embedded state that survives container restarts
+- **Temperature = 0.0**: All LLM calls are fully deterministic
+- **Fail-open security**: If Prompt Guard is unreachable, requests are allowed through (logged)
+- **Version-gated upserts**: Context updates are idempotent — same or lower version is a no-op
+- **Fallback pipeline**: If any LLM is unavailable, the system uses heuristic signal extraction and template-based messages grounded in real merchant data
+
+## Tradeoffs
+
+1. **Single worker**: SQLite requires single-writer access. Traded concurrency for data integrity.
+2. **Synchronous LLM calls in executor**: Cerebras/Groq SDKs are synchronous; wrapped in `run_in_executor` to avoid blocking the event loop.
+3. **Prompt Guard fail-open**: Chose availability over strict security — a blocked legitimate request costs more than a logged suspicious one.

database.py

@@ -0,0 +1,238 @@
+"""
+database.py — Vera Message Engine
+Embedded SQLite state management matching the exact judge harness contract.
+
+Schema:
+  contexts  — (scope, context_id) composite PK, version-gated upserts
+  conversations — append-only turn log keyed by conversation_id
+"""
+
+import sqlite3
+import json
+import os
+import logging
+from datetime import datetime, timezone
+from typing import Optional, Dict, Any, List, Tuple
+
+logger = logging.getLogger("vera.database")
+
+DB_PATH = os.getenv("VERA_DB_PATH", "vera_state.db")
+
+_conn: Optional[sqlite3.Connection] = None
+
+
+def get_db() -> sqlite3.Connection:
+    """Return the singleton database connection, initializing if needed."""
+    global _conn
+    if _conn is None:
+        _conn = sqlite3.connect(DB_PATH, check_same_thread=False)
+        _conn.row_factory = sqlite3.Row
+        _conn.execute("PRAGMA journal_mode=WAL")
+        _conn.execute("PRAGMA synchronous=NORMAL")
+        _conn.execute("PRAGMA busy_timeout=5000")
+        _init_schema(_conn)
+        logger.info("Database initialized at %s", DB_PATH)
+    return _conn
+
+
+def close_db():
+    """Gracefully close the database connection."""
+    global _conn
+    if _conn is not None:
+        _conn.close()
+        _conn = None
+        logger.info("Database connection closed")
+
+
+def _init_schema(conn: sqlite3.Connection):
+    conn.executescript("""
+        CREATE TABLE IF NOT EXISTS contexts (
+            scope       TEXT NOT NULL,
+            context_id  TEXT NOT NULL,
+            version     INTEGER NOT NULL DEFAULT 0,
+            payload     TEXT NOT NULL DEFAULT '{}',
+            delivered_at TEXT,
+            stored_at   TEXT NOT NULL,
+            PRIMARY KEY (scope, context_id)
+        );
+
+        CREATE TABLE IF NOT EXISTS conversations (
+            id              INTEGER PRIMARY KEY AUTOINCREMENT,
+            conversation_id TEXT NOT NULL,
+            turn_number     INTEGER NOT NULL DEFAULT 0,
+            role            TEXT NOT NULL,
+            message         TEXT NOT NULL DEFAULT '',
+            timestamp       TEXT NOT NULL
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_conv_id ON conversations(conversation_id);
+    """)
+    conn.commit()
+
+
+# ─── Context CRUD ─────────────────────────────────────────────────────────────
+
+def upsert_context(
+    scope: str,
+    context_id: str,
+    version: int,
+    payload: Dict[str, Any],
+    delivered_at: Optional[str] = None,
+) -> Dict[str, Any]:
+    """
+    Idempotent context upsert matching judge contract:
+    - If incoming version > stored version → replace atomically, return accepted=True
+    - If incoming version <= stored version → return accepted=False + 409 (stale)
+    - If context_id is new → insert, return accepted=True
+    """
+    db = get_db()
+    now = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z"
+
+    row = db.execute(
+        "SELECT version FROM contexts WHERE scope = ? AND context_id = ?",
+        (scope, context_id),
+    ).fetchone()
+
+    if row is not None:
+        current_version = row["version"]
+        if version <= current_version:
+            # Stale or duplicate — return 409 per judge contract
+            return {
+                "accepted": False,
+                "reason": "stale_version",
+                "current_version": current_version,
+                "status_code": 409,
+            }
+
+    payload_json = json.dumps(payload, ensure_ascii=False)
+
+    db.execute(
+        """
+        INSERT INTO contexts (scope, context_id, version, payload, delivered_at, stored_at)
+        VALUES (?, ?, ?, ?, ?, ?)
+        ON CONFLICT(scope, context_id) DO UPDATE SET
+            version = excluded.version,
+            payload = excluded.payload,
+            delivered_at = excluded.delivered_at,
+            stored_at = excluded.stored_at
+        """,
+        (scope, context_id, version, payload_json, delivered_at, now),
+    )
+    db.commit()
+
+    ack_id = f"ack_{context_id}_v{version}"
+    return {
+        "accepted": True,
+        "ack_id": ack_id,
+        "stored_at": now,
+        "status_code": 200,
+    }
+
+
+def get_context(scope: str, context_id: str) -> Optional[Dict[str, Any]]:
+    """Retrieve a single context entry."""
+    db = get_db()
+    row = db.execute(
+        "SELECT * FROM contexts WHERE scope = ? AND context_id = ?",
+        (scope, context_id),
+    ).fetchone()
+    if row is None:
+        return None
+    return {
+        "scope": row["scope"],
+        "context_id": row["context_id"],
+        "version": row["version"],
+        "payload": json.loads(row["payload"]),
+    }
+
+
+def get_all_contexts_by_scope(scope: str) -> List[Dict[str, Any]]:
+    """Get all contexts for a given scope."""
+    db = get_db()
+    rows = db.execute(
+        "SELECT context_id, version, payload FROM contexts WHERE scope = ?",
+        (scope,),
+    ).fetchall()
+    return [
+        {
+            "context_id": r["context_id"],
+            "version": r["version"],
+            "payload": json.loads(r["payload"]),
+        }
+        for r in rows
+    ]
+
+
+def count_contexts() -> Dict[str, int]:
+    """Count contexts per scope — used by /v1/healthz."""
+    db = get_db()
+    rows = db.execute(
+        "SELECT scope, COUNT(*) as cnt FROM contexts GROUP BY scope"
+    ).fetchall()
+    counts = {"category": 0, "merchant": 0, "customer": 0, "trigger": 0}
+    for r in rows:
+        counts[r["scope"]] = r["cnt"]
+    return counts
+
+
+def wipe_all():
+    """Teardown — wipe all state."""
+    db = get_db()
+    db.execute("DELETE FROM contexts")
+    db.execute("DELETE FROM conversations")
+    db.commit()
+    logger.info("All state wiped (teardown)")
+
+
+# ─── Conversation CRUD ────────────────────────────────────────────────────────
+
+def append_turn(
+    conversation_id: str,
+    turn_number: int,
+    role: str,
+    message: str,
+):
+    """Append a turn to a conversation."""
+    db = get_db()
+    now = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z"
+    db.execute(
+        """
+        INSERT INTO conversations (conversation_id, turn_number, role, message, timestamp)
+        VALUES (?, ?, ?, ?, ?)
+        """,
+        (conversation_id, turn_number, role, message, now),
+    )
+    db.commit()
+
+
+def get_conversation(conversation_id: str) -> List[Dict[str, Any]]:
+    """Retrieve all turns for a conversation in chronological order."""
+    db = get_db()
+    rows = db.execute(
+        """
+        SELECT turn_number, role, message, timestamp
+        FROM conversations
+        WHERE conversation_id = ?
+        ORDER BY turn_number ASC, id ASC
+        """,
+        (conversation_id,),
+    ).fetchall()
+    return [
+        {
+            "turn_number": r["turn_number"],
+            "role": r["role"],
+            "message": r["message"],
+            "timestamp": r["timestamp"],
+        }
+        for r in rows
+    ]
+
+
+def conversation_exists(conversation_id: str) -> bool:
+    """Check if a conversation already has turns logged."""
+    db = get_db()
+    row = db.execute(
+        "SELECT 1 FROM conversations WHERE conversation_id = ? LIMIT 1",
+        (conversation_id,),
+    ).fetchone()
+    return row is not None

llm_pipeline.py

@@ -0,0 +1,493 @@
+"""
+llm_pipeline.py — Vera Message Engine
+Tri-Model Pipeline: Diagnostician (Cerebras) → Copywriter (Groq)
++ Category Voice Routing (Pillar 5)
+"""
+
+import os, json, logging, re, hashlib, uuid
+import requests
+from typing import Dict, Any, Optional, List
+
+logger = logging.getLogger("vera.llm_pipeline")
+
+CEREBRAS_API_KEY = os.getenv("CEREBRAS_API_KEY", "")
+GROQ_API_KEY = os.getenv("GROQ_API_KEY", "")
+CEREBRAS_URL = "https://api.cerebras.ai/v1/chat/completions"
+GROQ_URL = "https://api.groq.com/openai/v1/chat/completions"
+DIAG_MODEL = "llama3.1-8b"
+COPY_MODEL = "llama-3.3-70b-versatile"
+
+# ─── Category Voice Templates (Pillar 5) ─────────────────────────────────────
+
+CATEGORY_VOICES = {
+    "dentists": "You are Vera, a clinical growth assistant. Tone: peer-clinical, collegial. Use 'Dr. {name}'. Reference JIDA/DCI sources. Avoid: 'guaranteed','100% safe','cure'. Focus on clinical credibility, patient recall, treatment conversion.",
+    "salons": "You are Vera, a beauty growth assistant. Tone: warm, visual, timely. Use first names. Reference style trends, bridal seasons. Focus on bookings, aesthetic results, stylist expertise.",
+    "restaurants": "You are Vera, a restaurant growth assistant. Tone: operator-to-operator, urgent. Reference footfall, match days, thali combos. Focus on event tie-ins, order volume, capacity.",
+    "gyms": "You are Vera, a fitness growth assistant. Tone: coaching, motivational. Address seasonal dips directly. Reference member counts, churn, trial conversion. Focus on retention and reactivation.",
+    "pharmacies": "You are Vera, a pharmacy growth assistant. Tone: clinical, trustworthy, precise. Never make medical claims. Reference stock alerts, refill cycles, compliance. Focus on patient care continuity.",
+}
+DEFAULT_VOICE = "You are Vera, magicpin's merchant growth assistant. Be specific, data-driven, action-oriented. Use real numbers from context. One clear CTA."
+
+
+def _get_voice(category_slug: str, category_payload: Optional[Dict] = None) -> str:
+    """Get category voice, enriching with actual voice data from context if available."""
+    base = CATEGORY_VOICES.get(category_slug, DEFAULT_VOICE)
+    if category_payload and "voice" in category_payload:
+        v = category_payload["voice"]
+        tone = v.get("tone", "")
+        taboos = v.get("vocab_taboo", v.get("taboos", []))
+        if tone:
+            base += f" Tone style: {tone}."
+        if taboos:
+            base += f" NEVER use these words/phrases: {', '.join(taboos[:8])}."
+    return base
+
+
+# ─── Step 1: Diagnostician (Cerebras llama3.1-8b) ────────────────────────────
+
+DIAG_SYSTEM = """You are an expert business signal analyst. Given merchant context (category, merchant, trigger, customer), identify the SINGLE most critical signal for the next message.
+
+Output ONLY this JSON — no markdown, no explanation:
+{"signal": "<best_signal_type>", "signal_detail": "<why this signal matters now>", "best_offer": "<offer_id or title to pair, or null>", "key_fact": "<the ONE specific number/fact to anchor the message>", "merchant_name": "<name>", "owner_name": "<owner first name>"}"""
+
+
+def _run_diagnostician(context_bundle: str) -> Dict[str, Any]:
+    """Call Cerebras llama3.1-8b to extract the critical signal."""
+    if not CEREBRAS_API_KEY:
+        logger.warning("CEREBRAS_API_KEY not set — using heuristic signal extraction")
+        return {}
+
+    try:
+        resp = requests.post(CEREBRAS_URL, headers={
+            "Authorization": f"Bearer {CEREBRAS_API_KEY}",
+            "Content-Type": "application/json",
+        }, json={
+            "model": DIAG_MODEL,
+            "messages": [
+                {"role": "system", "content": DIAG_SYSTEM},
+                {"role": "user", "content": context_bundle},
+            ],
+            "temperature": 0.0, "max_tokens": 400, "top_p": 1.0,
+        }, timeout=15)
+
+        if resp.status_code != 200:
+            logger.error("Cerebras %d: %s", resp.status_code, resp.text[:300])
+            return {}
+
+        raw = resp.json()["choices"][0]["message"]["content"].strip()
+        return _parse_json(raw) or {}
+    except Exception as e:
+        logger.error("Diagnostician error: %s", e)
+        return {}
+
+
+# ─── Step 2: Copywriter (Groq llama-3.3-70b-versatile) ───────────────────────
+
+def _build_copy_prompt(signal: Dict, context_bundle: str, is_reply: bool = False, reply_msg: str = "", conv_history: str = "") -> str:
+    parts = []
+    if is_reply:
+        parts.append(f'The merchant/customer said: "{reply_msg}"')
+        if conv_history:
+            parts.append(f"Conversation so far:\n{conv_history}")
+        parts.append("Craft a contextual reply. Acknowledge their message. Stay grounded in the signal.")
+        parts.append("If they said 'not interested' or hostile → action should be 'end'.")
+        parts.append("If it's an auto-reply (canned 'thank you for contacting') → action should be 'wait' with wait_seconds.")
+        parts.append("If they committed ('ok let's do it') → switch to ACTION mode, not more questions.")
+        parts.append("If off-topic (GST, unrelated) → politely decline and redirect to your signal.")
+    else:
+        parts.append("Craft a proactive outreach message for this merchant.")
+        parts.append("High compulsion, specific benchmark from their data, real offer, ONE clear CTA.")
+    
+    parts.append(f"\nSignal: {json.dumps(signal)}")
+    parts.append(f"\nFull context:\n{context_bundle[:6000]}")
+
+    if is_reply:
+        parts.append("""
+Output ONLY this JSON:
+{"action": "send|wait|end", "body": "<message>", "cta": "<open_ended|binary_yes_no|multi_choice_slot|binary_confirm_cancel|none>", "rationale": "<why>", "wait_seconds": <int or null>}
+
+Rules:
+- "send": you have a message to send
+- "wait": back off (set wait_seconds)  
+- "end": close conversation gracefully
+- body: specific, grounded, no fabricated facts, no URLs
+- If action is "end" or "wait", body can be empty or a short closing line""")
+    else:
+        parts.append("""
+Output ONLY this JSON:
+{"body": "<message text>", "cta": "<open_ended|binary_yes_no|multi_choice_slot|binary_confirm_cancel>", "send_as": "<vera|merchant_on_behalf>", "rationale": "<1-2 sentences>", "template_name": "<short_template_id>", "template_params": ["<param1>", "<param2>"]}
+
+Rules:
+- body MUST reference specific numbers/offers/facts from the context
+- NEVER fabricate data not in the context
+- NO URLs in body
+- One clear CTA
+- send_as: use "merchant_on_behalf" for customer-scoped triggers, "vera" otherwise""")
+
+    return "\n".join(parts)
+
+
+def _run_copywriter(system_prompt: str, user_prompt: str) -> Dict[str, Any]:
+    """Call Groq llama-3.3-70b-versatile to draft the message."""
+    if not GROQ_API_KEY:
+        logger.warning("GROQ_API_KEY not set — using fallback message")
+        return {}
+
+    try:
+        resp = requests.post(GROQ_URL, headers={
+            "Authorization": f"Bearer {GROQ_API_KEY}",
+            "Content-Type": "application/json",
+        }, json={
+            "model": COPY_MODEL,
+            "messages": [
+                {"role": "system", "content": system_prompt},
+                {"role": "user", "content": user_prompt},
+            ],
+            "temperature": 0.0, "max_tokens": 1024, "top_p": 1.0,
+        }, timeout=20)
+
+        if resp.status_code != 200:
+            logger.error("Groq Copywriter %d: %s", resp.status_code, resp.text[:300])
+            return {}
+
+        raw = resp.json()["choices"][0]["message"]["content"].strip()
+        return _parse_json(raw) or {}
+    except Exception as e:
+        logger.error("Copywriter error: %s", e)
+        return {}
+
+
+# ─── Context Bundle Builder ──────────────────────────────────────────────────
+
+def build_context_bundle(category: Dict, merchant: Dict, trigger: Dict, customer: Optional[Dict] = None) -> str:
+    """Serialize the 4-context framework into a single text block for LLM input."""
+    parts = []
+    parts.append(f"=== CATEGORY ({category.get('slug','?')}) ===")
+    voice = category.get("voice", {})
+    parts.append(f"Tone: {voice.get('tone','?')}")
+    taboos = voice.get("vocab_taboo", voice.get("taboos", []))
+    if taboos:
+        parts.append(f"Taboos: {taboos}")
+    digest = category.get("digest", [])
+    if digest:
+        parts.append(f"Digest items: {json.dumps(digest[:3])}")
+    offers_cat = category.get("offer_catalog", [])
+    if offers_cat:
+        parts.append(f"Category offers: {json.dumps(offers_cat[:4])}")
+    peers = category.get("peer_stats", {})
+    if peers:
+        parts.append(f"Peer stats: {json.dumps(peers)}")
+    seasonal = category.get("seasonal_beats", [])
+    if seasonal:
+        parts.append(f"Seasonal: {json.dumps(seasonal[:3])}")
+    trends = category.get("trend_signals", [])
+    if trends:
+        parts.append(f"Trends: {json.dumps(trends[:3])}")
+
+    parts.append(f"\n=== MERCHANT ({merchant.get('merchant_id','?')}) ===")
+    ident = merchant.get("identity", {})
+    parts.append(f"Name: {ident.get('name','?')}, Owner: {ident.get('owner_first_name','?')}")
+    parts.append(f"City: {ident.get('city','?')}, Locality: {ident.get('locality','?')}")
+    parts.append(f"Languages: {ident.get('languages',[])}")
+    perf = merchant.get("performance", {})
+    if perf:
+        parts.append(f"Performance (30d): views={perf.get('views','?')}, calls={perf.get('calls','?')}, ctr={perf.get('ctr','?')}, directions={perf.get('directions','?')}")
+        delta = perf.get("delta_7d", {})
+        if delta:
+            parts.append(f"7d delta: {json.dumps(delta)}")
+    signals = merchant.get("signals", [])
+    if signals:
+        parts.append(f"Signals: {signals}")
+    m_offers = merchant.get("offers", [])
+    if m_offers:
+        active = [o for o in m_offers if o.get("status") == "active"]
+        parts.append(f"Active offers: {json.dumps(active)}")
+    conv_hist = merchant.get("conversation_history", [])
+    if conv_hist:
+        parts.append(f"Conversation history: {json.dumps(conv_hist[-3:])}")
+    cust_agg = merchant.get("customer_aggregate", {})
+    if cust_agg:
+        parts.append(f"Customer aggregate: {json.dumps(cust_agg)}")
+    reviews = merchant.get("review_themes", [])
+    if reviews:
+        parts.append(f"Review themes: {json.dumps(reviews)}")
+    sub = merchant.get("subscription", {})
+    if sub:
+        parts.append(f"Subscription: {json.dumps(sub)}")
+
+    parts.append(f"\n=== TRIGGER ({trigger.get('id','?')}) ===")
+    parts.append(f"Kind: {trigger.get('kind','?')}, Urgency: {trigger.get('urgency','?')}")
+    parts.append(f"Scope: {trigger.get('scope','?')}")
+    trig_payload = trigger.get("payload", {})
+    if trig_payload:
+        parts.append(f"Payload: {json.dumps(trig_payload)}")
+    parts.append(f"Suppression key: {trigger.get('suppression_key','')}")
+
+    if customer:
+        parts.append(f"\n=== CUSTOMER ({customer.get('customer_id','?')}) ===")
+        c_ident = customer.get("identity", {})
+        parts.append(f"Name: {c_ident.get('name','?')}, Lang: {c_ident.get('language_pref','?')}")
+        rel = customer.get("relationship", {})
+        if rel:
+            parts.append(f"Visits: {rel.get('visits_total','?')}, Last: {rel.get('last_visit','?')}, Services: {rel.get('services_received',[])[: 5]}")
+        parts.append(f"State: {customer.get('state','?')}")
+        prefs = customer.get("preferences", {})
+        if prefs:
+            parts.append(f"Preferences: {json.dumps(prefs)}")
+        consent = customer.get("consent", {})
+        if consent:
+            parts.append(f"Consent scope: {consent.get('scope',[])}")
+
+    return "\n".join(parts)
+
+
+# ─── Compose for /v1/tick ─────────────────────────────────────────────────────
+
+def compose_tick_action(
+    category: Dict, merchant: Dict, trigger: Dict, customer: Optional[Dict] = None
+) -> Dict[str, Any]:
+    """Full compose pipeline for a tick action. Returns the action dict."""
+    cat_slug = merchant.get("category_slug", category.get("slug", "general"))
+    bundle = build_context_bundle(category, merchant, trigger, customer)
+
+    # Step 1: Diagnostician
+    signal = _run_diagnostician(bundle)
+    if not signal:
+        signal = _heuristic_signal(merchant, trigger, customer)
+
+    # Step 2: Copywriter
+    voice = _get_voice(cat_slug, category)
+    user_prompt = _build_copy_prompt(signal, bundle, is_reply=False)
+    result = _run_copywriter(voice, user_prompt)
+
+    if not result or not result.get("body"):
+        result = _fallback_tick_message(signal, merchant, trigger, customer, category)
+
+    # Build the full action envelope
+    mid = merchant.get("merchant_id", "")
+    cid = customer.get("customer_id") if customer else trigger.get("customer_id")
+    tid = trigger.get("id", "")
+    conv_id = f"conv_{mid}_{tid}" if tid else f"conv_{mid}_{uuid.uuid4().hex[:8]}"
+
+    return {
+        "conversation_id": conv_id,
+        "merchant_id": mid,
+        "customer_id": cid,
+        "send_as": result.get("send_as", "merchant_on_behalf" if cid else "vera"),
+        "trigger_id": tid,
+        "template_name": result.get("template_name", f"vera_{trigger.get('kind','generic')}_v1"),
+        "template_params": result.get("template_params", []),
+        "body": result.get("body", ""),
+        "cta": result.get("cta", "open_ended"),
+        "suppression_key": trigger.get("suppression_key", f"auto:{mid}:{tid}"),
+        "rationale": result.get("rationale", "Composed from category+merchant+trigger context"),
+    }
+
+
+# ─── Compose for /v1/reply ───────────────────────────────────────────────────
+
+def compose_reply(
+    merchant: Dict, category: Dict, message: str,
+    conversation_history: List[Dict] = None,
+    trigger: Optional[Dict] = None, customer: Optional[Dict] = None,
+) -> Dict[str, Any]:
+    """Full compose pipeline for a reply. Returns {action, body, cta, rationale}."""
+    cat_slug = merchant.get("category_slug", category.get("slug", "general"))
+    
+    # Build conversation history string
+    conv_str = ""
+    if conversation_history:
+        conv_parts = []
+        for t in conversation_history[-6:]:
+            conv_parts.append(f"[{t['role']}]: {t['message']}")
+        conv_str = "\n".join(conv_parts)
+
+    # Use a minimal trigger if none provided
+    if not trigger:
+        trigger = {"id": "reply_context", "kind": "reply", "scope": "merchant",
+                   "payload": {}, "urgency": 2, "suppression_key": ""}
+
+    bundle = build_context_bundle(category, merchant, trigger, customer)
+
+    # Step 1: Diagnostician  
+    signal = _run_diagnostician(bundle)
+    if not signal:
+        signal = _heuristic_signal(merchant, trigger, customer)
+
+    # Step 2: Copywriter (reply mode)
+    voice = _get_voice(cat_slug, category)
+    user_prompt = _build_copy_prompt(signal, bundle, is_reply=True, reply_msg=message, conv_history=conv_str)
+    result = _run_copywriter(voice, user_prompt)
+
+    if not result:
+        result = _fallback_reply(message, merchant, signal)
+
+    # Ensure required fields
+    result.setdefault("action", "send")
+    result.setdefault("body", "")
+    result.setdefault("cta", "open_ended")
+    result.setdefault("rationale", "Reply composed from context")
+
+    # Clean up wait_seconds
+    if result["action"] == "wait" and not result.get("wait_seconds"):
+        result["wait_seconds"] = 3600
+
+    return result
+
+
+# ─── Heuristic Fallbacks ─────────────────────────────────────────────────────
+
+def _heuristic_signal(merchant: Dict, trigger: Dict, customer: Optional[Dict] = None) -> Dict:
+    """Deterministic signal extraction when Cerebras is unavailable."""
+    ident = merchant.get("identity", {})
+    perf = merchant.get("performance", {})
+    offers = merchant.get("offers", [])
+    active_offers = [o for o in offers if o.get("status") == "active"]
+    
+    return {
+        "signal": trigger.get("kind", "general_engagement"),
+        "signal_detail": json.dumps(trigger.get("payload", {}))[:200],
+        "best_offer": active_offers[0].get("title") if active_offers else None,
+        "key_fact": f"views={perf.get('views','?')}, calls={perf.get('calls','?')}" if perf else "",
+        "merchant_name": ident.get("name", ""),
+        "owner_name": ident.get("owner_first_name", ""),
+    }
+
+
+def _fallback_tick_message(signal: Dict, merchant: Dict, trigger: Dict, customer: Optional[Dict], category: Dict) -> Dict:
+    """Grounded fallback when Groq is unavailable."""
+    ident = merchant.get("identity", {})
+    name = ident.get("owner_first_name", ident.get("name", ""))
+    perf = merchant.get("performance", {})
+    offers = merchant.get("offers", [])
+    active = [o for o in offers if o.get("status") == "active"]
+    kind = trigger.get("kind", "update")
+    trig_payload = trigger.get("payload", {})
+    cat_slug = category.get("slug", "")
+
+    # Build a grounded message based on trigger kind
+    if customer:
+        c_name = customer.get("identity", {}).get("name", "Customer")
+        body = f"Hi {c_name}, {ident.get('name','')} here. "
+        if kind == "recall_due":
+            slots = trig_payload.get("available_slots", [])
+            slot_str = " or ".join([s.get("label","") for s in slots[:2]]) if slots else "this week"
+            body += f"Your {trig_payload.get('service_due','check-up')} is due. Available: {slot_str}."
+            if active:
+                body += f" {active[0]['title']} included."
+        elif kind == "chronic_refill_due":
+            mols = trig_payload.get("molecule_list", [])
+            body += f"Your refill for {', '.join(mols[:3])} is coming up. "
+            body += "Shall I arrange home delivery?"
+        else:
+            body += f"Following up on your recent visit. We have an update for you."
+        return {"body": body, "cta": "binary_yes_no", "send_as": "merchant_on_behalf",
+                "rationale": f"Customer-scoped {kind} trigger", "template_name": f"vera_{kind}_v1", "template_params": [c_name, name]}
+    
+    # Merchant-scoped
+    greeting = f"Dr. {name}" if cat_slug == "dentists" else name
+    body = f"{greeting}, "
+    
+    if kind == "research_digest":
+        digest = category.get("digest", [])
+        top_id = trig_payload.get("top_item_id", "")
+        item = next((d for d in digest if d.get("id") == top_id), None)
+        if item:
+            body += f"{item.get('source','New research')} — {item['title']}. {item.get('summary','')[:100]}"
+            body += f" Worth a look?"
+        else:
+            body += "New research relevant to your practice just landed. Want me to pull the details?"
+    elif kind == "perf_dip" or kind == "seasonal_perf_dip":
+        metric = trig_payload.get("metric", "views")
+        delta = trig_payload.get("delta_pct", 0)
+        body += f"Your {metric} dipped {abs(int(delta*100))}% this week. "
+        if active:
+            body += f"Your '{active[0]['title']}' offer could help recover. Want me to push it?"
+        else:
+            body += "Want me to draft an offer to bring traffic back?"
+    elif kind == "renewal_due":
+        days = trig_payload.get("days_remaining", "?")
+        body += f"Your Pro subscription expires in {days} days. "
+        body += f"Current performance: {perf.get('views','?')} views, {perf.get('calls','?')} calls this month. Renew to keep the momentum?"
+    elif kind == "ipl_match_today":
+        match = trig_payload.get("match", "tonight's match")
+        body += f"{match} is tonight! Your locality gets high footfall on match nights. "
+        if active:
+            body += f"Want me to push your '{active[0]['title']}' as a match-night special?"
+        else:
+            body += "Want to run a match-night special?"
+    else:
+        body += f"Quick update based on your latest data — {perf.get('views','?')} views this month"
+        if active:
+            body += f", and your '{active[0]['title']}' is live"
+        body += ". Want me to help optimize?"
+    
+    return {"body": body, "cta": "open_ended", "send_as": "vera",
+            "rationale": f"Signal: {kind}. Grounded in merchant perf + trigger payload.",
+            "template_name": f"vera_{kind}_v1", "template_params": [greeting]}
+
+
+def _fallback_reply(message: str, merchant: Dict, signal: Dict) -> Dict:
+    """Deterministic fallback for reply composition."""
+    msg_lower = message.lower().strip()
+    
+    # Auto-reply detection
+    auto_phrases = ["thank you for contacting", "our team will respond", "we will get back",
+                    "auto-reply", "out of office", "away message"]
+    if any(p in msg_lower for p in auto_phrases):
+        return {"action": "wait", "wait_seconds": 14400,
+                "body": "", "cta": "none",
+                "rationale": "Detected auto-reply. Backing off 4 hours."}
+    
+    # Hostile detection
+    hostile_phrases = ["stop messaging", "not interested", "useless", "spam", "stop sending",
+                       "don't message", "unsubscribe", "leave me alone"]
+    if any(p in msg_lower for p in hostile_phrases):
+        return {"action": "end", "body": "",
+                "rationale": "Merchant explicitly opted out. Closing conversation gracefully."}
+    
+    # Commitment detection → switch to action
+    commit_phrases = ["ok let's do it", "let's do it", "yes do it", "go ahead", "proceed",
+                      "sounds good let's", "ok go ahead", "yes please", "confirm", "let's go"]
+    if any(p in msg_lower for p in commit_phrases):
+        ident = merchant.get("identity", {})
+        name = ident.get("owner_first_name", ident.get("name", ""))
+        return {"action": "send",
+                "body": f"Great, {name}! Setting this up now. I'll have the draft ready in a moment. You'll be able to review before anything goes live.",
+                "cta": "binary_confirm_cancel",
+                "rationale": "Merchant committed — switching from qualifying to action mode."}
+    
+    # Off-topic detection
+    offtopic = ["gst", "tax", "invoice", "salary", "loan", "insurance"]
+    if any(w in msg_lower for w in offtopic):
+        return {"action": "send",
+                "body": "That's outside what I can help with directly — best to check with your CA on that. Coming back to your business growth — want me to continue with what we were working on?",
+                "cta": "open_ended",
+                "rationale": "Off-topic ask declined politely; redirecting to growth signal."}
+    
+    # Default engaged reply
+    return {"action": "send",
+            "body": "Got it — let me work on that. I'll have something ready for you shortly.",
+            "cta": "open_ended",
+            "rationale": "Acknowledged merchant reply; advancing conversation."}
+
+
+def _parse_json(text: str) -> Optional[Dict]:
+    """Robustly parse JSON from LLM output."""
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        pass
+    match = re.search(r'```(?:json)?\s*\n?(.*?)\n?```', text, re.DOTALL)
+    if match:
+        try:
+            return json.loads(match.group(1).strip())
+        except json.JSONDecodeError:
+            pass
+    s, e = text.find("{"), text.rfind("}")
+    if s != -1 and e > s:
+        try:
+            return json.loads(text[s:e+1])
+        except json.JSONDecodeError:
+            pass
+    return None

magicpin-ai-challenge/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.

magicpin-ai-challenge/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.

magicpin-ai-challenge/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"]
+}

magicpin-ai-challenge/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"]
+}

magicpin-ai-challenge/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"]
+}

magicpin-ai-challenge/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"]
+}

magicpin-ai-challenge/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"]
+}

magicpin-ai-challenge/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": [] }
+    }
+  ]
+}

magicpin-ai-challenge/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()

magicpin-ai-challenge/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": []
+    }
+  ]
+}

magicpin-ai-challenge/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"
+    }
+  ]
+}

magicpin-ai-challenge/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).

magicpin-ai-challenge/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`)

magicpin-ai-challenge/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.

magicpin-ai-challenge/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.

magicpin-ai-challenge/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()

main.py

@@ -0,0 +1,271 @@
+"""
+main.py — Vera Message Engine
+FastAPI server implementing the exact magicpin judge harness API contract.
+
+Endpoints (per challenge-testing-brief.md §2):
+  GET  /v1/healthz  — liveness + context counts
+  GET  /v1/metadata — bot identity
+  POST /v1/context  — idempotent context push (200 or 409)
+  POST /v1/tick     — proactive message generation
+  POST /v1/reply    — conversation reply handling
+"""
+
+import os, time, json, logging
+from datetime import datetime, timezone
+from typing import Optional, Any, Dict, List
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel, Field
+from dotenv import load_dotenv
+
+load_dotenv()
+
+import database
+from security import check_prompt_injection, injection_response
+from llm_pipeline import compose_tick_action, compose_reply
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s | %(name)-18s | %(levelname)-5s | %(message)s",
+    datefmt="%Y-%m-%d %H:%M:%S",
+)
+logger = logging.getLogger("vera.main")
+
+START_TIME = time.time()
+
+
+# ─── Lifespan ─────────────────────────────────────────────────────────────────
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    logger.info("Vera Message Engine starting...")
+    database.get_db()
+    logger.info("Database ready ✓")
+    yield
+    database.close_db()
+    logger.info("Shutdown complete ✓")
+
+
+app = FastAPI(title="Vera Message Engine", version="1.0.0", lifespan=lifespan)
+app.add_middleware(CORSMiddleware, allow_origins=["*"], allow_methods=["*"], allow_headers=["*"])
+
+
+# ─── Pydantic Models (exact judge contract) ──────────────────────────────────
+
+class ContextBody(BaseModel):
+    scope: str
+    context_id: str
+    version: int
+    payload: Dict[str, Any] = {}
+    delivered_at: Optional[str] = None
+
+class TickBody(BaseModel):
+    now: str
+    available_triggers: List[str] = []
+
+class ReplyBody(BaseModel):
+    conversation_id: str
+    merchant_id: Optional[str] = None
+    customer_id: Optional[str] = None
+    from_role: str
+    message: str
+    received_at: Optional[str] = None
+    turn_number: int
+
+
+# ─── GET /v1/healthz ──────────────────────────────────────────────────────────
+
+@app.get("/v1/healthz")
+async def healthz():
+    counts = database.count_contexts()
+    return {
+        "status": "ok",
+        "uptime_seconds": int(time.time() - START_TIME),
+        "contexts_loaded": counts,
+    }
+
+
+# ─── GET /v1/metadata ────────────────────────────────────────────────────────
+
+@app.get("/v1/metadata")
+async def metadata():
+    return {
+        "team_name": "Vera Engine",
+        "team_members": ["Madhav Kapila"],
+        "model": "cerebras/llama3.1-8b + groq/llama-3.3-70b-versatile",
+        "approach": "Tri-Model Pipeline: Cerebras diagnostician extracts signal, Groq copywriter composes. Category voice routing. Prompt Guard security shield.",
+        "contact_email": "madhav@example.com",
+        "version": "1.0.0",
+        "submitted_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+    }
+
+
+# ─── POST /v1/context ────────────────────────────────────────────────────────
+
+@app.post("/v1/context")
+async def push_context(body: ContextBody):
+    scope = body.scope.lower().strip()
+    valid_scopes = {"category", "merchant", "customer", "trigger"}
+    if scope not in valid_scopes:
+        return JSONResponse(status_code=400, content={
+            "accepted": False, "reason": "invalid_scope",
+            "details": f"scope must be one of {valid_scopes}"
+        })
+
+    result = database.upsert_context(
+        scope=scope, context_id=body.context_id,
+        version=body.version, payload=body.payload,
+        delivered_at=body.delivered_at,
+    )
+
+    status_code = result.pop("status_code", 200)
+    if status_code == 409:
+        return JSONResponse(status_code=409, content=result)
+    return result
+
+
+# ─── POST /v1/tick ────────────────────────────────────────────────────────────
+
+@app.post("/v1/tick")
+async def tick(body: TickBody):
+    actions = []
+
+    for trig_id in body.available_triggers:
+        try:
+            # Fetch trigger context
+            trig_ctx = database.get_context("trigger", trig_id)
+            if not trig_ctx:
+                logger.warning("Trigger %s not found in DB, skipping", trig_id)
+                continue
+            trigger = trig_ctx["payload"]
+
+            # Fetch merchant context
+            merchant_id = trigger.get("merchant_id")
+            if not merchant_id:
+                continue
+            merch_ctx = database.get_context("merchant", merchant_id)
+            if not merch_ctx:
+                logger.warning("Merchant %s not found for trigger %s", merchant_id, trig_id)
+                continue
+            merchant = merch_ctx["payload"]
+
+            # Fetch category context
+            cat_slug = merchant.get("category_slug", "")
+            cat_ctx = database.get_context("category", cat_slug)
+            category = cat_ctx["payload"] if cat_ctx else {"slug": cat_slug}
+
+            # Fetch customer context if customer-scoped
+            customer = None
+            customer_id = trigger.get("customer_id")
+            if customer_id:
+                cust_ctx = database.get_context("customer", customer_id)
+                if cust_ctx:
+                    customer = cust_ctx["payload"]
+
+            # Run the compose pipeline
+            action = compose_tick_action(category, merchant, trigger, customer)
+
+            if action and action.get("body"):
+                actions.append(action)
+                # Log the bot's outbound message
+                database.append_turn(
+                    action["conversation_id"], 1, "vera", action["body"]
+                )
+
+        except Exception as e:
+            logger.error("Error processing trigger %s: %s", trig_id, e, exc_info=True)
+            continue
+
+    return {"actions": actions}
+
+
+# ─── POST /v1/reply ──────────────────────────────────────────────────────────
+
+@app.post("/v1/reply")
+async def reply(body: ReplyBody):
+    # Security Shield: check for prompt injection FIRST
+    is_safe = check_prompt_injection(body.message)
+    if not is_safe:
+        logger.warning("Injection blocked: conv=%s", body.conversation_id)
+        database.append_turn(body.conversation_id, body.turn_number, body.from_role, "[BLOCKED]")
+        return injection_response()
+
+    # Log the inbound message
+    database.append_turn(
+        body.conversation_id, body.turn_number, body.from_role, body.message
+    )
+
+    # Fetch merchant context
+    merchant = {}
+    category = {}
+    if body.merchant_id:
+        merch_ctx = database.get_context("merchant", body.merchant_id)
+        if merch_ctx:
+            merchant = merch_ctx["payload"]
+            cat_slug = merchant.get("category_slug", "")
+            cat_ctx = database.get_context("category", cat_slug)
+            category = cat_ctx["payload"] if cat_ctx else {"slug": cat_slug}
+
+    # Fetch conversation history
+    conv_history = database.get_conversation(body.conversation_id)
+
+    # Fetch customer context if provided
+    customer = None
+    if body.customer_id:
+        cust_ctx = database.get_context("customer", body.customer_id)
+        if cust_ctx:
+            customer = cust_ctx["payload"]
+
+    # Run compose pipeline in reply mode
+    try:
+        result = compose_reply(
+            merchant=merchant, category=category, message=body.message,
+            conversation_history=conv_history, customer=customer,
+        )
+    except Exception as e:
+        logger.error("Reply compose error: %s", e, exc_info=True)
+        result = {"action": "send", "body": "Got it — let me look into that for you.",
+                  "cta": "open_ended", "rationale": "Fallback due to processing error"}
+
+    # Log bot's response
+    if result.get("body"):
+        database.append_turn(
+            body.conversation_id, body.turn_number + 1, "vera", result["body"]
+        )
+
+    return result
+
+
+# ─── POST /v1/teardown (optional per spec §11) ──────────────────────────────
+
+@app.post("/v1/teardown")
+async def teardown():
+    database.wipe_all()
+    return {"status": "wiped"}
+
+
+# ─── Payload Size Guard ─────────────────────────────────────────────────────
+
+@app.middleware("http")
+async def payload_guard(request: Request, call_next):
+    cl = request.headers.get("content-length")
+    if cl and int(cl) > 512_000:
+        return JSONResponse(status_code=413, content={"error": "Payload too large"})
+    return await call_next(request)
+
+
+# ─── Global Error Handler ───────────────────────────────────────────────────
+
+@app.exception_handler(Exception)
+async def catch_all(request: Request, exc: Exception):
+    logger.error("Unhandled: %s", exc, exc_info=True)
+    return JSONResponse(status_code=500, content={"error": str(exc)})
+
+
+if __name__ == "__main__":
+    import uvicorn
+    port = int(os.getenv("PORT", "8000"))
+    uvicorn.run("main:app", host="0.0.0.0", port=port, log_level="info", workers=1)

requirements.txt

@@ -0,0 +1,5 @@
+fastapi
+uvicorn[standard]
+pydantic
+python-dotenv
+requests

security.py

@@ -0,0 +1,93 @@
+"""
+security.py — Vera Message Engine
+Prompt Guard middleware using Groq's meta-llama/llama-prompt-guard-2-86m.
+
+Pillar 4: Security Shield
+- Every inbound /v1/reply message passes through Prompt Guard BEFORE
+  touching the DB or invoking any main LLM.
+- On injection detection → return {"action": "end", "rationale": "Security violation detected."}
+- Fail-open on API errors (logged) to avoid blocking legitimate requests.
+"""
+
+import os
+import json
+import logging
+import requests
+from typing import Dict, Any
+
+logger = logging.getLogger("vera.security")
+
+GROQ_API_KEY = os.getenv("GROQ_API_KEY", "")
+GROQ_CHAT_URL = "https://api.groq.com/openai/v1/chat/completions"
+GUARD_MODEL = "meta-llama/llama-prompt-guard-2-86m"
+
+
+def check_prompt_injection(text: str) -> bool:
+    """
+    Run inbound text through Groq Prompt Guard.
+    Returns True if the text is SAFE, False if injection detected.
+    """
+    if not text or not text.strip():
+        return True  # Empty is safe
+
+    if not GROQ_API_KEY:
+        logger.warning("GROQ_API_KEY not set — prompt guard DISABLED (fail-open)")
+        return True
+
+    try:
+        resp = requests.post(
+            GROQ_CHAT_URL,
+            headers={
+                "Authorization": f"Bearer {GROQ_API_KEY}",
+                "Content-Type": "application/json",
+            },
+            json={
+                "model": GUARD_MODEL,
+                "messages": [{"role": "user", "content": text}],
+                "temperature": 0.0,
+                "max_tokens": 32,
+            },
+            timeout=8,
+        )
+
+        if resp.status_code != 200:
+            logger.error("Prompt Guard returned %d: %s", resp.status_code, resp.text[:300])
+            return True  # Fail open
+
+        data = resp.json()
+        guard_output = (
+            data.get("choices", [{}])[0]
+            .get("message", {})
+            .get("content", "")
+            .strip()
+            .lower()
+        )
+
+        # Check for injection indicators
+        injection_words = ["unsafe", "injection", "jailbreak", "malicious", "attack", "yes"]
+        safe_words = ["safe", "benign", "clean", "no injection", "legitimate", "no"]
+
+        for w in safe_words:
+            if w in guard_output:
+                return True
+        for w in injection_words:
+            if w in guard_output:
+                logger.warning("INJECTION DETECTED: %s → guard said: %s", text[:100], guard_output)
+                return False
+
+        return True  # Ambiguous → fail open
+
+    except requests.Timeout:
+        logger.warning("Prompt Guard timed out — fail-open")
+        return True
+    except Exception as e:
+        logger.error("Prompt Guard error: %s", str(e))
+        return True
+
+
+def injection_response() -> Dict[str, Any]:
+    """Return the security violation response per judge contract."""
+    return {
+        "action": "end",
+        "rationale": "Security violation detected.",
+    }