Hattama — протокол совещаний с контролем поручений

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

---

1. Какую проблему решает

На совещаниях поручения раздают устно. Секретарь записывает их вручную: часть теряется, сроки искажаются («до конца недели» превращается в «до пятницы»), ответственный не всегда зафиксирован. Через неделю никто не может сказать, кому что поручено. Протокол оформляют ещё два-три часа после встречи, а исполнение не контролируется, потому что контролировать нечего: списка нет.

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

Что даёт система

Кому	Что получает
Секретарь	Протокол собирается сам: участники, краткое содержание, таблица поручений
Руководитель	Поручения со сроками и статусами, просроченные отмечаются автоматически
Исполнитель	Своё поручение с цитатой из совещания и сроком

---

2. Что умеет

1. Распознаёт речь — русский, казахский, смешанная речь. Локально. Модель определяет язык один раз на всю запись, поэтому на совещании, где языки чередуются, казахские фразы уезжают в русский. Мы прогоняем запись двумя проходами, русским и казахским, и по каждой реплике берём тот вариант, в котором действительно есть казахские буквы. Плата за это — время обработки вырастает вдвое.
2. Разделяет говорящих. Два режима: по паузам в одной записи либо по дорожкам, когда каждый участник пишет со своего телефона. Во втором случае имя говорящего известно точно.
3. Язык совещания выбирается перед записью: русский, казахский или смешанный. Один язык — один проход распознавания, быстро и точно. Смешанный — два прохода с выбором варианта по каждой реплике, это режим по умолчанию.
4. Отмечает участников перед началом: QR на экране ведущего, участник сканирует и вводит имя. Имена участников передаются распознаванию и разбору поручений, что снижает число ошибок.
5. Находит поручения: что сделать, кому, к какому сроку, кто поручил, и цитату из стенограммы, откуда поручение взято.
6. Переводит устные сроки в даты: «до конца недели» → 25.09.2026. Рядом сохраняется исходная формулировка и правило пересчёта.
7. Составляет краткое содержание: по каждому докладчику показатель, названная проблема и принятое решение.
8. Даёт название совещанию по содержанию разговора.
9. Экспортирует протокол в DOCX: шапка, участники, краткое содержание, таблица поручений, стенограмма приложением.
10. Ведёт статусы: в работе, просрочено, выполнено. Просрочка считается сама.
11. Удаляет совещание полностью: из базы стираются стенограмма, поручения и участники, а аудиофайл и дорожки участников удаляются с диска. Запись не хранится дольше, чем нужно.

---

3. Архитектура

аудио (файл, запись в браузере или дорожки участников)
  └─ ffmpeg            приведение к 16 кГц моно, срез гула, выравнивание громкости
  └─ whisper.cpp       распознавание речи на видеоядре Apple Silicon, локально
  └─ разделение        по паузам либо по дорожкам участников
  └─ склейка дорожек   реплики по времени, чужие голоса отсеиваются по громкости
  └─ Ollama qwen3:4b   поручения, краткое содержание, название совещания
  └─ dates.py          устные сроки в даты, обычным кодом
  └─ SQLite            хранение совещаний, участников, поручений, статусов
  └─ FastAPI           API и веб-интерфейс
  └─ python-docx       протокол в DOCX

Два решения, которые стоит отметить:

• Сроки переводит код, а не модель. Правило должно быть одинаковым каждый раз и объяснимым. Рядом с датой в интерфейсе видно, как она получена.
• Дорожки не смешиваются в один звук. Смешивание складывает шумы и не делает дальний голос громче. Склеивается текст, имя берётся из владельца дорожки.

Подробнее: docs/multitrack.md.

---

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

Слой	Чем
Распознавание речи	whisper.cpp, модель ggml-large-v3-turbo, Metal на Apple Silicon
Языковая модель	Ollama, qwen3:4b, локально
Бэкенд	Python 3, FastAPI, SQLite
Документы	python-docx
QR для отметки участников	segno, генерация офлайн
Интерфейс	HTML и JavaScript без сборки, один файл на страницу

Внешние облачные API не используются. Это требование кейса о закрытом контуре и одновременно главное отличие от Otter и Fireflies. Ключи и учётные записи для проверки не нужны.

---

5. Установка

Требуется macOS с Apple Silicon, Homebrew, около 6 ГБ свободного места.

# инструменты
brew install ffmpeg ollama whisper-cpp

