Funk-lab/admin/hermes.md

# Hermes Agent — Commandes d'administration

Hermes Agent tourne en deux services systemd sur **storage-01** :
- `hermes-agent` — gateway (messagerie, API)
- `hermes-dashboard` — interface web (port 9119)

Il passe par **LiteLLM** (`:4000`) pour toute inférence — Qwen local ou Claude API.
Les données persistantes sont sur le RAID5 : `/srv/data/hermes`.

---

## Architecture

```
funk-ai / brain / system / monitor (alias → profil)
        │
        ▼  LM_BASE_URL=http://127.0.0.1:4000/v1
   LiteLLM Proxy (:4000)
        ├── qwen3-8b            →  llama-server gpu-01 :1234  (GPU RX 6700XT)
        ├── qwen3-1.7b-system   →  llama-server gpu-01 :1236  (CPU 14 threads)
        ├── qwen3-1.7b-monitor  →  llama-server gpu-01 :1237  (CPU 14 threads)
        ├── claude-sonnet-4-6   →  api.anthropic.com
        └── claude-opus-4-7     →  api.anthropic.com
```

---

## Profils

Hermes supporte plusieurs profils isolés — chacun a son propre `config.yaml`, ses
mémoires, sessions et modèle. Tous stockés dans `$HERMES_HOME/profiles/<nom>/`.

### Tableau des profils

| Profil | Alias CLI | Modèle | Usage |
|---|---|---|---|
| `funk-ai` ◆ | `funk-ai` | qwen3-8b (GPU, ~35 tok/s) | Principal — par défaut |
| `brain` | `brain` | claude-sonnet-4-6 (API) | Analyse complexe, coûteux |
| `system` | `system` | qwen3-1.7b-system (CPU, ~21 tok/s) | Appels rapides |
| `monitor` | `monitor` | qwen3-1.7b-monitor (CPU, ~21 tok/s) | Appels rapides |

`◆` = profil actif par défaut

### Utilisation

```bash
# Lancer un profil (nouvelle session TUI)
funk-ai          # Qwen3-8B GPU
brain            # Claude Sonnet
system           # Qwen3-1.7B CPU
monitor          # Qwen3-1.7B CPU

# Oneshot
sudo -i -u hermes bash -c 'HERMES_HOME=/srv/data/hermes hermes --profile system -z "ta question"'

# Changer le profil par défaut
sudo -i -u hermes bash -c 'HERMES_HOME=/srv/data/hermes hermes profile use funk-ai'

# Lister les profils
sudo -i -u hermes bash -c 'HERMES_HOME=/srv/data/hermes hermes profile list'
```

> Il n'y a pas de changement de profil à chaud dans le TUI — ouvrir une nouvelle session.

### Points d'attention profils

| Sujet | Détail |
|---|---|
| `HERMES_HOME` | Toujours préfixer les commandes avec `HERMES_HOME=/srv/data/hermes` |
| `context_length` | Hermes exige 64k minimum — override via `model.context_length: 65536` dans config.yaml |
| GPU vs CPU | system/monitor : Qwen3-1.7B sur 14 CPUs (5950X) — pour appels courts et rapides |
| brain | Facturé à l'API Anthropic — réserver aux tâches complexes |

---

## Dashboard Web

Accessible depuis le poste admin uniquement (`192.168.1.10`) :

```
http://192.168.1.200:9119
```

Inclut : gestion des sessions, configuration, API keys.

> L'onglet Chat (TUI embarqué via WebSocket/PTY) ne s'affiche pas dans le dashboard malgré `--tui`.
> Utiliser `hermes-tui` en SSH à la place (voir ci-dessous).

```bash
# Service dashboard
sudo systemctl status hermes-dashboard
sudo systemctl restart hermes-dashboard
sudo journalctl -u hermes-dashboard -f
```

## TUI (chat interactif)

Le TUI nécessite un terminal interactif (PTY) et doit tourner sous le compte `hermes` :

```bash
# Depuis le poste perso
ssh storage-01
sudo -i -u hermes        # basculer vers le compte hermes
cd /srv/data/hermes
hermes --tui
```

> Lancer depuis un autre compte (ex: ansible) génère des "gateway error" — toujours utiliser le compte hermes.

---

## Service systemd

```bash
sudo systemctl status hermes-agent
sudo systemctl restart hermes-agent
sudo journalctl -u hermes-agent -f
sudo journalctl -u hermes-agent -n 50
```

