# AISSIA - AI Smart Schedule & Interactive Assistant

## Vue d'ensemble

Assistant personnel intelligent en C++ utilisant GroveEngine pour gérer l'hyperfocus et la gestion du temps avec hot-reload 0.4ms.

### Problème Résolu

**Symptômes identifiés** :
- **Hyperfocus** : Incapacité à stopper une tâche une fois démarrée (travail ou jeu)
- **Absence de limites** : Continuer jusqu'à épuisement physique
- **Multi-tâches impossibles** : Difficile de gérer 2-3 activités par jour
- **Régulation défaillante** : Besoin d'un système externe pour gérer les transitions

**Pattern typique** :
- Démarre tâche A à 14h
- Hyperfocus jusqu'à 3h du matin
- Épuisement physique
- Aucune autre activité possible dans la journée

### Solution

Assistant IA qui :
- Pense le planning en arrière-plan
- Intervient **proactivement** (pas juste réactif)
- S'adapte aux patterns comportementaux
- Force les transitions quand nécessaire

---

## Architecture Technique

### Stack Principal

**GroveEngine** (moteur C++ modulaire extrait de WarFactory)
- Hot-reload DLL validé : **0.4ms**
- Architecture modulaire stricte
- Types stricts C++
- Namespace : `grove::`

**Repo structure** :
```
Projets/
├── GroveEngine/          # Moteur (27 headers + 10 impls)
│   ├── include/grove/
│   │   ├── IEngine.h, IModule.h, IIO.h
│   │   ├── IDataTree.h, IDataNode.h
│   │   ├── DebugEngine.h, IntraIO.h
│   │   └── ... (factories, UI, utils)
│   ├── src/
│   │   ├── DebugEngine.cpp
│   │   ├── IntraIO.cpp, IntraIOManager.cpp
│   │   ├── ModuleFactory.cpp, EngineFactory.cpp
│   │   └── ImGuiUI.cpp, ResourceRegistry.cpp
│   ├── docs/
│   └── CMakeLists.txt
├── aissia/               # Application assistant
│   ├── .claude/settings.json  # additionalDirectories: ["../GroveEngine"]
│   ├── docs/
│   └── (modules à développer)
└── warfactoryracine/     # Source originale (non modifié)
```

### Timeline Architecture GroveEngine

| Date | Event | Impact |
|------|-------|--------|
| **20 Sept** | Suppression engines monolithiques → Interfaces modulaires | Architecture propre créée |
| **24 Sept (fc28009)** | Hot-reload validé 0.4ms | DebugEngine + IntraIO fonctionnels |
| **27 Sept (f6c3b34)** | IDataTree ajouté | Breaking change API → Implémentations supprimées |
| **27 Oct 2025** | Extraction GroveEngine | Récupération impls depuis Git history |

**État actuel** :
- ✅ Interfaces complètes (27 headers)
- ✅ Implémentations récupérées (10 .cpp)
- ⚠️ Implémentations = pre-IDataTree API (ancien format `json`, pas `IDataNode`)
- ✅ Hot-reload 0.4ms confirmé fonctionnel
- ✅ aissia configuré (Claude Code access via additionalDirectories)

---

## AI Subsystem Architecture

### API Call Management

**LLM Provider Abstraction**
```cpp
class ILLMProvider {
public:
    virtual ~ILLMProvider() = default;

    struct Message {
        std::string role;     // "user", "assistant", "system"
        std::string content;
    };

    struct CompletionRequest {
        std::vector<Message> messages;
        float temperature = 0.7f;
        int max_tokens = 1000;
        std::string model;
    };

    struct CompletionResponse {
        std::string content;
        int tokens_used;
        float cost_usd;
        bool success;
        std::string error;
    };

    virtual CompletionResponse Complete(const CompletionRequest& req) = 0;
};
```