# локальная языковая модель
ollama serve &
ollama pull qwen3:4b

# модель распознавания речи
mkdir -p ~/Desktop/models
curl -L -o ~/Desktop/models/ggml-large-v3-turbo.bin \
  https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3-turbo.bin

# окружение проекта
python3 -m venv .venv
./.venv/bin/pip install fastapi uvicorn python-docx requests python-multipart segno pillow

Первая установка требует интернета для загрузки моделей, около 4 ГБ. Дальше система работает офлайн.

---

6. Запуск

ollama serve &                                   # если ещё не запущен
./.venv/bin/python -m uvicorn backend.main:app --host 0.0.0.0 --port 8000

• Лендинг: http://localhost:8000
• Приложение: http://localhost:8000/app

Порт 0.0.0.0 нужен, чтобы участники могли отметиться со своих телефонов в той же сети.

---

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

Быстрая проверка, около двух минут

1. Открыть http://localhost:8000/app
2. Нажать «Загрузить файл», выбрать samples/meeting_test.wav
3. Дождаться четырёх шагов обработки и статуса «готово»
4. Проверить результат:
   • совещание получило название по содержанию;
   • показано краткое содержание;
   • в списке поручений есть ответственный, срок в виде даты, исходная формулировка срока и цитата из стенограммы;
   • вкладка «Стенограмма» показывает реплики с говорящими.
5. Нажать «Скачать протокол» и открыть полученный DOCX.

Проверка отметки участников и записи с телефонов

1. В приложении «Новое совещание» — появится QR
2. Открыть с телефона в той же сети или ввести участников вручную
3. Участник на своей странице нажимает «Начать запись», в конце дорожка уходит на сервер
4. Ведущий нажимает «Собрать совещание из дорожек участников»

Проверка работы без интернета

Отключить Wi-Fi и повторить быструю проверку. Система продолжает работать: сетевых вызовов в решении нет.

---

8. Параметры окружения

Ключи и внешние учётные записи не требуются. Поведение можно менять переменными:

Переменная	По умолчанию	Что делает
HATTAMA_PROMPT	on	Передаёт распознаванию имена участников, снижает ошибки в именах. В подсказке только имена собственные: длинный текст на одном языке склоняет модель к этому языку и мешает смешанной речи. off отключает
HATTAMA_AUDIO_CLEAN	on	Срез гула техники и выравнивание громкости, помогает участникам вдали от микрофона. off отключает
HATTAMA_MIXED	on	Двухпроходное распознавание для смешанной речи: русский и казахский проходы с выбором варианта по каждой реплике. off оставляет один проход и работает вдвое быстрее
HATTAMA_SECRET	встроенный	Секрет для кода отметки участников

Пути к моделям задаются в backend/transcribe.py (MODEL_TURBO) и backend/extract.py (MODEL, адрес Ollama).

---

9. Структура репозитория

backend/
  main.py         API, база, сценарий обработки, отметка участников, QR
  transcribe.py   подготовка звука, распознавание, говорящие, склейка дорожек
  extract.py      поручения, краткое содержание, название совещания
  dates.py        перевод устных сроков в даты
  export.py       протокол в DOCX
frontend/
  landing.html    лендинг
  index.html      приложение
  join.html       страница отметки участника
  img/            изображения
samples/          демо-запись, стенограммы, текст для проверки речи
docs/             развитие продукта: кабинеты, многодорожечная запись, устройство

---

10. Ограничения, о которых честно

• В режиме одной записи говорящие разделяются по паузам: на перебивках возможны ошибки. Режим с дорожками участников решает это полностью.
• Качество распознавания казахской речи ниже русской: модель turbo ужата ради скорости. Полная large-v3 точнее, требует 3 ГБ места и вдвое больше времени.
• Запись в samples/ синтезирована для тестирования, живых записей совещаний в репозитории нет по соображениям приватности.
• Устройство записи, показанное на лендинге, это концепт: в решение хакатона оно не входит.

---

11. Проверено

23.09.2026. Репозиторий склонирован в пустую папку, зависимости установлены по инструкции выше, сервер запущен, пройден полный сценарий: загрузка записи, распознавание, название совещания, краткое содержание, три поручения с ответственными, сроки переведены в даты, протокол DOCX скачан.

Проверка выполнена на чистой копии, без файлов и настроек из рабочей папки.