deploying the new UI

README.md

@@ -4,1127 +4,240 @@ emoji: 🎶
 colorFrom: blue
 colorTo: gray
 sdk: streamlit
-sdk_version: 1.46.0
+sdk_version: 1.50.0
 python_version: 3.9
 app_file: app.py
 ---
 
-# AI Messaging System - Visualization Tool
 
-An interactive Streamlit-based visualization and experimentation tool for the AI Messaging System v2. This tool enables non-technical users to generate, visualize, analyze, and improve personalized message campaigns with integrated A/B testing capabilities and comprehensive historical tracking.
+# AI Messaging System v3 — Visualization Tool
 
-## 🎯 Purpose
+A Streamlit tool for reviewing and evaluating AI-generated push notification messages. All data is read from a single output table — no joins. Reviewers filter messages by brand, campaign, and scenario, inspect user context stored at generation time, and flag any message that has issues. Rejections are persisted to Snowflake. No action on a message means it is good.
 
-- Generate personalized messages with various configurations
-- Run A/B tests with parallel processing and side-by-side comparison
-- Visualize and analyze messages in real-time across all campaign stages
-- Provide detailed feedback with message header/body tracking
-- Track improvements and trends across historical experiments
-- Cloud-native architecture with Snowflake integration
-- Ready for deployment on HuggingFace Spaces
+This tool does **not** generate messages. It is purely for reviewing messages already produced by the v3 pipeline.
 
 ---
 
-## 🏗️ Architecture Overview
+## Purpose
 
-### Core Philosophy: **In-Memory + Cloud Persistence**
-
-The system operates on a hybrid architecture:
-- **In-Memory Operations**: All active experiments run in `session_state` (no local files)
-- **Cloud Persistence**: Data stored in Snowflake for long-term analytics
-- **On-Demand Loading**: Historical data loaded from Snowflake when needed
-- **One-Click Storage**: Results persisted with a single button click
-
-### Why This Architecture?
-
-1. **HuggingFace Ready**: No local file dependencies
-2. **Fast Operations**: In-memory processing for real-time feedback
-3. **Scalable**: Snowflake handles unlimited historical data
-4. **Clean Separation**: Current experiments vs. historical data
-5. **Versioned Configs**: Automatic configuration versioning in Snowflake
+- Pre-fetch the most recent 150 messages per campaign on login (single query, no joins)
+- Filter instantly by brand, campaign, and scenario — all client-side, no extra DB queries
+- View the user context captured at generation time (streaks, profile, previous messages, last interacted content)
+- Reject messages with a structured reason — persisted to Snowflake immediately
+- Track rejection counts per review session in the sidebar
 
 ---
 
-## 📁 Directory Structure
+## Directory Structure
 
 ```
 visualization/
-├── app.py                         # Main entry point with authentication & brand selection
-├── pages/                         # Multi-page Streamlit application
-│   ├── 1_Campaign_Builder.py      # Campaign configuration & generation (with A/B testing)
-│   ├── 2_Message_Viewer.py        # Message browsing & feedback (A/B aware)
-│   ├── 4_Analytics.py             # Performance metrics for CURRENT experiment
-│   └── 5_Historical_Analytics.py  # Historical experiments from Snowflake
-├── utils/                         # Utility modules
-│   ├── __init__.py
-│   ├── auth.py                    # Authentication logic
-│   ├── config_manager.py          # Configuration loading from Snowflake
-│   ├── db_manager.py              # Snowflake database operations (NEW)
-│   ├── experiment_runner.py       # Parallel experiment execution (NEW)
-│   ├── session_feedback_manager.py # In-memory feedback management (NEW)
-│   └── theme.py                   # Brand-specific theming
-├── data/                          # Local data storage (configs cached here)
-│   └── UI_users/                  # Pre-loaded user lists (100 users per brand)
-│       ├── drumeo_users.csv
-│       ├── pianote_users.csv
-│       ├── guitareo_users.csv
-│       └── singeo_users.csv
-├── requirements.txt               # Python dependencies
-├── README.md                      # This file
-├── IMPLEMENTATION_COMPLETE.md     # Refactoring details & progress
-└── ARCHITECTURE_REFACTOR_GUIDE.md # Technical refactoring guide
-```
-
-## 🗄️ Snowflake Database Schema
-
-### Tables
-
-**1. MESSAGING_SYSTEM_V2.UI.CONFIGS**
-```sql
-CONFIG_NAME      VARCHAR    -- Configuration identifier
-CONFIG_FILE      VARIANT    -- JSON configuration
-CONFIG_VERSION   INTEGER    -- Auto-incrementing version
-BRAND            VARCHAR    -- Brand name (drumeo, pianote, etc.)
-CREATED_AT       TIMESTAMP  -- Creation timestamp
-```
-
-**2. MESSAGING_SYSTEM_V2.UI.EXPERIMENT_METADATA**
-```sql
-EXPERIMENT_ID               VARCHAR    -- Unique experiment identifier
-CONFIG_NAME                 VARCHAR    -- Configuration used
-BRAND                       VARCHAR    -- Brand name
-CAMPAIGN_NAME               VARCHAR    -- Campaign identifier
-STAGE                       INTEGER    -- Stage number (1-11)
-LLM_MODEL                   VARCHAR    -- Model used (gpt-4o-mini, gemini-2.5-flash-lite, etc.)
-TOTAL_MESSAGES              INTEGER    -- Messages generated in this stage
-TOTAL_USERS                 INTEGER    -- Unique users in this stage
-PLATFORM                    VARCHAR    -- Platform (push, email, etc.)
-PERSONALIZATION             BOOLEAN    -- Personalization enabled
-INVOLVE_RECSYS              BOOLEAN    -- Recommendations enabled
-RECSYS_CONTENTS             ARRAY      -- Recommendation types
-SEGMENT_INFO                VARCHAR    -- Segment description
-CAMPAIGN_INSTRUCTIONS       VARCHAR    -- Campaign-wide instructions
-PER_MESSAGE_INSTRUCTIONS    VARCHAR    -- Stage-specific instructions
-START_TIME                  TIMESTAMP  -- Experiment start time
-END_TIME                    TIMESTAMP  -- Experiment end time (optional)
-```
-
-**3. MESSAGING_SYSTEM_V2.UI.FEEDBACKS**
-```sql
-EXPERIMENT_ID      VARCHAR    -- Links to EXPERIMENT_METADATA
-USER_ID            INTEGER    -- User who received the message
-STAGE              INTEGER    -- Stage number
-FEEDBACK_TYPE      VARCHAR    -- 'reject' (only type currently)
-REJECTION_REASON   VARCHAR    -- Reason category key
-REJECTION_TEXT     VARCHAR    -- Custom text explanation
-MESSAGE_HEADER     VARCHAR    -- Full message header
-MESSAGE_BODY       VARCHAR    -- Full message body
-CAMPAIGN_NAME      VARCHAR    -- Campaign identifier
-BRAND              VARCHAR    -- Brand name
-CONFIG_NAME        VARCHAR    -- Configuration used
-TIMESTAMP          TIMESTAMP  -- Feedback submission time
+├── app.py                          # Entry point: login + data pre-fetch on authentication
+├── pages/
+│   └── 1_Message_Viewer.py         # Message cards, filters, user context, rejection UI
+├── utils/
+│   ├── auth.py                     # Login / session authentication
+│   ├── snowflake_client.py         # Snowflake reads (single table) and feedback writes
+│   ├── feedback_manager.py         # In-session rejection state + Snowflake persistence
+│   ├── theme.py                    # Brand colours, campaign labels, scenario definitions
+│   └── __init__.py
+├── requirements.txt
+├── .env                            # Credentials (not committed)
+├── .env.example
+└── README.md
 ```
 
 ---
 
-## 🚀 Getting Started
+## Getting Started
 
-### Prerequisites
-
-- Python 3.9+
-- Snowflake account and credentials
-- OpenAI/Google AI API keys
-- AI Messaging System v2 installed in parent directory
-- Plotly for data visualization
-
-### Installation
+### 1. Install dependencies
 
 ```bash
-# Install dependencies
 pip install -r requirements.txt
-
-# Set up environment variables (.env file)
-SNOWFLAKE_USER=your_user
-SNOWFLAKE_PASSWORD=your_password
-SNOWFLAKE_ACCOUNT=your_account
-SNOWFLAKE_ROLE=your_role
-SNOWFLAKE_DATABASE=MESSAGING_SYSTEM_V2
-SNOWFLAKE_WAREHOUSE=your_warehouse
-SNOWFLAKE_SCHEMA=UI
-
-# LLM API keys
-OPENAI_API_KEY=your_key
-GOOGLE_API_KEY=your_key
-```
-
-### Running the Application
-
-```bash
-# From the visualization directory
-cd visualization
-streamlit run app.py
-```
-
-### First-Time Setup
-
-1. Ensure `.env` file exists with Snowflake credentials
-2. Verify user CSV files exist in `data/UI_users/` for each brand
-3. Create Snowflake tables using schema above (or let system auto-create)
-4. Upload initial configurations to Snowflake (optional - can create in UI)
-5. Login with authorized email and access token
-
----
-
-## 📊 Complete Data Flow
-
-### **Session State Architecture**
-
-All active data lives in Streamlit's `session_state`:
-
-```python
-# Single Experiment Mode
-st.session_state.ui_log_data              # DataFrame: Generated messages
-st.session_state.current_experiment_id    # String: Experiment identifier
-st.session_state.current_experiment_metadata  # List[Dict]: Metadata per stage
-st.session_state.current_feedbacks        # List[Dict]: Feedback records
-
-# AB Testing Mode
-st.session_state.ui_log_data_a            # DataFrame: Experiment A messages
-st.session_state.ui_log_data_b            # DataFrame: Experiment B messages
-st.session_state.experiment_a_id          # String: Experiment A identifier
-st.session_state.experiment_b_id          # String: Experiment B identifier
-st.session_state.experiment_a_metadata    # List[Dict]: A's metadata
-st.session_state.experiment_b_metadata    # List[Dict]: B's metadata
-st.session_state.feedbacks_a              # List[Dict]: A's feedback
-st.session_state.feedbacks_b              # List[Dict]: B's feedback
-
-# Configuration
-st.session_state.campaign_config          # Dict: Single mode config
-st.session_state.campaign_config_a        # Dict: AB mode config A
-st.session_state.campaign_config_b        # Dict: AB mode config B
-st.session_state.configs_cache            # Dict: Cached configs from Snowflake
-```
-
-### **End-to-End Workflow**
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                     1. CAMPAIGN BUILDER                         │
-├─────────────────────────────────────────────────────────────────┤
-│ • Load configs from Snowflake (cached in session_state)         │
-│ • User selects/modifies configuration                           │
-│ • Sample users from CSV files                                   │
-│ • Generate messages (stored in session_state.ui_log_data)       │
-│ • Track metadata (session_state.current_experiment_metadata)    │
-└─────────────────────────────────────────────────────────────────┘
-                              ↓
-┌─────────────────────────────────────────────────────────────────┐
-│                      2. MESSAGE VIEWER                          │
-├─────────────────────────────────────────────────────────────────┤
-│ • Load messages from session_state.ui_log_data                  │
-│ • Display in user-centric or stage-centric views               │
-│ • User provides feedback (reject messages)                      │
-│ • Feedback stored in session_state.current_feedbacks            │
-│ • [BUTTON] Store Results to Snowflake                          │
-│   → Writes metadata to EXPERIMENT_METADATA table               │
-│   → Writes feedback to FEEDBACKS table                         │
-└─────────────────────────────────────────────────────────────────┘
-                              ↓
-┌─────────────────────────────────────────────────────────────────┐
-│                        3. ANALYTICS                             │
-├─────────────────────────────────────────────────────────────────┤
-│ • Load current experiment from session_state                    │
-│ • Calculate metrics using SessionFeedbackManager                │
-│ • Show overall performance, stage analysis, rejection reasons   │
-│ • Support AB testing side-by-side comparison                    │
-└─────────────────────────────────────────────────────────────────┘
-                              ↓
-┌─────────────────────────────────────────────────────────────────┐
-│                   4. HISTORICAL ANALYTICS                       │
-├─────────────────────────────────────────────────────────────────┤
-│ • [BUTTON] Load Historical Data from Snowflake                  │
-│ • Query EXPERIMENT_METADATA + FEEDBACKS tables                  │
-│ • Calculate aggregate metrics across all experiments            │
-│ • Show trends: rejection rates over time                        │
-│ • Compare configurations: which performs best                   │
-│ • Filter by date range                                          │
-└─────────────────────────────────────────────────────────────────┘
-```
-
----
-
-## 📄 Pages Overview
-
-### Page 0: Home & Authentication (app.py)
-
-**Purpose**: Login, brand selection, config loading, and navigation hub
-
-**Features**:
-- Email and token-based authentication
-- Brand selection (Drumeo, Pianote, Guitareo, Singeo)
-- **Config loading from Snowflake on startup**
-- Brand-specific theming applied throughout app
-- Navigation guide and quick start instructions
-- Current experiment status overview
-
-**Technical Details**:
-- Session-based authentication
-- Brand selection persists via `st.session_state.selected_brand`
-- Configs cached in `st.session_state.configs_cache` on first load
-- Dynamic theming using `utils/theme.py`
-- Loads environment variables from `.env` file
-
-**Key Functions**:
-```python
-def load_configs_from_snowflake(brand):
-    """Load all configs for brand from Snowflake, cache in session_state."""
-    session = create_snowflake_session()
-    config_manager = ConfigManager(session)
-    configs = config_manager.load_configs_from_snowflake(brand)
-    st.session_state.configs_cache = configs
-    session.close()
-```
-
----
-
-### Page 1: Campaign Builder
-
-**Purpose**: Create and run message generation campaigns with integrated A/B testing
-
-**Architecture**: In-memory experiment execution with parallel AB testing
-
-#### Key Features
-
-**Configuration Management**:
-- Loads configs from cached `session_state.configs_cache`
-- Real-time config editing in UI
-- Save configs to Snowflake with auto-versioning
-- Quick save or save-as-new options
-
-**A/B Testing Toggle**:
-- Single Experiment Mode (default): One campaign
-- A/B Testing Mode: Two parallel experiments for comparison
-
-**User Sampling**:
-- Random sampling from brand-specific CSV files
-- 1-25 users selectable
-- Same users used for both AB experiments (fair comparison)
-
-**Parallel Execution**:
-- Uses `ExperimentRunner.run_ab_test_parallel()`
-- Threading for simultaneous A/B generation
-- Separate Snowflake sessions per experiment (no conflicts)
-- Console logging for thread progress
-- Results stored directly in session_state
-
-**Technical Details**:
-
-**Single Mode Generation**:
-```python
-# ExperimentRunner handles all generation logic
-runner = ExperimentRunner(brand=brand, system_config=config)
-
-success, ui_log_data, metadata = runner.run_single_experiment(
-    config=campaign_config,
-    sampled_users_df=users_df,
-    experiment_id=experiment_id,
-    create_session_func=create_snowflake_session,
-    progress_container=st.container()
-)
-
-# Store in session_state
-st.session_state.ui_log_data = ui_log_data
-st.session_state.current_experiment_metadata = metadata
-st.session_state.current_experiment_id = experiment_id
 ```
 
-**AB Mode Generation**:
-```python
-# Parallel execution in threads
-results = runner.run_ab_test_parallel(
-    config_a=campaign_config_a,
-    config_b=campaign_config_b,
-    sampled_users_df=users_df,
-    experiment_a_id=experiment_a_id,
-    experiment_b_id=experiment_b_id,
-    create_session_func=create_snowflake_session
-)
+### 2. Configure credentials
 
