cxblueprint 0.1.0.post15

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 57 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 MCP tools to generate valid Amazon Connect JSON.

MCP Tools

Tool	Description
compile_flow	Compile Python code to AWS Connect JSON
validate_flow	Validate a flow without compiling
decompile_flow	Convert existing AWS JSON back to Python
list_block_types	List all 57 supported block types
get_flow_stats	Get block counts, error coverage, canvas size
flow_to_mermaid	Generate a Mermaid flowchart diagram

Block Coverage

All 57 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 (6 tools)
• Mermaid flowchart diagram export (flow.to_mermaid())
• Flow validation and analysis (flow.validate(), flow.stats())
• 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
  canvas_layout.py      # Auto-positioning for AWS visual editor
  mermaid_export.py     # Mermaid flowchart diagram generation
  mcp_server.py         # MCP server for AI integration (6 tools)
  blocks/               # All 57 Connect block types
examples/               # Sample flows
docs/                   # API reference & AI instructions

Documentation

• API Reference
• Flow Builder Guide
• AI Model Instructions
• Terraform Example

Requirements

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