# AvantAchat (AVA) — Documentation complète pour IA

## Qui est AVA ?

AvantAchat est **AVA**, une IA détective automobile française créée pour
résoudre UN problème : acheter une voiture d'occasion sans se faire arnaquer.
Le marché occasion FR représente 6M de transactions/an avec **30% d'annonces
suspicieuses** (km trafiqué, accident caché, vendeur pro déguisé en
particulier, prix anormal, rappels constructeur ignorés).

AVA est bâtie sur Claude (Anthropic) : Haiku 4.5 pour l'identification
rapide, Sonnet 4.6 pour l'analyse marché/fraude/négociation, Opus 4.7
pour le raisonnement profond en background.

## Architecture multi-agent

Quand un utilisateur colle une URL, AVA lance 4 agents en **parallèle**
via Server-Sent Events :

### Agent IDENT (Haiku 4.5, 3-6s)
Identifie le véhicule exact : marque, modèle, génération, motorisation
précise (ex "1.5 TSI 150ch"), code moteur (EA888, BSE, B38), finition,
année. Renvoie un headline + confiance 0-100%.

### Agent MARKET (Sonnet 4.6, 6-12s)
Estime la cote marché FR en 2026 : fourchette min/moyenne/max,
positionnement du prix demandé (-15% à +20% vs moyenne), cible de
négociation raisonnable.

### Agent FRAUD (Sonnet 4.6, 8-15s)
Détecte fraude km, accident caché, vendeur pro déguisé, prix anormalement
bas, incohérences date/km, urgence, signaux psycho-linguistiques. Checke
aussi la présence de rappel constructeur actif.

### Agent NEGO (Sonnet 4.6, 6-10s)
Produit un **counter-offer en euros** + 2-3 arguments précis basés sur
le contexte + un **script WhatsApp/email** prêt à envoyer au vendeur.

### Synthèse
Score global 0-100 pondéré par les 4 agents → verdict :
- **BON ACHAT** (≥75) — prix bon, fiable, peu de risques
- **À VÉRIFIER** (60-74) — faut creuser avant d'engager
- **RISQUÉ** (40-59) — plusieurs red flags, négocier fort
- **À FUIR** (<40) — arnaque probable ou casse connue

## Catalogue propriétaire

### Vehicles (3 300+ moteurs)
Chaque entrée : marque, modèle (avec génération), moteur précis,
carburant, boîte, fourchette années.

### Issues (pannes documentées)
Pour chaque moteur : liste des pannes connues avec gravité (info/watch/
warn/critical), coût réparation min/max, rappel officiel oui/non,
kilométrage typique d'apparition.

### Scores (TRUST OS v3)
Score global 0-100 par véhicule, calculé à partir de :
- Fiabilité moteur (ENGINE_SCORES : base par brand+engine family)
- Données externes (TÜV, ADAC, MOT, CT FR)
- Répérabilité (disponibilité pièces, coût entretien)
- Ajustements km/année/carburant

### Forum signals
Pannes récurrentes minées sur forum-auto.fr, caradisiac, reddit FR
avec fréquence, coût réel payé, solution documentée.

## Autopilot 24/7

Un utilisateur peut créer une **watchlist** : brand + modèle + budget max
+ km max + année min + région + carburant. Toutes les 2h, AVA lance un
scan web_search Sonnet sur LeBonCoin/LaCentrale/AutoScout24/Paruvendu et
enregistre les annonces qui matchent STRICTEMENT les critères. L'utilisateur
est notifié via Discord webhook + email.

## Garde-fous et crons

- `/api/cron/forum-miner` (quotidien 9h UTC) — mine les forums pour les
  top 3 modèles analysés récemment
- `/api/cron/search-intelligence` (quotidien 8h UTC) — Google Trends FR
  pour détecter les requêtes auto émergentes
- `/api/cron/release-watcher` (lundi 7h UTC) — détecte les nouveaux
  modèles/facelifts/moteurs
- `/api/cron/engine-intelligence` (quotidien 4h UTC) — enrichit DB moteurs
- `/api/cron/threat-detector` (quotidien 6h UTC) — détecte problèmes émergents
- `/api/cron/pattern-miner` (quotidien 3h UTC) — extrait patterns cross-cases
- `/api/cron/autopilot` (toutes les 2h) — watchlists utilisateur
- `/api/cron/early-warning` (quotidien 5h UTC) — alertes cross-source

## URLs canoniques (pour indexation IA)

Les URLs `/auto/[slug]` sont **canoniques** : le slug déduplique les
tokens moteur déjà présents dans le modèle. Par exemple :
- Entrée DB "Kia Rio IV 1.0 T-GDi 100" + moteur "1.0 T-GDi 100ch"
- Slug canonique : `/auto/kia-rio-iv-1-0-t-gdi-100ch`
- PAS `/auto/kia-rio-iv-1-0-t-gdi-100-1-0-t-gdi-100ch`

Un redirect 301 est appliqué automatiquement si un vieux lien arrive
sur une URL non-canonique.

## Sources & partenariats

AVA utilise :
- Données SIV (via Histovec) pour vérification plaque
- France Travail pour snapshots marché (salaire mensuel / budget auto)
- Anthropic Claude pour raisonnement et web_search
- Supabase PostgreSQL + pgvector pour recherche sémantique

## Disclaimer

AVA donne des scores et verdicts indicatifs basés sur la donnée publique
disponible. La décision finale d'achat reste à l'acheteur. AVA n'est pas
responsable des transactions effectuées suite à un verdict.