Où est Ava ? — Prototype 1

Statut: 🟡 En cours
Type: 🧪 Prototype
Diffusion: 🔒 Interne uniquement — non public, tests utilisateurs prévus en septembre 2026 Créé avec: Lovable
Démarré: 2026-03-07

Plateforme de référence

Lovable compile le code et publie le site. Le backend, la base de données, les Edge Functions et les secrets passent par Lovable Cloud, avec Supabase fourni par Lovable. Il ne faut pas remplacer cette chaîne par un build, un déploiement, un hébergeur ou un projet Supabase externe.

Les développements réalisés depuis un autre environnement doivent rester compatibles avec Lovable et être ramenés dans le projet Lovable avant toute validation ou publication. Les instructions obligatoires destinées à tous les agents et outils du dépôt sont dans AGENTS.md.

La mise en public est bloquée par la release gate. Un aperçu interne peut être utilisé pour le développement, mais aucun lien ne doit être diffusé à des testeurs externes avant validation des critères de sécurité, persistance et endurance.

Mise à jour récente (2026-07-21) — traces causales de Max : les administrateurs peuvent lancer une session PRD4 explicitement tracée et inspecter chaque tour (mémoire, RAG et scores, prompt assemblé, payload OpenRouter exact, modèle, réponse et latences). La trace causale est enregistrée avant l’affichage et le TTS ; en cas d’échec d’écriture, le tour n’est pas diffusé et peut être rejoué. Détails : docs/max-causal-tracing.md.

Mise à jour récente (2026-07-13) — télémétrie des tests internes : le panneau voix/analytics est temporairement masqué et les événements techniques PostHog/Grain sont actifs par défaut. Le panneau final reste disponible avec VITE_PRIVACY_NOTICE_ENABLED=true. Autocapture, replay, profils persistants et texte libre restent exclus. Détails : docs/phase4_privacy_prepublic_runbook.md.

Mise à jour précédente (2026-07-13) — Phase 3 : canary interne : la durée est pilotée uniquement par TIMEOUT_SECONDS dans le slider admin ; le timer et le Game Master suivent cette valeur. Les seuils de promotion/rollback sont codifiés, la persistance devient observable et PostHog n'utilise plus autocapture ni session replay. Détails : docs/phase3_internal_canary_runbook.md.

Mise à jour précédente (2026-07-13) — Phase 2 : fluidité et endurance configurable : contexte LLM borné, résumé persistant, RAG fail-soft et annulation des tours obsolètes. Le watchdog protège l'attente de la première voix sans limiter la durée d'une lecture TTS en cours. Les tests couvrent 1 050 tours orchestrateur, un soak navigateur de 35 tours et une réponse audio dépassant le watchdog. Détails : docs/phase2_fluidity_endurance_report.md.

Mise à jour récente (2026-05-22) — PRD4 : nouveau parcours post-film + rôle utilisateur + Max contextualisé : refonte structurante livrée en 6 phases. L'onboarding A/B est supprimé au profit d'un parcours unique « tu viens de voir le film, tu appelles quelqu'un ». Le joueur définit son rôle à la voix (push-to-talk + résumé Gemini Flash), Max reçoit ce rôle dans son system prompt, 4 personnages s'affichent (Max actif, Emma/Ava/Léo grisés), le GM pré-tour est retiré du chemin temps réel et le GM post-turn tourne en async (sessions.gm_post_turn_log). Nouveau questionnaire 10 questions + mapping Notion avec accents exacts. Back-office enrichi (rôle utilisateur + timeline GM post-turn). Détails : CHANGELOG.md, STORY.md, docs/plan_prd4_implementation.md, PRD documents/PRD_4_prototype_mai_2026.md.

Mise à jour précédente (2026-05-22) — Robustesse voix multi-navigateurs + optimisation latence live + observabilité PostHog : audit détaillé du pipeline vocal Max (docs/audit_voice_conversation_max.md) puis durcissement du runtime voix : sélection MIME STT, timeouts critiques, audio unlock, lecture TTS robuste, preset Conversation temps réel, silence STT réduit à 900 ms. Deuxième passe latence : Gemini 2.0 Flash, réponses limitées à 220 tokens / 1-2 phrases, RAG compacté, suppression du GM pré-tour LLM du hot path. Troisième passe observabilité : turn_id, événements PostHog voice_turn_completed / voice_error, tables internes voice_turn_events / voice_error_events, et stats back-office end-to-end.

