О проекте
Команда: Scoundrels
Кейс HackAlem.ai: Коммуникации — Halyk Bank · кейс 2
Стадия: Доведённый продукт
Задача кейса: «Voice Router»: голосовой AI, маршрутизирующий звонки в контакт-центре страховой компании
Суть
Голосовой и текстовый маршрутизатор обращений для вымышленной страховой компании Saqta. Выбирает один или несколько из 40 бизнес-сценариев и отвечает голосом. Панель супервизора показывает маршрут, альтернативы, слоты и задержки.
Как устроено
Голосовой путь: STT (gpt-transcribe) → LLM-маршрутизатор (OpenAI Responses API со Structured Outputs, gpt-6-luna) → ответ по базе знаний и mock-бэкенду Saqta → TTS (gpt-4o-mini-tts) с потоковым воспроизведением. Маршрутизатор выбирает один или несколько из 40 сценариев и 3 системных намерений; темы и слоты сохраняются при переключении между репликами. Поддерживается RU/KK/EN и смешанная речь. Есть eval-скрипты на официальном dev-наборе и holdout, бюджетные лимиты на сессию и прогон, а также режим scaffold без платных вызовов.
Ключевые решения
- Structured Outputs
- multi-intent routing
- slot filling
- topic state tracking
- streaming TTS
- latency p50/p95 tracking
- eval harness
- budget guards
Метрики
104/104 реплик и 40/40 маршрутов на dev-наборе (10 диалогов); 85 Python- и 13 JS-тестов; медиана ожидания озвучки снизилась с 1,91 до 1,18 с
Особенности
Работа разбита на три потока (router, voice, frontend), у каждого свои файлы AGENTS/GEMINI/HANDOFF/TASKS для AI-агентов. Потоковая TTS проверена в A/B-замерах. README прямо признаёт, что цель ≤1,5 с от конца речи до звука не достигнута.
Стек
Python · FastAPI · Pydantic · HTML/CSS/JS · MediaRecorder · Docker · pytest · Node test runner · GitHub Actions
Модели
gpt-6-luna · gpt-transcribe · gpt-4o-mini-tts
Проект создан за 5 часов на финале хакатона HackAlem.ai (23 сентября 2026, Астана). Код — BAITC-Hacks/hack-22e0bf81-scoundrels.
README
README.mdRouteMap — голосовой AI-маршрутизатор
Проект команды Scoundrels для HackAlem AI, трек «Коммуникации», кейс Voice Router от Halyk Bank. RouteMap помогает клиентам вымышленной страховой компании Saqta задать вопрос голосом или текстом и попасть в нужный сценарий.
LLM выбирает один или несколько из 40 бизнес-сценариев и 3 системных намерений. Система сохраняет темы разговора при переключении, использует данные Saqta для ответа и озвучивает его. Панель супервизора показывает маршрут, альтернативы, слоты и задержки. Поддерживаются RU, KK, EN и смешанная речь; интерфейс — RU/KK.
Запуск
Нужны Python 3.11+ и ключ OpenAI. Из корня репозитория:
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements-dev.txt
Скопируйте .env.example в .env, если его ещё нет. Впишите свой
OPENAI_API_KEY, поставьте APP_MODE=live и сохраните модели из примера:
gpt-6-luna, gpt-transcribe, gpt-4o-mini-tts. Ключ хранится только на сервере.
.\.venv\Scripts\python.exe run.py
Откройте localhost:8000, отправьте текст или удерживайте
кнопку микрофона во время речи. API-документация.
На Linux/macOS используйте .venv/bin/python.
По умолчанию APP_MODE=scaffold: интерфейс работает без платных LLM/STT/TTS-вызовов.
Технологии
Python, FastAPI, Pydantic, OpenAI Responses API со Structured Outputs;
HTML/CSS/JavaScript и MediaRecorder. Голосовой путь: STT → LLM-маршрутизатор →
ответ по данным Saqta → TTS. База знаний и тестовые клиенты — из официального
набора case_2/voice_router_dataset/. Node.js и отдельная БД для запуска не нужны.
Проверка
.\.venv\Scripts\python.exe -m pytest -q
# Дополнительно, если установлен Node.js 22.7+:
node --test frontend/tests/*.test.mjs
85 Python-тестов и 13 JS-тестов проходят без API-ключа и расходов. Для ручной проверки
отправьте «Действует ли мой полис?» — ожидается SC25 и запрос данных для проверки.
Голосовой ввод должен вернуть транскрипт, маршрут и озвученный ответ.
На доступном dev-наборе после настройки промпта: 104/104 реплики и 40/40 маршрутов в 10 диалогах. Это результаты на известных данных. Подробнее: оценка маршрутизации, голосовые проверки. Потоковая озвучка начинает воспроизведение до окончания загрузки; замеры и повторение эксперимента.
Ограничения
Это симулятор: реализованы справочные ответы, проверка тестового полиса и обращения; остальные сценарии используют подсказки из каталога. Изменение данных, SMS и передача оператору не выполняются реально. Сессии ограничены 10 репликами и хранятся в памяти. В четырёх браузерных A/B-пробах поток уменьшил медиану ожидания озвучки с 1,91 до 1,18 с. Это только TTS, не вся цепочка: LLM остаётся основной задержкой, цель ≤1,5 с от конца речи до звука пока не достигнута.
Live-вызовы расходуют OpenAI-бюджет. SESSION_BUDGET_USD и RUN_BUDGET_USD
ограничивают локальные резервы запросов; это не точный счёт провайдера.
Авторы коммитов
История коммитов
- 2026-09-23 17:56fix: restore session banner and label demo traces honestlyAlexandrKhvan
- 2026-09-23 17:46merge: integrate verified streaming and audio lifecycle improvementsAlexandrKhvan
- 2026-09-23 17:46fix: guard audio lifecycle and validate performance profilesAlexandrKhvan
- 2026-09-23 17:29perf: stream speech playback and benchmark router profilesAlexandrKhvan
- 2026-09-23 17:01docs: shorten README and document hosting optionsAlexandrKhvan
- 2026-09-23 16:51docs: mark main integration as shippedAlexandrKhvan
- 2026-09-23 16:50feat: integrate live voice demo and jury documentationAlexandrKhvan
- 2026-09-23 16:18merge: integrate frontend workstreamAlexandrKhvan
Все коммиты (31)
- 2026-09-23 16:18merge: integrate LLM and voice workstreamAlexandrKhvan
- 2026-09-23 16:09feat(voice): add multilingual speech adapters and bounded live smokeAlexandrKhvan
- 2026-09-23 16:07docs(frontend): add branded SVG favicon and comprehensive integration guide for backend roleGooses404
- 2026-09-23 15:55feat(router): preserve multi-turn topics and slotsAlexandrKhvan
- 2026-09-23 15:51style(frontend): add #008265 borders for light theme and #E59800 hover effects on all buttonsGooses404
- 2026-09-23 15:24eval(router): record full live results and preserve downstream intentsFrostynncht
- 2026-09-23 15:22feat(frontend): add comprehensive bilingual localization for errors, notices and replay toolsGooses404
- 2026-09-23 15:15feat(router): evaluate and tune official routing setAlexandrKhvan
- 2026-09-23 15:09test(router): record live smoke and harden eval budgetFrostynncht
- 2026-09-23 14:56docs(frontend): add automated asset tests, demo checklist, update TASKS and HANDOFFGooses404
- 2026-09-23 14:55feat(frontend): add bilingual localization, session export/replay and design polishGooses404
- 2026-09-23 14:54feat(frontend): implement tts playback and latency waterfall tracker with p50/p95 metricsGooses404
- 2026-09-23 14:54feat(frontend): add push-to-talk microphone recording and stt transcription handlerGooses404
- 2026-09-23 14:54feat(frontend): establish complete text conversation flow with turn limiter and session lifecycleGooses404
- 2026-09-23 14:54feat(frontend): build supervisor explainability panel for decisions, topics and slotsGooses404
- 2026-09-23 14:54feat(frontend): implement robust api client and scenarios catalog lookupGooses404
- 2026-09-23 14:53merge: bring main into feat/router and resolve role notesFrostynncht
- 2026-09-23 14:46feat(router): add multilingual live smoke evaluationAlexandrKhvan
- 2026-09-23 14:23test(router): add bounded eval tooling and reproducible mock demoFrostynncht
- 2026-09-23 14:13feat(router): implement structured LLM routing and topic stateFrostynncht
- 2026-09-23 14:03feat(router): add structured OpenAI routing foundationAlexandrKhvan
- 2026-09-23 13:50chore: combine LLM and voice ownership and split backend workstreamAlexandrKhvan
- 2026-09-23 13:39chore: scaffold Voice Router and three team workstreamsAlexandrKhvan
Структура репозитория (125 файлов)
.dockerignore .env.example .gitattributes .github/workflows/ci.yml .gitignore AGENTS.md Dockerfile GEMINI.md README.md backend/__init__.py backend/platform/AGENTS.md backend/platform/GEMINI.md backend/platform/HANDOFF.md backend/platform/START_PROMPT.md backend/platform/TASKS.md backend/platform/__init__.py backend/platform/app.py backend/platform/config.py backend/platform/evals/live_smoke.py backend/platform/evals/stream_smoke.py backend/platform/requirements.txt backend/platform/services/__init__.py backend/platform/services/actions.py backend/platform/services/budget.py backend/platform/services/handoff.py backend/platform/services/responses.py backend/platform/sessions.py backend/platform/tests/test_api.py backend/platform/tests/test_live_api.py backend/router/AGENTS.md backend/router/GEMINI.md backend/router/HANDOFF.md backend/router/ROADMAP.md backend/router/START_PROMPT.md backend/router/TASKS.md backend/router/__init__.py backend/router/catalog.py backend/router/conversation.py backend/router/data/README.md backend/router/data/fixtures/scenarios.json backend/router/evals/README.md backend/router/evals/dialogs.py backend/router/evals/holdout_utterances.json backend/router/evals/official.py backend/router/evals/performance.py backend/router/evals/run.py backend/router/evals/smoke_utterances.json backend/router/models.py backend/router/prompting.py backend/router/prompts/router.md backend/router/providers/__init__.py backend/router/providers/openai_provider.py backend/router/requirements.txt backend/router/service.py backend/router/tests/test_conversation.py backend/router/tests/test_dialog_eval.py backend/router/tests/test_eval_runner.py backend/router/tests/test_official_eval.py backend/router/tests/test_openai_provider.py backend/router/tests/test_performance_eval.py backend/router/tests/test_prompting.py backend/router/tests/test_router.py backend/voice/AGENTS.md backend/voice/GEMINI.md backend/voice/HANDOFF.md backend/voice/START_PROMPT.md backend/voice/TASKS.md backend/voice/__init__.py backend/voice/evals/README.md backend/voice/evals/smoke.py backend/voice/stt.py backend/voice/tests/README.md backend/voice/tests/test_adapters.py backend/voice/tts.py case_2/voice_router_dataset/README.kz.md case_2/voice_router_dataset/README.md case_2/voice_router_dataset/README.ru.md case_2/voice_router_dataset/actions.json case_2/voice_router_dataset/dev_utterances.json case_2/voice_router_dataset/dialogs_sample.json case_2/voice_router_dataset/evaluate.py case_2/voice_router_dataset/knowledge_base.json case_2/voice_router_dataset/mock_backend.json case_2/voice_router_dataset/scenarios.json case_2/voice_router_dataset/slots.json compose.yaml contracts/README.md contracts/__init__.py contracts/models.py contracts/tests/test_models.py docs/ACCEPTANCE.md docs/CONTEXT.md docs/DEPLOYMENT.md docs/OWNERSHIP.md docs/PERFORMANCE.md docs/SPEC.md frontend/AGENTS.md frontend/GEMINI.md frontend/HANDOFF.md frontend/INTEGRATION_GUIDE.md frontend/START_PROMPT.md frontend/TASKS.md frontend/index.html frontend/src/api.js frontend/src/app.js frontend/src/audio.js frontend/src/catalog.js frontend/src/favicon.svg frontend/src/i18n.js frontend/src/metrics.js frontend/src/performance.html frontend/src/performance.js frontend/src/replay.js frontend/src/styles.css frontend/src/supervisor.js frontend/tests/DEMO_CHECKLIST.md frontend/tests/README.md frontend/tests/app_activity.test.mjs frontend/tests/audio_stream.test.mjs frontend/tests/supervisor_mode.test.mjs frontend/tests/test_frontend_assets.py pyproject.toml requirements-dev.txt requirements.txt run.py
Обсуждение 0 комментариев
Войдите, чтобы комментироватьПока нет комментариев — будьте первым.