ALFRED.txt
==========
Aide-mémoire technique du projet ALFRED
Version : 26/10/2026
À adapter selon les chemins et les versions réellement installés.

======================================================================
1. PRÉSENTATION RAPIDE
======================================================================

Alfred = assistant domestique local sur mini-PC MINISFORUM Mars MC560.
- Interface Web : Python / Flask + Socket.IO, port 54321
- Réveil vocal ("Alfred") : Vosk, moteur vosk_keyword
- Reconnaissance des phrases : STT (Vosk dans la chaîne vocale)
- Agent de conversation : Hermes, connecté au serveur IA Ollama
- Synthèse vocale : Piper / Wyoming selon la configuration
- Domotique : Home Assistant (REST pour vues ; MCP via Hermes)
- Images : ComfyUI, utilisé par Hermes et par le module météo
- Vision : webcam locale / OpenCV / YOLO et MCP reconnaissance faciale

Une commande vocale de météo ou d'agenda peut être traitée directement
par Alfred, sans passer par Hermes. Les autres questions passent par Hermes.

======================================================================
2. SERVICE ET INTERFACE ALFRED
======================================================================

# État du service
sudo systemctl status alfred --no-pager

# Redémarrer après changement de configuration ou de code
sudo systemctl restart alfred

# Arrêter / démarrer
sudo systemctl stop alfred
sudo systemctl start alfred

# Logs en direct
journalctl -u alfred -f

# Derniers logs
journalctl -u alfred -n 100 --no-pager

# Afficher la configuration du service systemd
sudo systemctl cat alfred

# Vérifier le port Flask
sudo ss -lntp | grep ':54321'

Interface locale : http://127.0.0.1:54321
Interface réseau : http://<IP_DU_MINI_PC>:54321
Recharger Chromium sans cache : Ctrl+F5

# État d'Alfred (mode, dernière réponse, wake, backend TTS, etc.)
curl -sS http://127.0.0.1:54321/api/state | python3 -m json.tool

======================================================================
3. MICROPHONE, HAUT-PARLEUR ET ÉCOUTE
======================================================================

# État des réglages audio
curl -sS http://127.0.0.1:54321/api/audio/settings | python3 -m json.tool

Exemple de réponse observée :
{
  "mic_gain": 74,
  "mic_muted": true,
  "speaker_muted": false,
  "volume": 80
}

mic_gain       = niveau de capture micro (%)
mic_muted      = coupure du micro dans Alfred (true = coupé)
speaker_muted  = coupure du haut-parleur (true = coupé)
volume         = volume de sortie (%)

# État de la détection du mot-clé « Alfred »
curl -sS http://127.0.0.1:54321/api/wake/status | python3 -m json.tool

Exemple de réponse observée :
{
  "engine": "vosk_keyword",
  "error": null,
  "last_score": 1.0,
  "paused": true,
  "running": true,
  "word": "alfred"
}

running = moteur lancé ; paused = écoute du mot-clé suspendue.
Quand mic_muted=true, paused=true est généralement attendu.
Le détecteur du mot-clé est distinct de la transcription complète STT.

# Endpoints d'action (POST) : à utiliser seulement pour le dépannage
curl -sS -X POST http://127.0.0.1:54321/api/wake/start
curl -sS -X POST http://127.0.0.1:54321/api/wake/stop

# Faire prononcer une phrase pour tester la synthèse vocale
curl -sS -X POST http://127.0.0.1:54321/api/tts/say \
  -H 'Content-Type: application/json' \
  -d '{"text":"Bonjour, je suis Alfred."}'

Note : si le micro est coupé dans Alfred, le redémarrage du wake
ne suffit pas toujours à réactiver une écoute normale : vérifier
également le bouton Mute.

======================================================================
4. CAMÉRA LOCALE ET RÉGLAGES
======================================================================

# État des paramètres V4L2 exposés par Alfred
curl -sS http://127.0.0.1:54321/api/camera/settings | python3 -m json.tool

# Identifier les caméras
v4l2-ctl --list-devices

# Lire les paramètres matériels de la webcam
v4l2-ctl -d /dev/video0 --list-ctrls-menus

# Remettre la luminosité à la valeur d'usine de cette webcam
v4l2-ctl -d /dev/video0 --set-ctrl brightness=0

# Aperçu MJPEG (ouvre et réserve la webcam le temps de la connexion)
http://127.0.0.1:54321/api/camera/stream