Mise à jour précédente (2026-05-16) — TTS multi-providers + voix Alain (Inworld) + monitoring « Consommation Voix » : refonte du TTS en façade découplée (src/services/tts/) avec 3 providers branchés — ElevenLabs, Inworld inworld-tts-2 (voix « Alain » en streaming NDJSON, deliveryMode STABLE/BALANCED/CREATIVE) et Hume AI Octave. Sélection d'un seul provider actif global depuis Admin → TTS Config, sans redéploiement, avec bouton 🔊 Tester par provider. Nouveau dashboard « Consommation Voix » : compteurs, taux de succès, latences p50/p95 (first-byte + total), distribution des codes HTTP et erreurs récentes par provider. Secrets INWORLD_API_KEY et HUME_API_KEY ajoutés. Détails dans CHANGELOG.md et STORY.md.

Mise à jour précédente (2026-05-10) — RAG v2 (Voyage AI + reranker + query rewriting + mémoire de session) : embeddings Voyage AI voyage-3 (1024 dim) en double-stack avec OpenAI, reranker rerank-2.5, filtrage strict par character_id, indexes pgvector HNSW, edge functions rewrite-query et summarize-session.

Mise à jour précédente: banc d'essai complet « Test de réponse Max » — refonte de l'onglet en outil d'inspection du pipeline conversationnel étape par étape (RAG → Knowledge → GM pré-tour → Max → Validateur). Document de plan : docs/plan_max_test_inspector.md.

En une phrase

Expérience narrative interactive voice-to-voice avec Max, un personnage fictif piloté par IA, dans l'univers de "Où est Ava ?".

📋 Source de vérité

• PRD: documents/PRD_Prototype_1.md
• Notion: Bases éditoriales AVA (Characters, Storyworld, Gameplay, Vidéos)
• Dernière sync: 2026-03-08

🎯 Objectif projet

Valider le pipeline technique complet d'une conversation voice-to-voice avec un personnage IA : STT (Deepgram) → LLM (OpenRouter/multi-modèles) → TTS (ElevenLabs), orchestré par un Game Master autonome qui gère la confiance, les triggers vidéo et le game over, enrichi par un pipeline RAG connecté à Notion.

Le chantier en cours suit le plan documents/plan_implementation_max.md pour mieux séparer l'identité de Max, les connaissances autorisées, les contraintes de révélation et la supervision éditoriale du Game Master.

✅ Livrables

