API_KEYS_FOR_COLLEAGUE.md

# A/B Test Predictor API - Integration Guide for Backend

## API Endpoint
```
https://nitish-spz-abtestpredictorv2.hf.space
```

## Available Endpoints

### 1. Auto-Categorization Prediction
**Endpoint:** `/call/predict_with_auto_categorization`
**Method:** POST
**Description:** Automatically categorizes images and predicts A/B test winner

**Request Format:**
```json
{
  "data": [
    {
      "path": "uploaded_control_image_path",
      "url": "https://nitish-spz-abtestpredictorv2.hf.space/file=uploaded_control_image_path",
      "orig_name": "control.jpg",
      "size": 123456,
      "mime_type": "image/jpeg",
      "meta": { "_type": "gradio.FileData" }
    },
    {
      "path": "uploaded_variant_image_path", 
      "url": "https://nitish-spz-abtestpredictorv2.hf.space/file=uploaded_variant_image_path",
      "orig_name": "variant.jpg",
      "size": 789012,
      "mime_type": "image/jpeg",
      "meta": { "_type": "gradio.FileData" }
    }
  ]
}
```

**Response Format:**
```json
{
  "predictionResults": {
    "probability": "0.041",
    "modelConfidence": "75.5%",
    "trainingDataSamples": 477,
    "totalPredictions": 53,
    "correctPredictions": 40,
    "totalWinPrediction": 24,
    "totalLosePrediction": 29
  },
  "autoDetectedCategories": {
    "businessModel": "SaaS",
    "customerType": "B2B", 
    "conversionType": "High-Intent Lead Gen",
    "industry": "B2B Software & Tech",
    "pageType": "Conversion"
  },
  "detectedPattern": {
    "pattern": "Double Column Form",
    "description": "The variant implements a 'Double Column Form' modification"
  },
  "processingInfo": {
    "totalProcessingTime": "32.36s",
    "aiCategorization": "Perplexity Sonar Reasoning Pro",
    "patternDetection": "Gemini Pro Vision", 
    "confidenceSource": "B2B Software & Tech | Conversion",
    "totalPatternsAnalyzed": 359
  }
}
```

### 2. Manual Categorization Prediction
**Endpoint:** `/call/predict_single`
**Method:** POST
**Description:** Predicts A/B test winner with manually provided categories

**Request Format:**
```json
{
  "data": [
    {
      "path": "uploaded_control_image_path",
      "url": "https://nitish-spz-abtestpredictorv2.hf.space/file=uploaded_control_image_path",
      "orig_name": "control.jpg",
      "size": 123456,
      "mime_type": "image/jpeg",
      "meta": { "_type": "gradio.FileData" }
    },
    {
      "path": "uploaded_variant_image_path",
      "url": "https://nitish-spz-abtestpredictorv2.hf.space/file=uploaded_variant_image_path", 
      "orig_name": "variant.jpg",
      "size": 789012,
      "mime_type": "image/jpeg",
      "meta": { "_type": "gradio.FileData" }
    },
    "E-Commerce",
    "B2C", 
    "Direct Purchase",
    "Retail & E-commerce",
    "Conversion"
  ]
}
```

**Response Format:**
```json
{
  "probability": "0.987",
  "modelConfidence": "82.3%",
  "trainingDataSamples": 1205,
  "totalPredictions": 120,
  "correctPredictions": 98,
  "totalWinsPrediction": 67,
  "totalLosePrediction": 53
}
```

## File Upload Process

### Step 1: Upload Images
**Endpoint:** `/upload`
**Method:** POST
**Content-Type:** multipart/form-data

```python
import requests

# Upload control image
with open('control.jpg', 'rb') as f:
    files = {'files': f}
    response = requests.post('https://nitish-spz-abtestpredictorv2.hf.space/upload', files=files)
    control_path = response.json()[0]

# Upload variant image  
with open('variant.jpg', 'rb') as f:
    files = {'files': f}
    response = requests.post('https://nitish-spz-abtestpredictorv2.hf.space/upload', files=files)
    variant_path = response.json()[0]
```

### Step 2: Make Prediction Request
```python
import requests

# Prepare FileData objects
control_file_data = {
    "path": control_path,
    "url": f"https://nitish-spz-abtestpredictorv2.hf.space/file={control_path}",
    "orig_name": "control.jpg",
    "size": 123456,
    "mime_type": "image/jpeg",
    "meta": { "_type": "gradio.FileData" }
}

variant_file_data = {
    "path": variant_path,
    "url": f"https://nitish-spz-abtestpredictorv2.hf.space/file={variant_path}",
    "orig_name": "variant.jpg", 
    "size": 789012,
    "mime_type": "image/jpeg",
    "meta": { "_type": "gradio.FileData" }
}

# Make prediction request
response = requests.post(
    'https://nitish-spz-abtestpredictorv2.hf.space/call/predict_with_auto_categorization',
    json={"data": [control_file_data, variant_file_data]}
)

result = response.json()
```

