1. AI Hatshy — ИИ-секретарь совещаний с фиксацией поручений

Решение кейса HackAlem AI «Система автопротоколирования совещаний с фиксацией поручений». «Хатшы» по-казахски — «секретарь».

Коротко. Загружаете или записываете совещание, и через несколько минут получаете готовый протокол:

• кто говорил и что сказал — на русском, казахском или вперемешку;
• поручения: кто отвечает, что сделать, к какому сроку, с цитатой и моментом записи;
• краткая и подробная сводка, PDF и DOCX;
• дашборд исполнения, напоминания о сроках, отправка поручений в СЭД;
• ИИ-помощник, которому можно задать вопрос по всем встречам.

Распознавание и разделение говорящих всегда выполняются на вашем сервере.

Оглавление: Описание · Почему это решение · Что реализовано · Как работает · Технологии · Архитектура · Установка · Проверка · Данные и интеграции · Ограничения · Deployed-версия · Масштабирование и развитие

2. Краткое описание

Проблема. Протоколы совещаний ведут вручную. Это отнимает время секретаря, а поручения, сроки и ответственные теряются или искажаются, и контролировать исполнение трудно.

Для кого.

• Секретарь получает готовый протокол вместо ручной записи.
• Руководитель видит исполнение поручений и просрочки на дашборде.
• Ответственные получают свои поручения и напоминания.
• ИТ-служба разворачивает решение в закрытом контуре и подключает его к СЭД.

Что делает система. Превращает запись совещания на русском, казахском или шала-казахском в протокол:

• транскрипт с разделением по говорящим;
• поручения с ответственным и сроком;
• краткая и подробная сводка;
• экспорт в PDF и DOCX.

Дальше система ведёт исполнение: статусы, напоминания, отправку во внешние системы.

Почему это решение

3. Что реализовано

Распознавание и протокол

Контроль исполнения

ИИ и интеграции

Удобство

4. Как работает решение

1. Вход. «Новое совещание» → загрузить аудио- или видеофайл (MP3, WAV, M4A, MP4 и другие форматы ffmpeg) или записать совещание в браузере. При записи участники слышат уведомление.

2. Обработка (в фоне, по одному совещанию, с прогрессом на экране):

   1. подготовка аудио;
   2. разделение говорящих;
   3. распознавание речи;
   4. выделение поручений, ответственных и сроков;
   5. формирование сводки и протокола.

3. Результат. Страница совещания с вкладками:

   • «Краткая сводка»;
   • «Подробная сводка»;
   • «Транскрипт»: говорящие, теги языка, плеер, переход по таймкоду.

   Справа — поручения с ответственным, сроком, цитатой и уверенностью.

4. Работа с протоколом. Подтвердить поручения, поправить имена, скачать PDF/DOCX, разослать выдержки, отправить поручения в СЭД.

5. Контроль. Раздел «Поручения» показывает статусы и сроки, «Уведомления» — напоминания о приближении срока и просрочке.

6. Вопросы. «Спросить ИИ» — по всем встречам или по открытой.

5. Технологии

• Язык и сервер: Python 3.12, FastAPI, uvicorn, SQLite, ffmpeg.
• Распознавание речи: GigaAM-Multilingual large CTC, int8 ONNX, ~592 МБ, лицензия MIT; запускается через onnx-asr.
• Диаризация и голосовые профили: sherpa-onnx; Silero VAD (ONNX); NeMo TitaNet-small (ONNX, 38 МБ). Кластеризация, поиск смены говорящего, имена по обращениям и сравнение голосов написаны в проекте.
• LLM:
  • по умолчанию gemma4 (8B, Q4_K_M) в Ollama на localhost:11434;
  • как вариант — OpenAI-совместимый Chat Completions API со структурированным выводом (JSON Schema);
  • на момент замеров использовалась модель gpt-5.2.
• MCP: официальный Python SDK mcp, транспорт stdio.
• Экспорт: python-docx; fpdf2 со шрифтом Montserrat (OFL, есть казахские буквы ә ғ қ ң ө ұ ү һ і).
• Интерфейс: HTML-шаблоны дизайн-макета на dc-runtime (app/static/support.js) и React 18 UMD. React и шрифты IBM Plex лежат в app/static/.
• Тестовые данные: macOS TTS (голоса Aru kk_KZ и Milena ru_RU) и ffmpeg.

Полный список сторонних компонентов и лицензий — в THIRD_PARTY.md.

