cxblueprint 0.1.0.post12

Python DSL for Amazon Connect contact flow generation

CxBlueprint

Programmatic Amazon Connect contact flow generation using Python. Lets AI models and developers build contact flows from plain English instead of hand-writing JSON.

All 56 AWS Connect block types have been implemented, covering IVR, routing, A/B testing, queue transfer, customer profiles, case management, Voice ID, and analytics patterns. Note that some less common blocks have not been fully validated against live AWS Connect instances. Includes an MCP server for AI-assisted flow generation with Claude Desktop, Cursor, and VS Code.

Simple Example

from cxblueprint import Flow

flow = Flow.build("Burger Order")

welcome = flow.play_prompt("Welcome to Burger Palace!")
menu = flow.get_input("Press 1 for Classic Burger or 2 for Veggie Burger", timeout=10)
welcome.then(menu)

classic = flow.play_prompt("You selected Classic Burger. Your order is confirmed!")
veggie = flow.play_prompt("You selected Veggie Burger. Your order is confirmed!")
error_msg = flow.play_prompt("Invalid selection. Goodbye.")

disconnect = flow.disconnect()

menu.when("1", classic) \
    .when("2", veggie) \
    .otherwise(error_msg) \
    .on_error("InputTimeLimitExceeded", error_msg) \
    .on_error("NoMatchingCondition", error_msg) \
    .on_error("NoMatchingError", error_msg)

classic.then(disconnect)
veggie.then(disconnect)
error_msg.then(disconnect)

flow.compile_to_file("burger_order.json")

Terraform Template Example

Use placeholders for dynamic resource ARNs:

from cxblueprint import Flow

flow = Flow.build("Counter Flow")

welcome = flow.play_prompt("Thank you for calling!")
invoke_counter = flow.invoke_lambda(
    function_arn="${COUNTER_LAMBDA_ARN}",  # Resolved by Terraform
    timeout_seconds="8"
)
welcome.then(invoke_counter)

say_count = flow.play_prompt("You are caller number $.External.count")
invoke_counter.then(say_count)

disconnect = flow.disconnect()
say_count.then(disconnect)
invoke_counter.on_error("NoMatchingError", disconnect)

flow.compile_to_file("counter_flow.json")

Generated Flow Examples

Here's what the generated flows look like in the Amazon Connect console:

Installation

pip install cxblueprint

# With MCP server for AI integration
pip install cxblueprint[mcp]

MCP Server

CxBlueprint includes an MCP server that lets AI tools (Claude Desktop, Cursor, VS Code) build contact flows conversationally.

Configure Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "cxblueprint": {
      "command": "cxblueprint-mcp"
    }
  }
}

Then ask Claude: "Build me an IVR with a welcome message and 3 menu options for sales, support, and billing"

The AI reads the bundled documentation automatically and uses the compile_flow tool to generate valid Amazon Connect JSON.

Block Coverage

All 56 AWS block types have been implemented. Core blocks (prompts, input, disconnect, Lambda, Lex, queues, transfers) are well-tested. Some less common blocks (Voice ID, Customer Profiles, Case Management) have not been fully validated against live AWS instances.

Category	Implemented	Total
Participant Actions	6	6
Contact Actions	27	27
Flow Control Actions	16	16
Interactions	8	8

See each category's README for the full per-block breakdown.

Features

• Fluent Python API for building flows
• MCP server for AI-assisted flow generation
• Canvas layout positioning for AWS Connect visual editor
• Automatic UUID generation for blocks
• Conditional branching and error handling
• AWS Lambda and Lex V2 bot integration
• Template placeholder support for Terraform/IaC
• Decompile existing flows back to Python

Project Structure

src/cxblueprint/
  flow_builder.py       # Main builder API
  flow_analyzer.py      # Flow validation
  mcp_server.py         # MCP server for AI integration
  blocks/               # All Connect block types
examples/               # Sample flows
docs/                   # API reference & AI instructions

Documentation

• API Reference
• Terraform Example

Requirements

• Python 3.11+
• AWS credentials (for deployment)
• Terraform (optional, for infrastructure)