conversational-insights-devkit
Health Gecti
- License — License: Apache-2.0
- Description — Repository has a description
- Active repo — Last push 0 days ago
- Community trust — 10 GitHub stars
Code Gecti
- Code scan — Scanned 12 files during light audit, no dangerous patterns found
Permissions Gecti
- Permissions — No dangerous permissions requested
Bu listing icin henuz AI raporu yok.
A high level scripting API for Conversational Insights
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 (
BASICview by
default), transcript retrieval with Cloud DLP / regex PII redaction, QA scorecard
analysis inspection,calculate_stats, andquery_metricstime-series slicing. - Guarded Configuration Promotion (
ConfigOps): Atomic GCS bundle export,
dry-runplan()with cryptographic HS256plan_tokenbinding, and create-onlyimport_()across projects and regions. - Vendor Transcript Onboarding: Deterministic JSON Schema validation and
conversion for AWS Transcribe and Genesys Cloud, plus Gemini speaker
role classification (AGENTvs.CUSTOMER) viagoogle-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-classFunctionTool(require_confirmation
wired automatically), remoteMcpToolset, bundledSKILL.mdAgent 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 setCXIDK_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
deploy/mcp-cloud-run/README.md: Container image andgcloud run deployscript for stateless Streamable HTTPcxidk-mcpbehind IAP/OIDC.examples/terraform/: Reference Terraform modules for
deployingcxidk-mcpon Cloud Run (cloud_run_mcp/)
and event-driven transcript ingestion on Cloud Run Functions (2nd Gen)
(cloud_run_function_ingest/).
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 viacxidk.get_llms_txt()orcxidk-mcp --print-llms-txt).llms-full.txt: Self-contained full-context Markdown bundle
inlining quickstarts, SDK & tool schemas, filter syntax, andSKILL.mdplaybooks.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 atskills/): PortableSKILL.mdplaybooks.
License
Distributed under the Apache 2.0 License. See LICENSE.txt for details.
Yorumlar (0)
Yorum birakmak icin giris yap.
Yorum birakSonuc bulunamadi