-# Store both results
-st.session_state.ui_log_data_a = results['a']['ui_log_data']
-st.session_state.ui_log_data_b = results['b']['ui_log_data']
-st.session_state.experiment_a_metadata = results['a']['metadata']
-st.session_state.experiment_b_metadata = results['b']['metadata']
-```
+Copy `.env.example` to `.env` and fill in your Snowflake credentials and the app token:
 
-**Configuration Saving to Snowflake**:
-```python
-# Save with auto-versioning
-session = create_snowflake_session()
-db_manager = UIDatabaseManager(session)
-success = db_manager.save_config(
-    config_name=config_name,
-    config_data=campaign_config,
-    brand=brand
-)
-session.close()
 ```
-
-**Thread-Safe Progress Handling**:
-- Main thread: Full Streamlit UI updates
-- Worker threads: Console logging only
-- Dummy progress bars prevent Streamlit errors in threads
-
----
-
-### Page 2: Message Viewer
-
-**Purpose**: Browse, search, and evaluate generated messages with A/B testing awareness
-
-**Architecture**: Loads from session_state, feedback stored in-memory
-
-#### Key Features
-
-**Automatic AB Detection**:
-```python
-def detect_ab_testing_mode():
-    """Detect AB mode from session_state."""
-    return (
-        'ui_log_data_a' in st.session_state and
-        'ui_log_data_b' in st.session_state and
-        st.session_state.ui_log_data_a is not None and
-        st.session_state.ui_log_data_b is not None
-    )
-```
-
-**Message Loading**:
-```python
-# Single mode
-def get_single_experiment_data():
-    if 'ui_log_data' in st.session_state:
-        return st.session_state.ui_log_data
-    return None
-
-# AB mode - loads both dataframes
-messages_a_df = st.session_state.ui_log_data_a
-messages_b_df = st.session_state.ui_log_data_b
-```
-
-**Feedback System**:
-- In-memory storage using `SessionFeedbackManager`
-- Rejection categories: Poor header, Poor body, Grammar, Emoji, Recommendation issues, Similar to previous, etc.
-- Stores full message header and body with feedback
-- Undo rejection capability
-
-```python
-# Add feedback
-SessionFeedbackManager.add_feedback(
-    experiment_id=experiment_id,
-    user_id=user_id,
-    stage=stage,
-    feedback_type="reject",
-    rejection_reason="poor_header",
-    rejection_text="Too generic",
-    message_header=header,
-    message_body=body,
-    campaign_name=campaign_name,
-    brand=brand,
-    config_name=config_name,
-    feedback_list_key="current_feedbacks"  # or "feedbacks_a", "feedbacks_b"
-)
+SNOWFLAKE_USER     = ...
+SNOWFLAKE_PASSWORD = ...
+SNOWFLAKE_ACCOUNT  = ...
+SNOWFLAKE_ROLE     = ACCOUNTADMIN
+SNOWFLAKE_DATABASE = RECSYS_V3
+SNOWFLAKE_WAREHOUSE= COMPUTE_WH
+SNOWFLAKE_SCHEMA   = PUBLIC
+APP_TOKEN          = ...
 ```
 
-**Store Results to Snowflake** (CRITICAL FEATURE):
-
-Located after message viewing section. Button appears prominently.
-
-```python
-if st.button("💾 Store Results to Snowflake"):
-    session = create_snowflake_session()
-    db_manager = UIDatabaseManager(session)
-
-    # Single mode
-    if not ab_mode:
-        # Store metadata
-        for meta in st.session_state.current_experiment_metadata:
-            db_manager.store_experiment_metadata(meta)
-
-        # Store feedback
-        for feedback in st.session_state.current_feedbacks:
-            db_manager.store_feedback(feedback)
-
-    # AB mode
-    else:
-        # Store both experiments
-        for meta in st.session_state.experiment_a_metadata:
-            db_manager.store_experiment_metadata(meta)
-        for meta in st.session_state.experiment_b_metadata:
-            db_manager.store_experiment_metadata(meta)
-
-        for feedback in st.session_state.feedbacks_a:
-            db_manager.store_feedback(feedback)
-        for feedback in st.session_state.feedbacks_b:
-            db_manager.store_feedback(feedback)
-
-    session.close()
-    st.success("✅ Results stored to Snowflake successfully!")
-    st.balloons()
-```
-
-**View Modes**:
-- User-Centric: All stages for each user
-- Stage-Centric: All users for each stage
-- Filters: Stage selection, keyword search, pagination
-
----
-
-### Page 3: Analytics Dashboard
-
-**Purpose**: Visualize performance metrics for CURRENT experiment only
-
-**Architecture**: Loads from session_state, uses SessionFeedbackManager
-
-#### Key Features
-
-**Data Loading**:
-```python
-# Single mode
-def get_single_experiment_data():
-    return st.session_state.ui_log_data
-
-# AB mode
-detect_ab_testing_mode()  # Returns True if AB data exists
-messages_a_df = st.session_state.ui_log_data_a
-messages_b_df = st.session_state.ui_log_data_b
-```
-
-**Feedback Stats Calculation**:
-```python
-# Single mode
-feedback_stats = SessionFeedbackManager.get_feedback_stats(
-    experiment_id=experiment_id,
-    total_messages=len(messages_df),
-    feedback_list_key="current_feedbacks"
-)
-
-# AB mode
-feedback_stats_a = SessionFeedbackManager.get_feedback_stats(
-    experiment_a_id,
-    total_messages=len(messages_a_df),
-    feedback_list_key="feedbacks_a"
-)
-feedback_stats_b = SessionFeedbackManager.get_feedback_stats(
-    experiment_b_id,
-    total_messages=len(messages_b_df),
-    feedback_list_key="feedbacks_b"
-)
-```
-
-**Metrics Displayed**:
-- Overall: Total messages, rejection rate, feedback count
-- Stage-by-Stage: Performance breakdown per stage
-- Rejection Reasons: Pie charts and bar charts
-- AB Comparison: Side-by-side metrics with winner determination
-
-**Export Options**:
-- Export current messages to CSV
-- Export current feedback to CSV
-- Export analytics summary to CSV
-
-**Important**: Analytics page shows ONLY the current in-memory experiment. For historical data, use Historical Analytics.
-
----
-
-### Page 4: Historical Analytics
-
-**Purpose**: Track all past experiments and analyze trends from Snowflake
-
-**Architecture**: Button-triggered Snowflake queries
-
-#### Key Features
-
-**Load Button**:
-```python
-if st.button("📊 Load Historical Data from Snowflake"):
-    session = create_snowflake_session()
-    db_manager = UIDatabaseManager(session)
-
-    # Load experiment summary with JOIN
-    experiments_df = db_manager.get_experiment_summary(brand=brand)
+### 3. Run the app
 
-    st.session_state['historical_experiments'] = experiments_df
-    st.session_state['historical_data_loaded'] = True
-
-    session.close()
-```
-
-**SQL Query Example**:
-```sql
-SELECT
-    m.EXPERIMENT_ID,
-    m.CONFIG_NAME,
-    m.CAMPAIGN_NAME,
-    m.BRAND,
-    MIN(m.START_TIME) as start_time,
-    SUM(m.TOTAL_MESSAGES) as total_messages,
-    MAX(m.TOTAL_USERS) as total_users,
-    COUNT(DISTINCT m.STAGE) as total_stages,
-    COUNT(f.FEEDBACK_TYPE) as total_rejects,
-    (COUNT(f.FEEDBACK_TYPE) * 100.0 / NULLIF(SUM(m.TOTAL_MESSAGES), 0)) as rejection_rate
-FROM MESSAGING_SYSTEM_V2.UI.EXPERIMENT_METADATA m
-LEFT JOIN MESSAGING_SYSTEM_V2.UI.FEEDBACKS f
-    ON m.EXPERIMENT_ID = f.EXPERIMENT_ID
-WHERE m.BRAND = :brand
-GROUP BY m.EXPERIMENT_ID, m.CONFIG_NAME, m.CAMPAIGN_NAME, m.BRAND
-ORDER BY start_time DESC
+```bash
+cd ai_messaging_system_v3/visualization
+streamlit run app.py
 ```
 
-**Visualizations**:
-- Experiments summary table
-- Rejection rate trend over time (line chart)
-- Performance comparison by configuration (bar chart)
-- Best/worst performing configs
-
-**Filters**:
-- Date range filtering
-- Automatic refresh button
-
-**Export**:
-- Export summary to CSV
-- Note: Detailed feedback export coming soon (use SQL queries for now)
-
 ---
 
-## 🔧 Utility Modules
-
-### utils/db_manager.py - UIDatabaseManager
-
-**Purpose**: All Snowflake database operations
-
-**Key Methods**:
-```python
-class UIDatabaseManager:
-    def __init__(self, session: Session):
-        """Initialize with Snowflake session."""
-
-    def save_config(self, config_name, config_data, brand):
-        """Save config with auto-versioning."""
-
-    def load_config(self, config_name, brand, version=None):
-        """Load specific config version."""
-
-    def store_experiment_metadata(self, metadata: dict):
-        """Insert metadata record."""
+## Authentication
 
-    def store_feedback(self, feedback: dict):
-        """Insert feedback record."""
-
-    def get_experiment_summary(self, brand=None, start_date=None, end_date=None):
-        """Get aggregated experiment metrics with JOIN."""
-
-    def close(self):
-        """Close Snowflake session."""
-```
-
-**Usage Pattern**:
-```python
-# Always use context-like pattern
-session = create_snowflake_session()
-db_manager = UIDatabaseManager(session)
-
-try:
-    # Do operations
-    db_manager.save_config(...)
-    db_manager.store_feedback(...)
-finally:
-    db_manager.close()  # or session.close()
-```
+Login requires an email from the authorised list and a shared access token (`APP_TOKEN` in `.env`). Authorised emails are defined in `utils/auth.py`.
 
 ---
 
-### utils/config_manager.py - ConfigManager
+## Snowflake Tables
 
-**Purpose**: Configuration loading and caching
+### Input (read-only) — single table, no joins
 
-**Key Methods**:
-```python
-class ConfigManager:
-    def __init__(self, session: Session):
-        """Initialize with Snowflake session."""
+All data needed for display and filtering is stored at message generation time in one table.
 
-    def load_configs_from_snowflake(self, brand: str) -> Dict:
-        """Load all configs for brand, returns {name: config_data}."""
+**`MESSAGING_SYSTEM_V2.GENERATED_DATA.DAILY_PUSH_MESSAGES`**
 
-    def get_latest_version(self, config_name: str, brand: str) -> int:
-        """Get latest version number."""
-```
+| Column | Type | Description |
+| --- | --- | --- |
+| `USER_ID` | NUMBER | Target user |
+| `DETECTED_BRAND` | VARCHAR | Brand: `drumeo`, `pianote`, `guitareo`, `singeo`, `playbass` |
+| `BRANCH` | VARCHAR | Campaign routing key (mirrors `CAMPAIGN_NAME`) |
+| `MESSAGE` | VARCHAR | JSON string `{"header": "...", "message": "..."}` — parsed into header + body |
+| `PLATFORM` | VARCHAR | Delivery platform (e.g. `push`) |
+| `CAMPAIGN_NAME` | VARCHAR | `dailyPush_dailyStreak`, `dailyPush_weeklyStreak`, `dailyPush_noStreak` |
+| `TIMESTAMP` | TIMESTAMP | Generation timestamp |
+| `RECOMMENDATION` | VARCHAR | Recommendation type; `for_you` means no specific recommendation (used for scenario detection) |
+| `RECOMMENDED_CONTENT_ID` | NUMBER | Content ID linked in the message (if any) |
+| `FIRST_NAME` | VARCHAR | User's first name at generation time |
+| `CURRENT_DAILY_STREAK_LENGTH` | NUMBER | Daily streak at generation time |
+| `CURRENT_WEEKLY_STREAK_LENGTH` | NUMBER | Weekly streak at generation time |
+| `USER_PROFILE` | VARCHAR | User profile text used for personalisation |
+| `PREVIOUS_MESSAGES` | VARCHAR | JSON snapshot of prior messages for this user |
+| `LAST_INTERACTED_CONTENT_PROFILE` | VARCHAR | Profile of the last content the user interacted with |
 
