aissia/README.md

# AISSIA - AI Smart Schedule & Interactive Assistant

**AISSIA** is an intelligent personal assistant for time management, hyperfocus detection, and language learning, powered by **GroveEngine**.

## What is AISSIA?

AISSIA helps manage:
- **Hyperfocus**: Detects when you've been working too long and need a break
- **Time Management**: Intelligent scheduling and task planning
- **Language Learning**: Interactive practice in target languages
- **Notifications**: Context-aware alerts with TTS support

## Built on GroveEngine

AISSIA leverages **GroveEngine**, a C++17 hot-reload module system that enables:

- **Hot-Reload**: Modify code at runtime without losing state (<1ms reload latency)
- **Modular Architecture**: Self-contained modules (200-300 lines each)
- **Pub/Sub Communication**: Decoupled inter-module messaging
- **State Preservation**: Automatic state serialization across reloads
- **Configuration Hot-Reload**: Update settings without code changes

### Why GroveEngine?

✅ **Ultra-fast Development**: Hot-reload validated at 0.4ms
✅ **Type Safety**: Strong C++ typing, no "wildcode"
✅ **Proven Architecture**: Production-ready module system
✅ **Privacy-First**: Local mode, data never uploaded
✅ **Progressive Evolution**: MVP → Production → Cloud without rewrite

## Project Structure

```
Aissia/
├── external/
│   └── GroveEngine/          # GroveEngine (symlink)
├── src/
│   ├── main.cpp              # Main application loop
│   └── modules/
│       ├── SchedulerModule.*       # Time management & hyperfocus
│       ├── NotificationModule.*    # Alerts & TTS
│       ├── AIAssistantModule.*     # (TODO) LLM integration
│       ├── LanguageLearningModule.* # (TODO) Language practice
│       └── DataModule.*            # (TODO) SQLite persistence
├── config/
│   ├── scheduler.json
│   └── notification.json
├── docs/
│   ├── README.md                   # Project documentation
│   └── GROVEENGINE_GUIDE.md        # GroveEngine user guide
└── CMakeLists.txt
```

## Modules

### Implemented

**SchedulerModule**: Time management and hyperfocus detection
- Tracks work sessions and break intervals
- Detects hyperfocus based on configurable threshold (default: 120 minutes)
- Reminds for breaks (default: every 45 minutes)
- Task estimation and tracking

**NotificationModule**: System alerts with priority levels
- Priority-based notifications (LOW, NORMAL, HIGH, URGENT)
- Silent mode (respects URGENT priority)
- TTS support (configurable)
- Multilingual support (fr/en/jp)
- Queue management with rate limiting

### Planned

**AIAssistantModule**: LLM-powered contextual interventions
- Claude API integration
- Context-aware suggestions
- Intelligent document retrieval

**LanguageLearningModule**: Language practice and learning
- Conversation in target language
- Vocabulary tracking
- Progress monitoring

**DataModule**: SQLite persistence
- Task history
- Session analytics
- Configuration backup

## Getting Started

### Prerequisites

- CMake 3.20+
- C++17 compiler (GCC/Clang)
- GroveEngine (included via symlink)

### Build

```bash
# Configure
cmake -B build

# Build everything
cmake --build build -j4

# Build modules only (for hot-reload workflow)
cmake --build build --target modules
```

### Run

```bash
# Interactive mode (requires ANTHROPIC_API_KEY in .env)
./run.sh

# Or manually with .env loaded
source .env && ./build/aissia -i

# MCP Server mode (for Claude Code integration)
./build/aissia --mcp-server

# Normal mode (background daemon)
./build/aissia
```

**Note**: Create a `.env` file with your API key:
```bash
ANTHROPIC_API_KEY=sk-ant-...
```

### Hot-Reload Workflow

1. Start AISSIA: `./build/aissia`
2. Edit a module: `src/modules/SchedulerModule.cpp`
3. Rebuild: `cmake --build build --target modules`
4. **Module reloads automatically with state preserved**

