conversational-insights-devkit

mcp
Security Audit
Pass
Health Pass
  • License — License: Apache-2.0
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Community trust — 10 GitHub stars
Code Pass
  • Code scan — Scanned 12 files during light audit, no dangerous patterns found
Permissions Pass
  • Permissions — No dangerous permissions requested

No AI report is available for this listing yet.

SUMMARY

A high level scripting API for Conversational Insights

README.md

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 Task cxidk Python Entrypoint MCP / ADK Tool
Aggregate call volume, sentiment, and QA metrics cxidk.wrapper.insights.Stats insights_calculate_stats, insights_query_metrics
Read conversations with PII masking & turn budgets cxidk.wrapper.insights.Conversations insights_list_conversations, insights_get_conversation
Export, dry-run plan, and promote Insights configs cxidk.workflow.ops.ConfigOps config_export_bundle, config_plan_import, config_apply_import
Convert AWS Transcribe or Genesys Cloud JSON cxidk.workflow.format.Insights transcript_validate, transcript_convert
Classify AGENT vs. CUSTOMER speaker roles cxidk.workflow.role_recognizer.RoleRecognizer transcript_recognize_roles
Evaluate & tune Quality AI (QAI) scorecards cxidk.wrapper.insights.Scorecards, cxidk.workflow.insight_refinements insights_list_scorecards, insights_get_scorecard, insights_list_scorecard_revisions, insights_list_analyses
Build confirmation-gated Google ADK agents cxidk.ai.adk.insights_tools, cxidk.ai.skills All 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.

Reviews (0)

No results found