nexus/README.md

# nexus

Orchestrateur principal du système multi-agents. Reçoit les instructions via XMPP, les traite avec un LLM (Ollama), délègue aux agents spécialisés via MQTT, et renvoie les résultats à l'utilisateur.

## Rôle

Nexus est le point d'entrée unique pour l'utilisateur. Il ne fait pas de travail technique lui-même — il comprend l'intention, choisit le bon agent, délègue la tâche, et agrège les résultats.

```
sylvain@xmpp.ovh
       ↕ XMPP (OMEMO chiffré)
  nexus@xmpp.ovh
       ↕ MQTT
  debian.local  /  ansible.main  /  deploy  /  ...
```

## Installation

```bash
cd /opt/nexus
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
systemctl enable --now nexus
```

## Skills disponibles

| Skill | Description |
|-------|-------------|
| `delegate` | Délègue une tâche à un agent via MQTT (vérifie les `work_hours` de l'agent cible) |
| `agents_status` | Liste les agents en ligne/hors ligne |
| `memory` | Mémoire clé/valeur SQLite persistante |
| `script` | Bibliothèque de scripts bash (save/list/show/edit/exec/run/delete) |
| `web_search` | Recherche DuckDuckGo |
| `web_read` | Lecture de page web (BeautifulSoup) |
| `mqtt_send` | Publie sur un topic MQTT arbitraire |
| `mqtt_subscribe` | S'abonne dynamiquement à un topic MQTT |
| `muc_send` | Poste dans le groupe XMPP agents@muc.xmpp.ovh |

## Commandes XMPP

### Navigation
```
/help                     — Liste toutes les commandes
/status                   — Statut de Nexus (queue, pause...)
/agents                   — Liste et statut des agents connus
```

### Gestion du LLM
```
/llm                      — Modèle actif + profils configurés
/llm local                — Switch tous les agents vers le profil local
/llm cloud                — Switch tous les agents vers le profil cloud
/llm list                 — Liste les modèles Ollama disponibles
/llm set local <model>    — Définir le profil local et l'activer
/llm set cloud <model>    — Définir le profil cloud et l'activer
/queue                    — État du coordinateur LLM + files d'attente
```

### Scripts
```
/script run <agent> <nom> [args]          — Exécuter un script immédiatement
/script schedule <fréq> <agent> <nom>     — Planifier un script
/script unschedule <job_id>               — Annuler une planification
/script schedules                         — Voir les scripts planifiés
/script list <agent>                      — Lister les scripts d'un agent

Fréquences : daily HH:MM | once HH:MM | every Xh | every Xmin | weekly <jour> HH:MM
```

### Planification de tâches
```
/schedule daily 03:00 @debian apt upgrade -y
/schedule every 6h @ansible playbook site.yml
/schedules                — Voir les tâches planifiées
/schedule cancel <id>     — Annuler une tâche planifiée
```

### Administration
```
/admins                   — Lister les JIDs autorisés
/admins add <jid>         — Autoriser un utilisateur (persistant)
/admins remove <jid>      — Retirer un utilisateur (persistant)
/update <agent>           — Demande git pull + restart à un agent
/update all               — Met à jour tous les agents
/report [agent]           — Rapport quotidien
/reset                    — Effacer l'historique LLM
/sleep / /wake            — Mettre Nexus en veille / réveiller
```

### APIs externes (one-shot)
```
/claude-apikey <clé>      — Enregistrer la clé API Anthropic
/claude-models            — Lister les modèles Claude disponibles
/claude-model <modèle>    — Définir le modèle par défaut (ex: claude-opus-4-6)
/claude <prompt>          — Appel one-shot à l'API Anthropic

/mammouth-apikey <clé>    — Enregistrer la clé API Mammouth
/mammouth-models          — Lister les modèles Mammouth disponibles
/mammouth-model <modèle>  — Définir le modèle par défaut (ex: gpt-4.1)
/mammouth <prompt>        — Appel one-shot à l'API Mammouth
```

Les clés et modèles sont persistés dans `config.json` sous `apis.claude` et `apis.mammouth`. Mammouth est compatible OpenAI API (`https://api.mammouth.ai/v1`).

### Routing direct
```
@debian.local apt update  — Commande directe sans passer par le LLM
@all status               — Broadcast à tous les agents
```

## Notifications automatiques

Nexus envoie une notification XMPP à chaque exécution de script sur n'importe quel agent (planifiée ou manuelle) :
```
📋 Script exécuté
  Agent   : debian.local
  Script  : backup
  Heure   : 2026-03-15 03:00:00
  Résultat: ...
```

## Configuration

`config/config.json` :
```json
{
  "agent_id": "nexus",
  "xmpp": {
    "jid": "nexus@xmpp.ovh",
    "password": "...",
    "admin_jid": "sylvain@xmpp.ovh",
    "muc_room": "agents@muc.xmpp.ovh"
  },
  "mqtt": { "host": "localhost", "port": 1883 },
  "llm": {
    "base_url": "http://192.168.7.119:11434",
    "model": "qwen3:8b",
    "temperature": 0.3
  },
  "llm_profiles": {
    "local": "qwen3:8b",
    "cloud": "gpt-oss:120b-cloud"
  },
  "llm_coordinator": { "max_concurrent": 1 },
  "use_omemo": true,
  "use_llm_coordinator": true,
  "system_prompt": "/opt/nexus/config/system_prompt.txt",
  "apis": {
    "claude":   { "key": "sk-ant-...", "model": "claude-opus-4-6" },
    "mammouth": { "key": "...",        "model": "gpt-4.1" }
  }
}
```

`config/system_prompt.txt` : prompt système dynamique — la liste des agents disponibles est injectée automatiquement au moment de chaque appel LLM via les capacités publiées sur MQTT.

## Fichiers

```
nexus.py              — Point d'entrée principal
scheduler.py          — Gestion des tâches et scripts planifiés (APScheduler)
daily_report.py       — Agrégation des rapports quotidiens
skills/               — Skills de Nexus
config/               — Configuration et system prompt
nexus.service         — Unit systemd
```

## Dépendances

- agents_core (partagé)
- apscheduler ≥ 3.10
- duckduckgo-search ≥ 6.0
- beautifulsoup4 ≥ 4.12
- requests ≥ 2.28