# NOEON — protocole de communication entre modèles Ce document décrit la couche de coopération de NOEON. Ce **n'est pas un routeur** : un routeur choisit un modèle et s'arrête. Le coordinateur de NOEON exécute un *plan* où plusieurs capacités coopèrent sur une même tâche, avec partage de contexte, demandes d'aide, vérification et gestion des conflits. ## 1. Enveloppe standard (`noeon/comm/protocol.py`) Chaque échange circule comme un `Message` : | Champ | Rôle | |---|---| | `kind` | `task`, `help`, `result`, `error`, `ping`, `cancel`, `ack` | | `sender` / `recipient` | capacités (noms stables : `vision`, `computer_use`, `generation`, `tools`) | | `payload` | contenu structuré | | `id` | identifiant unique | | `correlation_id` | relie une réponse à sa demande | | `created` / `deadline` | horodatage et échéance absolue (secondes epoch) | | `hops` | nombre de sauts (anti-boucle) | | `error` | erreur structurée (`CommError`) | Payloads typés : `Task` (objectif + payload + compétences requises + priorité), `HelpRequest` (besoin + contexte), `Result` (statut, sortie, confiance, contexte), `CommError` (code, message, lieu, retryable). Les statuts terminaux sont explicites : `ok`, `failed`, `timeout`, `rejected`, `deferred`. Une erreur est **une valeur**, jamais une exception qui disparaît. ## 2. Bus (`noeon/comm/bus.py`) Le bus transporte les messages et garantit : - **Enregistrement** — une capacité est adressée par nom ; un nom inconnu produit une erreur structurée (`unknown-recipient`), jamais un crash. - **Délais** — un message déjà expiré échoue immédiatement (`deadline-exceeded`) ; un gestionnaire plus lent que l'échéance renvoie un statut `timeout` explicite. - **Reprises** — une erreur *retryable* est retentée jusqu'à `max_retries` avec le même `correlation_id`, donc un doublon est détectable en aval. - **Confinement** — un gestionnaire qui lève une exception est converti en message `error` ; l'appelant reçoit toujours un `Message`. - **Journal** — chaque message est ajouté à `bus.log` pour audit. ## 3. Vérification (`noeon/comm/verify.py`) Un résultat n'est accepté qu'après vérification : - `SchemaVerifier` — la sortie a la forme attendue ; - `ConfidenceVerifier` — la confiance dépasse un seuil ; - `CrossCheckVerifier` — une seconde capacité reproduit la réponse ; - `VerifierChain` — enchaîne et s'arrête à la première défaillance. Un échec de vérification est un `Verdict(ok=False)`, pas une exception : le coordinateur peut retenter, escalader ou échouer explicitement. ## 4. Coordination (`noeon/comm/coordinator.py`) Le coordinateur exécute un plan de `Step`. Pour chaque étape : 1. **Décomposition** — chaque étape nomme la capacité qui doit l'exécuter et les compétences requises. 2. **Partage de contexte** — chaque étape reçoit le contexte partagé accumulé, donc les capacités en aval s'appuient sur les résultats amont. 3. **Demandes d'aide** — si une capacité signale `needs_help` avec un besoin, le coordinateur interroge une capacité pair qui annonce la compétence (`bus.find_by_skill`) et replie sa réponse dans le contexte partagé. 4. **Vérification** — chaque résultat passe la `VerifierChain` ; un échec déclenche une reprise, puis une escalade vers une capacité alternative, puis un échec explicite. 5. **Anti-conflit** — une étape *réserve* la capacité qu'elle utilise ; deux étapes qui ont besoin de la même capacité s'exécutent séquentiellement, donc une capacité n'est jamais pilotée par deux étapes à la fois. Chaque étape, message et verdict est consigné dans `Coordinator.transcript` : une exécution est entièrement auditable. ## 5. Capacités (`noeon/comm/capabilities.py`, `tools.py`) `CapabilityAdapter` transforme un flux NOEON en participant communicant. Il détient une **vraie fonction** — par défaut l'encodeur d'états cachés d'une source gelée, mais n'importe quel callable convient. Les compétences sont **déclarées**, pas devinées : | Capacité | Compétences annoncées | |---|---| | `vision` | `image_understand`, `caption`, `visual_question_answer`, `ocr` | | `computer_use` | `gui_understand`, `screen_ground`, `action_plan`, `click_target` | | `generation` | `image_generate`, `image_edit`, `inpaint` | | `tools` | `calc`, `tool_use` | Les **outils externes** et le **raisonnement de tâche** sont exposés sur le même bus que les flux neuronaux, donc le coordinateur les traite uniformément. Le planificateur (`RulePlanner`) est un moteur de règles déterministe et auditable : même objectif → même plan. Ce **n'est pas** un planificateur appris (futur `NOEON-Reasoning`), et il est étiqueté comme tel. ## 6. Ce que la coopération est et n'est pas - **Est** : une architecture réelle où des capacités partagent un contexte, se délèguent des tâches, se demandent de l'aide, vérifient leurs résultats et évitent les conflits. - **N'est pas** : un simple aiguillage. Le coordinateur exécute des plans multi-étapes où les résultats d'une capacité conditionnent les suivantes. - **Limite honnête** : la *qualité* de la coopération dépend de l'entraînement des ponts et des sources ; la mécanique est réelle et testée, les capacités ne sont pas présentées comme entraînées. ## 7. Fichiers | Fichier | Rôle | |---|---| | `noeon/comm/protocol.py` | enveloppe + payloads | | `noeon/comm/bus.py` | transport, délais, reprises, confinement | | `noeon/comm/verify.py` | vérification des résultats | | `noeon/comm/coordinator.py` | exécution de plan, aide, anti-conflit | | `noeon/comm/capabilities.py` | adaptateurs de capacités | | `noeon/comm/tools.py` | outils externes + planificateur déterministe | | `tests/test_comm.py` | 22 tests | | `tests/test_integration.py` | 5 tests (bout en bout) |