10. Annexes Techniques

Cette section constitue la référence de bas niveau du framework ECHO v5 : spécifications réseau, schémas SQL complets, inventaire des volumes Docker, collections Qdrant et dictionnaire des valves de configuration.

Topologie Réseau et Ports

ECHO orchestre un cluster de conteneurs sur un réseau Docker privé (echo-network). La passerelle BunkerWeb est l'unique point d'entrée exposé sur le WAN lorsqu'elle est activée. Les services de l'Arsenal (Browser Agent, Python Worker, SearxNG) ne sont jamais exposés directement.

Service	Conteneur	Port interne	Port hôte	Exposé WAN ?
Open WebUI	`echo-open-webui`	8080	3000	Via BunkerWeb
Admin Manager	`echo-admin-manager`	3001	3001	Via BunkerWeb
Qdrant	`echo-qdrant`	6333	Non	Non
Embedding Worker	`echo-embedding`	7997	Non	Non
STT Worker	`echo-stt-worker`	7995	Non	Non
TTS Worker	`echo-tts-worker`	7996	Non	Non
Browser Agent	`echo-browser-agent`	5002	Non	Non
Python Worker	`echo-python-worker`	5000	Non	Non
SearxNG	`echo-searxng`	8080	Non	Non
SSH Tunnel Auth	In-process WebUI	8020–8024	8020–8024	Non — localhost uniquement
Callback OAuth2	In-process WebUI	8025–8034	Non	Non — via tunnel SSH uniquement
BunkerWeb (WAF)	`echo-bunkerweb`	80 / 443	80 / 443	Oui

Volumes Docker

Volume	Point de montage	Contenu
`echo-webui-data`	`/app/backend/data`	`webui.db`, `identity.db` par utilisateur, bases SQLite de session (`{chat_id}.db`), Vault fichiers.
`echo-qdrant-data`	`/qdrant/storage`	Index vectoriels Qdrant (`echo_memory`, `echo_ephemeral`).
`echo-backups`	`/opt/ECHO/backups`	Archives `tar.gz` générées par l'Admin Manager.
`echo-worker-data`	`/data` (Python Worker)	Artefacts temporaires d'exécution Python.
`echo-browser-data`	`/data` (Browser Agent)	Captures d'écran, exports de sessions de navigation.
`echo-bunkerweb-data`	`/opt/ECHO/bunkerweb`	Configuration WAF persistante (certificats, règles).

Schéma SQL — `identity.db`

Base SQLite unique par utilisateur, stockée dans /app/backend/data/users/{uid}/identity.db. Gérée par EchoStateManager (instance identity_manager).

Table `auth_data`

Clé	Type	Description
`google_oauth2_access_token`	TEXT	Token Bearer OAuth2 courant. Durée de vie : 3 300 s (55 min).
`google_oauth2_refresh_token`	TEXT	Token de rafraîchissement à longue durée de vie.
`google_oauth2_last_refresh`	INT	Timestamp Unix du dernier rafraîchissement de token.
`google_user_email`	TEXT	Adresse e-mail du compte Google authentifié.
`google_user_tier`	TEXT	Niveau d'abonnement Google (ex. `FREE`, `STANDARD`).
`google_project_id`	TEXT	ID du projet API Antigravity actif.
`google_credits_total`	TEXT	Crédits AI disponibles (depuis `paidTier.availableCredits`).
`google_quota_by_model`	TEXT (JSON)	Dict `{ca_model_id: quotaInfo}`. Source du quota affiché dans le HUD.
`google_quota_fraction`	TEXT	Fraction quota restante du modèle principal (0,0–1,0).
`google_quota_reset`	TEXT	Heure de reset du quota (ISO 8601).
`google_quota_type`	TEXT	Type de quota (ex. `CODE_ASSIST`).
`google_quota_last_fetch`	INT	Timestamp Unix du dernier appel `fetch_available_models`. Cooldown 10 min.
`google_api_key`	TEXT	Clé API AI Studio primaire (fallback OAuth2).
`google_api_key_secondary`	TEXT	Clé API AI Studio de secours.

Schéma SQL — `{chat_id}.db`

Base SQLite par session de chat, stockée dans /app/backend/data/users/{uid}/chats/{chat_id}.db. Gérée par l'instance state_manager de EchoStateManager.

Table `message_shadows`