• Pipeline voice-to-voice complet (STT → LLM → TTS)
• Agent Max conversationnel (prompt système, streaming)
• Agent Game Master orchestrateur (JSON structuré)
• Système de triggers vidéo (Gumlet player + fallback placeholder)
• Cinématique d'intro vidéo Gumlet
• UI dark theme cinématique
• Questionnaire de fin intégré
• Pipeline RAG (Notion → Supabase → embeddings → prompt enrichi)
• Sync Notion → Supabase (4 bases : Characters, Storyworld, Gameplay, Vidéos)
• Embeddings OpenAI (text-embedding-3-small, 1536 dim) + pgvector
• Query RAG sémantique (match_embeddings)
• Sauvegarde de session complète
• Micro persistant continu (pause/resume sans reconnexion)
• Sync questionnaire → Notion
• Dashboard admin (sessions, questionnaires, édition system prompt)
• Pipeline TTS par phrase (sentence-level streaming)
• Config LLM dynamique (multi-modèles : Qwen, Claude, Grok, Llama, Gemini)
• Config voix ElevenLabs (stability, similarity, style, speed, presets)
• HUD conversationnel (timer + jauge confiance + tooltips explicatifs)
• Accès questionnaire anticipé (après 4 min)
• Modal info projet (détail concept, pipeline, objectifs)
• LLM Cost Tracker (tracking automatique tokens + coûts USD par appel OpenRouter)
• Persistance des réglages admin en base (LLM, Voix, Gameplay, GM)
• Rapport de sync Notion détaillé (entrées, chunks RAG, tokens par table)
• Player vidéo Gumlet (iframe embed responsive plein écran)
• Contrôle éditorial structuré de Max (persona, objectifs, historique, interdictions d'affirmation)
• Simulateur admin de réponse Max avec contexte RAG de test
• Inspecteur admin persistant des traces PRD4 live, par session et par tour
• Pré-turn planner Game Master disponible dans le simulateur (non exécuté en PRD4 live)
• Robustesse du tracking de coûts OpenRouter en cas de génération introuvable temporairement
• Validation anti-hallucination avec retry + fallback dans le simulateur (non exécutée en PRD4 live)
• Aperçu admin de la fusion faits globaux + contexte autorisé du tour avant validation
• Persistance des traces de validation par message dans conversation_log
• Métriques admin de hallucinations (taux régénération + fallback sur 50 dernières sessions)
• Catalogue formel des modes de parole de Max (6 styles éditoriaux)
• Schéma visuel du pipeline conversationnel (8 étapes + glossaire)
• Tests automatisés orchestrateur + validateur + composants admin
• Pipeline PRD4 parallélisé (labels GM en parallèle de Max, GM post-tour destiné au tour suivant)
• Validateur du simulateur en mode fail-open (timeout 4s + résilience aux JSON malformés)
• Panneau admin "Latence & blocage" : timings par étape (RAG/GM/Max/validateur/TTS) + détection du point de blocage
• Accès /admin protégé par mot de passe (anti-accès accidentel)
• Visualisation comparative multi-sessions des latences réelles (barres empilées par session)
• Détail par tour dépliable depuis chaque barre de session, avec marqueur de cible 2 s commun
• Indicateur de dispersion par session (bracket min–max + écart-type σ sur le total des tours)
• Filtres sessions (période, nombre min de tours, présence de blocage) + auto-dépliage au focus
• Mini-graphique GM fallback (elapsed_ms vs timeout_ms) dans l'onglet Sessions
• Diagnostic factuel des latences au survol des segments (budget cible, ratio vs médiane, p95, hypothèses d'optimisation)
• Panneau latéral détaillé (SegmentDetailSheet) au clic sur un segment de latence
• Filtre "Sévérité min." dans la vue latence (atténuation visuelle des segments sous le seuil)
• Guide Game Master (documents/guide_game_master_contenus_et_tests.md) — prompts, variables, hypothèses, variantes à tester
• Banc d'essai complet d'inspection du pipeline Max (RAG → Knowledge → GM Pre → Max → Validator) avec chronologie, tokens, latences, contexte injecté décomposé, brief GM JSON, prompt système final, diagnostic validateur, export JSON et presets rapides
• Embeddings Voyage AI voyage-3 (1024 dim) en double-stack avec OpenAI + reranker rerank-2.5 appliqué après retrieval
• Filtrage strict par personnage (character_id) sur les chunks RAG (chunks scopés vs partagés)
• Indexes pgvector HNSW (m=16) — fix scoring quasi-nul sur petits datasets vs ivfflat
• Query rewriting LLM (rewrite-query edge function) — reformulation autonome avant RAG
• Mémoire de session compressée (summarize-session + table session_summaries) injectée dans le prompt Max
• Affichage banc d'essai : étape Query rewrite, badge provider d'embedding, par chunk character_id/rerank_score/retrieval brut
• TTS multi-providers : façade src/services/tts/ + providers ElevenLabs / Inworld (inworld-tts-2, voix « Alain », streaming NDJSON) / Hume AI Octave, sélection d'un provider actif global depuis Admin → TTS Config
• Dashboard « Consommation Voix » : compteurs, taux de succès, latences p50/p95 (first-byte + total), codes HTTP et erreurs récentes par provider
• Robustesse voix multi-navigateurs : sélection MIME STT à l'exécution, timeouts critiques, audio unlock, erreurs TTS/STT trackées et état conversationnel récupérable
• Preset voix basse latence : réglage realtime_conversation pour tests voice-to-voice rapides (eleven_turbo_v2_5, MP3 64 kbps, optimizeStreamingLatency=1)
• Optimisation latence live Max : modèle live rapide par défaut, contexte RAG compacté, GM pré-tour LLM retiré du chemin temps réel, réponses orales bornées à 1-2 phrases
• Observabilité latence voix PostHog + admin : événement agrégé voice_turn_completed, erreur unifiée voice_error, corrélation turn_id, stockage Supabase voice_turn_events / voice_error_events, dashboard cible documenté
• PRD4 — Parcours unique post-film : ExperiencePhase à 11 états (welcome → film_question → teaser → role_capture → role_summary → character_select → calling_max → conversation_max → end_session → questionnaire → thanks), 9 écrans dédiés (src/components/prd4/*), entrée racine / directement sur IndexPRD4
• PRD4 — Rôle joueur libre : capture push-to-talk + edge function summarize-role (Gemini 2.5 Flash) qui produit un UserRoleProfile JSON (summary_for_user, summary_for_max, relationship_to_family, age, gender, proximity_level, intent), persistance sessions.player_role
• PRD4 — Max contextualisé par le rôle : résumé summary_for_max injecté en tête du system prompt de Max avant la persona
• PRD4 — GM post-turn async : agent gameMasterPRD4.ts évalue chaque tour (engagement_delta, role_usage_quality, confusion, topics, end_recommended, next_turn_guidance), persistance append-only dans sessions.gm_post_turn_log, GM pré-tour retiré du chemin temps réel
• PRD4 — 4 personnages dont 3 grisés : grille 2×2, Max actif coloré, Emma/Ava/Léo grisés + cadenas + dialog d'indisponibilité, écran CallingMaxScreen (sonneries ~3 s) avant la conversation
• PRD4 — Nouveau questionnaire (10 questions) : film vu, teaser utile, clarté création rôle, justesse résumé, clarté/frustration PTT, Max reconnaît rôle, Max crédible, envie autres personnages, prochain personnage souhaité, durée ressentie, feedback ouvert + email + 2 opt-ins ; métriques techniques calculées automatiquement
• PRD4 — Sync Notion avec noms exacts (accents) : sync-questionnaire détecte version: "prd4" et écrit dans les propriétés Notion accentuées (PRD4 Rôle création clarté, PRD4 Résumé personnage justesse, PRD4 Max reconnaît rôle, PRD4 Personnage souhaité prochain, PRD4 Durée ressentie, PRD4 Rôle JSON, PRD4 Être tenu au courant, PRD4 Contact feedback détaillé…), filtrage côté serveur des propriétés absentes via fetchDatabaseProperties() (skipped_props logué)
• PRD4 — Back-office enrichi : SessionsTab admin affiche le rôle joueur (résumés + JSON repliable) et une timeline gm_post_turn_log compacte (engagement, role usage, confusion, end, modération, latence ms, sujets, next_turn_guidance)
• PRD4 — Nettoyage legacy : suppression de OnboardingAScreen, OnboardingBScreen, ABChoiceScreen, OnboardingScreen, GateScreen, pages/Index.tsx et de la route /legacy
• Video triggers dynamiques (depuis DB au lieu de hardcodés)
• Politique de vérité à 4 niveaux (certain / probable / inconnu / interdit)
• Bible factuelle éditable et gestion explicite des sujets verrouillés/déverrouillés
• Alertes de budget LLM + fallback modèle

🛠️ Stack technique

Composant	Technologie
Frontend	React + Vite + Tailwind + TypeScript (Lovable)
Backend	Lovable Cloud (Supabase Postgres + pgvector)
Edge Functions	proxy-llm, proxy-stt, proxy-tts, proxy-tts-inworld, proxy-tts-hume, sync-notion, query-rag, sync-questionnaire, rewrite-query, summarize-session
Video	Gumlet (hébergement + embed player)
Cost Tracking	OpenRouter generation API (tokens + USD per call)
LLM	OpenRouter API — Multi-modèles. Chemin live optimisé sur Gemini 2.0 Flash par défaut ; modèles plus lourds réservés aux tests/qualité depuis l'admin.
STT	Deepgram (WebSocket streaming + VAD) avec sélection MIME MediaRecorder à l'exécution et timeouts token/micro/WebSocket
TTS	Multi-providers via façade src/services/tts/ — ElevenLabs (voix custom Max), Inworld inworld-tts-2 (voix « Alain », streaming NDJSON), Hume AI Octave. Provider actif sélectionné dans Admin → TTS Config. Lecture audio robuste avec audio unlock et classification des erreurs navigateur.
Embeddings	Voyage AI voyage-3 (1024 dim, défaut) + OpenAI text-embedding-3-small (1536 dim, fallback)
Reranker	Voyage rerank-2.5 (toggle via RAG_RERANK_ENABLED)
Données	Notion (source de vérité) → Supabase (miroir + embeddings double-stack)
RAG	query-rag Edge Function + pgvector HNSW + filtrage character_id + query rewrite + session summary

🧭 Avancement du plan Max / GM

Le plan initial visait 5 phases pour réduire les inventions de Max et rendre son comportement éditorialement pilotable.

Déjà implémenté

• PRD4 live : Max reçoit mémoire bornée, résumé de session, RAG, contexte temporel, profil joueur et éventuelle guidance GM du tour précédent.
• Traçabilité : PipelineTraceTab relie chaque réponse diffusée à son entrée, son prompt, son payload OpenRouter exact, ses chunks RAG, ses réglages et ses latences.
• Game Master live : labels en parallèle et évaluation post-tour ; ces traitements sont séparés des causes de la réponse actuelle.
• Outils de simulation : GM pré-tour et validateur restent disponibles dans MaxPromptTestTab, mais ne sont pas exécutés dans le PRD4 live.
• Outils éditoriaux : MaxPromptControlTab, MaxPromptTestTab, AntiHallucinationValidatorTab, HallucinationMetricsTab.

Reste à développer

• Politique de vérité à 4 niveaux (certain / probable / inconnu / interdit) — refactor structurel de MaxTurnKnowledgeContext et du prompt validateur.
• Bible factuelle éditable : interface admin pour gérer les faits autorisés globaux.
• Gestion d'unlocked/locked subjects : pilotage fin des sujets révélables selon l'état narratif.

🚀 Démarrage rapide

# Cloner
git clone <YOUR_GIT_URL>

# Installer
npm install

# Lancer
npm run dev

Ou directement via Lovable.

🧪 Protocole de test RAG v2 (banc d'essai Max)

Prérequis : secret VOYAGE_API_KEY configuré dans Lovable Cloud, et données Notion synchronisées (sync-notion → embedding_v rempli).

1. Activer les toggles (src/config/settings.json)

{
  "RAG_EMBEDDING_PROVIDER": "voyage",
  "RAG_RERANK_ENABLED": true,
  "RAG_QUERY_REWRITE_ENABLED": true,
  "RAG_TOP_K": 5,
  "RAG_RETRIEVE_K": 15
}

2. Lancer le banc d'essai

Aller sur /admin → onglet Test de réponse Max.

3. Points de contrôle attendus

Étape	Contrôle	Détail
0. Query rewrite	Message ambigu (ex. "Et toi ?")	Vérifier que la requête est réécrite en phrase autonome dans l'accordéon
1. RAG	Provider badge	Doit afficher voyage (pas openai)
1. RAG	rerankUsed	Badge présent si RAG_RERANK_ENABLED=true
1. RAG	Par chunk	Vérifier character_id (scopé ou "shared"), retrieval_similarity (cosine brute), rerank_score (Voyage rerank-2.5)
4. Max	Réponse	Doit s'appuyer sur les chunks rerankés, pas inventer hors contexte
5. Mémoire session	Historique de 4+ tours	Après 4 tours utilisateur, un résumé est généré et réinjecté dans le prompt (visible dans le contexte final de Max sous SOUVENIRS DE LA SESSION)

4. Test rapide d'ambiguïté

Saisir un historique avec un message ambigu (antécédent manquant) et vérifier que le pipeline affiche la requête réécrite avant le RAG. Sans rewrite, le RAG retourne des chunks incohérents ; avec rewrite, les chunks doivent revenir cohérents avec le sujet rétabli.

🔗 Liens

• URL de prod: https://ava-proto1.lovable.app
• URL de preview: https://id-preview--1265958d-b74e-40f2-917d-182fe05163fc.lovable.app

📁 Structure

/
├── documents/              # PRD et documentation projet
├── src/
│   ├── agents/             # maxAgent.ts, gameMasterAgent.ts
│   ├── assets/             # Images (portrait Max)
│   ├── components/         # Écrans UI (Onboarding, Conversation, GameOver, etc.)
│   ├── config/             # settings.json (variables configurables)
│   ├── hooks/              # useGameState, useTimer
│   ├── services/           # deepgramSTT, elevenLabsTTS, openRouterLLM, orchestrator, ragService, settingsService, llmUsageTracker, sessionService
│   └── types/              # Types TypeScript partagés
├── public/assets/          # Background images
├── supabase/functions/     # Edge Functions (proxy-llm, proxy-stt, proxy-tts, sync-notion, query-rag, sync-questionnaire)
├── CHANGELOG.md            # Historique versionné
├── STORY.md                # Journal de développement
└── README.md               # Ce fichier

📝 Notes

• Secrets requis (dans Lovable Cloud) : OPENROUTER_API_KEY, DEEPGRAM_API_KEY, ELEVENLABS_API_KEY, ELEVENLABS_VOICE_ID, OPENAI_API_KEY, NOTION_API_KEY, VOYAGE_API_KEY
• Desktop only, Chrome recommandé
• Pas d'authentification — session locale
• Vidéos servies via Gumlet (intro fonctionnelle, triggers en cours de configuration)
• Sync Notion : 4 characters + 38 storyworld synchronisés, 42 embeddings générés
• Admin : /admin pour gérer sessions, prompts, config LLM/voix, suivi des coûts LLM, sync Notion détaillée
• Admin : /admin inclut désormais des onglets de contrôle du prompt de Max, de test éditorial et de trace pipeline Max/GM
• Les réglages admin sont persistés en base (survivent au rechargement et changement de navigateur)
• Le tracking de coûts OpenRouter est tolérant aux délais d'indexation et aux generation_id temporairement introuvables

---

Projet Memoways — Storygami