ZYNX Minutes

Локальный помощник для протоколирования совещаний команды ZYNX. Кейс HackAlem, трек «Инновации»: извлечь из разговора решения, поручения, ответственных и сроки с возможностью проверки по исходным репликам.

Начните здесь: қазақша іске қосу нұсқаулығы — START_HERE_KZ.md.

Состояние прототипа

Реализованы веб-интерфейс, хранение в SQLite, редактирование поручений, статусы, проверка цитат, консервативный расчёт сроков и экспорт PDF/DOCX/JSON. В коде подключены локальные Whisper, pyannote и Ollama.

Проверено в среде разработки: 15 автоматических тестов, запуск HTTP-сервера, путь «текст → поручения → правка → сохранение → повторное чтение → экспорт/удаление»; PDF и DOCX с казахскими символами отрендерены и просмотрены. Проверена синтаксическая корректность JavaScript.

Ещё требуется на машине команды: запуск реальных моделей, проверка качества RU/KZ/смешанного аудио и диаризации, ручная проверка интерфейса в браузере Windows. Среда разработки не дала скачать веса и браузерный движок. Автоматические тесты агента используют подменённые ответы модели и не измеряют её точность. Код интеграций не равен подтверждённой работе всех моделей.

1. Быстрый запуск на Windows

Требуется Python 3.11 или 3.12; для воспроизведения рекомендуем Python 3.12. Скачайте репозиторий: Code → Download ZIP, распакуйте архив.

1. Дважды нажмите setup.cmd: создаст .venv и установит библиотеки PDF/DOCX.
2. Дважды нажмите start.cmd. Оставьте окно открытым.
3. Откройте http://127.0.0.1:8765.
4. Нажмите «Попробовать демо» → «Сформировать протокол».
5. В демо должно появиться 3 поручения. Проверьте цитаты, исправьте поля и скачайте PDF/DOCX.

Для первого открытия интерфейса достаточно py -3 app.py; библиотеки экспорта можно установить позже. Модели не нужны для демо по правилам. Этот режим не является AI и сам по себе не закрывает обязательные требования кейса.

Через PowerShell из папки проекта:

py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe app.py

Не требуется активировать окружение или менять ExecutionPolicy. Если команда py не найдена, установите Python 3.12 с официального python.org и откройте новое окно терминала.

Linux/macOS:

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python app.py

2. Подключение локального AI для текста

1. Установите Ollama на компьютер команды и запустите его.
2. Загрузите модель заранее; в терминале:

ollama pull qwen3:8b

3. В приложении выберите «Локальный AI · Ollama», модель qwen3:8b.
4. Вставьте разговор и нажмите «Сформировать протокол».

Используется только http://127.0.0.1:11434/api/chat. Прокси и HTTP-перенаправления в клиенте отключены. Облачные имена моделей с cloud отклоняются. Используйте скачанные локальные веса и запретите внешние подключения на машине демонстрации после подготовки. API-ключ OpenAI/NVIDIA не нужен.

Для ограниченной памяти можно попробовать ollama pull qwen3:4b и изменить поле модели; качество выделения поручений обязательно проверить. Практический ориентир для 8B — 16 ГБ RAM или больше; расход зависит от контекста и оборудования, скорость не гарантируется. Аудио/LLM/диаризация используют общую память; при нехватке применяйте короткие записи и более лёгкую модель. CPU поддерживается, GPU может ускорить работу.

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

3. Подготовка распознавания речи

Интернет нужен для установки библиотек и весов, а не для обработки совещания.

.\.venv\Scripts\python.exe -m pip install -r requirements-audio.txt
.\.venv\Scripts\python.exe scripts/download_models.py --whisper small

По умолчанию small используется как стартовый вариант для CPU. Для сложной казахской и смешанной речи сравните результат с large-v3, если есть время и оборудование:

.\.venv\Scripts\python.exe scripts/download_models.py --whisper large-v3
$env:ZYNX_WHISPER_PATH = "$PWD\models\whisper-large-v3"
.\.venv\Scripts\python.exe app.py

В приложении откройте «Аудио / видео», загрузите WAV/MP3/M4A/OGG/FLAC/WEBM/MP4 до 20 МБ и 10 минут. Выберите язык или RU+KZ. Режим mixed включает multilingual-распознавание; точность зависит от записи. Проверьте имена, цифры и казахские окончания в транскрипте. Изменённый вручную транскрипт анализируется как текст, временные метки в таком случае не сохраняются.

Загрузка видео означает извлечение его аудиодорожки. Подключение ботом к Zoom/Teams/Meet и live-поток в MVP не реализованы.

4. Диаризация — обязательный этап для полной демонстрации

Модуль отдельно разделяет голоса, затем сопоставляет временные интервалы со словами транскрипта. Голоса получают метки SPEAKER_00, SPEAKER_01. После прослушивания секретарь подписывает их именами. Биометрическая идентификация личности по голосу не заявляется.

.\.venv\Scripts\python.exe -m pip install -r requirements-diarization.txt

Примите условия модели pyannote community-1. Создайте read token Hugging Face и выполните:

.\.venv\Scripts\python.exe scripts/download_models.py --diarization

Скрипт запросит токен скрытым вводом. Не вставляйте токен в исходники и не отправляйте в чат. Веса сохраняются в models/diarization и не попадают в Git. Во время обработки включены HF_HUB_OFFLINE=1, HF_HUB_DISABLE_TELEMETRY=1, PYANNOTE_METRICS_ENABLED=0.

