Simulation Engine & Offer Management System

Sat, 27 Dec 2025 00:00:00 +0530

Overview

Implemented a complete simulation engine for testing offer management workflows with persona-based shopping agents. The system enables accelerated time simulation (1 real hour = 1 week simulated time) to model long-term offer lifecycle effects.

High-Level Architecture Overview (LangGraph + LangSmith)

┌─────────────────────────────────────────────────────────────────┐
│ SimulationOrchestrator (New) │
│ Coordinates time advancement + runs LangGraph agents │
└──────────────────────────┬──────────────────────────────────────┘
 │
 ┌───────────────┼───────────────┐
 │ │ │
 ▼ ▼ ▼
┌──────────────────┐ ┌────────────────────────────────────────┐
│ OfferScheduler │ │ LangGraph StateGraph (per agent) │
│ (Existing) │ │ │
│ │ │ [decide_shop] ──▶ [browse_products] │
│ - Time advance │ │ │ │ │
│ - Cycle mgmt │ │ (skip) [add_to_cart] │
│ - Offer refresh │ │ │ │ │
└──────────────────┘ │ │ [view_coupons] │
 │ │ │ │
 │ │ [decide_checkout] │
 │ │ / \ │
 │ │ [complete] [abandon] │
 │ ▼ \ / │
 │ [END] ◀─────────────── │
 └────────────────────────────────────────┘
 │
 ▼
 ┌───────────────────────────┐
 │ LangSmith Tracing │
 │ (Automatic per node) │
 └───────────────────────────┘
 │
 ▼
┌─────────────────────────────────────────────────────────────────┐
│ PostgreSQL Database │
│ agents | users | shopping_sessions | shopping_session_events │
│ user_coupons | offer_cycles | simulation_state │
└─────────────────────────────────────────────────────────────────┘

Simulation Layer-Specific Architecture Overview

Layer 1: Application & API

FastAPI Application (app/main.py)

 ┌──────────────────┐ ┌──────────────────────────────────┐
 │ Auth Verification │─────▶│ SIMULATION MODE BYPASS │
 │ (Supabase JWT) │ │ Bearer dev:<agent_id> │
 └──────────────────┘ └──────────────────────────────────┘
 │ │
 ▼ ▼
 ┌──────────────────┐ ┌──────────────────────────────────┐
 │ Production Paths │ │ Simulation Paths │
 └──────────────────┘ └──────────────────────────────────┘
 │ │
 ▼ ▼
 ┌──────────────────┐ ┌──────────────────────────────────┐
 │ Routes: │ │ Offer Engine Routes │
 │ • cart │ │ • /cycles (GET/POST) │
 │ • orders │ │ • /cycles/{id} │
 │ • stores │ │ • /refresh/user/{user_id} │
 └──────────────────┘ │ • /time/advance │
 └──────────────────────────────────┘

Layer 2: Simulation Orchestrator

SimulationOrchestrator (app/simulation/orchestrator.py)

 ┌────────────────────────────────────────────────────────────────┐
 │ Rich Dashboard (Terminal UI) │
 │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
 │ │ Statistics │ │ Agent List │ │ Event Log │ │
 │ │ • Cycles │ │ • Status │ │ • Actions │ │
 │ │ • Checkouts │ │ • Store │ │ • Errors │ │
 │ │ • Offers │ │ • Cart │ │ │ │
 │ └─────────────┘ └─────────────┘ └─────────────┘ │
 └────────────────────────────────────────────────────────────────┘

 ┌────────────────────────────────────────────────────────────────┐
 │ Time Service │
 │ • Real Time ───────────────────┐ │
 │ • Simulated Time ────────▶ 1 hour = 168 hours (1 week) │
 │ • Coordinate Conversion │ │
 └────────────────────────────────┼───────────────────────────────┘
 │
 ┌────────────────────────────────▼────────────────────────────────┐
 │ Offer Engine Scheduler │
 │ ┌──────────────────┐ ┌──────────────────┐ ┌───────────────┐ │
 │ │ Cycle Manager │ │ Expiration │ │ Offer Assigner│ │
 │ │ • Create cycles │──▶│ Handler │──▶│ • Distribute │ │
 │ │ • Track windows │ │ • Mark expired │ │ to wallets │ │
 │ └──────────────────┘ └──────────────────┘ └───────────────┘ │
 └────────────────────────────────────────────────────────────────┘

