🌐 Сайт: https://owlpeer.com/

📞 Позвонить Butaq: +1 (201) 231-1497

🎬 Демо: Открыть демо

Butaq — голосовой AI-помощник страховой службы

Клиент описывает проблему своими словами — Butaq выбирает сценарий, уточняет детали и отвечает на русском или казахском языке.

Проект для кейса Voice Router: голосовой маршрутизатор обращений в страховую компанию. Он помогает клиенту разобраться с полисом, оплатой, возвратом или страховым случаем, а команде контакт-центра — настраивать сценарии и видеть, почему AI выбрал конкретное направление обращения.

Голосовой интерфейс · Главная · Быстрый запуск · Проверка для жюри · Ограничения

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

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

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

Butaq сопоставляет запрос с каталогом сценариев через LLM, учитывает контекст беседы и запрашивает уточнение при недостаточной уверенности. Для демонстрации доступны браузерный диалог и панель администратора; для входящих телефонных звонков реализован отдельный адаптер.

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

Возможность	Что доступно в текущей версии
Голосовой диалог	Страница /voice/, микрофон, голосовой ответ и текстовые подписи через GPT-Live и WebRTC
Текстовый ввод	Сообщения в интерфейсе, в том числе во время голосового сеанса; отдельный HTTP API
Русский и казахский	Инструкции агентам и примеры данных для двух языков, смешанной речи и переключения языка
AI и workflow	Router выбирает сценарий и извлекает слоты; детерминированный Workflow проверяет параметры и подтверждение; Resolution готовит ответ по фактам и результатам действий
Контекст	Активная и отложенные темы, извлечённые параметры, продолжение и смена сценария
Прерывание	Остановка воспроизведения и отмена незавершённой работы при прерывании разговора
Объяснение решения	Сценарий, причина выбора, уверенность, альтернативы и времена этапов в ответе API; карточки решения в интерфейсе
Работа с данными	Чтение, расчёты и синтетическая симуляция 31 действия стартового набора; необратимые действия требуют preview и явного подтверждения
Администрирование	Редактирование сценариев, промптов, модели, workflow-политик и порога уверенности; импорт JSON-каталога
Вход администратора	Токен, passkey через WebAuthn и распознавание лица через InsightFace
Телефонный адаптер	Входящий звонок SignalWire → GPT-Live → общий сервис Router/Resolution; выключен по умолчанию

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

Пример входного запроса: «Хочу оформить ОГПО».

1. Ввод. Пользователь начинает голосовой разговор или вводит текст. В основном голосовом режиме звук идёт между браузером и GPT-Live по WebRTC; сервер управляет сеансом и получает события разговора.
2. Выбор сценария. Страховой вопрос передаётся Router вместе с контекстом беседы и актуальным каталогом из PostgreSQL. Агент определяет язык, намерение, параметры и возможные отложенные темы.
3. Проверка решения. Код проверяет структурированный ответ, допустимость ID и порог уверенности. Результат — route (выбран сценарий), clarify (нужно уточнение) или handoff (нужна помощь оператора).
4. Выполнение сценария. Workflow валидирует собранные слоты, запрашивает недостающие и запускает зарегистрированные action adapters. Необратимые действия сначала получают preview и явное подтверждение. Resolution формирует ответ только по данным и результатам; simulate не изменяет исходный mock backend.
5. Результат. Пользователь получает объяснение; голосовой слой озвучивает ответ, интерфейс показывает подписи и решение маршрутизатора. Следующая реплика использует контекст текущего сеанса.

Для файлового API путь отдельный: аудиофайл → транскрипция → Router → Resolution → синтез речи. Для текста через HTTP синтез включается параметром synthesize.

Технологии

Область	Технологии из репозитория
Backend	Python ≥ 3.10; Docker-образ на Python 3.12; FastAPI, Pydantic, Uvicorn
Frontend	TypeScript, Next.js 16, React 19, Tailwind CSS 4, Radix UI, Lucide, OGL
AI-агенты	OpenAI API, OpenAI Agents SDK; модель Router/Resolution задаётся настройками
Основной голосовой режим	GPT-Live, WebRTC, WebSocket для управления и событий
Дополнительный аудиопайплайн	OpenAI transcription/TTS, Web Audio API, AudioWorklet
Хранение	PostgreSQL 16, SQLAlchemy, Alembic
Аутентификация администратора	WebAuthn, InsightFace, ONNX Runtime
Телефония	SignalWire cXML, SIP/TLS, OpenAI Live; пакет telephony/
Развёртывание и проверки	Docker Compose, Caddy, pytest, Node.js test runner, TypeScript typecheck

