2. Librairies Partagées (echo_libs)

Le socle technique d'ECHO repose sur un triptyque de librairies situées dans 14-owui-libs/. Ces modules assurent la cohérence, la résilience et l'interopérabilité de tout l'écosystème.

Architecture Strictement Factorisée

Toutes les couches (Filtres, Pipes, Outils) importent ces libs. Toute modification ici impacte l'intégralité du framework. L'utilisation de httpx avec support HTTP/2 est le standard obligatoire.

echo_constants.py : Constantes & Topologie

Définit l'environnement d'exécution et les paramètres globaux du protocole Gemini.

Topologie Système

Constante	Valeur / Rôle
`ECHO_USERS_ROOT`	`/app/backend/data/users` (Stockage des BDD et Vaults)
`ECHO_UPLOADS_DIR`	`/app/backend/data/uploads` (Transit des fichiers OWUI)
`ECHO_USER_AGENT`	`ECHO-Framework/5` (Identité réseau pour l'API Google)

Détection MIME Intelligente

La fonction get_gemini_mime(file_path) est le crible d'entrée pour Gemini. Elle utilise une cascade de 6 niveaux :

Mapping ECHO : Extensions prioritaires (code source, configs).
Mimetypes Std : Bibliothèque standard Python.
Magic Numbers : Signature binaire via filetype.
Whitelist Gemini : Filtrage natif Google (PDF, Images, Vidéos, Audio).
Null-Byte Sniffing : Épreuve textuelle pour identifier le texte brut sans extension.
Fallback : Rejet sécurisé en application/octet-stream.

echo_auth.py : Validation d'Identité

Gère le workflow d'enrôlement des clés API des utilisateurs.

AuthService

get_auth_prompt() : Retourne le message formaté demandant à l'utilisateur de configurer ses clés.
validate_and_save_api_key(raw_input) :
- Extrait les clés via Regex (AIza...).
- Valide en parallèle (asyncio.gather) jusqu'à 2 clés auprès de Google.
- Enregistre la clé primaire et la clé de secours.
- Nettoie les anciens tokens OAuth obsolètes.

echo_utils.py : Le Cœur Réactif

Contient les classes maîtresses de gestion d'état, de communication et d'interface.

EchoGeminiClient : Moteur de Résilience & HTTP/2

Ce moteur factorisé est le point de passage unique pour toutes les requêtes sortantes vers l'API Google AI Studio. Il implémente une stratégie de "Cognitive Cascade" et de "Failover" automatique.

Protocole HTTP/2 Strict

ECHO exige un client httpx.AsyncClient configuré en HTTP/2 strict. Ce choix technique est vital pour le streaming Gemini (SSE), permettant de maintenir des connexions multiplexées sans subir les limitations de performance du HTTP/1.1 (Head-of-line blocking). Le singleton _SHARED_ASYNC_CLIENT gère dynamiquement l'expiration des sessions pour prévenir les fuites de mémoire.

Mécanique de Failover (Switching Seuil)

L'algorithme de tentative ne se contente pas de répéter l'appel. Il surveille les erreurs 429 (Rate Limit) et 503 (Service Unavailable) :

Seuil de Bascule (Valve KEY_SWITCH_THRESHOLD) : Si le nombre d'erreurs consécutives sur une clé dépasse ce seuil, ECHO bascule instantanément sur la clé de secours (google_api_key_secondary) sans interrompre la session utilisateur.
Jitter & Backoff : Les tentatives utilisent une gigue aléatoire (0.7x à 1.3x) pour éviter la synchronisation des requêtes lors d'une reprise de service Google.

EchoStateManager : L'Architecture Bit-Perfect

Le state_manager est l'organe de mémoire persistante d'ECHO. Il assure que le modèle ne perd jamais le fil, même lors de restructurations complexes du chat.

Le Système des Ombres (Shadowing)

ECHO ne se fie jamais au texte renvoyé par Open WebUI pour reconstruire le passé. Il utilise la table message_shadows pour stocker le "Moulage Original" (parts JSON) de chaque message associé à son updated_at physique. Si un message est édité, l'empreinte temporelle change, invalidant l'ombre et forçant une suture fraîche.

Algorithmes de Hachage & Suture

La continuité cognitive repose sur un double hachage SHA-256 :

Invariant Hash (SHA-256) : Calculé sur le triplet (rôle, contenu, tool_io). Il identifie de manière unique une "unité de sens". Si un outil a été appelé, ses entrées/sorties sont incluses dans le calcul pour garantir l'intégrité de la réponse.
Cumulative Hash (SHA-256) : Se calcule par hash(invariant + parent_cumulative). C'est l'ADN de la session. Chaque message porte en lui l'empreinte de toute la chaîne de réflexion précédente.

Logique de scellement (Python)

# Exemple de calcul de l'invariant bit-perfect
norm_c = json.dumps(content, option=json.OPT_SORT_KEYS)
norm_t = json.dumps(tool_io, option=json.OPT_SORT_KEYS) if tool_io else ""
invariant = hashlib.sha256(f"{role}|{norm_c}|{norm_t}".encode()).hexdigest()

EchoEvents : Communication Inter-Couches

Cette classe agit comme un bus d'événements asynchrone facilitant la remontée d'informations depuis les tréfonds du backend Python vers l'interface utilisateur OWUI.

Méthode	Événement OWUI	Impact UI
`emit("status", ...)`	`status`	Affiche une étape de réflexion avec une icône de chargement ou de succès dans le chat.
`toast(content, level)`	`notification`	Affiche une bannière temporaire (Toasts) en haut à droite (info, success, warning, error).
`call("input", ...)`	`input`	Interrompt l'exécution pour demander une saisie à l'utilisateur via une modale.
`call("execute", ...)`	`execute`	Injecte et exécute du JavaScript arbitraire dans le DOM du navigateur.

EchoUI : Le Moteur HUD (Heads-Up Display)

Le module monitor_ECHO est le cœur visuel d'ECHO. Il déploie un micro-système d'exploitation graphique injecté dynamiquement pour la supervision des artefacts.

Architecture du Moteur JS Injecté

Le JavaScript généré par _generate_universal_hud_js crée un objet window.echoEngine_xxx isolé. Il gère son propre état (position, zoom, timer) dans le LocalStorage, permettant au HUD de survivre aux rafraîchissements de page.

Capacités du HUD

Gestion de l'Espace : Calcul intelligent de la taille optimale (getBestSize) basée sur le ratio de l'image et le viewport.
Outils de Précision :
- Loupe (Zoom Active) : Rendu d'un canvas secondaire avec facteur 2.5x pour l'analyse de détails.
- Crop (Découpe) : Système de 8 poignées de redimensionnement pour extraire une zone spécifique.
Exportation Avancée : Supporte la copie directe vers le presse-papier ou le téléchargement local (PNG).
Auto-Destruction : Gestion d'un timeout optionnel avec fondu d'opacité avant suppression automatique du DOM.

Protocoles Sémantiques & Suture

ECHO utilise des fonctions utilitaires pour normaliser les échanges cognitifs entre Gemini et l'utilisateur.

Traitement de la Pensée (Thought Splitting)

La fonction split_thought_process(text) détecte les balises <think> ou <thought>. Elle sépare le raisonnement pur du texte final pour permettre l'archivage dans thought_archive et l'affichage différencié.

Standardisation des Sorties d'Outils

La fonction wrap_tool_output() est le contrat de sortie obligatoire. Elle garantit que les métadonnées (statut, nouveaux fichiers, multiparts) sont correctement encapsulées pour être interprétées par le Filtre et le Pipe lors de la phase de Suture.