⚙️ Cymbal Life — модульные MCP-инструменты для интеллектуальных киосков отделений, актуарный движок и аналитика BigQuery APM

Платформа корпоративного класса с развязанной архитектурой, объединяющая модульные MCP-инструменты, актуарный движок принятия решений и аналитику производительности BigQuery APM для интеллектуальных киосков в отделениях Cymbal Life. Построена на базе Google Agent Development Kit (ADK), Model Context Protocol (MCP), Google AlloyDB for PostgreSQL и Google BigQuery.

Сервис предоставляет модульные микросервисы для выполнения инструментов, запросы к AlloyDB через VPC за время менее 5 мс, сравнения «заём против расторжения полиса» с актуарными расчётами в реальном времени, генерацию VIP-талонов очереди в отделениях, а также комплексный мониторинг производительности приложений в BigQuery (APM).

🏛️ Высокоуровневая архитектура системы

Обзор архитектуры

Система организована в виде четырёх отдельных операционных слоёв:

1. Клиентский уровень и уровень киосков в отделениях:

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

   • Процессор AudioWorklet: захват линейного аудиопотока PCM с частотой 16 кГц с микрофонов отделения.

   • Монитор телеметрии киоска в реальном времени: отображает текущие вызовы функций, серверные задержки и аргументы инструментов.

2. Шлюз потоковой передачи в реальном времени и ядро ADK-агента (Cloud Run):

   • FastAPI Async WebSocket Bridge (/ws/live): проксирует двунаправленные аудио- и видеопотоки в Vertex AI Gemini Live API.

   • Виртуальный консультант отделения на базе ADK ("Priya"): координирует намерения клиента, подтверждает личность держателя полиса и выполняет профильные инструменты.

   • Транслятор событий телеметрии в реальном времени (_notify_ui): отправляет на экран киоска результаты запросов к БД и карточки актуарных расчётов.

