Retail Rewards Dataset Guide

The retail rewards dataset is the flagship dataset pack for KaireonAI. It creates a complete decisioning environment modeled after a retail loyalty rewards program with 10 promotional offers across 6 channels, decisioning gates, contact policies, adaptive models, experiments, and a customer segment. This guide walks you through loading the dataset, exploring what gets created, running recommendations, recording outcomes, and using adaptive models.

What Gets Created

Entity	Count	Details
Data Schemas + DDL Tables	3	`retail_customers` (100 rows), `retail_offers` (10 rows), `retail_events` (500 rows)
Categories	3	Acquisition (BOGO), Retention (Discount), Engagement (Informational)
Channels	6	Web (banner), Email, Mobile (push), Social, Batch Email (file), Manual Outreach
Offers	10	4 BOGO, 4 Discount, 2 Informational — priorities 55-85
Creatives	60	10 offers x 6 channels — each with channel-specific content
Decisioning Gates	5	Min Age 18, Min Income $30k, Loyalty Members Only, Premium BOGO — High Spend, Senior Discount Gate
Contact Policies	5	Max 3/day, 24hr same-offer cooldown, 48hr post-conversion cooldown, max 10/week, BOGO vs Discount exclusion
Outcome Types	5	impression, click, accept, convert, dismiss
Algorithm Models	3	Scorecard, Bayesian (Naive Bayes), Thompson Bandit
Experiment	1	Scorecard vs Bayesian (80/20 split)
Decision Flow	1	Full pipeline with 7 stages
Segment	1	High-Income Members (income > $70k, tenure > 365 days)
Interaction History	500	90-day window of synthetic interactions
Interaction Summaries	500	Materialized aggregates for contact policy enforcement

Step-by-Step Walkthrough

Key Features Demonstrated

Decisioning Gates

The dataset ships 5 decisioning gates. The two global hard gates apply to every offer:

Rule	Type	Condition	Priority
Min Age 18	attribute_condition	`retail_customers.age >= 18`	100 (Critical)
Min Income $30k	attribute_condition	`retail_customers.income >= 30000`	90 (Critical)

Three more are offer-scoped: Loyalty Members Only (membership_days >= 30), Premium BOGO — High Spend (income >= 70000, on BOGO Hard only), and Senior Discount Gate (age >= 35, on Discount High only). Missing attributes cause the rule to fail closed — the customer is ineligible.

Contact Policies

The dataset ships 5 contact policies:

Policy	Type	Config
Max 3 per Day	frequency_cap	`maxPerDay: 3`
24hr Same-Offer Cooldown	cooldown	`cooldownHours: 24`
48hr Post-Conversion Cooldown	cooldown	pauses all offers for 48h after a conversion
Max 10 per Week Global	frequency_cap	`maxFrequency: 10`, `periodDays: 7` (across all channels)
BOGO vs Discount Exclusion	mutual_exclusion	don’t show both offer types in the same session

Three Model Types

Model	Type	How It Learns	Best For
Scorecard	`scorecard`	Rule-based (manual)	Transparent, explainable scoring
Bayesian	`bayesian`	Auto-incremental, updates every 100 outcomes	Adapts to changing preferences
Thompson Bandit	`thompson_bandit`	Updates Beta(alpha, beta) per arm on each outcome	Exploration/exploitation for new offers

Decision Pipeline

The pipeline processes candidates through 7 stages:

Inventory — Filters by schedule, flattens offers x creatives into candidates
Qualification — Hard-gate rules (age, income, segment). Fail = removed
Contact Policy — Frequency cap, cooldown, mutual exclusion
Consent — Channel-level consent check
Guardrails — Business constraint rules
Scoring — Model-based or priority-weighted
Ranking — Sort by score, apply limit, diversity constraints

Batch Email via Segments

Use the pre-loaded High-Income Members segment for batch email campaigns:

curl -X POST "http://localhost:3000/api/v1/simulate" \
  -H "Content-Type: application/json" \
  -H "X-Requested-With: XMLHttpRequest" \
  -d '{
  "segmentId": "<segment-uuid>",
  "sampleSize": 100,
  "channelFilter": "email"
}'

This runs the decision pipeline for the matching segment members (the High-Income Members segment is a subset of the 100 seeded customers) and returns per-customer decisions with email content (subject, body, CTA) ready for your ESP.

What to Look For

Qualification blocking: Request without attributes returns 0 decisions. The debugTrace shows which rules blocked each offer.
Contact policy enforcement: After 3 recommendations in a day, the frequency cap blocks further contact. The 24hr cooldown prevents re-contact too soon.
Experiment routing: The same customer always lands in the same experiment arm (deterministic hashing). 80% of customers get Scorecard scoring, 20% get Bayesian.
Adaptive learning: After recording outcomes via /respond, Bayesian models auto-update every 100 outcomes. Thompson Bandit updates alpha/beta per outcome immediately.
Multi-channel creatives: Each of the 10 offers has 6 creatives (web, email, mobile push, social, batch email, manual outreach) with channel-appropriate content.

API Quick Reference

Action	Method	Endpoint
Load sample data	POST	`/api/v1/seed-dataset/retail-rewards`
List offers	GET	`/api/v1/offers`
List channels	GET	`/api/v1/channels`
List creatives	GET	`/api/v1/creatives`
Get recommendations	POST	`/api/v1/recommend`
Record outcome	POST	`/api/v1/respond`
Query interaction history	GET	`/api/v1/interaction-history`
Run batch simulation	POST	`/api/v1/simulate`
Train model	POST	`/api/v1/algorithm-models/{id}/train`
Score customer	POST	`/api/v1/algorithm-models/{id}/score`
Create experiment	POST	`/api/v1/experiments`

Get Started

Tutorials

Use Cases

Decisioning

Studio

Data Pipelines

AI & ML

Operations & Reporting

Governance & Security

Integrations

Reference

Retail Rewards Dataset Guide

What Gets Created

Step-by-Step Walkthrough

Key Features Demonstrated

Decisioning Gates

Contact Policies

Three Model Types

Decision Pipeline

Batch Email via Segments

What to Look For

API Quick Reference

​What Gets Created

​Step-by-Step Walkthrough

​Key Features Demonstrated

​Decisioning Gates

​Contact Policies

​Three Model Types

​Decision Pipeline

​Batch Email via Segments

​What to Look For

​API Quick Reference

What Gets Created

Step-by-Step Walkthrough

Key Features Demonstrated

Decisioning Gates

Contact Policies

Three Model Types

Decision Pipeline

Batch Email via Segments

What to Look For

API Quick Reference