diteko 0.1.0__py3-none-any.whl

diteko/__init__.py

@@ -0,0 +1,12 @@
+"""Diteko: generate, export and run tests for Amazon Connect contact flows.
+
+The testing counterpart to cxblueprint: build or export a flow, then let Diteko derive
+its grammar, evolve a test suite, export it (Excel test script, JSON, Connect native)
+and run it on Connect's native testing.
+"""
+
+from ._http import DitekoError
+from .sdk import FOCUS, SIZES, Diteko, Execution, Grammar, Project, Projects, Run, Suite, Test
+
+__all__ = ["Diteko", "DitekoError", "Execution", "FOCUS", "Grammar", "Project", "Projects", "Run", "SIZES", "Suite", "Test"]
+__version__ = "0.1.0"

diteko/_http.py

@@ -0,0 +1,59 @@
+"""The HTTP layer: one place that knows the API's paths and turns errors into DitekoError."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+
+class DitekoError(RuntimeError):
+    """The Diteko API refused a request, or could not be reached."""
+
+    def __init__(self, message: str, status: int | None = None, body: Any = None):
+        super().__init__(message)
+        self.status = status
+        self.body = body
+
+
+class Http:
+    """A thin client for the Diteko REST API (``/api/**``)."""
+
+    def __init__(self, base_url: str, *, timeout: float = 60.0, transport: httpx.BaseTransport | None = None):
+        self._client = httpx.Client(base_url=base_url.rstrip("/") + "/api", timeout=timeout, transport=transport)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def request(self, method: str, path: str, *, json: Any = None, params: dict[str, Any] | None = None) -> httpx.Response:
+        clean = {k: v for k, v in (params or {}).items() if v is not None}
+        try:
+            response = self._client.request(method, path, json=json, params=clean)
+        except httpx.HTTPError as e:
+            raise DitekoError(f"Could not reach the Diteko API at {self._client.base_url}: {e}") from e
+        if response.status_code >= 400:
+            try:
+                body: Any = response.json()
+            except ValueError:
+                body = response.text
+            detail = body.get("detail") or body.get("title") if isinstance(body, dict) else body
+            raise DitekoError(f"{method} {path} failed with HTTP {response.status_code}: {detail}", response.status_code, body)
+        return response
+
+    def get(self, path: str, **params: Any) -> Any:
+        return self.request("GET", path, params=params).json()
+
+    def post(self, path: str, body: Any = None, **params: Any) -> Any:
+        response = self.request("POST", path, json=body, params=params)
+        return response.json() if response.content else None
+
+    def put(self, path: str, body: Any) -> Any:
+        return self.request("PUT", path, json=body).json()
+
+    def download(self, path: str, **params: Any) -> tuple[bytes, str | None]:
+        response = self.request("GET", path, params=params)
+        disposition = response.headers.get("content-disposition", "")
+        name = None
+        if "filename=" in disposition:
+            name = disposition.split("filename=", 1)[1].strip('"; ')
+        return response.content, name

diteko/mcp_server.py

@@ -0,0 +1,122 @@
+"""MCP server: drive Diteko from Claude Desktop, Cursor or VS Code.
+
+    pip install "diteko[mcp]"
+    DITEKO_URL=http://localhost:8888 diteko-mcp
+
+Publishing to Connect defaults to a dry run; a live run must be asked for explicitly,
+because it bills the AWS account behind the deployment.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+from .sdk import FOCUS, SIZES, Diteko
+
+try:  # mcp 2.x renamed FastMCP to MCPServer; the API this module uses is otherwise the same
+    from mcp.server.mcpserver import MCPServer as _Server
+except ImportError:
+    try:
+        from mcp.server.fastmcp import FastMCP as _Server
+    except ImportError as e:  # pragma: no cover - exercised only without the extra
+        raise SystemExit('The MCP server needs the "mcp" extra: pip install "diteko[mcp]"') from e
+from mcp.types import ToolAnnotations
+
+mcp = _Server("diteko")
+
+
+def _hints(**hints: bool) -> ToolAnnotations:
+    """Tool annotations by their wire names, which both mcp 1.x and 2.x accept."""
+    return ToolAnnotations.model_validate(hints)
+
+
+READ_ONLY = _hints(readOnlyHint=True, openWorldHint=False)
+CHANGES_DITEKO = _hints(readOnlyHint=False, destructiveHint=False, openWorldHint=False)
+_client: Diteko | None = None
+
+
+def _dk() -> Diteko:
+    global _client
+    if _client is None:
+        _client = Diteko(os.environ.get("DITEKO_URL", "http://localhost:8888"))
+    return _client
+
+
+def _project(p: Any) -> dict[str, Any]:
+    return {"flow_id": p.flow_id, "name": p.name, "next_step": p.next_step, "connect_flow_id": p.connect_flow_id, "suite_run_id": p.summary.get("suiteRunId")}
+
+
+@mcp.tool(annotations=READ_ONLY)
+def list_projects() -> list[dict[str, Any]]:
+    """List every contact flow under test, with the next step for each (GRAMMAR, EVOLVE, RUN or DONE)."""
+    return [_project(p) for p in _dk().projects.list()]
+
+
+@mcp.tool(annotations=CHANGES_DITEKO)
+def import_flow(name: str, flow_json: str | None = None, path: str | None = None, connect_flow_id: str | None = None) -> dict[str, Any]:
+    """Register a contact flow as a project: from flow JSON text (Connect export or cxblueprint output), a .json file path, or a flow id in the configured Connect instance."""
+    projects = _dk().projects
+    if connect_flow_id:
+        return _project(projects.import_from_connect(connect_flow_id))
+    if path:
+        return _project(projects.from_json(Path(path), name=name))
+    if flow_json:
+        return _project(projects.from_json(flow_json, name=name))
+    raise ValueError("Give flow_json, path or connect_flow_id")
+
+
+@mcp.tool(annotations=CHANGES_DITEKO)
+def generate_grammar(flow_id: int) -> dict[str, Any]:
+    """Generate, store and validate the grammar for a project's flow. Returns it as BNF."""
+    g = _dk().projects.get(flow_id).grammar.generate()
+    return {"grammar_id": g.id, "start_symbol": g.start_symbol, "bnf": g.bnf}
+
+
+@mcp.tool(annotations=READ_ONLY)
+def convert_grammar(content: str, source: str, target: str) -> str:
+    """Convert a grammar between "bnf" and "json" (exact reflections of each other)."""
+    return _dk().convert_grammar(content, source.lower(), target.lower())  # type: ignore[arg-type]
+
+
+@mcp.tool(annotations=CHANGES_DITEKO)
+def start_evolution(flow_id: int, size: str = "standard", focus: str = "balanced", seed: int | None = None) -> dict[str, Any]:
+    """Start an evolution run for a project. size: quick, standard or thorough; focus: balanced, coverage, errors or transfers. Returns immediately; poll get_run."""
+    if size not in SIZES or focus not in FOCUS:
+        raise ValueError(f"size must be one of {sorted(SIZES)} and focus one of {sorted(FOCUS)}")
+    run = _dk().projects.get(flow_id).evolve(size, focus, seed=seed)  # type: ignore[arg-type]
+    return {"run_id": run.id, "status": run.status}
+
+
+@mcp.tool(annotations=READ_ONLY)
+def get_run(run_id: int) -> dict[str, Any]:
+    """An evolution run's progress: status, generation, best/average fitness."""
+    return _dk().run(run_id).progress
+
+
+@mcp.tool(annotations=_hints(readOnlyHint=False, destructiveHint=True, idempotentHint=True, openWorldHint=False))  # writes a local file
+def export_suite(run_id: int, format: str = "xlsx", path: str | None = None, top: int | None = None, selection: str = "fitness") -> str:
+    """Export a run's suite. format: xlsx (manual test script), json, or native (Connect test cases). selection: fitness or coverage. Returns the file written."""
+    suite = _dk().run(run_id).suite(top, selection)  # type: ignore[arg-type]
+    exporters = {"xlsx": suite.export_xlsx, "json": suite.export_json, "native": suite.export_native}
+    if format not in exporters:
+        raise ValueError(f"format must be one of {sorted(exporters)}")
+    return str(exporters[format](path).resolve())
+
+
+# Reaches Amazon Connect; a live run (dry_run=false) bills the AWS account.
+@mcp.tool(annotations=_hints(readOnlyHint=False, destructiveHint=False, openWorldHint=True))
+def publish_suite(run_id: int, dry_run: bool = True, top: int | None = None, selection: str = "fitness") -> dict[str, Any]:
+    """Run a suite on Amazon Connect native testing. Dry run by default: nothing is called or billed. A live run (dry_run=false) bills one execution per test."""
+    execution = _dk().run(run_id).suite(top, selection).publish_to_connect(dry_run=dry_run)  # type: ignore[arg-type]
+    return {"upload_id": execution.upload_id, "dry_run": execution.dry_run, "passed": execution.passed, "failed": execution.failed, "verdicts": execution.verdicts}
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

diteko/sdk.py

@@ -0,0 +1,459 @@
+"""The fluent API: projects, grammars, runs, suites and executions.
+
+A project is a contact flow under test. The pipeline is the same as in the console:
+flow -> grammar -> evolve (a run) -> suite -> run on Connect -> results.
+"""
+
+from __future__ import annotations
+
+import json as _json
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Iterable, Literal
+
+from ._http import DitekoError, Http
+
+Size = Literal["quick", "standard", "thorough"]
+Focus = Literal["balanced", "coverage", "errors", "transfers"]
+Selection = Literal["fitness", "coverage"]
+GrammarFormat = Literal["bnf", "json"]
+
+#: Run sizes, the same as the console's: calls per generation x generations.
+SIZES: dict[str, dict[str, int]] = {
+    "quick": {"populationSize": 40, "generations": 15},
+    "standard": {"populationSize": 100, "generations": 50},
+    "thorough": {"populationSize": 200, "generations": 120},
+}
+
+#: What a suite should be good at, as fitness weights (the console's "Focus").
+FOCUS: dict[str, dict[str, float]] = {
+    "balanced": {"state_coverage": 0.3, "branch_coverage": 0.3, "happy_path": 0.2, "error_recovery": 0.2},
+    "coverage": {"state_coverage": 0.5, "branch_coverage": 0.5},
+    "errors": {"error_recovery": 0.6, "branch_coverage": 0.4},
+    "transfers": {"queue_reachability": 0.6, "state_coverage": 0.4},
+}
+
+_SELECTION = {"fitness": "FITNESS", "coverage": "ADDITIONAL_COVERAGE"}
+_RUNNING = {"INITIALIZING", "RUNNING", "PAUSED"}
+
+
+def _selection(value: Selection) -> str:
+    try:
+        return _SELECTION[value]
+    except KeyError:
+        raise ValueError(f"selection must be one of {sorted(_SELECTION)}, not {value!r}") from None
+
+
+def _flow_json(flow: str | Path | dict[str, Any]) -> str:
+    """A flow definition as a JSON string, from a dict, a JSON string or a path to a .json file."""
+    if isinstance(flow, dict):
+        return _json.dumps(flow)
+    if isinstance(flow, Path) or (isinstance(flow, str) and not flow.lstrip().startswith("{")):
+        return Path(flow).read_text(encoding="utf-8")
+    _json.loads(flow)  # fail early, with Python's message, on text that is not JSON
+    return flow
+
+
+# --------------------------------------------------------------------------- grammar
+
+
+@dataclass
+class Grammar:
+    """A flow's grammar: which calls count as tests. Editable as BNF or JSON (exact reflections)."""
+
+    _http: Http = field(repr=False)
+    flow_id: int
+    bnf: str
+    start_symbol: str = "test"
+    id: int | None = None
+    name: str | None = None
+
+    def to_bnf(self) -> str:
+        return self.bnf
+
+    def to_json(self) -> dict[str, Any]:
+        """The grammar in Diteko's JSON form (``diteko-grammar/v1``)."""
+        result = self._http.post("/grammars/convert", {"content": self.bnf, "from": "BNF", "to": "JSON", "startSymbol": self.start_symbol})
+        if not result.get("converted"):
+            raise DitekoError("The grammar cannot be converted: " + "; ".join(result.get("errors", [])))
+        return _json.loads(result["content"])
+
+    def replace(self, content: str | dict[str, Any], format: GrammarFormat = "bnf") -> "Grammar":
+        """Replace the grammar's text, given as BNF or as JSON (a dict or a string)."""
+        if format == "json":
+            text = content if isinstance(content, str) else _json.dumps(content)
+            result = self._http.post("/grammars/convert", {"content": text, "from": "JSON", "to": "BNF"})
+            if not result.get("converted"):
+                raise DitekoError("The JSON grammar cannot be read: " + "; ".join(result.get("errors", [])))
+            self.bnf = result["content"]
+            self.start_symbol = result.get("startSymbol") or self.start_symbol
+        else:
+            self.bnf = str(content)
+        return self
+
+    def save(self) -> "Grammar":
+        """Store the grammar on the flow (creating it if new) and validate it; raises if it is invalid."""
+        body = {"name": self.name or f"Grammar for flow {self.flow_id}", "bnfDefinition": self.bnf, "startSymbol": self.start_symbol, "contactFlow": {"id": self.flow_id}}
+        if self.id is None:
+            saved = self._http.post("/grammars", body)
+        else:
+            saved = self._http.put(f"/grammars/{self.id}", {**body, "id": self.id})
+        self.id, self.name = saved["id"], saved.get("name")
+        result = self._http.post(f"/grammars/{self.id}/validate")
+        if not result.get("valid"):
+            raise DitekoError("The grammar is invalid: " + "; ".join(result.get("errors", [])), body=result)
+        return self
+
+
+class GrammarAccess:
+    """``project.grammar``: the flow's latest grammar, or a new one generated from the flow."""
+
+    def __init__(self, project: "Project"):
+        self._project = project
+
+    def generate(self, save: bool = True) -> Grammar:
+        """Generate a grammar from the flow (and, by default, store and validate it)."""
+        p = self._project
+        generated = p._http.post(f"/contact-flows/{p.flow_id}/generate-grammar")
+        grammar = Grammar(p._http, p.flow_id, generated["bnfDefinition"], generated.get("startSymbol") or "test", name=f"{p.name} grammar")
+        return grammar.save() if save else grammar
+
+    def latest(self) -> Grammar | None:
+        """The grammar new runs use, or None if the flow has none yet."""
+        p = self._project.refresh()
+        if not p.summary.get("grammar"):
+            return None
+        g = p._http.get(f"/grammars/{p.summary['grammar']['id']}")
+        return Grammar(p._http, p.flow_id, g["bnfDefinition"], g.get("startSymbol") or "test", id=g["id"], name=g.get("name"))
+
+
+# --------------------------------------------------------------------------- suite and execution
+
+
+@dataclass
+class Test:
+    """One generated test: a call through the flow."""
+
+    id: int
+    test_id: str
+    steps: list[str]
+    fitness: float | None
+    priority: int | None
+    scores: dict[str, float]
+
+    @property
+    def keys(self) -> list[str]:
+        """The keys the caller presses, in order (TIMEOUT = silence, INVALID = an unoffered key)."""
+        return [s[7:] for s in self.steps if s.startswith("PRESS: ")]
+
+
+@dataclass
+class Execution:
+    """One publish to Connect's native testing: its verdicts per test."""
+
+    _http: Http = field(repr=False)
+    upload_id: str
+    raw: dict[str, Any]
+
+    @property
+    def status(self) -> str:
+        return self.raw.get("status", "")
+
+    @property
+    def dry_run(self) -> bool:
+        return bool(self.raw.get("dryRun"))
+
+    @property
+    def verdicts(self) -> dict[str, str]:
+        """Test id -> outcome (PASSED, FAILED, ERRORED for "Connect could not start it", ...)."""
+        return {e.get("testId"): e.get("status") for e in self.raw.get("executions", [])}
+
+    @property
+    def passed(self) -> int:
+        return sum(1 for v in self.verdicts.values() if v == "PASSED")
+
+    @property
+    def failed(self) -> int:
+        return sum(1 for v in self.verdicts.values() if v == "FAILED")
+
+    def refresh(self) -> "Execution":
+        self.raw = self._http.get(f"/test-cases/connect-runs/{self.upload_id}")
+        return self
+
+    def wait(self, timeout: float = 1800, poll: float = 3) -> "Execution":
+        """Block until the run completes (or raise TimeoutError)."""
+        deadline = time.monotonic() + timeout
+        while self.refresh().status != "COMPLETED":
+            if time.monotonic() > deadline:
+                raise TimeoutError(f"Connect run {self.upload_id} still {self.status} after {timeout}s")
+            time.sleep(poll)
+        return self
+
+
+@dataclass
+class Suite:
+    """The tests a completed run kept, in the order and size chosen."""
+
+    _http: Http = field(repr=False)
+    run_id: int
+    top: int | None = None
+    selection: Selection = "fitness"
+    _tests: list[Test] | None = field(default=None, repr=False)
+
+    @property
+    def tests(self) -> list[Test]:
+        if self._tests is None:
+            rows = self._http.post("/test-cases/prioritize", {"evolutionRunId": self.run_id, "topN": self.top, "selection": _selection(self.selection)})
+            self._tests = [
+                Test(r["id"], r["testId"], r.get("actions", []), r.get("compositeFitness"), r.get("priority"), r.get("fitnessScores") or {}) for r in rows
+            ]
+        return self._tests
+
+    def __len__(self) -> int:
+        return len(self.tests)
+
+    def __iter__(self) -> Iterable[Test]:  # type: ignore[override]
+        return iter(self.tests)
+
+    def export_xlsx(self, path: str | Path | None = None) -> Path:
+        """Download the Excel test script (ISO/IEC/IEEE 29119-3 layout) for manual execution."""
+        content, name = self._http.download("/test-cases/export.xlsx", evolutionRunId=self.run_id, topN=self.top, selection=_selection(self.selection))
+        target = Path(path) if path else Path(name or f"diteko-run-{self.run_id}-test-script.xlsx")
+        target.write_bytes(content)
+        return target
+
+    def _export(self, format: str, path: str | Path | None) -> Path:
+        result = self._http.post("/test-cases/export", {"evolutionRunId": self.run_id, "format": format, "topN": self.top, "selection": _selection(self.selection)})
+        target = Path(path) if path else Path(result.get("fileName") or f"diteko-run-{self.run_id}-{format.lower()}.json")
+        target.write_text(_json.dumps(result, indent=2), encoding="utf-8")
+        return target
+
+    def export_json(self, path: str | Path | None = None) -> Path:
+        """Portable JSON: every test with its steps and scores."""
+        return self._export("JSON", path)
+
+    def export_native(self, path: str | Path | None = None) -> Path:
+        """Amazon Connect native test cases (only tests Connect can run meaningfully)."""
+        return self._export("NATIVE", path)
+
+    def publish_to_connect(self, dry_run: bool = True, wait: bool = True, connect_flow_id: str | None = None) -> Execution:
+        """Publish and execute on Connect native testing. Dry run by default: nothing is called or billed."""
+        result = self._http.post(
+            "/test-cases/upload-to-connect",
+            {"evolutionRunId": self.run_id, "topN": self.top, "selection": _selection(self.selection), "dryRun": dry_run, "connectFlowId": connect_flow_id},
+        )
+        execution = Execution(self._http, result["uploadId"], result)
+        return execution.wait() if wait else execution
+
+
+# --------------------------------------------------------------------------- run
+
+
+@dataclass
+class Run:
+    """An evolution run: generations of test calls bred against the grammar."""
+
+    _http: Http = field(repr=False)
+    id: int
+    name: str | None = None
+    progress: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def status(self) -> str:
+        return self.progress.get("status", "INITIALIZING")
+
+    def refresh(self) -> "Run":
+        self.progress = self._http.get(f"/evolution-runs/{self.id}/progress")
+        return self
+
+    def wait(self, timeout: float = 3600, poll: float = 2) -> "Run":
+        """Block until the run finishes; raises DitekoError if it failed, TimeoutError if it is slow."""
+        deadline = time.monotonic() + timeout
+        while self.refresh().status in _RUNNING:
+            if time.monotonic() > deadline:
+                raise TimeoutError(f"Run {self.id} still {self.status} after {timeout}s")
+            time.sleep(poll)
+        if self.status != "COMPLETED":
+            raise DitekoError(f"Run {self.id} ended {self.status}", body=self.progress)
+        return self
+
+    def suite(self, top: int | None = None, selection: Selection = "fitness") -> Suite:
+        """The run's tests: all, or the top N by fitness or by added coverage."""
+        _selection(selection)
+        return Suite(self._http, self.id, top, selection)
+
+    def pause(self) -> "Run":
+        self._http.post(f"/evolution-runs/{self.id}/pause")
+        return self.refresh()
+
+    def resume(self) -> "Run":
+        self._http.post(f"/evolution-runs/{self.id}/resume")
+        return self.refresh()
+
+    def cancel(self) -> "Run":
+        self._http.post(f"/evolution-runs/{self.id}/cancel")
+        return self.refresh()
+
+
+# --------------------------------------------------------------------------- project
+
+
+class Project:
+    """A contact flow under test, and where it stands in the pipeline."""
+
+    def __init__(self, http: Http, summary: dict[str, Any]):
+        self._http = http
+        self.summary = summary
+        self.grammar = GrammarAccess(self)
+
+    def __repr__(self) -> str:
+        return f"Project(flow_id={self.flow_id}, name={self.name!r}, next_step={self.next_step!r})"
+
+    @property
+    def flow_id(self) -> int:
+        return int(self.summary["flowId"])
+
+    @property
+    def name(self) -> str:
+        return self.summary.get("name", "")
+
+    @property
+    def next_step(self) -> str:
+        """GRAMMAR, EVOLVE, RUN or DONE."""
+        return self.summary.get("nextStep", "")
+
+    @property
+    def connect_flow_id(self) -> str | None:
+        return self.summary.get("awsFlowId")
+
+    def refresh(self) -> "Project":
+        self.summary = self._http.get(f"/projects/{self.flow_id}")
+        return self
+
+    def validate(self) -> dict[str, Any]:
+        """Validate the flow definition: ``{"valid": bool, "errors": [...], "warnings": [...]}``."""
+        return self._http.post(f"/contact-flows/{self.flow_id}/validate")
+
+    def evolve(
+        self,
+        preset: Size = "standard",
+        focus: Focus = "balanced",
+        *,
+        name: str | None = None,
+        seed: int | None = None,
+        population: int | None = None,
+        generations: int | None = None,
+        weights: dict[str, float] | None = None,
+    ) -> Run:
+        """Start an evolution run (returns immediately; call ``.wait()``). Uses the latest grammar, or generates one."""
+        if preset not in SIZES:
+            raise ValueError(f"preset must be one of {sorted(SIZES)}")
+        if weights is None and focus not in FOCUS:
+            raise ValueError(f"focus must be one of {sorted(FOCUS)}")
+        config = {**SIZES[preset], "mutationRate": 0.1, "crossoverRate": 0.8, "tournamentSize": 3, "elitismCount": 2, "randomSeed": seed}
+        if population:
+            config["populationSize"] = population
+        if generations:
+            config["generations"] = generations
+        chosen = weights or FOCUS[focus]
+        summary = self._http.post(
+            "/evolution-runs/launch",
+            {
+                "contactFlowId": self.flow_id,
+                "grammarId": (self.refresh().summary.get("grammar") or {}).get("id"),
+                "name": name or f"{preset.capitalize()} run, {focus} focus",
+                "optimizationStrategy": "WEIGHTED_SUM",
+                "config": config,
+                "fitnessWeights": [{"fitnessFunctionId": k, "weight": v, "enabled": True, "priority": i} for i, (k, v) in enumerate(chosen.items())],
+            },
+        )
+        return Run(self._http, summary["id"], summary.get("name")).refresh()
+
+    def runs(self) -> list[Run]:
+        """The flow's evolution runs, newest first."""
+        rows = self._http.get("/evolution-runs", **{"contactFlowId.equals": self.flow_id, "sort": "id,desc", "size": 200})
+        return [Run(self._http, r["id"], r.get("name"), {"status": r.get("status")}) for r in rows]
+
+    def suite(self, top: int | None = None, selection: Selection = "fitness") -> Suite:
+        """The project's current suite (its latest completed run that produced tests)."""
+        run_id = self.refresh().summary.get("suiteRunId")
+        if run_id is None:
+            raise DitekoError(f"{self.name} has no suite yet; run project.evolve().wait() first")
+        return Run(self._http, run_id).suite(top, selection)
+
+
+class Projects:
+    """``dk.projects``: list, open, and create projects from flow JSON, cxblueprint or Connect."""
+
+    def __init__(self, http: Http):
+        self._http = http
+
+    def list(self) -> list[Project]:
+        return [Project(self._http, p) for p in self._http.get("/projects")]
+
+    def get(self, flow_id: int) -> Project:
+        return Project(self._http, self._http.get(f"/projects/{flow_id}"))
+
+    def find(self, name: str) -> Project | None:
+        return next((p for p in self.list() if p.name == name), None)
+
+    def from_json(self, flow: str | Path | dict[str, Any], name: str | None = None, description: str | None = None) -> Project:
+        """Register a flow from Connect-exported or cxblueprint-compiled JSON (a dict, a JSON string, or a file path)."""
+        definition = _flow_json(flow)
+        if name is None:
+            name = Path(flow).stem if isinstance(flow, (str, Path)) and not str(flow).lstrip().startswith("{") else None
+        if not name:
+            raise ValueError("name is required when the flow is not given as a file path")
+        created = self._http.post("/contact-flows", {"name": name, "description": description, "definition": definition})
+        return self.get(created["id"])
+
+    def from_cxblueprint(self, flow: Any, name: str | None = None) -> Project:
+        """Register a flow built with cxblueprint: compiles it (``flow.compile()``) and uploads the JSON."""
+        compiled = flow.compile()
+        return self.from_json(compiled, name=name or getattr(flow, "name", None) or compiled.get("Metadata", {}).get("name"))
+
+    def import_from_connect(self, connect_flow_id: str) -> Project:
+        """Import (or refresh) a flow straight from the configured Connect instance."""
+        imported = self._http.post("/contact-flows/import-from-connect", {"connectFlowId": connect_flow_id})
+        return self.get(imported["id"])
+
+
+class Diteko:
+    """Entry point::
+
+    dk = Diteko("http://localhost:8888")
+    project = dk.projects.from_json("claims.json")
+    project.grammar.generate()
+    run = project.evolve(preset="standard").wait()
+    suite = run.suite(top=30, selection="coverage")
+    suite.export_xlsx("claims-tests.xlsx")
+    suite.publish_to_connect(dry_run=True)
+    """
+
+    def __init__(self, url: str = "http://localhost:8888", *, timeout: float = 60.0, transport: Any = None):
+        self._http = Http(url, timeout=timeout, transport=transport)
+        self.projects = Projects(self._http)
+
+    def connect_settings(self) -> dict[str, Any]:
+        """How the deployment reaches Amazon Connect (read-only)."""
+        return self._http.get("/settings/connect")
+
+    def convert_grammar(self, content: str, source: GrammarFormat, target: GrammarFormat, start_symbol: str | None = None) -> str:
+        """Convert a grammar between BNF and JSON without storing it."""
+        result = self._http.post("/grammars/convert", {"content": content, "from": source.upper(), "to": target.upper(), "startSymbol": start_symbol})
+        if not result.get("converted"):
+            raise DitekoError("The grammar cannot be converted: " + "; ".join(result.get("errors", [])), body=result)
+        return result["content"]
+
+    def run(self, run_id: int) -> Run:
+        return Run(self._http, run_id).refresh()
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "Diteko":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()

diteko-0.1.0.dist-info/METADATA

@@ -0,0 +1,147 @@
+Metadata-Version: 2.5
+Name: diteko
+Version: 0.1.0
+Summary: Generate, export and run tests for Amazon Connect contact flows with Diteko (Grammatical Evolution).
+Author: Lehlohonolo Sehako
+License-Expression: MIT
+License-File: LICENSE
+Keywords: amazon-connect,contact-flow,cxblueprint,grammatical-evolution,ivr,mcp,testing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Telephony
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: cxblueprint
+Requires-Dist: cxblueprint>=0.1.0.post15; extra == 'cxblueprint'
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp<3,>=1.26.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# diteko (Python)
+
+Generate, export and run tests for Amazon Connect contact flows, from Python. It is the
+testing counterpart to [cxblueprint](https://pypi.org/project/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. Diteko has no application-level authentication, so point the SDK only
+at a deployment inside your network or behind your VPN.
+
+```bash
+pip install diteko               # SDK
+pip install "diteko[mcp]"        # + MCP server for Claude Desktop / Cursor / VS Code
+pip install "diteko[cxblueprint]"
+```
+
+## The pipeline
+
+```python
+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
+
+```python
+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
+
+```python
+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.
+
+```python
+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
+
+| `preset`   | calls × generations |
+| ---------- | ------------------- |
+| `quick`    | 40 × 15             |
+| `standard` | 100 × 50            |
+| `thorough` | 200 × 120           |
+
+| `focus`     | favours                                              |
+| ----------- | ---------------------------------------------------- |
+| `balanced`  | blocks and branches, plus happy paths and recoveries |
+| `coverage`  | visiting as much of the flow as possible             |
+| `errors`    | timeouts and wrong keys that still end properly      |
+| `transfers` | calls that reach an agent queue                      |
+
+Pass `population=`, `generations=`, `weights={"state_coverage": 1.0}` or `seed=` to go beyond them.
+
+## MCP server
+
+```bash
+DITEKO_URL=http://localhost:8888 diteko-mcp
+```
+
+```json
+{ "mcpServers": { "diteko": { "command": "diteko-mcp", "env": { "DITEKO_URL": "http://localhost:8888" } } } }
+```
+
+| Tool               | Does                                                                                   |
+| ------------------ | -------------------------------------------------------------------------------------- |
+| `list_projects`    | every flow under test and its next step                                                |
+| `import_flow`      | register a flow from JSON text, a file path, or a Connect flow id                      |
+| `generate_grammar` | derive, store and validate a flow's grammar                                            |
+| `convert_grammar`  | BNF ⇄ JSON                                                                             |
+| `start_evolution`  | start a run (`size`, `focus`, `seed`)                                                  |
+| `get_run`          | a run's progress                                                                       |
+| `export_suite`     | `xlsx`, `json` or `native` to a file                                                   |
+| `publish_suite`    | run on Connect; **`dry_run` defaults to true**, since a live run bills the AWS account |
+
+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.
+
+## Development
+
+```bash
+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 test against a local stack
+```

diteko-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+diteko/__init__.py,sha256=363wbvJr5w8gffrrjGYPuOCrGfP_SANJsnYzM7224-s,569
+diteko/_http.py,sha256=Hk02TgDmnLXtgnoIAx6JE7IHPROrN1VDbAMtZhYnVq0,2465
+diteko/mcp_server.py,sha256=pxlM3PnwIPmC5KL90ZdC6r9LVinsLm_Jy83QJYj-Xzc,5619
+diteko/sdk.py,sha256=Q2RczIc-fME4J29KlD_b6gAm50qfaH88hM6cFYUPSa4,19198
+diteko-0.1.0.dist-info/METADATA,sha256=74ECbggZOkhM-HWMRBpBob2v7eb2p_opbER5RPGe4_s,6172
+diteko-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+diteko-0.1.0.dist-info/entry_points.txt,sha256=oTJxDSGXTDoFmTelRfGKWUQ1L8qaBE3PVfc_MrFRyno,54
+diteko-0.1.0.dist-info/licenses/LICENSE,sha256=QIt3DrYQ3kwXLLojBU8WMLzohCjpBGi2Z-fldHQL5A8,1075
+diteko-0.1.0.dist-info/RECORD,,

diteko-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

diteko-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+diteko-mcp = diteko.mcp_server:main

diteko-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lehlohonolo Sehako
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.