social-media-automation/docs/AB_TESTING.md

# A/B Testing

Sistema de pruebas A/B para optimizar contenido y maximizar engagement.

## Descripción

El A/B Testing permite comparar diferentes versiones de contenido para determinar cuál tiene mejor rendimiento. El sistema:

1. Crea múltiples variantes de contenido
2. Publica cada variante
3. Recopila métricas de cada una
4. Determina estadísticamente el ganador

## Modelos de Datos

### ABTest

```python
ABTest:
    id: int
    name: str
    description: str
    test_type: str  # content, timing, hashtags, image

    platform: str  # x, threads, instagram, facebook
    status: str  # draft, running, completed, cancelled

    started_at: datetime
    ended_at: datetime
    duration_hours: int  # Duración del test (default 24)

    winning_variant_id: int (FK)
    confidence_level: float  # Nivel de confianza estadística

    min_sample_size: int  # Mín impresiones por variante (default 100)
    success_metric: str  # engagement_rate, likes, comments, shares
```

### ABTestVariant

```python
ABTestVariant:
    id: int
    test_id: int (FK -> ab_tests)
    name: str  # A, B, C, D

    content: str
    hashtags: JSON
    image_url: str

    post_id: int (FK -> posts)

    # Métricas
    impressions: int
    reach: int
    likes: int
    comments: int
    shares: int
    clicks: int
    engagement_rate: float

    is_winner: bool
    published_at: datetime
```

## API Endpoints

### GET /api/ab-tests/
Lista todos los tests A/B.

**Parámetros:**
- `status`: draft, running, completed, cancelled
- `platform`: x, threads, etc.
- `limit` (int, default=20)

**Respuesta:**
```json
{
    "tests": [
        {
            "id": 1,
            "name": "Test de copies",
            "platform": "x",
            "status": "running",
            "variants": [...]
        }
    ],
    "count": 5
}
```

### GET /api/ab-tests/{test_id}
Obtiene un test específico con sus variantes.

### POST /api/ab-tests/
Crea un nuevo test A/B.

**Body:**
```json
{
    "name": "Test de copies para tips",
    "platform": "x",
    "variants": [
        {
            "name": "A",
            "content": "💡 Tip: Automatiza tus procesos con IA...",
            "hashtags": ["#IA", "#Automatización"]
        },
        {
            "name": "B",
            "content": "¿Sabías que la IA puede ahorrarte 10 horas semanales?...",
            "hashtags": ["#Productividad", "#Tech"]
        }
    ],
    "test_type": "content",
    "duration_hours": 24,
    "min_sample_size": 100,
    "success_metric": "engagement_rate"
}
```

**Validaciones:**
- Mínimo 2 variantes, máximo 4
- Cada variante debe tener contenido

### POST /api/ab-tests/{test_id}/start
Inicia un test A/B.

**Proceso:**
1. Crea posts para cada variante
2. Programa publicación (escalonada cada 5 min)
3. Cambia status a "running"
4. Registra start_time

**Respuesta:**
```json
{
    "message": "A/B test started successfully",
    "success": true,
    "test_id": 1,
    "post_ids": [101, 102],
    "variants_count": 2
}
```

### POST /api/ab-tests/{test_id}/evaluate
Evalúa resultados y determina ganador.

**Proceso:**
1. Actualiza métricas de cada variante
2. Verifica tamaño de muestra mínimo
3. Ejecuta test estadístico (chi-square)
4. Determina ganador y confianza
5. Si duration_hours pasó, marca como completed

**Respuesta:**
```json
{
    "success": true,
    "winner": {
        "variant_id": 1,
        "name": "A",
        "engagement_rate": 4.5,
        "impressions": 1500
    },
    "runner_up": {
        "variant_id": 2,
        "name": "B",
        "engagement_rate": 3.2,
        "impressions": 1400
    },
    "confidence_level": 95.5,
    "p_value": 0.045,
    "test_status": "completed"
}
```

**Si datos insuficientes:**
```json
{
    "success": true,
    "status": "insufficient_data",
    "min_impressions": 50,
    "required": 100
}
```

### GET /api/ab-tests/{test_id}/results
Obtiene resultados actuales (sin determinar ganador).

### POST /api/ab-tests/{test_id}/cancel
Cancela un test en progreso.

## Tareas Programadas

### evaluate_ab_tests
- **Frecuencia:** Cada hora
- **Función:**
  - Busca tests en estado "running"
  - Si pasó duration_hours, evalúa y completa
  - Si no, solo actualiza métricas

## Tipos de Test

| Tipo | Descripción |
|------|-------------|
| `content` | Prueba diferentes textos |
| `timing` | Prueba diferentes horarios |
| `hashtags` | Prueba diferentes conjuntos de hashtags |
| `image` | Prueba diferentes imágenes |

## Métricas de Éxito

| Métrica | Descripción |
|---------|-------------|
| `engagement_rate` | (likes + comments + shares) / impressions |
| `likes` | Total de likes |
| `comments` | Total de comentarios |
| `shares` | Total de compartidos |
| `clicks` | Total de clics (si aplica) |

## Análisis Estadístico

El sistema usa el **test chi-cuadrado** para determinar significancia estadística:

```python
# Tabla de contingencia
[
    [engagements_A, non_engagements_A],
    [engagements_B, non_engagements_B]
]

chi2, p_value, dof, expected = scipy.stats.chi2_contingency(tabla)
confidence = (1 - p_value) * 100
```

### Interpretación

| p-value | Confianza | Interpretación |
|---------|-----------|----------------|
| < 0.01 | > 99% | Muy significativo |
| < 0.05 | > 95% | Significativo |
| < 0.10 | > 90% | Marginalmente significativo |
| ≥ 0.10 | < 90% | No significativo |

## Flujo de Trabajo

```
1. Crear Test (status: draft)
        ↓
2. Iniciar Test (status: running)
   - Crea posts para variantes
   - Programa publicación
        ↓
3. Esperar duración
   - Sistema recopila métricas cada 15 min
   - Evalúa cada hora
        ↓
4. Evaluar Resultados (status: completed)
   - Determina ganador estadístico
   - Calcula nivel de confianza
```

## Ejemplo de Uso

```python
from app.services.ab_testing_service import ab_testing_service

# Crear test
test = await ab_testing_service.create_test(
    name="Test de engagement",
    platform="x",
    variants=[
        {"name": "A", "content": "Versión corta y directa"},
        {"name": "B", "content": "Versión más elaborada con detalles"}
    ],
    duration_hours=48,
    min_sample_size=200
)

# Iniciar
result = await ab_testing_service.start_test(test.id)

# Evaluar (después de publicado)
results = await ab_testing_service.evaluate_test(test.id)
if results.get("winner"):
    print(f"Ganador: Variante {results['winner']['name']}")
    print(f"Confianza: {results['confidence_level']:.1f}%")
```

## Mejores Prácticas

1. **Tamaño de muestra:** Espera al menos 100 impresiones por variante
2. **Una variable:** Prueba solo un elemento a la vez
3. **Duración:** Mínimo 24 horas para datos representativos
4. **Horarios:** Publica variantes en horarios similares
5. **Confianza:** Busca > 95% antes de tomar decisiones