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

pip install gradio-client pillow

Basic Example

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

{
  "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:

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:

{
  "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

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

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

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

#!/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:

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)

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)

# ✅ 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

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 section
• Verify your inputs match the 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