6. Архитектура проекта

Браузер: веб (/) и мобильный (/m)            ИИ-агент (Claude Code / Desktop)
  │  REST, загрузка файлов, запись в браузере          │ stdio
  ▼                                                    ▼
FastAPI  app/main.py  ◄──────────── REST ──────── app/mcp_server.py (только localhost)
  │
  ├─ SQLite data/hatshy.db — совещания, реплики, говорящие, поручения, уведомления, профили, интеграции
  ├─ app/pipeline/runner.py — очередь обработки (по одной задаче); live-распознавание; сторож брошенных записей
  │    1. audio.py         ffmpeg → 16 кГц
  │    2. diarize.py       Silero VAD → TitaNet → кластеризация → реплики
  │       voice.py         узнавание говорящих по голосовым профилям
  │    3. asr.py, text.py  GigaAM по каждой реплике, регистр имён, тег языка
  │    4. llm/extract.py   LLM (Ollama или OpenAI-совместимый API) → участники, поручения, саммари (JSON)
  │    5. protocol.py      имена, проверка цитат (llm/verifier.py), сроки (llm/deadline_resolver.py)
  │    6. report.py        подробная сводка
  │    7. integrations.py  автоотправка поручений (если включена)
  ├─ app/assistant.py     ИИ-помощник: индекс совещаний + поиск фрагментов → LLM → ответ со ссылками
  ├─ app/reminders.py     напоминания, эскалация, выдержки → data/outbox/*.eml
  ├─ app/integrations.py  HTTP-вебхуки во внешние системы (СЭД, трекеры, боты), журнал отправок
  ├─ app/export/          PDF (fpdf2) и DOCX (python-docx)
  ├─ app/setup.py         мастер: статус и скачивание моделей, загрузка моделей в Ollama
  └─ app/llm_settings.py  выбор провайдера LLM; ключ хранится только в data/

Ответ LLM не принимается на веру: цитата поручения сверяется с транскриптом, срок пересчитывается правилами, имя ответственного сверяется с говорящими. Контракт API описан в CONTRACT.md.

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

Система целиком работает на одном компьютере: веб-интерфейс, API, распознавание, диаризация и LLM. Docker и сборка фронтенда не нужны: интерфейс — статические файлы из web/ и app/static/, библиотеки и шрифты уже лежат в репозитории.

7.1. Что нужно

7.2. Установка инструментов (один раз)

macOS (через Homebrew):

brew install git ffmpeg uv
# Ollama: приложение с https://ollama.com/download (после запуска работает в фоне)
# или из Homebrew в виде службы:
brew install ollama && brew services start ollama

Linux (Ubuntu/Debian):

sudo apt update && sudo apt install -y git ffmpeg curl
curl -LsSf https://astral.sh/uv/install.sh | sh     # uv
curl -fsSL https://ollama.com/install.sh | sh       # Ollama (ставится как служба)

Проверка: ffmpeg -version, uv --version, ollama --version — каждая команда печатает версию.

7.3. Установка проекта

# 1. Код
git clone https://github.com/BAITC-Hacks/hack-c9414062-smaguloveka.git
cd hack-c9414062-smaguloveka

# 2. Окружение Python и зависимости
uv venv --python 3.12 .venv
uv pip install --python .venv/bin/python -r pyproject.toml

# 3. Модели распознавания и диаризации в models/ (~0,63 ГБ, один раз).
#    Шаг можно пропустить: те же модели скачает «Мастер настройки» в браузере.
./scripts/download_models.sh

# 4. Локальная LLM (~9,6 ГБ, один раз). Тоже можно скачать из мастера.
ollama pull gemma4

Что скачивается в шаге 3:

• GigaAM-Multilingual large CTC, int8 ONNX, 592 МБ — распознавание RU, KZ и смешанной речи;
• Silero VAD, 2 МБ — поиск речи в записи;
• NeMo TitaNet-small, 38 МБ — «отпечатки» голосов для диаризации и голосовых профилей.

7.4. Запуск

.venv/bin/python -m uvicorn app.main:app --port 8000

Сервер готов, когда в терминале появится Uvicorn running on http://127.0.0.1:8000. Откройте:

• http://localhost:8000 — веб-версия;
• http://localhost:8000/m — мобильная версия.

Остановить сервер — Ctrl+C в том же терминале. Проверить, что сервер отвечает и модели на месте:

curl -s http://localhost:8000/api/setup

В ответе "models_ready":true — модели найдены, "llm_ready":true — LLM доступна.

7.5. Первый запуск: «Мастер настройки»

При первом открытии в браузере мастер проведёт по четырём шагам:

1. Приветствие — что делает система и что будет установлено.
2. Модели распознавания и диаризации. Если шаг 3 из 7.3 пропущен, нажмите «Скачать всё» — прогресс виден в окне, файлы лягут в models/.
3. ИИ для поручений и саммари. Выберите одно и нажмите «Проверить подключение»:
   • Локально — модель Ollama, по умолчанию gemma4. Если её нет, мастер скачает её сам (Ollama должна быть запущена). Данные не покидают компьютер.
   • OpenAI-совместимый API — вставьте свой ключ. Ключ хранится только в локальной базе data/hatshy.db (папка data/ в .gitignore) и в браузер не возвращается. Подойдёт и свой сервер в контуре организации, например vLLM: укажите его адрес. Аудио при этом всё равно распознаётся локально, во внешний API уходит только текст.
4. Готово — откроется дашборд. Модель можно сменить позже: «Настройки» → «ИИ и модели». Мастер можно открыть снова оттуда же.

Дальше — сценарий проверки из раздела 8.

7.6. Где лежат данные

Начать с чистого листа: остановите сервер и удалите папку data/ — при следующем запуске снова откроется мастер. Модели в models/ останутся.

7.7. Дополнительно

Доступ с телефона или другого компьютера в сети. Запустите сервер с --host 0.0.0.0 и откройте http://<IP-компьютера>:8000. Запись с микрофона браузеры разрешают только на localhost или по HTTPS, поэтому для записи с другого устройства нужен HTTPS (например, через обратный прокси). Загрузка файлов работает и по HTTP.

Обновление до новой версии:

git pull
uv pip install --python .venv/bin/python -r pyproject.toml

Затем перезапустите сервер. Данные в data/ сохраняются.

Подключить MCP к Claude Code (веб-сервер должен быть запущен), подробнее — docs/MCP.md:

claude mcp add ai-hatshy -- "$PWD/scripts/mcp.sh"

Переменные окружения — все необязательны, см. .env.example:

• OLLAMA_URL (по умолчанию http://localhost:11434), LLM_MODEL (gemma4:latest) — локальная LLM;
• HATSHY_DATA (./data) — каталог данных;
• ASR_THREADS (4) — потоки процессора для распознавания;
• OPENAI_API_KEY, OPENAI_BASE_URL, OPENAI_MODEL — если выбран OpenAI-совместимый API. Ключ также можно ввести в интерфейсе.

7.8. Если что-то не работает

Журнал сервера печатается в терминал, где он запущен.

8. Как проверить решение

1. Мастер настройки откроется при первом запуске: модели → «✓ Установлено», выберите LLM.
2. Обработка. «Новое совещание» → «Загрузить файл» → samples/shala_meeting.mp3 (шала-казахский, 95 с, 4 участника, эталон — samples/shala_meeting.gold.json). Подойдут и записи организаторов из spec/.
3. Протокол. Вкладки «Краткая сводка», «Подробная сводка», «Транскрипт» (имена, теги RU / KZ / RU+KZ, переход по таймкоду). Справа — поручения с датами сроков, их можно подтвердить.
4. Экспорт. «Экспорт PDF / DOCX», включите «Анонимизировать ФИО».
5. Напоминания. «Уведомления» → «Демо: текущая дата», например 2026-10-01. Появятся «Срок через N дн.» и «Просрочено», письма — в data/outbox/.
6. ИИ-помощник. «Спросить ИИ»: «Где обсуждали охрану труда и что решили?» — ответ со ссылками. Внутри протокола: «Кто что должен сделать?». Переключите язык на KZ или EN — помощник ответит на нём.
7. Голосовой профиль. «Участники» → «Из совещания»: выделите на шкале реплику участника, прослушайте, сохраните.
8. Интеграции. «Настройки» → «Интеграции» → «+ Добавить»: адрес любого HTTP-приёмника → «Проверить подключение». Затем откройте поручение → «Отправить в «…»»: в истории появится код ответа.
9. MCP. Подключите командой из раздела 7 и спросите Claude: «Какие поручения просрочены?».
10. Автопроверки:

    .venv/bin/python -m unittest -v              # сроки RU/KZ, тег языка, регистр имён, VAD
    .venv/bin/python scripts/test_export.py      # экспорт PDF/DOCX, анонимизация
    .venv/bin/python scripts/asr_check.py        # CER/WER распознавания на samples/
    .venv/bin/python scripts/try_diar.py samples/*.mp3 spec/*.mp3   # число голосов
    .venv/bin/python scripts/eval.py --api http://localhost:8000 --id <id совещания> --gold samples/shala_meeting.gold.json
    

Результаты, полученные в день хакатона (подробно — samples/asr_report.md, eval/results.md):

• Распознавание (синтетические записи, нарезка по эталонным границам реплик):

  Язык	CER	WER
  KZ	0,6%	3,9%
  RU+KZ	0,7%	6,1%
  RU	1,7%	5,0%

  Казахских букв распознано 226 из 231.

• Диаризация: число голосов верно на всех 4 записях с известным составом — 5, 5, 4 и 3.

• Поручения:

  Запись	LLM	Найдено из эталона	Ответственный	Срок
  Совещание №1 (организаторы)	gpt-5.2	11/11 (precision 79%)	10/11	11/11
  Совещание №2 (организаторы)	gpt-5.2	8/10 (precision 89%)	8/8	7/8
  Шала-казахская	gemma4	4/4	4/4	4/4
  Казахская	gemma4	5/5	5/5	5/5

  Эталон для записей организаторов размечен по текстам протоколов, а само аудио местами от них отличается.

• Время на 1,5–4,5-минутную запись:

  • аудио, диаризация и распознавание — 12–19 с;
  • LLM через OpenAI API — 35–43 с;
  • локальная gemma4 на ноутбуке 16 ГБ — 5–10 минут.

  Ответ ИИ-помощника через OpenAI API — 3–10 с.

9. Данные и интеграции

• Данные кейса. Записи и протоколы организаторов лежат в spec/. На их основе вручную размечен эталон eval/gold.json: 21 поручение, дословные цитаты.
• Синтетические казахская и шала-казахская записи сгенерированы scripts/make_samples.sh (кейс это допускает) и лежат в samples/ со сценариями и эталонами.
• Сеть при установке:
  • PyPI;
  • Hugging Face — GigaAM и Silero VAD;
  • GitHub Releases sherpa-onnx — TitaNet;
  • реестр Ollama — модель LLM.
• Сеть во время работы по умолчанию не нужна. Наружу данные уходят только в двух случаях:
  1. в «Настройках» выбран OpenAI API — туда уходит текст транскрипта для LLM;
  2. настроена интеграция на внешний адрес — туда уходят данные поручений.
• Интеграция с СЭД и другими системами. Работает через исходящие HTTP-запросы: подойдёт любая система, которая принимает JSON по HTTP (REST API или входящий вебхук) — СЭД, таск-трекер, Bitrix24, Telegram-бот и т. п.
  • Формат запроса задаётся шаблоном с подстановками полей поручения.
  • Авторизация: Bearer-токен или свой заголовок.
  • Для систем с другим протоколом (SOAP/XML, OAuth-потоки) нужен небольшой адаптер.
• Встроенные каналы: письма (выдержки и напоминания) в локальный data/outbox/; звук Zoom / Teams / Meet — через системное аудиоустройство.
• MCP. MCP-сервер обращается только к локальному API. Текст, который он возвращает, получает модель ИИ-клиента.
• Секреты. В репозитории их нет. Ключ OpenAI и токены интеграций вводятся в интерфейсе и хранятся только в локальной базе data/hatshy.db; каталог data/ и .env в .gitignore.

10. Ограничения

• Конференции. Нет бота-участника Zoom / Teams / Meet, звук захватывается через системное устройство. Облачные боты противоречат требованию закрытого контура.
• Live-режим. Во время записи показывается только текст, без разделения по говорящим. Говорящие и поручения появляются после «Завершить».
• Качество измерено на синтетике. Казахский и шала-казахский проверены на TTS-записях. На живых записях точность распознавания, диаризации и порог узнавания по голосу (0,65) не измерялись, разметки нет.
• Диаризация. Перекрывающаяся речь не обрабатывается. Короткие реплики, вклеенные в чужую речь без паузы, могут достаться соседнему говорящему.
• ASR без пунктуации. Регистр имён восстанавливается эвристически.
• Длинные встречи. Транскрипт отправляется в LLM целиком, до 32k токенов контекста. Разбиение 1–2-часовых встреч на части не реализовано.
• Скорость локальной LLM. На ноутбуке 16 ГБ локальная LLM работает минутами. Ускорить можно меньшей моделью, GPU-сервером (не проверено) или OpenAI-совместимым API.
• Интеграции. Готовых коннекторов под конкретные СЭД нет, есть универсальные HTTP-вебхуки. SMTP-отправки нет, письма пишутся в outbox.
• Однопользовательский режим. Авторизации и ролей на сервере нет, переключатель ролей работает только в интерфейсе. SQLite рассчитан на один сервер.
• Перевод интерфейса. KZ / EN переводят навигацию и ИИ-помощника, остальные тексты интерфейса на русском.
• Анонимизация в экспорте теряет падеж имени.
• Мобильная версия проверялась меньше веб-версии. Запись с микрофона на телефоне требует HTTPS или localhost.

11. Deployed-версия

Публичной развёрнутой версии нет. Решение запускается локально по инструкции из раздела 7, так и задумано для закрытого контура.

12. Масштабирование и развитие

Этот раздел описывает, как решение можно развивать. Всё, что не реализовано, помечено «план».

Почему архитектура масштабируется

• Этапы разделены: API, очередь обработки, распознавание, LLM, интеграции. Каждый этап — отдельный модуль (app/pipeline/*) с понятным входом и выходом, поэтому их можно разнести по разным серверам.
• LLM подключается по OpenAI-совместимому API. Её можно вынести на GPU-сервер заказчика (например, vLLM) без изменения кода, достаточно указать адрес в настройках.
• Модели распознавания и диаризации в формате ONNX. Они работают на CPU; на GPU-серверах можно использовать onnxruntime с CUDA — план, не проверено.
• Всё управляется через REST API и MCP: веб, мобильная версия и ИИ-агенты работают с одним и тем же API. Новые клиенты подключаются без изменений сервера.

Шаги к масштабу организации (план)

1. PostgreSQL вместо SQLite, несколько воркеров обработки вместо одного.
2. Авторизация (SSO / LDAP), роли секретаря, руководителя и исполнителя на сервере.
3. Docker-образ и Helm-чарт для закрытого контура.
4. Разбиение длинных встреч на части для LLM.

Новые клиенты и каналы

• Мобильная версия. Уже есть веб-приложение /m: главная, запись, поручения, уведомления, установка на телефон. План: нативное приложение с push-уведомлениями о сроках.
• Смарт-часы (план). Напоминания о сроках и кнопка «Выполнено» на Apple Watch / Wear OS через мобильное приложение. Сервер уже отдаёт поручения и принимает смену статуса через API.
• Любые СЭД и мессенджеры. Уже есть универсальные вебхуки с шаблонами. План: готовые коннекторы для популярных СЭД и Telegram-бот с кнопками «Выполнено / Перенести срок».
• ИИ-агенты. Уже есть MCP-сервер. План: действия агента по расписанию, например утренний дайджест просроченных поручений (промпт overdue_digest в MCP-сервере уже есть).
• Конференции (план). Бот-участник для Zoom / Teams / Meet в контуре заказчика; потоковая диаризация во время записи.

app/main.py              FastAPI: API и раздача интерфейса
app/pipeline/            аудио, диаризация, ASR, текст, LLM-извлечение и проверка, подробная сводка, очередь
app/export/              PDF и DOCX
app/reminders.py         напоминания, эскалация, выдержки
app/voice.py             голосовые профили (узнавание по тембру)
app/assistant.py         ИИ-помощник по совещаниям
app/integrations.py      интеграции (HTTP-вебхуки)
app/mcp_server.py        локальный MCP-сервер; scripts/mcp.sh — запуск; docs/MCP.md — описание
app/setup.py             мастер настройки
app/llm_settings.py      выбор LLM
app/static/              dc-runtime, React UMD, шрифты, consent.mp3, манифест мобильной версии
web/index.html           веб-интерфейс; web/mobile.html — мобильный; web/design_*.dc.html — исходный макет
scripts/                 загрузка моделей, генерация тестовых записей, оценка и проверки
samples/                 синтетические KZ и RU+KZ совещания с эталонами и отчётом ASR
spec/                    материалы кейса: ТЗ, протоколы и записи организаторов
eval/                    эталон поручений (gold.json) и результаты оценки (results.md)
tests/                   юнит-тесты