AAYMA
RU
Войти

Voice Router

Студия маршрутизации обращений в контакт-центр: LLM классифицирует реплики клиента, извлекает слоты и выполняет mock-действия с подтверждением…

Рабочий MVP
AI-агентыHackAlemLLMДашбордыКоммуникации
GitHub
Команда «Cathays» 19💬 0 комментариевс 23 сентября 2026 г.

О проекте

Команда: Cathays
Кейс HackAlem.ai: Коммуникации — Halyk Bank · кейс 2
Стадия: Рабочий MVP

Задача кейса: «Voice Router»: голосовой AI, маршрутизирующий звонки в контакт-центре страховой компании

Суть

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

Как устроено

FastAPI-бэкенд с модулями routing (triage, prompt_builder, decision_policy, validator), execution (слоты, state machine, действия с preview и явным подтверждением, защита от двойного выполнения) и grounding (ответы по knowledge_base). Роутинг идёт через OpenAI-совместимый провайдер (gpt-4.1-mini по умолчанию). React-фронтенд показывает решения, извлечённые данные и JSON-трейсы для супервизора. run_evaluation.py прогоняет dev-датасет через штатный evaluator организаторов.

Ключевые решения

  • intent routing
  • slot filling
  • state machine
  • confirmation preview
  • grounded responder
  • trace redaction
  • Spec Kit spec-driven development

Особенности

Разработка по методологии GitHub Spec Kit (constitution → specify → plan → tasks → implement) видна в коммитах и папке specs/. Потенциально опасные действия выполняются только после предпросмотра и подтверждения; повтор не выполняет их дважды.

Стек

Python 3.12 · FastAPI · uvicorn · pytest · React · TypeScript · Vite · Tailwind CSS · shadcn/ui

Модели

gpt-4.1-mini

Проект создан за 5 часов на финале хакатона HackAlem.ai (23 сентября 2026, Астана). Код — BAITC-Hacks/hack-ea9d4245-cathays.

README

README.md

Voice Router

Run

Run these commands from the repository root. The backend now lives in apps/web/backend.

  1. Create and activate a Python 3.12+ virtual environment: python -m venv .venv, then .\.venv\Scripts\Activate.ps1 in PowerShell.
  2. Install backend and test dependencies: python -m pip install -e "./apps/web/backend[dev]".
  3. Copy apps/web/backend/.env.example to apps/web/backend/.env only if the .env file does not already exist. Set VOICE_ROUTER_API_KEY (or OPENAI_API_KEY). OpenAI's base URL and gpt-4.1-mini are the defaults. Dataset paths resolve from the repository root, so starting from a different directory does not break them.
  4. Run python -m uvicorn app.main:app --app-dir apps/web/backend --reload.
  5. In a separate terminal, run npm install --prefix apps/web then npm run dev --prefix apps/web.

The web app is a responsive routing studio built with Tailwind CSS and shadcn/ui. Its development server proxies /api to http://127.0.0.1:8000. Restart Vite after changing its configuration. For production, serve /api through your backend reverse proxy, or set VITE_API_URL when building and set VOICE_ROUTER_CORS_ORIGINS to the frontend origin (comma-separated when needed). Localhost ports 5173 and 5174 are allowed by default.

Use Load an example to explore the UI without calling a provider. Live conversations show routing decisions, extracted details, execution status, and JSON traces. Session history lasts for the current browser tab; use Export session to save a conversation before reloading. Voice input is not configured; the studio supports text input.

Checks: python -m pytest apps/web/backend/tests -q, npm run build --prefix apps/web, and npm test --prefix apps/web. Backend tests block live provider requests and use synthetic data.

Consequential actions are mock operations. They require a conversation-bound preview and explicit confirmation; cancellation and retries cannot execute the same preview twice. A preview created on turn 10 can still be confirmed or cancelled. Other new messages are limited to 10 turns.

Run $env:PYTHONIOENCODING='utf-8'; python apps/web/backend/run_evaluation.py in PowerShell to create predictions and invoke the checked-in evaluator. This makes paid provider requests for the development dataset. Results are written to the repository's artifacts directory. The checked-in dataset is authoritative. Hackathon team repository for Cathays

