From 4dd8df53e168eaebf4eb947d7857a3796405a7b2 Mon Sep 17 00:00:00 2001 From: Hermann_Kitio Date: Thu, 2 Jul 2026 06:13:58 +0300 Subject: [PATCH] docs(adr-007): decide Gemini Live -> Deepgram migration for EO Live MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - New ADR-007: architecture decision to migrate T1+T2 Live audio from Gemini Live to decoupled Deepgram (STT nova-3 + DeepSeek LLM + Aura-2 TTS), following conclusive POC. Two-phase plan: parallel module behind EO_STT_PROVIDER flag, then full cutover with Gemini Live code removal (no long-term dual-stack intent). - ROADMAP.md: new Sprint 7c (migration, high-level entry, detailed breakdown deferred to dedicated planning session). Note added on Sprint 7e (TD-23 caveat resolved once Deepgram is live, streaming-native transcription). - TECH_DEBT.md v1.32: FTD-45/46 stay frozen (§3bis), resolution path now points to ADR-007. No active FTD cap breach (15 unchanged) — deliberate choice to defer reopening until Sprint 7c execution begins. Docs only, no code changes. --- docs/ROADMAP.md | 8 +++ docs/TECH_DEBT.md | 7 ++- docs/adr/007-deepgram-vs-gemini-eo-live.md | 67 ++++++++++++++++++++++ 3 files changed, 79 insertions(+), 3 deletions(-) create mode 100644 docs/adr/007-deepgram-vs-gemini-eo-live.md diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index bbd7e7d..c92e5d0 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -172,6 +172,13 @@ - Tests manuels Groupe D étendu (T1 Live) rejoués - Commit refactor(t1-live) +## Sprint 7c — Migration audio EO Live : Gemini Live → Deepgram (T1 + T2) + +- Décision actée (**ADR-007**) de migrer l'architecture audio de Gemini Live natif vers une architecture découplée Deepgram (STT nova-3 + DeepSeek LLM + TTS Aura-2), suite à un POC concluant : transcription quasi parfaite à débit lent (vs confusions de langue/omissions Gemini), relances ancrées sur le discours réel du candidat, coût 4-5x inférieur. +- Implémentation en deux temps : (1) construction du module Deepgram en parallèle de Gemini Live derrière un flag `EO_STT_PROVIDER=gemini|deepgram` pour comparaison en conditions réelles, (2) bascule complète + retrait du code Gemini Live (`geminiLive.ts`, usages `t1live.ts`/`t2live.ts`). +- Résout FTD-45, FTD-46 (frontend, gelées avec renvoi vers cet ADR — cf. `TECH_DEBT.md`) et TD-22/TD-23 (backend, hors scope frontend — dépôt séparé). +- Découpage fin (sous-sprints backend/frontend) à définir dans une session de planification dédiée avant exécution — non détaillé ici. + ## Sprint 7e — Transcription live à l'écran (T2 + T1) - Affichage incrémental temps réel des prises de parole pendant le dialogue : router `inputTranscription` + `outputTranscription` (déjà produits côté backend pour l'évaluation) jusqu'au frontend via le WebSocket, puis rendu progressif à l'écran. @@ -179,6 +186,7 @@ - **Chantier non trivial** (flux WS + affichage incrémental) — à décomposer en sous-étapes ; pas « cosmétique ». - **MAJ post-7a** : source backend de la transcription déjà disponible (confirmé par 7a). - **Caveat TD-23** : en VAD manuel, `inputTranscription` candidat n'est flushé qu'à `activityEnd` (pas token par token) → l'affichage incrémental temps réel n'est possible que pour `outputTranscription` (examinateur) ; l'incrémental côté candidat est à reconcevoir. +- **Note (ajoutée 2026-07-02)** : à réévaluer/simplifier une fois la migration **Sprint 7c** (Deepgram, ADR-007) effectuée — le caveat TD-23 ci-dessus disparaît avec un provider nativement streaming. Ce sprint pourrait devenir substantiellement plus simple, voire trivial, une fois 7c terminé. ## Sprint 8 — Mode Examen diff --git a/docs/TECH_DEBT.md b/docs/TECH_DEBT.md index 2327983..9ea64b8 100644 --- a/docs/TECH_DEBT.md +++ b/docs/TECH_DEBT.md @@ -1,6 +1,6 @@ # TECH_DEBT.md — Expria Frontend -> **Document de référence — Version 1.31** +> **Document de référence — Version 1.32** > Ce document recense les décisions techniques prises par pragmatisme qui devront être revisitées, les stubs temporaires, et les fonctionnalités reportées. > À mettre à jour après chaque session de développement. > @@ -488,7 +488,7 @@ Frontend : **Impact actuel :** dégrade le réalisme de l'entretien T1 ; non bloquant pour la livraison 7b (le flux fonctionne, l'évaluation finale reste correcte). -**À faire :** ré-évaluer côté backend/prompt (formulation de la consigne de relance, fenêtre de contexte) une fois la transcription incrémentale repensée (Sprint 7e / TD-23). +**À faire :** ré-évaluer côté backend/prompt (formulation de la consigne de relance, fenêtre de contexte) une fois la transcription incrémentale repensée (Sprint 7e / TD-23). **Piste de résolution actée : voir ADR-007 (migration Gemini Live → Deepgram). Sera dégelée et réévaluée au démarrage du Sprint 7c.** **Condition de résolution :** après traitement de TD-23 (transcription live) — non actionnable côté frontend seul. @@ -503,7 +503,7 @@ Frontend : **Impact actuel :** qualité du transcript variable ; non bloquant pour 7b (l'évaluation 5 critères reste exploitable). -**À faire :** suivre l'évolution du modèle Gemini Live ; évaluer un post-traitement ou une source de transcription alternative si la qualité reste insuffisante au Sprint 7e. +**À faire :** suivre l'évolution du modèle Gemini Live ; évaluer un post-traitement ou une source de transcription alternative si la qualité reste insuffisante au Sprint 7e. **Piste de résolution actée : voir ADR-007 (migration Gemini Live → Deepgram). Sera dégelée et réévaluée au démarrage du Sprint 7c.** **Condition de résolution :** amélioration amont (modèle) ou décision d'architecture transcription au Sprint 7e. @@ -612,3 +612,4 @@ Frontend : | 1.29 | 2026-06-30 | Sprint 7b (T1 Live) — Ajout FTD-44 🟡 **gelée** (hooks audio génériques empruntés à `features/t2-live/`, réactivée au Sprint 7.5). **14 FTD actives** (inchangé — entrée gelée, ne compte pas dans le cap, même mécanique que FTD-06). | | 1.30 | 2026-06-30 | Sprint 7b (T1 Live, finalisation) — Ajout FTD-45 🟡 **gelée** (relances Gemini hors-sujet, extension TD-23) et FTD-46 🟡 **gelée** (transcription Gemini Live hasardeuse). Bugs amont observés au test manuel, hors contrôle frontend. **14 FTD actives** (inchangé — entrées gelées, ne comptent pas dans le cap). | | 1.31 | 2026-07-02 | Sprint 7.5 Clean — FTD-44 résolue (hooks audio relocalisés vers `shared/lib/audio/`, dégelée → fermée ; ne libère pas de place, une entrée gelée ne comptait pas dans le cap). Ajout FTD-47 🟢 (sessions T1 Live non taguées dans l'historique — découverte Sprint 7.5, racine Sprint 7a backend). **14 → 15 FTD actives — cap de 15 atteint.** | +| 1.32 | 2026-07-02 | ADR-007 — décision actée de migration Gemini Live → Deepgram (T1 + T2 Live, voir Sprint 7c dans ROADMAP.md). FTD-45 et FTD-46 : champ « À faire » complété avec un renvoi vers ADR-007, restent gelées en l'état (§3bis). **15 FTD actives, inchangé — FTD-45/46 restent gelées avec renvoi ADR-007, dégel prévu à l'ouverture du Sprint 7c.** | diff --git a/docs/adr/007-deepgram-vs-gemini-eo-live.md b/docs/adr/007-deepgram-vs-gemini-eo-live.md new file mode 100644 index 0000000..a1b7497 --- /dev/null +++ b/docs/adr/007-deepgram-vs-gemini-eo-live.md @@ -0,0 +1,67 @@ +# ADR 007 — Migration architecture audio EO Live : Gemini Live → Deepgram + +**Statut :** Accepté +**Date :** 2026-07-02 +**Décideur :** Hermann + +--- + +## Contexte + +L'Expression Orale Live (T1 + T2) repose depuis les Sprints 6-7 sur Gemini Live (modèle audio-à-audio natif, `geminiLive.ts` côté backend). Cette architecture présente un défaut rédhibitoire : une transcription de mauvaise qualité qui biaise systématiquement les corrections DeepSeek vers la sévérité (**FTD-46**) — un problème de fiabilité produit, pas cosmétique, sur un service qui évalue un examen officiel. Gemini pose également des questions de relance sans lien avec le discours du candidat (**FTD-45**, T1 Live). Ces deux défauts sont eux-mêmes une extension de la dette backend **TD-23** (en VAD manuel, `inputTranscription` n'est flushé qu'à `activityEnd`, donc sans transcription token-par-token fiable pour ancrer les relances). + +Un test comparatif (POC) a été mené entre l'architecture actuelle et une architecture découplée Deepgram (STT nova-3 + DeepSeek LLM + TTS Aura-2), pour évaluer si ces défauts sont propres à Gemini ou inhérents au produit. + +## Résultats du test comparatif (POC) + +- **Transcription** : à débit de parole lent du candidat, Deepgram approche la perfection sur la tâche T1 Live (quasi 100 %). Gemini produit des confusions de langue et des omissions de phrases entières en conditions réelles. +- **Relances/interruptions** : Deepgram (LLM + orchestration) pose des questions ancrées sur le discours réel du candidat, contrairement à Gemini qui relance hors-sujet. +- **Coût** : Deepgram + DeepSeek + Aura-2 ≈ 0,015-0,020 $/session de 2 min vs Gemini Live ≈ 0,075-0,080 $/session — 4-5x moins cher. Réserve : tarifs volatils, le calcul Gemini n'inclut pas la réaccumulation de contexte par tour — à revérifier avant tout engagement budgétaire. +- **Seul point faible identifié** : débit vocal Aura-2 FR légèrement lent et non naturel à T2, aucun paramètre de vitesse fiable trouvé sans risque de régression. Jugé préférable malgré tout à un débit naturel qui s'accompagne de confusions de langue et d'omissions de phrases côté Gemini — compromis assumé, pas un point bloquant. +- **Détail d'implémentation validé sur le POC** (Fable 5, agent de code) : succès one-shot sur T1 (contrainte d'ancrage sur tout le monologue, point d'échec de Gemini) ; T2 a nécessité du debug itératif mais les causes étaient des artefacts d'exécution (build obsolète), pas des limites structurelles. + +## Options envisagées + +### Option A — Statu quo : Gemini Live + +- Avantages : modèle unique audio-à-audio natif, pas d'orchestration multi-service, déjà en production (T1 + T2 livrés Sprints 6-7). +- Inconvénients : transcription de qualité inégale biaisant systématiquement les corrections DeepSeek vers la sévérité (FTD-46) ; relances hors-sujet en T1 (FTD-45) ; caveat TD-23 (flush transcription à `activityEnd` seulement) bloquant l'affichage incrémental prévu au Sprint 7e. + +### Option B — Architecture découplée Deepgram (STT nova-3 + DeepSeek LLM + TTS Aura-2) + +- Avantages : transcription quasi parfaite à débit lent (T1), relances ancrées sur le discours réel du candidat, coût 4-5x inférieur, nativement streaming (résout TD-23 sans contournement), POC one-shot réussi sur T1. +- Inconvénients : complexité d'orchestration accrue (3 services au lieu d'1), débit vocal Aura-2 FR légèrement lent/non naturel à T2 (aucun paramètre de vitesse fiable trouvé), T2 a nécessité du debug itératif (causes non structurelles), tarifs à revérifier avant engagement budgétaire. + +## Décision + +**Option B** — migration actée de Gemini Live vers Deepgram, pour **T1 ET T2 Live**. + +## Plan d'implémentation en deux temps + +1. **Temps 1 — Construction en parallèle** : construire le module Deepgram à côté de Gemini Live, activé par un flag `EO_STT_PROVIDER=gemini|deepgram`, pour permettre des tests comparatifs en conditions réelles avant toute bascule définitive. +2. **Temps 2 — Bascule + retrait** : une fois la comparaison validée, bascule complète sur Deepgram et **retrait du code Gemini Live** (`geminiLive.ts` et son usage dans `t1live.ts` / `t2live.ts` côté backend). + +**Clause de non-maintien à long terme** : le flag `EO_STT_PROVIDER` est un outil de transition de sprint, pas une fonctionnalité permanente. Aucune intention de maintenir les deux architectures en parallèle à long terme. + +## Conséquences + +**Positives :** + +- Résout FTD-45 et FTD-46 à la racine. +- Résout également le caveat TD-23 du Sprint 7e (flush `inputTranscription` à `activityEnd` seulement) — Deepgram est nativement streaming, l'affichage incrémental candidat devient possible sans contournement. + +**Négatives :** + +- Complexité d'orchestration accrue pendant la phase de transition (3 services au lieu d'1) — mitigée par le fait que le flag est temporaire, pas un choix d'architecture permanent à deux branches. +- Travail de retrait à prévoir en fin de migration : suppression du code Gemini Live une fois Deepgram validé (hors scope de cette session doc-only). + +**À revisiter si :** + +- Les tarifs Deepgram / DeepSeek / Aura-2 évoluent défavorablement (réserve explicite sur la volatilité tarifaire et sur le calcul Gemini incomplet ci-dessus). +- Un paramètre de vitesse Aura-2 FR fiable devient disponible (lèverait le seul point faible identifié). + +## Références + +- `TECH_DEBT.md` FTD-45, FTD-46 (renvoi vers cet ADR), FTD-47 +- `ROADMAP.md` Sprint 7c (migration, à planifier en détail dans une session dédiée) +- `expria-backend/docs/TECH_DEBT-backend.md` TD-22, TD-23 (dette backend directement concernée — non modifiée dans cette session, dépôt séparé)