NOEON / docs /COMMUNICATION.md
openhands
openhands
NOEON: real context system, inter-model communication, integrated brain
3f71e8c
|
Raw History Blame Contribute Delete
5.92 kB

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)