aissia/docs/SUCCESSION.md

Document de Succession - AISSIA

Contexte

AISSIA = Assistant vocal agentique basé sur GroveEngine (C++17 hot-reload). Architecture "Claude Code en vocal" avec tools internes + FileSystem + MCP.

Dernier commit : 37b62b5

État Actuel

Ce qui fonctionne

✅ Build complet - cmake -B build && cmake --build build -j4 ✅ 6 modules hot-reload - Scheduler, Notification, Monitoring, AI, Voice, Storage ✅ 4 services - LLMService, StorageService, PlatformService, VoiceService ✅ 17 tools pour l'agent :

• 11 tools internes (via IIO pub/sub)
• 6 FileSystem tools (read/write/edit/list/glob/grep)
• MCP tools (désactivés par défaut) ✅ Tests - 67/75 tests modules+types passent

Lancement

# Build
cmake -B build && cmake --build build -j4

# Run (depuis racine ou build/)
./build/aissia

# Mode MCP Server (expose les tools via JSON-RPC stdio)
./build/aissia --mcp-server

# Tests
cmake -B build -DBUILD_TESTING=ON
./build/tests/aissia_tests "[scheduler],[notification]"  # Modules
./build/tests/aissia_tests "[types]"                      # MCP types

Variables d'Environnement

export ANTHROPIC_API_KEY="sk-ant-..."   # Requis pour Claude API

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     LLMService                               │
│                   (Agentic Loop)                             │
├─────────────────────────────────────────────────────────────┤
│  ToolRegistry                                                │
│  ├── InternalTools (11) ─────► IIO pub/sub                  │
│  ├── FileSystemTools (6) ────► Direct C++ (read/write/edit) │
│  └── MCPClient (optionnel) ──► stdio JSON-RPC               │
└─────────────────────────────────────────────────────────────┘
                              │
         ┌──────────────┬─────┴──────┬──────────────┐
    Scheduler      Monitoring    Storage        Voice
     Module          Module       Module        Module

Tools Disponibles

Catégorie	Tools	Communication
Scheduler	get_current_task, list_tasks, start_task, complete_task, start_break	IIO
Monitoring	get_focus_stats, get_current_app	IIO
Storage	save_note, query_notes, get_session_history	IIO
Voice	speak	IIO
FileSystem	read_file, write_file, edit_file, list_directory, glob_files, grep_files	Direct C++

FileSystem Tools (Nouveau)

Implémentés dans src/shared/tools/FileSystemTools.* :

// Lecture avec numéros de ligne
FileSystemTools::execute("read_file", {{"path", "/path/to/file"}, {"limit", 10}});

// Édition style Claude Code
FileSystemTools::execute("edit_file", {
    {"path", "/path/to/file"},
    {"old_string", "foo"},
    {"new_string", "bar"}
});

// Recherche
FileSystemTools::execute("glob_files", {{"pattern", "**/*.cpp"}});
FileSystemTools::execute("grep_files", {{"pattern", "TODO"}, {"path", "./src"}});

Sécurité :

• Chemins autorisés configurables
• Patterns bloqués : *.env, *.key, *credentials*
• Limites : 1MB lecture, 10MB écriture

Fichiers Clés

Nouveaux (Session actuelle)

src/shared/tools/FileSystemTools.hpp
src/shared/tools/FileSystemTools.cpp
PLAN_FILESYSTEM_TOOLS.md

Services

src/services/LLMService.*      # Agentic loop, tools registry
src/services/StorageService.*  # SQLite persistence
src/services/PlatformService.* # Window tracking
src/services/VoiceService.*    # TTS/STT

Modules (Hot-Reload)

src/modules/SchedulerModule.*
src/modules/NotificationModule.*
src/modules/MonitoringModule.*
src/modules/AIModule.*
src/modules/VoiceModule.*
src/modules/StorageModule.*

MCP

src/shared/mcp/MCPTypes.hpp
src/shared/mcp/MCPClient.*      # Client MCP (consomme des serveurs externes)
src/shared/mcp/MCPServer.*      # Serveur MCP (expose AISSIA comme serveur)
src/shared/mcp/StdioTransport.*
config/mcp.json

Tests

# Build avec tests
cmake -B build -DBUILD_TESTING=ON && cmake --build build -j4

# Par catégorie
./build/tests/aissia_tests "[scheduler]"      # 10 tests
./build/tests/aissia_tests "[notification]"   # 10 tests
./build/tests/aissia_tests "[types]"          # 15 tests MCP

# Tous les modules
./build/tests/aissia_tests "[scheduler],[notification],[monitoring],[ai],[voice],[storage]"

Résultats actuels :

• Modules : 52/60 (87%)
• MCP Types : 15/15 (100%)
• MCP Transport/Client : Nécessite fix serveurs Python

Prochaines Étapes

Priorité Haute

1. Tester avec API key - Vérifier la boucle agentique complète
2. Activer MCP filesystem - Pour tests end-to-end avec tools externes

Priorité Moyenne

3. Fixer tests MCP Transport - Les serveurs Python reçoivent EOF
4. Ajouter plus de tools - add_task, set_reminder, etc.
5. Streaming responses - Feedback temps réel pendant génération

Priorité Basse

6. Tests end-to-end - Flux complet inter-modules
7. CI/CD - GitHub Actions
8. Documentation API - Doxygen

MCP Server Mode

AISSIA peut fonctionner comme serveur MCP, exposant ses tools à des clients externes via JSON-RPC sur stdio.

./build/aissia --mcp-server

Protocole

Communication JSON-RPC 2.0 sur stdin/stdout :

// Client → AISSIA
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"clientInfo":{"name":"client","version":"1.0"}}}

// AISSIA → Client
{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","serverInfo":{"name":"aissia","version":"0.2.0"},...}}

// Lister les tools
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

// Appeler un tool
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_directory","arguments":{"path":"."}}}

Utilisation avec Claude Code

Ajouter dans la config MCP :

{
  "servers": {
    "aissia": {
      "command": "/chemin/vers/build/aissia",
      "args": ["--mcp-server"]
    }
  }
}

Tools Exposés (actuellement)

6 FileSystem tools. TODO: exposer les tools internes (scheduler, voice, etc.).

Notes Techniques

WSL

• Window tracker non disponible (stub utilisé)
• espeak non installé (TTS stub)
• Tout le reste fonctionne

Hot-Reload

Les modules sont des .so chargés dynamiquement. Pour recompiler un module :

cmake --build build --target SchedulerModule
# Le module sera rechargé au prochain cycle si modifié