## Response Field Descriptions

### Prediction Results
- **probability**: Float between 0-1 (probability of variant winning). Values > 0.5 mean variant wins, < 0.5 mean control wins
- **modelConfidence**: Percentage confidence based on historical data
- **trainingDataSamples**: Number of training samples used for confidence calculation
- **totalPredictions**: Total number of historical predictions in this category
- **correctPredictions**: Number of correct predictions in historical data
- **totalWinPrediction**: Number of times variant won in historical data
- **totalLosePrediction**: Number of times control won in historical data

### Auto-Detected Categories
- **businessModel**: "E-Commerce", "SaaS", "Lead Generation", "Other*"
- **customerType**: "B2B", "B2C", "Both", "Other*"
- **conversionType**: "Direct Purchase", "High-Intent Lead Gen", "Info/Content Lead Gen", "Location Search", "Non-Profit/Community", "Other Conversion"
- **industry**: 14 categories including "B2B Software & Tech", "Retail & E-commerce", etc.
- **pageType**: "Awareness & Discovery", "Consideration & Evaluation", "Conversion", "Internal & Navigation", "Post-Conversion & Other"

### Detected Pattern
- **pattern**: A/B test pattern name (e.g., "Button", "Form Over UI", "Hero Changes")
- **description**: Human-readable description of the pattern

### Processing Info
- **totalProcessingTime**: Time taken for prediction (typically 20-40 seconds)
- **aiCategorization**: AI service used for categorization
- **patternDetection**: AI service used for pattern detection
- **confidenceSource**: Data source for confidence scores
- **totalPatternsAnalyzed**: Number of patterns in the detection database

## Error Handling

### Common Error Responses
```json
{
  "error": "Prediction failed: [error message]",
  "modelConfidence": "50.0%",
  "trainingDataSamples": 0,
  "totalPredictions": 0,
  "correctPredictions": 0,
  "totalWinPrediction": 0,
  "totalLosePrediction": 0
}
```

### HTTP Status Codes
- **200**: Success
- **400**: Bad request (invalid parameters)
- **500**: Internal server error
- **503**: Service unavailable (GPU quota exceeded)

## Rate Limits
- Free tier: Limited concurrent requests
- Processing time: 20-40 seconds per prediction
- GPU duration: 50-60 seconds maximum

## Example Integration (Python)

```python
import requests
import time

class ABTestPredictor:
    def __init__(self):
        self.base_url = "https://nitish-spz-abtestpredictorv2.hf.space"
    
    def predict(self, control_image_path, variant_image_path):
        # Step 1: Upload images
        control_path = self._upload_image(control_image_path)
        variant_path = self._upload_image(variant_image_path)
        
        # Step 2: Make prediction
        return self._make_prediction(control_path, variant_path)
    
    def _upload_image(self, image_path):
        with open(image_path, 'rb') as f:
            files = {'files': f}
            response = requests.post(f"{self.base_url}/upload", files=files)
            return response.json()[0]
    
    def _make_prediction(self, control_path, variant_path):
        control_data = self._create_file_data(control_path, "control.jpg")
        variant_data = self._create_file_data(variant_path, "variant.jpg")
        
        response = requests.post(
            f"{self.base_url}/call/predict_with_auto_categorization",
            json={"data": [control_data, variant_data]}
        )
        
        return response.json()
    
    def _create_file_data(self, path, orig_name):
        return {
            "path": path,
            "url": f"{self.base_url}/file={path}",
            "orig_name": orig_name,
            "size": 0,  # Optional
            "mime_type": "image/jpeg",
            "meta": { "_type": "gradio.FileData" }
        }

# Usage
predictor = ABTestPredictor()
result = predictor.predict("control.jpg", "variant.jpg")

# Get prediction results
prob = float(result['predictionResults']['probability'])
winner = "VARIANT WINS" if prob > 0.5 else "CONTROL WINS"

print(f"Winner: {winner}")
print(f"Probability: {prob}")
print(f"Confidence: {result['predictionResults']['modelConfidence']}")
print(f"Accuracy: {result['predictionResults']['correctPredictions']}/{result['predictionResults']['totalPredictions']}")
```

## Notes
- Images are automatically deleted after processing
- Maximum image size: 10MB
- Supported formats: JPEG, PNG, WebP
- Processing time varies based on image complexity and server load