Модели по умолчанию в .env.example:

Назначение	Переменная	Значение
Router и Resolution	ROUTER_MODEL	gpt-5.6-terra
Голосовой разговор в браузере	MULTI_AGENT_LIVE_MODEL	gpt-live-1
Потоковая транскрипция дополнительного WebSocket-режима	MULTI_AGENT_TRANSCRIBE_MODEL	gpt-live-transcribe
Распознавание загруженного аудио	V2V_TRANSCRIBE_MODEL	gpt-transcribe
Отдельный синтез речи	V2V_TTS_MODEL	gpt-4o-mini-tts

Это значения конфигурации проекта. Для запуска требуется доступ к выбранным моделям в используемом аккаунте API.

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

flowchart LR
    B[Браузер: голос и текст] <-->|WebRTC: аудио| L[OpenAI GPT-Live]
    B <-->|HTTP / WebSocket| C[Caddy]
    A[Панель администратора] --> C
    C <--> F[FastAPI]
    F <-->|Управление голосовым сеансом| L
    F --> S[RouterService]
    S --> R[Router: выбор сценария]
    R --> V[Проверка решения]
    V --> W[Workflow: слоты, подтверждение, симуляция действий]
    W --> Q[Resolution: ответ по проверенным данным]
    Q --> S
    S <--> D[(PostgreSQL: каталог и настройки)]
    P[SignalWire: входящий звонок] --> T[Телефонный адаптер]
    T <--> L
    T --> S

Два агента используют общий сервис для браузера, HTTP-запросов и телефонии. Каталог и настройки сохраняются в PostgreSQL; изменения администратора учитываются при следующем обращении. Контекст активных разговоров хранится в памяти процесса backend.

app/                         FastAPI, API, сервис маршрутизации
├── api/                     Текст, голос, потоковые сеансы, администрирование
├── db/                      Модели БД, репозиторий, миграции Alembic
├── phone/                   Адаптер входящих звонков SignalWire
└── data/                    Демокаталог и дополнительные синтетические наборы
multi-agent/src/multi_agent/  Router, Resolution, контекст, инструменты, Live
v2v/                         Общий клиент OpenAI и аудиопайплайн
faceid/                      Распознавание лица и хранение шаблонов
telephony/                   Библиотека телефонии и её тесты
frontend/                    Next.js: главная, /voice/, /admin/, /telephony/
case_2/voice_router_dataset/  Отдельный датасет кейса Saqta Insurance
tests/                       Тесты приложения и интеграции с PostgreSQL

Описание AI-пайплайна — в multi-agent/README.md, подключения звонков — в docs/telephony.md.

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

1. Подготовить окружение

Нужны Docker с Compose v2, доступ к интернету для сборки и ключ OpenAI API. Команды выполняются из корня клонированного репозитория. Локальные Python и Node.js для Docker-запуска не требуются.

# Для новой установки. Если .env уже существует, отредактируйте его.
cp .env.example .env

Заполните в .env:

V2V_API_KEY=ваш-ключ-api
ROUTER_ADMIN_TOKEN=ваш-длинный-случайный-токен
POSTGRES_PASSWORD=ваш-пароль-postgresql

Для локального запуска оставьте ROUTER_WEBAUTHN_ORIGIN=http://localhost:3000, localhost в FRONTEND_ORIGINS и TELEPHONY_ENABLED=false. Полный список настроек с пояснениями — в .env.example. Ключи хранятся на backend; .env не следует добавлять в Git.

2. Собрать и запустить

docker compose up --build -d
docker compose ps

Эквивалентная команда при установленном Make — make up.

Compose запускает PostgreSQL, backend и frontend под Caddy. Backend автоматически применяет миграции. При старте пустой каталог заполняется полным стартовым набором из case_2/voice_router_dataset/; существующий каталог и правки сохраняются.

3. Открыть приложение

Страница или сервис	Локальный адрес
Главная	http://localhost:3000/
Голосовой и текстовый интерфейс	http://localhost:3000/voice/
Панель администратора	http://localhost:3000/admin/
Swagger UI	http://localhost:8000/docs
Проверка backend	http://localhost:8000/health
PostgreSQL для локальных инструментов	localhost:5433, база butaq, пользователь butaq