Colonne	Type	Description
`message_id`	TEXT PK	UUID du message fourni par Open WebUI.
`updated_at`	INT	Verrou de Version — timestamp physique de la dernière modification du message.
`parent_id`	TEXT	UUID du message parent (chaîne de conversation).
`cumulative_hash`	TEXT FK	Référence vers `suture_index`.
`parts`	TEXT (JSON)	Structure Gemini complète des `parts` (texte, inlineData, thoughtSignature, etc.)
`created_at`	INT	Timestamp de scellement.

Table `suture_index`

Colonne	Type	Description
`cumulative_hash`	TEXT PK	SHA-256 cumulatif — ADN de la conversation.
`message_id`	TEXT FK	Référence vers `message_shadows`.
`invariant_hash`	TEXT	SHA-256 du contenu seul, indépendant de la position dans l'historique.
`parent_hash`	TEXT	Hash cumulatif du tour précédent — forme la chaîne Merkle.
`created_at`	INT	Timestamp de scellement.

Table `cognitive_signatures`

Colonne	Type	Description
`cumulative_hash`	TEXT PK	Lié au tour courant (chaîne Merkle).
`thought_signature`	TEXT	ThoughtSignature Gemini — jeton opaque cryptographique réinjecté au tour suivant.
`message_id`	TEXT	UUID du message (colonne de migration, nullable).
`model_id`	TEXT	Identifiant du modèle ayant généré la pensée.
`updated_at`	INT	Timestamp de scellement.

Table `tool_journal`

Colonne	Type	Description
`cumulative_hash`	TEXT PK	Lié au tour courant.
`io_json`	TEXT (JSON)	Appels d'outils (arguments) et sorties (réponses multipart). Journalisation traçable.
`updated_at`	INT	Timestamp de scellement.

Table `thought_archive`

Colonne	Type	Description
`cumulative_hash`	TEXT PK	Lié au tour courant.
`raw_thought`	TEXT	Texte intégral de la pensée (thinking block) du modèle, archivé pour traçabilité.
`updated_at`	INT	Timestamp de scellement.

Table `processed_files`

Colonne	Type	Description
`chat_id`	TEXT PK	Session de rattachement.
`file_id`	TEXT PK	UUID du fichier (clé composite avec chat_id).
`filename`	TEXT	Nom original du fichier uploadé.
`mime`	TEXT	Type MIME détecté.
`mode`	TEXT	Mode de traitement (`direct`, `rag_ephemeral`, `rag_organic`).
`message_id`	TEXT	Message dans lequel le fichier a été soumis.
`timestamp`	INT	Timestamp de traitement.

Table `call_bridge`

Colonne	Type	Description
`call_id`	TEXT PK	UUID de l'appel de fonction.
`signature`	TEXT	Signature de la fonction (nom + hash des arguments).
`function_name`	TEXT	Nom de l'outil appelé.
`args_json`	TEXT (JSON)	Arguments sérialisés de l'appel.
`timestamp`	INT	Timestamp de l'appel.

Table `rich_payloads`

Colonne	Type	Description
`invariant_hash`	TEXT PK	Hash invariant du message porteur.
`rich_parts_json`	TEXT (JSON)	Parts Gemini enrichies (inlineData, fichiers binaires encodés).
`message_id`	TEXT	UUID du message.
`created_at`	INT	Timestamp de création.

Table `plans`

Table utilisée par le Planificateur Stratégique pour persister les plans d'action de chaque chat. Gérée par l'outil strategic_planner.py.

Table `context_stats`

Colonne	Type	Description
`id`	INT PK (=1)	Ligne unique — singleton.
`data`	TEXT (JSON)	Statistiques de contexte sérialisées (tokens, cache, etc.).
`updated_at`	INT	Timestamp de la dernière mise à jour.

Table `session_state`

Colonne	Type	Description
`id`	INT PK	Ligne unique — singleton.
`last_model_id`	TEXT	Dernier modèle utilisé dans cette session (pour reprise).
`updated_at`	INT	Timestamp.

Table `cognitive_threads`