Attention : l'aperçu local peut monopoliser la webcam et empêcher
temporairement le MCP de reconnaissance faciale d'y accéder.
Le bouton Caméra de l'interface permet de désactiver le flux.

Fichiers principaux :
/opt/alfred/app/services/camera.py
/opt/alfred/app/services/camera_settings.py

======================================================================
5. HERMES : AGENT, WEBUI ET MCP
======================================================================

# Lancer le tableau de bord Hermes (port indiqué : 9119)
hermes dashboard --host 0.0.0.0

Interface : http://<IP_DU_MINI_PC>:9119
Attention : --host 0.0.0.0 expose le tableau de bord sur le réseau.
Éviter l'exposition publique sans contrôle d'accès.

# Vérifier le MCP de reconnaissance faciale (commande utilisée auparavant)
hermes mcp test face_recognition

Répertoire des MCP de Hermes :
/opt/hermes/MCP_home_assistant/
/opt/hermes/MCP_comfyui/
/opt/hermes/MCP_face_recognition/

Exemple de structure d'un MCP :
/opt/hermes/MCP_nom/mcp.py  (nom du fichier variable)
/opt/hermes/MCP_nom/venv/
/opt/hermes/MCP_nom/.env

# Configuration/session liée à l'intégration Hermes dans Alfred
/opt/alfred/app/services/hermes_client.py
/opt/alfred/app/config/hermes_session.json

Important : le fichier /opt/alfred/app/config/identity.md a déjà
provoqué des restrictions artificielles empêchant Hermes de proposer
certains outils. Ne pas le réintroduire sans vérifier son contenu.

======================================================================
6. HOME ASSISTANT : MÉTÉO, AGENDA, CAPTEURS
======================================================================

# État météo actuel et prévisions (depuis l'API Alfred)
curl -sS http://127.0.0.1:54321/api/ha/weather | python3 -m json.tool

# Recommandations vestimentaires et illustration générée
# Attention : peut déclencher une génération ComfyUI coûteuse !
curl -sS http://127.0.0.1:54321/api/ha/weather/outfits \
  | python3 -c 'import json,sys; d=json.load(sys.stdin); d.pop("image",None); print(json.dumps(d,indent=2,ensure_ascii=False))'

# Vérifier les calendriers présents
curl -sS http://127.0.0.1:54321/api/calendar/calendars \
  | python3 -m json.tool

# Températures exposées par Home Assistant
curl -sS http://127.0.0.1:54321/api/ha/temperatures \
  | python3 -m json.tool

# Liste des caméras Home Assistant (pas la caméra USB locale)
curl -sS http://127.0.0.1:54321/api/ha/cameras \
  | python3 -m json.tool

Configuration Home Assistant utilisée par Alfred :
HA_URL                  = URL de Home Assistant
HA_TOKEN                = jeton longue durée (SECRET)
HA_WEATHER_ENTITY       = entité weather.* à interroger
ALFRED_TIMEZONE         = Europe/Paris
ALFRED_ALLOW_CALENDAR_WRITES = true/false

Le fichier qui contient ces variables dépend du service systemd.
Vérifier avec « sudo systemctl cat alfred » et le répertoire de travail.
Ne jamais copier HA_TOKEN dans ALFRED.txt.

Fichiers Python utiles :
/opt/alfred/app/services/ha_weather.py
/opt/alfred/app/services/ha_views.py
/opt/alfred/app/services/alfred_intents.py
/opt/alfred/app/services/alfred_views_controller.py

======================================================================
7. COMFYUI : GÉNÉRATION D'IMAGES ET TENUES MÉTÉO
======================================================================

Adresse du serveur ComfyUI utilisée jusqu'ici :
http://192.168.1.13:8188

# Vérifier la connexion ComfyUI
curl -sS --max-time 5 http://192.168.1.13:8188/system_stats \
  | python3 -m json.tool

Workflow de génération déjà utilisé par Hermes :
/opt/hermes/MCP_comfyui/workflows/text_to_image.json

Configuration MCP :
/opt/hermes/MCP_comfyui/.env

Paramètres propres aux tenues météo (depuis la V5) :
/opt/alfred/app/config/weather_outfits.env

# Éditer ces paramètres
sudo nano /opt/alfred/app/config/weather_outfits.env

Réglages du module météo :
ALFRED_WEATHER_ILLUSTRATION_ATTEMPTS=2
ALFRED_WEATHER_ILLUSTRATION_TARGET_SCORE=8.6
ALFRED_WEATHER_DISPLAY_SIZE=350
ALFRED_WEATHER_REVIEW=true
ALFRED_WEATHER_REFERENCE_MODE=auto
ALFRED_WEATHER_REFERENCE_DENOISE=0.56
ALFRED_WEATHER_PRESERVE_FACE=true
ALFRED_WEATHER_ACCESSORY_LIMIT=1