Для первого входа в панель используйте ROUTER_ADMIN_TOKEN. После входа можно зарегистрировать passkey или лицо. Микрофону и камере нужно разрешение браузера; для голосового режима используйте localhost или HTTPS.

Compose также занимает порты 80 и 443 для Caddy. Они должны быть свободны, как и 3000, 8000 и 5433.

4. Управлять сервисами

docker compose logs --tail=100 backend  # Диагностика backend
docker compose logs -f                # Логи всех сервисов
docker compose down                   # Остановка с сохранением тома БД

После изменения .env пересоздайте backend: docker compose up -d --build backend. Значения ROUTER_MODEL и ROUTER_CONFIDENCE_THRESHOLD из окружения инициализируют только пустые настройки: на существующей базе меняйте их через /admin/settings/.

Для своего публичного домена обновите frontend/Caddyfile, FRONTEND_ORIGINS и ROUTER_WEBAUTHN_ORIGIN. Последний должен точно совпадать с origin браузера для passkey и операций администратора с cookie.

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

Демонстрация для жюри

Сценарий рассчитан на стартовый каталог case_2/voice_router_dataset/ и настроенный ключ API.

1. Проверьте доступность backend и загрузку каталога:

   curl -fsS http://localhost:8000/health
   # {"status":"ok"}
   
   curl -fsS http://localhost:8000/router/scenarios
   # На новой установке — массив из 40 сценариев.
   

2. Откройте http://localhost:3000/voice/. При первом обращении загрузится стартовый каталог из 40 сценариев. Нажмите Talk to Butaq и скажите: «Хочу оформить ОГПО». Агент последовательно запросит регион, тип машины, ИИН водителей, госномер и телефон, покажет preview и попросит подтверждение. Карточка справа отображает собранные слоты и действия.

3. Проверьте собранные слоты, preview и подтверждение в панели трассировки. Смените язык на казахский и тему разговора, затем вернитесь к отложенному вопросу.

4. Убедитесь, что результат обозначен как синтетический, без обещания реального выпуска полиса или соединения с оператором.

Успешный /health подтверждает ответ процесса, но не проверяет доступ к моделям или передачу аудио.

Проверка через API без микрофона

curl -sS http://localhost:8000/router/text \
  -H 'Content-Type: application/json' \
  -d '{"session_id":"jury-demo","text":"Хочу оформить ОГПО","synthesize":false}'

Ответ содержит transcript, reply, action, scenario_id, confidence, reason, alternatives, pending_scenario_ids, language и timings. Workflow также возвращает workflow_status, collected_slots, missing_slots, confirmation_required, action_trace и completed. Для продолжения разговора используйте тот же session_id, для нового — другое значение. synthesize:false отключает озвучку; обращения к LLM остаются платными.

API	Назначение
POST /router/text	Текстовый запрос; опциональная озвучка
POST /router/voice	Аудиофайл в поле audio и session_id, формат multipart/form-data
WS /router/live	Управление основным WebRTC-разговором и события интерфейса
WS /router/stream	Дополнительный потоковый протокол для текста и аудио
GET /router/scenarios	Активный каталог
GET /router/sessions/{session_id}	Контекст браузерного/текстового сеанса
POST /router/admin/catalog/import-files	Импорт каталога с авторизацией администратора

Тесты и оценка

Для локальных тестов нужны Python с venv, Node.js (в Docker используется версия 22) и npm. Установка Python-зависимостей может потребовать компилятор и CMake для InsightFace; состав системных зависимостей указан в Dockerfile backend.

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'
TELEPHONY_ENABLED=false python -m pytest -q

Без TEST_DATABASE_URL тесты с PostgreSQL пропускаются. Для их запуска на локальной БД из Compose подставьте пароль из .env (специальные символы в URL нужно кодировать):

TEST_DATABASE_URL='postgresql+psycopg://butaq:YOUR_POSTGRES_PASSWORD@localhost:5433/butaq' \
  TELEPHONY_ENABLED=false python -m pytest -q

Тесты БД создают и удаляют отдельную схему. Основной набор использует заглушки AI и аудио; он проверяет логику приложения, а не качество реальных ответов моделей.

# Из корня репозитория: проверки frontend в отдельном подкаталоге.
(cd frontend && npm ci && npm run typecheck && npm run test:voice)