Если pyannote сообщает об отсутствующем FFmpeg/torchcodec, установите FFmpeg из источника, рекомендованного вашей ОС, и проверьте совместимость torch/torchcodec по документации pyannote. Основной декодер Whisper использует PyAV. В модуль диаризации передаётся уже декодированный массив в памяти.

Для диагностики:

.\.venv\Scripts\python.exe scripts/doctor.py

Не отключайте диаризацию в финальной демонстрации без явного объявления этого ограничения. Без неё говорящий обозначается «Не определён».

5. Что происходит с датами и ответственными

• Дата совещания задаётся пользователем; относительные сроки считаются от неё.
• через две недели / екі апта ішінде превращаются в дату с пометкой о календарных днях.
• 25 қыркүйек получает год совещания и пометку для подтверждения.
• до конца недели, к среде, рабочие дни и сроки после другого события оставляются для уточнения: календарная политика организации неизвестна.
• Дата без года, которая уже прошла относительно встречи, не переносится автоматически на следующий год.
• Сроки, отсутствующие в указанном источнике, не получают вычисленную дату.
• Автор реплики не назначается ответственным автоматически. В AI-режиме учитываются обращения и ответы.
• Цитата проверяется как подстрока источника. Это проверка происхождения текста, а не гарантия правильности вывода; все задачи первоначально непроверенные.
• Правки сохраняются отдельно от исходных цитат. Пометки «Проверка при извлечении» отражают исходную автоматическую проверку.

6. Данные и приватность

Однопользовательский локальный прототип слушает только 127.0.0.1. Он не предназначен для публикации в интернет в текущем виде. Нет аутентификации, многопользовательских ролей или шифрования SQLite.

Аудио записывается во временную папку и удаляется после обработки или ошибки. Транскрипт, результаты и правки сохраняются в data/meetings.sqlite3 на этом компьютере. После аварийного завершения ОС временные файлы могут потребовать ручной очистки. Кнопка удаления убирает запись из БД, но не обещает криминалистически безопасное стирание диска.

В исходном коде нет отправки аудио или текста во внешние API. Модели нужно загрузить заранее, проверить конфигурацию Ollama и запретить внешний сетевой доступ на подготовленной машине. Для реальных записей нужны согласие участников и анонимизация демонстрационных материалов согласно кейсу.

data/, models/, .env и окружение исключены из Git. Не добавляйте реальные записи, ключи, платёжные скриншоты или персональные данные в репозиторий.

7. Проверки и воспроизведение

.\.venv\Scripts\python.exe -m unittest discover -s tests -v

15 тестов: даты, несуществующие цитаты, отсутствие срока, сохранение/повторное чтение, экспорт, согласие на аудио, CSRF, изменение говорящего внутри ASR-сегмента, два этапа агента с подменёнными ответами. Тесты экспорта пропускаются, если не установлены зависимости.

План проверки качества на реальных моделях и эталонные ожидания: EVALUATION.md. Синтетические тексты: examples/demo.json; это входы, а не зашитые ответы AI. Встроенная кнопка демо загружает первый пример для ограниченного разбора по правилам. Остальные тексты можно скопировать для AI-тестирования.

Версии прямых Python-зависимостей зафиксированы. Транзитивные зависимости и версии весов не полностью зафиксированы; после успешной установки на демонстрационной машине сохраните pip freeze в requirements-tested.txt, версию Ollama и результат ollama list. Не называйте сборку полностью воспроизводимой без проверки на целевой машине.

8. Файлы и архитектура

Файл	Роль
app.py	HTTP API, очередь обработки, SQLite, сохранение правок
web/	HTML/CSS/JavaScript, ввод, исправления, экспорт
audio_engine.py	Локальные Whisper + pyannote, временные метки
agent.py	Извлечение и проверка локальной моделью Ollama
core.py	Правила демо, даты, цитаты, сопоставление слов и голосов
exporter.py	DOCX и PDF с кириллицей
scripts/	Подготовка моделей и диагностика
tests/	Автоматические проверки

UI → локальный HTTP API → Whisper/pyannote → подписи голосов → Ollama → проверка цитат/дат → ручная проверка → SQLite → PDF/DOCX.

Нагрузка обрабатывается последовательно, чтобы не запускать несколько тяжёлых задач одновременно. Для MVP текст ограничен 26 000 символами; большие совещания нужно делить на части. Объединение результатов частей пока ручное.

9. Ограничения и развитие

Нет live-ботов встреч, фоновых напоминаний, интеграции с СЭД, рассылок и промышленного доступа. Дашборд показывает текущие статусы и просрочку, но не рассылает уведомления. Нужны замеры скорости, WER/CER и ошибки диаризации на целевых RU/KZ данных. Следующие шаги: проверенная запись смешанной речи, длинные совещания с объединением задач, календарные правила организации, контроль доступа, внутренний сервер и интеграция с СЭД.

Для закрытого сервера можно запускать процесс с моделями внутри организации и показывать его через локальный браузер/RDP. Для сетевого веб-доступа сначала нужны аутентификация, TLS и отдельный сервер приложений; не открывайте встроенный HTTP-сервер наружу.

10. Источники технических интерфейсов

• faster-whisper — локальные модели, timestamps, CPU/GPU.
• pyannote community-1 — local/offline inference и exclusive diarization; соблюдайте лицензию модели CC-BY-4.0.
• Ollama Chat API — локальный structured JSON output.
• Qwen3 в Ollama — локальная языковая модель.

Материалы для сдачи и план четырёх часов: SUBMISSION.md.