**Implementations**
```cpp
// Claude API (Anthropic)
class ClaudeProvider : public ILLMProvider {
    std::string api_key;
    std::string endpoint = "https://api.anthropic.com/v1/messages";

    CompletionResponse Complete(const CompletionRequest& req) override;
};

// GPT API (OpenAI)
class GPTProvider : public ILLMProvider {
    std::string api_key;
    std::string endpoint = "https://api.openai.com/v1/chat/completions";

    CompletionResponse Complete(const CompletionRequest& req) override;
};

// Local LLM (Llama via llama.cpp server)
class LocalLLMProvider : public ILLMProvider {
    std::string endpoint = "http://localhost:8080/v1/chat/completions";

    CompletionResponse Complete(const CompletionRequest& req) override;
};
```

### AISubsystem Module

```cpp
class AISubsystem : public grove::IModule {
public:
    void initialize(const IDataNode& config, IIO* io) override;
    void update(float dt) override;
    void shutdown() override;

    // High-level API
    std::string AskQuestion(const std::string& question, const std::string& context);
    std::string GenerateResponse(const std::vector<Message>& conversation);

    // Context management
    void SetSystemPrompt(const std::string& prompt);
    void AddContext(const std::string& key, const std::string& value);
    void ClearContext();

private:
    std::unique_ptr<ILLMProvider> provider;
    std::string system_prompt;
    std::map<std::string, std::string> context_data;

    // Request queue (async processing)
    std::queue<CompletionRequest> pending_requests;
    std::thread worker_thread;
};
```

### HTTP Client (API Calls)

**Using libcurl (C++ wrapper)**
```cpp
class HTTPClient {
public:
    struct Request {
        std::string url;
        std::string method;  // GET, POST
        std::map<std::string, std::string> headers;
        std::string body;
    };

    struct Response {
        int status_code;
        std::string body;
        std::map<std::string, std::string> headers;
    };

    Response Send(const Request& req);

private:
    CURL* curl;
};

// Usage pour LLM API
HTTPClient client;
HTTPClient::Request req;
req.url = "https://api.anthropic.com/v1/messages";
req.method = "POST";
req.headers["x-api-key"] = api_key;
req.headers["Content-Type"] = "application/json";
req.body = R"({
    "model": "claude-3-5-sonnet-20241022",
    "messages": [{"role": "user", "content": "Hello!"}],
    "max_tokens": 1024
})";

auto response = client.Send(req);
```

### Async Processing (Non-blocking)

```cpp
void AISubsystem::update(float dt) {
    // Process pending requests asynchronously
    if (!pending_requests.empty() && !worker_thread.joinable()) {
        auto request = pending_requests.front();
        pending_requests.pop();

        worker_thread = std::thread([this, request]() {
            auto response = provider->Complete(request);

            // Send response via IIO to other modules
            io->SendMessage("ai_response", response.content);
        });
    }

    // Cleanup finished threads
    if (worker_thread.joinable()) {
        worker_thread.join();
    }
}
```

### Configuration

**Config file : `aissia_ai_config.json`**
```json
{
  "ai_subsystem": {
    "provider": "claude",
    "api_key_env": "ANTHROPIC_API_KEY",
    "model": "claude-3-5-sonnet-20241022",
    "default_temperature": 0.7,
    "max_tokens": 1000,
    "system_prompt": "You are AISSIA, an AI assistant helping manage hyperfocus and time management.",
    "timeout_seconds": 30,
    "retry_attempts": 3
  },
  "providers": {
    "claude": {
      "endpoint": "https://api.anthropic.com/v1/messages",
      "cost_per_1k_input": 0.003,
      "cost_per_1k_output": 0.015
    },
    "gpt": {
      "endpoint": "https://api.openai.com/v1/chat/completions",
      "cost_per_1k_input": 0.00015,
      "cost_per_1k_output": 0.0006
    },
    "local": {
      "endpoint": "http://localhost:8080/v1/chat/completions",
      "cost_per_1k_input": 0.0,
      "cost_per_1k_output": 0.0
    }
  }
}
```

### TTS/STT (Bonus)

**Text-to-Speech Options**
```cpp
class ITTSProvider {
public:
    virtual void Speak(const std::string& text) = 0;
};

// Windows SAPI (already documented in daily check system)
class WindowsSAPIProvider : public ITTSProvider {
    void Speak(const std::string& text) override {
        // Use SAPI COM interface
        // See: anki_tingting/CLAUDE.md for implementation
    }
};

// ElevenLabs API (cloud, high quality)
class ElevenLabsProvider : public ITTSProvider {
    void Speak(const std::string& text) override;
};
```

