Skip to main content
Glama
niteshwalia0124

cymbal-kiosk-tools-apm

by niteshwalia0124
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote
README.md
# āš™ļø Cymbal Life ā€” Smart Branch Kiosk Modular MCP Tools, Actuarial Engine & BigQuery APM Analytics

[![Google Cloud](https://img.shields.io/badge/Google%20Cloud-Vertex%20AI-4285F4?logo=googlecloud&logoColor=white)](https://cloud.google.com/vertex-ai)
[![ADK](https://img.shields.io/badge/Google%20ADK-Agent%20Development%20Kit-34A853?logo=google&logoColor=white)](https://cloud.google.com/vertex-ai/generative-ai/docs/agent-development-kit)
[![Model Context Protocol](https://img.shields.io/badge/Tools-Model%20Context%20Protocol%20(MCP)-009688)](https://modelcontextprotocol.io)
[![AlloyDB](https://img.shields.io/badge/Database-Google%20AlloyDB%20PostgreSQL-336791?logo=postgresql&logoColor=white)](https://cloud.google.com/alloydb)
[![BigQuery APM](https://img.shields.io/badge/Observability-BigQuery%20Agent%20Analytics-669DF6?logo=googlebigquery&logoColor=white)](https://cloud.google.com/bigquery)
[![Cloud Run](https://img.shields.io/badge/Deployment-Cloud%20Run-4285F4?logo=googlecloud&logoColor=white)](https://cloud.google.com/run)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)

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

![Cymbal Life Smart Branch Kiosk MCP Tools & APM Architecture](docs/architecture.jpg)

### 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/`](backend/tools/):

| Tool Module | Function Name | Category | Description |
| :--- | :--- | :--- | :--- |
| [`policy_tools.py`](backend/tools/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`](backend/tools/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`](backend/tools/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`](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

```bash
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:
```bash
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:
```bash
gcloud auth application-default login
gcloud config set project your-gcp-project-id
```

---

### Step 2: Run Locally

```bash
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:

```bash
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](LICENSE) file for details.

This server cannot be deployed

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources