Vera— Голосовой агент для Windows

О проекте

Vera — локальный голосовой агент для Windows, работающий без передачи данных в облако. Все вычисления выполняются на компьютере пользователя:

• Распознавание речи: Sherpa-ONNX (оффлайн, streaming)
• Модель LLM: Ваша локальная (при разработке использовалась Qwen 3.5 2B) или внешний сервер (Ollama, LM Studio)
• Синтез речи: Supertonic (высококачественный нейросетевой голос Lily, локально через ONNX Runtime)
• Интерфейс: Плавающий виджет и полноценное окно чата поверх всех окон

Важно: агент может ошибаться. Проверяйте критически важные данные, включая результаты веб-поиска, курсы валют, погодные данные и статистику.

Чтобы прервать разговор Веры, скажите "Вера" — она остановится и будет ждать команду.

Вы можете скачать агента на сайте https://agentvera.ru

Возможности

Архитектура памяти

Память Веры — это гибридная система поиска, спроектированная для работы полностью локально (без векторных БД и эмбеддингов, чтобы оставаться в рамках небольших моделей).

Хранение

Миграция из старого .md формата в JSON происходит автоматически и однократно при первом запуске; далее агент работает только с JSON.

Категории фактов

Каждый факт автоматически относится к одной из категорий по regex-эвристикам (без LLM-вызова):

Гибридный поиск

Когда пользователь отправляет сообщение, агент извлекает последнюю реплику пользователя из истории диалога и использует её как поисковый запрос. Поиск работает по формуле:

score = 0.50 × keyword_score
      + 0.30 × recency_score (с hard-cap 5%)
      + 0.20 × category_match
      + 0.15 × pinned_bonus

• keyword_score — BM25 с лёгким стеммингом (русские и английские словоформы: Москва/Москве/Москву, loves/loved/loving). Per-corpus нормализация (max raw → 1.0) даёт стабильный gate на маленьких корпусах.
• recency_score — линейный спад от 1.0 (сейчас) до 0.0 (год назад), ограничен 5% вклада.
• category_match — если категория запроса совпадает с категорией факта, +0.20 × weight[category] (preference/project весят 1.2, остальные 1.0).
• pinned_bonus — закреплённые факты всегда попадают в контекст, даже при BM25 = 0.

Итоговый контекст = профиль + pinned-факты (целиком) + top-3 recalled факта, с жёстким cap в 600 символов.

Закрепление фактов

Любой факт можно «приколоть» через API — он будет гарантированно попадать в system prompt агента. Полезно для критичной информации (аллергии, имя, ограничения), которая не должна «выпасть» из контекста при большом корпусе фактов.

Лимиты

Системные требования

С учетом встроенной локальной LLM (Qwen3.5-2B-GGUF) и нейросетевых движков распознавания/синтеза речи (Sherpa-ONNX STT, Supertonic TTS):

Для разработчиков:

• Python 3.10+
• Node.js 20.19+ (текущая ветка Vite 8 из ui/package.json).

Установка и запуск

Шаг 1: Клонирование

git clone https://github.com/tripleguard/Vera.git
cd Vera

Установка через .exe

Windows-установщик ставит Vera в %LOCALAPPDATA%\Vera и предлагает три типа установки:

• Полная: основное приложение, локальный llama.cpp, модель Qwen3.5-2B Q4_K_M и Supertonic 3.
• Минимальная: основное приложение для работы с внешним LLM-сервером, без локальной LLM и голосового пакета.
• Выборочная: ручной выбор компонентов.

Supertonic является отдельным необязательным компонентом. Без него Vera запускается в текстовом режиме. Установщик также может создать ярлык на рабочем столе и добавить Vera в автозапуск Windows.

Каталоги установленной версии:

При установке новой версии файлы приложения копируются из новой сборки повторно. Пользовательские данные в %LOCALAPPDATA%\Vera\data не входят в состав staging приложения и сохраняются отдельно.

Шаг 2: Зависимости

pip install -r requirements.txt

Для сетевых запросов веб-слой использует niquests как основной HTTP-клиент с автоматическим fallback на requests. Поэтому после обновления зависимостей Vera получает более современный клиент, но старые окружения не ломаются, если niquests еще не установлен.