### Configuration

Configuration files in `config/`:

**scheduler.json**:
```json
{
    "hyperfocusThresholdMinutes": 120,
    "breakReminderIntervalMinutes": 45,
    "breakDurationMinutes": 10,
    "workdayStartHour": 9,
    "workdayEndHour": 18
}
```

**notification.json**:
```json
{
    "language": "fr",
    "silentMode": false,
    "ttsEnabled": false,
    "maxQueueSize": 50
}
```

## Documentation

- **[docs/README.md](docs/README.md)**: Project documentation and architecture
- **[docs/GROVEENGINE_GUIDE.md](docs/GROVEENGINE_GUIDE.md)**: Complete GroveEngine user guide
- **[CDCDraft.md](CDCDraft.md)**: Detailed requirements specification (French)

## Development Philosophy

### MVP-First

- **Phase 1 (Required)**: Local Windows mode only
- **Phase 2+ (Optional)**: Cloud features if needed
- **Configuration-Driven**: 90% of needs via JSON
- **Simplicity First**: Complexity emerges from interaction

### Module Development

Each module is a self-contained unit (~200-300 lines):

1. Implements `IModule` interface
2. Pure business logic (no infrastructure code)
3. Communicates via `IIO` pub/sub
4. Serializes state for hot-reload
5. Configurable via `IDataNode`

See `docs/GROVEENGINE_GUIDE.md` for detailed module development guide.

## Architecture

AISSIA runs on a simple loop (10Hz for assistant workload):

```
┌─────────────────────────────────────────────┐
│           Main Loop (10Hz)                   │
│                                              │
│  ┌────────────────────────────────────┐    │
│  │  1. Check for module file changes   │    │
│  │  2. Hot-reload if modified          │    │
│  │  3. Process all modules             │    │
│  │  4. Route inter-module messages     │    │
│  │  5. Sleep to maintain 10Hz          │    │
│  └────────────────────────────────────┘    │
└─────────────────────────────────────────────┘
```

Modules communicate via topics:
- `scheduler:hyperfocus_detected` → NotificationModule alerts user
- `notification:alert_sent` → DataModule logs event
- `aiassistant:suggestion` → NotificationModule displays suggestion

## Technical Stack

- **Core**: C++17
- **Module System**: GroveEngine
- **Logging**: spdlog
- **Data Format**: JSON (nlohmann/json)
- **Build**: CMake 3.20+
- **Future**: SQLite (DataModule), Claude API (AIAssistantModule)

## Roadmap

### Completed ✅
- [x] Project setup with GroveEngine
- [x] SchedulerModule (time management & hyperfocus)
- [x] NotificationModule (alerts & TTS)
- [x] MonitoringModule (app tracking & classification)
- [x] AIModule (LLM conversation & suggestions)
- [x] VoiceModule (TTS/STT interfaces)
- [x] StorageModule (SQLite persistence)
- [x] WebModule (HTTP requests via IIO pub/sub)
- [x] LLM Service (Claude API integration - Sonnet 4)
- [x] 17 Agentic Tools (filesystem, scheduler, storage, etc.)
- [x] MCP Server mode (JSON-RPC stdio)
- [x] Interactive mode (--interactive)
- [x] **110/110 unit tests passing**
- [x] **13/13 integration tests implemented**
- [x] **TTS integration (espeak-ng)** ✨ NEW
- [x] **Interactive mode validated with real queries** ✨ NEW

### In Progress 🚧
- [ ] Expose InternalTools via MCP Server
- [ ] Fix integration tests (requires modules loaded + API key)

### Planned 📋
- [ ] Windows Toast notifications
- [ ] STT integration (Whisper API)
- [ ] Language learning features

## License

To be determined

## Links

- **GroveEngine**: [../GroveEngine](../GroveEngine)
- **Claude Code**: https://docs.claude.com/en/docs/claude-code