---

## Utilisation CLI

```bash
# Chat interactif (depuis storage-01)
cd /srv/data/hermes && hermes chat

# Question one-shot
cd /srv/data/hermes && hermes -z "ta question"

# Statut global
hermes status

# Diagnostics
hermes doctor
```

---

## Configuration

### config.yaml (profil par défaut : `/srv/data/hermes/config.yaml`)

```yaml
model:
  provider: lmstudio
  base_url: "http://127.0.0.1:4000/v1"
  default: "hermes-default"
  context_length: 65536

gateway:
  host: "0.0.0.0"
  port: 8080
```

### .env (`/srv/data/hermes/.env`)

```bash
LM_BASE_URL=http://127.0.0.1:4000/v1
LM_API_KEY=lm-studio    # valeur exacte obligatoire
```

---

## Variables d'environnement (service systemd)

| Variable | Valeur |
|---|---|
| `HOME` | `/opt/hermes` |
| `HERMES_HOME` | `/srv/data/hermes` |
| `LM_BASE_URL` | `http://127.0.0.1:4000/v1` |
| `LM_API_KEY` | `lm-studio` |

---

## SOUL.md — Identité des profils

Chaque profil peut avoir un fichier `SOUL.md` chargé en **slot #1** du system prompt.
Il définit l'identité de l'agent, son environnement, ses outils et son comportement.
Rechargé à chaque message sans redémarrage du service.

```
/srv/data/hermes/profiles/<profil>/SOUL.md
```

Sources versionnées dans le repo :
```
hermes-skills/souls/funk-ai.md   → profil funk-ai
hermes-skills/souls/system.md    → profil system
hermes-skills/souls/monitor.md   → profil monitor
hermes-skills/souls/brain.md     → profil brain
```

### Déployer un SOUL.md

```bash
# Depuis le repo lab (poste perso)
scp hermes-skills/souls/funk-ai.md storage-01:/tmp/soul.md
ssh storage-01 "sudo cp /tmp/soul.md /srv/data/hermes/profiles/funk-ai/SOUL.md"
# Pas de redémarrage nécessaire — rechargé automatiquement
```

### Ce que contient le SOUL.md de funk-ai

- Environnement cluster (machines, IPs, services)
- Accès SSH vers gpu-01 (`hermes@192.168.10.20`)
- Règles d'utilisation d'`ask-agent` (pattern 2 étapes obligatoires)
- Routing : quand appeler `system` vs `monitor` vs `brain` avec exemples concrets
- Différence `ask-agent` (analyse texte rapide) vs `delegate_task` (agent autonome)
- Style : concis, technique, actif

---

## Skills

Les skills sont des fichiers `SKILL.md` chargés en contexte dans chaque session Hermes.
Ils enseignent à l'agent des patterns, commandes et procédures spécifiques.

> **Point d'attention critique** : un skill doit être présent dans **deux endroits** :
> - `$HERMES_HOME/skills/<cat>/<nom>/SKILL.md` — répertoire global (référence)
> - `$HERMES_HOME/profiles/<profil>/skills/<cat>/<nom>/SKILL.md` — chargé par le profil
>
> Placer un skill uniquement dans le répertoire global ne suffit pas — le profil ne le charge pas.

```bash
# Lister les skills actifs du profil courant
sudo -u hermes env HERMES_HOME=/srv/data/hermes hermes skills list

# Vérifier qu'un skill est bien dans le profil funk-ai
sudo ls /srv/data/hermes/profiles/funk-ai/skills/funk/

# Redémarrer après ajout/modif d'un skill
sudo systemctl restart hermes-agent
```

### Skills custom Funk

| Skill | Catégorie | Usage |
|---|---|---|
| `agent-delegation` | `funk` | Déléguer des sous-tâches aux agents system/monitor/brain via `ask-agent` |

Documentation complète : [ask-agent.md](ask-agent.md)

### Skill Qdrant Vector Search

```bash
# Vérifier le skill installé
cat /srv/data/hermes/skills/mlops/qdrant/SKILL.md

# Tester les embeddings (requis pour le skill)
curl -s -X POST http://192.168.10.20:1234/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen3-8b","input":["test"]}' | python3 -c \
  "import sys,json; print('dim:', len(json.load(sys.stdin)['data'][0]['embedding']))"

# Installer qdrant-client si absent
sudo -u hermes /opt/hermes/.hermes/hermes-agent/venv/bin/pip install "qdrant-client>=1.12.0"
```

