1. High-Level Design (HLD)

Cette section décrit l'architecture technique d'ECHO v5 de manière exhaustive. Elle s'articule autour de quatre schémas complémentaires : la Grande Boucle (vue de survol), l'Écorché Structurel (modules Python), le Pipeline de Suture (séquence temporelle) et la Topologie Réseau (infrastructure Docker).

La Grande Boucle

Chaque requête de l'utilisateur traverse quatre zones de souveraineté avant de produire une réponse. Ces zones sont physiquement isolées : l'Interception (Filtre) prépare le contexte, la Reconstruction (Pipe) restaure l'historique bit-perfect, l'Action (Arsenal) exécute les outils, et le Scellement (SQLite) archive le tour pour les sessions futures.

Plan de Masse Holistique : Architecture ECHO v5 [FLUX DE SOUVERAINETÉ]

flowchart TD subgraph UI ["👤 ZONE 0 : INTERACTION"] U([Utilisateur]) <--> OWUI[🖥️ Open WebUI] end subgraph INLET ["🌙 ZONE 1 : INTERCEPTION"] F{{"🌒 FILTRE ECHO
(Inlet Hook)"}} F --> SC[Smart Context / Moulage] end subgraph CORE ["🧠 ZONE 2 : CŒUR & SUTURE"] P("⚙️ PIPE ENGINE
(Cortex)") S[["⚓ SUTURE SÉMANTIQUE
(Reconstruction Bit-Perfect)"]] DB[("🗄️ OMBRE RICHE
(SQLite Shadows)")] P <--> S S <--> DB end subgraph ACTION ["🛠️ ZONE 3 : ARSENAL & VAULT"] direction LR Tools["🛠️ Outils Sensoriels & Exécutifs"] V[("📂 Vault Local")] Tools <--> V end subgraph CLOUD ["☁️ ZONE 4 : INFÉRENCE"] G(("🌩️ API GEMINI
(PRO / FLASH / LITE)")) end U -->|1. Requête| OWUI OWUI -->|2. Inlet| F F -->|3. Draft YAML| P P -->|4. Suture| S P <-->|5. Tool Call| Tools P <-->|6. Inférence HTTP/2| G P -->|7. Scellement| DB P -->|8. Réponse SSE| OWUI OWUI -->|9. Rendu HUD| U classDef ui fill:#1e293b,stroke:#475569,color:#fff classDef inlet fill:#334155,stroke:#64748b,color:#fff classDef core fill:#1e1b4b,stroke:#4338ca,stroke-width:2px,color:#fff classDef action fill:#064e3b,stroke:#10b981,color:#fff classDef cloud fill:#4c1d95,stroke:#8b5cf6,color:#fff class UI ui; class INLET inlet; class CORE core; class ACTION action; class CLOUD cloud;

Écorché Structurel — Modules Python

Ce schéma vectoriel représente l'imbrication réelle des modules Python d'ECHO et leurs dépendances. Les connexions reproduisent fidèlement les imports déclarés dans le code source (pipe_engine.py v192.1, echo_utils.py v7.14). Cliquer sur le diagramme pour le zoomer.

Pipe Engine (Orchestrateur) ECHO Libs (14-owui-libs) Interface HUD (echo_ui / echo_visuals) Admin Manager Couche de persistance (Volumes)

Référentiel Conceptuel

Les termes suivants sont employés avec une signification technique précise dans l'ensemble de la documentation. Chaque concept est défini par sa nature, sa localisation dans le code source et son rôle dans le flux de données.

🌒 Le Filtre (Inlet)

Nature : Middleware d'interception Open WebUI, type Filter.

Source : 11-owui-filters/new_context_filter.py (v7.8)

Intercepte chaque requête avant le Pipe. Effectue le Smart Context (préanalyse des fichiers par Gemini 2.5 Flash), construit le Draft YAML et l'injecte dans les métadonnées via _echo_user_parts_draft.

⚙️ Le Pipe (Cortex)

Nature : Moteur d'orchestration Open WebUI, type Pipe.

Source : 10-owui-pipes/pipe_engine.py (v192.1)

Se présente comme un modèle GenAI auprès d'Open WebUI. Opère la Suture Bit-Perfect, gère la boucle d'outils de l'Arsenal, pilote l'API Gemini en HTTP/2 SSE et scelle chaque tour dans les Ombres Riches.

🗄️ L'Ombre Riche (Rich Shadow)

Nature : Registre SQLite immuable par chat.

Source : /app/backend/data/users/{uid}/chats/{cid}.db, table message_shadows

Miroir haute-fidélité de chaque tour de parole : structure JSON brute telle qu'envoyée à l'API, appels d'outils, médias Base64 et pensées internes (CoT). Permet la Suture bit-perfect lors du tour suivant.

⚓ La Suture (Cognitive Suture)

Nature : Algorithme de reconstruction (prepare_context()).

Source : Orchestrator.prepare_context() dans pipe_engine.py

Reconstruit l'historique complet à partir des Ombres SQLite. Le Verrou de Version (message_id + updated_at) garantit que seule l'Ombre correspondant exactement au message actuel est utilisée. En cas d'absence, le Pipe bascule en Cold Recovery.

📡 L'AEC

Nature : Bloc YAML proprioceptif injecté par le Filtre.

Contient <environnement_contexte> (identité, date, Registre Fichiers) et <smart_context> (RAG éphémère : résumé ≤ 300 mots + source_id Qdrant).

🧱 Le Moulage (Semantic Molding)

Nature : Pipeline de distillation asynchrone de fichiers volumineux.

Déclenché par le Filtre pour tout fichier dépassant MAX_DIRECT_TEXT_SIZE (256 Ko). L'API de distillation (call_distillation) produit un distillat structuré, vectorisé dans echo_ephemeral (Qdrant, bge-m3). Le modèle principal reçoit un résumé (≤ 300 mots) et le source_id pour interroger les détails.

📝 Le Draft (Brouillon Sémantique)

Nature : État mémoire volatile produit par le Filtre.

Conteneur JSON stocké dans metadata._echo_user_parts_draft : liste de parts Gemini-natifs (textes, inlineData, slugs éphémères, bloc AEC). Le Pipe le fusionne avec le texte brut de l'utilisateur lors de la Suture.

⛳ L'Ancre (Thought Signature)

Nature : Jeton opaque impératif de l'API Gemini 3+.

À la fin de chaque génération, l'API Gemini retourne systématiquement une thoughtSignature — un blob opaque dont la structure est interne à Google. En la réinjectant dans le tour suivant (p["thoughtSignature"] = sig), ECHO permet au modèle de retrouver son état de réflexion sans avoir à relire ses pensées en texte brut. Réduction de la charge contextuelle de 30 à 70 %.

⚠ À ne pas confondre avec le KV Cache, qui est une technique Google d'économie de tokens : les activations clé/valeur du prefill sont mises en cache implicite côté serveur pour éviter de les recalculer. Ces deux mécanismes sont entièrement distincts.

Architecture Mémorielle Duale

ECHO opère deux collections Qdrant physiquement isolées, vectorisées par le modèle local BAAI/bge-m3 (1024 dimensions, multilingue, 8192 tokens) via l'Embedding Worker (http://echo-embedding:7997). Aucune donnée ne quitte l'infrastructure.

🧠 RAG Organique (`echo_memory`)

Outils : save_memory, search_memory, list_memory_topics, forget_memory

Scope : user_id — permanent, survit aux sessions.

Usage : Préférences, contraintes techniques, décisions structurelles, règles personnelles.

Reranking : score_pondéré = cos_score × MEMORY_IMPORTANCE_WEIGHTS[lvl]. Un Axiome (niveau 5, poids 1,70) à similarité cosinus 0,60 surclasse un Trivial (niveau 1, poids 0,55) à similarité 0,85.

Purge TTL : De 30 jours (Trivial) à 540 jours (Axiome), orchestrée par l'Admin Manager.

⏱️ RAG Éphémère (`echo_ephemeral`)

Outils : save_session_context, search_session_context

Scope : user_id + chat_id + source_id — session courante uniquement.

Usage : Distillats de fichiers volumineux, résultats de navigation web, données intermédiaires d'analyse.

Purge : Automatique en fin de session par l'Admin Manager (suppression filtrée par chat_id).

La Vallée de la Mort et la compensation RAG

Lorsque le contexte dépasse ~30 % de la fenêtre maximale, les informations des premiers tours deviennent effectivement inaccessibles au mécanisme d'attention. Les deux RAG constituent la réponse architecturale : save_session_context indexe proactivement avant saturation, search_session_context permet une lecture sémantique précise indépendante de la position dans l'historique. search_memory couvre les sessions antérieures, totalement absentes du contexte actif.

Pipeline de Suture — Séquence temporelle

Ce diagramme de séquence retrace le cycle complet d'un tour de parole, des quatre phases distinctes : Préparation (Draft), Suture (Restauration), Inférence (Boucle outils) et Scellement.

Diagramme de Séquence : Pipeline de Bout en Bout [INLET ➔ SUTURE ➔ OUTLET]

sequenceDiagram autonumber box rgb(15, 23, 42) Utilisateur participant U as 👤 Utilisateur end box rgb(2, 6, 23) Middleware participant OWUI as 🖥️ Open WebUI end box rgb(30, 41, 59) ECHO Kernel participant F as 🌒 Filtre (Inlet) participant P as ⚙️ Pipe (Outlet) participant DB as 🗄️ SQLite (Shadows) end box rgb(6, 78, 59) Sandbox participant T as 🛠️ Arsenal end box rgb(76, 29, 149) Cloud participant G as ☁️ Gemini API end U->>OWUI: Prompt + Fichiers (HTTPS) OWUI->>F: Interception hook.inlet() note over F,DB: PHASE 1 : PRÉPARATION & DRAFT F->>F: Sniffing MIME & Analyse Multimodale F->>DB: get_session_registry(chat_id) F->>F: Moulage fichiers > 256 Ko → echo_ephemeral F-->>OWUI: Injection AEC + Draft YAML (metadata) OWUI->>P: Routage /api/chat/completions note over P,DB: PHASE 2 : SUTURE (BIT-PERFECT) P->>DB: get_message_shadow(msg_id, updated_at) DB-->>P: Parts JSON originales + Verrou de Version P->>DB: get_thought_signature(message_id) DB-->>P: thoughtSignature (Ancre Gemini 3+ — jeton opaque interne) P->>P: Fusion Draft + Historique → contexte Gemini note over P,G: PHASE 3 : INFÉRENCE & BOUCLE OUTILS P->>G: streamGenerateContent (HTTP/2 SSE) loop Appels d'outils G-->>P: functionCall (Tool Call Request) P->>T: Exécution isolée (API REST interne) T-->>P: Résultat multipart (texte + médias + nouveaux fichiers) P->>G: functionResponse (Tool Call Response) end G-->>P: Génération finale (stream Markdown + thoughtSignature) note over P,DB: PHASE 4 : SCELLEMENT P->>DB: save_message_shadow(final_parts + updated_at) P->>DB: save_signature_by_id(message_id, thoughtSignature) P->>DB: save_cognitive_data(cumulative_hash, tool_io) P->>DB: index_suture(cumulative_hash, parent_hash) P-->>OWUI: Forward SSE Stream OWUI-->>U: Rendu HUD & Markdown

Topologie Réseau (Cluster Docker)

💡 Lecture d'architecte

Ce schéma représente la topologie réelle du cluster Docker ECHO. Le trafic WAN est filtré par BunkerWeb (WAF). L'Arsenal (Browser Agent, Python Worker, SearxNG) s'exécute sur un sous-réseau Docker privé sans accès entrant. Les volumes SQLite garantissent la persistance des données hors-conteneur. L'Admin Manager accède au Docker Daemon via /var/run/docker.sock (socket Unix monté en volume).

Network & System Topology [MODE : DOCKER CLUSTER]

flowchart TB subgraph WAN ["🌐 ZONE 0 : PUBLIC WAN (Non fiable)"] U([👤 Utilisateur Client]) end subgraph DMZ ["🛡️ ZONE 1 : DMZ (Réseau Edge)"] BW{{"🛡️ BunkerWeb WAF
[:80/443]"}} end subgraph APP ["🖥️ ZONE 2 : APPLICATION & KERNEL TIER"] direction TB OWUI["🖥️ Open WebUI
[:3000]"] subgraph Kernel ["🧠 ECHO Kernel (In-Process)"] direction LR F("🌒 Filtre") P("⚙️ Pipe") end OWUI --- Kernel end subgraph DATA ["🗄️ ZONE 3 : COUCHE DE PERSISTANCE (Volumes)"] direction LR SQL[("🗄️ SQLite Shadows
(Volume Local)")] QD[("🧠 Qdrant Engine
[:6333]")] FS[("📂 Vault
(Système de fichiers)")] EMB[("🔢 Embedding Worker
[:7997]")] end subgraph SANDBOX ["🛠️ ZONE 4 : ARSENAL ISOLÉ (Sans accès entrant)"] direction LR BA["🌐 Browser Agent
[:3001]"] PW["🚀 Python Worker
[:3002]"] SNG["🔍 SearxNG Proxy
[:8080]"] AUD["🎙️ Audio Workers
[:7995, :7996]"] end subgraph MGMT ["⚙️ ZONE 5 : PLAN DE CONTRÔLE"] AM["📊 Admin Manager
(server.py)"] DOCKER("🐋 Docker Daemon
(/var/run/docker.sock)") end subgraph CLOUD ["☁️ ZONE 6 : SORTIE CLOUD"] GEMINI(("🌩️ Google Gemini API
[TCP 443]")) WWW(("🕸️ World Wide Web
[TCP 443]")) end U == "HTTPS" ==> BW BW == "Reverse Proxy" ==> OWUI BW -. "Accès Admin" .-> AM P == "SQL R/W" ==> SQL P == "HTTP Interne" ==> BA & PW & SNG P == "HTTP/2 SSE" ==> GEMINI F -. "Hash Uploads" .-> SQL BA & SNG == "HTTPS Sortant" ==> WWW AM == "Orchestration" ==> DOCKER AM -. "Health/Prune" .-> Kernel & SQL & QD QD <--> EMB classDef node fill:#1e293b,stroke:#475569,stroke-width:2px,color:#f8fafc classDef db fill:#0f172a,stroke:#f59e0b,stroke-width:2px,color:#f8fafc classDef core fill:#172554,stroke:#60a5fa,stroke-width:2px,color:#f8fafc classDef tool fill:#064e3b,stroke:#34d399,stroke-width:2px,color:#f8fafc class U,BW,OWUI,AM,DOCKER node class SQL,QD,FS,EMB db class F,P core class BA,PW,SNG,AUD tool

Schéma SQL — Ombres Riches

La persistance repose sur la classe EchoStateManager (echo_utils.py v7.14). Chaque chat dispose d'une base SQLite dédiée, en mode WAL (Write-Ahead Logging) pour la résistance aux pannes.

Entity-Relationship Diagram (ERD) [SCHÉMA SQL — RICH SHADOWS]

erDiagram MESSAGE_SHADOWS { string message_id PK "UUID du Middleware" integer updated_at "Verrou de Version (timestamp physique)" string parent_id FK "Message précédent" string cumulative_hash FK "ADN de la conversation" json parts "Parts Gemini originales (JSON brut)" } SUTURE_INDEX { string cumulative_hash PK "Hash SHA-256 cumulatif" string message_id FK string invariant_hash "Hash du contenu seul" string parent_hash "Hash parent" integer created_at } COGNITIVE_SIGNATURES { string message_id PK "UUID du message" string thought_signature "Ancre Gemini 3+ — jeton opaque interne" integer updated_at } TOOL_JOURNAL { string cumulative_hash PK json io_json "Appels et sorties outils (multipart)" integer updated_at } RICH_PAYLOADS { string invariant_hash PK "SHA-256 du contenu" string content_type "MIME Type" blob binary_data "Données Base64 (images, PDFs)" string summary "Résumé Smart Context" string message_id FK } PROCESSED_FILES { string file_id PK string user_id string mime_type string vault_path "Chemin dans l'Espace Personnel" string status "inline | rag_ephemeral | vault" } MESSAGE_SHADOWS ||--o| SUTURE_INDEX : "indexé par" SUTURE_INDEX ||--o| COGNITIVE_SIGNATURES : "lie" SUTURE_INDEX ||--o{ TOOL_JOURNAL : "journalise" MESSAGE_SHADOWS }|--o{ RICH_PAYLOADS : "référence (Invariant Hash)" TOOL_JOURNAL }|--o{ PROCESSED_FILES : "génère / consulte"

⚙️ Algorithmes de hachage (Cœur Merkle)

1. Invariant Hash : SHA-256(role + content_sorted + tool_io). Identité pure du tour, indépendante de sa position dans l'historique.

2. Cumulative Hash : SHA-256(invariant_hash + parent_cumulative_hash). ADN de la conversation — forme une chaîne de blocs similaire à Merkle. Tout changement dans l'historique invalide les hashes des tours suivants.

✅ Exactitude — Cold Recovery

Le Verrou de Version compare le triplet (message_id, updated_at, parent_hash) lors de la Suture. Si un message est détecté comme modifié manuellement dans Open WebUI (Ghost Message), l'Ombre SQLite est invalidée et le Pipe bascule en Cold Recovery : il utilise le texte brut fourni par le middleware, perdant temporairement les pièces jointes binaires et les appels d'outils du tour concerné, mais préservant la continuité de la conversation.

Cette architecture requiert une infrastructure précise pour s'exécuter de manière fiable. Passer à la stratégie de déploiement ➔