Premiers pas

Pour commencer

Bienvenue dans la documentation officielle de **Keoxs Co-Pilot**, un moteur d'intelligence open-source et local conçu pour automatiser, auditer et optimiser vos campagnes Amazon PPC. Keoxs place une puissance de diagnostic économique et d'analyse IA cognitive de niveau entreprise directement sur votre machine locale, garantissant une confidentialité totale des données et des temps d'analyse ultra-rapides.

💡

Confidentialité Absolue (Local-First)

Contrairement aux plateformes SaaS traditionnelles qui nécessitent une intégration complète de votre compte vendeur et stockent vos données financières sur des serveurs distants, Keoxs fonctionne **entièrement en local sur votre ordinateur**. Vos rapports de termes de recherche (STR), COGS, structures de prix et clés API ne quittent jamais votre machine.

Comment fonctionne Keoxs Co-Pilot

Keoxs Co-Pilot repose sur une **architecture double moteur** qui combine rigueur mathématique et synthèse IA qualitative :

1. Algorithmes Économiques Unitaires

Le moteur de calcul analyse vos rapports de termes de recherche (STR) ligne par ligne, comparant chaque métrique à vos prix de vente réels, COGS et frais FBA afin de repérer les cibles déficitaires et calculer des enchères optimales.

2. Cerveau IA Cognitif

Propulsé par Google Gemini, le cerveau IA dépasse les limites des seuils algorithmiques rigides pour analyser l'intention de recherche, le potentiel organique et les opportunités de conquête concurrentielle, générant une feuille de route stratégique sur mesure.

Ce dont vous avez besoin

Avant de déployer Keoxs Co-Pilot, assurez-vous que votre ordinateur possède la configuration suivante :

  • Node.js – Version 18+ recommandée (v20+ entièrement supportée) pour faire tourner l'interface web frontend.
  • Python – Version 3.10+ requise pour exécuter le serveur backend local sous FastAPI.
  • Clé API Google AI Studio – Indispensable pour activer le Cerveau IA Cognitif. Vous pouvez l'obtenir gratuitement en 1 clic sur Google AI Studio.
  • Git – Recommandé pour récupérer facilement les mises à jour et gérer le dépôt local.

Installation Rapide

Nous fournissons un script d'installation en une seule ligne qui vérifie vos prérequis, clone le dépôt le plus récent, configure l'environnement virtuel local et démarre les deux serveurs automatiquement.

Windows PowerShell (Recommandé) Automatique
powershell -ExecutionPolicy Bypass -Command "Invoke-Expression (New-Object Net.WebClient).DownloadString('https://raw.githubusercontent.com/scalerify-keoxs/keoxs-website/main/install.ps1')"
Terminal macOS / Linux
curl -fsSL https://raw.githubusercontent.com/scalerify-keoxs/keoxs-website/main/install.sh | bash

Installation Manuelle pour Développeurs

Si vous préférez configurer votre espace de travail manuellement ou souhaitez contribuer au projet open-source, suivez ces étapes.

1. Cloner le Dépôt

git clone https://github.com/scalerify-keoxs/keoxs-co-pilot.git
cd keoxs-co-pilot

2. Configurer le Backend FastAPI

cd backend
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. Configurer le Frontend React

cd ../frontend
npm install
npm run dev
Modules principaux

L'Assistant d'Onboarding

Au lancement, Keoxs vous guide à travers un panneau de configuration financière ultra-complet. Saisissez vos paramètres :

  • Clé API – Sécurise la connexion avec les modèles Gemini. Sauvegardée exclusivement dans votre stockage local de navigateur.
  • Prix Moyen & COGS – Permet à l'algorithme de calculer votre ACOS de rentabilité en temps réel (`Marge Net = (Prix Vente - COGS - Frais FBA) / Prix Vente`).
  • Seuil de Dépenses Inutiles (Wasted Spend) – Valeur standard : 10 clics sans conversion. Détermine à partir de quand un terme déficitaire doit être désactivé ou faire l'objet d'une baisse agressive d'enchère.

Zone d'Ingestion (Drop Zone)

Glissez et déposez votre fichier de **Rapport de Termes de Recherche** (Sponsored Products ou Rapports Généraux) au format CSV ou XLSX directement dans la zone d'ingestion.

Keoxs normalise instantanément le fichier (quel que soit le pays Amazon d'origine), filtre les données corrompues et affiche un tableau de bord exécutif trié par urgence économique :

🔴 Urgences

Mots-clés qui dépensent du budget avec de nombreux clics mais 0 vente. Suggère une exclusion immédiate en Négatif Exact.

🟠 Optimisations

Mots-clés convertisseurs mais dont l'ACOS dépasse votre marge de rentabilité calculée. Suggère des baisses d'enchères régulières.

🟢 Opportunités

Termes hautement rentables, expressions saisonnières ou cibles concurrentes à fort potentiel. Suggère des hausses d'enchères.

Cerveau IA Cognitif

Les règles d'optimisation mathématiques classiques échouent souvent à repérer les micro-opportunités, comme une cible concurrente convertissant dès le premier clic ou des tendances de recherche saisonnières précoces.

L'onglet **Cerveau IA** contourne ces contraintes en injectant dans Gemini un contexte commercial extrêmement riche :

  • Flux complet de convertisseurs – L'IA analyse chaque recherche ayant généré au moins une vente, capturant instantanément les ASIN concurrents (comme `b0fmzkwkx9`) affichant un excellent ROAS.
  • Injection d'Historique – Mémorise automatiquement vos 5 dernières analyses pour assurer une cohérence d'optimisation sur le long terme et éviter des décisions contraires.
  • Diagnostic Conversion/Trafic – Synthétise les taux de conversion face aux volumes d'impressions pour vous indiquer si une campagne est bridée par son budget ou ses enchères.

Export Actions en Masse

Appliquez vos optimisations sur la console Amazon Ads en quelques secondes. En cliquant sur **Export Bulk Actions**, vous filtrez l'intégralité de vos lignes pour ne garder que les lignes d'actions suggérées.

Le fichier CSV plat utilise un séparateur point-virgule standard, immédiatement lisible par Excel ou Google Sheets, vous permettant de copier-coller vos actions en masse directement dans votre gestionnaire de campagnes Amazon.

Bonnes pratiques

Conseils Pro & Stratégie

📅 Sélectionnez la bonne Période d'Analyse

Lors du téléchargement de vos rapports, nous vous recommandons d'utiliser une période d'analyse des **30 derniers jours** (en excluant les dernières 48 heures pour tenir compte du décalage d'attribution des ventes Amazon). Cela donne au moteur un volume statistique robuste.

✍️ Optimisez le Contexte Prompt IA

N'hésitez pas à fournir au Cerveau IA des indications qualitatives précises (ex : *"Nous lançons une nouvelle saveur la semaine prochaine et devons être agressifs sur la conquête concurrentielle"* ou *"Rupture de stock sur l'ASIN B jusqu'en juin, réduisez la voilure sur les campagnes 3 et 4"*). L'IA ajustera sa feuille de route en conséquence.

⚖️ Équilibrez le TACoS & les Marges Nettes

Suivez attentivement votre TACoS (Total Advertising Cost of Sales). Si vos ventes organiques sont fortes mais que vos marges nettes souffrent, utilisez les suggestions d'enchères de Keoxs pour réduire progressivement la pression publicitaire jusqu'à ce que votre TACoS repasse sous la barre cible des 15 %.