8. Annexes Techniques : Référence Deep-Dive

Cette documentation constitue la "Vérité Sémantique" du Framework ECHO. Elle détaille chaque mécanisme, classe et base de données avec une précision absolue pour les ingénieurs et architectes système.

1. Spécifications du Data Layer (SQLite / WAL)

ECHO utilise une architecture de stockage distribuée, isolée par identifiant utilisateur (UUID/ID) et par session (ChatID).

Global Registry : identity.db

Base centrale de l'utilisateur assurant la persistance de l'identité et de la sécurité.

TableSchéma SQLDescription & Contraintes
auth_data key (TEXT PK), value (TEXT), updated_at (INT) Stockage chiffré (AES-256 GCM) des secrets API. Clés gérées : google_api_key, google_api_key_secondary.
user_profile uid (TEXT PK), preferences_json (TEXT) Dictionnaire de préférences utilisateur (Thème, Langue, Modèles favoris).
context_stats id (INT PK=1), data (TEXT), updated_at (INT) Métriques consolidées (usageMetadata) pour le monitoring des coûts.

Session Cortex : {chat_id}.db

Base éphémère ou persistante selon le mode de session, gérant la continuité cognitive (Suture).

TableColonnes CritiquesRôle de la Suture
message_shadows message_id (PK), chat_id, full_parts_json, updated_at Shadowing : Sauvegarde bit-perfect de l'état multimodal exact envoyé à Gemini. Indispensable pour la reprise de contexte.
suture_index cumulative_hash (PK), invariant_hash, parent_hash, message_id Indexation SHA-256 garantissant qu'aucun message n'a été altéré ou perdu entre deux tours.
processed_files file_id (PK), filename, mime, mode, file_content Registre des artefacts. file_content stocke les moulages sémantiques (Smart Context).
cognitive_signatures cumulative_hash (PK), thought_signature, model_id Archive les identifiants de pensée Gemini pour la validation croisée.
tool_journal cumulative_hash (PK), io_json, updated_at Replay-log des outils. Stocke les appels (arguments) et les retours (multiparts) complets.

2. Référence API des Classes Fondamentales

EchoGeminiClient (Backbone de Communication)

async call(keys: List[str], target_model: str, payload: dict) -> dict

Exécute un appel atomique. Implémente la rotation automatique des clés API sur erreur 429/500/503.

- threshold: Nombre d'échecs avant rotation (Défaut: 2).
- max_retries: Tentatives avec exponential backoff (Défaut: 3).
async stream(keys, target_model, payload, process_callback) -> AsyncGenerator

Moteur SSE (Server-Sent Events) optimisé pour HTTP/2. Gère le partitionnement des tokens et la capture des signatures de pensée.

EchoStateManager (Gestionnaire de Vérité)

calculate_invariant_hash(role: str, content: Any, tool_io: dict) -> str

Génère l'empreinte unique d'un tour de parole. Normalise le contenu (tri des clés JSON) pour garantir la stabilité du hash.

save_message_shadow(message_id, chat_id, role, parts)

Scelle physiquement les "parts" Gemini (Text + InlineData + FunctionCall) dans SQLite.

3. L'Arsenal : Outils & Moteurs Spécialisés

Navigation Engine (v6.70)

Architecture Client/Serveur entre le plugin OWUI et le container browser-agent.

web_browse_navigate(url: str)

Lance une instance Chromium Headless, capture le DOM interactif et déploie le HUD de monitoring.

get_browser_frames_history(depth: int)

Récupère la mémoire visuelle de la session (captures PNG indexées). Chaque frame est scellée dans le Vault ECHO avec son propre ID.

Vault Explorer & Smart Context

semantic_probe(file_id: str, query: str)

Utilise Gemini Flash comme unité de prétraitement. Permet de "questionner" un fichier de 50 Mo sans l'injecter intégralement dans le contexte principal.

read_raw_file_content(file_id, start_line, end_line, mode="text")

Lecture sécurisée (Tell-Safe) par pagination. Limite matérielle de 16 Ko par lecture pour protection du contexte.

4. Lifecycle & Maintenance (Admin Manager)

Le service Admin Manager (Flask/Docker SDK) assure la pérennité de l'écosystème.

Élagage Sémantique (Auto-Pruning)

Algorithme récurrent (par défaut à 03:00) :

  • Orphelins : Suppression des dossiers Vault dont l'ID utilisateur n'existe plus dans webui.db.
  • Atrophie : Suppression des fichiers /uploads datant de plus de 3 ans (configurables).
  • Compression : Exécution de VACUUM sur toutes les bases SQLite pour récupérer l'espace inutilisé.

Scripts d'Infrastructure

install-stack.sh

Provisionnement auto : volumes, réseaux, détection CORS IPs, et launch orchestré.

config-owui.sh

Injection programmatique (API REST) des modèles ECHO et durcissement des réglages OWUI.

sync-echo.sh

Moteur de synchronisation bidirectionnelle Host <-> Docker via rsync.

enable-bunkerweb.sh

Déploiement du WAF (ModSecurity) et certificat TLS automatique.

disable-bunkerweb.sh

Désactivation du WAF et retour à l'accès direct standard (sans TLS).

5. Dictionnaire des Valves Critiques (Tuning)

Variable (Valve)ValeurImpact sur le Système
MAX_DIRECT_TEXT_SIZE 256 Ko Taille limite d'injection brute. Au-delà, passage automatique en Smart Context.
KEY_SWITCH_THRESHOLD 2 Nombre d'échecs API (429/503) avant basculement sur la clé de secours (Haute Disponibilité).
MAX_CASCADE_ATTEMPTS 5 Nombre max de transferts cognitifs (Ex: LITE -> FLASH -> PRO) autorisés par tour.
SMART_CONTEXT_TIMEOUT 120s Temps limite pour la génération d'un moulage sémantique par Gemini Flash.
IDLE_TIMEOUT 900s Temps d'inactivité avant arrêt automatique du moteur de navigation (Browser Agent).
HTTP_MAX_CONNECTIONS 100 Pool de sockets HTTP/2 persistants mutualisés (httpx).

6. Protocoles de Sécurité & Chiffrement