⚙️ Cymbal Life — Smart Branch Kiosk Modular MCP Tools, Actuarial Engine & BigQuery APM Analytics

An enterprise-grade, decoupled Modular MCP Tools, Actuarial Decision Engine & BigQuery APM Analytics Platform for Cymbal Life Smart Branch Kiosks, built on Google Agent Development Kit (ADK), Model Context Protocol (MCP), Google AlloyDB for PostgreSQL, and Google BigQuery.

This service provides modular tool execution microservices, sub-5ms VPC database queries against AlloyDB, real-time actuarial loan vs. surrender comparisons, in-branch VIP queue ticket generation, and comprehensive BigQuery Application Performance Monitoring (APM).

---

🏛️ High-Level System Architecture

Architectural Overview

The system is organized into four distinct operational layers:

1. Client & In-Branch Kiosk Tier:

   • Smart Kiosk Touch Interface: High-resolution touchscreen terminal displaying real-time policy breakdown cards, loan calculators, and queue token numbers.
   • AudioWorklet Processor: 16kHz linear PCM audio capture from branch microphones.
   • Live Kiosk Telemetry Monitor: Displays live function calls, server latencies, and tool arguments.

2. Real-Time Streaming Gateway & ADK Agent Core (Cloud Run):

   • FastAPI Async WebSocket Bridge (/ws/live): Proxies bi-directional audio/video streams to Vertex AI Gemini Live API.
   • ADK Virtual Branch Advisor Agent ("Priya"): Coordinates customer intents, verifies policyholder identity, and executes domain tools.
   • Live Event Telemetry Broadcaster (_notify_ui): Pushes real-time database query results and actuarial calculation cards to the kiosk screen.

3. Modular Model Context Protocol (MCP) Tools Tier:

   • policy_tools Microservice: Real-time SQL queries against AlloyDB for customer KYC, plan specifications, and total premiums paid.
   • actuarial_tools Decision Engine: Computes exact financial trade-offs between policy surrender forfeiture penalties (-₹4.2L) versus instant kiosk policy loans (₹4.8L @ 8.5%).
   • branch_tools Operations Microservice: Generates VIP queue escalation tokens (#RET-04), assigns to Branch Manager Cabin 2, and dispatches digital slips over WhatsApp.

4. Enterprise Data, APM Analytics & Omnichannel Layer:

   • Google AlloyDB for PostgreSQL: Enterprise database cluster managing customer KYC records, active policies, surrender schedules, and escalation tickets via sub-5ms VPC queries.
   • Google BigQuery APM & Agent Analytics Suite: Records turn-by-turn agent trajectories, tool latencies, token consumption, and retention conversion funnels.
   • Twilio WhatsApp Business API: Dispatches digital VIP token slips and branch cabin routing maps to the customer's mobile number.

---

🧰 Modular MCP Tools Catalog

The tool microservices are located under backend/tools/:

Tool Module	Function Name	Category	Description
policy_tools.py	lookup_policyholder_details	Core Banking	Real-time AlloyDB query for customer KYC, plan specs, total premiums paid (₹6.0L), surrender value (₹3.8L), and guaranteed benefits (₹18L).
actuarial_tools.py	calculate_surrender_penalty_vs_loan	Actuarial Engine	Compares financial trade-offs: Surrender loss (-₹4.2L) vs. Instant Kiosk Loan (₹4.8L @ 8.5%) vs. Reduced Paid-Up status.
branch_tools.py	issue_in_branch_vip_token	Operations	Generates in-branch VIP escalation ticket (#RET-04), assigns to Cabin 2 (Branch Head Mr. Vikram Mehta), and triggers WhatsApp slip.

---

📊 BigQuery APM & Agent Analytics Suite

The platform includes a complete BigQuery Application Performance Monitoring (APM) suite documented in docs/ANALYTICS_QUERIES.md:

• Session Trajectory & Tool Execution Audit: Tracks turn-by-turn tool invocations and execution durations.
• Perceptual Latency & P95 Distribution: Monitors voice-to-tool round-trip latency (<150ms target).
• Retention Conversion & Policy Loan Uptake: Measures how many surrender-intent customers convert to instant kiosk policy loans.
• Branch Queue & VIP Ticket Escalation APM: Tracks escalation ticket resolution times across branch cabins.

---

📁 Repository Structure

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

---

🚀 Quick Start Guide

Prerequisites

• Python: 3.11 to 3.13
• Google Cloud SDK (gcloud): Configured with an active GCP project.
• Google AlloyDB for PostgreSQL: Accessible cluster with customer and policy schemas.

---

Step 1: Clone Repository & Configure Environment

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

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

Configure your .env variables:

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

Authenticate with Google Cloud:

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

---

Step 2: Run Locally

chmod +x run.sh
./run.sh

Open http://localhost:8080 in your browser to interact with the kiosk tools and telemetry deck.

---

🐳 Cloud Run Deployment

Deploy the modular tools service to Google Cloud Run with VPC peering for 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

---

📄 License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.