Geniusia_v2/.kiro/specs/gui-logs-improvement/design.md

Design - Amélioration GUI et Logs

Overview

Ce document décrit l'architecture et le design de la nouvelle interface utilisateur minimaliste et du système de logs amélioré pour GeniusIA v2.

Architecture

┌─────────────────────────────────────────────────────────┐
│                    Main Application                      │
└────────────────┬────────────────────────────────────────┘
                 │
        ┌────────┴────────┐
        ▼                 ▼
┌──────────────┐  ┌──────────────────┐
│ Orchestrator │  │  Improved GUI    │
│              │  │                  │
│ - Détecte    │──│ - System Tray   │
│ - Apprend    │  │ - Logs Panel    │
│ - Suggère    │  │ - Popups        │
└──────┬───────┘  └──────────────────┘
       │
       ▼
┌──────────────┐
│ HumanLogger  │
│              │
│ - Messages   │
│ - Formatting │
└──────────────┘

Components and Interfaces

1. HumanLogger

Classe pour générer des messages lisibles par l'utilisateur.

class HumanLogger:
    """
    Logger qui génère des messages simples pour l'utilisateur.
    """
    
    def log_observation(self, action_type: str, window: str):
        """Log une action observée."""
        return f"👀 Action dans {window}"
    
    def log_pattern_detected(self, repetitions: int, task_name: str):
        """Log un pattern détecté."""
        return f"🎯 Pattern détecté: {task_name} (répété {repetitions}x)"
    
    def log_workflow_learned(self, task_name: str, count: int):
        """Log un workflow appris."""
        return f"📚 Workflow appris: {task_name} ({count} observations)"
    
    def log_mode_change(self, old_mode: str, new_mode: str):
        """Log un changement de mode."""
        return f"✅ Mode {new_mode} activé"
    
    def log_finetuning_started(self, num_examples: int):
        """Log le début du fine-tuning."""
        return f"🧠 Amélioration du modèle ({num_examples} exemples)..."
    
    def log_finetuning_completed(self, duration: float):
        """Log la fin du fine-tuning."""
        return f"✅ Modèle amélioré (en {duration:.1f}s)"

2. ImprovedGUI

Interface minimaliste avec system tray.

Layout Principal

┌─────────────────────────────────────┐
│  GeniusIA v2                  [_][X]│
├─────────────────────────────────────┤
│                                     │
│  Mode: 👀 Observation               │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  │
│                                     │
│  📊 Activité:                       │
│  • 12 actions observées             │
│  • 2 patterns détectés              │
│                                     │
│  🧠 Fine-tuning:                    │
│  • 8/10 exemples collectés          │
│                                     │
├─────────────────────────────────────┤
│  📝 Journal:                        │
│  ┌─────────────────────────────────┐│
│  │14:23 👀 J'observe...            ││
│  │14:24 🎯 Pattern: Calculer 9/9   ││
│  │14:24 📚 J'apprends...           ││
│  │14:25 💡 Prêt à suggérer         ││
│  │14:26 ✅ Mode Suggestions activé ││
│  └─────────────────────────────────┘│
│                                     │
│  [Pause] [Arrêter]                 │
└─────────────────────────────────────┘

System Tray

Icône dans la barre: 🤖

Menu clic droit:
┌─────────────────────┐
│ 🤖 GeniusIA v2      │
├─────────────────────┤
│ 👀 Mode: Shadow     │
│ 📊 12 actions       │
├─────────────────────┤
│ Afficher            │
│ Masquer             │
│ ─────────────────   │
│ Quitter             │
└─────────────────────┘

Popup Interactif

┌─────────────────────────────────────────┐
│  💡 J'ai une idée !                     │
│                                         │
│  J'ai remarqué que vous faites souvent: │
│  "Calculer 9/9 dans la calculatrice"   │
│                                         │
│  Est-ce que je peux essayer de vous    │
│  suggérer cette action la prochaine    │
│  fois ?                                 │
│                                         │
│  [Oui, essaie !]  [Non, continue]     │
│                                         │
│  ⏱️ Fermeture auto dans 10s            │
└─────────────────────────────────────────┘

3. LogsPanel

Widget pour afficher les logs avec scroll.

class LogsPanel(QWidget):
    """
    Panneau d'affichage des logs avec scroll.
    
    - Affiche 5 dernières actions
    - Scrollable jusqu'à 30
    - Auto-scroll si en bas
    - Format: HH:MM emoji Message
    """
    
    def add_log(self, message: str, emoji: str = "ℹ️"):
        """Ajoute un log avec timestamp."""
        pass
    
    def clear(self):
        """Efface tous les logs."""
        pass
    
    def get_logs(self) -> List[str]:
        """Retourne l'historique."""
        pass

4. InteractiveDialog

Popup pour dialogues avec timeout.

class InteractiveDialog(QDialog):
    """
    Dialogue interactif avec timeout automatique.
    
    - Non-bloquant (l'app continue)
    - Timeout 10 secondes
    - Callbacks pour réponses
    """
    
    def __init__(
        self,
        title: str,
        message: str,
        on_accept: Callable,
        on_reject: Callable,
        timeout: int = 10
    ):
        pass

Data Models

LogMessage

