diteko (Python)

Generate, export and run tests for Amazon Connect contact flows, from Python. It is the testing counterpart to cxblueprint: build or export a flow, then let Diteko derive its grammar, evolve a test suite with Grammatical Evolution, export it, and run it on Connect's native testing.

The SDK is a client: it talks to a running Diteko deployment over its REST API, so you need one to point it at. If that deployment requires API keys, set DITEKO_API_KEY (or pass api_key=); otherwise point the SDK only at a deployment inside your network or behind your VPN.

pip install diteko               # SDK
pip install "diteko[mcp]"        # + MCP server for Claude Desktop / Cursor / VS Code
pip install "diteko[cxblueprint]"

The pipeline

from diteko import Diteko

dk = Diteko("http://localhost:8888")

project = dk.projects.from_json("claims.json")          # Connect export or cxblueprint output
project.grammar.generate()                              # derive, store and validate the grammar
run = project.evolve(preset="standard", focus="balanced").wait()
suite = run.suite(top=30, selection="coverage")         # or selection="fitness"

for test in suite:
    print(test.test_id, test.keys, test.fitness)

suite.export_xlsx("claims-tests.xlsx")                  # manual test script (ISO/IEC/IEEE 29119-3)
suite.export_native("claims-native.json")               # Amazon Connect native test cases
result = suite.publish_to_connect(dry_run=True)         # dry run unless you say otherwise
print(result.passed, result.failed, result.verdicts)

Straight from cxblueprint

from cxblueprint import Flow
from diteko import Diteko

flow = Flow.build("Burger Order")
menu = flow.get_input("Press 1 for Classic or 2 for Veggie", timeout=10)
# ... build the flow as usual ...

project = Diteko().projects.from_cxblueprint(flow)      # compiles locally, uploads the JSON

Other ways in

dk.projects.import_from_connect("08e145dc-d959-4094-9021-6f10d8590be2")   # from the instance
dk.projects.list()                                      # every project and its next step
dk.projects.get(21601).suite(top=10).export_xlsx()

Grammars as BNF or JSON

The two forms are exact reflections of each other. Both are validated by the same parser, and both keep comments.

g = project.grammar.latest()
spec = g.to_json()                    # {"format": "diteko-grammar/v1", "start": ..., "rules": [...]}
g.replace(spec, format="json").save() # edit as JSON, store as canonical BNF
dk.convert_grammar(bnf_text, "bnf", "json")

Presets

Pass population=, generations=, weights={"state_coverage": 1.0} or seed= to go beyond them.

API keys

dk = Diteko("https://diteko.internal", api_key="dk_...")   # or set DITEKO_API_KEY
dk.whoami()   # {"name": "nightly CI", "prefix": "dk_...", "scope": "WRITE", ...}; None if keys are off

A key carries one scope: READ (see and export), WRITE (also create, run and dry-run), PUBLISH_LIVE (also run on Connect for real, which is billed) or ADMIN (also manage keys). Keys are created in the console under Settings, API keys.

MCP server

DITEKO_URL=http://localhost:8888 DITEKO_API_KEY=dk_... diteko-mcp   # the key only if the server requires one

{ "mcpServers": { "diteko": { "command": "diteko-mcp", "env": { "DITEKO_URL": "http://localhost:8888", "DITEKO_API_KEY": "dk_..." } } } }

Each tool carries MCP annotations: read-only tools say so, and publish_suite is marked as reaching an external system. Works with mcp 1.x and 2.x.

Versioning

The package follows Semantic Versioning. See the changelog for what each release changed.

The server reports an API version, MAJOR.MINOR, at GET /api/version. A minor bump only adds endpoints or fields. A major bump changes something an existing client relies on. Each SDK release speaks one API major version, currently 1. On its first call the SDK checks the server's version:

Diteko(url, check_version=False) skips the check, and dk.version() returns what the server reports.

Development

cd clients/python
python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev,mcp]"
pytest                                   # against an in-memory fake of the API
DITEKO_URL=http://localhost:8888 pytest  # also runs the live and contract tests against a local stack

Changelog

All notable changes to the diteko Python package. The format follows Keep a Changelog, and versions follow Semantic Versioning as described under “Versioning” in the README.

0.2.0 - 2026-10-11

Added

• The first call checks that the server speaks this SDK's API major version (GET /api/version, API 1.x). A server on another major is refused with an error that says which side to upgrade; a server that predates version reporting gets a warning, not a failure. Diteko(..., check_version=False) skips the check.
• Diteko.version() returns the server's API version and build.
• API keys: the SDK and diteko-mcp send DITEKO_API_KEY (or Diteko(api_key=...)) to servers that require keys (API 1.1). A missing key, a refused key and a key without permission each raise a DitekoError that says which. Diteko.whoami() returns the key in use.

Fixed

• Moving a record to another parent with a partial update (for example a grammar to another flow) no longer fails on the server (fixed server-side, Diteko API 1.0).

0.1.0 - 2026-10-10

Added

• First release: projects from Connect exports, cxblueprint flows or a Connect instance; grammars as BNF or JSON; evolution with size and focus presets; suites exported as an Excel test script (ISO/IEC/IEEE 29119-3), JSON or Connect native tests; publishing to Connect, dry run by default.
• diteko-mcp, an MCP server exposing the same pipeline as eight tools, on mcp 1.x or 2.x.