-**Caching Strategy**:
-- Configs loaded once on app startup
-- Cached in `st.session_state.configs_cache`
-- Format: `{"config_name": {...config_data...}, ...}`
-- No re-querying Snowflake during session
+### Output (written by this tool)
 
----
-
-### utils/experiment_runner.py - ExperimentRunner
-
-**Purpose**: Execute experiments with proper session management
+**`MESSAGING_SYSTEM_V2.UI.V3_FEEDBACKS`** — created automatically on first run.
 
-**Key Methods**:
-```python
-class ExperimentRunner:
-    def run_single_experiment(
-        self, config, sampled_users_df, experiment_id,
-        create_session_func, progress_container
-    ):
-        """Run one experiment, all stages sequentially."""
+| Column | Description |
+| --- | --- |
+| `BATCH_ID` | UUID generated per review session |
+| `USER_ID` | Reviewed user |
+| `CAMPAIGN_NAME` | Campaign of the reviewed message |
+| `BRAND` | Brand of the reviewed user |
+| `REJECTION_REASON` | Category key (see Rejection Reasons) |
+| `REJECTION_TEXT` | Optional free-text note from the reviewer |
+| `MESSAGE_HEADER` | Full header at time of review |
+| `MESSAGE_BODY` | Full body at time of review |
+| `MESSAGE_TIMESTAMP` | When the message was originally generated |
+| `REVIEWER_EMAIL` | Email of the reviewer |
+| `TIMESTAMP` | When the rejection was submitted |
 
-    def run_ab_test_parallel(
-        self, config_a, config_b, sampled_users_df,
-        experiment_a_id, experiment_b_id, create_session_func
-    ):
-        """Run two experiments in parallel threads."""
-```
-
-**Thread-Safe Design**:
-- Each thread gets own Snowflake session
-- Progress updates handled safely:
-  - Main thread: Full Streamlit UI
-  - Worker threads: Console logging with dummy UI objects
-- No Streamlit context errors
+Rejections are upserted via `MERGE` — changing the reason on an already-rejected message updates the existing row.
 
-**Implementation**:
-```python
-# Thread function
-def run_experiment(exp_key, config, exp_id):
-    try:
-        success, data, metadata = self.run_single_experiment(
-            config=config,
-            sampled_users_df=users_df,
-            experiment_id=exp_id,
-            create_session_func=create_session_func,
-            progress_container=None  # None = threaded mode
-        )
-        results[exp_key] = {'success': success, 'ui_log_data': data, 'metadata': metadata}
-    except Exception as e:
-        results[exp_key] = {'success': False, 'error': str(e)}
-
-# Start threads
-thread_a = threading.Thread(target=run_experiment, args=('a', config_a, exp_a_id))
-thread_b = threading.Thread(target=run_experiment, args=('b', config_b, exp_b_id))
-thread_a.start()
-thread_b.start()
-thread_a.join()
-thread_b.join()
-```
+Users with any existing rejection in `V3_FEEDBACKS` are **excluded** from the pre-fetch query, so the same message is never shown twice across sessions.
 
 ---
 
-### utils/session_feedback_manager.py - SessionFeedbackManager
-
-**Purpose**: In-memory feedback management
-
-**Static Methods** (no instance needed):
-```python
-@staticmethod
-def add_feedback(experiment_id, user_id, stage, feedback_type,
-                 rejection_reason, rejection_text, message_header,
-                 message_body, campaign_name, brand, config_name,
-                 feedback_list_key):
-    """Add feedback to session_state list."""
-
-@staticmethod
-def get_feedback_stats(experiment_id, total_messages, feedback_list_key):
-    """Calculate aggregate stats from feedback list."""
-
-@staticmethod
-def get_stage_feedback_stats(experiment_id, messages_df, feedback_list_key):
-    """Calculate per-stage stats."""
-
-@staticmethod
-def get_rejection_reason_label(reason_key):
-    """Map reason key to display label."""
-```
+## Filters
 
-**Feedback List Keys**:
-- `"current_feedbacks"` - Single mode
-- `"feedbacks_a"` - AB mode experiment A
-- `"feedbacks_b"` - AB mode experiment B
+All filters are applied instantly client-side on the pre-loaded DataFrame — no Snowflake query is triggered on filter change.
 
-**Usage**:
-```python
-# Add feedback
-SessionFeedbackManager.add_feedback(
-    experiment_id="drumeo_20260114_1234",
-    user_id=12345,
-    stage=1,
-    feedback_type="reject",
-    rejection_reason="poor_header",
-    rejection_text="Too generic",
-    message_header="Your next lesson 👇",
-    message_body="Check it out...",
-    campaign_name="Re-engagement",
-    brand="drumeo",
-    config_name="drumeo_re_engagement_test",
-    feedback_list_key="current_feedbacks"
-)
-
-# Get stats
-stats = SessionFeedbackManager.get_feedback_stats(
-    experiment_id="drumeo_20260114_1234",
-    total_messages=100,
-    feedback_list_key="current_feedbacks"
-)
-# Returns: {'total_feedback': 10, 'total_rejects': 10,
-#           'reject_rate': 10.0, 'rejection_reasons': {...}}
-```
+| Filter | Source column | Notes |
+| --- | --- | --- |
+| Brand | `DETECTED_BRAND` | All, Drumeo, Pianote, Guitareo, Singeo, Playbass |
+| Campaign | `CAMPAIGN_NAME` | All, Daily Streak, Weekly Streak, No Streak |
+| Scenario | `RECOMMENDATION` | Weekly Streak campaign only (see Scenarios) |
+| Only users with previous messages | `HAS_PREVIOUS` | Pre-computed at fetch time via `COUNT(*) > 1` |
 
 ---
 
-## 🎨 Brand Theming
-
-Theming automatically adjusts based on selected brand:
-
-| Brand    | Primary Color | Sidebar BG | Accent   | Emoji |
-|----------|---------------|------------|----------|-------|
-| Base     | Gold          | Dark Gold  | Gold     | 🎵    |
-| Drumeo   | Light Blue    | Dark Blue  | Blue     | 🥁    |
-| Pianote  | Light Red     | Dark Red   | Red      | 🎹    |
-| Guitareo | Light Green   | Dark Green | Green    | 🎸    |
-| Singeo   | Light Purple  | Dark Purple| Purple   | 🎤    |
-
-**Implementation**: `utils/theme.py`
-
-```python
-def get_brand_theme(brand):
-    """Returns theme dictionary."""
+## Campaigns and Scenarios
 
-def apply_theme(brand):
-    """Applies CSS via st.markdown."""
-
-def get_brand_emoji(brand):
-    """Returns brand emoji."""
-```
+| Campaign | Scenario key | Display label | Detection |
+| --- | --- | --- | --- |
+| `dailyPush_dailyStreak` | — | — | No sub-scenarios |
+| `dailyPush_weeklyStreak` | `no_practice_this_week` | No Practice This Week | `RECOMMENDATION == 'for_you'` |
+| `dailyPush_weeklyStreak` | `practiced_this_week` | Practiced This Week | `RECOMMENDATION != 'for_you'` |
+| `dailyPush_noStreak` | — | — | No sub-scenarios |
 
 ---
 
-## 🔍 Key Implementation Details
+## Rejection Reason Categories
 
-### Configuration File Structure
-
-```json
-{
-  "brand": "drumeo",
-  "campaign_type": "re_engagement",
-  "campaign_name": "UI-Test-Campaign",
-  "campaign_instructions": "Keep messages encouraging and motivational.",
-  "1": {
-    "stage": 1,
-    "model": "gemini-2.5-flash-lite",
-    "personalization": true,
-    "involve_recsys_result": true,
-    "recsys_contents": ["workout", "course", "quick_tips"],
-    "specific_content_id": null,
-    "segment_info": "Students inactive for 3+ days",
-    "instructions": "",
-    "sample_examples": "Header: Your next lesson 👇\nMessage: Check it out!",
-    "identifier_column": "user_id",
-    "platform": "push"
-  },
-  "2": {
-    "stage": 2,
-    "model": "gpt-4o-mini",
-    "personalization": true,
-    "involve_recsys_result": true,
-    "recsys_contents": ["song"],
-    "specific_content_id": 12345,
-    "segment_info": "Students inactive for 7+ days",
-    "instructions": "Focus on easy songs",
-    "sample_examples": "Header: Let's jam! 🎸\nMessage: Try this song!",
-    "identifier_column": "user_id",
-    "platform": "push"
-  }
-}
-```
-
-### Rejection Reason Categories
-
-```python
-REJECTION_REASONS = {
-    "poor_header": "Poor Header",
-    "poor_body": "Poor Body/Content",
-    "grammar_issues": "Grammar Issues",
-    "emoji_problems": "Emoji Problems",
-    "recommendation_issues": "Recommendation Issues",
-    "wrong_information": "Wrong/Inaccurate Information",
-    "tone_issues": "Tone Issues",
-    "similarity": "Similar To Previous Header/Messages",
-    "other": "Other"
-}
-```
-
-### Environment Variables Required
-
-```bash
-# Snowflake
-SNOWFLAKE_USER=your_user
-SNOWFLAKE_PASSWORD=your_password
-SNOWFLAKE_ACCOUNT=your_account
-SNOWFLAKE_ROLE=your_role
-SNOWFLAKE_DATABASE=MESSAGING_SYSTEM_V2
-SNOWFLAKE_WAREHOUSE=your_warehouse
-SNOWFLAKE_SCHEMA=UI
-
-# LLM APIs
-OPENAI_API_KEY=sk-...
-GOOGLE_API_KEY=AIza...
-```
+| Key | Label |
+| --- | --- |
+| `poor_header` | Poor Header |
+| `poor_body` | Poor Body / Content |
+| `grammar_issues` | Grammar Issues |
+| `emoji_problems` | Emoji Problems |
+| `recommendation_issues` | Recommendation Issues |
+| `wrong_information` | Wrong / Inaccurate Information |
+| `tone_issues` | Tone Issues |
+| `similarity` | Similar To Previous Messages |
+| `other` | Other |
 
 ---
 
-## 🛠️ Development Guide
-
-### Adding a New Page
+## Supported Brands
 
-1. Create `pages/{number}_{Name}.py`
-2. Follow standard structure:
-```python
-import streamlit as st
-import os
-from pathlib import Path
-from dotenv import load_dotenv
+| Brand | Colour |
+| --- | --- |
+| Drumeo | Red `#E84545` |
+| Pianote | Blue `#4A90D9` |
+| Guitareo | Amber `#F5A623` |
+| Singeo | Purple `#7B68EE` |
+| Playbass | Green `#3DAA5C` |
 
-# Load .env
-env_path = Path(__file__).parent.parent.parent / '.env'
-if env_path.exists():
-    load_dotenv(env_path)
-
-from utils.auth import check_authentication
-from utils.theme import apply_theme, get_brand_emoji
-
-st.set_page_config(page_title="New Page", page_icon="🆕", layout="wide")
-
-if not check_authentication():
-    st.error("🔒 Please login first")
-    st.stop()
-
-if "selected_brand" not in st.session_state:
-    st.error("⚠️ Please select a brand first")
-    st.stop()
-
-brand = st.session_state.selected_brand
-apply_theme(brand)
-
-# Your content here
-```
-3. Update `app.py` navigation
-4. Test with all brands
-
-### Adding a New Feedback Category
-
-1. Update `utils/session_feedback_manager.py`:
-```python
-REJECTION_REASONS = {
-    # ... existing
-    "new_reason": "New Reason Label"
-}
-```
-2. Automatically appears in UI
-
-### Adding a New Brand
-
-1. Create `data/UI_users/{brand}_users.csv` (100 users, must have `USER_ID` column)
-2. Add to `utils/theme.py`:
-```python
-BRAND_THEMES["newbrand"] = {
-    "primary": "#COLOR",
-    "accent": "#COLOR",
-    "sidebar_bg": "#DARK_COLOR",
-    "text": "#FFFFFF"
-}
-BRAND_EMOJIS["newbrand"] = "🆕"
-```
-3. Update `app.py`:
-```python
-brands = ["drumeo", "pianote", "guitareo", "singeo", "newbrand"]
-brand_labels["newbrand"] = "🆕 New Brand"
+---
+
+## UI Flow
+
+```
+app.py (Login form)
+    ↓ authenticated
+app.py (Landing)
+    → pre-fetches top 150 messages per campaign from DAILY_PUSH_MESSAGES
+    → stores result in session_state["all_messages"]
+    → shows per-campaign counts
+    ↓ navigate to Message Viewer
+pages/1_Message_Viewer.py
+    Sidebar (instant, no Apply button):
+        Brand / Campaign / Scenario / "Only users with prev messages"
+        Reload button → clears cache, re-fetches
+    Sidebar:
+        Session stats: showing · rejected · reject %
+
+    Main area — paginated cards (20 per page):
+        Each card:
+        ┌─ Brand badge · Campaign · User #ID · Generated timestamp ──┐
+        │                                                             │
+        │  Push Notification Preview                                  │
+        │  [Header text]                                              │
+        │  [Body text]                                                │
+        │  Header: N chars · Body: N chars                           │
+        │                                                             │
+        │  ▼ User Context          (collapsible)                      │
+        │    First name · Daily streak · Weekly streak · Profile      │
+        │                                                             │
+        │  ▼ Previous Messages     (collapsible)                      │
+        │    Parsed from PREVIOUS_MESSAGES column — no extra query    │
+        │                                                             │
+        │  ▼ Last Interacted Content Profile  (collapsible)           │
+        │                                                             │
+        │  Feedback column:                                           │
+        │    [❌ Reject] → reason dropdown + optional note → Submit   │
+        │    Already rejected: shows reason · [✏️ Change] [Clear]    │
+        └─────────────────────────────────────────────────────────────┘
+    → Rejections saved to Snowflake on Submit
+    → No action = message is considered good
 ```
