EveFlow/README.md

EveFlow 2 — Interface vocale JARVIS pour Hermes Agent

EveFlow est un compagnon de bureau Windows qui transforme Hermes Agent en assistant vocal à la JARVIS : un noyau holographique réactif au son, une conversation en streaming, les outils, sous-agents, approbations, crons, skills et sessions d'Hermes pilotés depuis un seul HUD.

La version 2 est une réécriture complète : plus de robot 3D, un pipeline vocal fiable (AudioWorklet + détection d'activité vocale), un client Hermes qui exploite l'API serveur complète (runs SSE, sessions, jobs, capabilities) et une architecture Electron sécurisée (sandbox, webSecurity actif, réseau proxifié par le processus principal).

---

Fonctionnalités

Noyau JARVIS

• Arc reactor rendu en Canvas 2D : anneaux gradués, arcs segmentés et spectre radial calculé sur le vrai signal audio (voix synthétisée ou microphone).
• États visuels : veille, écoute, analyse (outils en cours), transmission, attention (approbation), anomalie, succès.
• Quatre thèmes (arc cyan, gold, crimson, emerald), mode animations réduites.
• Mode compact flottant toujours au premier plan, opacité réglable.

Voix

• Capture micro via AudioWorklet à 16 kHz, sans monitoring du micro dans les haut-parleurs, avec annulation d'écho et réduction de bruit.
• Détection d'activité vocale (seuil adaptatif, sensibilité et silence de fin réglables) : l'enregistrement s'arrête tout seul quand vous avez fini de parler.
• Mains libres : le micro se réactive après chaque réponse.
• STT : n'importe quelle API /v1/audio/transcriptions compatible OpenAI (Qwen3-ASR, Whisper, Speaches, faster-whisper-server, LocalAI, OpenAI). Repli sur la reconnaissance Chromium.
• TTS : API /v1/audio/speech compatible OpenAI (Kokoro, Piper, OpenAI…), voix système Windows ou Google Translate. Lecture phrase par phrase pendant le streaming, préchargement du segment suivant, coupure instantanée.
• Raccourcis globaux : Ctrl+Shift+Espace (micro), Ctrl+Shift+J (afficher/masquer), Ctrl+Shift+Échap (couper la voix).

Hermes, toute la puissance

• Découverte automatique via GET /v1/capabilities et GET /health/detailed, choix du transport le plus riche :
  1. Runs API (POST /v1/runs + GET /v1/runs/{id}/events) : deltas, outils, sous-agents, approval.request, run.completed, arrêt (/stop) et injection de consignes en cours de run (/steer).
  2. Sessions API (/api/sessions/{id}/chat/stream) : mémoire côté serveur, fork, suppression, relecture de l'historique.
  3. Chat completions OpenAI (/v1/chat/completions) avec hermes.tool.progress, continuité de session (X-Hermes-Session-Id) et outils EveFlow côté client (état du HUD, fichiers partagés, notifications).
• Mémoire longue durée via X-Hermes-Session-Key.
• Approbations d'outils affichées dans le HUD : une fois, pour la session, toujours, refuser.
• Crons : création en langage naturel (every 1h, weekdays at 9am, in 30m, expression cron), pause/reprise, exécution immédiate, édition, historique des résultats lus à voix haute.
• Skills et toolsets exposés par le serveur, sessions navigables.
• Webhook local (POST http://<pc>:7842/eveflow/hook) pour recevoir les livraisons de crons, le miroir Telegram ou n'importe quel script, avec secret optionnel.
• Images inline (URL, data URL, fichiers du dossier partagé Documents/EveFlow_Shared).

Système

• Télémétrie réelle : charge CPU, mémoire, fréquence, FPS, uptime.
• Journal sur disque (%APPDATA%/eveflow/eveflow.log), icône de zone de notification, instance unique.

---

Stack

• Electron 44 (sandbox, contextIsolation, webSecurity actif, proxy HTTP en streaming dans le main process)
• React 19 + Vite 8 + TypeScript 5.9 + Zustand
• Canvas 2D, Web Audio (AudioWorklet, AnalyserNode)
• Vitest pour les tests unitaires (SSE, VAD, WAV, normalisation d'événements Hermes)

electron/        processus principal (fenêtre, tray, raccourcis, IPC, webhook, proxy HTTP)
shared/          contrat IPC + normalisation des pushs webhook (main + renderer)
src/lib          transport, SSE, persistance, utilitaires texte
src/services     hermes/ (client, événements, outils locaux)  voice/ (capture, VAD, STT, TTS)
src/state        stores Zustand (settings, chat, hermes, voice)
src/components   hud/ chat/ panels/ settings/ compact/
tests/           vitest

---

Prérequis côté Hermes

Activez le serveur API dans la configuration Hermes (~/.hermes/config.yaml) ou via l'environnement :

API_SERVER_ENABLED=true
API_SERVER_PORT=8642
API_SERVER_KEY=<votre clé>

Puis lancez hermes gateway. Renseignez l'URL (http://<hôte>:8642) et la clé dans Paramètres → Hermes et cliquez Tester la liaison. Le transport choisi apparaît dans la barre supérieure.

Pour recevoir les résultats de crons ou le miroir d'autres canaux dans EveFlow, faites pointer une livraison Hermes (script, webhook, deliver) vers http://<ip-du-pc>:7842/eveflow/hook avec un JSON tel que :

{ "role": "assistant", "text": "Rapport terminé", "source": "telegram" }
{ "event": "run.completed", "input": "question", "output": "réponse" }
{ "event": "job.completed", "job": { "name": "Rapport" }, "output": "…", "status": "ok" }

---

Développement

npm install
npm start          # Vite + Electron (rechargement à chaud du renderer)
npm test           # tests unitaires
npm run typecheck  # renderer + main process

Sans Electron, npm run dev puis http://127.0.0.1:5173/ (ou ?mode=compact) permet de travailler l'interface dans un navigateur ; les appels réseau passent alors directement par fetch (CORS requis côté serveur).

Packaging Windows et versions

npm run dist

L'installateur NSIS est produit dans out/. Le numéro de version publié est releaseVersion dans package.json (quatre chiffres, ex. 2.0.0.1 : le quatrième chiffre sert aux petits correctifs). version reste la base à trois chiffres exigée par electron-builder. À chaque fusion sur master, le workflow GitHub Actions crée le tag et la release Windows si ce numéro n'a pas encore été publié.

---

Licence

MIT.