GitHub

BAITC-Hacks/hack-ea9d4245-cathays
Звёзды
⭐ 1
Форки
0
Язык
PowerShell
Последний push
в прошлом месяце
Коммиты
10
Авторы
2
Файлы
131
Ветки
1

Авторы коммитов

Bektas 6rinH1 4

История коммитов

  • 2026-09-23 17:57FInal editsBektas
  • 2026-09-23 17:29Added frontendBektas
  • 2026-09-23 16:51improvementsrinH1
  • 2026-09-23 16:05FeaturesrinH1
  • 2026-09-23 15:52speckit-implement and speckit-convergerinH1
  • 2026-09-23 15:35Speckit-plan and speckit-tasksrinH1
  • 2026-09-23 15:16Speckit dataset patchBektas
  • 2026-09-23 14:48speckit specify was usedBektas
Все коммиты (10)
  • 2026-09-23 14:19ratify Voice Router constitution v1.0.0Bektas
  • 2026-09-23 13:47Installed the dataset and speckitBektas
Структура репозитория (131 файлов)
.agents/skills/speckit-analyze/SKILL.md
.agents/skills/speckit-checklist/SKILL.md
.agents/skills/speckit-clarify/SKILL.md
.agents/skills/speckit-constitution/SKILL.md
.agents/skills/speckit-converge/SKILL.md
.agents/skills/speckit-implement/SKILL.md
.agents/skills/speckit-plan/SKILL.md
.agents/skills/speckit-specify/SKILL.md
.agents/skills/speckit-tasks/SKILL.md
.agents/skills/speckit-taskstoissues/SKILL.md
.gitignore
.specify/.gitignore
.specify/init-options.json
.specify/integration.json
.specify/integrations/codex.manifest.json
.specify/integrations/speckit.manifest.json
.specify/memory/.constitution-template.json
.specify/memory/constitution.md
.specify/scripts/powershell/check-prerequisites.ps1
.specify/scripts/powershell/common.ps1
.specify/scripts/powershell/create-new-feature.ps1
.specify/scripts/powershell/resolve-template.ps1
.specify/scripts/powershell/setup-plan.ps1
.specify/scripts/powershell/setup-tasks.ps1
.specify/templates/checklist-template.md
.specify/templates/constitution-template.md
.specify/templates/plan-template.md
.specify/templates/spec-template.md
.specify/templates/tasks-template.md
.specify/workflows/speckit/workflow.yml
.specify/workflows/workflow-registry.json
README.md
apps/web/backend/.env.example
apps/web/backend/app/__init__.py
apps/web/backend/app/api/errors.py
apps/web/backend/app/api/schemas.py
apps/web/backend/app/dataset/repository.py
apps/web/backend/app/dataset/validator.py
apps/web/backend/app/dialogue/service.py
apps/web/backend/app/evaluation/projection.py
apps/web/backend/app/evaluation/reporting.py
apps/web/backend/app/evaluation/runner.py
apps/web/backend/app/execution/actions.py
apps/web/backend/app/execution/identity.py
apps/web/backend/app/execution/service.py
apps/web/backend/app/execution/slots.py
apps/web/backend/app/execution/state_machine.py
apps/web/backend/app/grounding/responder.py
apps/web/backend/app/main.py
apps/web/backend/app/routing/decision_policy.py
apps/web/backend/app/routing/llm_client.py
apps/web/backend/app/routing/prompt_builder.py
apps/web/backend/app/routing/provider_client.py
apps/web/backend/app/routing/service.py
apps/web/backend/app/routing/triage.py
apps/web/backend/app/routing/validator.py
apps/web/backend/app/settings.py
apps/web/backend/app/tracing/redaction.py
apps/web/backend/app/tracing/service.py
apps/web/backend/app/tracing/timers.py
apps/web/backend/pyproject.toml
apps/web/backend/run_evaluation.py
apps/web/backend/tests/conftest.py
apps/web/backend/tests/contract/test_dataset_validator.py
apps/web/backend/tests/contract/test_routing_validator.py
apps/web/backend/tests/integration/test_confirmation_api.py
apps/web/backend/tests/integration/test_regressions.py
apps/web/backend/tests/unit/test_decision_policy.py
apps/web/backend/tests/unit/test_execution_safety.py
apps/web/backend/tests/unit/test_grounded_responder.py
apps/web/backend/tests/unit/test_prediction_projection.py
apps/web/backend/tests/unit/test_regressions.py
apps/web/backend/tests/unit/test_timers.py
apps/web/components.json
apps/web/index.html
apps/web/package-lock.json
apps/web/package.json
apps/web/public/favicon.svg
apps/web/src/App.test.tsx
apps/web/src/App.tsx
apps/web/src/api/client.ts
apps/web/src/components/ui/badge.tsx
apps/web/src/components/ui/button.tsx
apps/web/src/components/ui/card.tsx
apps/web/src/components/ui/tabs.tsx
apps/web/src/components/ui/textarea.tsx
apps/web/src/features/customer/CustomerConversation.tsx
apps/web/src/features/supervisor/SupervisorTrace.tsx
apps/web/src/index.css
apps/web/src/lib/trace.test.ts
apps/web/src/lib/trace.ts
apps/web/src/lib/utils.ts
apps/web/src/main.tsx
apps/web/tsconfig.json
apps/web/vite.config.ts
specs/001-voice-router/checklists/requirements.md
specs/001-voice-router/contracts/http-api.md
specs/001-voice-router/data-model.md
specs/001-voice-router/plan.md
specs/001-voice-router/quickstart.md
specs/001-voice-router/research.md
specs/001-voice-router/spec.md
specs/001-voice-router/tasks.md
voice_router_dataset/__MACOSX/._case_2
voice_router_dataset/__MACOSX/case_2/._.DS_Store
voice_router_dataset/__MACOSX/case_2/._voice_router_dataset
voice_router_dataset/__MACOSX/case_2/voice_router_dataset/._.DS_Store
voice_router_dataset/__MACOSX/case_2/voice_router_dataset/._README.kz.md
voice_router_dataset/__MACOSX/case_2/voice_router_dataset/._README.md
voice_router_dataset/__MACOSX/case_2/voice_router_dataset/._README.ru.md
voice_router_dataset/__MACOSX/case_2/voice_router_dataset/._actions.json
voice_router_dataset/__MACOSX/case_2/voice_router_dataset/._dev_utterances.json
voice_router_dataset/__MACOSX/case_2/voice_router_dataset/._dialogs_sample.json
voice_router_dataset/__MACOSX/case_2/voice_router_dataset/._evaluate.py
voice_router_dataset/__MACOSX/case_2/voice_router_dataset/._knowledge_base.json
voice_router_dataset/__MACOSX/case_2/voice_router_dataset/._mock_backend.json
voice_router_dataset/__MACOSX/case_2/voice_router_dataset/._scenarios.json
voice_router_dataset/__MACOSX/case_2/voice_router_dataset/._slots.json
voice_router_dataset/case_2/.DS_Store
voice_router_dataset/case_2/voice_router_dataset/.DS_Store
voice_router_dataset/case_2/voice_router_dataset/README.kz.md
voice_router_dataset/case_2/voice_router_dataset/README.md
voice_router_dataset/case_2/voice_router_dataset/README.ru.md
voice_router_dataset/case_2/voice_router_dataset/actions.json
voice_router_dataset/case_2/voice_router_dataset/dev_utterances.json
voice_router_dataset/case_2/voice_router_dataset/dialogs_sample.json
voice_router_dataset/case_2/voice_router_dataset/evaluate.py
voice_router_dataset/case_2/voice_router_dataset/knowledge_base.json
voice_router_dataset/case_2/voice_router_dataset/mock_backend.json
voice_router_dataset/case_2/voice_router_dataset/scenarios.json
voice_router_dataset/case_2/voice_router_dataset/slots.json

Обсуждение 0 комментариев

Войдите, чтобы комментировать

Пока нет комментариев — будьте первым.