Mapping of grouped metadata

API_DOCUMENTATION.md

@@ -0,0 +1,631 @@
+# A/B Test Predictor API Documentation
+
+Welcome! This API predicts A/B test outcomes using multimodal AI analysis of your control and variant images combined with business context data.
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+pip install gradio-client pillow
+```
+
+### Basic Example
+
+```python
+from gradio_client import Client
+
+# Connect to the API
+client = Client("SpiralyzeLLC/ABTestPredictor")
+
+# Make a prediction
+result = client.predict(
+    "path/to/control.jpg",
+    "path/to/variant.jpg",
+    "SaaS",                    # Business Model
+    "B2B",                     # Customer Type
+    "High-Intent Lead Gen",    # Conversion Type
+    "B2B Software & Tech",     # Industry
+    "Awareness & Discovery",   # Page Type
+    api_name="/predict_with_categorical_data"
+)
+
+print(f"Win Probability: {result['predictionResults']['probability']}")
+print(f"Confidence: {result['predictionResults']['modelConfidence']}%")
+```
+
+## 📋 API Reference
+
+### Endpoint
+
+```
+/predict_with_categorical_data
+```
+
+### Input Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `control_image` | Image File | Yes | Control version image (JPG, PNG) |
+| `variant_image` | Image File | Yes | Variant version image (JPG, PNG) |
+| `business_model` | String | Yes | Business model type |
+| `customer_type` | String | Yes | Target customer type |
+| `conversion_type` | String | Yes | Type of conversion |
+| `industry` | String | Yes | Business industry |
+| `page_type` | String | Yes | Type of page being tested |
+
+### Valid Category Values
+
+#### Business Model
+- `E-Commerce`
+- `Lead Generation`
+- `Other*`
+- `SaaS`
+
+#### Customer Type
+- `B2B`
+- `B2C`
+- `Both`
+- `Other*`
+
+#### Conversion Type
+
+**🎯 New Feature**: The API now accepts both **parent group values** (listed below) AND **specific values** (e.g., "Request Demo/Contact Sales"). Specific values are automatically converted to their parent groups.
+
+**Parent Groups** (model uses these internally):
+- `Direct Purchase`
+- `High-Intent Lead Gen`
+- `Info/Content Lead Gen`
+- `Location Search`
+- `Non-Profit/Community`
+- `Other Conversion`
+
+**Example Specific Values** (automatically mapped):
+- `Request Demo/Contact Sales` → `High-Intent Lead Gen`
+- `Buy Now` → `Direct Purchase`
+- `Download Asset / App` → `Info/Content Lead Gen`
+- See `mapping.json` for complete list
+
+#### Industry
+
+**🎯 New Feature**: The API now accepts both **parent group values** (listed below) AND **specific values** (e.g., "Accounting Services"). Specific values are automatically converted to their parent groups.
+
+**Parent Groups** (model uses these internally):
+- `Automotive & Transportation`
+- `B2B Services`
+- `B2B Software & Tech`
+- `Consumer Services`
+- `Consumer Software & Apps`
+- `Education`
+- `Finance, Insurance & Real Estate`
+- `Food, Hospitality & Travel`
+- `Health & Wellness`
+- `Industrial & Manufacturing`
+- `Media & Entertainment`
+- `Non-Profit & Government`
+- `Other`
+- `Retail & E-commerce`
+
+**Example Specific Values** (automatically mapped):
+- `Accounting Services` → `B2B Services`
+- `Marketing Agency` → `B2B Services`
+- `Cybersecurity` → `B2B Software & Tech`
+- `Healthcare Software` → `B2B Software & Tech`
+- See `mapping.json` for complete list (200+ specific industries supported)
+
+#### Page Type
+
+**🎯 New Feature**: The API now accepts both **parent group values** (listed below) AND **specific values** (e.g., "Homepage"). Specific values are automatically converted to their parent groups.
+
+**Parent Groups** (model uses these internally):
+- `Awareness & Discovery`
+- `Consideration & Evaluation`
+- `Conversion`
+- `Internal & Navigation`
+- `Post-Conversion & Other`
+
+**Example Specific Values** (automatically mapped):
+- `Homepage` → `Awareness & Discovery`
+- `Pricing Page` → `Consideration & Evaluation`
+- `Checkout` → `Conversion`
+- `Login` → `Internal & Navigation`
+- See `mapping.json` for complete list
+
+### Response Format
+
+```json
+{
+  "predictionResults": {
+    "probability": "0.682",
+    "modelConfidence": "66.1",
+    "trainingDataSamples": 14634,
+    "totalPredictions": 1626,
+    "correctPredictions": 1074,
+    "totalWinPrediction": 667,
+    "totalLosePrediction": 959
+  },
+  "providedCategories": {
+    "businessModel": "SaaS",
+    "customerType": "B2B",
+    "conversionType": "Request Demo/Contact Sales",
+    "industry": "Cybersecurity",
+    "pageType": "Homepage"
+  },
+  "groupedCategories": {
+    "businessModel": "SaaS",
+    "customerType": "B2B",
+    "conversionType": "High-Intent Lead Gen",
+    "industry": "B2B Software & Tech",
+    "pageType": "Awareness & Discovery"
+  },
+  "processingInfo": {
+    "totalProcessingTime": "2.34s",
+    "confidenceSource": "B2B Software & Tech | Awareness & Discovery"
+  }
+}
+```
+
+#### Response Fields
+
+**predictionResults**
+- `probability`: Win probability for variant (0-1 scale, >0.5 means variant wins)
+- `modelConfidence`: Model accuracy percentage for this category combination
+- `trainingDataSamples`: Training samples used for this category
+- `totalPredictions`: Total test predictions for this category
+- `correctPredictions`: Correct predictions for this category
+- `totalWinPrediction`: Actual wins in historical data
+- `totalLosePrediction`: Actual losses in historical data
+
+**providedCategories**
+- Echo of input categorical data (as provided by you)
+
+**groupedCategories** *(New!)*
+- The parent group values used by the model for prediction
+- Shows how specific values were mapped to parent groups
+- This is what the model actually uses internally
+
+**processingInfo**
+- `totalProcessingTime`: API processing time
+- `confidenceSource`: Category combination used for confidence scoring
+
+## 🔄 Automatic Value Mapping
+
+### How It Works
+
+The API now automatically converts specific categorical values to their parent groups using the `mapping.json` file. This means you can send more specific data (e.g., "Accounting Services", "Homepage", "Request Demo/Contact Sales") and the API will handle the conversion automatically.
+
+**Benefits:**
+- ✅ More flexibility in input data
+- ✅ No need to pre-process your data
+- ✅ API handles the conversion automatically
+- ✅ Both original and grouped values returned in response
+
+### Mapping Examples
+
+#### Industry Mapping
+```
+"Accounting Services" → "B2B Services"
+"Marketing Agency" → "B2B Services"
+"Cybersecurity" → "B2B Software & Tech"
+"CRM Software" → "B2B Software & Tech"
+"Healthcare" → "Health & Wellness"
+"Hotels" → "Food, Hospitality & Travel"
+```
+
+#### Page Type Mapping
+```
+"Homepage" → "Awareness & Discovery"
+"Blog / Content" → "Awareness & Discovery"
+"Pricing Page" → "Consideration & Evaluation"
+"Demo Squeeze" → "Consideration & Evaluation"
+"Checkout" → "Conversion"
+"Contact Sales" → "Conversion"
+"Login" → "Internal & Navigation"
+```
+
+#### Conversion Type Mapping
+```
+"Request Demo/Contact Sales" → "High-Intent Lead Gen"
+"Start Free Trial/Signup" → "High-Intent Lead Gen"
+"Buy Now" → "Direct Purchase"
+"Subscription (No Free Trial)" → "Direct Purchase"
+"Download Asset / App" → "Info/Content Lead Gen"
+"Register for Webinar/Event" → "Info/Content Lead Gen"
+```
+
+### Using Specific Values in API Calls
+
+**Example with specific values:**
+```python
+result = client.predict(
+    "control.jpg",
+    "variant.jpg",
+    "SaaS",                           # Business Model (no mapping needed)
+    "B2B",                            # Customer Type (no mapping needed)
+    "Request Demo/Contact Sales",     # Will be mapped to "High-Intent Lead Gen"
+    "Cybersecurity",                  # Will be mapped to "B2B Software & Tech"
+    "Homepage",                       # Will be mapped to "Awareness & Discovery"
+    api_name="/predict_with_categorical_data"
+)
+```
+
+**Response will include both:**
+```json
+{
+  "providedCategories": {
+    "conversionType": "Request Demo/Contact Sales",
+    "industry": "Cybersecurity",
+    "pageType": "Homepage"
+  },
+  "groupedCategories": {
+    "conversionType": "High-Intent Lead Gen",
+    "industry": "B2B Software & Tech",
+    "pageType": "Awareness & Discovery"
+  }
+}
+```
+
+## 💻 Code Examples
+
+### Python
+
+#### Complete Example with Error Handling
+
+```python
+from gradio_client import Client
+from PIL import Image
+import json
+
+def predict_abtest(control_path, variant_path, categories):
+    """
+    Predict A/B test outcome
+    
+    Args:
+        control_path: Path to control image
+        variant_path: Path to variant image
+        categories: Dict with business_model, customer_type, etc.
+    
+    Returns:
+        dict: Prediction results
+    """
+    try:
+        # Initialize client
+        client = Client("SpiralyzeLLC/ABTestPredictor")
+        
+        # Make prediction
+        result = client.predict(
+            control_path,
+            variant_path,
+            categories['business_model'],
+            categories['customer_type'],
+            categories['conversion_type'],
+            categories['industry'],
+            categories['page_type'],
+            api_name="/predict_with_categorical_data"
+        )
+        
+        return {
+            'success': True,
+            'data': result
+        }
+        
+    except Exception as e:
+        return {
+            'success': False,
+            'error': str(e)
+        }
+
+# Usage
+categories = {
+    'business_model': 'SaaS',
+    'customer_type': 'B2B',
+    'conversion_type': 'High-Intent Lead Gen',
+    'industry': 'B2B Software & Tech',
+    'page_type': 'Awareness & Discovery'
+}
+
+result = predict_abtest('control.jpg', 'variant.jpg', categories)
+
+if result['success']:
+    prob = result['data']['predictionResults']['probability']
+    conf = result['data']['predictionResults']['modelConfidence']
+    
+    print(f"✅ Prediction: {prob}")
+    print(f"📊 Confidence: {conf}%")
+    
+    if float(prob) > 0.5:
+        print("🎉 Variant is predicted to WIN")
+    else:
+        print("⚠️ Control is predicted to win")
+else:
+    print(f"❌ Error: {result['error']}")
+```
+
+#### Batch Processing Multiple Tests
+
+```python
+from gradio_client import Client
+import time
+
+def batch_predict(test_cases):
+    """Process multiple A/B tests"""
+    client = Client("SpiralyzeLLC/ABTestPredictor")
+    results = []
+    
+    for i, test in enumerate(test_cases):
+        print(f"Processing test {i+1}/{len(test_cases)}...")
+        
+        try:
+            result = client.predict(
+                test['control_image'],
+                test['variant_image'],
+                test['business_model'],
+                test['customer_type'],
+                test['conversion_type'],
+                test['industry'],
+                test['page_type'],
+                api_name="/predict_with_categorical_data"
+            )
+            
+            results.append({
+                'test_id': i + 1,
+                'status': 'success',
+                'result': result
+            })
+            
+        except Exception as e:
+            results.append({
+                'test_id': i + 1,
+                'status': 'failed',
+                'error': str(e)
+            })
+        
+        # Rate limiting
+        time.sleep(1)
+    
+    return results
+
+# Usage
+tests = [
+    {
+        'control_image': 'test1_control.jpg',
+        'variant_image': 'test1_variant.jpg',
+        'business_model': 'SaaS',
+        'customer_type': 'B2B',
+        'conversion_type': 'High-Intent Lead Gen',
+        'industry': 'B2B Software & Tech',
+        'page_type': 'Awareness & Discovery'
+    },
+    # Add more tests...
+]
+
+results = batch_predict(tests)
+print(f"Completed {len(results)} predictions")
+```
+
+### JavaScript/Node.js
+
+```javascript
+const axios = require('axios');
+const fs = require('fs');
+
+async function predictABTest(controlPath, variantPath, categories) {
+    const apiUrl = 'https://spiralyzellc-abtestpredictor.hf.space/api/predict';
+    
+    // Read and encode images
+    const controlImage = fs.readFileSync(controlPath);
+    const variantImage = fs.readFileSync(variantPath);
+    
+    const controlB64 = `data:image/jpeg;base64,${controlImage.toString('base64')}`;
+    const variantB64 = `data:image/jpeg;base64,${variantImage.toString('base64')}`;
+    
+    // Prepare payload
+    const payload = {
+        data: [
+            controlB64,
+            variantB64,
+            categories.businessModel,
+            categories.customerType,
+            categories.conversionType,
+            categories.industry,
+            categories.pageType
+        ]
+    };
+    
+    try {
+        const response = await axios.post(apiUrl, payload, {
+            headers: { 'Content-Type': 'application/json' },
+            timeout: 30000
+        });
+        
+        return {
+            success: true,
+            data: response.data.data[0]
+        };
+    } catch (error) {
+        return {
+            success: false,
+            error: error.message
+        };
+    }
+}
+
+// Usage
+const categories = {
+    businessModel: 'SaaS',
+    customerType: 'B2B',
+    conversionType: 'High-Intent Lead Gen',
+    industry: 'B2B Software & Tech',
+    pageType: 'Awareness & Discovery'
+};
+
+predictABTest('control.jpg', 'variant.jpg', categories)
+    .then(result => {
+        if (result.success) {
+            console.log('Win Probability:', result.data.predictionResults.probability);
+            console.log('Confidence:', result.data.predictionResults.modelConfidence + '%');
+        } else {
+            console.error('Error:', result.error);
+        }
+    });
+```
+
+### cURL
+
+```bash
+#!/bin/bash
+
+# Encode images to base64
+CONTROL_B64=$(base64 -i control.jpg)
+VARIANT_B64=$(base64 -i variant.jpg)
+
+# Make API request
+curl -X POST "https://spiralyzellc-abtestpredictor.hf.space/api/predict" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "data": [
+      "data:image/jpeg;base64,'"${CONTROL_B64}"'",
+      "data:image/jpeg;base64,'"${VARIANT_B64}"'",
+      "SaaS",
+      "B2B",
+      "High-Intent Lead Gen",
+      "B2B Software & Tech",
+      "Awareness & Discovery"
+    ]
+  }' | jq '.'
+```
+
+## 🔧 Best Practices
+
+### Image Requirements
+
+- **Format**: JPG, PNG, or JPEG
+- **Size**: Recommended < 5MB per image
+- **Resolution**: Minimum 800x600px recommended
+- **Content**: Should show the actual page/element being tested
+
+### Rate Limiting
+
+- **Recommended**: 1 request per second
+- **Maximum**: No hard limit, but please be respectful
+- Add delays between batch requests
+
+### Error Handling
+
+Always wrap API calls in try-catch blocks:
+
+```python
+try:
+    result = client.predict(...)
+except Exception as e:
+    # Handle timeout, network errors, invalid inputs
+    print(f"API Error: {e}")
+```
+
+### Interpreting Results
+
+**Win Probability**
+- `> 0.5`: Variant predicted to win
+- `< 0.5`: Control predicted to win
+- `~ 0.5`: Too close to call
+
+**Model Confidence**
+- `> 70%`: High confidence
+- `60-70%`: Moderate confidence
+- `< 60%`: Lower confidence (less historical data for this category)
+
+**Training Data Samples**
+- `> 1000`: Robust category with lots of data
+- `100-1000`: Moderate data available
+- `< 100`: Limited data, prediction may be less reliable
+
+## 🐛 Common Issues
+
+### Issue: "Connection timeout"
+**Solution**: Increase timeout to 30-60 seconds for first request (model loads)
+
+```python
+client = Client("SpiralyzeLLC/ABTestPredictor")
+# First call might be slower due to model loading
+```
+
+### Issue: "Invalid category value"
+**Solution**: Ensure exact match with valid values (case-sensitive)
+
+```python
+# ✅ Correct
+business_model = "SaaS"
+
+# ❌ Wrong
+business_model = "saas"  # Wrong case
+business_model = "Software as a Service"  # Not in valid list
+```
+
+### Issue: "Image file not found"
+**Solution**: Use absolute paths or verify file exists
+
+```python
+import os
+
+control_path = os.path.abspath("control.jpg")
+if not os.path.exists(control_path):
+    print(f"File not found: {control_path}")
+```
+
+## 📊 Understanding Confidence Scores
+
+Confidence scores are based on **Industry + Page Type** combinations from historical A/B test data:
+
+- **High Sample Count** (>1000 samples): More reliable predictions
+- **Low Sample Count** (<100 samples): Less reliable, use with caution
+- **Accuracy**: Historical accuracy for this specific category combination
+
+The model has been trained on thousands of real A/B tests, so confidence scores reflect actual performance on similar tests.
+
+## 🌐 Web Interface
+
+You can also use the web interface:
+
+**URL**: https://huggingface.co/spaces/SpiralyzeLLC/ABTestPredictor
+
+1. Upload control and variant images
+2. Select categories from dropdowns
+3. Click "Predict"
+4. View results in JSON format
+
+## 📝 Example Use Cases
+
+### 1. Pre-Test Analysis
+Predict outcome before running expensive A/B tests
+
+### 2. Batch Analysis
+Analyze multiple test variations to pick the best candidate
+
+### 3. Historical Analysis
+Compare predictions with actual results to calibrate decisions
+
+### 4. Integration
+Embed in your testing platform or analytics dashboard
+
+## 🆘 Support
+
+**Issues?**
+- Check the [Common Issues](#-common-issues) section
+- Verify your inputs match the [Valid Category Values](#valid-category-values)
+- Ensure images are valid and readable
+
+**Questions?**
+- Open an issue on the Hugging Face Space
+- Check the example code for reference implementations
+
+## 📜 License
+
+This API is provided for research and commercial use. Please use responsibly.
+
+---
+
+**API Version**: 1.0  
+**Last Updated**: October 31, 2025  
+**Model**: Multimodal Siamese Network (GGG Enhanced)  
+**Hosted on**: Hugging Face Spaces
+

COMPLETE_EXAMPLE_WITH_MAPPING.py

@@ -0,0 +1,304 @@
+"""
+Complete Example: Using the A/B Test Predictor API with Automatic Mapping
+
+This example demonstrates how to use the updated API that accepts both
+specific and parent group values for Industry, Page Type, and Conversion Type.
+
+The API now automatically converts specific values to parent groups using
+mapping.json before feeding them to the model.
+"""
+
+from gradio_client import Client
+
+def predict_ab_test_with_specific_values():
+    """
+    Example showing how to use SPECIFIC values.
+    The API will automatically map them to parent groups.
+    """
+    print("=" * 80)
+    print("EXAMPLE 1: Using Specific Values (NEW FEATURE)")
+    print("=" * 80)
+    print()
+    
+    # Initialize the client
+    client = Client("SpiralyzeLLC/ABTestPredictor")
+    
+    # Make prediction with SPECIFIC values
+    # These will be automatically converted to parent groups
+    result = client.predict(
+        "path/to/control.jpg",
+        "path/to/variant.jpg",
+        "SaaS",                           # Business Model (no mapping needed)
+        "B2B",                            # Customer Type (no mapping needed)
+        "Request Demo/Contact Sales",     # Will map to: High-Intent Lead Gen
+        "Cybersecurity",                  # Will map to: B2B Software & Tech
+        "Homepage",                       # Will map to: Awareness & Discovery
+        api_name="/predict_with_categorical_data"
+    )
+    
+    print("📥 INPUT:")
+    print(f"   Industry: {result['providedCategories']['industry']}")
+    print(f"   Page Type: {result['providedCategories']['pageType']}")
+    print(f"   Conversion Type: {result['providedCategories']['conversionType']}")
+    print()
+    
+    print("🔄 AUTO-MAPPED TO:")
+    print(f"   Industry: {result['groupedCategories']['industry']}")
+    print(f"   Page Type: {result['groupedCategories']['pageType']}")
+    print(f"   Conversion Type: {result['groupedCategories']['conversionType']}")
+    print()
+    
+    print("🎯 PREDICTION RESULTS:")
+    print(f"   Win Probability: {result['predictionResults']['probability']}")
+    print(f"   Model Confidence: {result['predictionResults']['modelConfidence']}%")
+    print(f"   Training Samples: {result['predictionResults']['trainingDataSamples']}")
+    print()
+    
+    return result
+
+
+def predict_ab_test_with_parent_groups():
+    """
+    Example showing traditional usage with parent groups.
+    This still works exactly as before (backward compatible).
+    """
+    print("=" * 80)
+    print("EXAMPLE 2: Using Parent Groups (TRADITIONAL METHOD)")
+    print("=" * 80)
+    print()
+    
+    client = Client("SpiralyzeLLC/ABTestPredictor")
+    
+    # Make prediction with PARENT GROUP values
+    result = client.predict(
+        "path/to/control.jpg",
+        "path/to/variant.jpg",
+        "SaaS",
+        "B2B",
+        "High-Intent Lead Gen",          # Parent group value
+        "B2B Software & Tech",            # Parent group value
+        "Awareness & Discovery",          # Parent group value
+        api_name="/predict_with_categorical_data"
+    )
+    
+    print("📥 INPUT (Parent Groups):")
+    print(f"   Industry: {result['providedCategories']['industry']}")
+    print(f"   Page Type: {result['providedCategories']['pageType']}")
+    print(f"   Conversion Type: {result['providedCategories']['conversionType']}")
+    print()
+    
+    print("🎯 PREDICTION RESULTS:")
+    print(f"   Win Probability: {result['predictionResults']['probability']}")
+    print(f"   Model Confidence: {result['predictionResults']['modelConfidence']}%")
+    print()
+    
+    return result
+
+
+def batch_predictions_with_mixed_values():
+    """
+    Example showing batch processing with mixed values
+    (some specific, some parent groups).
+    """
+    print("=" * 80)
+    print("EXAMPLE 3: Batch Processing with Mixed Values")
+    print("=" * 80)
+    print()
+    
+    client = Client("SpiralyzeLLC/ABTestPredictor")
+    
+    test_cases = [
+        {
+            "name": "E-commerce Checkout Test",
+            "business_model": "E-Commerce",
+            "customer_type": "B2C",
+            "conversion_type": "Buy Now",              # Specific → Direct Purchase
+            "industry": "Apparel & Accessories ",       # Specific → Retail & E-commerce
+            "page_type": "Checkout"                     # Specific → Conversion
+        },
+        {
+            "name": "SaaS Pricing Page Test",
+            "business_model": "SaaS",
+            "customer_type": "B2B",
+            "conversion_type": "High-Intent Lead Gen",  # Parent group
+            "industry": "B2B Software & Tech",          # Parent group
+            "page_type": "Pricing Page"                 # Specific → Consideration & Evaluation
+        },
+        {
+            "name": "Healthcare Portal Test",
+            "business_model": "Lead Generation",
+            "customer_type": "B2C",
+            "conversion_type": "Request Information",   # Specific → Info/Content Lead Gen
+            "industry": "Healthcare",                   # Specific → Health & Wellness
+            "page_type": "Contact Us"                   # Specific → Conversion
+        }
+    ]
+    
+    results = []
+    
+    for i, test in enumerate(test_cases):
+        print(f"📊 Test {i+1}: {test['name']}")
+        print(f"   Input: {test['industry']} | {test['page_type']} | {test['conversion_type']}")
+        
+        # Note: In a real scenario, you'd provide actual image paths
+        result = client.predict(
+            f"control_{i}.jpg",
+            f"variant_{i}.jpg",
+            test['business_model'],
+            test['customer_type'],
+            test['conversion_type'],
+            test['industry'],
+            test['page_type'],
+            api_name="/predict_with_categorical_data"
+        )
+        
+        print(f"   Mapped: {result['groupedCategories']['industry']} | "
+              f"{result['groupedCategories']['pageType']} | "
+              f"{result['groupedCategories']['conversionType']}")
+        print(f"   Probability: {result['predictionResults']['probability']}")
+        print()
+        
+        results.append(result)
+    
+    return results
+
+
+def mapping_reference_guide():
+    """
+    Quick reference guide showing common mappings.
+    """
+    print("=" * 80)
+    print("MAPPING REFERENCE GUIDE")
+    print("=" * 80)
+    print()
+    
+    print("📌 COMMON INDUSTRY MAPPINGS:")
+    industry_mappings = {
+        "Accounting Services": "B2B Services",
+        "Marketing Agency": "B2B Services",
+        "Consulting Services": "B2B Services",
+        "Cybersecurity": "B2B Software & Tech",
+        "CRM Software": "B2B Software & Tech",
+        "Marketing Automation Software": "B2B Software & Tech",
+        "Healthcare": "Health & Wellness",
+        "Pharmaceuticals": "Health & Wellness",
+        "Hotels, Lodging, Resorts and Cruises": "Food, Hospitality & Travel",
+        "Restaurants, Food & Beverage": "Food, Hospitality & Travel",
+        "Real Estate": "Finance, Insurance & Real Estate",
+        "Insurance": "Finance, Insurance & Real Estate"
+    }
+    
+    for specific, parent in industry_mappings.items():
+        print(f"   '{specific}' → '{parent}'")
+    print()
+    
+    print("📌 COMMON PAGE TYPE MAPPINGS:")
+    page_mappings = {
+        "Homepage": "Awareness & Discovery",
+        "Blog / Content": "Awareness & Discovery",
+        "Features Page": "Awareness & Discovery",
+        "Pricing Page": "Consideration & Evaluation",
+        "Demo Squeeze": "Consideration & Evaluation",
+        "Product Page (PDP)": "Consideration & Evaluation",
+        "Checkout": "Conversion",
+        "Contact Sales": "Conversion",
+        "Signup": "Conversion",
+        "Login": "Internal & Navigation",
+        "Navigation": "Internal & Navigation",
+        "Thank You": "Post-Conversion & Other"
+    }
+    
+    for specific, parent in page_mappings.items():
+        print(f"   '{specific}' → '{parent}'")
+    print()
+    
+    print("📌 COMMON CONVERSION TYPE MAPPINGS:")
+    conversion_mappings = {
+        "Request Demo/Contact Sales": "High-Intent Lead Gen",
+        "Start Free Trial/Signup": "High-Intent Lead Gen",
+        "See Pricing/Request Quote": "High-Intent Lead Gen",
+        "Buy Now": "Direct Purchase",
+        "Reservation / Booking": "Direct Purchase",
+        "Subscription (No Free Trial)": "Direct Purchase",
+        "Download Asset / App": "Info/Content Lead Gen",
+        "Register for Webinar/Event": "Info/Content Lead Gen",
+        "Subscribe to Newsletter/Mailing List": "Info/Content Lead Gen",
+        "Find a Branch/Seller/Provider": "Location Search",
+        "Donate": "Non-Profit/Community"
+    }
+    
+    for specific, parent in conversion_mappings.items():
+        print(f"   '{specific}' → '{parent}'")
+    print()
+
+
+def benefits_summary():
+    """
+    Summary of benefits from the new mapping feature.
+    """
+    print("=" * 80)
+    print("✨ BENEFITS OF AUTOMATIC MAPPING")
+    print("=" * 80)
+    print()
+    
+    benefits = [
+        "✅ Send your own specific categorization (339 industries supported)",
+        "✅ No need to learn or memorize parent group names",
+        "✅ API handles conversion automatically",
+        "✅ Response shows both original and mapped values",
+        "✅ Backward compatible - parent groups still work",
+        "✅ More accurate categorization possible",
+        "✅ Easier integration with existing systems",
+        "✅ Better tracking of what was actually provided vs used"
+    ]
+    
+    for benefit in benefits:
+        print(f"   {benefit}")
+    print()
+
+
+if __name__ == "__main__":
+    print("\n")
+    print("🚀 A/B TEST PREDICTOR API - AUTOMATIC MAPPING DEMO")
+    print("\n")
+    
+    # Show mapping reference
+    mapping_reference_guide()
+    
+    # Show benefits
+    benefits_summary()
+    
+    print("=" * 80)
+    print("USAGE EXAMPLES")
+    print("=" * 80)
+    print()
+    
+    print("ℹ️  NOTE: The following examples show the structure.")
+    print("   To run them, uncomment the function calls and provide valid image paths.")
+    print()
+    
+    # Uncomment these to run actual predictions:
+    # predict_ab_test_with_specific_values()
+    # predict_ab_test_with_parent_groups()
+    # batch_predictions_with_mixed_values()
+    
+    print("=" * 80)
+    print("STATISTICS")
+    print("=" * 80)
+    print()
+    print("📊 Supported Values:")
+    print("   - 339 specific industry values → 14 parent groups")
+    print("   - 43 specific page type values → 5 parent groups")
+    print("   - 16 specific conversion type values → 6 parent groups")
+    print()
+    print("📂 For complete list, see: mapping.json")
+    print()
+    print("=" * 80)
+    print("DOCUMENTATION")
+    print("=" * 80)
+    print()
+    print("📖 Full API Documentation: API_DOCUMENTATION.md")
+    print("📝 Update Summary: MAPPING_UPDATE_SUMMARY.md")
+    print("🧪 Test Script: test_mapping_feature.py")
+    print()
+

MAPPING_UPDATE_SUMMARY.md

@@ -0,0 +1,185 @@
+# Automatic Value Mapping Update - Summary
+
+## Overview
+
+The A/B Test Predictor API has been enhanced with automatic value mapping functionality. The API now accepts both **specific values** and **parent group values** for Industry, Page Type, and Conversion Type inputs, automatically converting them using the `mapping.json` file before feeding to the model.
+
+## Changes Made
+
+### 1. Core Implementation (`app.py`)
+
+#### New Functions Added:
+- `load_value_mappings()`: Loads the `mapping.json` file at startup
+- `convert_to_parent_group()`: Converts specific values to their parent groups
+- `get_all_possible_values()`: Returns all possible values (both specific and grouped) for API documentation
+
+#### Updated Functions:
+- `predict_with_categorical_data()`: Now converts incoming specific values to parent groups before prediction
+  - Accepts original values from API
+  - Converts industry → grouped_industry
+  - Converts page_type → grouped_page_type  
+  - Converts conversion_type → grouped_conversion_type
+  - Returns both original and grouped values in response
+
+- `predict_single()`: Updated docstring to clarify it expects grouped values
+- `predict_batch()`: Added documentation noting it expects pre-grouped values in CSV
+
+#### Response Structure Enhancement:
+The API response now includes both `providedCategories` and `groupedCategories`:
+
+```json
+{
+  "predictionResults": { ... },
+  "providedCategories": {
+    "industry": "Cybersecurity",
+    "pageType": "Homepage",
+    "conversionType": "Request Demo/Contact Sales"
+  },
+  "groupedCategories": {
+    "industry": "B2B Software & Tech",
+    "pageType": "Awareness & Discovery",
+    "conversionType": "High-Intent Lead Gen"
+  },
+  "processingInfo": { ... }
+}
+```
+
+### 2. UI Updates (Gradio Interface)
+
+Updated the "🎯 API Prediction" tab description to explain:
+- API accepts both specific and parent group values
+- Automatic conversion happens behind the scenes
+- Model uses parent groups internally
+
+### 3. Documentation Updates (`API_DOCUMENTATION.md`)
+
+Added comprehensive documentation for the new mapping feature:
+- **New Section**: "🔄 Automatic Value Mapping" explaining how it works
+- **Updated**: Valid Category Values sections with parent groups and example specific values
+- **Updated**: Response format to show both `providedCategories` and `groupedCategories`
+- **Added**: Mapping examples for Industry, Page Type, and Conversion Type
+- **Added**: Code examples showing usage with specific values
+
+## How It Works
+
+### Data Flow:
+1. **API receives request** with specific values (e.g., "Cybersecurity", "Homepage")
+2. **Mapping function** looks up values in `mapping.json`
+3. **Conversion happens** to parent groups (e.g., "B2B Software & Tech", "Awareness & Discovery")
+4. **Model processes** using parent group values
+5. **Response includes** both original and grouped values
+
+### Example Mappings:
+
+#### Industry:
+- `Accounting Services` → `B2B Services`
+- `Cybersecurity` → `B2B Software & Tech`
+- `Healthcare` → `Health & Wellness`
+- 200+ specific industries supported
+
+#### Page Type:
+- `Homepage` → `Awareness & Discovery`
+- `Pricing Page` → `Consideration & Evaluation`
+- `Checkout` → `Conversion`
+- `Login` → `Internal & Navigation`
+
+#### Conversion Type:
+- `Request Demo/Contact Sales` → `High-Intent Lead Gen`
+- `Buy Now` → `Direct Purchase`
+- `Download Asset / App` → `Info/Content Lead Gen`
+
+## API Usage Examples
+
+### Before (only parent groups accepted):
+```python
+result = client.predict(
+    "control.jpg",
+    "variant.jpg",
+    "SaaS",
+    "B2B",
+    "High-Intent Lead Gen",        # Had to know parent group
+    "B2B Software & Tech",          # Had to know parent group
+    "Awareness & Discovery",        # Had to know parent group
+    api_name="/predict_with_categorical_data"
+)
+```
+
+### After (accepts specific values):
+```python
+result = client.predict(
+    "control.jpg",
+    "variant.jpg",
+    "SaaS",
+    "B2B",
+    "Request Demo/Contact Sales",   # Specific value (auto-converted)
+    "Cybersecurity",                # Specific value (auto-converted)
+    "Homepage",                     # Specific value (auto-converted)
+    api_name="/predict_with_categorical_data"
+)
+```
+
+## Benefits
+
+1. **🎯 More Flexible Input**: Accept detailed, specific categorizations
+2. **🔄 Automatic Processing**: No need for clients to pre-process data
+3. **📊 Transparency**: Both original and grouped values returned
+4. **✅ Backward Compatible**: Still accepts parent group values directly
+5. **🛠️ Easy Integration**: Clients can send their own categorization system
+
+## Files Modified
+
+1. `/app.py` - Core application logic
+2. `/API_DOCUMENTATION.md` - Updated API documentation
+3. `/mapping.json` - Reference file (already existed, now actively used)
+
+## Testing Recommendations
+
+1. Test with parent group values (should work as before)
+2. Test with specific values (should auto-convert)
+3. Test with mixed values (some specific, some parent groups)
+4. Verify response includes both `providedCategories` and `groupedCategories`
+5. Test edge cases:
+   - Unknown values (should return as-is with warning)
+   - Case sensitivity
+   - Values with special characters
+
+## Deployment Notes
+
+- **No Breaking Changes**: Existing API calls with parent groups still work
+- **New Feature**: Specific value support is additive
+- **Dependencies**: Requires `mapping.json` file to be present
+- **Backward Compatible**: All existing integrations continue working
+
+## Version Info
+
+- **Update Date**: October 31, 2025
+- **API Version**: 1.1 (backward compatible with 1.0)
+- **Model Version**: Unchanged (still GGG Enhanced)
+
+## Future Enhancements
+
+Potential improvements for future versions:
+1. Add validation endpoint to check if a value will be mapped
+2. Return mapping confidence scores
+3. Support for custom mapping files
+4. API endpoint to retrieve all possible values
+5. Fuzzy matching for close-but-not-exact values
+
+## Example Logs
+
+When using the updated API, you'll see logs like:
+```
+📋 Original categories from API: SaaS | B2B | Request Demo/Contact Sales | Cybersecurity | Homepage
+✅ Mapped 'Request Demo/Contact Sales' -> 'High-Intent Lead Gen'
+✅ Mapped 'Cybersecurity' -> 'B2B Software & Tech'
+✅ Mapped 'Homepage' -> 'Awareness & Discovery'
+📋 Mapped to parent groups: SaaS | B2B | High-Intent Lead Gen | B2B Software & Tech | Awareness & Discovery
+```
+
+---
+
+**For Questions or Issues:**
+- Review the updated `API_DOCUMENTATION.md`
+- Check `mapping.json` for complete list of supported values
+- Verify your input values match the expected format (case-sensitive)
+

QUICK_START_GUIDE.md

@@ -0,0 +1,84 @@
+# A/B Test Predictor - Quick Start Guide
+
+## 🚀 Get Started in 3 Steps
+
+### 1. Install
+
+```bash
+pip install gradio-client
+```
+
+### 2. Predict
+
+```python
+from gradio_client import Client
+
+client = Client("SpiralyzeLLC/ABTestPredictor")
+
+result = client.predict(
+    "control.jpg",           # Your control image
+    "variant.jpg",           # Your variant image
+    "SaaS",                  # Business Model
+    "B2B",                   # Customer Type
+    "High-Intent Lead Gen",  # Conversion Type
+    "B2B Software & Tech",   # Industry
+    "Awareness & Discovery", # Page Type
+    api_name="/predict_with_categorical_data"
+)
+```
+
+### 3. View Results
+
+```python
+print(f"Win Probability: {result['predictionResults']['probability']}")
+print(f"Confidence: {result['predictionResults']['modelConfidence']}%")
+
+if float(result['predictionResults']['probability']) > 0.5:
+    print("🎉 Variant predicted to WIN!")
+else:
+    print("⚠️ Control predicted to win")
+```
+
+## 📋 Input Parameters
+
+| Parameter | Values |
+|-----------|--------|
+| **Business Model** | `E-Commerce`, `Lead Generation`, `Other*`, `SaaS` |
+| **Customer Type** | `B2B`, `B2C`, `Both`, `Other*` |
+| **Conversion Type** | `Direct Purchase`, `High-Intent Lead Gen`, `Info/Content Lead Gen`, `Location Search`, `Non-Profit/Community`, `Other Conversion` |
+| **Industry** | `Automotive & Transportation`, `B2B Services`, `B2B Software & Tech`, `Consumer Services`, `Consumer Software & Apps`, `Education`, `Finance, Insurance & Real Estate`, `Food, Hospitality & Travel`, `Health & Wellness`, `Industrial & Manufacturing`, `Media & Entertainment`, `Non-Profit & Government`, `Other`, `Retail & E-commerce` |
+| **Page Type** | `Awareness & Discovery`, `Consideration & Evaluation`, `Conversion`, `Internal & Navigation`, `Post-Conversion & Other` |
+
+## 📊 Response
+
+```json
+{
+  "predictionResults": {
+    "probability": "0.682",          // >0.5 = Variant wins
+    "modelConfidence": "66.1",       // Accuracy % for this category
+    "trainingDataSamples": 14634,    // Training data size
+    "totalPredictions": 1626,        // Total test predictions
+    "correctPredictions": 1074       // Correct predictions
+  }
+}
+```
+
+## 🌐 Or Use Web Interface
+
+Visit: **https://huggingface.co/spaces/SpiralyzeLLC/ABTestPredictor**
+
+1. Upload images
+2. Select categories
+3. Click "Predict"
+4. Get instant results!
+
+## 📖 Full Documentation
+
+For complete API reference, error handling, and advanced examples:
+
+👉 See **[API_DOCUMENTATION.md](API_DOCUMENTATION.md)**
+
+---
+
+**Need Help?** Check [Common Issues](API_DOCUMENTATION.md#-common-issues) in the full docs.
+

README.md

@@ -74,10 +74,29 @@ Advanced A/B testing outcome predictor using multimodal AI analysis combining:
 
 ## 📡 API Usage
 
-See `API_USAGE_UPDATED.md` for detailed API documentation including:
-- Input parameters and their valid values
-- Response format and field descriptions
-- Example usage code
-- Confidence scoring methodology
+### Quick Start
+```python
+from gradio_client import Client
+
+client = Client("SpiralyzeLLC/ABTestPredictor")
+result = client.predict(
+    "control.jpg", "variant.jpg",
+    "SaaS", "B2B", "High-Intent Lead Gen",
+    "B2B Software & Tech", "Awareness & Discovery",
+    api_name="/predict_with_categorical_data"
+)
+```
+
+### 📚 Documentation
+
+- **[QUICK_START_GUIDE.md](QUICK_START_GUIDE.md)** - Get started in 3 steps
+- **[API_DOCUMENTATION.md](API_DOCUMENTATION.md)** - Complete API reference with examples in Python, JavaScript, and cURL
+- **[API_USAGE_UPDATED.md](API_USAGE_UPDATED.md)** - Technical details and migration notes
+
+### 🌐 Web Interface
+
+Use the interactive interface: **https://huggingface.co/spaces/SpiralyzeLLC/ABTestPredictor**
+
+---
 
 Built with ❤️ using Gradio, PyTorch, Transformers, and Hugging Face.

UPDATE_NOTES.md

@@ -0,0 +1,153 @@
+# 🎯 Automatic Value Mapping - Update Complete
+
+## ✅ What Was Implemented
+
+The A/B Test Predictor API now supports **automatic value mapping** for three key inputs:
+1. **Industry** - Converts 339 specific industries to 14 parent groups
+2. **Page Type** - Converts 43 specific page types to 5 parent groups  
+3. **Conversion Type** - Converts 16 specific conversion types to 6 parent groups
+
+## 🔄 How It Works
+
+### Before This Update:
+```python
+# You HAD to use parent groups
+result = client.predict(
+    "control.jpg", "variant.jpg",
+    "SaaS", "B2B",
+    "High-Intent Lead Gen",      # Parent group (required)
+    "B2B Software & Tech",        # Parent group (required)
+    "Awareness & Discovery",      # Parent group (required)
+    api_name="/predict_with_categorical_data"
+)
+```
+
+### After This Update:
+```python
+# You CAN NOW use specific values
+result = client.predict(
+    "control.jpg", "variant.jpg",
+    "SaaS", "B2B",
+    "Request Demo/Contact Sales",  # Specific value ✨
+    "Cybersecurity",                # Specific value ✨
+    "Homepage",                     # Specific value ✨
+    api_name="/predict_with_categorical_data"
+)
+
+# API automatically converts to:
+# "Request Demo/Contact Sales" → "High-Intent Lead Gen"
+# "Cybersecurity" → "B2B Software & Tech"
+# "Homepage" → "Awareness & Discovery"
+```
+
+## 📊 Response Format
+
+The API now returns both the original values you provided AND the grouped values used by the model:
+
+```json
+{
+  "predictionResults": { ... },
+  "providedCategories": {
+    "industry": "Cybersecurity",
+    "pageType": "Homepage",
+    "conversionType": "Request Demo/Contact Sales"
+  },
+  "groupedCategories": {
+    "industry": "B2B Software & Tech",
+    "pageType": "Awareness & Discovery",
+    "conversionType": "High-Intent Lead Gen"
+  },
+  "processingInfo": { ... }
+}
+```
+
+## 📂 Files Modified
+
+1. **`app.py`**
+   - Added `load_value_mappings()` function
+   - Added `convert_to_parent_group()` function
+   - Updated `predict_with_categorical_data()` to handle mapping
+   - Added `get_all_possible_values()` helper function
+   - Enhanced response to include both provided and grouped categories
+
+2. **`API_DOCUMENTATION.md`**
+   - Added "🔄 Automatic Value Mapping" section
+   - Updated category value lists with examples
+   - Updated response format documentation
+   - Added mapping examples and use cases
+
+3. **`mapping.json`**
+   - Already existed, now actively used by the API
+   - Contains all 339 industries, 43 page types, 16 conversion types
+
+## 🧪 Testing
+
+Created test files to verify functionality:
+- `test_mapping_feature.py` - Unit tests (7/7 passed ✅)
+- `COMPLETE_EXAMPLE_WITH_MAPPING.py` - Usage examples and demos
+
+## ✨ Benefits
+
+1. **More Flexible**: Accept 339+ specific values instead of just 14 parent groups
+2. **Easier Integration**: Use your existing categorization system
+3. **Backward Compatible**: Parent groups still work exactly as before
+4. **Transparent**: See both original and mapped values in response
+5. **Automatic**: No preprocessing needed on your end
+
+## 📈 Supported Values
+
+| Category | Parent Groups | Specific Values | Examples |
+|----------|--------------|----------------|----------|
+| Industry | 14 | 339 | "Accounting Services", "Cybersecurity", "Healthcare" |
+| Page Type | 5 | 43 | "Homepage", "Pricing Page", "Checkout" |
+| Conversion Type | 6 | 16 | "Request Demo", "Buy Now", "Download Asset" |
+
+## 🔍 Example Mappings
+
+**Industry:**
+- `Accounting Services` → `B2B Services`
+- `Cybersecurity` → `B2B Software & Tech`
+- `Healthcare` → `Health & Wellness`
+
+**Page Type:**
+- `Homepage` → `Awareness & Discovery`
+- `Pricing Page` → `Consideration & Evaluation`
+- `Checkout` → `Conversion`
+
+**Conversion Type:**
+- `Request Demo/Contact Sales` → `High-Intent Lead Gen`
+- `Buy Now` → `Direct Purchase`
+- `Download Asset / App` → `Info/Content Lead Gen`
+
+## 📖 Documentation
+
+- **API Documentation**: See `API_DOCUMENTATION.md`
+- **Detailed Summary**: See `MAPPING_UPDATE_SUMMARY.md`
+- **Complete Examples**: See `COMPLETE_EXAMPLE_WITH_MAPPING.py`
+- **Unit Tests**: See `test_mapping_feature.py`
+- **Mapping Data**: See `mapping.json`
+
+## 🚀 Deployment
+
+- **Status**: Ready to deploy ✅
+- **Breaking Changes**: None (fully backward compatible)
+- **Requirements**: `mapping.json` must be present in root directory
+- **Version**: API v1.1
+
+## ⚠️ Important Notes
+
+1. **Values are case-sensitive**: "Cybersecurity" works, "cybersecurity" doesn't
+2. **Exact matches required**: Use exact strings from `mapping.json`
+3. **Unknown values**: Will be passed through as-is (with warning logged)
+4. **Business Model & Customer Type**: Not mapped (no changes needed)
+
+## 🎉 Ready to Use
+
+The update is complete and tested. The API now accepts both specific and parent group values, making it much more flexible and easier to integrate with your existing systems!
+
+---
+
+**Updated**: October 31, 2025  
+**Version**: 1.1  
+**Backward Compatible**: Yes ✅
+

app.py

@@ -187,6 +187,61 @@ if not os.path.exists(CAT_MAPPINGS_SAVE_PATH):
 with open(CAT_MAPPINGS_SAVE_PATH, 'r') as f:
     category_mappings = json.load(f)
 
+# Load mapping.json for converting specific values to parent groups
+def load_value_mappings():
+    """Load mapping.json for converting industry, page_type, and conversion_type to parent groups"""
+    try:
+        script_dir = os.path.dirname(os.path.abspath(__file__))
+        mapping_file = os.path.join(script_dir, 'mapping.json')
+        
+        print(f"📂 Looking for mapping file at: {mapping_file}")
+        
+        if not os.path.exists(mapping_file):
+            print(f"⚠️ Mapping file not found, trying fallback location...")
+            mapping_file = 'mapping.json'
+        
+        with open(mapping_file, 'r') as f:
+            mapping_data = json.load(f)
+            print(f"✅ Successfully loaded mapping.json with {len(mapping_data)} mapping types")
+            return mapping_data
+    except Exception as e:
+        print(f"⚠️ Error loading mapping.json: {e}")
+        import traceback
+        traceback.print_exc()
+        return {}
+
+def convert_to_parent_group(value, mapping_type, value_mappings):
+    """
+    Convert a specific value to its parent group using mapping.json
+    
+    Args:
+        value: The specific value (e.g., "Accounting Services")
+        mapping_type: Type of mapping ("industry_mappings", "page_type_mappings", "conversion_type_mappings")
+        value_mappings: The loaded mapping.json data
+    
+    Returns:
+        The parent group name (e.g., "B2B Services")
+    """
+    if mapping_type not in value_mappings:
+        print(f"⚠️ Mapping type '{mapping_type}' not found in mapping.json")
+        return value
+    
+    mappings = value_mappings[mapping_type]
+    
+    # Search for the value in all parent groups
+    for parent_group, child_values in mappings.items():
+        if value in child_values:
+            print(f"✅ Mapped '{value}' -> '{parent_group}'")
+            return parent_group
+    
+    # If not found, check if the value itself is a parent group
+    if value in mappings.keys():
+        print(f"ℹ️ '{value}' is already a parent group")
+        return value
+    
+    print(f"⚠️ Value '{value}' not found in {mapping_type}, returning as-is")
+    return value
+
 # Load confidence scores directly from JSON file
 def load_confidence_scores():
     """Load confidence scores from confidence_scores.json"""
@@ -227,6 +282,18 @@ def load_confidence_scores():
         traceback.print_exc()
         return {}
 
+# Load value mappings for converting specific values to parent groups
+try:
+    print("=" * 50)
+    print("🚀 LOADING VALUE MAPPINGS...")
+    print("=" * 50)
+    value_mappings = load_value_mappings()
+    print(f"✅ Value mappings loaded successfully")
+    print("=" * 50)
+except Exception as e:
+    print(f"⚠️ Error loading value mappings: {e}")
+    value_mappings = {}
+
 # Load confidence scores
 try:
     print("=" * 50)
@@ -373,10 +440,17 @@ def predict_with_categorical_data(control_image, variant_image, business_model,
     
     start_time = time.time()
     
-    print(f"📋 Using provided categories: {business_model} | {customer_type} | {conversion_type} | {industry} | {page_type}")
+    print(f"📋 Original categories from API: {business_model} | {customer_type} | {conversion_type} | {industry} | {page_type}")
+    
+    # Convert specific values to parent groups using mapping.json
+    grouped_conversion_type = convert_to_parent_group(conversion_type, "conversion_type_mappings", value_mappings)
+    grouped_industry = convert_to_parent_group(industry, "industry_mappings", value_mappings)
+    grouped_page_type = convert_to_parent_group(page_type, "page_type_mappings", value_mappings)
     
-    # Run the prediction with provided categorical data
-    prediction_result = predict_single(control_image, variant_image, business_model, customer_type, conversion_type, industry, page_type)
+    print(f"📋 Mapped to parent groups: {business_model} | {customer_type} | {grouped_conversion_type} | {grouped_industry} | {grouped_page_type}")
+    
+    # Run the prediction with grouped categorical data
+    prediction_result = predict_single(control_image, variant_image, business_model, customer_type, grouped_conversion_type, grouped_industry, grouped_page_type)
     
     # Create comprehensive result with prediction and confidence data
     result = {
@@ -388,9 +462,16 @@ def predict_with_categorical_data(control_image, variant_image, business_model,
             "industry": industry,
             "pageType": page_type
         },
+        "groupedCategories": {
+            "businessModel": business_model,
+            "customerType": customer_type,
+            "conversionType": grouped_conversion_type,
+            "industry": grouped_industry,
+            "pageType": grouped_page_type
+        },
         "processingInfo": {
             "totalProcessingTime": f"{time.time() - start_time:.2f}s",
-            "confidenceSource": f"{industry} | {page_type}"
+            "confidenceSource": f"{grouped_industry} | {grouped_page_type}"
         }
     }
     
@@ -398,7 +479,12 @@ def predict_with_categorical_data(control_image, variant_image, business_model,
 
 @spaces.GPU(duration=60)  # Maximum allowed duration on free tier
 def predict_single(control_image, variant_image, business_model, customer_type, conversion_type, industry, page_type):
-    """Orchestrates the prediction for a single pair of images and features."""
+    """
+    Orchestrates the prediction for a single pair of images and features.
+    
+    Note: This function expects GROUPED values for conversion_type, industry, and page_type.
+    If calling from API, use predict_with_categorical_data() which handles the conversion automatically.
+    """
     try:
         if control_image is None or variant_image is None:
             return {"Error": 1.0, "Please upload both images": 0.0}
@@ -488,9 +574,46 @@ def predict_single(control_image, variant_image, business_model, customer_type,
             "totalLosePrediction": 0
         }
 
+def get_all_possible_values():
+    """
+    Get all possible values (both specific and grouped) for industry, page_type, and conversion_type.
+    This is useful for API documentation and validation.
+    """
+    all_values = {
+        "industry": [],
+        "page_type": [],
+        "conversion_type": []
+    }
+    
+    # Get all industry values (both parent groups and specific values)
+    if "industry_mappings" in value_mappings:
+        for parent_group, child_values in value_mappings["industry_mappings"].items():
+            all_values["industry"].append(parent_group)
+            all_values["industry"].extend(child_values)
+    
+    # Get all page type values
+    if "page_type_mappings" in value_mappings:
+        for parent_group, child_values in value_mappings["page_type_mappings"].items():
+            all_values["page_type"].append(parent_group)
+            all_values["page_type"].extend(child_values)
+    
+    # Get all conversion type values
+    if "conversion_type_mappings" in value_mappings:
+        for parent_group, child_values in value_mappings["conversion_type_mappings"].items():
+            all_values["conversion_type"].append(parent_group)
+            all_values["conversion_type"].extend(child_values)
+    
+    return all_values
+
 @spaces.GPU
 def predict_batch(csv_path, control_img_dir, variant_img_dir, num_samples):
-    """Handles batch prediction from a CSV file."""
+    """
+    Handles batch prediction from a CSV file.
+    Note: CSV should contain grouped values (not specific values) for:
+    - grouped_conversion_type
+    - grouped_industry
+    - grouped_page_type
+    """
     if not all([csv_path, control_img_dir, variant_img_dir, num_samples]):
         return pd.DataFrame({"Error": ["Please fill in all fields."]})
     
@@ -519,7 +642,7 @@ def predict_batch(csv_path, control_img_dir, variant_img_dir, num_samples):
             if not v_path or not os.path.exists(v_path):
                 raise FileNotFoundError(f"Variant image not found: {v_path}")
 
-            # Get categorical features from the row
+            # Get categorical features from the row (expects grouped values in CSV)
             cat_features_from_row = [row[f] for f in CATEGORICAL_FEATURES]
             
             # Use the core prediction logic
@@ -561,7 +684,15 @@ with gr.Blocks() as iface:
 
     with gr.Tab("🎯 API Prediction"):
         gr.Markdown("### 📊 Predict with Categorical Data")
-        gr.Markdown("Upload images and provide categorical data for prediction:")
+        gr.Markdown("""
+        Upload images and provide categorical data for prediction.
+        
+        **Note:** For Industry, Page Type, and Conversion Type, you can provide either:
+        - Specific values (e.g., "Accounting Services") - will be automatically converted to parent group (e.g., "B2B Services")
+        - Parent group values (e.g., "B2B Services") - will be used directly
+        
+        The model uses parent groups internally, but the API accepts both for convenience.
+        """)
         
         with gr.Row():
             with gr.Column():

mapping.json

@@ -0,0 +1,456 @@
+{
+    "industry_mappings": {
+        "Automotive & Transportation": [
+            "Automotive Services",
+            "Transportation*"
+        ],
+        "B2B Services": [
+            "Accounting Services",
+            "Affiliate Marketing",
+            "Cleaning Services",
+            "Consulting Services",
+            "Creative Service Providers",
+            "Digital Marketing Services [DO NOT USE - Use Marketing Agency instead]",
+            "Enterprise Services",
+            "Events Planning",
+            "Funeral Related Services ",
+            "HR & Recruitment Agency",
+            "HR & Recruitment Software",
+            "Implementation Services Providers",
+            "Job Search",
+            "Law Firms & Legal Services",
+            "Marketing",
+            "Marketing Agency",
+            "Multimedia & Design Agencies",
+            "Printing",
+            "Research & Development",
+            "Research & Development Services",
+            "Solution Consulting Providers",
+            "Translation & Linguistic Services"
+        ],
+        "B2B Software & Tech": [
+            "AI & Machine Learning Operationalization (MLOps) Software",
+            "AI Sales Assistant Software",
+            "API Management Tools",
+            "Account-Based Marketing Software",
+            "Accounting & Financial Software",
+            "Accounting & Financial Software ",
+            "Adblocking Software",
+            "Address Verification Tools",
+            "Advertiser Campaign Management Software",
+            "Application Development Software",
+            "Asset Management Software",
+            "Auction ",
+            "Audio Editing Software",
+            "Augmented Reality (AR) Software",
+            "Automotive & Transportation Software",
+            "Blockchain Software",
+            "Business Card Scanning Software",
+            "Business Intelligence Software",
+            "Business Intelligence Software ",
+            "Business Scheduling Software",
+            "CAD Software",
+            "Call & Contact Center Software",
+            "Carbon Accounting Software",
+            "Child Care Software",
+            "Church Management Software",
+            "Cloud-Based Software",
+            "Competitive Intelligence Software",
+            "Confidentiality Software",
+            "Construction Software",
+            "Content & Collaboration Software ",
+            "Content Management System (CMS) Tools & Software",
+            "Content Marketing Software",
+            "Continuous Testing Platforms Software",
+            "Contract Analytics Software",
+            "Contract Management Software",
+            "Contractor Platform",
+            "Conversational Intelligence Software ",
+            "Conversational Marketing Software",
+            "Conversion Rate Optimization (CRO) Software",
+            "Corporate Social Responsibility (CSR) Software",
+            "Customer Data Platforms (CDP)",
+            "Customer Relationship Management (CRM) Software ",
+            "Customer Service Software",
+            "Customer Success Software",
+            "Cybersecurity",
+            "Data Analytics",
+            "Data Destruction Software",
+            "Data Governance Software",
+            "Data Integration Software",
+            "Data Labeling Software",
+            "Data Management Platform (DMP)",
+            "Data Quality Tools",
+            "Data Recovery Software ",
+            "Data Science and Machine Learning Platforms",
+            "DataOps Platform",
+            "Database & File Management Software ",
+            "Demand Generation Software",
+            "Deployment Software",
+            "DevOps Software",
+            "DevSecOps Software",
+            "Diagramming Software",
+            "Digital Adoption Platform",
+            "Digital Analytics Software",
+            "Digital Experience Platform",
+            "Digital Signage Software",
+            "Direct Mail Automation Software",
+            "Disk Cleanup Software",
+            "Distribution Software",
+            "Document Generation Software",
+            "Document Scanning Software",
+            "E-Commerce Software",
+            "E-Commerce Software ",
+            "E-Signature Software",
+            "E-mail Signature Software",
+            "Education Management Software",
+            "Email Marketing Software",
+            "Email Verification Software",
+            "Emergency Medical Services Software ",
+            "Emergency Notification Software",
+            "Employee Scheduling Software",
+            "Engineering Software ",
+            "Enterprise Resource Planning (ERP) Software ",
+            "Enterprise SaaS",
+            "Enterprise Search Software",
+            "Entity Management Software",
+            "Environmental, Social, and Governance (ESG) Reporting Software",
+            "Event Management Software",
+            "Event Stream Processing Software",
+            "Experience Management Software",
+            "Feature Management Software",
+            "Field Sales Software",
+            "Field Service Management Software",
+            "Fitness Software",
+            "Fleet Tracking Software",
+            "Fleet Tracking Software ",
+            "Fundraising Software ",
+            "Generative AI Software",
+            "Governance, Risk and Compliance (GRC) Platform",
+            "Graphic Design Software",
+            "Gym Management Software",
+            "Healthcare Management Software",
+            "Healthcare Software",
+            "Help Desk Software",
+            "Hospitality Software",
+            "IT Management Software",
+            "IT Services ",
+            "Identity Management Software",
+            "Identity Verification & Anti-Money Laundering Software",
+            "Inbound Call Tracking Software",
+            "Incident Management Software",
+            "Integrated Development Environments",
+            "Internal Communications Software",
+            "Internet Service Providers",
+            "Inventory Management Software",
+            "IoT Device Management Platform",
+            "Knowledge Management Software",
+            "Learning Management Software (LMS)",
+            "Legal Software",
+            "Legal Software ",
+            "Life Sciences Software",
+            "Live Chat Software",
+            "Load Balancing Software",
+            "Local Marketing Software",
+            "Location Intelligence Software",
+            "Marketing Analytics Software",
+            "Marketing Automation Software",
+            "Message Queue (MQ) Software",
+            "Microsoft Channel Partners",
+            "Mobile App Development ",
+            "Mobile Forms Automation Software",
+            "Monitoring Software",
+            "Networking Software ",
+            "Nonprofit Software",
+            "Note-Taking Management Software ",
+            "On-Demand Delivery Software",
+            "Online Appointment Scheduling Software ",
+            "Online Community Management Software",
+            "Online Form Builder Software ",
+            "Online Marketplace Optimization Tool",
+            "Online Reputation Management Software",
+            "Org Chart Software",
+            "Other Development Software",
+            "POS Software",
+            "Partner Management Software",
+            "Payroll Software",
+            "Podcast Hosting Platform",
+            "Pop-Up Builder Software",
+            "Presentation Software",
+            "Print Management Software",
+            "Privacy Software",
+            "Process Automation Software ",
+            "Procurement Software",
+            "Productivity Bots Software",
+            "Professional Services Automation Software",
+            "Project, Portfolio, & Program Management Software",
+            "Property Management Software",
+            "Public Relations (PR) Software",
+            "Public Safety Software",
+            "Public Sector Software",
+            "Quality Management Systems (QMS)",
+            "Real Estate Software",
+            "Regulatory Information Management (RIM) Systems",
+            "Remote Monitoring & Management (RMM) Software",
+            "Remote Support Software",
+            "Repository Management Software",
+            "Requirements Management Software",
+            "Research Software",
+            "Retail Software",
+            "Revenue Operations & Intelligence (RO&I) Software",
+            "Route Planning Software",
+            "SEO Software",
+            "SMS Marketing Software",
+            "SaaS Spend Management Software",
+            "Sales Acceleration Software",
+            "Sales Gamification",
+            "Sales Intelligence Software",
+            "Screen and Video Capture Software",
+            "Service Desk Software",
+            "Shipping Software ",
+            "Social Media Marketing Software ",
+            "Software Design Software",
+            "Software Testing Tools ",
+            "Spa and Salon Management Software",
+            "Space Management Software",
+            "Sports Software",
+            "Stock Media Software",
+            "Storage & System Management Software ",
+            "Supply Chain Management (SCM) Software ",
+            "Sustainability Management Software",
+            "Talent Management Software",
+            "Team Collaboration Software",
+            "Tech Development Tools",
+            "Technology",
+            "Text Analysis Software",
+            "Time Tracking Software",
+            "Transcription Software",
+            "URL Shortener",
+            "Video Conferencing Software",
+            "Video Email Software",
+            "Video Platform as a Service (VPaaS) Software",
+            "Video Software",
+            "Virtual Mailbox Software",
+            "Virtual Private Networks (VPN) ",
+            "VoIP (Voice over IP) Provider",
+            "Vulnerability Management Software ",
+            "Web Data Providers Software",
+            "Website Builder Software",
+            "Website Hosting",
+            "Whistleblowing Software",
+            "Workforce Management Software"
+        ],
+        "Consumer Services": [
+            "Consumer Services",
+            "Dating",
+            "Delivery Services ",
+            "Home & Office Security",
+            "Pets",
+            "Rental Services ",
+            "Weddings"
+        ],
+        "Consumer Software & Apps": [
+            "Consumer Software",
+            "Mobile Marketing Software",
+            "Personality Tests"
+        ],
+        "Education": [
+            "Education & Universities",
+            "Language Learning",
+            "Online Learning Platforms"
+        ],
+        "Finance, Insurance & Real Estate": [
+            "Cryptocurrency",
+            "Finance",
+            "Insurance",
+            "Quote Management Software",
+            "Real Estate",
+            "Transactional Email Software"
+        ],
+        "Food, Hospitality & Travel": [
+            "Airlines, Airports & Air Services ",
+            "Hotels, Lodging, Resorts and Cruises",
+            "Restaurants, Food & Beverage",
+            "Travel Agencies & Services",
+            "Travel Arrangement Software"
+        ],
+        "Health & Wellness": [
+            "Ancestry",
+            "Beauty & Cosmetics",
+            "Corporate Wellness Software",
+            "Elderly Care ",
+            "Fitness, Weight loss & Wellness ",
+            "Healthcare",
+            "Human Services Software",
+            "Medical Devices & Equipment ",
+            "Mental Health & Rehabilitation Facilities",
+            "Pharmaceuticals",
+            "Vitamins, Supplements & Health Stores",
+            "Water Testing"
+        ],
+        "Industrial & Manufacturing": [
+            "Aerospace & Defense ",
+            "Agriculture & Livestock",
+            "Construction",
+            "Energy, Electricity, Utilities & Waste",
+            "Freight & Logistics Services",
+            "Industrial Machinery & Equipment",
+            "Manufacturing",
+            "Minerals & Mining",
+            "Oil & Gas",
+            "Oil & Gas Software",
+            "Plastic, Packaging & Containers",
+            "Telecommunication "
+        ],
+        "Media & Entertainment": [
+            "Editor Software",
+            "Entertainment",
+            "Fine Art",
+            "Gaming & Gambling ",
+            "Magazines, Newspapers and News Services",
+            "Media & Internet",
+            "Museum",
+            "Music Production & Services",
+            "Photography & Photography Software",
+            "Social Media",
+            "Sports & Recreation ",
+            "Streaming Services ",
+            "Zoos, Amusement Parks & National Parks"
+        ],
+        "Non-Profit & Government": [
+            "Government Site",
+            "Holding Companies & Conglomerates",
+            "Non-Profit & Charitable Organizations ",
+            "Political Software",
+            "Professional / Membership Organizations",
+            "Religious Organizations",
+            "Surveys"
+        ],
+        "Other": [
+            "Adult Entertainment",
+            "Architecture & Interior Design ",
+            "Communication",
+            "Cycling ",
+            "Engineering",
+            "Expo Event Websites",
+            "General",
+            "Horoscope",
+            "Laboratory Software",
+            "Lottery",
+            "Marketplace Apps/Software",
+            "Other",
+            "Other*",
+            "Performing Arts Software",
+            "Personal Websites"
+        ],
+        "Retail & E-commerce": [
+            "Apparel & Accessories ",
+            "Appliances, Furniture, and Hardware Retail",
+            "Automobile Parts & Dealers",
+            "Boats & Submarines ",
+            "Books, Stationeries, & Office Supplies",
+            "Chemicals and Laboratory Equipment",
+            "Consignment",
+            "Consumer Electronics",
+            "Convenience Stores, Gas Stations & Liquor Stores",
+            "Department Stores, Malls, Shopping Centers & Superstores",
+            "Flowers, Gifts & Specialty Stores ",
+            "Gardening [DO NOT USE - USE LANDSCAPING INSTEAD]",
+            "Gardening, Landscaping & Plants",
+            "Hardware / DIY Tools",
+            "Home Improvement & Hardware Retail [DO NOT USE]",
+            "Hygiene Products",
+            "Jewelery ",
+            "Kitchenware & Tableware",
+            "Mom & Baby",
+            "Musical Instruments and Equipment",
+            "Retail ",
+            "Toys"
+        ]
+    },
+    "page_type_mappings": {
+        "Awareness & Discovery": [
+            "Blog / Content",
+            "Features Page",
+            "Homepage",
+            "Individual Resource Page",
+            "Organic Landing Page",
+            "Paid Landing Page (PLP)",
+            "Resource Listing",
+            "Solutions Page"
+        ],
+        "Consideration & Evaluation": [
+            "Calculator",
+            "Competitor Comparison",
+            "Demo Long Page",
+            "Demo Squeeze",
+            "Listing",
+            "Pricing Page",
+            "Pricing Squeeze",
+            "Product Comparison",
+            "Product Page (PDP)",
+            "Quote",
+            "Trial Long Page",
+            "Trial Squeeze",
+            "Webinar"
+        ],
+        "Conversion": [
+            "Booking",
+            "Checkout",
+            "Contact Sales",
+            "Contact Us",
+            "Donate",
+            "Quiz/Survey",
+            "Shopping Cart",
+            "Signup"
+        ],
+        "Internal & Navigation": [
+            "Internal Page",
+            "Locations / Map",
+            "Login",
+            "Navigation",
+            "Search",
+            "Sitewide"
+        ],
+        "Post-Conversion & Other": [
+            "About Us",
+            "Awards",
+            "Cancellation",
+            "Careers",
+            "In-App",
+            "Other",
+            "Support",
+            "Thank You"
+        ]
+    },
+    "conversion_type_mappings": {
+        "Direct Purchase": [
+            "Buy Now",
+            "Reservation / Booking",
+            "Subscription (No Free Trial)"
+        ],
+        "High-Intent Lead Gen": [
+            "Request Demo/Contact Sales",
+            "See Pricing/Request Quote",
+            "Start Free Trial/Signup"
+        ],
+        "Info/Content Lead Gen": [
+            "Download Asset / App",
+            "Register for Webinar/Event",
+            "Request Information",
+            "Subscribe to Newsletter/Mailing List"
+        ],
+        "Location Search": [
+            "Find a Branch/Seller/Provider"
+        ],
+        "Non-Profit/Community": [
+            "Donate",
+            "Leave a Review"
+        ],
+        "Other Conversion": [
+            "Link to Partner Product",
+            "Other",
+            "zz-Pending"
+        ]
+    }
+}

test_mapping_feature.py

@@ -0,0 +1,145 @@
+"""
+Test script to demonstrate the automatic value mapping feature.
+
+This script shows how the API now accepts both specific and parent group values
+for Industry, Page Type, and Conversion Type.
+"""
+
+import json
+
+# Load the mapping.json file
+with open('mapping.json', 'r') as f:
+    mappings = json.load(f)
+
+def convert_to_parent_group(value, mapping_type):
+    """Convert a specific value to its parent group"""
+    if mapping_type not in mappings:
+        return value
+    
+    mapping_dict = mappings[mapping_type]
+    
+    # Search for the value in all parent groups
+    for parent_group, child_values in mapping_dict.items():
+        if value in child_values:
+            return parent_group
+    
+    # If not found, check if it's already a parent group
+    if value in mapping_dict.keys():
+        return value
+    
+    return value
+
+# Test cases
+test_cases = [
+    {
+        "name": "Test 1: Specific Industry Value",
+        "input": "Accounting Services",
+        "mapping_type": "industry_mappings",
+        "expected": "B2B Services"
+    },
+    {
+        "name": "Test 2: Specific Page Type Value",
+        "input": "Homepage",
+        "mapping_type": "page_type_mappings",
+        "expected": "Awareness & Discovery"
+    },
+    {
+        "name": "Test 3: Specific Conversion Type Value",
+        "input": "Request Demo/Contact Sales",
+        "mapping_type": "conversion_type_mappings",
+        "expected": "High-Intent Lead Gen"
+    },
+    {
+        "name": "Test 4: Parent Group Value (should remain unchanged)",
+        "input": "B2B Software & Tech",
+        "mapping_type": "industry_mappings",
+        "expected": "B2B Software & Tech"
+    },
+    {
+        "name": "Test 5: Another Specific Industry",
+        "input": "Cybersecurity",
+        "mapping_type": "industry_mappings",
+        "expected": "B2B Software & Tech"
+    },
+    {
+        "name": "Test 6: Pricing Page Type",
+        "input": "Pricing Page",
+        "mapping_type": "page_type_mappings",
+        "expected": "Consideration & Evaluation"
+    },
+    {
+        "name": "Test 7: Buy Now Conversion",
+        "input": "Buy Now",
+        "mapping_type": "conversion_type_mappings",
+        "expected": "Direct Purchase"
+    }
+]
+
+print("=" * 80)
+print("TESTING AUTOMATIC VALUE MAPPING FEATURE")
+print("=" * 80)
+print()
+
+passed = 0
+failed = 0
+
+for test in test_cases:
+    result = convert_to_parent_group(test["input"], test["mapping_type"])
+    status = "✅ PASS" if result == test["expected"] else "❌ FAIL"
+    
+    if result == test["expected"]:
+        passed += 1
+    else:
+        failed += 1
+    
+    print(f"{status} - {test['name']}")
+    print(f"   Input: '{test['input']}'")
+    print(f"   Expected: '{test['expected']}'")
+    print(f"   Got: '{result}'")
+    print()
+
+print("=" * 80)
+print(f"SUMMARY: {passed} passed, {failed} failed out of {len(test_cases)} tests")
+print("=" * 80)
+print()
+
+# Show some statistics
+print("MAPPING STATISTICS:")
+print(f"- Total Industry Parent Groups: {len(mappings['industry_mappings'])}")
+print(f"- Total Specific Industries: {sum(len(v) for v in mappings['industry_mappings'].values())}")
+print(f"- Total Page Type Parent Groups: {len(mappings['page_type_mappings'])}")
+print(f"- Total Specific Page Types: {sum(len(v) for v in mappings['page_type_mappings'].values())}")
+print(f"- Total Conversion Type Parent Groups: {len(mappings['conversion_type_mappings'])}")
+print(f"- Total Specific Conversion Types: {sum(len(v) for v in mappings['conversion_type_mappings'].values())}")
+print()
+
+# Show example API usage
+print("=" * 80)
+print("EXAMPLE API USAGE:")
+print("=" * 80)
+print()
+print("from gradio_client import Client")
+print()
+print('client = Client("SpiralyzeLLC/ABTestPredictor")')
+print()
+print("# Now you can use SPECIFIC values:")
+print("result = client.predict(")
+print('    "control.jpg",')
+print('    "variant.jpg",')
+print('    "SaaS",                           # Business Model')
+print('    "B2B",                            # Customer Type')
+print('    "Request Demo/Contact Sales",     # Specific conversion type ✨')
+print('    "Cybersecurity",                  # Specific industry ✨')
+print('    "Homepage",                       # Specific page type ✨')
+print('    api_name="/predict_with_categorical_data"')
+print(')')
+print()
+print("# The API will automatically convert to:")
+print('# - "Request Demo/Contact Sales" → "High-Intent Lead Gen"')
+print('# - "Cybersecurity" → "B2B Software & Tech"')
+print('# - "Homepage" → "Awareness & Discovery"')
+print()
+print("# Response includes both original and grouped values:")
+print('# result["providedCategories"]  # Your original input')
+print('# result["groupedCategories"]   # What the model used')
+