Spaces:
Running
Running
File size: 27,051 Bytes
fdeeb34 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 | # 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.
|