Para empezar
Bienvenido a la documentación oficial de **Keoxs Co-Pilot**, un motor de inteligencia open-source y local diseñado para automatizar, auditar y optimizar sus campañas Amazon PPC. Keoxs coloca un poder de diagnóstico económico y de análisis IA cognitivo de nivel corporativo directamente en su máquina local, garantizando una privacidad absoluta de los datos y tiempos de análisis ultra-rápidos.
Privacidad Absoluta (Local-First)
A diferencia de las plataformas SaaS tradicionales que requieren una integración completa de su cuenta vendedor y almacenan sus datos financieros en servidores remotos, Keoxs funciona **enteramente en local en su ordenador**. Sus informes de términos de búsqueda (STR), COGS, estructuras de precios y claves API nunca salen de su máquina.
Cómo funciona Keoxs Co-Pilot
Keoxs Co-Pilot se basa en una **arquitectura de doble motor** que combina el rigor matemático con la síntesis cualitativa de la IA:
1. Algoritmos Económicos Unitarios
El motor de cálculo analiza sus informes de términos de búsqueda (STR) línea por línea, comparando cada métrica con sus precios de venta reales, COGS y tarifas de FBA para identificar los objetivos deficitarios y calcular ofertas óptimas.
2. Cerebro IA Cognitivo
Impulsado por Google Gemini, el cerebro de la IA supera los límites de los umbrales algorítmicos rígidos para analizar la intención de búsqueda, el potencial orgánico y las oportunidades de conquista competitiva, generando una hoja de ruta estratégica a medida.
Lo que necesita
Antes de desplegar Keoxs Co-Pilot, asegúrese de que su ordenador cumple con la siguiente configuración:
- Node.js – Versión 18+ recomendada (v20+ totalmente soportada) para ejecutar la interfaz web frontend.
- Python – Versión 3.10+ requerida para ejecutar el servidor backend local con FastAPI.
- Clave API Google AI Studio – Indispensable para activar el Cerebro IA Cognitivo. Puede obtenerla de forma gratuita en Google AI Studio.
- Git – Recomendado para recuperar fácilmente las actualizaciones y gestionar el repositorio local.
Instalación Rápida
Proporcionamos un script de instalación en una sola línea que verifica sus requisitos, clona el repositorio más reciente, configura el entorno virtual local y arranca ambos servidores automáticamente.
Instalación Manual para Desarrolladores
Si prefiere configurar su espacio de trabajo manualmente o desea contribuir al proyecto de código abierto, siga estos pasos.
1. Clonar el Repositorio
cd keoxs-co-pilot
2. Configurar el Backend FastAPI
python -m venv venv
# Windows:
.\venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate
pip install -r requirements.txt
python -m uvicorn api:app --host 127.0.0.1 --port 8001 --reload
3. Configurar el Frontend React
npm install
npm run dev
El Asistente de Onboarding
Al iniciar, Keoxs le guía a través de un panel de configuración financiera sumamente completo. Ingrese sus parámetros:
- Clave API – Asegura la conexión con los modelos Gemini. Guardada exclusivamente en el almacenamiento local del navegador.
- Precio Medio & COGS – Permite al algoritmo calcular su ACOS de rentabilidad en tiempo real (`Margen Neto = (Precio Venta - COGS - Tarifas FBA) / Precio Venta`).
- Umbral de Gasto Inútil (Wasted Spend) – Valor estándar: 10 clics sin conversión. Determina cuándo un término deficitario debe desactivarse o recibir una reducción agresiva de oferta.
Zona de Ingesta (Drop Zone)
Arrastre y suelte su archivo de **Informe de Términos de Búsqueda** (Sponsored Products o Informes Generales) en formato CSV o XLSX directamente en la zona de ingesta.
Keoxs normaliza instantáneamente el archivo (independientemente del país de origen de Amazon), filtra los datos corruptos y muestra un panel ejecutivo ordenado por urgencia económica:
🔴 Urgencias
Palabras clave que gastan presupuesto con muchos clics pero 0 ventas. Sugiere exclusión inmediata en Negativo Exacto.
🟠 Optimizaciones
Palabras clave con conversiones pero cuyo ACOS supera su margen de rentabilidad calculado. Sugiere bajas progresivas de ofertas.
🟢 Oportunidades
Términos altamente rentables, expresiones estacionales o ciber-objetivos competidores con gran potencial. Suggère subidas de ofertas.
Cerebro IA Cognitivo
Las reglas de optimización matemática tradicionales suelen fallar a la hora de identificar micro-oportunidades, como un objetivo competidor que convierte desde el primer clic o tendencias de búsqueda estacionales precoces.
La pestaña **Cerebro IA** supera estas limitaciones inyectando en Gemini un contexto comercial sumamente rico:
- Flujo completo de convertidores – La IA analiza cada búsqueda que haya generado al menos una venta, capturando instantáneamente los ASIN competidores (como `b0fmzkwkx9`) con excelente ROAS.
- Inyección de Historial – Memoriza automáticamente sus 5 análisis más recientes para asegurar una coherencia de optimización a largo plazo y evitar decisiones contradictorias.
- Diagnóstico Conversión/Tráfico – Sintetiza las tasas de conversión frente a los volúmenes de impresiones para indicarle si una campaña está limitada por su presupuesto o sus ofertas.
Exportar Acciones en Lote
Aplique sus optimizaciones en la consola Amazon Ads en pocos segundos. Al hacer clic en **Export Bulk Actions**, filtra la totalidad de sus filas para conservar únicamente las líneas de acciones sugeridas.
El archivo CSV plano utiliza un separador de punto y coma estándar, legible inmediatamente por Excel o Google Sheets, lo que le permite copiar y pegar sus acciones en lote directamente en su gestor de campañas de Amazon.
Consejos Pro & Estrategia
📅 Seleccione el Periodo de Análisis Correcto
Al descargar sus informes, le recomendamos utilizar un periodo de análisis de los **últimos 30 días** (excluyendo las últimas 48 horas para tener en cuenta el desfase de atribución de ventas en Amazon). Esto proporciona al motor un volumen estadístico robusto.
✍️ Optimice el Contexto del Prompt de la IA
No dude en proporcionar al Cerebro de la IA indicaciones cualitativas precisas (por ejemplo: *"Lanzaremos un nuevo sabor la próxima semana y debemos ser agresivos en la conquista de la competencia"* o *"Falta de stock en el ASIN B hasta junio, reduzca el ritmo en las campañas 3 y 4"*). La IA ajustará su hoja de ruta de acuerdo a esto.
⚖️ Equilibre el TACoS & los Márgenes Netos
Siga de cerca su TACoS (Total Advertising Cost of Sales). Si sus ventas orgánicas son fuertes pero sus márgenes netos sufren, utilice las sugerencias de ofertas de Keoxs para reducir progresivamente la presión publicitaria hasta que su TACoS vuelva a estar por debajo del 15% objetivo.