# Модуль 5: горячие клавиши + машина состояний + память

Сердце ассистента: сшивает STT (М1), brain (М4), TTS (М3), аудио (М2)
в цельную программу с тремя способами управления.

## Управление (три режима)

| Режим | Как управлять | Где использовать |
|---|---|---|
| **Свободный** (`test_free.py`) | просто говори; пауза 2 с = фраза окончена (Silero-VAD) | целевой для отца |
| **Клавиши-консоль** (`test_assistant.py`) | Enter/s/r/q (имитация) | разработка в Linux |
| **Глобальные клавиши** (`--backend keys`) | space/esc/enter из любого окна | Windows-сборка |

## Машина состояний

```
idle ─▶ listening ─▶ thinking ─▶ speaking ─▶ idle
  ▲         │            │           │
  └─────────┴────────────┴───────────┘  («Замолчи» из любого)
```

- Говорит, а отец начал говорить → речь мгновенно стихает, новая фраза обрабатывается.
- «Замолчи» гасит речь/отменяет запись/отбрасывает «думание» (счётчик поколений:
  устаревшие ответы никогда не прозвучат).
- «Повтори» — последняя фраза (в idle).

## Долговременная память (data/memory.md)

- Слово прощания («до свидания», «прощай», «пока»…) → мгновенный прощальный ответ +
  фоновым запросом модель формулирует конспект разговора → дописывается в файл.
- При старте конспект вшивается в системный промпт — ассистент «помнит» прошлые разговоры.
- Файл — обычный текст с датами, можно править руками; при переполнении (>8000 симв.)
  старые записи сжимаются автоматически.
- Память не критична к сбоям: ошибка сети при конспекте просто логируется.

## Файлы

| Файл | Назначение |
|---|---|
| `modules/hotkeys/` | бэкенды клавиш: `console.py` (Linux), `keyboard_hook.py` (Windows), общий контракт `KeyEvents` |
| `modules/assistant/assistant.py` | машина состояний, конвейер STT→LLM→TTS, перебивание |
| `modules/assistant/memory.py` | файл-конспект между сессиями |
| `modules/assistant/farewell.py` | детект прощания + саммари диалога |
| `modules/audio_io/handsfree.py` | свободный режим: Silero-VAD в потоке, конец фразы по паузе |
| `test_assistant.py` | клавиши-консоль / глобальные клавиши |
| `test_free.py` | свободный режим (говори без кнопок) |

## Запуск

```bash
# свободный режим (целевой):
.venv/bin/python modules/assistant/test_free.py
.venv/bin/python modules/assistant/test_free.py --silence 2.5   # подольше пауза

# клавишный режим (Linux-разработка):
.venv/bin/python modules/assistant/test_assistant.py
```

Клавиши Windows-сборки настраиваются в .env: `HOTKEY_TALK/HOTKEY_STOP/HOTKEY_REPEAT`.

## Критерии приёмки — статус

1. ✅ Обычный цикл (живой тест юзером, 2026-09-11).
2. ✅ Контекст диалога внутри сессии.
3. ✅ «Замолчи» мгновенно; перебивание речи новым вопросом.
4. ✅ «Повтори».
5. ✅ Память между сессиями (мок-тест); живой тест двух запусков — на юзере.
6. 🟡 Свободный режим VAD — код готов, живой тест после установки silero-vad (CPU-torch).

## Известные детали

- Silero-VAD требует torch; для разработки ставим CPU-вариант (~200 МБ):
  `pip install --index-url https://download.pytorch.org/whl/cpu torch silero-vad`.
  В Windows-сборке заменим на ONNX-детектор (2 МБ, без torch).
- suppress-механизм: на время ответа микрофон глушится, чтобы не слышать саму себя;
  при перебивании отцом suppress снимается мгновенно.