**Speech-to-Text Options**
```cpp
class ISTTProvider {
public:
    virtual std::string Transcribe(const std::vector<uint8_t>& audio_data) = 0;
};

// Whisper API (OpenAI)
class WhisperProvider : public ISTTProvider {
    std::string Transcribe(const std::vector<uint8_t>& audio_data) override;
};
```

---

## Modules AISSIA Prévus

Architecture modulaire GroveEngine :

```cpp
// Chaque module = ~200-300 lignes
class MonitoringModule : public grove::IModule {
    // Surveillance apps actives
    // Tracking temps réel
    // Détection hyperfocus
};

class SchedulerModule : public grove::IModule {
    // Planning intelligent
    // Gestion priorités
    // Estimation durées
};

class AIAssistantModule : public grove::IModule {
    // Génération interventions LLM
    // Analyse contexte
    // Décisions proactives
};

class NotificationModule : public grove::IModule {
    // TTS
    // Notifications système
    // Rappels
};

class DataModule : public grove::IModule {
    // SQLite storage
    // Métriques
    // Analytics
};

class VoiceModule : public grove::IModule {
    // Speech-to-text (optionnel)
    // Text-to-speech
};

class UIModule : public grove::IModule {
    // ImGui interface
    // Dashboard
    // Settings
};
```

---

## Roadmap Développement

### Phase 1 - MVP Local Windows (Semaines 1-2)

**Obligatoire** - Validation concept

**Stack** :
- `aissia-core.exe` (GroveEngine DebugEngine)
- Modules DLL (hot-reload 0.4ms)
- ImGui pour UI
- SQLite local
- **Coût : $0**
- **Privacy : 100% local**

**Fonctionnalités** :
- ✅ Gestion tâches : Création, priorités, durées, deadlines
- ✅ Tracking temps : Timer manuel, historique
- ✅ IA basique : Suggestions planning, réorganisation, estimations
- ✅ Notifications : Rappels début/fin tâches

**Livrables** :
- MonitoringModule (tracking apps Windows)
- SchedulerModule (planning basique)
- AIAssistantModule (LLM suggestions)
- NotificationModule (système + TTS)
- UIModule (ImGui dashboard)

### Phase 2 - IA Proactive (Semaines 3-4)

**Optionnel** - Intelligence avancée

**Fonctionnalités** :
- ⏳ Détection hyperfocus : Analyse temps vs planifié, patterns anormaux
- ⏳ Assistant conversationnel : Chat avec l'IA
- ⏳ Apprentissage patterns : Heures productives, activités dangereuses
- ⏳ Interventions : Blocage apps, breaks forcés, réorganisation auto

**Questions techniques non résolues** :
1. **LLM choice** : Claude API (cher) vs GPT-4o mini (cheap) vs Local Llama (gratuit mais moins bon) ?
2. **Blocage apps** : Kill process forcé ou juste notifs agressives ?
3. **Antivirus** : Monitoring Windows apps = risque flag keylogger/spyware, acceptable ?

### Phase 3 - POC WASM (Semaine 5+)

**Expérimental** - Validation portabilité

**Objectif** : Tester si modules C++ compilent en WebAssembly

**Si succès** :
```
MÊME code C++ → 3 formats possibles :
├─ monitoring.dll   (Dev Windows + hot-reload 0.4ms)
├─ monitoring.so    (Serveur Linux Docker)
└─ monitoring.wasm  (Browser PWA)
```

### Phase 4 - Cloud PWA (Conditionnel)

**Optionnel** - Seulement si Phase 3 validée

**Stack** :
- React PWA frontend
- Modules WASM côté client (70% processing)
- Backend Docker Linux (30% processing)
- PostgreSQL
- **Coût : $3-5/mois**

**Fonctionnalités supplémentaires** :
- 🔮 Intelligence contextuelle : Détection auto activité
- 🔮 Intégrations : Google Calendar, Todoist, RescueTime
- 🔮 Gamification : Points, streaks, achievements
- 🔮 Analytics : Rapports, visualisations, insights

---

## Avantages Architecture