3. Уровень модульных инструментов Model Context Protocol (MCP):

   • Микросервис policy_tools: выполняет SQL-запросы к AlloyDB в реальном времени для получения KYC-данных клиента, характеристик плана и общей суммы уплаченных взносов.

   • Движок принятия решений actuarial_tools: вычисляет точное финансовое соотношение между потерями при расторжении полиса (-₹4.5L) и мгновенным займом в киоске (₹4.8L @ 8.5%).

   • Операционный микросервис branch_tools: генерирует VIP-талоны эскалации (#RET-04), назначает кабинет 2 руководителя отделения и отправляет цифровые талоны через WhatsApp.

4. Корпоративный уровень данных, аналитики APM и омниканальности:

   • Google AlloyDB for PostgreSQL: корпоративный кластер баз данных, управляющий KYC-данными клиентов, активными полисными договорами, графиками расторжения и талонами эскалации через VPC-запросы со временем ответа менее 5 мс.

   • BigQuery APM и аналитический комплект агентов: записывает пошаговые траектории агентов, задержки инструментов, потребление токенов и воронки конверсии удержания.

   • Twilio WhatsApp Business API: доставляет цифровые VIP-талоны и схемы маршрутов к кабинетам отделений на мобильный номер клиента.

Related MCP server: Consignado MCP Local

🧰 Каталог модульных MCP-инструментов

Микросервисы инструментов расположены в каталоге backend/tools/:

📊 BigQuery APM и аналитика агентов

Платформа включает полный комплект мониторинга производительности приложений BigQuery (APM), описанный в docs/ANALYTICS_QUERIES.md:

• Аудит траекторий сессий и выполнения инструментов: отслеживает пошаговые вызовы инструментов и длительность их выполнения.

• Воспринимаемая задержка и P95-распределение: контролирует сквозную задержку «голос-инструмент» (цель <150 мс).

• Конверсия удержания и спрос на полисssuale займы: измеряет, сколько клиентов с намерением расторгнуть полис переходят в мгновенные займы киосков.

• Очередь отделений и эскалация VIP-талонов: отслеживает время решения по эскалированным талонам во всех кабинетах отделений.

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

cymbal-kiosk-tools-apm/
├── docs/
│   ├── architecture.jpg        # High-level architecture block diagram
│   ├── ARCHITECTURE.md         # Full enterprise architecture specification
│   └── ANALYTICS_QUERIES.md    # BigQuery APM SQL queries & trajectory audit
├── pyproject.toml              # Dependencies (google-adk, fastapi, psycopg2-binary, uvicorn)
├── requirements.txt            # Python dependencies
├── run.sh                      # Local startup script
├── Dockerfile                  # Production container spec
├── .gitignore
├── .env.example                # Environment configuration template
├── backend/
│   ├── __init__.py
│   ├── agent.py                # ADK Agent definition & retention prompt
│   ├── database.py             # Google AlloyDB PostgreSQL connector (psycopg2)
│   ├── mcp_tools.py            # MCP tools facade & WebSocket telemetry broadcaster
│   ├── analytics.py            # BigQuery agent analytics plugin
│   ├── avatar.png              # Assistant avatar asset
│   ├── server.py               # FastAPI WebSocket /ws/live endpoint
│   └── tools/                  # Modular MCP Tool Microservices
│       ├── __init__.py
│       ├── policy_tools.py     # Policy lookup microservice
│       ├── actuarial_tools.py  # Actuarial decision engine
│       └── branch_tools.py     # VIP escalation & WhatsApp dispatcher
└── frontend/
    ├── index.html              # Kiosk terminal touch interface
    ├── style.css               # Cymbal Life corporate styling
    ├── app.js                  # WebSocket client & telemetry renderer
    └── dashboard.html          # Executive APM Analytics Dashboard

🚀 Быстрый старт

Предварительные требования

• Python: 3.11 — 3.13

• Google Cloud SDK (gcloud): настроенный с активным проектом GCP.

• Google AlloyDB for PostgreSQL: допустимый кластер со схемами клиентов и полисов.

Шаг 1: Клонируйте репозиторий и настройте окружение

git clone https://github.com/niteshwalia0124/cymbal-kiosk-tools-apm.git
cd cymbal-kiosk-tools-apm

# Create .env from template
cp .env.example .env

Настройте переменные в своём файле .env:

GOOGLE_GENAI_USE_VERTEXAI=true
GOOGLE_CLOUD_PROJECT=your-gcp-project-id
GOOGLE_CLOUD_LOCATION=us-central1
PORT=8080
AVATAR_NAME=Priya

# AlloyDB / Cloud SQL PostgreSQL Connection
DB_USER=postgres
DB_PASS=your-database-password
DB_NAME=postgres
DB_HOST=10.48.19.2
DB_PORT=5432

# Twilio WhatsApp (Optional)
TWILIO_ACCOUNT_SID=
TWILIO_AUTH_TOKEN=
TWILIO_WHATSAPP_FROM=whatsapp:+14155238886

# BigQuery Agent Analytics
BIGQUERY_PROJECT_ID=your-gcp-project-id
BIGQUERY_DATASET_ID=cymbal_kiosk_analytics
BIGQUERY_TABLE_ID=agent_trajectory_logs

Выполните вход в Google Cloud:

gcloud auth application-default login
gcloud config set project your-gcp-project-id

Шаг 2: Локальный запуск

chmod +x run.sh
./run.sh

Откройте http://localhost:8080 в браузере, чтобы запустить инструменты киоска и телеметрию.

🐳 Развёртывание в Cloud Run

Разверните сервис модульных инструментов в Google Cloud Run с VPC-пирингом для AlloyDB:

export PROJECT_ID=$(gcloud config get-value project)
export REGION="us-central1"
export SERVICE_NAME="cymbal-kiosk-tools-apm"

gcloud run deploy $SERVICE_NAME \
  --source . \
  --region $REGION \
  --project $PROJECT_ID \
  --allow-unauthenticated \
  --set-env-vars GOOGLE_CLOUD_PROJECT=$PROJECT_ID,GOOGLE_CLOUD_LOCATION=$REGION,DB_HOST=10.48.19.2 \
  --vpc-connector="projects/$PROJECT_ID/locations/$REGION/connectors/kiosk-vpc-connector" \
  --memory 2Gi \
  --cpu 2 \
  --timeout 3600

📄 Лицензия

Проект распространяется под лицензией Apache 2.0 — подробности в файле LICENSE.