cd ui
npm install
cd ..

Шаг 3: Бинарные модели

Sherpa-ONNX:

1. Скачайте модель sherpa-onnx-streaming-zipformer-small-ru-vosk-2025-08-16
2. Распакуйте её в корень проекта

LLM: Если вы используете встроенный механизм запуска, скачайте модель формата GGUF (в установщике используется Qwen3.5-2B-Q4_K_M) и поместите файл в корень проекта.

В Windows-установщике Supertonic предлагается отдельным необязательным компонентом. Без него Vera запускается в текстовом режиме и явно показывает, что синтез речи недоступен.

Запуск

cd ui
npm start

npm start поднимает Vite + Electron и автоматически запускает Python backend (server.py) из .venv, если окружение найдено.

Консольные команды:

Графический интерфейс (GUI)

Агент работает в фоновом режиме через графический интерфейс с плавающим поверх остальных окон виджетом, который пульсирует во время разговора и обдумывания ответа. Также доступно окно чата для текстового взаимодействия и отдельная панель сессий, открывающаяся слева от основного окна. Распознанные голосовые запросы автоматически отображаются в чате вместе с ответами.

В интерфейсе чата доступны следующие визуальные элементы и кнопки управления:

• Плавающий виджет: Виджет можно скрыть крестиком при наведении. Настройка «Показывать плавающий виджет» применяется сразу и сохраняется между запусками.
• Системный трей (Windows): Иконка агента в трее открывает чат, а через контекстное меню доступны действия «Открыть чат», «Показывать плавающий виджет» и «Выход».
• Кнопка-скрепка (Прикрепление файлов): Позволяет загружать файлы прямо в чат, передавая их содержимое в контекст запроса. Поддерживаются форматы .docx, .txt, .xlsx, .pptx, .md, .py, .pdf, .html, .json. Загрузив документ, вы можете просить агента извлечь нужную информацию, проанализировать код или таблицы, сделать саммари.
• Drag-and-drop и буфер обмена: Файлы и изображения можно перетаскивать в активную область чата или вставлять из буфера обмена. Для изображений отображается миниатюра, а мультимодальная модель получает текст и изображение в одном запросе.
• Панель сессий: Каждая сессия хранится отдельно, поддерживает переименование, закрепление, архивирование и удаление. Архивный режим показывает архивные сессии отдельно от активного списка, при этом сообщения внутри архивных сессий сохраняются и снова доступны после открытия или возврата сессии из архива. При переключении агент подгружает только контекст выбранной сессии.
• Заметки: Раздел заметок содержит текстовые записи, чек-листы и холст для свободного рисования. Заметки сохраняются локально, поддерживают несколько записей, задачи с приоритетами, цвета, перо, ластик, очистку холста и масштабирование.
• Проекты: Созданные презентации доступны в отдельном разделе, открываются напрямую из приложения и при необходимости перемещаются в системную корзину.
• Рабочая панель: Правая панель содержит дерево выбранной директории и интерактивный CMD-терминал. Файлы из дерева можно открывать и перетаскивать в чат.
• Нижняя панель: Показывает активную модель и версию приложения, открывает периодические задачи и поток системных логов. Если доступна новая сборка llama.cpp, рядом с моделью появляется кнопка обновления, которая скачивает подходящий архив, устанавливает runtime и перезапускает агент.
• Настройки модели: В разделе модели отображается установленная версия llama.cpp в формате b12345, а также доступны параметры локальной модели, контекста, режима размышления и внешнего LLM-сервера.
• Настройки голоса и аудио: Стилизованные списки позволяют без перезапуска менять микрофон и устройство вывода. Vera показывает только уникальные WASAPI-устройства, поддерживает проверку входа/выхода и автоматически откатывает нерабочий выбор.
• Режим озвучивания: Можно озвучивать только ответы на голосовые запросы (значение по умолчанию), все ответы либо полностью отключить TTS.
• Темы оформления: В настройках доступны шесть светлых и темных тем: «Обсидиан», «Дневной», «Терминал», «Сакура», «Графит» и «Аврора».
• Переключатель мышления (иконка мозга рядом с вводом): Позволяет быстро включать/выключать режим размышления модели; токенный бюджет задается в настройках, а ход мысли можно раскрыть в карточке ответа.
• Индикатор активности: Во время генерации отображается компактная надпись «Думает», а при выполнении функции индикатор показывает фактическое действие: поиск в интернете, чтение документа, создание презентации и другие операции.
• Кнопки источников: Ссылки из веб-поиска парсятся и отображаются в виде аккуратных кликабельных кнопок с доменами сайтов, открывающихся в браузере.
• Кнопка "Открыть папку с файлом": После генерации документа или презентации и создания скриншота появляется кнопка для быстрого перехода к файлу в Проводнике.
• Системные уведомления в чате: GUI показывает служебные сообщения при проблемах backend (автоперезапуск, исчерпание попыток, сетевые неполадки).

