Локальный голосовой ассистент для macOS с wake-word «Эй Бэн», транскрибацией через faster-whisper, интерпретацией интентов через локальную LLM (Ollama) и безопасным выполнением системных команд.

Проект ориентирован на приватный локальный запуск (MVP), без обязательной облачной зависимости.

English version: README.en.md.

• Непрерывно слушает микрофон и режет поток на речевые сегменты (VAD).
• Преобразует речь в текст (faster-whisper).
• Активирует контроль по wake-word и держит ownership по спикеру с TTL.
• Парсит намерения в структурированный JSON (action, payload, confidence) через Ollama.
• Выполняет allowlist-действия: dictate_text, move_mouse, switch_window, open_app.
• Требует подтверждение для рискованных действий (RISKY_ACTIONS).
• Поддерживает режим непрерывной диктовки (voice on/off).
• Логирует события в logs/events.jsonl.

AudioCapture → VADSegmenter → WhisperTranscriber → SpeakerRoleResolver → WakeWordController → IntentRouter → ConfirmationGuard → MacActionExecutor → EventLogger

• Event-driven цикл реализован в main.py.
• При USE_DIARIZATION=false используется fallback SPEAKER_00.
• Для action=none команды не исполняются и "Готово" не озвучивается.

Подробные документы:

• docs/architecture-overview.md
• docs/adr/0001-system-architecture.md

• macOS (целевая платформа).
• Python 3.11+.
• Установленный Ollama.
• Доступы в macOS:
  • Microphone
  • Accessibility (для управления клавиатурой/мышью/окнами).

make setup
make run

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
brew install ollama
ollama serve
ollama pull qwen2.5:3b-instruct
PYTHONPATH=src python -m uncle_ben.main

make test

Дополнительно:

make unit
make e2e

make e2e запускает интерактивный ручной сценарий с ожидаемыми голосовыми шагами.

Источник примера: .env.example.

Ключевые группы переменных:

• Whisper: WHISPER_* (включая WHISPER_INITIAL_PROMPT).
• Язык и wake-word: LANGUAGE, WAKE_WORDS, ACTIVE_CONTROL_SECONDS.
• LLM: OLLAMA_BASE_URL, OLLAMA_MODEL.
• Safety: RISKY_ACTIONS, CONFIRM_WORDS, CANCEL_WORDS, CONFIRMATION_TTL_SECONDS.
• Dictation: DICTATION_ENABLE_PHRASES, DICTATION_DISABLE_PHRASES.
• Voice feedback: VOICE_FEEDBACK_ENABLED, VOICE_FEEDBACK_VOICE, VOICE_FEEDBACK_RATE.
• Audio/VAD: INPUT_DEVICE, SAMPLE_RATE, FRAME_MS, VAD_AGGRESSIVENESS, MIN_SEGMENT_MS, MAX_SEGMENT_MS, SILENCE_PADDING_MS.
• Логи: LOG_LEVEL, EVENTS_LOG_PATH.

• Все runtime-события пишутся в logs/events.jsonl в формате JSONL.
• Типовые события: transcript, intent, confirmation, action_result, dictation, control_granted.

• Команды из RISKY_ACTIONS требуют подтверждения от того же спикера.
• Таймаут подтверждения настраивается через CONFIRMATION_TTL_SECONDS.
• Executor ограничен allowlist-экшенами; произвольный shell не используется.

Подробнее: SECURITY.md.

• Проект сфокусирован на macOS и русском голосовом UX.
• Качество зависит от микрофона, шума и выбранной Whisper-модели.
• Полная diarization опциональна и отключена по умолчанию.
• В models/piper лежат артефакты, но дефолтный TTS в проекте — системный say.

• docs/a3.md — постановка задачи и контрмеры.
• docs/fma.md — анализ отказов.
• docs/bmad.md — цикл улучшений.
• docs/decision-log.md — журнал инженерных решений.
• docs/adr/0001-system-architecture.md — архитектурное решение.

• Лицензия: GPL-3.0-only (LICENSE).
• Вклад в проект: CONTRIBUTING.md.
• Политика безопасности: SECURITY.md.

Проект распространяется «как есть», без гарантий пригодности для конкретной цели. Проверяйте голосовые команды перед использованием на рабочей системе.