# Cosmo Voice Satellite

Голосовой ассистент дома — аналог Алисы через OpenClaw. Два агента: **Cosmo** (владельца) и **Люся** (жены). Каждый активируется своим wake word и идёт на свой OpenClaw gateway.

## Архитектура

```
┌─────────────┐  wake word   ┌──────────────┐   STT (Groq)
│ Microphone  │ ───────────► │   Satellite  │ ──────────────►
└─────────────┘              └──────────────┘                  │
                                    │                           ▼
                                    │                    ┌──────────────┐
                                    │                    │  OpenClaw    │
                                    │                    │  Gateway     │
                                    │                    │  (N100 PC)   │
                                    │    stream response └──────────────┘
                                    ▼                           │
                             ┌──────────────┐                   │
                             │  ElevenLabs  │ ◄─────────────────┘
                             │     TTS      │
                             └──────────────┘
                                    │
                                    ▼  mp3 stream
                             ┌──────────────┐
                             │     mpv      │ → speakers (BT)
                             └──────────────┘
```

## Инфраструктура

- **Сервер**: N100 Mini-PC, `192.168.31.103`, Proxmox
- **Cosmo Gateway**: порт `18789`, агент `openclaw/main`
- **Люся Gateway**: порт `18790`, агент `openclaw/wife`
- **Модель**: `openai/gpt-5.4-mini` (через `x-openclaw-model` header)
- **STT**: Groq API, `whisper-large-v3-turbo`, язык ru
- **TTS**: ElevenLabs, `eleven_flash_v2_5` (~75ms латентность)
- **Wake word**: Porcupine (на Pi), Enter (при разработке)

## Структура проекта

```
home-voice-assistant/
├── .env                 # секреты (не в git)
├── .env.example         # шаблон
├── requirements.txt
├── satellite.py         # обёртка для запуска
├── satellite/
│   ├── __init__.py
│   ├── __main__.py      # entry: python -m satellite [--wake]
│   ├── config.py        # env, AGENTS dict, keep-alive sessions
│   ├── text.py          # clean_for_speech, find_sentence_end
│   ├── stt.py           # transcribe (Groq, BytesIO, без temp файла)
│   ├── audio.py         # record, record_with_timeout (VAD)
│   ├── tts.py           # ElevenLabs streaming через mpv, barge-in
│   ├── llm.py           # ask_agent_stream, Conversation (history)
│   └── modes.py         # run_with_enter, run_with_porcupine
└── deploy/
    ├── setup.sh               # установка на Raspberry Pi
    └── cosmo-satellite.service  # systemd unit
```

## Что важно знать

### Сессии диалога
- **Одна сессия на день** для каждого агента. Это осознанное решение: каждая новая сессия в OpenClaw тяжёлая (чтение памяти, большой контекст).
- История хранится в `Conversation.messages[]` на клиенте и отправляется целиком с каждым запросом (stateless к серверу).
- Сброс сессии: фраза "начни новую сессию" / "сбрось историю" / "очисти контекст" — паттерны в `RESET_PATTERNS` в `llm.py`.
- Автосброс при смене даты (`Conversation.is_expired()`).
- `MAX_HISTORY=20` — лимит сообщений, чтобы не раздувать контекст.

### Оптимизации скорости (все уже внедрены)
1. **Keep-alive HTTP сессии** (`requests.Session()`) — в `config.py._make_session()`, переиспользуется TCP/TLS.
2. **Streaming TTS** — ElevenLabs аудио пайпится в `mpv` через stdin, играет пока генерируется.
3. **STT без диска** — PCM → WAV в `BytesIO` → Groq, без temp файлов.
4. **Barge-in** — `stop_speaking()` вызывается при каждой активации, убивает текущий mpv процесс.

### Роутинг по wake word
В `modes.py::run_with_porcupine` Porcupine грузит оба wake word:
- index 0 = Cosmo → `AGENTS["cosmo"]` (:18789)
- index 1 = Люся → `AGENTS["lusya"]` (:18790)

Каждый агент имеет свой `tts_voice` в ElevenLabs.

### Ошибки не должны ронять сервис
Каждый слой (stt, tts, llm, audio, modes) ловит `Exception` и пишет в `errors.log` через `config.log`. Верхний уровень в modes.py ловит всё непредвиденное и продолжает цикл.

## Запуск

