API_DOCUMENTATION.md

# 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