18. 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 (Domain-Driven IPAM) et Ports
ECHO orchestre un cluster de conteneurs sur deux réseaux Docker isolés (echo-network en 10.20.40.0/24 par défaut et echo-sandbox en 10.20.50.0/24 pour le Coding Worker), régis par stack-echo.yml et bunkerweb-stack.yml.
Les briques Core utilisent la plage .100–.103 et les Workers ECHO calquent leur dernier octet IP sur le numéro de leur dossier source (.20–.30).
| Service | Conteneur | IP (echo-network) |
Port interne | Port hôte / Exposition |
|---|---|---|---|---|
| Open WebUI (Cortex) | echo-open-webui | .100 | 8080 | 3000 (ou ui. via BunkerWeb) |
| SearXNG | echo-searxng | .101 | 8080 | Interne uniquement |
| Watchtower | echo-watchtower | .102 | - | Interne uniquement |
| Qdrant | echo-qdrant | .103 | 6333 | Interne uniquement |
| Admin Manager | echo-admin-manager | .20 | 3001 | 3001 (ou am. via BunkerWeb) |
| Coding Worker (Sandbox) | echo-coding-worker | .21 (echo-sandbox) | 5000 | Interne (réseau echo-sandbox) |
| Browser Worker | echo-browser-worker | .22 | 5002 | Interne uniquement |
| MCP Broker | echo-mcp-broker | .23 | 8000 | 8000 (Interne au WAF) |
| ECHO Auth Manager (IdP) | echo-auth-manager | .24 | 8000 | Sous-domaine auth. via BunkerWeb |
| Download Broker | echo-download-broker | .25 | Daemon | Interne uniquement |
| N8N Worker (Headless) | echo-n8n-worker | .26 | 5003 (API) / 5678 | Interne uniquement |
| Embedding Worker | echo-embedding | .30 | 7997 | WAF (/ws/edge-embed) |
| Pont Audio In-Process (STT/TTS) | In-process WebUI | .100 | 8080 (/echo/v1/audio) | Interne (127.0.0.1:8080) |
| SSH Tunnel Auth PKCE | In-process WebUI | .100 | 8020–8024 | 8020–8024 (callback interne 8025–8034) |
| BunkerWeb (WAF) | bunkerweb | bw-universe (.2) / echo-network (.200) | 8080 / 8443 | 80 / 443 (WAN) |
Volumes Docker
| Volume | Point de montage | Contenu |
|---|---|---|
echo-webui-data |
/app/backend/data |
webui.db, identity.db par utilisateur, bases SQLite de session (/users/{uid}/chats/{chat_id}/session.db), Codex Git (main/sandbox), Vault fichiers et cache .cache/pip. |
echo-qdrant-data |
/qdrant/storage |
Index vectoriels Qdrant (echo_meta_artifacts, echo_session_rag). |
echo-download-broker-data |
/app/downloads |
Drop-zone partagée entre Browser Worker, N8N Worker et Download Broker. |
echo-n8n-data |
/home/node/.n8n (et /app/n8n-data sur Admin Manager) |
Base SQLite native (database.sqlite) et workflows persistants du moteur N8N. |
echo-mcp-cache |
/app/mcp_cache |
Cache persistant des tokens OAuth2 MSAL Microsoft 365 (.microsoft_mcp_token_cache.json et empreinte MD5 .cred_hash) partagé entre echo-mcp-broker et echo-admin-manager. |
echo-auth-data |
/app/auth-data |
Base SQLite auth.db (comptes Argon2, secrets TOTP et sessions SSO). |
echo-embedding-cache |
/root/.cache/huggingface |
Poids GGUF F16 du modèle microsoft/Harrier-OSS-v1-0.6B. |
echo-backups |
/backups (sur echo-admin-manager) |
Archives de sauvegarde tar.xz (5 volumes) générées par l'Admin Manager. |
bw-data / bw-db-data |
/data (depuis /opt/ECHO/bunkerweb) et /var/lib/mysql (sur bw-db) |
Certificats Let's Encrypt, configurations WAF et base MariaDB 11.4. |
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_g1_credits | TEXT | Crédits Google One AI disponibles. |
google_quota_summary | TEXT (JSON) | Quotas glissants 5h et hebdomadaire sérialisés en JSON (depuis :retrieveUserQuotaSummary). |
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 - session.db
Base SQLite par session de chat, stockée dans
/app/backend/data/users/{uid}/chats/{chat_id}/session.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 (indexé également sur chat_id). |
chat_id | TEXT NOT NULL | Identifiant de la session de chat. |
role | TEXT NOT NULL | Rôle de l'émetteur (user ou model). |
full_parts_json | TEXT (JSON) | Structure Gemini complète des parts (texte, inlineData, functionCall, etc.). |
updated_at | INT | Verrou de Version - timestamp physique de la dernière modification du message. |
is_embedded | INT DEFAULT 0 | Flag booléen O(1) interrogé par conversation_rag_filter.py pour éviter toute réindexation redondante dans Qdrant. |
Table suture_index
| Colonne | Type | Description |
|---|---|---|
cumulative_hash | TEXT PK | SHA-256 cumulatif - ADN de la conversation. |
chat_id | TEXT NOT NULL | Identifiant de la session (index idx_chat_id). |
invariant_hash | TEXT NOT NULL | 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. |
message_id | TEXT | Référence vers message_shadows. |
timestamp | INT | Timestamp de scellement. |
Table cognitive_signatures
| Colonne | Type | Description |
|---|---|---|
cumulative_hash | TEXT PK | Lié au tour courant (chaîne Merkle). |
thought_signature | TEXT NOT NULL | ThoughtSignature Gemini 3+ - jeton opaque cryptographique rattaché au premier functionCall. |
message_id | TEXT | UUID du message (indexé par idx_sig_msg_id avec tri ORDER BY updated_at DESC LIMIT 1). |
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 echo_resources (Registre Unifié v8.0)
| Colonne | Type | Description |
|---|---|---|
id | TEXT PK | Identifiant unique de la ressource ou de l'événement (aec_directive, aec_event). |
name | TEXT NOT NULL | Nom du fichier, du plan, du workflow N8N ou de l'événement. |
resource_type | TEXT NOT NULL | Type (codex, plan, media, binary, weburl, n8n_workflow, aec_directive, aec_event). |
mime / status | TEXT | Type MIME et statut (put_in_context, vectorized_sum_up, indexed, pending_ingestion, etc.). |
summary / storage_path | TEXT | Résumé Smart Context ou message de directive AEC, et chemin physique dans le Vault/Codex. |
item_type | TEXT DEFAULT 'file' | Distinction file ou directory pour l'arborescence Codex Multi-Workspace. |
created_at / updated_at | INT NOT NULL | Horodatages de création et de mise à jour (indexés). |
Table echo_settings (Registre KV Unifié de Session)
| Colonne | Type | Description |
|---|---|---|
key | TEXT PK | Clé de réglage (last_model_id, turn_origin_model, last_framework_version, context_stats, compaction_state, aec_tier_*, model_policy). |
value | TEXT NOT NULL | Valeur sérialisée (remplace les anciennes tables session_state et context_stats). |
updated_at | INT NOT NULL | Timestamp de dernière mise à jour. |
Tables Complémentaires (call_bridge, rich_payloads, codex_docs, cognitive_threads)
call_bridge: Pont entre uncall_idd'outil (signature,function_name,args_json) et son résultat au sous-tour suivant.rich_payloads: Stocke les parts enrichies (rich_parts_json) indexées parinvariant_hash.codex_docs: Table de suivi documentaire complémentaire au registreecho_resources(les plans stratégiques et fichiers Codex étant gouvernés parecho_resourceset les dépôts Gitmain/sandbox).cognitive_threads: Stocke l'historique des délégations multi-agents (Conseil Delphi & Sous-Agents) par(sub_sid, step_index).
Collections Qdrant
| Collection | Constante | Dimensions | Distance | Scope | Durée de vie |
|---|---|---|---|---|---|
echo_meta_artifacts |
COLLECTION_META_ARTIFACTS |
1024 (Harrier-OSS) | Cosinus | user_id |
Permanent - Consolidation Lvl1→Lvl2 & TTL par niveau (Admin Manager) |
echo_session_rag |
COLLECTION_SESSION_RAG |
1024 (Harrier-OSS) | Cosinus | user_id + chat_id + slug |
Session - purgé automatiquement en fin de session |
Dictionnaire des Constantes & Valves Critiques (echo_constants.py)
Ces constantes et valves gouvernent les seuils d'ingestion, la résilience réseau et les rappels cognitifs au sein de la Stack ECHO.
| Constante / Valve | Défaut | Composant | Impact |
|---|---|---|---|
MAX_DIRECT_TEXT_INJECT_SIZE | 32 Ko | Ingestion | Plafond d'injection directe en contexte pour les fichiers texte (au-delà : Smart Context RAG). |
MAX_DIRECT_MMEDIA_INJECT_SIZE | 1 Mo | Ingestion | Plafond d'injection directe Base64 pour les fichiers multimédias et PDF. |
ECHO_MAX_TOOL_TEXT_OUTPUT_CHARS | 131 Ko | API / Sandbox | Plafond anti-OOM de sortie textuelle pour api_client et worker_api. |
ECHO_UCTP_CHUNK_SIZE | 256 Ko | UI Events | Taille de fragmentation des payloads JS transmis via le protocole UCTP. |
ECHO_API_KEY_RETRIES | 2 | Client Gemini | Nombre d'échecs avant basculement vers la source d'authentification suivante. |
ECHO_API_MAX_RETRIES | 5 | Client Gemini | Nombre maximum de tentatives par source. |
ECHO_RETRY_BASE_DELAY | 3,0 s | Client Gemini | Délai de base du backoff exponentiel (compatible avec GUNICORN_TIMEOUT=120s). |
ECHO_RETRY_MULTIPLIER | 1,5 | Client Gemini | Multiplicateur du backoff exponentiel. |
ECHO_RETRY_JITTER_MIN/MAX | 0,7 / 1,3 | Client Gemini | Plage de jitter aléatoire pour éviter les tempêtes de retry. |
AEC_REMINDERS | 22k / 34k / 55k / 88k / 120k | Echo Orchestrator | Paliers de tokens et outils déclenchant les rappels cognitifs multi-axes (efficiency, strategy, alignment, factuality, kernel, context_hygiene). |
ECHO_COMPACTION_ENABLED_DEFAULT | False | Compaction | État par défaut de la valve d'auto-compaction contextuelle (ENABLE_AUTO_COMPACTION). |
CONTEXT_COMPACTION_TRIGGER_RATIO | 0.45 | Compaction | Ratio de charge de ECHO_MAX_CONTEXT_SIZE (45 %) déclenchant le compactage contextuel in-place. |
CONTEXT_COMPACTION_TARGET_RATIO | 0.25 | Compaction | Ratio cible de fenêtre récente conservée (25 %) après élagage et synthèse du Checkpoint. |
ECHO_COMPACTION_MIN_TURNS_TO_KEEP | 2 | Compaction | Nombre minimal de tours complets récents préservés intacts lors du compactage. |
ECHO_COMPACTION_MODEL | MODEL_APOLLO | Compaction | Modèle cognitif sollicité par EchoCompactionEngine pour la consolidation téléscopique. |
ECHO_COMPACTION_MAX_OUTPUT_TOKENS | 32768 | Compaction | Budget maximal de tokens de sortie alloué à la génération du Checkpoint cognitif. |
PKCE_CALLBACK_TIMEOUT | 300 s | Auth PKCE | Délai maximal accordé à l'utilisateur pour valider l'autorisation OAuth2. |
GOOGLE_OAUTH_TOKEN_LIFETIME | 3 300 s | Auth PKCE | Durée proactive de rafraîchissement du token OAuth2 (55 min). |
ECHO_AUDIO_DEFAULT_TTS_VOICE | fr-FR-VivienneMultilingualNeural | Pont Audio | Voix neuronale multilingue par défaut de la synthèse vocale Edge TTS. |
ECHO_AUDIO_DEFAULT_TTS_SPEED / PITCH | 1.0 / -2Hz | Pont Audio | Vitesse d'élocution nominale et hauteur vocale feutrée par défaut. |
ECHO_AUDIO_DEFAULT_STT_MODEL | MODEL_ZEPHYR | Pont Audio | Modèle cible pour la transcription vocale multimodale in-process. |
ECHO_AUDIO_MAX_UPLOAD_SIZE | 14 Mo | Pont Audio | Taille binaire maximale acceptée par /echo/v1/audio/transcriptions. |
Référence API - Classes Fondamentales
EchoStateManager - Méthodes principales
| Méthode | Signature | Description |
|---|---|---|
get_message_shadow | (message_id, updated_at) → list | None | Lit l'Ombre du message. Retourne None si absente ou si le Verrou de Version diffère. |
save_message_shadow | (message_id, chat_id, role, parts, updated_at) | Scelle l'Ombre en base. Upsert idempotent. |
is_message_embedded | (message_id) → bool | Validation O(1) en amont vérifiant le flag is_embedded dans message_shadows. |
get_signature_by_id | (message_id) → str | None | Lit la dernière thoughtSignature via ORDER BY updated_at DESC LIMIT 1. |
index_suture | (cumul, chat_id, inv, parent, message_id) | Met à jour la chaîne Merkle dans suture_index. |
save_session_setting | (key, value, conn=None) | Écrit dans le registre KV unifié echo_settings (supporte l'injection de connexion anti-deadlock). |
get_auth_data / save_api_key | (key_name, ...) | Lecture et écriture clé-valeur dans auth_data (identity.db). |
EchoGeminiClient - Méthodes principales
| Méthode | Description |
|---|---|
call(model, payload, user_id, chat_id) | Appel non-streamant gérant automatiquement le choix du backend (AI Studio / Code Assist) et le Circuit Breaker OAuth2. |
call_distillation(prompt, __user__, __metadata__, is_json, max_tokens) | Exécute une tâche de distillation via MODEL_DISTILLATION (gemini-3.5-flash-lite sur les deux backends, avec filtrage strict des blocs de pensée native thought). |
generate_embedding(text, task_type, __user__, __metadata__) | Vectorise un texte en 1024 floats via l'Edge Bridge WebGPU ou le fallback local microsoft/Harrier-OSS-v1-0.6B. |
get_stealth_headers(url) | Construit les en-têtes HTTP/2 haute fidélité (ECHO_STEALTH_USER_AGENT Chrome 123, Sec-Fetch-*). |
Transport HTTP/2 et En-têtes Antigravity
EchoGeminiClient utilise httpx avec l'option http2=True
(dépendance h2 obligatoire). Pour les requêtes vers l'API Code Assist, les en-têtes
reproduisent l'identité de la plateforme Linux Docker émulée :
En-têtes - ECHO API Code Assist (Antigravity 2.24.0)
User-Agent: antigravity/hub/2.24.0 (os_type=linux; arch=amd64; cl=1000335682; auth_method=personal_consumer; proxy_client=antigravity/2.24.0)
x-goog-api-client: antigravity/2.24.0
Authorization: Bearer {oauth_token}
Content-Type: application/jsonRéseau et Furtivité
Les requêtes web orchestrées par le Cortex s'appuient sur des connexions HTTP/2 strictes couplées à l'injection d'en-têtes de navigation haute fidélité (get_stealth_headers), simulant un navigateur réel lors des investigations agentiques.