Layer 3: Agent Simulation

Agent Pool (Multiple Persona-Based Agents)

 ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
 │ Agent 1 │ │ Agent 2 │ │ Agent 3 │ │ Agent N │
 │ (Excel │ │ (Excel │ │ (Excel │ │ (Excel │
 │ Persona)│ │ Persona)│ │ Persona)│ │ Persona)│
 └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘
 │ │ │ │
 ▼ ▼ ▼ ▼

 ┌────────────────────────────────────────────────────────────────┐
 │ Agent State (28 Persona Attributes) │
 │ • Demographics: age, income, location │
 │ • Shopping: frequency, basket_size, impulsivity │
 │ • Preferences: categories, brands, days_of_week │
 │ • Psychology: discount_sensitivity, price_consciousness │
 └────────────────────────────────────────────────────────────────┘
 │ │ │ │
 └─────────────┴─────────────┴─────────────┘
 │
 ▼

 ┌────────────────────────────────────────────────────────────────┐
 │ LangGraph Shopping Graph (Decision Workflow) │
 │ │
 │ ┌──────────┐ │
 │ │ Start │ │
 │ └────┬─────┘ │
 │ │ │
 │ ▼ │
 │ ┌─────────────┐ │
 │ │decide_shop │ │
 │ └─────┬───────┘ │
 │ Yes│ │No │
 │ ▼ ▼ │
 │ ┌────────────┐ ┌────┐ │
 │ │browse_ │ │END │ │
 │ │products │ └────┘ │
 │ └─────┬──────┘ │
 │ │ │
 │ ▼ │
 │ ┌───────────────┐ │
 │ │ add_to_cart │ │
 │ └───────┬───────┘ │
 │ │ │
 │ ▼ │
 │ ┌───────────────┐ │
 │ │ view_coupons │ │
 │ └───────┬───────┘ │
 │ │ │
 │ ▼ │
 │ ┌─────────────────┐ │
 │ │ decide_checkout│ │
 │ └────┬───────┬───┘ │
 │ │ │ │
 │ Yes │ │ No │
 │ ▼ ▼ │
 │ ┌────────────┐ ┌────┐ │
 │ │complete_ │ │END │ │
 │ │checkout │ └────┘ │
 │ └────────────┘ │
 │ │
 └────────────────────────────────────────────────────────────────┘
 │
 ▼

 ┌────────────────────────────────────────────────────────────────┐
 │ Shopping Actions (Database Operations) │
 │ • create_session() • browse_products() │
 │ • add_to_cart() • apply_coupon() │
 │ • view_coupon() • complete_checkout() │
 │ • abandon_session() • create_event() (ML training data) │
 └────────────────────────────────────────────────────────────────┘

Layer 4: Database Schema

NEW TABLES (Migration 007)

┌─────────────────────┐ ┌─────────────────────┐
│ offer_cycles │ │ user_offer_cycles │
├─────────────────────┤ ├─────────────────────┤
│ id │ │ user_id → users(id) │
│ cycle_number │ │ current_cycle_id │
│ started_at │ │ last_refresh_at │
│ ends_at │ │ next_refresh_at │
│ simulated_start_date│ │ is_simulation │
│ simulated_end_date │ └─────────────────────┘
│ is_simulation │
└─────────────────────┘

┌─────────────────────┐
│ simulation_state │
├─────────────────────┤
│ simulated_date │
│ real_start_time │
│ cycle_number │
└─────────────────────┘


MODIFIED TABLES

┌─────────────────────────────┐ ┌───────────────────────────────┐
│ user_coupons │ │ orders │
├─────────────────────────────┤ ├───────────────────────────────┤
│ + status (active/expired/) │ │ + is_simulated │
│ + offer_cycle_id │ │ + simulated_at │
│ + is_simulation │ │ │
└─────────────────────────────┘ └───────────────────────────────┘