Tentatives : maximum par personnage, pas nombre fixe.
Review : dépend d'un workflow vision compatible ; n'est pas garantie.
Reference mode auto : se replie sur text-to-image si incompatibilité.
Reference denoise : valeur plus élevée = vêtements plus modifiables,
mais risque accru de variation des visages.

Images de référence V5 :
/opt/alfred/app/static/assets/weather/child-reference.png
/opt/alfred/app/static/assets/weather/adult-reference.png

Code de génération et assemblage :
/opt/alfred/app/services/weather_outfits.py

Cache (emplacement par défaut, sauf ALFRED_CACHE_DIR personnalisé) :
/opt/alfred/app/cache/weather_outfit_cache.json
/opt/alfred/app/cache/weather_outfit_images/

# Consulter le cache sans le supprimer
ls -lh /opt/alfred/app/cache/weather_outfit_images/

# Tester la syntaxe du module
/opt/alfred/venv/bin/python -m py_compile \
  /opt/alfred/app/services/weather_outfits.py

Après modification du fichier de réglages :
sudo systemctl restart alfred

======================================================================
8. ARBORESCENCE IMPORTANTE
======================================================================

/opt/alfred/
  venv/                     Python virtuel de l'application
  app/
    app.py                  Serveur Flask / API
    templates/index.html    Page principale
    static/js/              Scripts de l'interface
    static/css/             Styles de l'interface
    services/audio.py       STT / TTS
    services/wakeword.py    Réveil vocal Vosk
    services/hermes_client.py Appels Hermes
    services/camera.py      Caméra locale
    services/camera_settings.py Réglages webcam
    services/ha_weather.py  Météo Home Assistant
    services/weather_outfits.py Tenues et ComfyUI
    config/weather_outfits.env Réglages V5
    config/hermes_session.json Session Hermes
    cache/                  Illustrations météo en cache

/opt/hermes/
  MCP_home_assistant/
  MCP_comfyui/
  MCP_face_recognition/

Cette arborescence synthétise plusieurs versions successives :
vérifier l'existence d'un fichier avant de l'éditer.

======================================================================
9. DÉPANNAGE RAPIDE
======================================================================

# Alfred ne démarre pas
sudo systemctl status alfred -n 50 --no-pager
journalctl -u alfred -n 100 --no-pager

# Erreur Python dans un module
/opt/alfred/venv/bin/python -m py_compile /opt/alfred/app/app.py

# API Flask ne répond pas
curl -v --max-time 5 http://127.0.0.1:54321/api/state
sudo ss -lntp | grep ':54321'

# Micro coupé / mot-clé en pause
curl -sS http://127.0.0.1:54321/api/audio/settings
curl -sS http://127.0.0.1:54321/api/wake/status

# ComfyUI inaccessible
curl -v --max-time 5 http://192.168.1.13:8188/system_stats
# Vérifier BASE/COMFYUI_URL et le .env du MCP

# ComfyUI génère la même image
# Vérifier seeds du workflow, bouton Régénérer et cache.
# La V5 utilise de nouveaux seeds lors de la régénération.

# Les tenues ne correspondent pas à la date demandée
# Vérifier les prévisions de la date, les paramètres focus_date/date
# et la disponibilité des prévisions Home Assistant.

# Sauvegarder avant de modifier le code
sudo cp -a /opt/alfred/app /opt/alfred/app.backup.$(date +%Y%m%d_%H%M%S)

======================================================================
10. RÈGLES PRATIQUES À NE PAS OUBLIER
======================================================================

- Ne pas mettre de jetons/API keys/mots de passe dans ce fichier.
- Tester la syntaxe Python avant de redémarrer Alfred.
- Sauvegarder l'app avant d'appliquer un patch.
- Conserver les calendriers et les réglages caméra lors d'une mise à jour météo.
- Ne pas bloquer la webcam avec un aperçu permanent.
- Pour les images météo : une fille de 8 ans et un homme de 42 ans.
- Les deux personnes doivent garder une apparence cohérente entre les jours.
- ComfyUI génère les images ; Home Assistant fournit la météo.
- La génération des tenues peut être longue : ne pas la relancer inutilement.
- La plupart des réglages V5 sont modifiables dans weather_outfits.env.

FIN DU FICHIER
