CredSim

CredSim is a multi-agent AI simulation of a living credit card ecosystem targeting American Express. 250 AI-powered cardholder agents make real-time spending decisions — 90% via rule engine, 10% via Groq LLM — streaming every transaction through Kafka into a live React dashboard. A scenario control panel lets you trigger world events (recession, bonus season, competitor launch) and watch agent behaviour shift in real time.

---

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│  simulation/main.py                                                 │
│  250 Agent objects (10 persona archetypes)                          │
│  ├── Rule Engine  →  90% of decisions                               │
│  └── Groq LLM     →  10% of decisions  (Llama 3.3 70B via LangChain)│
└──────────────────────────┬──────────────────────────────────────────┘
                           │ confluent-kafka producer
                           ▼
              ┌────────────────────────┐
              │  Kafka  (port 9092)    │  topic: vaultsim.transactions
              └─────────┬──────────────┘
               ┌────────┘────────────────┐
               ▼                         ▼
  ┌────────────────────────┐  ┌───────────────────────────┐
  │  consumer_db.py        │  │  consumer_api.py           │
  │  → TimescaleDB         │  │  → asyncio Queue           │
  │    (port 5432)         │  │       │                    │
  └────────────────────────┘  │       ▼                    │
                               │  FastAPI  (port 8000)      │
                               │  ├── REST endpoints        │
                               │  └── WebSocket  /ws        │
                               └───────────┬────────────────┘
                                           │ WebSocket
                                           ▼
                               ┌───────────────────────────┐
                               │  React Dashboard           │
                               │  http://localhost:3000     │
                               │  ├── Live Transaction Feed │
                               │  ├── Spend Heatmap         │
                               │  ├── Cohort Metrics        │
                               │  └── Scenario Panel        │
                               └───────────────────────────┘

  Infrastructure (Docker Compose):
    vaultsim-zookeeper   :2181
    vaultsim-kafka       :9092
    vaultsim-timescaledb :5432
    vaultsim-kafka-ui    :8080   ← browser Kafka inspector

---

Prerequisites

Tool	Version	Notes
Docker + Docker Compose	24+	Colima works on Mac: brew install colima && colima start
Python	3.11+
Node.js	18+	For the React dashboard
Groq API key	—	Free tier at console.groq.com — 500 req/min

Install Python dependencies:

pip install -r requirements.txt

Install dashboard dependencies:

cd dashboard && npm install

---

Setup

1. Configure environment

cp .env.example .env
# Edit .env and set GROQ_API_KEY=your_key_here

2. Start infrastructure

docker compose up -d

Waits for all 4 services to be healthy (zookeeper, kafka, timescaledb, kafka-ui). Takes ~30 seconds on first run.

3. Start the Kafka → TimescaleDB consumer (terminal 1)

python pipeline/consumer_db.py

4. Start the FastAPI backend (terminal 2)

uvicorn api.main:app --host 0.0.0.0 --port 8000

5. Start the React dashboard (terminal 3)

cd dashboard && npm run dev

---

Run the Simulation

Batch mode (fast, no LLM):

python simulation/main.py --mode batch --days 30 --agents 250

With Kafka streaming (sends transactions live to dashboard):

python simulation/main.py --mode batch --days 30 --agents 250 --kafka

With LLM decisions (Groq, requires API key):

python simulation/main.py --mode batch --days 5 --agents 50 --kafka --llm

With a world event triggered on day 5:

python simulation/main.py --mode batch --days 30 --agents 250 --kafka --event recession --event-day 5

Without Kafka — dashboard header updates, no live feed

python simulation/main.py --mode live --agents 50

With Kafka — full live feed + dashboard header

python simulation/main.py --mode live --agents 50 --kafka

Faster default tick rate

python simulation/main.py --mode live --agents 100 --tick-delay 0.5

All flags:

--mode       batch | compare
--days       N          (simulated days to run)
--agents     N          (population size, default 250)
--start-date YYYY-MM-DD
--event      recession | boom | holiday_season | competitor_launch | bonus_season | travel_surge
--event-day  N          (day on which to trigger the event)
--seed       N          (random seed for reproducibility)
--llm                   (enable Groq LLM decisions)
--kafka                 (stream transactions to Kafka)

---

Access the Dashboard

Open http://localhost:3000 after starting the React dev server.