Table de support pour les délégations cognitives récursives (Conseil d'Experts). Stocke les échanges par sous-session (sub_sid) et rôle (role_id).

Collections Qdrant

Collection	Constante	Dimensions	Distance	Scope	Durée de vie
`echo_memory`	`COLLECTION_MEMORY`	1024 (bge-m3)	Cosinus	`user_id`	Permanent — TTL par niveau (Admin Manager)
`echo_ephemeral`	`COLLECTION_EPHEMERAL`	1024 (bge-m3)	Cosinus	`user_id + chat_id + slug`	Session — purgé automatiquement en fin de session

Dictionnaire des Valves Critiques

Les valves sont des paramètres configurables exposés dans l'interface d'administration Open WebUI pour chaque composant (Pipe, Filtres, Outils). Elles permettent d'ajuster le comportement sans redéploiement.

Valve	Défaut	Composant	Impact
`MAX_DIRECT_TEXT_SIZE`	256 Ko	Filtre Inlet	Seuil de basculement en Moulage (Smart Context).
`ECHO_API_KEY_THRESHOLD`	2	Pipe	Nombre d'échecs avant failover vers la source d'auth suivante.
`ECHO_API_MAX_RETRIES`	5	Pipe	Nombre maximum de tentatives par source.
`ECHO_RETRY_BASE_DELAY`	2,0 s	Pipe	Délai de base du backoff exponentiel.
`ECHO_RETRY_MULTIPLIER`	2,0	Pipe	Multiplicateur du backoff.
`ECHO_RETRY_JITTER_MIN/MAX`	0,7 / 1,3	Pipe	Plage de jitter aléatoire pour éviter les tempêtes de retry.
`PKCE_CALLBACK_TIMEOUT`	300 s	Auth	Délai maximal pour l'utilisateur pour autoriser dans le navigateur.
`GOOGLE_OAUTH_TOKEN_LIFETIME`	3 300 s	Auth	Durée proactive de rafraîchissement du token (55 min).
`SCORE_THRESHOLD`	0,45	Mémoire	Score pondéré minimal pour inclure un résultat de `search_memory`.
`PROBE_TIMEOUT`	120 s	Vault Explorer	Timeout de l'analyse sémantique `semantic_probe` (appel LLM).

✅ Source de vérité — Valves

Les valeurs ci-dessus sont celles déclarées dans les constantes de echo_constants.py (v5.2) et dans les constructeurs Valves de chaque composant. En cas de divergence entre cette documentation et le code source, le code source fait foi.

Référence API — Classes Fondamentales

`EchoStateManager` — Méthodes principales

Méthode	Signature	Description
`get_message_shadow`	`(message_id, updated_at) → dict \| None`	Lit l'Ombre du message. Retourne `None` si absente ou Verrou invalide.
`save_message_shadow`	`(message_id, chat_id, role, parts, updated_at)`	Scelle l'Ombre en base. Upsert idempotent. 5 paramètres.
`get_signature_by_id`	`(message_id) → str \| None`	Lit l'Ancre ThoughtSignature depuis `cognitive_signatures` par `message_id`.
`save_signature_by_id`	`(message_id, signature)`	Scelle la ThoughtSignature.
`index_suture`	`(cumul, chat_id, inv, parent, message_id)`	Met à jour la chaîne Merkle dans `suture_index`. `chat_id` est le 2ème argument.
`save_cognitive_data`	`(cumul, sig, thought, tool_io, message_id, model_id)`	Journalise les données cognitives du tour (ThoughtSignature, pensées, appels d'outils, modèle).
`get_auth_data`	`(key_name, user_id) → str \| None`	Lecture clé-valeur depuis `auth_data` (identity.db).
`save_api_key`	`(key_name, value, user_id)`	Écriture clé-valeur dans `auth_data`. Upsert.

`EchoGeminiClient` — Méthodes principales

Méthode	Description
`call(model, payload, user_id, chat_id)`	Appel non-streamant (utilisé pour la distillation). Gère automatiquement le choix du backend (AI Studio / API Antigravity) et le failover.
`call_distillation(prompt, __user__, __metadata__, is_json, max_tokens)`	Exécute une tâche de distillation. Route par défaut vers `gemini-2.5-flash` (API). Gère le nettoyage des thoughts et le parsing JSON.
`generate_embedding(text, task_type, __user__, __metadata__)`	Vectorise un texte via le modèle local BAAI/bge-m3 (Embedding Worker). Retourne une liste de 1024 floats.
`get_stealth_headers(url)`	Construit les en-têtes HTTP/2 haute fidélité (User-Agent Chrome 123, Sec-Fetch-*) pour le téléchargement Stealth. Paramètre `url` optionnel.

10. Annexes Techniques

Topologie Réseau et Ports

Volumes Docker

Schéma SQL — identity.db

Table auth_data

Schéma SQL — {chat_id}.db

Table message_shadows

Table suture_index

Table cognitive_signatures

Table tool_journal

Table thought_archive

Table processed_files

Table call_bridge

Table rich_payloads

Table plans

Table context_stats

Table session_state

Table cognitive_threads