Initial commit

docs/reference/FONCTIONNEMENT_MODE_SHADOW.md

@@ -0,0 +1,196 @@
+# 🔍 Fonctionnement du Mode Shadow
+
+## Qu'est-ce que le Mode Shadow ?
+
+Le mode Shadow (👀) est le mode d'**observation passive** où l'application :
+- ✅ Observe les actions de l'utilisateur
+- ✅ Enregistre les patterns répétitifs
+- ❌ N'interfère PAS avec l'utilisateur
+- ❌ Ne suggère PAS d'actions
+
+## 🤔 Problème Actuel
+
+### Ce qui se passe maintenant
+
+Quand tu cliques sur "Start" en mode Shadow :
+1. L'application démarre la boucle cognitive
+2. Elle capture l'écran
+3. Elle cherche une "intention" (quelle action automatiser)
+4. **Pas d'intention** → Elle ne fait rien et attend
+
+### Pourquoi les warnings ?
+
+Les warnings que tu vois :
+```
+WARNING: Aucune détection avec owl-v2
+WARNING: DINO n'est pas disponible
+WARNING: YOLO-World n'est pas disponible
+ERROR: Aucun modèle n'a pu détecter 'observer'
+```
+
+Sont causés par une tentative de détecter des éléments avec le terme "observer", qui est trop générique.
+
+**C'est maintenant corrigé** : L'application n'essaie plus de détecter sans intention.
+
+## ✅ Comment Ça Devrait Fonctionner
+
+### Architecture Complète (À Implémenter)
+
+```
+Mode Shadow
+    ↓
+Capture d'événements système
+    ↓
+Détection d'actions répétitives
+    ↓
+Création d'une "intention"
+    ↓
+Apprentissage du pattern
+    ↓
+Proposition de passer en mode Assisté
+```
+
+### Ce qui Manque Actuellement
+
+**Capture d'événements système** :
+- Hooks clavier (pynput, keyboard)
+- Hooks souris (pynput, mouse)
+- Détection de patterns répétitifs
+
+### Implémentation Actuelle (Simplifiée)
+
+L'application attend que tu **définisses manuellement une tâche** :
+1. Via l'interface (à ajouter)
+2. Via des actions répétitives détectées (à implémenter)
+
+## 🚀 Solution Temporaire
+
+En attendant l'implémentation complète des hooks système, voici comment utiliser l'application :
+
+### Option 1: Mode Assisté Direct
+
+Au lieu de commencer en Shadow, commence directement en mode Assisté :
+
+1. **Définir une tâche manuellement** (via interface à ajouter)
+2. **Passer en mode Assisté**
+3. **Valider les suggestions**
+
+### Option 2: Utiliser l'API Programmatique
+
+Créer une tâche via code :
+
+```python
+from core.learning_manager import LearningManager
+from core.models import TaskProfile
+
+# Créer une tâche
+task = TaskProfile(
+    task_id="test_task",
+    window_title="Firefox",
+    description="Cliquer sur le bouton de recherche"
+)
+
+# Définir l'intention
+learning_manager.set_current_intent("button")
+```
+
+## 📝 Prochaines Étapes
+
+### Pour Rendre le Mode Shadow Fonctionnel
+
+1. **Implémenter la capture d'événements** :
+```python
+from pynput import mouse, keyboard
+
+def on_click(x, y, button, pressed):
+    if pressed:
+        # Enregistrer le clic
+        capture_action("click", x, y)
+
+def on_key(key):
+    # Enregistrer la frappe
+    capture_action("key", key)
+
+# Démarrer les listeners
+mouse_listener = mouse.Listener(on_click=on_click)
+keyboard_listener = keyboard.Listener(on_press=on_key)
+```
+
+2. **Détecter les patterns répétitifs** :
+```python
+def detect_repetitive_pattern(actions):
+    # Analyser les actions pour trouver des répétitions
+    # Si 3+ actions similaires → Créer une intention
+    pass
+```
+
+3. **Créer automatiquement des intentions** :
+```python
+if pattern_detected:
+    intent = extract_intent_from_pattern(pattern)
+    learning_manager.set_current_intent(intent)
+```
+
+## 🎯 État Actuel
+
+### Ce qui Fonctionne
+
+✅ **Capture d'écran** : L'application capture l'écran en continu
+✅ **Détection UI** : OWL-v2 peut détecter des éléments (boutons, champs, etc.)
+✅ **Raisonnement** : Qwen3-VL peut analyser les images
+✅ **Mémoire visuelle** : OpenCLIP stocke les embeddings
+
+### Ce qui Manque
+
+❌ **Capture d'événements** : Pas de hooks clavier/souris
+❌ **Détection de patterns** : Pas d'analyse des répétitions
+❌ **Création auto d'intentions** : Pas de génération automatique
+
+## 💡 Recommandation Actuelle
+
+**Pour tester l'application maintenant** :
+
+1. **Ne pas utiliser le mode Shadow** pour l'instant
+2. **Attendre l'implémentation des hooks système**
+3. **Ou contribuer à l'implémentation** (voir ci-dessous)
+
+### Comment Contribuer
+
+Si tu veux implémenter la capture d'événements :
+
+```bash
+# Installer les dépendances
+pip install pynput
+
+# Créer le module
+touch geniusia2/core/event_capture.py
+
+# Implémenter les hooks
+# Voir exemple ci-dessus
+```
+
+## 📚 Ressources
+
+- **pynput** : https://pynput.readthedocs.io/
+- **keyboard** : https://github.com/boppreh/keyboard
+- **mouse** : https://github.com/boppreh/mouse
+
+---
+
+## ✅ Résumé
+
+**Situation actuelle** :
+- Le mode Shadow démarre mais n'a rien à faire sans événements utilisateur
+- Les warnings sont normaux et ont été corrigés
+- L'application attend une intention pour agir
+
+**Solution temporaire** :
+- L'application fonctionne mais en mode "passif"
+- Elle attend que tu définisses une tâche manuellement
+- Ou que les hooks système soient implémentés
+
+**Prochaine étape** :
+- Implémenter la capture d'événements système
+- Ou utiliser l'application en mode manuel pour l'instant
+
+**L'application est fonctionnelle, mais le mode Shadow complet nécessite encore du développement ! 🚀**