Metadata-Version: 2.4
Name: rayuela
Version: 1.0.0
Summary: SDK oficial de Python para la API de Recomendaciones de Rayuela
Home-page: https://github.com/rayuela/rayuela-sdk-python
Author: Rayuela Team
Author-email: Rayuela Team <support@rayuela.ai>
Maintainer-email: Rayuela Team <support@rayuela.ai>
License: MIT
Project-URL: Homepage, https://docs.rayuela.ai
Project-URL: Documentation, https://docs.rayuela.ai/sdk/python
Project-URL: Repository, https://github.com/rayuela/rayuela-sdk-python
Project-URL: Bug Tracker, https://github.com/rayuela/rayuela-sdk-python/issues
Project-URL: Changelog, https://github.com/rayuela/rayuela-sdk-python/blob/main/CHANGELOG.md
Keywords: recommendations,machine-learning,personalization,api,sdk,python,ecommerce,content-recommendation
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: flake8>=5.0.0; extra == "dev"
Requires-Dist: mypy>=0.990; extra == "dev"
Requires-Dist: isort>=5.10.0; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# Rayuela SDK para Python

[![PyPI version](https://badge.fury.io/py/rayuela.svg)](https://badge.fury.io/py/rayuela)
[![Python Versions](https://img.shields.io/pypi/pyversions/rayuela.svg)](https://pypi.org/project/rayuela/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**SDK oficial de Python para la API de Recomendaciones de Rayuela**

Simplifica la integración con Rayuela de más de 20 líneas de código a solo 3 líneas. 
Diseñado para data scientists, desarrolladores backend y equipos B2B que necesitan recomendaciones 
personalizadas de alta calidad sin la complejidad del manejo manual de HTTP.

---

## 🚀 Características Principales

- **🎯 Zero Boilerplate**: De 20+ líneas de código manual a 3 líneas
- **🔑 Usa tus IDs externos**: No necesitas mapear o almacenar IDs internos de Rayuela
- **🏭 Específico por industria**: Métodos optimizados para e-commerce, media y marketplaces
- **📊 A/B Testing integrado**: Compara automáticamente vs baseline con significancia estadística
- **🛡️ Manejo de errores robusto**: Mensajes claros con sugerencias de solución
- **⚡ Type hints completos**: Autocompletado perfecto en VS Code y PyCharm
- **🐍 Python 3.8+**: Compatible con todas las versiones modernas de Python

---

## 📦 Instalación

### Desde PyPI (Recomendado)

```bash
pip install rayuela
```

### Desde el código fuente

```bash
git clone https://github.com/rayuela/rayuela-sdk-python.git
cd rayuela-sdk-python
pip install -e .
```

---

## ⚡ Inicio Rápido (< 5 minutos)

### 1. Obtén tu API Key

Obtén tu clave API gratuita en: [https://dashboard.rayuela.ai](https://dashboard.rayuela.ai)

### 2. Primera Recomendación en 3 Líneas

```python
from rayuela import RayuelaClient, RayuelaConfig

client = RayuelaClient(RayuelaConfig(api_key="sk_your_api_key"))
recs = client.recommend('user_123', limit=10)

# ¡Eso es todo! 🎉
for item in recs.items:
    print(f"{item.name}: {item.score:.2f}")
```

### 3. Inicio Ultra-Rápido con Datos de Muestra

```python
from rayuela import quick_start

# Una línea para obtener recomendaciones de prueba
recs = quick_start(api_key='sk_your_api_key', user_id='demo-user')
```

---

## 📖 Guía de Uso

### Configuración del Cliente

```python
from rayuela import RayuelaClient, RayuelaConfig

# Configuración básica
client = RayuelaClient(RayuelaConfig(
    api_key="sk_your_api_key",
    debug=True  # Opcional: habilita logging
))

# Configuración avanzada
client = RayuelaClient(RayuelaConfig(
    api_key="sk_your_api_key",
    base_url="https://api.rayuela.ai",  # Por defecto
    timeout=30,  # Timeout en segundos
    debug=False
))
```

### Obtener Recomendaciones Personalizadas

```python
from rayuela import RecommendationOptions

# Recomendaciones básicas
recs = client.recommend('user_abc123')

# Con opciones avanzadas
recs = client.recommend(
    user_id='user_abc123',
    options=RecommendationOptions(
        limit=20,
        strategy='collab',  # hybrid, collab, content_based, popularity
        category='electronics',
        min_rating=4.0,
        explain=True,  # Incluye explicaciones
        filters={
            'brand': ['Apple', 'Samsung'],
            'price_max': 1000
        }
    )
)

# Acceder a los resultados
print(f"Total: {recs.total} recomendaciones")
print(f"Estrategia: {recs.meta.strategy}")
print(f"Tiempo: {recs.meta.response_time:.2f}ms")

for item in recs.items:
    print(f"{item.name} - ${item.price:.2f}")
    print(f"  Score: {item.score:.2f} | Rating: {item.average_rating}/5")
    if item.explanation:
        print(f"  💡 {item.explanation}")
```

### Estrategias de Recomendación

| Estrategia | Descripción | Mejor para |
|-----------|-------------|-----------|
| `hybrid` | Equilibrio general entre señales | Homepage, feed general |
| `collab` | Colaborativo (usuarios similares) | Páginas de producto |
| `content_based` | Similitud de contenido | Nuevos usuarios |
| `popularity` | Tendencia/popularidad | Arranques en frío |

---

## 🏭 Integraciones Específicas por Industria

### E-commerce

```python
from rayuela import EcommerceOptions

# Homepage
homepage_recs = client.ecommerce(
    user_id='user123',
    options=EcommerceOptions(
        page='homepage',
        limit=12,
        in_stock_only=True
    )
)

# Página de producto (productos relacionados)
product_recs = client.ecommerce(
    user_id='user123',
    options=EcommerceOptions(
        page='product',
        category='electronics',
        price_range={'min': 50, 'max': 500},
        in_stock_only=True,
        explain=True
    )
)

# Carrito (cross-sell)
cart_recs = client.ecommerce(
    user_id='user123',
    options=EcommerceOptions(
        page='cart',
        strategy='content_based',
        limit=6
    )
)
```

### Plataformas de Medios

```python
from rayuela import MediaOptions

# Artículos recomendados
media_recs = client.media(
    user_id='user123',
    options=MediaOptions(
        media_type='article',
        reading_time={'min': 5, 'max': 15},
        freshness='latest',
        limit=10
    )
)

# Videos trending
video_recs = client.media(
    user_id='user123',
    options=MediaOptions(
        media_type='video',
        freshness='trending',
        category='technology'
    )
)
```

### Marketplaces

```python
from rayuela import MarketplaceOptions

# Cross-sell
marketplace_recs = client.marketplace(
    user_id='user123',
    options=MarketplaceOptions(
        type='cross-sell',
        vendor_id='vendor_456',
        region='US',
        limit=8
    )
)
```

---

## 📊 Seguimiento de Eventos

Registra las interacciones del usuario para mejorar las recomendaciones:

```python
from rayuela import InteractionEvent

# View
client.track(InteractionEvent(
    user_id='user123',
    product_id='prod456',
    type='view'
))

# Click
client.track(InteractionEvent(
    user_id='user123',
    product_id='prod456',
    type='click',
    context={'position': 1, 'page': 'homepage'}
))

# Purchase (conversión)
client.track(InteractionEvent(
    user_id='user123',
    product_id='prod456',
    type='purchase',
    value=99.99,
    context={'order_id': 'ORD-001'}
))

# Otros tipos: 'like', 'share', 'add_to_cart'
```

---

## 🧪 A/B Testing

Compara automáticamente las recomendaciones de Rayuela vs un baseline:

```python
from rayuela import ABTestEvent

# 1. Obtener recomendaciones A/B
ab_result = client.ab_test(
    user_id='user123',
    options=RecommendationOptions(limit=10),
    experiment_id='exp_2025_q1'
)

print(f"Variant: {ab_result.variant}")  # 'control' o 'treatment'
print(f"Experiment ID: {ab_result.experiment_id}")

# 2. Registrar eventos del experimento
client.track_ab_test(ABTestEvent(
    experiment_id=ab_result.experiment_id,
    user_id='user123',
    event_type='view'
))

client.track_ab_test(ABTestEvent(
    experiment_id=ab_result.experiment_id,
    user_id='user123',
    event_type='click',
    product_id='prod456'
))

client.track_ab_test(ABTestEvent(
    experiment_id=ab_result.experiment_id,
    user_id='user123',
    event_type='conversion',
    product_id='prod456',
    value=99.99
))

# 3. Obtener resultados
results = client.get_ab_test_results('exp_2025_q1')

print(f"Control CTR: {results.control.ctr:.2%}")
print(f"Treatment CTR: {results.treatment.ctr:.2%}")
print(f"CTR Lift: {results.lifts.ctr_lift_percentage}")
print(f"CVR Lift: {results.lifts.cvr_lift_percentage}")
print(f"Significativo: {results.statistical_significance.is_significant}")
```

---

## 📈 Métricas de Negocio

```python
metrics = client.get_metrics()

print(f"CTR Lift: {metrics.ctr_lift:.2%}")
print(f"CVR Lift: {metrics.cvr_lift:.2%}")
print(f"Revenue Attribution: ${metrics.revenue_attribution:,.2f}")
print(f"Catalog Coverage: {metrics.catalog_coverage:.2%}")
print(f"Engagement Score: {metrics.engagement_score:.2f}")
```

---

## 🛡️ Manejo de Errores

El SDK proporciona errores claros con sugerencias:

```python
from rayuela import RayuelaError

try:
    recs = client.recommend('user123')
except RayuelaError as e:
    print(f"Error: [{e.code}] {e.message}")
    print(f"Sugerencia: {e.suggestion}")
    print(f"Detalles: {e.details}")
```

### Códigos de Error Comunes

| Código | Descripción | Solución |
|--------|-------------|----------|
| `INVALID_API_KEY` | API key inválida o faltante | Verifica tu clave en el dashboard |
| `RATE_LIMIT_EXCEEDED` | Límite de requests excedido | Reduce la frecuencia o mejora tu plan |
| `RESOURCE_NOT_FOUND` | Usuario/producto no encontrado | Verifica que el recurso exista |
| `SERVER_ERROR` | Error en el servidor | Intenta más tarde o contacta soporte |

---

## 📚 Ejemplos Completos

Encuentra ejemplos completos en el directorio [`examples/`](./examples/):

- **[quickstart.py](./examples/quickstart.py)**: Guía de inicio rápido
- **[ecommerce_integration.py](./examples/ecommerce_integration.py)**: Integración completa de e-commerce
- **[ab_testing.py](./examples/ab_testing.py)**: Tutorial de A/B testing

### Ejecutar los ejemplos

```bash
# Instala el SDK
pip install rayuela

# Ejecuta el quickstart
python examples/quickstart.py

# Ejecuta el ejemplo de e-commerce
python examples/ecommerce_integration.py

# Ejecuta el ejemplo de A/B testing
python examples/ab_testing.py
```

---

## 🎯 Comparación: Antes vs Después

### ❌ Antes (Sin SDK): 20+ líneas

```python
import requests
import json

headers = {
    "X-API-Key": "sk_your_api_key",
    "Content-Type": "application/json"
}

payload = {
    "external_user_id": "user_123",
    "limit": 10,
    "strategy": "maximize_engagement",
    "explain": True
}

try:
    response = requests.post(
        "https://api.rayuela.ai/api/v1/recommendations/personalized/query",
        headers=headers,
        json=payload,
        timeout=30
    )
    
    if response.status_code == 200:
        data = response.json()
        items = data.get('items', [])
        for item in items:
            print(f"{item['name']}: {item['score']}")
    elif response.status_code == 401:
        print("Error: API key inválida")
    elif response.status_code == 429:
        print("Error: Rate limit excedido")
    else:
        print(f"Error: {response.status_code}")
except requests.exceptions.Timeout:
    print("Error: Request timeout")
except Exception as e:
    print(f"Error: {e}")
```

### ✅ Después (Con SDK): 3 líneas

```python
from rayuela import RayuelaClient, RayuelaConfig

client = RayuelaClient(RayuelaConfig(api_key="sk_your_api_key"))
recs = client.recommend('user_123', limit=10, strategy='collab', explain=True)

for item in recs.items:
    print(f"{item.name}: {item.score}")
```

**Reducción de código: 85%** 🎉

---

## 🔧 Desarrollo

### Instalación para desarrollo

```bash
git clone https://github.com/rayuela/rayuela-sdk-python.git
cd rayuela-sdk-python
pip install -e ".[dev]"
```

### Ejecutar tests

```bash
pytest
```

### Formateo de código

```bash
black rayuela/
isort rayuela/
```

### Type checking

```bash
mypy rayuela/
```

---

## 📝 Requisitos

- Python 3.8 o superior
- `requests` >= 2.28.0

---

## 🤝 Soporte y Contribución

### Documentación

- **Documentación completa**: [https://docs.rayuela.ai/sdk/python](https://docs.rayuela.ai/sdk/python)
- **Guías de integración**: [https://docs.rayuela.ai/guides](https://docs.rayuela.ai/guides)
- **Referencia de API**: [https://docs.rayuela.ai/api](https://docs.rayuela.ai/api)

### Soporte

- **Email**: support@rayuela.ai
- **GitHub Issues**: [https://github.com/rayuela/rayuela-sdk-python/issues](https://github.com/rayuela/rayuela-sdk-python/issues)
- **Dashboard**: [https://dashboard.rayuela.ai](https://dashboard.rayuela.ai)

### Contribuir

¡Las contribuciones son bienvenidas! Por favor, lee nuestra [Guía de Contribución](CONTRIBUTING.md) antes de enviar un PR.

---

## 📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT - ver el archivo [LICENSE](LICENSE) para más detalles.

---

## 🌟 Casos de Éxito

> "El SDK de Python de Rayuela redujo nuestro tiempo de integración de 2 semanas a 2 días. 
> El manejo automático de IDs externos fue un game-changer."
> 
> — **Tech Lead, E-commerce B2B**

> "La integración A/B testing out-of-the-box nos permitió validar un +23% de CTR lift 
> en solo 10 días de experimento."
> 
> — **Data Scientist, Marketplace**

---

## 🗺️ Roadmap

- [ ] Soporte para batch recommendations
- [ ] Cliente asíncrono (asyncio)
- [ ] Integración con pandas DataFrames
- [ ] CLI para testing rápido
- [ ] Soporte para webhooks

---

## 🔗 Links Útiles

- [Documentación oficial](https://docs.rayuela.ai)
- [Dashboard](https://dashboard.rayuela.ai)
- [Blog](https://blog.rayuela.ai)
- [Estado del servicio](https://status.rayuela.ai)

---

**¿Preguntas?** Contáctanos en support@rayuela.ai

**Made with ❤️ by the Rayuela Team**