Для удобства пользователя реализован стриминг ответов: в чате текст набирается плавно и постепенно, слово за словом (в голосовом режиме ответы выводятся целиком для синхронизации со звуком).

Внешние LLM-серверы

Агент поддерживает работу со сторонними серверами, такими как Ollama или LM Studio. Это позволяет не запускать локальную модель силами самого агента, а перенаправить запросы на уже запущенный в системе (или в другой сети) инстанс, экономя ресурсы компьютера и обеспечивая гибкость в выборе моделей.

Как подключить другой эндпоинт:

1. Откройте настройки в графическом интерфейсе агента.
2. Включите опцию "Внешний LLM-сервер".
3. Введите URL вашего сервера (например, http://localhost:11434/v1 для Ollama или http://localhost:1234/v1 для LM Studio).
4. Нажмите кнопку сохранения. Изменения применяются мгновенно без необходимости перезапуска агента.

Периодические задачи и напоминания

Вы можете управлять фоновыми задачами и напоминаниями двумя способами: ставя их голосом или настраивая самостоятельно через графический интерфейс.

Самостоятельная настройка через GUI:

1. Откройте окно Настроек в интерфейсе агента.
2. Перейдите к разделу "Периодические задачи".
3. В этом разделе представлен список всех активных задач. Вы можете визуально добавлять новые напоминания, редактировать время и интервал срабатывания существующих, включать и отключать задачи, а также удалять их.
4. Расписание хранится локально в data/heartbeat_tasks.json: при сохранении задачи валидируются, получают устойчивый id, нормализованное время, статус последнего запуска (running / success / failed), текст последней ошибки и счетчик выполнений. Если список очищен, фоновые задачи сразу удаляются и из файла, и из памяти работающего агента.
5. Интервальные задачи защищены от некорректных значений: нулевой интервал автоматически приводится к минимальному рабочему интервалу, а невалидное время сбрасывается к безопасному значению по умолчанию.
6. Сложные задачи (например, запрос новостей или погоды по утрам) автоматически направляются в LLM для обработки, а простые (напоминания вроде "попей воду") сразу выводятся на экран в виде текста.

Виджет и звук таймера:
При установке таймера в маленьком плавающем виджете агента наглядно отображается обратный отсчет. По истечении времени (с секундной точностью) проигрывается обновленный звук таймера и через backend отправляется одно системное уведомление «Таймер завершён». Звук повторяется до тех пор, пока вы не остановите его командой «стоп». После остановки виджет автоматически возвращается в обычный режим.

Управление голосом (Примеры команд):

Вера, таймер 10 минут
Вера, напомни через полчаса позвонить начальнику
Вера, читай мне новости каждое утро в 9:30
Вера, удали таймер

Полный справочник команд

Приложения и окна

Агент использует нечёткий поиск названий программ.

Вера, открой хром
Вера, закрой телеграм
Вера, запусти калькулятор
Вера, открой командную строку
Вера, сверни окно
Вера, разверни браузер
Вера, переключись на телеграм

Запланированный запуск приложений

Агент может запускать приложения по расписанию, автоматически определяя правильные даты.

Вера, запускай телегу каждый день в 9 утра
Вера, запускай хром в 8:30 по будням
Вера, запусти дискорд в 22:30
Вера, покажи запланированные запуски

Файлы и папки

Поиск директорий и файлов с фильтрацией по дискам и fallback на встроенный поиск Windows:

Вера, открой файл отчет
Вера, найди файл резюме
Вера, открой папку проект
Вера, открой папку bb на диске d

Системные настройки и питание

Вера, громкость 75 процентов
Вера, яркость 7
Вера, открой пуск
Вера, мой компьютер
Вера, сделай скриншот
Вера, какой мой IP
Вера, выключи компьютер
Вера, перезагрузи через час
Вера, спящий режим

Музыка и медиа

Управление воспроизведением (Spotify, Яндекс Музыка и другие плееры). Команды выполняются без голосового подтверждения.

Вера, пауза
Вера, играй
Вера, продолжи
Вера, стоп музыка
Вера, выключи музыку
Вера, дальше трек
Вера, следующий трек
Вера, назад

Корзина, диспетчер задач и утилиты

Вера, открой корзину
Вера, очисти корзину
Вера, открой диспетчер задач
Вера, закрой диспетчер задач
Вера, подбрось монетку

Веб-поиск, Погода и Курсы валют

Агент самостоятельно очищает и нормализует содержимое загруженных веб-страниц, чтобы небольшой локальной модели было проще работать с контекстом:

Вера, погода в Москве
Вера, запомни мой город Москва
Вера, погода
Вера, курс доллара
Вера, найди информацию о Python
Вера, кто такой Эйнштейн
Вера, открой ютуб

Погода определяется по указанному городу. Если город в запросе не назван, но агент знает ваш город из памяти, простой запрос «Вера, погода» будет искать прогноз именно для этого города. Профиль можно заполнить обычной командой памяти, например: «Вера, запомни мой город Москва». В ответе показываются текущая температура, погодные условия и короткая рекомендация по одежде или осадкам.

Источником курсов валют является ЦБ РФ.

Память и контекст

Агент обладает долгосрочной персистентной памятью (сохраняется между запусками в data/memory.json). Факты извлекаются автоматически из обычного разговора и автоматически распределяются по категориям (identity / contact / preference / project / fact). При формировании ответа используется гибридный поиск (BM25 + recency + category match) — релевантные факты подтягиваются в system prompt как контекст.

Прямое управление:

Вера, запомни меня зовут Имя
Вера, запомни я работаю программистом
Вера, запомни мой email user@example.com
Вера, запомни работаю над проектом X
Вера, что ты знаешь обо мне
Вера, забудь про работу
Вера, забудь всё

Подробнее об архитектуре памяти и поиска — в разделе Архитектура памяти.

Skills

Skills расширяют поведение агента локальными инструкциями для конкретных классов задач. Каждый skill хранится в отдельном каталоге с файлом SKILL.md, описывает назначение, правила выполнения, разрешенные инструменты и профиль модели. Агент загружает только подходящий skill, поэтому основной системный промпт остается компактным даже при большом количестве возможностей.

В Vera входят skills для презентаций и текстовых документов:

• skills/presentations — исследование темы, планирование структуры, подбор визуального стиля, генерация .pptx и сохранение результата в проекты;
• skills/documents — создание докладов, отчетов, статей и текстовых документов с проверкой фактического пути сохраненного файла.

Установленные skills отображаются в разделе Skills интерфейса. Пользовательские skills могут дополнять встроенные или переопределять их без изменения кода агента.

Инструменты (Tools)

Агент выбирает небольшой релевантный набор инструментов через единый маршрутизатор намерений. Это уменьшает системный промпт, снижает количество ложных вызовов на небольших моделях и сохраняет полный набор возможностей при работе с более крупными LLM.

Чтение и аналитика документов (read_document)

Вера, расскажи что написано в файле readme
Вера, прочитай документ отчёт.docx
Вера, о чём файл changelog.md

Длинные документы автоматически суммаризируются.

Офисные инструменты и презентации

Создание текстовых файлов, таблиц и презентаций. Для презентаций агент исследует тему через веб-поиск, объединяет источники, подбирает структуру и визуальный стиль. Если сеть недоступна, используется локальный контекст и знания модели:

Вера, создай заметку с текстом привет мир
Вера, сделай презентацию про искусственный интеллект
Вера, создай таблицу с расходами

Презентации используют разные композиции и цветовые схемы, сохраняются в раздел Проекты и содержат источники, если использовался поиск. Доклады, отчеты и статьи создаются отдельным документным pipeline, который возвращает фактический путь готового файла.

Интерпретатор Python (code_interpreter)

Безопасное выполнение скриптов в отдельном процессе с защитой от зацикливания:

Вера, посчитай факториал 20
Вера, сгенерируй случайный пароль
Вера, реши уравнение x^2 - 5x + 6 = 0

Telegram-режим

В текущей версии этот режим деактивирован единым feature flag. Раздел ниже сохранён как документация для возможного контролируемого возврата функции.

Агент может работать через "Telethon", подключаясь к привязанному аккаунту Telegram, обрабатывая команды прямо из папки Избранное (Saved Messages):

Вера, уйди в телегу
Вера, перейди в телеграм

• Работа с файлами: можно написать "скинь файл отчет.docx" — агент найдет и отправит документ или фото прямо в чат. Если доступно несколько вариантов, он предложит выбор.
• Генерация презентаций: отправьте запрос на создание презентации, и готовый .pptx файл автоматически придет в чат.
• Для возврата в десктопный режим напишите «вернись» в чате. С целью безопасности в Telegram-режиме отключено управление ПК.

Доступно чтение сообщений из переписок с нормализацией имён:

Вера, напиши Назару привет
Вера, что написал Назар?
Вера, мне кто-то писал в телеге?
Вера, выйди из телеги

Как работает веб-поиск

HTTP-запросы веб-слоя проходят через web/http_client.py: сначала используется niquests, а если он недоступен, система автоматически возвращается к requests. Это сохраняет совместимость с текущим кодом и дает возможность использовать более современный HTTP-клиент там, где он доступен.

1. Поисковый запрос сначала отправляется в Brave Search.
2. Если Brave недоступен, вернул ошибку или не нашёл результатов, Vera автоматически переключается на DuckDuckGo Lite.
3. Из выдачи выбираются ссылки с учётом доменных фильтров и базового ранжирования по релевантности.
4. Страницы загружаются параллельно, чтобы не тратить лишнее время на последовательные сетевые запросы.
5. Основной контент страницы извлекается через trafilatura сразу в Markdown. Это убирает меню, скрипты, служебные блоки и сохраняет заголовки, списки, ссылки и текст в форме, удобной для LLM.
6. Если trafilatura недоступна или не смогла извлечь полезный контент, Vera использует встроенный fallback-экстрактор на BeautifulSoup.
7. Полученный контекст ограничивается по объёму, сортируется по релевантности и передаётся модели для краткого ответа строго по найденным источникам.

Конфигурация

В установленной версии файл находится в %LOCALAPPDATA%\Vera\data\config.json, при запуске из исходников — в data/config.json проекта. Ключевые параметры: настройки слова активации, таймаут тишины, выбранные устройства (audio.input_device, audio.output_device), голос и параметры синтеза речи (tts.voice_name, tts.total_steps, tts.volume, tts.speak_responses), внешние серверы LLM и алиасы сайтов.

Запуск через Vite/Electron

cd ui
npm start

Desktop-приложение использует Electron (ui/main.js) и FastAPI backend (server.py). Renderer работает без прямого доступа к Node.js и взаимодействует с системными функциями через ограниченный preload API (ui/preload.js).

Тестирование

Тесты лежат в tests/ и используют unittest и функции в стиле pytest. Полный прогон:

python -m pytest -q

Покрытие (145 тестов и 4 subtests):

Запуск отдельного модуля

python tests/test_memory.py
python tests/test_tool_router.py
python tests/test_presentation_generator.py

Что НЕ покрыто (out of scope)

• Полный E2E-прогон Electron / Vite UI с реальным управлением окнами
• Sherpa-ONNX / Supertonic нейросетевые модели (требуют GPU/CPU setup)
• llama.cpp инференс (требует скачанной GGUF модели)
• Сквозной Telegram-режим (в версии 1.1.2 отключён feature flag и требует credentials при повторном включении)

Устранение неполадок

• Бесконечное соединение при запуске: в версиях до 1.1.2 запуск мог зависать на соединении, если микрофон отсутствовал, был отключён или недоступен системе. Проблема исправлена в версии 1.1.2: текстовый чат запускается независимо от микрофона, STT и TTS, а интерфейс показывает конкретное состояние недоступного компонента.
• Sherpa-ONNX не загружается: проверьте наличие папки с моделью (например, sherpa-onnx-streaming-zipformer-small-ru-vosk-2025-08-16).
• LLM не заводится / Ошибка llama-server.exe:
  1. Проверьте, что в папке с программой (%LOCALAPPDATA%\Vera по умолчанию) есть файл llama-server.exe и сопутствующие ему DLL.
  2. Если файлы отсутствуют (ошибка автоматического скачивания), скачайте архив llama-bin-win-vulkan-x64.zip (или cpu версию) с официального релиза llama.cpp и распакуйте его содержимое прямо в папку с приложением.
  3. Убедитесь, что там же лежит файл модели .gguf.
• Нет звука: проверьте компонент Supertonic, режим tts.speak_responses, выбранное устройство вывода и имя голоса в tts.voice_name. Устройство можно проверить и поменять в настройках без перезапуска.
• Микрофон не работает: разрешите доступ к микрофону в параметрах конфиденциальности Windows и выберите нужное WASAPI-устройство в настройках Vera. Даже при ошибке микрофона текстовый чат продолжает работать.
• Команды "Вера", "стоп" или "Вера, стоп" не останавливают речь: убедитесь, что микрофон не выключен через /mute или кнопку микрофона в GUI. Если таймер звенит, команда должна остановить таймер без обращения к LLM; если Вера говорит, команда очищает очередь TTS и прерывает воспроизведение.
• Ответ пустой или видны теги <think>: отключите режим мышления в GUI или уменьшите thinking budget. Vera дополнительно чистит <think> из обычных и веб-ответов, но сторонний LLM-сервер может отдавать нестандартный формат.
• Веб-поиск ничего не нашёл: проверьте доступ браузера/сети. Vera сначала пробует Brave Search, затем DuckDuckGo Lite; при блокировке обоих источников ответ будет построен только на локальных знаниях или вернёт понятную ошибку.
• Погода подставляет не тот город: проверьте поле город в панели памяти или в %LOCALAPPDATA%\Vera\data\memory.json (data/memory.json при запуске из исходников). Город из памяти используется только для геозависимых запросов вроде погоды, маршрутов и мест рядом.
• Backend перезапускается: в GUI появится служебное уведомление о перезапуске. Если попытки исчерпаны, перезапустите приложение и проверьте логи backend.
• Внешний LLM не отвечает: проверьте URL в настройках, наличие /v1 для OpenAI-compatible серверов, запущена ли модель в Ollama/LM Studio, и не занят ли порт.
• Память «забывает» факты: проверьте, что %LOCALAPPDATA%\Vera\data\memory.json (data/memory.json при запуске из исходников) не повреждён. Это единственное хранилище профиля и долгосрочных фактов. Лимит — 20 фактов; закреплённые (pinned) факты сохраняются последними при эвикции.

FAQ

Передает ли агент данные в интернет?
Нет, кроме веб-поиска, погоды и курсов валют. STT и LLM работают локально (или на вашем внешнем сервере, если он настроен).

Можно ли изменить слово активации?
Да, в общих настройках GUI или в config.json.

Как прервать Веру, когда она говорит?
Просто скажите "Вера" или "Вера, стоп" — она сразу остановится.

Как работает поиск по памяти?
Подробное описание алгоритма (BM25 + recency + category + pinned bonus) — в разделе Архитектура памяти. Коротко: последняя реплика пользователя используется как поисковый запрос, факты ранжируются гибридной формулой, top-3 + pinned попадают в system prompt.

Можно ли «приколоть» факт, чтобы он не терялся?
Да, через API MemoryManager.pin(fact_id). Закреплённые факты гарантированно попадают в контекст и не вытесняются при достижении лимита MAX_FACTS=20.

Благодарности

• Георгию Герганову — за вклад в развитие локальных языковых моделей.

Лицензии и ссылки

Sherpa-ONNX: https://github.com/k2-fsa/sherpa-onnx
llama.cpp: https://github.com/ggerganov/llama.cpp