### macOS / Windows (разработка)
```bash
python -m venv .venv
# macOS/Linux: source .venv/bin/activate
# Windows:     .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env  # заполнить ключи

python satellite.py           # режим Enter (без wake word)
python satellite.py --wake    # режим Porcupine (нужны .ppn + PORCUPINE_KEY)
```

### Raspberry Pi (продакшн)
```bash
sudo bash deploy/setup.sh
# далее:
sudo systemctl start cosmo-satellite
sudo journalctl -u cosmo-satellite -f
```

## Зависимости системы

- **Python 3.12+**
- **portaudio** — для `pyaudio` (`brew install portaudio` / `apt install portaudio19-dev`)
- **mpv** — для воспроизведения TTS (`brew install mpv` / `apt install mpv`)
- **ffmpeg** — опционально, для совместимости форматов

### Windows
- Python 3.12+ с pip
- `pip install pyaudio` — обычно работает через колеса pipwin или pre-built wheels. Если нет — `pip install pipwin && pipwin install pyaudio`
- mpv: скачать с [mpv.io](https://mpv.io/installation/), положить `mpv.exe` в PATH
- Porcupine работает и на Windows — wake word модель нужна под платформу windows (качать отдельную `.ppn`)

## Переменные окружения

Все в `.env`. Ключевые:

| Переменная | Что |
|-----------|-----|
| `GATEWAY_URL`, `LUSYA_GATEWAY_URL` | URL OpenClaw gateway на N100 |
| `GATEWAY_TOKEN`, `LUSYA_GATEWAY_TOKEN` | Токены авторизации |
| `AGENT`, `LUSYA_AGENT` | Имя агента в OpenClaw (`openclaw/main`, `openclaw/wife`) |
| `VOICE_MODEL`, `LUSYA_VOICE_MODEL` | Модель LLM для голоса |
| `GROQ_API_KEY` | Groq для STT |
| `ELEVENLABS_API_KEY` | ElevenLabs TTS |
| `COSMO_TTS_VOICE`, `LUSYA_TTS_VOICE` | Voice ID в ElevenLabs |
| `ELEVENLABS_MODEL` | `eleven_flash_v2_5` (быстрый) |
| `AUDIO_SINK` | На Pi: `bluez_sink.XX_XX_XX.a2dp_sink`. На Mac/Win: пусто. |
| `PORCUPINE_KEY`, `WAKE_WORD_COSMO`, `WAKE_WORD_LUSYA` | Только для `--wake` режима |
| `SILENCE_THRESHOLD=500` | VAD: чувствительность (ниже = ловит тихую речь) |
| `SILENCE_DURATION=1.5` | Сек тишины = конец фразы |
| `FOLLOWUP_TIMEOUT=8` | Сек ожидания продолжения диалога |
| `MAX_HISTORY=20` | Макс. сообщений в сессии |

## Частые задачи

**Сменить голос у агента**: меняй `COSMO_TTS_VOICE` / `LUSYA_TTS_VOICE` в `.env`. Voice ID берётся на [elevenlabs.io/app/voice-library](https://elevenlabs.io/app/voice-library).

**Отладить VAD (ассистент не слышит / слушает слишком долго)**: `SILENCE_THRESHOLD` (громкость) и `SILENCE_DURATION` (сек).

**Добавить третьего агента**: в `config.py::AGENTS` новый ключ, в `modes.py::run_with_porcupine` добавить `WAKE_WORD_*` и `wake_word_map.append(...)`.

**Сменить модель LLM**: `VOICE_MODEL` в `.env` — передаётся в header `x-openclaw-model`. Модель `openclaw/main` остаётся как agent (это маршрут в OpenClaw).

## Что НЕ делать

- Не комитить `.env` (есть в `.gitignore`)
- Не возвращать fallback на macOS `say` — проект специально унифицирован на ElevenLabs + mpv
- Не создавать новую сессию Conversation на каждую активацию — это было в старой версии, сейчас одна сессия на день
- Не добавлять temp файлы для WAV/mp3 — всё идёт через `BytesIO` / stdin pipe

## Roadmap

- [ ] Speaker identification (определять кто говорит без разных wake words)
- [ ] Проактивные уведомления (WebSocket от сервера → satellite сам начинает говорить)
- [ ] Контекст окружения в system prompt (время, погода, состояние устройств)
- [ ] Real-time barge-in (прерывание по голосу во время озвучки, не только по новой активации)