> Toujours passer par le terminal (fichier /tmp/*.py) pour accéder à Qdrant depuis Hermes,
> jamais via execute_code (pas de qdrant-client dans cet environnement).

---

## Arborescence

Depuis l'incident 2026-05-13, le code est sur le SSD OS et les données sur le RAID5.

```
/opt/hermes/                          → home utilisateur hermes (SSD OS)
├── .local/bin/hermes                 → wrapper bash → venv hermes-agent
└── .hermes/hermes-agent/             → code source + venv Python
    ├── venv/                         → environnement Python (uv)
    ├── hermes_cli/                   → source CLI
    └── web/                          → source frontend dashboard

/srv/data/hermes/                     → HERMES_HOME (RAID5) — données persistantes
├── config.yaml                       → configuration profil par défaut (géré Ansible)
├── .env                              → LM_BASE_URL, LM_API_KEY (géré Ansible)
├── memories/                         → mémoire persistante profil par défaut
├── sessions/                         → historique sessions profil par défaut
├── logs/                             → logs
├── skills/                           → skills installées
├── state.db                          → base SQLite état agent
└── profiles/                         → profils isolés
    ├── funk-ai/                      → config.yaml, memories/, sessions/, state.db
    ├── brain/
    ├── system/
    └── monitor/
```

---

## Mise à jour de Hermes

```bash
# Stopper les services
sudo systemctl stop hermes-dashboard hermes-agent

# Mettre à jour (depuis le compte hermes)
sudo -i -u hermes bash -c 'HOME=/opt/hermes HERMES_HOME=/srv/data/hermes hermes update'

# Redémarrer
sudo systemctl start hermes-agent hermes-dashboard
sudo systemctl status hermes-agent hermes-dashboard --no-pager
```

> Après une mise à jour majeure, recompiler le frontend (voir section suivante) et vérifier
> que `hermes --tui` fonctionne encore (`npm install --ignore-scripts` dans `/opt/hermes/.hermes/hermes-agent/ui-tui/` si besoin).

---

## Recompiler le frontend dashboard

Si mise à jour de hermes-agent nécessite un rebuild :

```bash
sudo -u hermes bash -c \
  'HOME=/opt/hermes && \
   cd /opt/hermes/.hermes/hermes-agent/web && \
   npm install && npm run build'
sudo systemctl restart hermes-dashboard
```

---

## Points d'attention

| Sujet | Détail |
|---|---|
| Code vs données | Code + venv : `/opt/hermes/.hermes/hermes-agent/` (SSD OS) — Profils/données : `/srv/data/hermes/` (RAID5) |
| LiteLLM requis | litellm.service doit tourner avant hermes-agent |
| `LM_API_KEY` | Doit valoir `lm-studio` exactement |
| Contexte | GPU (funk-ai) : 32768 tokens réels, override Hermes à 65536 via config.yaml |
| Contexte CPU | system/monitor : 32768 tokens réels, idem override |
| path `hermes -z` | Toujours lancer depuis `/srv/data/hermes` (cherche .git en remontant) |
| Gemma 4 | Interdit — crash ROCm sur prompts >800 tokens |
| SELinux | Fichiers sur RAID5 ont contexte `unlabeled_t` — exécuter via binaire dans `/opt/hermes/.local/bin/` |
| Dashboard | Accessible uniquement depuis `192.168.1.10:9119` (restreint nftables) |
| TUI | `hermes --tui` nécessite un TTY — utiliser `sudo hermes-tui` en SSH interactif |
| `/opt/hermes` perms | Répertoire en `711` — traversable par tous mais non listable |
| **Skills double emplacement** | Tout skill custom doit être dans `skills/` ET dans `profiles/funk-ai/skills/` — voir [ask-agent.md](ask-agent.md) |
| **Restart après skill** | `systemctl restart hermes-agent` obligatoire après ajout ou modification d'un skill |
| `SupplementaryGroups` | Le service inclut `systemd-journal` — `journalctl` fonctionne sans sudo dans le Terminal de Hermes |
| `systemd-journal` admin | L'utilisateur admin (`alkatrazz`) est aussi dans le groupe — géré via rôle Ansible `common` |