| Aspect | Bénéfice |
|--------|----------|
| **Hot-reload 0.4ms** | Itération ultra-rapide en dev (validé WarFactory) |
| **Types stricts C++** | Pas de wildcode, compilation catch erreurs |
| **Modularité** | Modules 200-300 lignes, développement parallèle |
| **Évolution progressive** | Commence local $0, décide cloud plus tard |
| **Privacy-first** | Mode local = données jamais uploadées |
| **Réutilisation WarFactory** | Économie 3-4 semaines dev (architecture déjà prouvée) |

---

## Problèmes Techniques Identifiés

### 1. API Mismatch (IDataTree)

**Situation** :
- Implémentations récupérées = pre-IDataTree (utilisent `nlohmann::json`)
- Interfaces actuelles = post-IDataTree (utilisent `IDataNode`)

**Options** :
- **A)** Utiliser implémentations telles quelles pour MVP (ignorer IDataTree temporairement)
- **B)** Adapter implémentations pour IDataTree avant démarrage
- **C)** Créer wrapper `json ↔ IDataNode` temporaire

**Recommandation** : Option A pour MVP, refactor plus tard si nécessaire

### 2. Monitoring Windows Apps

**Technique** :
```cpp
// Win32 API pour tracking app active
HWND hwnd = GetForegroundWindow();
GetWindowThreadProcessId(hwnd, &processId);
// → Obtenir nom app, temps d'utilisation
```

**Problèmes** :
- Nécessite permissions admin potentiellement
- Antivirus peuvent flag comme malware (comportement keylogger)
- Privacy concerns si données non chiffrées

**Mitigation** :
- Chiffrement SQLite local
- Signature code (codesigning certificate)
- Disclaimer explicite utilisateur

### 3. LLM Integration

**Choix non fait** :

| Option | Coût | Qualité | Privacy | Latence |
|--------|------|---------|---------|---------|
| **Claude API** | $$$ | Excellent | ❌ Cloud | 1-3s |
| **GPT-4o mini** | $ | Bon | ❌ Cloud | 0.5-1s |
| **Llama 3.2 local** | $0 | Moyen | ✅ Local | 2-5s (CPU) |

**Décision requise** avant Phase 2.

---

## Statut Actuel

### GroveEngine
- ✅ Repo créé et structuré
- ✅ 27 headers copiés
- ✅ 10 implémentations récupérées (Git history)
- ✅ Documentation complète
- ✅ CMakeLists.txt configuré
- ⏳ Build test à faire (vérifier compilation)