-4. Create default config in Snowflake or via UI
-
-### Debugging Tips
-
-**Common Issues**:
-
-1. **"No messages found"** in Message Viewer:
-   - Check `st.session_state.ui_log_data` exists
-   - Verify generation completed in Campaign Builder
-   - Look for errors in terminal
-
-2. **Snowflake connection errors**:
-   - Verify `.env` file exists and is loaded
-   - Check credentials are correct
-   - Test connection: `create_snowflake_session()`
-
-3. **AB test AttributeError**:
-   - Fixed in latest version
-   - Ensure ExperimentRunner uses thread-safe progress handling
-
-4. **Config save errors with quotes**:
-   - Fixed: Now uses `write_pandas()` instead of raw SQL
-   - Handles JSON with apostrophes correctly
-
-5. **Feedback not in Analytics**:
-   - Check `st.session_state.current_feedbacks` has data
-   - Verify correct feedback_list_key used
-   - Check experiment_id matches
-
-**Debugging Code**:
-```python
-# Debug session state
-with st.expander("Debug Info"):
-    st.write("Session State Keys:", list(st.session_state.keys()))
-    if 'ui_log_data' in st.session_state:
-        st.write("Messages shape:", st.session_state.ui_log_data.shape)
-    if 'current_feedbacks' in st.session_state:
-        st.write("Feedback count:", len(st.session_state.current_feedbacks))
-```
-
----
-
-## 🎯 Key Design Decisions
-
-### 1. In-Memory + Cloud Hybrid
-**Decision**: Use session_state for active data, Snowflake for persistence
-**Rationale**:
-- Fast in-memory operations
-- No local file dependencies (HuggingFace ready)
-- Scalable historical storage
-- Clean separation: current vs. historical
-
-### 2. One-Click Storage
-**Decision**: Single "Store Results" button to persist everything
-**Rationale**:
-- Simple user workflow
-- Explicit persistence action
-- User controls when data is saved
-- No auto-save surprises
-
-### 3. Config Caching
-**Decision**: Load all configs once, cache in session_state
-**Rationale**:
-- Reduces Snowflake queries
-- Faster config switching
-- Session-scoped cache (fresh on page load)
-- No stale data issues
-
-### 4. Thread-Safe AB Testing
-**Decision**: Separate Snowflake sessions per thread, console logging
-**Rationale**:
-- Prevents session conflicts
-- Streamlit UI only in main thread
-- Clean error handling
-- Production-ready parallel execution
-
-### 5. Versioned Configurations
-**Decision**: Auto-increment version on every config save
-**Rationale**:
-- Full audit trail
-- Can rollback to previous versions
-- Supports experimentation
-- No data loss
-
-### 6. Button-Triggered Historical Loading
-**Decision**: Historical Analytics loads on button click, not auto
-**Rationale**:
-- User controls when to query Snowflake
-- Avoids unnecessary queries
-- Faster page load
-- Clear user action
-
-### 7. SessionFeedbackManager Static Methods
-**Decision**: All methods static, no instance needed
-**Rationale**:
-- Simpler API
-- Works directly with session_state
-- No state to manage
-- Cleaner code
-
----
-
-## 🚀 Deployment Guide
-
-### HuggingFace Spaces Deployment
-
-**Requirements**:
-- No local file dependencies ✅
-- Environment variables for secrets ✅
-- Snowflake connectivity ✅
-- CSV files in repo (data/UI_users/) ✅
-
-**Steps**:
-1. Push code to GitHub/HuggingFace repo
-2. Include `data/UI_users/` CSV files
-3. Set environment variables in Space settings:
-   - All SNOWFLAKE_* variables
-   - All API keys
-4. Run: `streamlit run app.py`
-5. Verify Snowflake connection works
-
-**Files to Exclude**:
-- `.env` (use Space secrets instead)
-- Local cache directories
-- Test data
-
----
-
-## 📞 Support & Resources
-
-**Contact**:
-- Technical Support: danial@musora.com
-
-**Related Documentation**:
-- Main System: `ai_messaging_system_v2/README.md`
-- UI Mode Guide: `ai_messaging_system_v2/UI_MODE_GUIDE.md`
-- Implementation Details: `visualization/IMPLEMENTATION_COMPLETE.md`
-- Refactoring Guide: `visualization/ARCHITECTURE_REFACTOR_GUIDE.md`
-
-**Useful Links**:
-- Streamlit Documentation: https://docs.streamlit.io
-- Snowflake Python Connector: https://docs.snowflake.com/en/developer-guide/python-connector/python-connector
-- Plotly Charts: https://plotly.com/python/
-
----
-
-## 📊 System Status
-
-**Completion**: 100% ✅
-
-**Completed Components**:
-1. ✅ Database Layer (db_manager.py)
-2. ✅ Config Manager (config_manager.py)
-3. ✅ Session Feedback Manager (session_feedback_manager.py)
-4. ✅ Experiment Runner (experiment_runner.py)
-5. ✅ App.py - Authentication & config loading
-6. ✅ Campaign Builder - Generation & AB testing
-7. ✅ Message Viewer - Viewing & feedback
-8. ✅ Analytics - Current experiment metrics
-9. ✅ Historical Analytics - Snowflake integration
-
-**Recent Fixes**:
-- ✅ Configuration save error (JSON escaping) - Fixed with `write_pandas()`
-- ✅ AB testing `AttributeError: enter` - Fixed with thread-safe design
-- ✅ Historical Analytics Snowflake connection - Fixed to use `.env`
-
-**Ready For**:
-- ✅ Production use
-- ✅ HuggingFace deployment
-- ✅ End-to-end testing
-- ✅ Team onboarding
 
 ---
 
-**Built with ❤️ for the Musora team**
+## Module Responsibilities
 
-**Last Updated**: 2026-01-14
-**Version**: 2.0 (Refactored Architecture)
+| Module | Responsibility |
+| --- | --- |
+| `auth.py` | Session authentication, email allowlist, token verification |
+| `snowflake_client.py` | Single-table fetch from `DAILY_PUSH_MESSAGES`; feedback MERGE/DELETE |
+| `feedback_manager.py` | In-session rejection dict (fast cache), delegates writes to `snowflake_client` |
+| `theme.py` | Brand colours, campaign labels, scenario definitions and `detect_scenario()` |

app.py

@@ -1,19 +1,18 @@
 """
-Hugging Face Spaces wrapper for AI Messaging System Visualization Tool
-This wrapper imports and runs the main app from the visualization folder.
+Root entry point for HuggingFace Spaces deployment.
+Delegates to visualization/app.py without modifying any underlying code.
 """
 
 import sys
-from pathlib import Path
+import os
+import runpy
 
-# Add the visualization directory to Python path
-visualization_dir = Path(__file__).parent / "visualization"
-sys.path.insert(0, str(visualization_dir))
-sys.path.insert(0, str(Path(__file__).parent))
+_here = os.path.dirname(os.path.abspath(__file__))
+_viz = os.path.join(_here, "visualization")
 
-# Change to visualization directory context for relative imports
-import os
-os.chdir(visualization_dir)
+if _viz not in sys.path:
+    sys.path.insert(0, _viz)
+
+os.chdir(_viz)
 
-# Import and run the main app
-from visualization import app
+runpy.run_path(os.path.join(_viz, "app.py"), run_name="__main__")

pages/1_Message_Viewer.py

@@ -0,0 +1,18 @@
+"""
+Root-level page wrapper for HuggingFace Spaces deployment.
+Delegates to visualization/pages/1_Message_Viewer.py without modifying any underlying code.
+"""
+
+import sys
+import os
+import runpy
+
+_here = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+_viz = os.path.join(_here, "visualization")
+
+if _viz not in sys.path:
+    sys.path.insert(0, _viz)
+
+os.chdir(_viz)
+
+runpy.run_path(os.path.join(_viz, "pages", "1_Message_Viewer.py"), run_name="__main__")

requirements.txt

@@ -1,47 +1,10 @@
-# AI Messaging System - Combined Requirements for HuggingFace Space
-# Merges dependencies from both ai_messaging_system_v2 and visualization
+# AI Messaging System v3 - Visualization Tool Requirements
 
-# Core Dependencies
-numpy==1.26.4
-streamlit==1.46.0
-pandas==2.2.0
-python-dotenv==1.0.0
+# Core
+streamlit>=1.50.0
+pandas>=2.2.0
+python-dotenv>=1.0.0
 
-# Data Visualization
-plotly==6.5.1
-
-# Snowflake Integration
+# Snowflake (connector is bundled with snowpark; either works)
 snowflake-snowpark-python==1.19.0
 snowflake-connector-python==3.17.3
-pyarrow==21.0.0
-cloudpickle==2.2.1
-PyYAML==6.0.2
-
-# Date/Time Handling
-pytz==2025.2
-python-dateutil==2.9.0.post0
-tzdata==2025.2
-
-# AI/ML APIs
-openai==1.99.9
-google-genai==1.24.0
-anyio==4.10.0
-google-auth==2.40.3
-httpx==0.28.1
-pydantic==2.11.7
-tenacity==8.5.0
-websockets==15.0.1
-distro==1.9.0
-jiter==0.10.0
-sniffio==1.3.1
-
-# HTTP and Crypto Dependencies
-certifi==2025.8.3
-requests==2.32.5
-urllib3==1.26.20
-cryptography==45.0.7
-pyOpenSSL==25.1.0
-cffi==1.17.1
-
-# Utility Libraries
-tqdm==4.66.4

visualization/.gitignore

