docs: README — semantic intent + denoise

README.md

@@ -43,7 +43,9 @@ python main.py
   - `MICROPHONE_INDEX = -1` — индекс микрофона (`-1` означает устройство по умолчанию). Если микрофонов несколько и берётся не тот, поменяйте число.
   - `WAKE_WORDS = ('jarvis', 'джарвис')` — варианты транскрипции wake-word, которые принимает Vosk. Если ваш голос/акцент стабильно расшифровывается как, например, `жарвис` — добавьте этот вариант сюда (всё в нижнем регистре).
   - `GROQ_MODEL` — имя модели Groq (по умолчанию `llama-3.3-70b-versatile`).
-- `commands.yaml` — набор голосовых команд и их вариантов для fuzzy-матчинга.
+  - `INTENT_SIMILARITY_THRESHOLD = 0.45` — минимальная косинусная близость для срабатывания команды (см. ниже).
+  - `DENOISE_ENABLED = False` — шумоподавление перед Vosk (см. ниже).
+- `commands.yaml` — набор голосовых команд и их вариантов; матчится семантически по эмбеддингам.
 - `custom-commands/` — скомпилированные AHK-скрипты под конкретный сетап автора оригинала (переключение мониторов, управление Яндекс.Музыкой и т.п.). На вашей машине большая часть из них работать не будет, но ассистент запустится в любом случае.
 
 ## Использование
@@ -63,6 +65,26 @@ python main.py
 - `COMMAND_MIN_LISTEN_MS` — минимальное время записи, чтобы не закрыться мгновенно (1000 мс).
 - `COMMAND_MAX_LISTEN_MS` — жёсткий потолок (15000 мс).
 
+## Семантический матчинг команд
+
+Раньше распознанная фраза сравнивалась с фразами из `commands.yaml` через `fuzzywuzzy.fuzz.ratio` — это срабатывало только на формальное совпадение букв. Теперь используется sentence-transformer `all-MiniLM-L6-v2` (ONNX, CPU) — фраза кодируется в 384-мерный вектор, считается косинусная близость с фразами всех команд, побеждает самая близкая.
+
+Это означает, что фраза `«запусти браузер»` сматчится с командой `open_browser`, даже если в YAML записано только `«открой браузер»` — у них близкий смысл.
+
+- Модель лежит в `models/all-MiniLM-L6-v2/` (87 МБ, хранится через Git LFS — `git lfs pull` после клонирования).
+- Порог `INTENT_SIMILARITY_THRESHOLD = 0.45` (косинус, диапазон [-1; 1], для близких смыслов обычно 0.7+). Ниже порога — «команда не распознана», сработает `not_found.wav` (или ветка `«скажи …»` для LLM).
+- Все фразы из `commands.yaml` эмбеддятся один раз при старте; на каждой команде эмбеддится только распознанная пользователем фраза (~1-5 мс на CPU).
+
+## Шумоподавление перед STT
+
+Опциональный пре-процессинг аудио командного буфера через `noisereduce` (спектральное гейтирование). Помогает в шумных помещениях (кулер, кондиционер, фоновая музыка). К wake-word фазе не применяется — там важна отзывчивость.
+
+В `config.py`:
+
+- `DENOISE_ENABLED = False` — главный тумблер.
+- `DENOISE_PROP = 0.85` — доля подавления (0..1).
+- `DENOISE_STATIONARY = False` — `False` для меняющегося шума (рекомендуется), `True` для стабильного фона.
+
 ## Эффекты под AI-ассистента
 
 Silero звучит естественно, но иногда хочется лёгкой «AI-окраски» в духе J.A.R.V.I.S. — узкую полосу, еле заметную реверберацию, при желании небольшой сдвиг высоты. Это тонкий постпроцессинг, голос и sample rate не меняются.