From c3c073fe5a1701b1d88e02c7328171c4c2d441e4 Mon Sep 17 00:00:00 2001 From: sylvain Date: Sun, 15 Mar 2026 19:54:20 +0000 Subject: [PATCH] docs: update README with OMEMO, LLM coordinator, script skill Co-Authored-By: Claude Sonnet 4.6 --- README.md | 60 +++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 47 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index b3c0d4d..64d9a0a 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # agents_core -Bibliothèque partagée pour le système multi-agents. Fournit toutes les briques communes : communication MQTT/XMPP, LLM, gestion des tâches, chargement des skills, et découverte des capacités entre agents. +Bibliothèque partagée pour le système multi-agents. Fournit toutes les briques communes : communication MQTT/XMPP (avec chiffrement OMEMO), LLM, coordination des appels Ollama, gestion des tâches, chargement des skills, et découverte des capacités entre agents. ## Installation @@ -11,12 +11,15 @@ pip install -e /opt/agents_core ## Architecture ``` -XMPP (slixmpp) MQTT (Mosquitto local) +XMPP (slixmpp + OMEMO) MQTT (Mosquitto local) utilisateur ←→ nexus ←→ agents/nexus/inbox - ←→ agents/+/status (retained) - ←→ agents/+/capabilities (retained) - ←→ agents/broadcast - ←→ agents/llm/switch (retained) + ←→ agents/+/status (retained) + ←→ agents/+/capabilities (retained) + ←→ agents/broadcast + ←→ agents/llm/switch (retained) + ←→ agents/llm/request (coordinateur) + ←→ agents/llm/release (coordinateur) + ←→ agents/scripts/execution ``` ## Modules @@ -24,9 +27,11 @@ utilisateur ←→ nexus ←→ agents/nexus/inbox | Fichier | Rôle | |---------|------| | `base_agent.py` | Classe abstraite `BaseAgent` — à hériter dans chaque agent | -| `mqtt_client.py` | Client MQTT (paho), reconnexion auto, publish/subscribe/reply | -| `xmpp_client.py` | Client XMPP (slixmpp 1.13), reconnexion auto, MUC, thread-safe | +| `mqtt_client.py` | Client MQTT (paho), reconnexion auto, publish/subscribe/unsubscribe/reply | +| `xmpp_client.py` | Client XMPP (slixmpp 1.13), reconnexion auto, MUC, OMEMO E2E, thread-safe | +| `omemo_storage.py` | Backend SQLite pour les clés/sessions OMEMO (XEP-0384, BTBV) | | `llm_client.py` | Wrapper Ollama — chat, historique, extraction de skill calls | +| `llm_coordinator.py` | Coordinateur MQTT — limite les appels Ollama simultanés (sémaphore) | | `message_bus.py` | Enveloppe `Message` standard (type, payload, sender, reply_to…) | | `skill_loader.py` | Auto-découverte et exécution des plugins `.py` dans `skills/` | | `task_queue.py` | Queue SQLite FIFO avec worker thread | @@ -70,14 +75,16 @@ if __name__ == "__main__": }, "llm": { "base_url": "http://192.168.7.119:11434", - "model": "ministral-3:latest", + "model": "qwen3:8b", "temperature": 0.3 }, "llm_profiles": { - "local": "ministral-3:latest", + "local": "qwen3:8b", "cloud": "gpt-oss:120b-cloud" }, - "queue_db": "/opt/mon_agent/data/queue.db" + "queue_db": "/opt/mon_agent/data/queue.db", + "use_omemo": true, + "use_llm_coordinator": true } ``` @@ -92,7 +99,7 @@ NAME = "mon_skill" DESCRIPTION = "Fait quelque chose d'utile. Args: " def run(args: str, context) -> str: - # context.agent, context.mqtt, context.xmpp, context.llm + # context.agent, context.mqtt, context.xmpp, context.llm, context.config return f"Résultat pour : {args}" ``` @@ -109,6 +116,20 @@ Le LLM appelle le skill avec : `SKILL:mon_skill ARGS:paramètre` | `handle_custom_command(cmd, args, msg)` | Commande `/xxx` non gérée par BaseAgent | | `setup_extra_subscriptions()` | Pour ajouter des souscriptions MQTT custom | +## Commandes système intégrées (BaseAgent) + +Toutes les commandes suivantes sont disponibles sur chaque agent : + +``` +/status — État de la queue de tâches +/pause — Pause du traitement +/resume — Reprise +/report — Rapport de l'agent +/update — Git pull + redémarrage du service +/script — Gestion de la bibliothèque de scripts bash + list, show , save | , exec [args], run | , delete +``` + ## Topics MQTT | Topic | Usage | @@ -118,10 +139,23 @@ Le LLM appelle le skill avec : `SKILL:mon_skill ARGS:paramètre` | `agents/{id}/capabilities` | Skills déclarés (retained) | | `agents/broadcast` | Message à tous les agents | | `agents/llm/switch` | Changement de modèle LLM global (retained) | +| `agents/llm/request` | Demande de slot LLM (coordinateur) | +| `agents/llm/release` | Libération de slot LLM (coordinateur) | +| `agents/{id}/llm/grant/{uuid}` | Accord de slot LLM | +| `agents/scripts/execution` | Notification d'exécution de script | + +## Coordinateur LLM + +Pour éviter de surcharger Ollama, un sémaphore MQTT limite les appels concurrents : +- Nexus instancie `LLMCoordinator(max_concurrent=1)` +- Chaque agent publie sur `agents/llm/request` avant d'appeler le LLM +- Il attend le grant sur `agents/{id}/llm/grant/{uuid}` (timeout 90s) +- Il publie sur `agents/llm/release` après ## Dépendances - Python ≥ 3.10 - paho-mqtt ≥ 1.6 -- slixmpp ≥ 1.8 +- slixmpp ≥ 1.13 +- slixmpp-omemo ≥ 2.1.0 - requests ≥ 2.28