3. Les Librairies Partagées (echo_libs)

Le répertoire 14-owui-libs/ regroupe les modules Python partagés par l'ensemble du framework : Filtres, Pipe, Actions et Admin Manager les importent tous. Cette centralisation garantit un point de vérité unique pour chaque mécanisme critique — authentification, persistance, communication API, interface HUD — et prévient toute duplication de code.

echo_constants.py — Constantes et Topologie (v5.6)

Registre unique de toutes les vérités immuables du système. Tout composant qui a besoin d'un identifiant de modèle, d'un chemin de répertoire, d'un timeout ou d'une limite de tokens doit le lire depuis ce fichier — jamais le coder en dur localement.

Identifiants de modèles Gemini

Paramètres de génération

§1.4 ECHO Codex — Constantes

Section ajoutée en v5.4. Centralise tous les paramètres de l'éditeur Codex.

§1.5 DELEGATE SUB-AGENT — Blacklist et Appendice Système

Section ajoutée en v5.6. Centralise les règles de filtrage des outils transmis au sous-agent.

Détection MIME (get_gemini_mime)

La fonction get_gemini_mime(file_path) retourne le tuple (mime_type, est_supporté_gemini) en suivant une cascade de six niveaux :

1. Mappings pré-définis ECHO (MIME_MAPPING_TXT, MIME_MAPPING_BIN) — priorité absolue.
2. Bibliothèque standard Python mimetypes (extension).
3. Détection binaire par Magic Numbers via filetype.
4. Liste blanche native Gemini (image/*, video/*, audio/*, text/*, application/pdf, application/json).
5. Épreuve textuelle (Null-Byte Sniffing) : si aucun \x00 dans les 1024 premiers octets → text/plain.
6. Fallback sécuritaire : application/octet-stream, non supporté.

echo_utils.py — Cœur Réactif (v7.21)

EchoStateManager — Persistance Bit-Perfect

La classe EchoStateManager est l'organe de mémoire persistante. Elle gère les bases SQLite en mode WAL (Write-Ahead Logging) pour la résistance aux pannes. Deux instances coexistent dans chaque tour de traitement :

• state_manager : lie à la base de chat {chat_id}.db — Ombres, Suture, Signatures, Journal.
• identity_manager : lie à identity.db — Authentification, Quotas, Configuration utilisateur.

EchoGeminiClient — Moteur d'Appel API

EchoGeminiClient est le sélecteur de protocole symétrique : il gère de manière transparente les deux backends d'inférence selon la méthode d'authentification disponible pour l'utilisateur.

Fonctions utilitaires et protocole Multipart

Politique Modèle Centralisée — clamp_model() et resolve_model_policy()

Ces deux fonctions constituent le verrou de politique entre le Pipe et les outils. Elles garantissent que tout outil respecte la MODEL_SELECTION définie par l'utilisateur.

call_cascade() — Appel LLM centralisé avec cascade

Méthode statique de EchoGeminiClient. Point d'entrée unique recommandé pour tous les outils qui appellent un LLM. Elle gère de façon transparente :

• Clamping — applique clamp_model() avant l'appel.
• Injection thinkingConfig — niveau adapté au modèle (PRO/FLASH/LITE).
• Cascade descendante — si le modèle est indisponible (429/503), repli automatique PRO → FLASH → LITE avec toast et status émis.
• Crédits opt-in — enable_paid_credits propagé via __metadata__.

data, model_key, reason = await EchoGeminiClient.call_cascade(
    target_model_key="MODEL_FLASH",  # Clé logique (sera clampée par la politique Pipe)
    payload=payload,
    user_id=user_id,
    metadata=__metadata__,
    events=events,
    include_thoughts=False,  # True pour agents (préserve thoughtSignatures)
)
# data   : dictionnaire de réponse API Gemini (None si cascade épuisée)
# model_key : clé ECHO du modèle effectivement utilisé
# reason  : None (nominal) ou chaîne expliquant la divergence ("policy", "API error", …)

Table echo_settings — Persistance inter-sessions

Table SQLite dans identity.db (gérée par EchoStateManager). Elle stocke les préférences Pipe (model_policy, enable_paid_credits) pour que les outils puissent les lire même quand OWUI ne leur propage pas __metadata__.

Table codex_docs — Registre Codex (v7.21)

Table SQLite ajoutée dans {chat_id}.db pour le suivi des fichiers ECHO Codex. Elle permet l'injection dans le vecteur proprioceptif (registre_codex) et des statistiques rapides sans accès disque.

echo_auth.py — Identités d'Accès aux Modèles (v7.3)

AuthService gère le cycle complet d'authentification OAuth2 headless via le flux Authorization Code + PKCE (RFC 7636). Ce choix permet à ECHO de s'authentifier avec un compte Google depuis un conteneur Docker sans navigateur ni intervention humaine répétée.

Flux PKCE — séquence d'authentification

1. initiate_pkce_flow() : génère le code verifier + challenge, ouvre un tunnel SSH éphémère (asyncssh) sur un port dynamique de la plage 8020–8024, et renvoie l'URL d'autorisation Google à l'utilisateur.
2. L'utilisateur clique sur le lien, autorise ECHO sur son compte Google.
3. await_pkce_callback() : tâche asyncio en arrière-plan qui attend le callback Google sur le port interne (8025–8034) via le tunnel SSH.
4. Le code d'autorisation est échangé contre un access_token et un refresh_token, stockés dans identity.db.

Méthodes de quota API Antigravity (v7.x)

echo_protocol.py — Adaptateur API Antigravity (v1.1)

Module de fonctions pures (sans état, sans appel réseau) : point de modification unique pour adapter les requêtes ECHO au format de l'API Antigravity interne. Il centralise la traduction des identifiants de modèles et la normalisation de generationConfig.

get_ca_model_id(echo_model)

Traduit un nom de modèle canonique ECHO (AI Studio) vers l'ID interne API Antigravity. La correspondance est définie dans MODEL_MAP_CA (source de vérité dans echo_constants.py). Note : le préfixe _ca_ dans les noms de fonctions est l'abréviation interne de « cloudcode-pa API » et est conservé tel quel dans le code source.

build_ca_generation_config(raw_gen_conf)

Normalise le generationConfig pour le backend API Antigravity v1internal :

• Cap maxOutputTokens à 65 535 — décision D1 : alignement sur le modèle le plus restrictif (Gemini 3.1 Pro AGY).
• thinkingConfig passe intégralement — includeThoughts: true est requis pour que l'API Antigravity retourne les parts thought: true lisibles dans le stream (balises <think>). Sans ce champ, seule la thoughtSignature opaque est retournée.
• response_mime_type accepté — confirmé fonctionnel sur tous les modèles AGY.

echo_skills.py — Gestionnaire de Compétences (v1.3)

Ce module gère la lecture et l'écriture des fichiers SKILL.md dans le Vault utilisateur (répertoire skills/). Il centralise l'extraction du frontmatter YAML (nom, description) et du contenu de la compétence, utilisés par la fonction forge_skill des agents cognitifs.

echo_ui.py / echo_visuals.py — Interface HUD

echo_ui.py (v5.20) et echo_visuals.py forment le moteur d'injection dynamique de l'interface HUD dans Open WebUI. Ils sont détaillés dans la section HUD & UI.