EXISTING TABLES (Used by Simulation)

users, agents, products, shopping_sessions,
shopping_session_events, cart_items, coupons

Layer 5: Tooling & Utilities

┌────────────────────────────────────┐ ┌──────────────────────────────┐
│ seed_simulation_agents.py │ │ check_db.py │
│ • Load Excel personas │ │ • List tables & row counts │
│ • Create users & agents │ │ • Inspect sample data │
│ • --test flag for quick testing │ │ • Validate schema │
└────────────────────────────────────┘ └──────────────────────────────┘

Data Flows

1. TIME ADVANCEMENT
 Orchestrator ──▶ TimeService ──▶ SimulationState (DB)
 │
 └──▶ Coordinate Conversion
 Real Time ↔ Simulated Time
 (1 hour = 168 hours = 1 week)

2. OFFER CYCLE MANAGEMENT
 Scheduler ──▶ CycleManager ──▶ OfferAssigner ──▶ user_coupons
 │ │
 │ └─▶ Distribute to wallets
 │ • frontstore: 2/cycle
 │ • category-brand: 30/cycle
 └─▶ ExpirationHandler
 └─▶ Mark expired offers

3. AGENT EXECUTION
 Orchestrator ──▶ ShoppingGraph (LangGraph)
 │
 ├─▶ decide_shop
 ├─▶ browse_products
 ├─▶ add_to_cart
 ├─▶ view_coupons
 ├─▶ decide_checkout
 └─▶ complete_checkout / abandon_session
 │
 ▼
 Actions ──▶ Database
 │
 ├─▶ shopping_sessions
 └─▶ shopping_session_events (ML training data)

4. AUTHENTICATION FLOW
 HTTP Request ──▶ verify_token()
 │
 ┌────────────┴────────────┐
 ▼ ▼
 Production Simulation
 (Supabase JWT) (dev:<agent_id>)
 │ │
 └───────────┬─────────────┘
 ▼
 User Context
 (user_id, email)

Core Components

1. Offer Engine (Simulation-Only)

Location: app/offer_engine/

Persona Engine

Thu, 25 Dec 2025 00:00:00 +0530

300+ Realistic Shopping Personas at $0 Cost

I have built a retail shopping app to gain hands-on experience in full-stack development. I built and deployed the app and “convinced” 7 friends to sign up for it and play with it. I realized finding users, convincing them to use your app, and get them to play with it for data collection is a hard problem. Enter AI. I used the hallucinating properties of LLMs (along with temperature control, and prompt engineering techniques) to generate 300+ diverse, believable shopper personas. Since this is just a micro-blog on how I generated personas - stay tuned for the next ones where I actually put these 300+ agents to use/interact with the app and give me copius amounts of data to play with (albeit synthetic) AND more importantly it gives me the much needed experience of playing and building with AI Agents (primarily Langgraph). Stay tuned!

2025 Reinforcement Learning Plan

Sat, 26 Jul 2025 23:16:49 -0400

My goal is to become capable of reading research papers and implementing them to solve business/engineering problems using RL. I used the “Study and Learn” mode in ChatGPT to generate the below plan. It seems a decent structure to get me started. I am estimating 5-10 hours per week of work. However, I will push myself to get this done faster and complete it by end of 2025.

Reinforcement Learning Mastery Plan

Time: ~5–10 hrs/week

Mon, 01 Jan 0001 00:00:00 +0000

My Adventure in Full-Stack AI-Powered Application

Ever since I read “Losing My Virginity: How I Survived, Had Fun..” book by Richard Branson, I have always dreamed of entrepreneurship. Building a product and converting it into a business. Until before LLMs came to town, the first step of entrepreneurship - building a product seemed the first and unsurmountable challenge while maintaining a full-time job. Times have changed. But my desire has not. Equipped with AI assist coding tools, I had no doubts about tackling full-stack development, Postgres design, and aim for real users. That is exactly what I did.

Unmesh Mali