⚙️ Cymbal Life — Modulare MCP-Tools für Smart Branch Kiosk, Aktuar-Engine & BigQuery-APM-Analysen

Eine unternehmensgerechte, entkoppelte Plattform für modulare MCP-Tools, eine aktuarielle Entscheidungs-Engine und BigQuery-APM-Analysen für Cymbal Life Smart Branch Kiosks, aufgebaut auf Google Agent Development Kit (ADK), Model Context Protocol (MCP), Google AlloyDB for PostgreSQL und Google BigQuery.

Dieser Dienst bietet modulare Microservices zur Tool-Ausführung, AlloyDB-Datenbankabfragen über die VPC mit unter 5 ms Latenz, Echtzeit-Vergleiche zwischen Policendarlehen und Rückkauf, die Erstellung von VIP-Warteschlangentickets in der Filiale sowie umfassendes BigQuery-APM (Application Performance Monitoring).

🏛️ Systemarchitektur im Überblick

Architektonische Übersicht

Das System ist in vier unterschiedliche Betriebsebenen gegliedert:

1. Client- und In-Branch-Kiosk-Ebene:

   • Smart Kiosk Touch Interface: Hochauflösende Touchscreen-Oberfläche, die Echtzeit-Policenübersichtskarten, Darlehensrechner und Warteschlangen-Ticketnummern anzeigt.

   • AudioWorklet Processor: Erfasst 16-kHz-Audio in linearer PCM über die Mikrofone der Filiale.

   • Live Kiosk Telemetry Monitor: Zeigt Live-Funktionsaufrufe, Serverlatenzen und Tool-Argumente an.

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

   • FastAPI-Async-WebSocket-Bridge (/ws/live): Leitet bidirektionale Audio-/Video-Streams an die Vertex-AI-Gemini-Live-API weiter.

   • ADK Virtual-Filialberater-Agent („Priya"): Koordiniert Kundenabsichten, überprüft die Identität des Versicherungsnehmers und führt Domänen-Tools aus.

   • Live-Event-Telemetrie-Broadcaster (_notify_ui): Überträgt Echtzeit-Ergebnisse von Datenbankabfragen und aktuarielle Berechnungskarten an den Kioskbildschirm.

3. Ebene der modularen Model Context Protocol (MCP)-Tools:

   • Mikroservice policy_tools: Echtzeit-SQL-Abfragen gegen AlloyDB für Kundenunterliegs-KYC, Tarifangaben und insgesamt gezahlte Prämien.

   • Entscheidungs-Engine actuarial_tools: Berechnet die genauen finanziellen Abwägen zwischen Rückkaufsstrafen (-₹4.2L) und sofortigen Policendarlehen am Kiosk (₹4.8L @ 8.5%).

   • Betriebs-Mikroservice branch_tools: Erstellt In-Branch-VIP-Warteschlangen-Eskalationstickets (#RET-04), weist diese der Filialleitung in Kabine B 2 zu und löst die digitale Belegsendung über WhatsApp aus.

4. Enterprise-Daten, APM-Analysen & Omnichannel-Ebene:

   • Google AlloyDB for PostgreSQL: Unternehmensdaten-Cluster zur Verwaltung von Kunden-KYC-Datensätze, aktiven Policen, Rückkaufplänen und Eskalationstickets über VPC-Abfragen mit unter 5 ms.

   • Google BigQuery APM & Agent-Analytics-Suite: Erfastet Schritt-für-Schritt-Agent-Trajektoriesen, Tool-Latenzen, Token-Verbrauch und Retention-Conversion-Trichters.

   • Twilio WhatsApp Business API: Sendet digitale VIP-Ticketbelege und Raumlpläne für Filialkabinen an die Mobilnummer des Kunden.

Related MCP server: MCP Business AI Transformation

🧰 Katalog der modularen MCP-Tools

Die Tool-Microservices befinden sich unter backend/tools/:

📊 BigQuery-APM- & Agent-Analytics-Suite

Die Lösungstheme umfasst eine vollständige BigQuery-Suite für Anwendungsleistungsüberwachung (APM), die im Dokumentation docs/ANALYTICS_QUERIES.md dokumentiert ist:

• Session-Trajectory & Tool-Ausführungsaudit: Zeichnet Schritt für Schritt Tool-Aufrufe und Ausführungsdauern auf.

• Wahrgenommene Latenz & P95-Verteilung: Überwacht die Roundtrip-Latenzen von Sprache-2-Tool (Zielwert: <150 ms).

• Retention-Konvertierung & Policendarlehens-Abnahme: Misst, wie viele Kunden mit Rückkaufabsicht zu sofortigen Kiosk-Policendarlehnen übergehen.

• Filialwarteschlange & VIP-Ticket-Eskalations-APM: Verfolgt Lösungszeiten für Eskalationstickets über die Filialkabellen.

📁 Repository-Struktur

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

🚀 Schnellstartanleitung

Voraussetzungen

• Python: 3.11 bis 3.13

• Google Cloud SDK (gcloud): Mit einem aktiven GCP-Projekt konfiguriert.

• Google AlloyDB for PostgreSQL: Erreichbarer Cluster mit Kunden- und Policierschemata.

Schritt 1: Repository klonen und Umgebung konfigurieren

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

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

Konfigurieren Sie die .env-Variablen:

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

Authentifizieren Sie sich bei Google Cloud:

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

Schritt 2: Lokal ausführen

chmod +x run.sh
./run.sh

Öffnen Sie http://localhost:8080 in Ihrem Browser, um mit den Kiosk-Tools und dem Telemetrie-Dashboard zu interagieren.

🐳 Cloud-Run-Bereitstellung

Stellen Sie den Dienst für modulare Werkzeuge auf Google Cloud Run mit VPC-Peering für AlloyDB bereit:

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

📄 Lizenz

Dieses Projekt ist unter der Apache-2.0-Lizenz lizenziert – siehe die Datei LICENSE für Details.