Download docs/COMMUNICATION.md from Frankenstein-Labs/NOEON: direct link, hf CLI and curl.
- Browser
- Download file 5.92 kB
-
https://huggingface.co/Frankenstein-Labs/NOEON/resolve/main/docs/COMMUNICATION.md
- Command line
-
hf download hf://Frankenstein-Labs/NOEON/docs/COMMUNICATION.md
-
curl -L -o COMMUNICATION.md https://huggingface.co/Frankenstein-Labs/NOEON/resolve/main/docs/COMMUNICATION.md
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 statuttimeoutexplicite. - Reprises — une erreur retryable est retentée jusqu'à
max_retriesavec le mêmecorrelation_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 unMessage. - Journal — chaque message est ajouté à
bus.logpour 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 :
- Décomposition — chaque étape nomme la capacité qui doit l'exécuter et les compétences requises.
- Partage de contexte — chaque étape reçoit le contexte partagé accumulé, donc les capacités en aval s'appuient sur les résultats amont.
- Demandes d'aide — si une capacité signale
needs_helpavec 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é. - 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. - 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) |