⚙️ Cymbal Life — Herramientas MCP modulares para quioscos de sucursal inteligente, Motor Actuarial y Análisis APM en BigQuery

Una plataforma empresarial y desacoplada de Herramientas MCP modulares, Motor de Decisión Actuarial y Análisis APM en BigQuery para los quioscos de sucursal inteligente de Cymbal Life, construida sobre Google Agent Development Kit (ADK), Model Context Protocol (MCP), Google AlloyDB for PostgreSQL y Google BigQuery.

Este servicio ofrece microservicios de ejecución de herramientas modulares, consultas de bases de datos VPC contra AlloyDB en menos de 5 ms, comparaciones actuariales de latencia real entre préstamo y rescate, generación de tickets VIP de cola en sucursal y monitoreo completo del rendimiento de aplicaciones (APM) en BigQuery.

🏛️ Arquitectura del Sistema de Alto Nivel

Resumen de la Arquitectura

El sistema se organiza en cuatro capas operativas distintas:

1. Nivel de Cliente y Quiosco en Sucursal:

   • Interfaz táctil del quiosco inteligente: Pantalla táctil de alta resolución que muestra tarjetas de desglose de pólizas en tiempo real, calculadoras de préstamos y números de token de cola.

   • Procesador AudioWorklet: Captura de audio PCM lineal de 16 kHz desde los micrófonos de la sucursal.

   • Monitor de telemetría en vivo del quiosco: Muestra llamadas a funciones en vivo, latencias del servidor y argumentos de herramientas.

2. Gateway de transmisión en tiempo real y Núcleo del Agente ADK (Cloud Run):

   • Puente FastAPI Async WebSocket (/ws/live): Actúa como proxy de los flujos de audio/vídeo bidireccionales hacia la API Vertex AI Gemini Live.

   • Agente asesor virtual de sucursal ADK (“Priya”): Coordina las intenciones de los clientes, verifica la identidad del titular de la póliza y ejecuta las herramientas del dominio.

   • Transmisor de telemetría de eventos en vivo (_notify_ui): Envía los resultados de las consultas en tiempo real y las tarjetas de cálculos actuariales a la pantalla del quiosco.

3. Nivel de herramientas modulares del Model Context Protocol (MCP):

   • Microservicio policy_tools: Consultas SQL en tiempo real a AlloyDB para el KYC del cliente, específicaciones del plan y total de primas pagadas.

   • Motor de decisión actuarial_tools: Calcula las compensaciones económicas exactas entre las penalizaciones por rescate de póliza (-₹4.2L) y los préstamos instantáneos de póliza en el quiosco (₹4.8L @ 8.5%).

   • Microservicio de operaciones branch_tools: Genera tokens de escalación de cola VIP (#RET-04), los asigna a la Cabina 2 del Director de Sucursal y envía los comprobantes digitales por WhatsApp.

4. Capa de Datos Empresariales, Análisis de APM y Omnicanalidad:

   • Google AlloyDB for PostgreSQL: Clúster de base de datos empresarial que gestiona los registros KYC de los clientes, las pólizas activas, los esquemas de rescate y los tickets de escalación mediante consultas VPC de menos de 5 ms.

   • Google BigQuery APM & Analítica de Agentes: Registra las trayectorias de los agentes, las las duraciones de las herramientas, el consumo de tokens y los embudos de conversión de retención.

   • Twilio WhatsApp Business API: Envía los comprobantes digitales de token VIP y los mapas de ubicación de las cabinas a los clientes al número de teléfono móvil del cliente.

Related MCP server: MCP Business AI Transformation

🧰 Catálogo de Herramientas MCP Modulares

Los microservicios de herramientas se encuentran en backend/tools/:

📊 Suite APM y Analítica de Agentes de BigQuery

La plataforma incluye una suite completa de APM de BigQuery documentada en docs/ANALYTICS_QUERIES.md:

• Traza de la sesión y auditoría de ejecución: Realiza el seguimiento de las llamadas a herramientas paso a paso y de las duraciones de ejecución.

• Latencia percibida y percentil P95: Supervisa la latencia de ida y vuelta de la voz de la herramienta (<150 ms como objetivo).

• Conversión de retención y adopción de opciones de préstamos de pólizas: Mide cuántos clientes con intención de rescate se convierten a préstamos instantáneos de póliza en el quiosco.

• APM de la cola de sucursal y escalado de tickets VIP: Rastrea los tiempos de resolución de los tickets de escalamiento en las cabinas de la sucursal.

📁 Estructura del Repositorio

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

🚀 Guía de Inicio Rápido

Prerrequisitos

• Python: 3.11 a 3.13

• Google Cloud SDK (gcloud): Configurado con un proyecto activo de GCP.

• Google AlloyDB for PostgreSQL: Clúster accesible con los esquemas de esquema y de pólizas de clientes.

Paso 1: Clona tu repositorio y configura el entorno

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

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

Configura las variables de tu archivo .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

Autentícate con Google Cloud:

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

Paso 2: Ejecutar la prueba localmente

chmod +x run.sh
./run.sh

Abre http://localhost:8080 en tu navegador para interactuar con las herramientas del quiosco y el panel de telemetría.

🐳 Despliegue en Cloud Run

Despliega el servicio de herramientas modulares en Google Cloud Run con VPC peering para 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

📄 Licencia

Este proyecto está licenciado bajo la Apache 2.0 License (consulte el LICENSE para obtener detalles). Puedes ver el archivo de los [Licencia] para más información.