### aissia
- ✅ Repo cloné depuis Bitbucket
- ✅ Nettoyé (supprimé artefacts C#)
- ✅ Claude Code configuré (additionalDirectories)
- ✅ Documentation adaptée
- ⏳ Aucun module développé encore

### Prochaines Étapes

**Immédiat** :
1. ✅ Build test GroveEngine (vérifier que ça compile)
2. ⏳ Créer `aissia-core.exe` (DebugEngine wrapper)
3. ⏳ Développer AISubsystem (LLM API calls + management)
4. ⏳ Valider hot-reload 0.4ms avec module AISSIA

**Base Running Requirements** :
- ✅ GroveEngine integrated
- ⏳ LLM API subsystem (Claude/GPT calls)
- ⏳ AI subsystem management (context, prompts, responses)
- 🎁 Bonus: TTS/STT APIs (optionnel)

**Questions bloquantes** :
- LLM choice pour AIAssistantModule ?
- Niveau d'intervention acceptable (kill process ou juste notifs) ?
- Budget acceptable pour APIs cloud (si non-local) ?

---

## Lien avec Autres Projets

### Contexte Global (4 projets)

1. **Social Network Manager** : Automation réseaux sociaux (suspendu - ToS issues)
2. **MP3 → TXT** : Extraction texte cours chinois (documenté, prêt)
3. **AISSIA** : Assistant anti-hyperfocus (ce document)
4. **Modif WarFactory** : (non encore détaillé)

**Impact combiné** : "Changement macro massif" dans workflow personnel
- Network manager = présence online automatique
- MP3 extractor = apprentissage chinois optimisé
- AISSIA = gestion temps/focus améliorée + **apprentissage langues intégré**
- WarFactory modif = ?

---

## Cas d'Usage : Apprentissage Chinois

### Contexte (28 octobre 2025)

**Problème identifié** :
- Système de cours actuel ne convient pas à Alexis
- Besoin de **pression + accountability personnalisée** (comme études japonais)
- Tingting concernée par manque de progression

**Solution multi-vecteur** :

#### 1. Prof Chinois (Priorité 1)
- **Format** : Prof privé 1-on-1 avec accountability forte
- **Fréquence** : X heures/semaine (à définir)
- **Plateforme** : Italki / Preply / Local Shanghai (à décider)
- **Timeline** : Recherche cette semaine, début sous 7-10 jours
- **Objectif** : Recréer système pression qui fonctionnait pour japonais

#### 2. Aissia - LanguageLearningModule (Support technique)
- **Fonctionnalités** :
  - Détection apps d'apprentissage (tracking temps pratique)
  - Conversations en chinois avec IA (practice quotidienne)
  - Corrections intelligentes en temps réel
  - Dialogues bilingues (intégration AIAssistantModule)
- **Timeline** : MVP Phase 1 (après MonitoringModule/SchedulerModule)
- **Objectif** : Consistency entre sessions prof + practice automatisée

**Complémentarité** :
- Prof = accountability humaine + pression personnalisée
- Aissia = consistency quotidienne + gestion hyperfocus sur pratique
- Ensemble = système complet apprentissage structuré

**Prochaines actions (semaine du 28 octobre)** :
1. ⏳ Rechercher prof chinois (3-4h max)
2. ⏳ Définir budget + fréquence + format
3. ⏳ Booker première session
4. ⏳ Développer LanguageLearningModule (parallèle au dev MVP)

**Lien** : Voir `couple_backlog/28_octobre_2025.md` pour contexte discussion

---

## Décisions en Attente

### Techniques
1. ⚠️ LLM provider (Claude / GPT-4o mini / Local Llama)
2. ⚠️ Niveau intervention (kill apps ou notifs only)
3. ⚠️ Handling antivirus flags (codesigning ?)
4. ⚠️ API mismatch strategy (use old impls vs adapt to IDataTree)

### Produit
1. ⚠️ MVP scope exact (quelles features minimum ?)
2. ⚠️ Cloud PWA nécessaire ou local suffit ?
3. ⚠️ Gamification importante ou distraction ?

### Business
1. ⚠️ Side project perso uniquement ou intention monétiser ?
2. ⚠️ Budget mensuel acceptable APIs cloud ?

---

## Risques Identifiés

| Risque | Probabilité | Impact | Mitigation |
|--------|-------------|--------|------------|
| **Antivirus false positive** | Élevée | Bloquant | Codesigning certificate (~$100/an) |
| **Hot-reload pas stable AISSIA** | Faible | Moyen | Déjà validé WarFactory, même code |
| **LLM trop cher en usage réel** | Moyenne | Moyen | Commencer local Llama, migrer si besoin |
| **Hyperfocus sur dev AISSIA** | Élevée | Ironique | Meta-utiliser AISSIA pour dev AISSIA 😄 |
| **WASM compilation fail** | Moyenne | Faible | Phase 3 optionnelle, pas bloquant |

---

## Ressources

### Repos
- `Projets/GroveEngine/` : Moteur C++ modulaire
- `Projets/aissia/` : Application assistant
- `Projets/warfactoryracine/` : Source originale

### Documentation
- `GroveEngine/docs/architecture-modulaire.md` : Explication interfaces
- `GroveEngine/docs/claude-code-integration.md` : Workflow dev
- `GroveEngine/docs/CLAUDE-HOT-RELOAD-GUIDE.md` : Guide hot-reload 0.4ms
- `aissia/docs/architecture/architecture-technique.md` : Architecture adaptée AISSIA

### Commits Clés (WarFactory history)
- `fc28009` : Hot-reload validé 0.4ms
- `fb49fb2` : IntraIO implementation
- `f6c3b34` : IDataTree ajouté (breaking change)

---

*Créé : 27 octobre 2025*
*Statut : En conception - GroveEngine prêt, modules AISSIA à développer*
*Stack : C++17, GroveEngine, ImGui, SQLite, LLM (TBD)*