@@ -0,0 +1,57 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+env/
+venv/
+ENV/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Data files (local storage)
+data/configs/*.json
+data/feedback/*.csv
+data/experiments/*.json
+data/users/*.csv
+
+# Keep directory structure but ignore contents
+!data/configs/.gitkeep
+!data/feedback/.gitkeep
+!data/experiments/.gitkeep
+!data/users/.gitkeep
+
+# Environment variables
+.env
+.env.local
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Streamlit
+.streamlit/secrets.toml
+
+# Logs
+*.log

visualization/README.md

@@ -0,0 +1,243 @@
+---
+title: AI Messaging System
+emoji: 🎶
+colorFrom: blue
+colorTo: gray
+sdk: streamlit
+sdk_version: 1.50.0
+python_version: 3.9
+app_file: app.py
+---
+
+
+# AI Messaging System v3 — Visualization Tool
+
+A Streamlit tool for reviewing and evaluating AI-generated push notification messages. All data is read from a single output table — no joins. Reviewers filter messages by brand, campaign, and scenario, inspect user context stored at generation time, and flag any message that has issues. Rejections are persisted to Snowflake. No action on a message means it is good.
+
+This tool does **not** generate messages. It is purely for reviewing messages already produced by the v3 pipeline.
+
+---
+
+## Purpose
+
+- Pre-fetch the most recent 150 messages per campaign on login (single query, no joins)
+- Filter instantly by brand, campaign, and scenario — all client-side, no extra DB queries
+- View the user context captured at generation time (streaks, profile, previous messages, last interacted content)
+- Reject messages with a structured reason — persisted to Snowflake immediately
+- Track rejection counts per review session in the sidebar
+
+---
+
+## Directory Structure
+
+```
+visualization/
+├── app.py                          # Entry point: login + data pre-fetch on authentication
+├── pages/
+│   └── 1_Message_Viewer.py         # Message cards, filters, user context, rejection UI
+├── utils/
+│   ├── auth.py                     # Login / session authentication
+│   ├── snowflake_client.py         # Snowflake reads (single table) and feedback writes
+│   ├── feedback_manager.py         # In-session rejection state + Snowflake persistence
+│   ├── theme.py                    # Brand colours, campaign labels, scenario definitions
+│   └── __init__.py
+├── requirements.txt
+├── .env                            # Credentials (not committed)
+├── .env.example
+└── README.md
+```
+
+---
+
+## Getting Started
+
+### 1. Install dependencies
+
+```bash
+pip install -r requirements.txt
+```
+
+### 2. Configure credentials
+
+Copy `.env.example` to `.env` and fill in your Snowflake credentials and the app token:
+
+```
+SNOWFLAKE_USER     = ...
+SNOWFLAKE_PASSWORD = ...
+SNOWFLAKE_ACCOUNT  = ...
+SNOWFLAKE_ROLE     = ACCOUNTADMIN
+SNOWFLAKE_DATABASE = RECSYS_V3
+SNOWFLAKE_WAREHOUSE= COMPUTE_WH
+SNOWFLAKE_SCHEMA   = PUBLIC
+APP_TOKEN          = ...
+```
+
+### 3. Run the app
+
+```bash
+cd ai_messaging_system_v3/visualization
+streamlit run app.py
+```
+
+---
+
+## Authentication
+
+Login requires an email from the authorised list and a shared access token (`APP_TOKEN` in `.env`). Authorised emails are defined in `utils/auth.py`.
+
+---
+
+## Snowflake Tables
+
+### Input (read-only) — single table, no joins
+
+All data needed for display and filtering is stored at message generation time in one table.
+
+**`MESSAGING_SYSTEM_V2.GENERATED_DATA.DAILY_PUSH_MESSAGES`**
+
+| Column | Type | Description |
+| --- | --- | --- |
+| `USER_ID` | NUMBER | Target user |
+| `DETECTED_BRAND` | VARCHAR | Brand: `drumeo`, `pianote`, `guitareo`, `singeo`, `playbass` |
+| `BRANCH` | VARCHAR | Campaign routing key (mirrors `CAMPAIGN_NAME`) |
+| `MESSAGE` | VARCHAR | JSON string `{"header": "...", "message": "..."}` — parsed into header + body |
+| `PLATFORM` | VARCHAR | Delivery platform (e.g. `push`) |
+| `CAMPAIGN_NAME` | VARCHAR | `dailyPush_dailyStreak`, `dailyPush_weeklyStreak`, `dailyPush_noStreak` |
+| `TIMESTAMP` | TIMESTAMP | Generation timestamp |
+| `RECOMMENDATION` | VARCHAR | Recommendation type; `for_you` means no specific recommendation (used for scenario detection) |
+| `RECOMMENDED_CONTENT_ID` | NUMBER | Content ID linked in the message (if any) |
+| `FIRST_NAME` | VARCHAR | User's first name at generation time |
+| `CURRENT_DAILY_STREAK_LENGTH` | NUMBER | Daily streak at generation time |
+| `CURRENT_WEEKLY_STREAK_LENGTH` | NUMBER | Weekly streak at generation time |
+| `USER_PROFILE` | VARCHAR | User profile text used for personalisation |
+| `PREVIOUS_MESSAGES` | VARCHAR | JSON snapshot of prior messages for this user |
+| `LAST_INTERACTED_CONTENT_PROFILE` | VARCHAR | Profile of the last content the user interacted with |
+
+### Output (written by this tool)
+
+**`MESSAGING_SYSTEM_V2.UI.V3_FEEDBACKS`** — created automatically on first run.
+
+| Column | Description |
+| --- | --- |
+| `BATCH_ID` | UUID generated per review session |
+| `USER_ID` | Reviewed user |
+| `CAMPAIGN_NAME` | Campaign of the reviewed message |
+| `BRAND` | Brand of the reviewed user |
+| `REJECTION_REASON` | Category key (see Rejection Reasons) |
+| `REJECTION_TEXT` | Optional free-text note from the reviewer |
+| `MESSAGE_HEADER` | Full header at time of review |
+| `MESSAGE_BODY` | Full body at time of review |
+| `MESSAGE_TIMESTAMP` | When the message was originally generated |
+| `REVIEWER_EMAIL` | Email of the reviewer |
+| `TIMESTAMP` | When the rejection was submitted |
+
+Rejections are upserted via `MERGE` — changing the reason on an already-rejected message updates the existing row.
+
+Users with any existing rejection in `V3_FEEDBACKS` are **excluded** from the pre-fetch query, so the same message is never shown twice across sessions.
+
+---
+
+## Filters
+
+All filters are applied instantly client-side on the pre-loaded DataFrame — no Snowflake query is triggered on filter change.
+
+| Filter | Source column | Notes |
+| --- | --- | --- |
+| Brand | `DETECTED_BRAND` | All, Drumeo, Pianote, Guitareo, Singeo, Playbass |
+| Campaign | `CAMPAIGN_NAME` | All, Daily Streak, Weekly Streak, No Streak |
+| Scenario | `RECOMMENDATION` | Weekly Streak campaign only (see Scenarios) |
+| Only users with previous messages | `HAS_PREVIOUS` | Pre-computed at fetch time via `COUNT(*) > 1` |
+
+---
+
+## Campaigns and Scenarios
+
+| Campaign | Scenario key | Display label | Detection |
+| --- | --- | --- | --- |
+| `dailyPush_dailyStreak` | — | — | No sub-scenarios |
+| `dailyPush_weeklyStreak` | `no_practice_this_week` | No Practice This Week | `RECOMMENDATION == 'for_you'` |
+| `dailyPush_weeklyStreak` | `practiced_this_week` | Practiced This Week | `RECOMMENDATION != 'for_you'` |
+| `dailyPush_noStreak` | — | — | No sub-scenarios |
+
+---
+
+## Rejection Reason Categories
+
+| Key | Label |
+| --- | --- |
+| `poor_header` | Poor Header |
+| `poor_body` | Poor Body / Content |
+| `grammar_issues` | Grammar Issues |
+| `emoji_problems` | Emoji Problems |
+| `recommendation_issues` | Recommendation Issues |
+| `wrong_information` | Wrong / Inaccurate Information |
+| `tone_issues` | Tone Issues |
+| `similarity` | Similar To Previous Messages |
+| `other` | Other |
+
+---
+
+## Supported Brands
+
+| Brand | Colour |
+| --- | --- |
+| Drumeo | Red `#E84545` |
+| Pianote | Blue `#4A90D9` |
+| Guitareo | Amber `#F5A623` |
+| Singeo | Purple `#7B68EE` |
+| Playbass | Green `#3DAA5C` |
+
+---
+
+## UI Flow
+
+```
+app.py (Login form)
+    ↓ authenticated
+app.py (Landing)
+    → pre-fetches top 150 messages per campaign from DAILY_PUSH_MESSAGES
+    → stores result in session_state["all_messages"]
+    → shows per-campaign counts
+    ↓ navigate to Message Viewer
+pages/1_Message_Viewer.py
+    Sidebar (instant, no Apply button):
+        Brand / Campaign / Scenario / "Only users with prev messages"
+        Reload button → clears cache, re-fetches
+    Sidebar:
+        Session stats: showing · rejected · reject %
+
+    Main area — paginated cards (20 per page):
+        Each card:
+        ┌─ Brand badge · Campaign · User #ID · Generated timestamp ──┐
+        │                                                             │
+        │  Push Notification Preview                                  │
+        │  [Header text]                                              │
+        │  [Body text]                                                │
+        │  Header: N chars · Body: N chars                           │
+        │                                                             │
+        │  ▼ User Context          (collapsible)                      │
+        │    First name · Daily streak · Weekly streak · Profile      │
+        │                                                             │
+        │  ▼ Previous Messages     (collapsible)                      │
+        │    Parsed from PREVIOUS_MESSAGES column — no extra query    │
+        │                                                             │
+        │  ▼ Last Interacted Content Profile  (collapsible)           │
+        │                                                             │
+        │  Feedback column:                                           │
+        │    [❌ Reject] → reason dropdown + optional note → Submit   │
+        │    Already rejected: shows reason · [✏️ Change] [Clear]    │
+        └─────────────────────────────────────────────────────────────┘
+    → Rejections saved to Snowflake on Submit
+    → No action = message is considered good
+```
+
+---
+
+## Module Responsibilities
+
+| Module | Responsibility |
+| --- | --- |
+| `auth.py` | Session authentication, email allowlist, token verification |
+| `snowflake_client.py` | Single-table fetch from `DAILY_PUSH_MESSAGES`; feedback MERGE/DELETE |
+| `feedback_manager.py` | In-session rejection dict (fast cache), delegates writes to `snowflake_client` |
+| `theme.py` | Brand colours, campaign labels, scenario definitions and `detect_scenario()` |

visualization/app.py

@@ -0,0 +1,140 @@
+"""
+AI Messaging System v3 — Visualization Tool
+Entry point: Login + data pre-fetch on authentication.
+"""
+
+import streamlit as st
+
+st.set_page_config(
+    page_title="Messaging Viewer",
+    page_icon="💬",
+    layout="wide",
+    initial_sidebar_state="expanded",
+)
+
+from utils.auth import check_authentication, verify_login, logout, get_current_user
+from utils.theme import inject_global_css
+from utils import snowflake_client as sf
+from utils import feedback_manager as fm
+
+inject_global_css()
+
+
+# ---------------------------------------------------------------------------
+# Login gate
+# ---------------------------------------------------------------------------
+
+def show_login():
+    col1, col2, col3 = st.columns([1, 2, 1])
+    with col2:
+        st.markdown("## 💬 Messaging Viewer")
+        st.markdown("Sign in to review AI-generated push notification messages.")
+        st.markdown("---")
+
+        with st.form("login_form"):
+            email = st.text_input("Email", placeholder="you@musora.com")
+            token = st.text_input("Access Token", type="password")
+            submitted = st.form_submit_button("Sign In", use_container_width=True)
+
+        if submitted:
+            if verify_login(email, token):
+                st.session_state["authenticated"] = True
+                st.session_state["user_email"] = email.lower().strip()
+                st.rerun()
+            else:
+                st.error("Invalid email or token. Please try again.")
+
+
+# ---------------------------------------------------------------------------
+# Data pre-fetch (runs once after login, cached in session_state)
+# ---------------------------------------------------------------------------
+
+def prefetch_messages():
+    """
+    Load top 150 messages per campaign for all campaigns in a single query.
+    Stores the result in session_state["all_messages"] so every page can
+    filter client-side without additional Snowflake round-trips.
+    Skips fetch if data is already cached in this session.
+    """
+    if "all_messages" in st.session_state:
+        return  # already loaded
+
+    with st.spinner("Loading messages…"):
+        try:
+            sf.ensure_feedback_table()
+            df = sf.fetch_all_messages()
+            st.session_state["all_messages"] = df
+        except Exception as e:
+            st.error(f"Failed to load messages: {e}")
+
+
+# ---------------------------------------------------------------------------
+# Main app (authenticated)
+# ---------------------------------------------------------------------------
+
+def show_home():
+    user = get_current_user()
+
+    with st.sidebar:
+        st.markdown(f"**Signed in as:** {user}")
+        if st.button("Sign Out", use_container_width=True):
+            logout()
+            fm.reset_session()
+            st.session_state.pop("all_messages", None)
+            st.rerun()
+        if st.button("Reload Data", use_container_width=True, help="Re-fetch messages from Snowflake"):
+            st.session_state.pop("all_messages", None)
+            fm.reset_session()
+            st.rerun()
+
+    # Pre-fetch data as soon as the user lands on the home page
+    prefetch_messages()
+
+    df = st.session_state.get("all_messages")
+    total = len(df) if df is not None else 0
+
+    st.markdown("## 💬 Messaging Viewer")
+    st.markdown(
+        "Browse AI-generated push notifications, inspect user context, "
+        "and flag messages that need improvement."
+    )
+    st.markdown("---")
+
+    if df is not None and not df.empty:
+        campaigns = df["CAMPAIGN_NAME"].value_counts().to_dict()
+        cols = st.columns(len(campaigns) + 1)
+        cols[0].metric("Total loaded", total)
+        for i, (camp, count) in enumerate(campaigns.items(), 1):
+            cols[i].metric(camp.replace("dailyPush_", ""), count)
+        st.markdown("---")
+
+    st.markdown("### How to use")
+    c1, c2, c3 = st.columns(3)
+    with c1:
+        st.markdown("**1. Open Message Viewer**")
+        st.markdown("Navigate to the Message Viewer page using the sidebar.")
+    with c2:
+        st.markdown("**2. Filter instantly**")
+        st.markdown(
+            "Use the sidebar filters (brand, campaign, scenario) to narrow down "
+            "messages. Changes apply immediately — no Apply button needed."
+        )
+    with c3:
+        st.markdown("**3. Review & reject**")
+        st.markdown(
+            "Read each message with its user context. Click **Reject** and pick "
+            "a reason for any message that has issues. No action = message is good."
+        )
+
+    st.markdown("---")
+    st.page_link("pages/1_Message_Viewer.py", label="Open Message Viewer →", icon="💬")
+
+
+# ---------------------------------------------------------------------------
+# Router
+# ---------------------------------------------------------------------------
+
+if not check_authentication():
+    show_login()
+else:
+    show_home()

visualization/pages/1_Message_Viewer.py

@@ -0,0 +1,533 @@
+"""
+Message Viewer page.
+
+Displays the chronological sequence of push notifications per user.
+Each user has up to 3 messages (oldest → newest).
+
+Sidebar view-mode controls how many columns are shown per card:
+  1 — oldest message only  (default)
+  2 — oldest + 2nd message side by side
+  3 — all three messages side by side
+
+All data comes from session_state["all_messages"] pre-fetched at login.
+Filters (brand, campaign, scenario, min messages) apply instantly client-side.
+Rejections are per user and persisted to Snowflake on submit.
+"""
+
+import streamlit as st
+import pandas as pd
+import json
+
+st.set_page_config(
+    page_title="Message Viewer",
+    page_icon="💬",
+    layout="wide",
+    initial_sidebar_state="expanded",
+)
+
+from utils.auth import check_authentication, get_current_user, logout
+from utils.theme import (
+    inject_global_css, get_brand, get_campaign_label,
+    ALL_BRANDS, ALL_CAMPAIGNS, get_scenarios, detect_scenario,
+)
+from utils import snowflake_client as sf
+from utils import feedback_manager as fm
+
+inject_global_css()
+
+# ---------------------------------------------------------------------------
+# Auth guard
+# ---------------------------------------------------------------------------
+
+if not check_authentication():
+    st.warning("Please sign in on the Home page.")
+    st.stop()
+
+user_email = get_current_user()
+
+# ---------------------------------------------------------------------------
+# Ensure data is loaded (fallback if user navigates here directly)
+# ---------------------------------------------------------------------------
+
+if "all_messages" not in st.session_state:
+    with st.spinner("Loading messages…"):
+        try:
+            sf.ensure_feedback_table()
+            st.session_state["all_messages"] = sf.fetch_all_messages()
+        except Exception as e:
+            st.error(f"Failed to load messages: {e}")
+            st.stop()
+
+df_all: pd.DataFrame = st.session_state["all_messages"]
+
+PAGE_SIZE = 15  # users per page (each user can span up to 3 columns)
+
+# ---------------------------------------------------------------------------
+# Sidebar
+# ---------------------------------------------------------------------------
+
+with st.sidebar:
+    st.markdown(f"**{user_email}**")
+
+    col_so, col_rl = st.columns(2)
+    with col_so:
+        if st.button("Sign Out", use_container_width=True):
+            logout()
+            fm.reset_session()
+            st.session_state.pop("all_messages", None)
+            st.rerun()
+    with col_rl:
+        if st.button("Reload", use_container_width=True, help="Re-fetch from Snowflake"):
+            st.session_state.pop("all_messages", None)
+            fm.reset_session()
+            st.session_state.pop("mv_page", None)
+            st.rerun()
+
+    st.markdown("---")
+    st.markdown("### View")
+
+    view_mode = st.radio(
+        "Messages to display per user",
+        options=[1, 2, 3],
+        format_func=lambda n: {
+            1: "First message only",
+            2: "First + 2nd message",
+            3: "All 3 messages",
+        }[n],
+        key="mv_view_mode",
+    )
+
+    st.markdown("---")
+    st.markdown("### Filters")
+
+    selected_brand = st.selectbox(
+        "Brand",
+        options=ALL_BRANDS,
+        format_func=lambda b: get_brand(b)["label"],
+        key="mv_brand",
+    )
+
+    selected_campaign = st.selectbox(
+        "Campaign",
+        options=ALL_CAMPAIGNS,
+        format_func=get_campaign_label,
+        key="mv_campaign",
+    )
+
+    scenarios = get_scenarios(selected_campaign)
+    selected_scenario = "all"
+    if scenarios:
+        scenario_keys   = [s[0] for s in scenarios]
+        scenario_labels = {s[0]: s[1] for s in scenarios}
+        selected_scenario = st.selectbox(
+            "Scenario",
+            options=scenario_keys,
+            format_func=lambda k: scenario_labels[k],
+            key="mv_scenario",
+        )
+
+    min_msgs = st.checkbox(
+        f"Only users with ≥ {view_mode} message(s)",
+        value=False,
+        key="mv_min_msgs",
+        help="Hide users who have fewer messages than the selected view mode",
+    )
+
+    # Reset to page 0 on any filter / view change
+    filter_sig = (selected_brand, selected_campaign, selected_scenario, min_msgs, view_mode)
+    if st.session_state.get("_filter_sig") != filter_sig:
+        st.session_state["mv_page"] = 0
+        st.session_state["_filter_sig"] = filter_sig
+
+    st.markdown("---")
+    st.markdown("### Session Stats")
+    stats_placeholder = st.empty()
+
+
+# ---------------------------------------------------------------------------
+# Client-side filtering
+# ---------------------------------------------------------------------------
+
+# Work only on the rank-1 (oldest) rows to decide which users to show
+df_primary = df_all[df_all["MSG_RANK"] == 1].copy()
+
+if selected_brand != "all":
+    df_primary = df_primary[df_primary["DETECTED_BRAND"] == selected_brand.lower()]
+
+if selected_campaign != "all":
+    df_primary = df_primary[df_primary["CAMPAIGN_NAME"] == selected_campaign]
+
+if (
+    selected_scenario != "all"
+    and selected_campaign == "dailyPush_weeklyStreak"
+    and "RECOMMENDATION" in df_primary.columns
+):
+    df_primary = df_primary[
+        df_primary["RECOMMENDATION"].apply(detect_scenario) == selected_scenario
+    ]
+
+if min_msgs:
+    df_primary = df_primary[df_primary["USER_MSG_COUNT"] >= view_mode]
+
+# Ordered list of USER_IDs to display
+user_ids_ordered = df_primary["USER_ID"].tolist()
+total_users = len(user_ids_ordered)
+
+# ---------------------------------------------------------------------------
+# Sidebar stats
+# ---------------------------------------------------------------------------
+
+stats = fm.get_stats(total_users)
+with stats_placeholder.container():
+    st.metric("Users shown", total_users)
+    st.metric("Rejected ❌", stats["total_rejected"])
+    if total_users:
+        st.progress(
+            stats["total_rejected"] / total_users,
+            text=f"{stats['reject_rate']}% rejected",
+        )
+
+# ---------------------------------------------------------------------------
+# Page header
+# ---------------------------------------------------------------------------
+
+b_cfg = get_brand(selected_brand)
+view_labels = {1: "First message", 2: "First 2 messages", 3: "All 3 messages"}
+st.markdown(f"## {b_cfg['emoji']} Message Viewer")
+st.caption(
+    f"Brand: **{b_cfg['label']}** · "
+    f"Campaign: **{get_campaign_label(selected_campaign)}** · "
+    f"{total_users} users · Showing: **{view_labels[view_mode]}**"
+)
+st.markdown("---")
+
+if not user_ids_ordered:
+    st.info("No messages match the current filters.")
+    st.stop()
+
+# ---------------------------------------------------------------------------
+# Pagination (per user, not per row)
+# ---------------------------------------------------------------------------
+
+total_pages = max(1, (total_users + PAGE_SIZE - 1) // PAGE_SIZE)
+if "mv_page" not in st.session_state:
+    st.session_state["mv_page"] = 0
+page = min(st.session_state["mv_page"], total_pages - 1)
+st.session_state["mv_page"] = page
+
+pc1, pc2, pc3 = st.columns([1, 3, 1])
+with pc1:
+    if st.button("← Prev", disabled=page == 0, key="prev_top"):
+        st.session_state["mv_page"] = page - 1
+        st.rerun()
+with pc2:
+    st.markdown(
+        f"<p style='text-align:center;color:#666;margin:6px 0'>"
+        f"Page {page + 1} of {total_pages}</p>",
+        unsafe_allow_html=True,
+    )
+with pc3:
+    if st.button("Next →", disabled=page >= total_pages - 1, key="next_top"):
+        st.session_state["mv_page"] = page + 1
+        st.rerun()
+
+page_user_ids = user_ids_ordered[page * PAGE_SIZE : (page + 1) * PAGE_SIZE]
+
+# Pre-slice all rows for users on this page
+page_df = df_all[df_all["USER_ID"].isin(page_user_ids)].copy()
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _val(v):
+    if v is None:
+        return None
+    try:
+        if pd.isna(v):
+            return None
+    except (TypeError, ValueError):
+        pass
+    return v
+
+
+def _parse_previous_messages(raw) -> list:
+    if not raw:
+        return []
+    try:
+        parsed = json.loads(str(raw))
+        if isinstance(parsed, list):
+            return parsed
+        if isinstance(parsed, dict):
+            return [
+                {"date": k, **v} if isinstance(v, dict) else {"date": k, "text": str(v)}
+                for k, v in parsed.items()
+            ]
+    except Exception:
+        pass
+    return [{"text": str(raw)}]
+
+
+def _parse_recommendation(raw) -> dict:
+    """
+    Parse the RECOMMENDATION column into a dict.
+    Returns {} if the value is missing, 'for_you', or not valid JSON.
+    """
+    if not raw:
+        return {}
+    s = str(raw).strip()
+    if s.lower() == "for_you":
+        return {}
+    try:
+        parsed = json.loads(s)
+        if isinstance(parsed, dict):
+            return parsed
+    except Exception:
+        pass
+    return {}
+
+
+def _render_recommendation(raw):
+    """
+    Display a recommendation card: thumbnail image + clickable title.
+    Renders nothing if there is no recommendation or it is 'for_you'.
+    """
+    rec = _parse_recommendation(raw)
+    if not rec:
+        return
+    title      = rec.get("title", "")
+    url        = rec.get("web_url_path", "")
+    thumb_url  = rec.get("thumbnail_url", "")
+
+    if thumb_url:
+        st.image(thumb_url, width=140)
+    if title and url:
+        st.markdown(f"[{title}]({url})")
+    elif title:
+        st.markdown(f"**{title}**")
+
+
+def _notification_box(header: str, body: str, border_color: str, label: str):
+    """Render a single push notification preview box with a column label."""
+    st.markdown(
+        f"<p style='font-size:11px;font-weight:700;text-transform:uppercase;"
+        f"letter-spacing:.06em;color:#999;margin-bottom:4px;'>{label}</p>",
+        unsafe_allow_html=True,
+    )
+    st.markdown(
+        f"""<div class="msg-preview" style="border-left-color:{border_color};">
+            <p class="msg-header-text">{header}</p>
+            <p class="msg-body-text">{body}</p>
+        </div>""",
+        unsafe_allow_html=True,
+    )
+    st.caption(f"Header: {len(header)} chars · Body: {len(body)} chars")
+
+
+# ---------------------------------------------------------------------------
+# Message cards — one card per user
+# ---------------------------------------------------------------------------
+
+col_labels = ["1st message (oldest)", "2nd message", "3rd message (latest)"]
+
+for user_id in page_user_ids:
+    user_rows = (
+        page_df[page_df["USER_ID"] == user_id]
+        .sort_values("MSG_RANK")
+        .reset_index(drop=True)
+    )
+
+    # All data for shared sections comes from the oldest (rank-1) row
+    base = user_rows.iloc[0]
+
+    brand_name   = str(_val(base.get("DETECTED_BRAND")) or "").lower()
+    campaign     = str(_val(base.get("CAMPAIGN_NAME")) or "")
+    msg_ts       = _val(base.get("TIMESTAMP"))
+    first_name   = str(_val(base.get("FIRST_NAME")) or "")
+    daily_streak = _val(base.get("CURRENT_DAILY_STREAK_LENGTH"))
+    weekly_streak= _val(base.get("CURRENT_WEEKLY_STREAK_LENGTH"))
+    user_profile = str(_val(base.get("USER_PROFILE")) or "")
+    prev_msgs_raw  = _val(base.get("PREVIOUS_MESSAGES"))
+    last_int       = str(_val(base.get("LAST_INTERACTED_CONTENT_PROFILE")) or "")
+    user_msg_count = int(_val(base.get("USER_MSG_COUNT")) or 1)
+
+    card_brand   = get_brand(brand_name)
+    border_color = card_brand["color"]
+    existing_rej = fm.get_rejection(user_id)
+
+    ts_str = str(msg_ts)[:16] if msg_ts else "—"
+
+    # Badge strip
+    st.markdown(
+        f"""<div style="border-left:5px solid {border_color};border-radius:4px;
+            background:{card_brand['light']};padding:3px 12px;margin-bottom:4px;
+            display:flex;justify-content:space-between;align-items:center;">
+            <span>
+                <span style="font-size:13px;font-weight:700;color:{border_color};">
+                    {card_brand['emoji']} {card_brand['label'].upper()}
+                </span>
+                &nbsp;
+                <span style="font-size:12px;color:#666;">{get_campaign_label(campaign)}</span>
+                &nbsp;·&nbsp;
+                <span style="font-size:12px;color:#888;">User #{user_id}</span>
+                &nbsp;·&nbsp;
+                <span style="font-size:12px;color:#aaa;">{user_msg_count} message(s) in sequence</span>
+            </span>
+            <span style="font-size:12px;color:#999;">{ts_str}</span>
+        </div>""",
+        unsafe_allow_html=True,
+    )
+
+    with st.container(border=True):
+
+        # ── Notification columns ─────────────────────────────────────────
+        n_cols = min(view_mode, user_msg_count)
+        notif_cols = st.columns(n_cols)
+
+        for col_idx, col in enumerate(notif_cols):
+            row = user_rows.iloc[col_idx]
+            header     = str(_val(row.get("MESSAGE_HEADER")) or "")
+            body       = str(_val(row.get("MESSAGE_BODY")) or "")
+            row_rec    = _val(row.get("RECOMMENDATION"))
+            with col:
+                _notification_box(header, body, border_color, col_labels[col_idx])
+                _render_recommendation(row_rec)
+
+        st.markdown("---")
+
+        # ── Shared context + feedback ────────────────────────────────────
+        ctx_col, fb_col = st.columns([2, 1])
+
+        with ctx_col:
+            # User Context
+            with st.expander("👤 User Context"):
+                has_ctx = False
+                if first_name:
+                    st.markdown(f"**First name:** {first_name}")
+                    has_ctx = True
+                if daily_streak is not None:
+                    st.markdown(f"**Current daily streak:** {int(daily_streak)} days")
+                    has_ctx = True
+                if weekly_streak is not None:
+                    st.markdown(f"**Current weekly streak:** {int(weekly_streak)} weeks")
+                    has_ctx = True
+                if user_profile:
+                    st.markdown("**User profile:**")
+                    st.text(user_profile)
+                    has_ctx = True
+                if not has_ctx:
+                    st.caption("No user context stored for this message.")
+
+            # Previous Messages (snapshot stored at generation time)
+            with st.expander("📜 Previous Messages (at generation time)"):
+                prev_msgs = _parse_previous_messages(prev_msgs_raw)
+                if not prev_msgs:
+                    st.caption("No previous messages recorded.")
+                else:
+                    for pm in prev_msgs:
+                        date_label = pm.get("date", "")
+                        pm_header  = pm.get("header", pm.get("text", ""))
+                        pm_body    = pm.get("message", pm.get("body", ""))
+                        if date_label:
+                            st.markdown(f"**{date_label}**")
+                        if pm_header:
+                            st.markdown(f"> **{pm_header}**")
+                        if pm_body:
+                            st.markdown(f"> {pm_body}")
+                        st.markdown("")
+
+            if last_int:
+                with st.expander("🎵 Last Interacted Content Profile"):
+                    st.text(last_int)
+
+        # ── Feedback ─────────────────────────────────────────────────────
+        with fb_col:
+            st.markdown('<p class="section-label">Feedback</p>', unsafe_allow_html=True)
+            st.caption("No action = sequence is good.")
+
+            if existing_rej:
+                reason_label = fm.get_rejection_label(
+                    existing_rej.get("rejection_reason") or "other"
+                )
+                st.error(f"❌ Rejected\n\n_{reason_label}_")
+                if existing_rej.get("rejection_text"):
+                    st.caption(existing_rej["rejection_text"])
+
+            if not st.session_state.get(f"rejecting_{user_id}"):
+                btn_label = "❌ Reject" if not existing_rej else "✏️ Change Reason"
+                if st.button(btn_label, key=f"open_{user_id}", use_container_width=True):
+                    st.session_state[f"rejecting_{user_id}"] = True
+                    st.rerun()
+
+            if st.session_state.get(f"rejecting_{user_id}"):
+                with st.form(key=f"form_{user_id}"):
+                    reason_keys   = list(fm.REJECTION_REASONS.keys())
+                    reason_labels = [fm.get_rejection_label(k) for k in reason_keys]
+
+                    default_idx = 0
+                    if existing_rej and existing_rej.get("rejection_reason") in reason_keys:
+                        default_idx = reason_keys.index(existing_rej["rejection_reason"])
+
+                    sel_reason = st.selectbox(
+                        "Reason",
+                        options=range(len(reason_keys)),
+                        format_func=lambda i: reason_labels[i],
+                        index=default_idx,
+                    )
+                    extra_text = st.text_input(
+                        "Additional notes (optional)",
+                        value=existing_rej.get("rejection_text") or "" if existing_rej else "",
+                    )
+                    c1, c2 = st.columns(2)
+                    with c1:
+                        submit_rej = st.form_submit_button("Submit", use_container_width=True)
+                    with c2:
+                        cancel_rej = st.form_submit_button("Cancel", use_container_width=True)
+
+                if submit_rej:
+                    fm.set_rejection(
+                        user_id=user_id,
+                        rejection_reason=reason_keys[sel_reason],
+                        rejection_text=extra_text.strip() or None,
+                        campaign_name=campaign,
+                        brand=brand_name,
+                        message_header=str(_val(user_rows.iloc[0].get("MESSAGE_HEADER")) or ""),
+                        message_body=str(_val(user_rows.iloc[0].get("MESSAGE_BODY")) or ""),
+                        message_timestamp=msg_ts,
+                        reviewer_email=user_email,
+                    )
+                    st.session_state.pop(f"rejecting_{user_id}", None)
+                    st.rerun()
+
+                if cancel_rej:
+                    st.session_state.pop(f"rejecting_{user_id}", None)
+                    st.rerun()
+
+            if existing_rej and not st.session_state.get(f"rejecting_{user_id}"):
+                if st.button("Clear rejection", key=f"clear_{user_id}", use_container_width=True):
+                    fm.clear_rejection(user_id)
+                    st.rerun()
+
+    st.markdown("")
+
+
+# ---------------------------------------------------------------------------
+# Bottom pagination
+# ---------------------------------------------------------------------------
+
+st.markdown("---")
+bp1, bp2, bp3 = st.columns([1, 3, 1])
+with bp1:
+    if st.button("← Prev", disabled=page == 0, key="prev_bot"):
+        st.session_state["mv_page"] = page - 1
+        st.rerun()
+with bp2:
+    st.markdown(
+        f"<p style='text-align:center;color:#666'>Page {page + 1} of {total_pages}</p>",
+        unsafe_allow_html=True,
+    )
+with bp3:
+    if st.button("Next →", disabled=page >= total_pages - 1, key="next_bot"):
+        st.session_state["mv_page"] = page + 1
+        st.rerun()

visualization/requirements.txt

@@ -0,0 +1,10 @@
+# AI Messaging System v3 - Visualization Tool Requirements
+
+# Core
+streamlit>=1.50.0
+pandas>=2.2.0
+python-dotenv>=1.0.0
+
+# Snowflake (connector is bundled with snowpark; either works)
+snowflake-snowpark-python==1.19.0
+snowflake-connector-python==3.17.3

visualization/utils/auth.py

@@ -0,0 +1,101 @@
+"""
+Authentication module for the AI Messaging System Visualization Tool.
+
+Handles user authentication and access control.
+"""
+
+import os
+import streamlit as st
+from pathlib import Path
+from dotenv import load_dotenv
+
+# Load environment variables from .env file in visualization directory
+env_path = Path(__file__).parent.parent / '.env'
+if env_path.exists():
+    load_dotenv(env_path)
+else:
+    # Try parent directory .env
+    parent_env_path = Path(__file__).parent.parent.parent / '.env'
+    if parent_env_path.exists():
+        load_dotenv(parent_env_path)
+
+# Authorized emails - team members only
+AUTHORIZED_EMAILS = {
+    "danial@musora.com",
+    "danial.ebrat@gmail.com",
+    "simon@musora.com",
+    "una@musora.com",
+    "mark@musora.com",
+    "gabriel@musora.com",
+    "nikki@musora.com"
+}
+
+
+def get_credential(key: str) -> str:
+    """
+    Get credential from environment variables.
+
+    Args:
+        key: Credential key
+
+    Returns:
+        str: Credential value
+    """
+    return os.getenv(key, "")
+
+
+def get_valid_token() -> str:
+    """
+    Get the valid access token from environment.
+
+    Returns:
+        str: Valid access token
+    """
+    return get_credential("APP_TOKEN")
+
+
+def verify_login(email: str, token: str) -> bool:
+    """
+    Verify user login credentials.
+
+    Args:
+        email: User email address
+        token: Access token
+
+    Returns:
+        bool: True if credentials are valid, False otherwise
+    """
+    valid_token = get_valid_token()
+    email_normalized = email.lower().strip()
+
+    return (email_normalized in AUTHORIZED_EMAILS) and (token == valid_token)
+
+
+def check_authentication() -> bool:
+    """
+    Check if user is authenticated in current session.
+
+    Returns:
+        bool: True if authenticated, False otherwise
+    """
+    return st.session_state.get("authenticated", False)
+
+
+def get_current_user() -> str:
+    """
+    Get the currently logged-in user's email.
+
+    Returns:
+        str: User email or empty string if not authenticated
+    """
+    return st.session_state.get("user_email", "")
+
+
+def logout():
+    """
+    Log out the current user by clearing session state.
+    """
+    if "authenticated" in st.session_state:
+        del st.session_state["authenticated"]
+    if "user_email" in st.session_state:
+        del st.session_state["user_email"]

visualization/utils/feedback_manager.py

@@ -0,0 +1,140 @@
+"""
+Feedback manager for the v3 visualization tool.
+
+Reviewers only submit rejections — no action means the message is good.
+Keeps an in-session dict as the source of truth and persists every change
+immediately to Snowflake via snowflake_client.
+"""
+
+from datetime import datetime
+from typing import Optional
+import streamlit as st
+
+from utils import snowflake_client as sf
+
+# ---------------------------------------------------------------------------
+# Rejection reason catalogue
+# ---------------------------------------------------------------------------
+
+REJECTION_REASONS = {
+    "poor_header": "Poor Header",
+    "poor_body": "Poor Body / Content",
+    "grammar_issues": "Grammar Issues",
+    "emoji_problems": "Emoji Problems",
+    "recommendation_issues": "Recommendation Issues",
+    "wrong_information": "Wrong / Inaccurate Information",
+    "tone_issues": "Tone Issues",
+    "similarity": "Similar To Previous Messages",
+    "other": "Other",
+}
+
+
+def get_rejection_labels() -> dict:
+    return REJECTION_REASONS.copy()
+
+
+def get_rejection_label(key: str) -> str:
+    return REJECTION_REASONS.get(key, key)
+
+
+# ---------------------------------------------------------------------------
+# Session-state helpers
+# ---------------------------------------------------------------------------
+
+_SESSION_KEY = "v3_rejections"  # dict keyed by user_id (int)
+
+
+def _fb_dict() -> dict:
+    if _SESSION_KEY not in st.session_state:
+        st.session_state[_SESSION_KEY] = {}
+    return st.session_state[_SESSION_KEY]
+
+
+def _batch_id() -> str:
+    """Return (or create) a stable batch ID for this review session."""
+    if "review_batch_id" not in st.session_state:
+        import uuid
+        st.session_state["review_batch_id"] = str(uuid.uuid4())
+    return st.session_state["review_batch_id"]
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def set_rejection(
+    user_id: int,
+    rejection_reason: str,
+    rejection_text: Optional[str],
+    campaign_name: str,
+    brand: str,
+    message_header: str,
+    message_body: str,
+    message_timestamp,
+    reviewer_email: str,
+) -> bool:
+    """
+    Record a rejection for a single message.
+    Updates session state and persists to Snowflake immediately.
+    """
+    record = {
+        "rejection_reason": rejection_reason,
+        "rejection_text": rejection_text,
+        "campaign_name": campaign_name,
+        "brand": brand,
+        "message_header": message_header,
+        "message_body": message_body,
+        "message_timestamp": message_timestamp,
+        "reviewer_email": reviewer_email,
+        "updated_at": datetime.now(),
+    }
+    _fb_dict()[int(user_id)] = record
+
+    return sf.save_feedback(
+        batch_id=_batch_id(),
+        user_id=user_id,
+        campaign_name=campaign_name,
+        brand=brand,
+        rejection_reason=rejection_reason,
+        rejection_text=rejection_text,
+        message_header=message_header,
+        message_body=message_body,
+        message_timestamp=message_timestamp,
+        reviewer_email=reviewer_email,
+    )
+
+
+def clear_rejection(user_id: int) -> bool:
+    """Remove a rejection (reviewer un-rated)."""
+    _fb_dict().pop(int(user_id), None)
+    return sf.delete_feedback(_batch_id(), user_id)
+
+
+def get_rejection(user_id: int) -> Optional[dict]:
+    """Return in-session rejection record for a user, or None."""
+    return _fb_dict().get(int(user_id))
+
+
+def get_stats(total_messages: int) -> dict:
+    """Aggregate rejection stats for the current session."""
+    fb = _fb_dict()
+    total_rejected = len(fb)
+
+    reason_counts: dict = {}
+    for v in fb.values():
+        key = v.get("rejection_reason") or "other"
+        label = get_rejection_label(key)
+        reason_counts[label] = reason_counts.get(label, 0) + 1
+
+    return {
+        "total_messages": total_messages,
+        "total_rejected": total_rejected,
+        "reject_rate": round(total_rejected / total_messages * 100, 1) if total_messages else 0.0,
+        "rejection_reasons": reason_counts,
+    }
+
+
+def reset_session():
+    """Clear all in-session rejections and start a new batch ID."""
+    st.session_state.pop(_SESSION_KEY, None)
+    st.session_state.pop("review_batch_id", None)

visualization/utils/snowflake_client.py

@@ -0,0 +1,279 @@
+"""
+Snowflake client for the AI Messaging System Visualization Tool.
+
+All message data — including brand, streaks, user profile, and previous
+messages — is read directly from DAILY_PUSH_MESSAGES. No joins needed.
+"""
+
+import os
+import json
+import streamlit as st
+import pandas as pd
+from pathlib import Path
+from typing import Optional
+
+from dotenv import load_dotenv
+
+_env_path = Path(__file__).parent.parent / ".env"
+if _env_path.exists():
+    load_dotenv(_env_path)
+
+
+# ---------------------------------------------------------------------------
+# Timestamp helper
+# ---------------------------------------------------------------------------
+
+def _to_ts_str(ts) -> Optional[str]:
+    """Convert any timestamp-like value to a string Snowflake can bind."""
+    if ts is None:
+        return None
+    if hasattr(ts, "strftime"):
+        return ts.strftime("%Y-%m-%d %H:%M:%S")
+    return str(ts)[:19]
+
+
+# ---------------------------------------------------------------------------
+# Connection
+# ---------------------------------------------------------------------------
+
+def _get_connection():
+    import snowflake.connector
+
+    conn = st.session_state.get("_sf_conn")
+    if conn is not None:
+        try:
+            conn.cursor().execute("SELECT 1")
+            return conn
+        except Exception:
+            pass
+
+    conn = snowflake.connector.connect(
+        user=os.getenv("SNOWFLAKE_USER"),
+        password=os.getenv("SNOWFLAKE_PASSWORD"),
+        account=os.getenv("SNOWFLAKE_ACCOUNT"),
+        role=os.getenv("SNOWFLAKE_ROLE", "ACCOUNTADMIN"),
+        warehouse=os.getenv("SNOWFLAKE_WAREHOUSE", "COMPUTE_WH"),
+        database=os.getenv("SNOWFLAKE_DATABASE", "RECSYS_V3"),
+        schema=os.getenv("SNOWFLAKE_SCHEMA", "PUBLIC"),
+    )
+    st.session_state["_sf_conn"] = conn
+    return conn
+
+
+def _run_query(sql: str, params: Optional[tuple] = None) -> pd.DataFrame:
+    conn = _get_connection()
+    cur = conn.cursor()
+    cur.execute(sql, params) if params else cur.execute(sql)
+    cols = [d[0].upper() for d in cur.description]
+    return pd.DataFrame(cur.fetchall(), columns=cols)
+
+
+def _run_dml(sql: str, params: Optional[tuple] = None) -> None:
+    conn = _get_connection()
+    cur = conn.cursor()
+    cur.execute(sql, params) if params else cur.execute(sql)
+    conn.commit()
+
+
+# ---------------------------------------------------------------------------
+# Schema bootstrap
+# ---------------------------------------------------------------------------
+
+CREATE_FEEDBACK_TABLE = """
+CREATE TABLE IF NOT EXISTS MESSAGING_SYSTEM_V2.UI.V3_FEEDBACKS (
+    BATCH_ID          VARCHAR,
+    USER_ID           INTEGER,
+    CAMPAIGN_NAME     VARCHAR,
+    BRAND             VARCHAR,
+    REJECTION_REASON  VARCHAR,
+    REJECTION_TEXT    VARCHAR,
+    MESSAGE_HEADER    VARCHAR,
+    MESSAGE_BODY      VARCHAR,
+    MESSAGE_TIMESTAMP TIMESTAMP,
+    REVIEWER_EMAIL    VARCHAR,
+    TIMESTAMP         TIMESTAMP DEFAULT CURRENT_TIMESTAMP()
+)
+"""
+
+
+def ensure_feedback_table():
+    try:
+        _run_dml(CREATE_FEEDBACK_TABLE)
+    except Exception as e:
+        st.warning(f"Could not verify feedback table: {e}")
+
+
+# ---------------------------------------------------------------------------
+# Pre-fetch: all campaigns, top N per campaign
+# ---------------------------------------------------------------------------
+
+def fetch_all_messages() -> pd.DataFrame:
+    """
+    Fetch all messages from DAILY_PUSH_MESSAGES — no joins, no per-campaign cap.
+
+    Each user has up to 3 rows (messages generated on different days).
+    Rows are ordered oldest→newest per user so the UI can display the
+    chronological sequence in columns.
+
+    Adds two window-function columns:
+      - MSG_RANK:      1 = oldest, 2 = middle, 3 = newest (per user)
+      - USER_MSG_COUNT: total messages this user has (1–3)
+
+    Excludes users who already have any rejection in V3_FEEDBACKS.
+
+    Returns a DataFrame with columns:
+        USER_ID, DETECTED_BRAND, CAMPAIGN_NAME, BRANCH, PLATFORM,
+        TIMESTAMP, MESSAGE_HEADER, MESSAGE_BODY, RECOMMENDATION,
+        RECOMMENDED_CONTENT_ID, FIRST_NAME,
+        CURRENT_DAILY_STREAK_LENGTH, CURRENT_WEEKLY_STREAK_LENGTH,
+        USER_PROFILE, PREVIOUS_MESSAGES, LAST_INTERACTED_CONTENT_PROFILE,
+        MSG_RANK, USER_MSG_COUNT
+    """
+    sql = """
+        WITH excluded_users AS (
+            SELECT DISTINCT USER_ID
+            FROM MESSAGING_SYSTEM_V2.UI.V3_FEEDBACKS
+        ),
+        ranked AS (
+            SELECT
+                m.USER_ID,
+                LOWER(m.DETECTED_BRAND)                         AS DETECTED_BRAND,
+                m.BRANCH,
+                m.MESSAGE,
+                m.PLATFORM,
+                m.CAMPAIGN_NAME,
+                m.TIMESTAMP,
+                m.RECOMMENDATION,
+                m.RECOMMENDED_CONTENT_ID,
+                m.FIRST_NAME,
+                m.CURRENT_DAILY_STREAK_LENGTH,
+                m.CURRENT_WEEKLY_STREAK_LENGTH,
+                m.USER_PROFILE,
+                m.PREVIOUS_MESSAGES,
+                m.LAST_INTERACTED_CONTENT_PROFILE,
+                ROW_NUMBER() OVER (
+                    PARTITION BY m.USER_ID
+                    ORDER BY m.TIMESTAMP ASC
+                )                                               AS MSG_RANK,
+                COUNT(*) OVER (PARTITION BY m.USER_ID)         AS USER_MSG_COUNT
+            FROM MESSAGING_SYSTEM_V2.GENERATED_DATA.DAILY_PUSH_MESSAGES m
+            WHERE m.USER_ID NOT IN (SELECT USER_ID FROM excluded_users)
+        )
+        SELECT
+            USER_ID, DETECTED_BRAND, BRANCH, MESSAGE, PLATFORM, CAMPAIGN_NAME,
+            TIMESTAMP, RECOMMENDATION, RECOMMENDED_CONTENT_ID, FIRST_NAME,
+            CURRENT_DAILY_STREAK_LENGTH, CURRENT_WEEKLY_STREAK_LENGTH,
+            USER_PROFILE, PREVIOUS_MESSAGES, LAST_INTERACTED_CONTENT_PROFILE,
+            MSG_RANK, USER_MSG_COUNT
+        FROM ranked
+        WHERE MSG_RANK <= 3
+        ORDER BY USER_ID, MSG_RANK
+    """
+
+    df = _run_query(sql)
+    if df.empty:
+        return df
+
+    df["MESSAGE_HEADER"] = df["MESSAGE"].apply(_parse_header)
+    df["MESSAGE_BODY"] = df["MESSAGE"].apply(_parse_body)
+    df.drop(columns=["MESSAGE"], inplace=True)
+
+    return df
+
+
+# ---------------------------------------------------------------------------
+# JSON message parsing
+# ---------------------------------------------------------------------------
+
+def _parse_json_message(raw) -> dict:
+    if raw is None:
+        return {}
+    if isinstance(raw, dict):
+        return raw
+    try:
+        return json.loads(str(raw))
+    except Exception:
+        return {}
+
+
+def _parse_header(raw) -> str:
+    return _parse_json_message(raw).get("header", "")
+
+
+def _parse_body(raw) -> str:
+    msg = _parse_json_message(raw)
+    return msg.get("message", msg.get("body", ""))
+
+
+# ---------------------------------------------------------------------------
+# Feedback storage
+# ---------------------------------------------------------------------------
+
+def save_feedback(
+    batch_id: str,
+    user_id: int,
+    campaign_name: str,
+    brand: str,
+    rejection_reason: Optional[str],
+    rejection_text: Optional[str],
+    message_header: str,
+    message_body: str,
+    message_timestamp,
+    reviewer_email: str,
+) -> bool:
+    msg_ts_str = _to_ts_str(message_timestamp)
+
+    merge_sql = """
+        MERGE INTO MESSAGING_SYSTEM_V2.UI.V3_FEEDBACKS AS tgt
+        USING (
+            SELECT
+                %s                   AS BATCH_ID,
+                %s                   AS USER_ID,
+                %s                   AS CAMPAIGN_NAME,
+                %s                   AS BRAND,
+                %s                   AS REJECTION_REASON,
+                %s                   AS REJECTION_TEXT,
+                %s                   AS MESSAGE_HEADER,
+                %s                   AS MESSAGE_BODY,
+                TO_TIMESTAMP_NTZ(%s) AS MESSAGE_TIMESTAMP,
+                %s                   AS REVIEWER_EMAIL
+        ) AS src
+        ON tgt.BATCH_ID = src.BATCH_ID AND tgt.USER_ID = src.USER_ID
+        WHEN MATCHED THEN UPDATE SET
+            REJECTION_REASON = src.REJECTION_REASON,
+            REJECTION_TEXT   = src.REJECTION_TEXT,
+            TIMESTAMP        = CURRENT_TIMESTAMP()
+        WHEN NOT MATCHED THEN INSERT (
+            BATCH_ID, USER_ID, CAMPAIGN_NAME, BRAND,
+            REJECTION_REASON, REJECTION_TEXT,
+            MESSAGE_HEADER, MESSAGE_BODY, MESSAGE_TIMESTAMP, REVIEWER_EMAIL
+        ) VALUES (
+            src.BATCH_ID, src.USER_ID, src.CAMPAIGN_NAME, src.BRAND,
+            src.REJECTION_REASON, src.REJECTION_TEXT,
+            src.MESSAGE_HEADER, src.MESSAGE_BODY, src.MESSAGE_TIMESTAMP, src.REVIEWER_EMAIL
+        )
+    """
+    try:
+        _run_dml(merge_sql, (
+            batch_id, int(user_id), campaign_name, brand,
+            rejection_reason, rejection_text,
+            message_header, message_body,
+            msg_ts_str, reviewer_email,
+        ))
+        return True
+    except Exception as e:
+        st.error(f"Failed to save feedback: {e}")
+        return False
+
+
+def delete_feedback(batch_id: str, user_id: int) -> bool:
+    sql = """
+        DELETE FROM MESSAGING_SYSTEM_V2.UI.V3_FEEDBACKS
+        WHERE BATCH_ID = %s AND USER_ID = %s
+    """
+    try:
+        _run_dml(sql, (batch_id, int(user_id)))
+        return True
+    except Exception as e:
+        st.error(f"Failed to delete feedback: {e}")
+        return False

visualization/utils/theme.py

@@ -0,0 +1,157 @@
+"""
+Brand theming for the AI Messaging System Visualization Tool.
+"""
+
+import streamlit as st
+
+BRAND_CONFIG = {
+    "drumeo": {
+        "color": "#E84545",
+        "light": "#FDEAEA",
+        "emoji": "🥁",
+        "label": "Drumeo",
+    },
+    "pianote": {
+        "color": "#4A90D9",
+        "light": "#EAF3FC",
+        "emoji": "🎹",
+        "label": "Pianote",
+    },
+    "guitareo": {
+        "color": "#F5A623",
+        "light": "#FEF6E7",
+        "emoji": "🎸",
+        "label": "Guitareo",
+    },
+    "singeo": {
+        "color": "#7B68EE",
+        "light": "#F0EEFF",
+        "emoji": "🎤",
+        "label": "Singeo",
+    },
+    "playbass": {
+        "color": "#3DAA5C",
+        "light": "#E8F7ED",
+        "emoji": "🎸",
+        "label": "Playbass",
+    },
+    "all": {
+        "color": "#555555",
+        "light": "#F5F5F5",
+        "emoji": "🎵",
+        "label": "All Brands",
+    },
+}
+
+CAMPAIGN_LABELS = {
+    "dailyPush_dailyStreak": "Daily Streak",
+    "dailyPush_weeklyStreak": "Weekly Streak",
+    "dailyPush_noStreak": "No Streak (Re-engagement)",
+    "all": "All Campaigns",
+}
+
+ALL_BRANDS = ["all", "drumeo", "pianote", "guitareo", "singeo", "playbass"]
+ALL_CAMPAIGNS = [
+    "all",
+    "dailyPush_dailyStreak",
+    "dailyPush_weeklyStreak",
+    "dailyPush_noStreak",
+]
+
+# Scenarios per campaign, applied client-side after data load.
+# Detection uses the RECOMMENDATION column in DAILY_PUSH_MESSAGES.
+# For weeklyStreak: RECOMMENDATION == 'for_you' → no_practice_this_week
+CAMPAIGN_SCENARIOS = {
+    "all": [],
+    "dailyPush_dailyStreak": [],  # single scenario, no sub-filter needed
+    "dailyPush_weeklyStreak": [
+        ("all", "All"),
+        ("practiced_this_week", "Practiced This Week"),
+        ("no_practice_this_week", "No Practice This Week"),
+    ],
+    "dailyPush_noStreak": [],
+}
+
+
+def get_scenarios(campaign: str) -> list:
+    """Return scenario (key, label) pairs for a given campaign."""
+    return CAMPAIGN_SCENARIOS.get(campaign, [])
+
+
+def detect_scenario(recommendation_value) -> str:
+    """
+    Detect the weekly-streak sub-scenario from the RECOMMENDATION column.
+
+    RECOMMENDATION == 'for_you'  → user hasn't practiced this week
+    anything else                → user has practiced this week
+    """
+    s = str(recommendation_value or "").strip().lower()
+    return "no_practice_this_week" if s == "for_you" else "practiced_this_week"
+
+
+def get_brand(brand: str) -> dict:
+    return BRAND_CONFIG.get(brand.lower() if brand else "all", BRAND_CONFIG["all"])
+
+
+def get_campaign_label(campaign: str) -> str:
+    return CAMPAIGN_LABELS.get(campaign, campaign)
+
+
+def inject_global_css():
+    """Inject shared CSS into the Streamlit app."""
+    st.markdown(
+        """
+        <style>
+        .msg-card {
+            border: 1px solid #e0e0e0;
+            border-radius: 12px;
+            padding: 20px;
+            margin-bottom: 18px;
+            background: #ffffff;
+            box-shadow: 0 1px 4px rgba(0,0,0,0.06);
+        }
+        .msg-preview {
+            background: #f4f6f8;
+            border-left: 4px solid #aaa;
+            border-radius: 6px;
+            padding: 12px 16px;
+            margin: 10px 0;
+        }
+        .msg-header-text {
+            font-size: 15px;
+            font-weight: 700;
+            margin: 0 0 5px 0;
+            color: #1a1a1a;
+        }
+        .msg-body-text {
+            font-size: 14px;
+            color: #444;
+            margin: 0;
+        }
+        .user-meta {
+            font-size: 13px;
+            color: #555;
+            margin: 3px 0;
+        }
+        .streak-badge {
+            display: inline-block;
+            background: #fff3cd;
+            border: 1px solid #ffc107;
+            border-radius: 20px;
+            padding: 2px 10px;
+            font-size: 12px;
+            font-weight: 600;
+            margin-right: 6px;
+        }
+        .section-label {
+            font-size: 11px;
+            font-weight: 700;
+            text-transform: uppercase;
+            letter-spacing: 0.08em;
+            color: #888;
+            margin-bottom: 4px;
+        }
+        </style>
+        """,
+        unsafe_allow_html=True,
+    )