@dataclass
class LogMessage:
    """Message de log pour affichage."""
    timestamp: datetime
    emoji: str
    message: str
    level: str  # 'info', 'success', 'warning', 'error'
    technical_details: Optional[str] = None  # Pour logs techniques

GUIState

@dataclass
class GUIState:
    """État de la GUI."""
    mode: str  # 'shadow', 'assist', 'auto'
    is_running: bool
    actions_count: int
    patterns_count: int
    workflows_count: int
    finetuning_status: Optional[str]  # None, 'collecting', 'training', 'completed'
    finetuning_progress: Optional[int]  # 0-100 ou None

Error Handling

Erreurs GUI

• Erreur d'affichage : Logger et continuer sans GUI
• Erreur system tray : Fallback vers fenêtre normale
• Erreur popup : Logger et utiliser notification simple

Erreurs Logs

• Fichier de log inaccessible : Créer nouveau fichier avec timestamp
• Disque plein : Nettoyer anciens logs automatiquement
• Permission refusée : Logger dans /tmp en fallback

Testing Strategy

Unit Tests

• Test HumanLogger : Vérifier format des messages
• Test LogsPanel : Vérifier scroll et limite 30
• Test InteractiveDialog : Vérifier timeout
• Test GUIState : Vérifier mise à jour

Integration Tests

• Test Orchestrator → GUI : Vérifier envoi de messages
• Test Popup → Orchestrator : Vérifier callbacks
• Test System Tray : Vérifier menu et actions

Manual Tests

• Test sur Ubuntu : Vérifier system tray et thème
• Test avec actions répétitives : Vérifier détection
• Test timeout : Vérifier fermeture auto après 10s

Correctness Properties

A property is a characteristic or behavior that should hold true across all valid executions of a system.

Property 1: Log History Bounds

For any sequence of log messages, the visible history should never exceed 30 messages.

Validates: Requirements 3.3

Property 2: Timeout Consistency

For any interactive dialog, if no user response is received within 10 seconds, the dialog should close automatically.

Validates: Requirements 4.3

Property 3: Mode Display Consistency

For any mode change, the GUI should display the correct mode icon and label within 100ms.

Validates: Requirements 5.1

Property 4: Message Ordering

For any sequence of events, the logs should appear in chronological order.

Validates: Requirements 2.1, 2.2, 2.3, 2.4

Property 5: Non-blocking Dialogs

For any interactive dialog displayed, the Orchestrator should continue processing events.

Validates: Requirements 4.2

Implementation Notes

PyQt5 Signals

Utiliser des signaux Qt pour communication thread-safe :

class GUISignals(QObject):
    """Signaux pour communication Orchestrator → GUI."""
    log_message = pyqtSignal(str, str)  # (emoji, message)
    update_stats = pyqtSignal(dict)  # GUIState
    show_dialog = pyqtSignal(str, str, object, object)  # (title, msg, on_accept, on_reject)
    mode_changed = pyqtSignal(str)  # nouveau mode

System Tray Ubuntu

Utiliser QSystemTrayIcon avec fallback si non supporté :

if QSystemTrayIcon.isSystemTrayAvailable():
    self.tray_icon = QSystemTrayIcon(QIcon.fromTheme("robot"))
    self.tray_icon.setToolTip("GeniusIA v2")
else:
    # Fallback: fenêtre normale
    self.setWindowFlags(Qt.Window)

Logs Techniques

Format structuré pour parsing facile :

2024-11-20 14:23:45.123 [INFO] EventCapture: Mouse click at (450, 320) in "Calculator"
2024-11-20 14:23:46.456 [DEBUG] SessionManager: Action added to session_001
2024-11-20 14:24:12.789 [INFO] WorkflowDetector: Pattern detected (3 repetitions)

Performance

• Logs GUI : Max 30 messages en mémoire
• Logs fichier : Rotation à 10MB
• Mise à jour GUI : Max 10 fois/seconde
• Popups : Timeout 10s pour éviter accumulation

UI/UX Considerations

Discrétion

• Fenêtre petite (300x400px)
• Minimisable
• System tray toujours visible
• Pas de sons

Clarté

• Messages courts (max 50 caractères)
• Emojis pour reconnaissance rapide
• Couleurs pour niveaux (info/success/warning/error)
• Timestamps relatifs ("il y a 2 min")

Réactivité

• Mise à jour en temps réel
• Pas de freeze
• Feedback immédiat sur actions

Migration Plan

Phase 1: Créer nouveaux composants

1. HumanLogger
2. ImprovedGUI
3. LogsPanel
4. InteractiveDialog

Phase 2: Modifier Orchestrator

1. Ajouter envoi de messages humains
2. Connecter aux signaux GUI
3. Déclencher dialogues interactifs

Phase 3: Remplacer ancienne GUI

1. Renommer minimal_gui.py → minimal_gui_old.py
2. Renommer improved_gui.py → minimal_gui.py
3. Tester

Phase 4: Cleanup

1. Supprimer anciens boutons (liste blanche, etc.)
2. Supprimer code inutilisé
3. Documentation

Security Considerations

• Logs techniques : Ne pas logger de données sensibles
• Popups : Timeout pour éviter DOS
• System tray : Vérifier permissions Ubuntu

Accessibility

• Contraste suffisant pour lisibilité
• Taille de police ajustable
• Support clavier complet
• Screen reader compatible (ARIA labels)