RAPPORT DE BUG : Installation et Lancement de Jarvis-OS (v0.3.1)

[Dfalm-Original]

---

LICENSE: WTFPL
VERSION: 1.0.0
TYPE: BUG_REPORT
STATUS: PRODUCTION
Auteur : Laurent (Dfalm)

🐞 RAPPORT DE BUG : Installation et Lancement de Jarvis-OS (v0.3.1)

🎯 MISSION

Documenter les anomalies critiques rencontrées lors du déploiement du bundle portable de Jarvis-OS v0.3.1 sur Windows 11, afin de permettre la résolution des régressions de lancement et d'installation.

---

💻 ENVIRONNEMENT TECHNIQUE

OS : Microsoft Windows 11 Professionnel (Build 26100)
Matériel : Xeon 10 cores / 20 Threads
Mémoire : 64 Go RAM
Installation : Bundle ZIP "portable" (v0.3.1) déployé en %USERNAME%\jarvis-OS-2 ( SOURCE : Release v0.3.1 - Bugfix bundle offline relocalisable GitHub )
Backend LLM : Local (Ollama - Modèle Qwen2.5:3b)
PS %USERNAME%\jarvis-OS-2> ollama run qwen2.5:3b "Bonjour"

• Olá! Comment ça va aujourd'hui ? Que puis-je faire pour vous aider aujourd'hui?

---

0. Setup installation avec succès

PS %USERNAME%\jarvis-OS-2> .\jarvis setup
JARVIS - Configuration web locale
Ouverture de http://127.0.0.1:8765/setup

Toutes les étapes se sont bien déroulées 👍 :

Étape 1 / 5
Configuration Jarvis
Cet assistant configure ton instance locale. Avec un bundle offline, aucun téléchargement supplémentaire n'est nécessaire.
Bundle offline = prêt
Python = prêt
Modèle YOLO = prêt
Modèle Piper = prêt
LiveKit local = prêt
...
Étape 2 / 5
Identité Ton prénom est affiché lors du scan biométrique et dans l'interface.
Prénom = Laurent
Ville = Osef
Photo de référence (optionnel)
...
Étape 3 / 5
LLM principal
Optionnel : tu peux laisser la clé vide et la configurer plus tard dans les réglages.
Backend = Local (Ollama)
▾ Modèle Ollama = Qwen2.5
URL Ollama = http://localhost:11434
...
Étape 4 / 5
Modules optionnels
Active uniquement ce dont tu as besoin. Tout reste modifiable plus tard dans les réglages.
[ NA ] Utiliser ElevenLabs (sinon Piper local)
[ NA ] Activer le pipeline vocal LiveKit
[ NA ] Reconnaissance faciale (extra vision installé)
...
Étape 5 / 5
Configuration terminée
Jarvis est prêt. Lance le serveur principal depuis le terminal, puis ouvre l'interface.
http://127.0.0.1:8000/

---

🚩 SYMPTÔMES ET ANOMALIES

1. Échec Critique du Lancement de l'API (Crash au Boot)

• Symptôme : .\jarvis run renvoie un API timeout. Le port 8000 reste fermé.
• Analyse : Le fichier api.log reste vide car le processus crash instantanément.
• Cause Racine : Le module VisionTool (dans src/jarvis/capabilities/tools/vision.py) tente d'instancier un client AsyncOpenAI sans vérifier la présence d'une clé API. Si OPENAI_API_KEY est absente, l'application crash, même si l'utilisateur a choisi un backend Local (Ollama).
• Impact : Bloquant. L'API ne démarre jamais sans clé OpenAI.

2. Conflit d'Accès aux Fichiers de Logs (File Lock)

• Symptôme : Erreur PowerShell Set-Content : Le processus ne peut pas accéder au fichier... car il est en cours d'utilisation.
• Analyse : Le script jarvis.ps1 tente de vider les logs au démarrage. Si un processus zombie (livekit-server.exe ou python.exe) détient encore le handle du fichier, le script crash immédiatement.
• Impact : Majeur. Empêche tout relancement après un crash sans intervention manuelle (taskkill).

3. Fausse Négative du Diagnostic .\jarvis doctor

• Symptôme : Le doctor annonce LiveKit binaire absent alors que le fichier livekit-server.exe est bien présent dans bundle\bin\.

• Cause Racine : Le script de diagnostic ne cherche probablement pas dans le répertoire spécifique du bundle portable, rendant l'outil de diagnostic inopérant pour la version portable.

• Impact : Confusion utilisateur.

  PS %USERNAME%\jarvis-OS-2> .\jarvis doctor
  FastAPI eteint (port 8000)
  LiveKit binaire absent
  https://github.com/livekit/livekit/releases
  uv installe
  PS %USERNAME%\jarvis-OS-2> ls .\bundle\bin
  Répertoire : %USERNAME%\jarvis-OS-2\bundle\bin
  Mode LastWriteTime Length Name
  ------ 09/06/2026 01:19 53315072 livekit-server.exe
  ------ 18/06/2026 22:28 69339136 uv.exe

4. Échec du "Préchauffement Vocal" (Bug d'Encodage Unicode)

• Symptôme : Vocal prechauffement long s'affiche systématiquement, alors que l'agent vocal est actif.
• Analyse :
  1. L'agent vocal tente d'écrire un symbole "Check" (✓) dans le log via logger.info("\u2713 Jarvis vocal prêt...").
  2. Sur Windows, l'encodage par défaut (cp1252) ne supporte pas ce caractère, provoquant une UnicodeEncodeError.
  3. Le message n'est donc jamais écrit dans voice.log.
  4. Le script jarvis.ps1 (qui scanne le log pour trouver ce texte exact) conclut à un timeout.
• Impact : Ergonomique / Signalement erroné.

5. Variables d'Environnement Manquantes dans le Bundle

• Symptôme : ValueError: ws_url is required dans le log vocal.
• Cause Racine : Le bundle portable ne pré-configure pas LIVEKIT_URL, LIVEKIT_API_KEY et LIVEKIT_API_SECRET dans le fichier .env, alors que le serveur LiveKit est lancé en mode --dev.
• Impact : Bloquant pour le mode vocal.

---

🛠️ TENTATIVES DE RÉSOLUTION (WORKAROUNDS)

Action effectuée	Résultat	Statut
Ajout de OPENAI_API_KEY=sk-dummy-key	L'API démarre enfin	✅ Succès
Ajout de LIVEKIT_URL=ws://localhost:7880	L'agent vocal s'enregistre	✅ Succès
taskkill /F /IM livekit-server.exe	Résolution du lock de fichier	✅ Succès
%LocalAppData%\Temp\jarvis	Supprimer TOUS les fichiers logs	✅ Succès
Lancement manuel via Python	Identification du crash VisionTool	✅ Succès

---

💡 RECOMMANDATIONS POUR LE FIX (DEVELOPPER)

1. VisionTool : Rendre l'initialisation du client OpenAI optionnelle ou encapsuler l'instanciation dans un bloc try/except pour éviter le crash global.
2. Jarvis.ps1 : Modifier la gestion des logs pour utiliser -ErrorAction SilentlyContinue ou supprimer les fichiers avant l'écriture.
3. Encodage : Remplacer le symbole \u2713 par un caractère ASCII standard (ex: [OK]) dans les logs pour assurer la compatibilité Windows.
4. Bundle .env : Pré-remplir les valeurs de développement pour LiveKit dans le .env du bundle portable.
5. Doctor : Mettre à jour les chemins de recherche du binaire LiveKit pour inclure bundle\bin\.

---

Rapport généré le : 2026-07-14
Statut : Prêt pour dépôt GitHub Issue.