Panel	Description
Live Transaction Feed	Real-time stream of every transaction as it's produced
Spend Heatmap	Category spend totals — click a bar to filter the feed
Cohort Metrics	Spend by card tier (Platinum / Gold / Green / Business)
Scenario Panel	Trigger world events with one click
Simulation Controls	Start / Pause / 1× 2× 5× 10× speed

---

Trigger a World Event (via API)

# Recession
curl -X POST http://localhost:8000/world/event \
  -H "Content-Type: application/json" \
  -d '{"event_type": "recession"}'

# Boom
curl -X POST http://localhost:8000/world/event \
  -d '{"event_type": "boom"}' -H "Content-Type: application/json"

# Other events: holiday_season | competitor_launch | bonus_season | travel_surge

The dashboard shows a banner immediately and spend patterns visibly shift in the live feed.

---

Query the Data (REST API)

# Spend by category
curl http://localhost:8000/metrics/categories

# Spend by card tier
curl http://localhost:8000/metrics/cohort

# Top 10 spenders
curl http://localhost:8000/metrics/top_agents

# Churn risk signals
curl http://localhost:8000/metrics/churn_risk

# Single agent profile
curl http://localhost:8000/agents/<agent_id>

# API docs (interactive)
open http://localhost:8000/docs

---

Jupyter Notebooks

jupyter lab notebooks/

Notebook	Business Question
01_rewards_roi_analysis.ipynb	Which tier earns the most points per dollar? Where are unredeemed points concentrated?
02_churn_signal_detection.ipynb	RFM model — which agents are at churn risk and what intervention is recommended?
03_segment_profitability.ipynb	Net profit by tier and persona after interchange revenue and rewards liability
04_upgrade_candidates.ipynb	Which Gold/Green cardholders are spending at a higher tier's level? Revenue uplift estimate
05_scenario_comparison.ipynb	Baseline vs recession: which segments are most resilient? Which merchants lose most?

Each notebook connects directly to TimescaleDB via SQLAlchemy and ends with a plain-English Business Recommendation cell.

---

Tech Stack

Layer	Tool	Why
Agent engine	Python OOP	Agents are plain Python objects — no framework overhead
LLM decisions	Groq API (Llama 3.3 70B)	Free tier, sub-second latency, 500 req/min — ideal for 90/10 hybrid routing
LLM orchestration	LangChain	Clean prompt templating and chain management
Event streaming	Apache Kafka	Decouples simulation from dashboard; true real-time push, not polling
Time-series DB	TimescaleDB	PostgreSQL + time-series extension; handles continuous high-volume transaction writes
Backend API	FastAPI + WebSocket	Native async WebSocket; zero-latency broadcast to all dashboard clients
Dashboard	React + Recharts + Tailwind	WebSocket live updates; only changed components re-render
Analysis	Pandas + Seaborn + Jupyter	Standard financial analytics stack; connects directly to TimescaleDB
Orchestration	Docker Compose	One command starts all infrastructure; reproducible across environments

---

Project Structure

vaultsim/
├── simulation/          # Agent engine, world events, decision routing, Kafka producer
│   ├── agents/          # 10 persona archetypes + agent factory
│   ├── decisions/       # Rule engine, LLM engine (Groq), decision router
│   ├── world/           # World state, event engine, merchant network, calendar
│   └── kafka/           # Transaction producer
├── pipeline/
│   ├── consumer_db.py   # Kafka → TimescaleDB
│   └── consumer_api.py  # Kafka → FastAPI broadcast queue
├── api/
│   ├── main.py          # FastAPI app + WebSocket broadcaster
│   ├── websocket.py     # ConnectionManager
│   ├── routes/          # REST endpoints (simulation, world events, agents, metrics)
│   └── db/              # TimescaleDB schema + query helpers
├── dashboard/           # React + Vite + Recharts + Tailwind
│   └── src/
│       ├── components/  # LiveFeed, SpendHeatmap, CohortMetrics, ScenarioPanel, AgentCard
│       └── hooks/       # useWebSocket
├── notebooks/           # 5 business analysis notebooks
├── docker-compose.yml   # Zookeeper, Kafka, TimescaleDB, Kafka-UI
└── .env.example

---

Built as a portfolio project targeting American Express — Data Analyst role. Demonstrates production-grade architecture: real-time streaming, hybrid AI decision routing, time-series analytics, and live dashboard.