# Библиотека телефонии имеет отдельный набор тестов.
(cd telephony && TELEPHONY_ENABLED=false PYTHONPATH=. python -m pytest -q)

# Просмотр демонабора без API-вызовов.
python app/data/demo/evaluate.py --limit 48

# Официальный live-прогон: 104 реплики и 10 диалогов, платные вызовы модели.
python case_2/voice_router_dataset/evaluate_live.py \
  --base-url http://localhost:8000 --dialogs --report /tmp/butaq-live-report.json

Результаты отдельных разработческих прогонов сохранены в multi-agent/evals/. Они не являются оценкой на скрытом наборе жюри и не подтверждают гарантированную точность или задержку.

Подробная последовательность настройки, импорта и демонстрации приведена в demo runbook, а проверка по исходному ТЗ — в матрице соответствия.

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

• При первом запуске backend пустая база атомарно заполняется всеми JSON-данными из case_2/voice_router_dataset/: 40 сценариями, 43 слотами, 31 действием, knowledge base, синтетическим backend, 104 тестовыми репликами и 10 диалогами. Повторный запуск не перезаписывает правки; после seed источником истины становится PostgreSQL.
• В app/data/prod/{auto,health,travel}/ лежат три независимых синтетических набора (авто-, медицинское и туристическое страхование). Они не загружаются автоматически: администратор может импортировать один согласованный набор через POST /router/admin/catalog/import-files. Подробности — в описании данных.
• Внешний OpenAI API нужен для распознавания речи, работы агентов и озвучки; доступность и стоимость зависят от выбранных моделей и учётной записи. InsightFace при первом использовании загружает локальную модель распознавания лиц. Исходный шаблон главной страницы также использует внешние медиа- и шрифтовые ресурсы.
• Интеграция с SignalWire/OpenAI для входящих звонков описана в docs/telephony.md, и включается через TELEPHONY_ENABLED=true после настройки credentials и вебхуков.

Для смены набора откройте /admin/import/ и загрузите согласованные JSON-файлы, включая сценарии, слоты, действия, knowledge base и mock backend. Импорт заменяет активный каталог и справочные данные; для экспериментов используйте отдельный экземпляр. Настройки модели и промпты сохраняются.

Главная страница использует внешние медиаресурсы; сведения об исходных шаблонах и лицензиях находятся в frontend/ATTRIBUTION.md.

Ограничения

• Демонстрационные операции. Workflow выполняет чтение, расчёты, preview и симуляцию действий. simulate не изменяет mock backend и не выполняет оплату, выпуск, отмену, отправку или запись в реальной системе.
• Передача оператору. handoff сообщает о необходимости помощи человека; фактический перевод звонка и исходящие звонки не реализованы.
• Зависимость от провайдеров. Голосовой режим требует совместимого браузера, разрешения на микрофон, сети и доступных моделей. Наличие адаптера SignalWire и тестов с заглушками не подтверждает успешный реальный звонок.
• Память сеансов. Активные разговоры и звонки хранятся в одном процессе и теряются при перезапуске. Общего хранилища сеансов для нескольких backend-процессов нет.
• Качество и измерения. Уверенность — оценка модели, а не откалиброванная вероятность. Нет подтверждённой метрики на скрытом наборе жюри или гарантии задержки. В Live-режиме времена Router/Resolution не равны времени до первого слышимого ответа; нули для отдельных STT/TTS-этапов не означают мгновенное распознавание и озвучку.
• Аутентификация по лицу. Сопоставление изображения само по себе не подтверждает присутствие живого человека. Проверки OpenAI assist опциональны и выключены по умолчанию; также доступен вход по passkey.
• Разные наборы данных. Демоидентификаторы DEMO-* и сценарии S* относятся к каталогу Butaq. Они не совпадают с SC* и записями Saqta. Используйте примеры и проверки именно активного каталога; новый набор действий требует совместимых action adapters.

Развёрнутая версия

В конфигурации Caddy и документации развёртывания телефонии указан домен owlpeer.com:

• Главная страница
• Голосовой интерфейс
• Панель администратора

Адреса подтверждаются конфигурацией репозитория. Текущая доступность сервера, состав загруженного каталога и работоспособность платных AI-вызовов при подготовке этого README не проверялись. Для воспроизводимой демонстрации используйте локальный запуск и сценарий проверки выше.