Repository avatar
AI Tools
v2.0.0
active

cxidk

io.github.GoogleCloudPlatform/cxidk

Google Cloud Conversational Insights (CCAI) MCP server for analytics, conversion, and config ops.

Documentation

Conversational Insights DevKit (cxidk 2.0)

The Conversational Insights DevKit (cxidk) is an AI-native Python library, Model Context Protocol (MCP) server, and Google Agent Development Kit (ADK) integration for Google Cloud Conversational Insights (formerly Contact Center AI / CCAI Insights, part of Customer Engagement Suite).

Key Features

  • Read & Analytics APIs: Token-budgeted conversation listing (BASIC view by default), transcript retrieval with Cloud DLP / regex PII redaction, QA scorecard analysis inspection, calculate_stats, and query_metrics time-series slicing.
  • Guarded Configuration Promotion (ConfigOps): Atomic GCS bundle export, dry-run plan() with cryptographic HS256 plan_token binding, and create-only import_() across projects and regions.
  • Vendor Transcript Onboarding: Deterministic JSON Schema validation and conversion for AWS Transcribe and Genesys Cloud, plus Gemini speaker role classification (AGENT vs. CUSTOMER) via google-genai.
  • MCP Server (cxidk-mcp): Ready for Gemini CLI, Claude Code, Cursor, VS Code (stdio), and remote multi-user Cloud Run deployments (Streamable HTTP with IAP/OIDC auth, MCP elicitation confirmation, OpenTelemetry, and audit logging).
  • Google ADK Integration (cxidk.ai.adk): First-class FunctionTool (require_confirmation wired automatically), remote McpToolset, bundled SKILL.md Agent Skills, and reference agents (insights_analyst, config_promoter, qa_tuner).

When to Use cxidk vs. google-cloud-contact-center-insights

google-cloud-contact-center-insights provides low-level auto-generated gRPC/Protobuf bindings. Use cxidk on top when building workflows, pipelines, or AI agents:

Developer / Agent Taskcxidk Python EntrypointMCP / ADK Tool
Aggregate call volume, sentiment, and QA metricscxidk.wrapper.insights.Statsinsights_calculate_stats, insights_query_metrics
Read conversations with PII masking & turn budgetscxidk.wrapper.insights.Conversationsinsights_list_conversations, insights_get_conversation
Export, dry-run plan, and promote Insights configscxidk.workflow.ops.ConfigOpsconfig_export_bundle, config_plan_import, config_apply_import
Convert AWS Transcribe or Genesys Cloud JSONcxidk.workflow.format.Insightstranscript_validate, transcript_convert
Classify AGENT vs. CUSTOMER speaker rolescxidk.workflow.role_recognizer.RoleRecognizertranscript_recognize_roles
Evaluate & tune Quality AI (QAI) scorecardscxidk.wrapper.insights.Scorecards, cxidk.workflow.insight_refinementsinsights_list_scorecards, insights_get_scorecard, insights_list_scorecard_revisions, insights_list_analyses
Build confirmation-gated Google ADK agentscxidk.ai.adk.insights_tools, cxidk.ai.skillsAll 19 @cx_tool functions

Requirements & Installation

Requires Python 3.11+.

python3 -m venv .venv
source .venv/bin/activate

# Core SDK
pip install cxidk

# With MCP server + Google ADK + Speech + DLP extras
pip install "cxidk[mcp,adk,speech,dlp]"

# Local editable install for contributors
pip install -e ".[all,dev]"

Quickstart 1: Python SDK (CxContext & Read APIs)

from cxidk import CxContext
from cxidk.ai.tools import insights_calculate_stats, insights_list_conversations

cx = CxContext(project_id="my-gcp-project", location="us-central1")

stats = insights_calculate_stats(filter='medium="PHONE_CALL"', cx=cx)
print(stats.stats)

page = insights_list_conversations(page_size=10, cx=cx)
for convo in page.conversations:
    print(convo.get("name"))

Quickstart 2: Gemini CLI Extension & Local MCP Server (stdio)

Authenticate with Application Default Credentials:

gcloud auth application-default login

Install in one command as a Gemini CLI Extension (wires cxidk-mcp, environment settings, and all 4 Agent Skills automatically):

gemini extensions install https://github.com/GoogleCloudPlatform/conversational-insights-devkit

Or add cxidk-mcp directly to Gemini CLI (~/.gemini/settings.json), Claude Desktop / Claude Code, VS Code, or Cursor via uvx (or an installed .venv):

{
  "mcpServers": {
    "cxidk": {
      "command": "uvx",
      "args": ["--from", "cxidk[mcp]", "cxidk-mcp", "--transport", "stdio"],
      "env": {
        "CXIDK_PROJECT_ID": "your-gcp-project",
        "CXIDK_LOCATION": "us-central1"
      }
    }
  }
}

Write tools are disabled by default. Pass "--allow-writes" (or set CXIDK_ALLOW_WRITES=true) to enable guarded promotion and ingestion tools with interactive MCP elicitation confirmation.

Quickstart 3: Google ADK Agents

from cxidk import CxContext
from cxidk.ai.adk import build_insights_analyst_agent, build_config_promoter_agent

cx = CxContext(project_id="my-gcp-project", location="us-central1")

# Read-only analyst agent with redacted transcript defaults
analyst = build_insights_analyst_agent(cx=cx)

# Guarded release agent (requires plan_token + ADK ToolConfirmation on writes)
promoter = build_config_promoter_agent(
    cx=cx,
    allowed_projects=["dev-insights", "prod-insights"],
)

Quickstart 4: Vendor Transcript Conversion & Ingestion

import json
import uuid
from cxidk.workflow import format as cx_format
from cxidk.workflow import role_recognizer as rr
from cxidk.wrapper import insights, speech, storage

project_id = "your-gcp-project"
location = "us-central1"
bucket_name = "your-insights-staging-bucket"
parent = f"projects/{project_id}/locations/{location}"

# Convert an AWS Transcribe JSON payload locally
with open("tests/integration/data/aws_transcript.json", "r", encoding="utf-8") as f:
    aws_payload = json.load(f)

insights_json = cx_format.Insights().from_aws(transcript=aws_payload)

# Upload to GCS and ingest into CCAI Insights
gcs = storage.Gcs(project_name=project_id, bucket_name=bucket_name)
blob_name = f"{uuid.uuid4()}.json"
gcs.upload_blob(file_name=blob_name, data=json.dumps(insights_json))

ingestor = insights.Ingestion(
    parent=parent,
    transcript_path=f"gs://{bucket_name}/{blob_name}",
)
operation = ingestor.single(language_code="en-US")
print(f"Ingestion operation started: {operation.name}")

Cloud Run & Terraform Deployment

Documentation for AI Systems

  • llms.txt: Concise machine-readable index of Python SDK modules, registered MCP/ADK tools, resources, prompts, and Agent Skills (also accessible offline via cxidk.get_llms_txt() or cxidk-mcp --print-llms-txt).
  • llms-full.txt: Self-contained full-context Markdown bundle inlining quickstarts, SDK & tool schemas, filter syntax, and SKILL.md playbooks.
  • AGENTS.md / GEMINI.md / CLAUDE.md: Contributor & coding-agent guardrails.
  • GEMINI_EXTENSION.md & gemini-extension.json: Gemini CLI Extension runtime context and configuration manifest.
  • src/cxidk/ai/skills/ (mirrored at skills/): Portable SKILL.md playbooks.

License

Distributed under the Apache 2.0 License. See LICENSE.txt for details.

PYPI
cxidk
Install Command
pip install cxidk
Runtime: uvx