rayuela 1.0.0

SDK oficial de Python para la API de Recomendaciones de Rayuela

Rayuela SDK para Python

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)

pip install rayuela

Desde el código fuente

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

2. Primera Recomendación en 3 Líneas

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

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

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

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

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

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

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:

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:

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

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:

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

• quickstart.py: Guía de inicio rápido
• ecommerce_integration.py: Integración completa de e-commerce
• ab_testing.py: Tutorial de A/B testing

Ejecutar los ejemplos

# 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

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

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

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

Ejecutar tests

pytest

Formateo de código

black rayuela/
isort rayuela/

Type checking

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
• Guías de integración: https://docs.rayuela.ai/guides
• Referencia de API: https://docs.rayuela.ai/api

Soporte

• Email: [e-mail]
• GitHub Issues: https://github.com/rayuela/rayuela-sdk-python/issues
• Dashboard: https://dashboard.rayuela.ai

Contribuir

¡Las contribuciones son bienvenidas! Por favor, lee nuestra Guía de Contribución antes de enviar un PR.

---

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT - ver el archivo 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
• Dashboard
• Blog
• Estado del servicio

---

¿Preguntas? Contáctanos en [e-mail]

Made with ❤️ by the Rayuela Team