diteko 0.2.0__tar.gz → 0.4.0__tar.gz

{diteko-0.2.0 → diteko-0.4.0}/CHANGELOG.md

@@ -4,6 +4,33 @@ All notable changes to the `diteko` Python package. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
 [Semantic Versioning](https://semver.org/) as described under “Versioning” in the README.
 
+## [0.4.0] - 2026-10-11
+
+### Added
+
+- `Verdict.attempts` and `Verdict.passed_on_rerun`. A server on API 1.2 re-runs a test
+  that failed, once, because Connect's prompt recognition sometimes misses a prompt the
+  flow played; a pass on the re-run is reported as a pass with `attempts == 2`. Older
+  servers leave `attempts` as `None`.
+
+## [0.3.0] - 2026-10-11
+
+### Added
+
+- `Run.wait(progress=True)` keeps a line on stderr up to date while a run evolves; pass
+  a callable instead to receive a `RunProgress` whenever the generation or status changes.
+- Typed views alongside the raw responses: `Run.info` (`RunProgress`), `Project.info`
+  (`ProjectInfo`: grammar, latest run, suite, last execution), `Execution.results`
+  (`Verdict`s with Connect's message) and `Execution.inconclusive`.
+- `Diteko()` reads `DITEKO_URL` when no address is given, as `diteko-mcp` already did.
+- A getting-started guide in this README, and `examples/cxblueprint_to_excel.py` (and the
+  same as a notebook): from a cxblueprint flow to an Excel test script.
+
+### Fixed
+
+- A project's last execution no longer reads as RUNNING for a moment after the execution
+  reported COMPLETED (fixed server-side).
+
 ## [0.2.0] - 2026-10-11
 
 ### Added
@@ -34,5 +61,7 @@ All notable changes to the `diteko` Python package. The format follows
 - `diteko-mcp`, an MCP server exposing the same pipeline as eight tools, on `mcp`
   1.x or 2.x.
 
+[0.4.0]: https://pypi.org/project/diteko/0.4.0/
+[0.3.0]: https://pypi.org/project/diteko/0.3.0/
 [0.2.0]: https://pypi.org/project/diteko/0.2.0/
 [0.1.0]: https://pypi.org/project/diteko/0.1.0/

{diteko-0.2.0 → diteko-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: diteko
-Version: 0.2.0
+Version: 0.4.0
 Summary: Generate, export and run tests for Amazon Connect contact flows with Diteko (Grammatical Evolution).
 Author: Lehlohonolo Sehako
 License-Expression: MIT
@@ -46,6 +46,41 @@ pip install "diteko[mcp]"        # + MCP server for Claude Desktop / Cursor / VS
 pip install "diteko[cxblueprint]"
 ```
 
+## Getting started
+
+1. **Find your Diteko.** Diteko is self-hosted: you need the address of a running deployment, such as `http://localhost:8888` when you run it yourself.
+2. **Get a key, if it asks for one.** When a deployment requires API keys, whoever runs it creates one for you under Settings › API keys. `WRITE` is enough for everything here except live runs on Connect. Put it in the environment:
+
+   ```bash
+   export DITEKO_URL=https://diteko.example.internal
+   export DITEKO_API_KEY=dk_...     # only if the deployment requires keys
+   ```
+
+3. **Check the connection:**
+
+   ```python
+   from diteko import Diteko
+
+   dk = Diteko()            # DITEKO_URL and DITEKO_API_KEY from the environment
+   print(dk.version())      # {'api': '1.1', 'server': '…', 'auth': 'keys'}
+   print(dk.whoami())       # the key in use, or None when keys are off
+   ```
+
+4. **Run the example.** `examples/cxblueprint_to_excel.py`, also as a notebook, builds a flow with cxblueprint, evolves a suite and writes the Excel test script, in about a minute. Both ship in the source distribution: `pip download --no-binary :all: --no-deps diteko`, then unpack it.
+
+## Watching a run, and typed results
+
+```python
+run = project.evolve(preset="standard").wait(progress=True)       # one line on stderr, kept up to date
+run = project.evolve(preset="standard").wait(progress=print)      # or any callable, given a RunProgress
+run.info.best_fitness, run.info.generation, run.info.generations
+
+project.refresh().info            # ProjectInfo: grammar, latest run, suite, last execution, typed
+execution = suite.publish_to_connect(dry_run=True)
+execution.results                 # [Verdict(test_id, status, message), ...]
+execution.passed, execution.failed, execution.inconclusive   # inconclusive: Connect could not start it, etc.
+```
+
 ## The pipeline
 
 ```python
@@ -182,6 +217,33 @@ All notable changes to the `diteko` Python package. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
 [Semantic Versioning](https://semver.org/) as described under “Versioning” in the README.
 
+## [0.4.0] - 2026-10-11
+
+### Added
+
+- `Verdict.attempts` and `Verdict.passed_on_rerun`. A server on API 1.2 re-runs a test
+  that failed, once, because Connect's prompt recognition sometimes misses a prompt the
+  flow played; a pass on the re-run is reported as a pass with `attempts == 2`. Older
+  servers leave `attempts` as `None`.
+
+## [0.3.0] - 2026-10-11
+
+### Added
+
+- `Run.wait(progress=True)` keeps a line on stderr up to date while a run evolves; pass
+  a callable instead to receive a `RunProgress` whenever the generation or status changes.
+- Typed views alongside the raw responses: `Run.info` (`RunProgress`), `Project.info`
+  (`ProjectInfo`: grammar, latest run, suite, last execution), `Execution.results`
+  (`Verdict`s with Connect's message) and `Execution.inconclusive`.
+- `Diteko()` reads `DITEKO_URL` when no address is given, as `diteko-mcp` already did.
+- A getting-started guide in this README, and `examples/cxblueprint_to_excel.py` (and the
+  same as a notebook): from a cxblueprint flow to an Excel test script.
+
+### Fixed
+
+- A project's last execution no longer reads as RUNNING for a moment after the execution
+  reported COMPLETED (fixed server-side).
+
 ## [0.2.0] - 2026-10-11
 
 ### Added
@@ -212,5 +274,7 @@ All notable changes to the `diteko` Python package. The format follows
 - `diteko-mcp`, an MCP server exposing the same pipeline as eight tools, on `mcp`
   1.x or 2.x.
 
+[0.4.0]: https://pypi.org/project/diteko/0.4.0/
+[0.3.0]: https://pypi.org/project/diteko/0.3.0/
 [0.2.0]: https://pypi.org/project/diteko/0.2.0/
 [0.1.0]: https://pypi.org/project/diteko/0.1.0/

{diteko-0.2.0 → diteko-0.4.0}/README.md

@@ -16,6 +16,41 @@ pip install "diteko[mcp]"        # + MCP server for Claude Desktop / Cursor / VS
 pip install "diteko[cxblueprint]"
 ```
 
+## Getting started
+
+1. **Find your Diteko.** Diteko is self-hosted: you need the address of a running deployment, such as `http://localhost:8888` when you run it yourself.
+2. **Get a key, if it asks for one.** When a deployment requires API keys, whoever runs it creates one for you under Settings › API keys. `WRITE` is enough for everything here except live runs on Connect. Put it in the environment:
+
+   ```bash
+   export DITEKO_URL=https://diteko.example.internal
+   export DITEKO_API_KEY=dk_...     # only if the deployment requires keys
+   ```
+
+3. **Check the connection:**
+
+   ```python
+   from diteko import Diteko
+
+   dk = Diteko()            # DITEKO_URL and DITEKO_API_KEY from the environment
+   print(dk.version())      # {'api': '1.1', 'server': '…', 'auth': 'keys'}
+   print(dk.whoami())       # the key in use, or None when keys are off
+   ```
+
+4. **Run the example.** `examples/cxblueprint_to_excel.py`, also as a notebook, builds a flow with cxblueprint, evolves a suite and writes the Excel test script, in about a minute. Both ship in the source distribution: `pip download --no-binary :all: --no-deps diteko`, then unpack it.
+
+## Watching a run, and typed results
+
+```python
+run = project.evolve(preset="standard").wait(progress=True)       # one line on stderr, kept up to date
+run = project.evolve(preset="standard").wait(progress=print)      # or any callable, given a RunProgress
+run.info.best_fitness, run.info.generation, run.info.generations
+
+project.refresh().info            # ProjectInfo: grammar, latest run, suite, last execution, typed
+execution = suite.publish_to_connect(dry_run=True)
+execution.results                 # [Verdict(test_id, status, message), ...]
+execution.passed, execution.failed, execution.inconclusive   # inconclusive: Connect could not start it, etc.
+```
+
 ## The pipeline
 
 ```python

diteko-0.4.0/examples/cxblueprint_to_excel.ipynb

@@ -0,0 +1,179 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# From a cxblueprint flow to an Excel test script\n",
+    "\n",
+    "Build a phone menu with [cxblueprint](https://pypi.org/project/cxblueprint/), then let Diteko derive its grammar, evolve a suite of test calls, and write the Excel script that business testers follow by hand.\n",
+    "\n",
+    "You need a running Diteko. Set `DITEKO_URL` (and `DITEKO_API_KEY` if your deployment requires keys) before starting the notebook, or pass them to `Diteko(...)` below."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "execution_count": null,
+   "outputs": [],
+   "source": [
+    "%pip install -q \"diteko[cxblueprint]\""
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 1. A flow, built the cxblueprint way"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "execution_count": null,
+   "outputs": [],
+   "source": [
+    "from cxblueprint import Flow\n",
+    "\n",
+    "flow = Flow.build(\"Burger Order\")\n",
+    "welcome = flow.play_prompt(\"Welcome to Burger Palace!\")\n",
+    "menu = flow.get_input(\"Press 1 for Classic Burger or 2 for Veggie Burger\", timeout=10)\n",
+    "welcome.then(menu)\n",
+    "classic = flow.play_prompt(\"You selected Classic Burger. Your order is confirmed!\")\n",
+    "veggie = flow.play_prompt(\"You selected Veggie Burger. Your order is confirmed!\")\n",
+    "sorry = flow.play_prompt(\"Invalid selection. Goodbye.\")\n",
+    "bye = flow.disconnect()\n",
+    "menu.when(\"1\", classic).when(\"2\", veggie).otherwise(sorry)\n",
+    "menu.on_error(\"InputTimeLimitExceeded\", sorry).on_error(\"NoMatchingCondition\", sorry).on_error(\"NoMatchingError\", sorry)\n",
+    "for block in (classic, veggie, sorry):\n",
+    "    block.then(bye)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 2. Register it with Diteko\n",
+    "\n",
+    "The flow is compiled here and uploaded as JSON. The first call also checks that the server speaks this SDK's API version."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "execution_count": null,
+   "outputs": [],
+   "source": [
+    "import os, time\n",
+    "from diteko import Diteko\n",
+    "\n",
+    "dk = Diteko(os.environ.get(\"DITEKO_URL\", \"http://localhost:8888\"))\n",
+    "print(dk.version())\n",
+    "project = dk.projects.from_cxblueprint(flow, name=f\"Burger Order example {int(time.time())}\")\n",
+    "project"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 3. Its grammar: everything a caller can do\n",
+    "\n",
+    "Editable as BNF or JSON; the two are exact reflections of each other."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "execution_count": null,
+   "outputs": [],
+   "source": [
+    "grammar = project.grammar.generate()\n",
+    "print(grammar.to_bnf())"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 4. Evolve a suite\n",
+    "\n",
+    "`progress=True` keeps a line updated while the run breeds test calls. `quick` is 40 calls over 15 generations."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "execution_count": null,
+   "outputs": [],
+   "source": [
+    "run = project.evolve(preset=\"quick\", focus=\"coverage\", seed=1).wait(progress=True)\n",
+    "run.info"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 5. The suite, read as calls"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "execution_count": null,
+   "outputs": [],
+   "source": [
+    "suite = run.suite(selection=\"coverage\")\n",
+    "for test in suite:\n",
+    "    print(test.test_id, \"presses\", \" \".join(test.keys) or \"nothing\", f\"fitness {test.fitness:.2f}\")\n",
+    "    for step in test.steps:\n",
+    "        print(\"    \", step)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 6. The Excel test script, and a dry run on Connect\n",
+    "\n",
+    "The workbook follows ISO/IEC/IEEE 29119-3: a cover sheet, plain-language steps with expected results, and Pass / Fail / Blocked / Skipped columns. The dry run translates every test to Connect's native format without publishing or billing anything."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "execution_count": null,
+   "outputs": [],
+   "source": [
+    "path = suite.export_xlsx(\"burger-order-tests.xlsx\")\n",
+    "print(\"Excel test script:\", path)\n",
+    "\n",
+    "execution = suite.publish_to_connect(dry_run=True)\n",
+    "for verdict in execution.results:\n",
+    "    print(verdict.test_id, verdict.status)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "execution_count": null,
+   "outputs": [],
+   "source": [
+    "project.refresh().info"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

diteko-0.4.0/examples/cxblueprint_to_excel.py

@@ -0,0 +1,56 @@
+"""From a cxblueprint flow to an Excel test script, with Diteko.
+
+    pip install "diteko[cxblueprint]"
+    DITEKO_URL=http://localhost:8888 python cxblueprint_to_excel.py
+    # add DITEKO_API_KEY=dk_... if your Diteko requires keys
+
+It builds a small ordering line with cxblueprint, lets Diteko derive its grammar and
+evolve a suite of test calls, prints the suite, writes the Excel script that business
+testers follow by hand, and does a dry run on Connect (nothing is published or billed).
+"""
+
+import os
+import time
+
+from cxblueprint import Flow
+
+from diteko import Diteko
+
+# 1. A flow, built the cxblueprint way.
+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!")
+sorry = flow.play_prompt("Invalid selection. Goodbye.")
+bye = flow.disconnect()
+menu.when("1", classic).when("2", veggie).otherwise(sorry)
+menu.on_error("InputTimeLimitExceeded", sorry).on_error("NoMatchingCondition", sorry).on_error("NoMatchingError", sorry)
+for block in (classic, veggie, sorry):
+    block.then(bye)
+
+with Diteko(os.environ.get("DITEKO_URL", "http://localhost:8888")) as dk:
+    print("Server:", dk.version())
+
+    # 2. Register it as a project (compiled locally, uploaded as JSON).
+    project = dk.projects.from_cxblueprint(flow, name=f"Burger Order example {int(time.time())}")
+    print(project)
+
+    # 3. A grammar of everything a caller can do, then a quick evolution run.
+    grammar = project.grammar.generate()
+    print(grammar.to_bnf())
+    run = project.evolve(preset="quick", focus="coverage", seed=1).wait(progress=True)
+
+    # 4. The suite, read as calls.
+    suite = run.suite(selection="coverage")
+    for test in suite:
+        print(f"{test.test_id}  keys {' '.join(test.keys) or '(none)':<12}  fitness {test.fitness:.2f}")
+
+    # 5. The manual test script, and a dry run on Connect.
+    path = suite.export_xlsx("burger-order-tests.xlsx")
+    print("Excel test script:", path)
+    execution = suite.publish_to_connect(dry_run=True)
+    print(f"Dry run {execution.status.lower()}: {len(execution.results)} tests translated, nothing published")
+
+    print(project.refresh().info)

{diteko-0.2.0 → diteko-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "diteko"
-version = "0.2.0"
+version = "0.4.0"
 description = "Generate, export and run tests for Amazon Connect contact flows with Diteko (Grammatical Evolution)."
 dynamic = ["readme"]
 requires-python = ">=3.10"

diteko-0.4.0/src/diteko/__init__.py

@@ -0,0 +1,41 @@
+"""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,
+    ProjectInfo,
+    Projects,
+    Run,
+    RunProgress,
+    Suite,
+    Test,
+    Verdict,
+)
+
+__all__ = [
+    "Diteko",
+    "DitekoError",
+    "Execution",
+    "FOCUS",
+    "Grammar",
+    "Project",
+    "ProjectInfo",
+    "Projects",
+    "Run",
+    "RunProgress",
+    "SIZES",
+    "Suite",
+    "Test",
+    "Verdict",
+]
+__version__ = "0.4.0"

{diteko-0.2.0 → diteko-0.4.0}/src/diteko/mcp_server.py

@@ -41,7 +41,7 @@ _client: Diteko | None = None
 def _dk() -> Diteko:
     global _client
     if _client is None:
-        _client = Diteko(os.environ.get("DITEKO_URL", "http://localhost:8888"))
+        _client = Diteko()  # DITEKO_URL and DITEKO_API_KEY from the environment
     return _client
 
 

{diteko-0.2.0 → diteko-0.4.0}/src/diteko/sdk.py

@@ -7,10 +7,12 @@ flow -> grammar -> evolve (a run) -> suite -> run on Connect -> results.
 from __future__ import annotations
 
 import json as _json
+import os
+import sys
 import time
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Any, Iterable, Literal
+from typing import Any, Callable, Iterable, Literal
 
 from ._http import DitekoError, Http
 
@@ -131,6 +133,135 @@ class GrammarAccess:
 # --------------------------------------------------------------------------- suite and execution
 
 
+# --------------------------------------------------------------------------- typed views
+
+
+@dataclass(frozen=True)
+class RunProgress:
+    """Where an evolution run stands: one generation's figures."""
+
+    run_id: int
+    status: str
+    generation: int
+    generations: int
+    best_fitness: float | None
+    average_fitness: float | None
+    population: int | None
+
+    @property
+    def done(self) -> bool:
+        return self.status not in _RUNNING
+
+    @property
+    def fraction(self) -> float:
+        """0.0 to 1.0, by generations completed."""
+        return self.generation / self.generations if self.generations else 0.0
+
+    def __str__(self) -> str:
+        best = "n/a" if self.best_fitness is None else f"{self.best_fitness:.3f}"
+        return f"Run {self.run_id}: generation {self.generation}/{self.generations}, best fitness {best}, {self.status.lower()}"
+
+    @classmethod
+    def of(cls, raw: dict[str, Any], run_id: int) -> "RunProgress":
+        return cls(
+            run_id=int(raw.get("runId") or run_id),
+            status=raw.get("status") or "INITIALIZING",
+            generation=int(raw.get("currentGeneration") or 0),
+            generations=int(raw.get("totalGenerations") or 0),
+            best_fitness=raw.get("bestFitness"),
+            average_fitness=raw.get("averageFitness"),
+            population=raw.get("populationSize"),
+        )
+
+
+@dataclass(frozen=True)
+class Verdict:
+    """What Connect decided about one test in an execution."""
+
+    test_id: str
+    status: str
+    message: str | None = None
+    attempts: int | None = None
+    """Executions started: 2 when the test failed and the server re-ran it (API 1.2; None from older servers)."""
+
+    @property
+    def conclusive(self) -> bool:
+        """PASSED or FAILED. Anything else (ERRORED: Connect could not start it; SKIPPED; a dry run's transcode) says nothing about the flow."""
+        return self.status in ("PASSED", "FAILED")
+
+    @property
+    def passed_on_rerun(self) -> bool:
+        """Failed once, then passed when re-run: most likely a prompt Connect's recognition missed, not a defect."""
+        return self.status == "PASSED" and (self.attempts or 1) > 1
+
+
+@dataclass(frozen=True)
+class GrammarInfo:
+    id: int
+    name: str | None
+    valid: bool | None
+
+
+@dataclass(frozen=True)
+class RunInfo:
+    id: int
+    name: str | None
+    status: str | None
+    tests: int
+    generation: int | None
+    generations: int | None
+
+
+@dataclass(frozen=True)
+class ExecutionInfo:
+    upload_id: str
+    status: str | None
+    dry_run: bool
+    passed: int
+    failed: int
+    total: int
+
+
+@dataclass(frozen=True)
+class ProjectInfo:
+    """A project's place in the pipeline, typed. ``Project.summary`` keeps the raw response."""
+
+    flow_id: int
+    name: str
+    next_step: str
+    connect_flow_id: str | None
+    grammars: int
+    grammar: GrammarInfo | None
+    runs: int
+    latest_run: RunInfo | None
+    suite_run_id: int | None
+    last_execution: ExecutionInfo | None
+
+    @classmethod
+    def of(cls, raw: dict[str, Any]) -> "ProjectInfo":
+        g, r, e = raw.get("grammar"), raw.get("latestRun"), raw.get("lastExecution")
+        return cls(
+            flow_id=int(raw["flowId"]),
+            name=raw.get("name", ""),
+            next_step=raw.get("nextStep", ""),
+            connect_flow_id=raw.get("awsFlowId"),
+            grammars=int(raw.get("grammarCount") or 0),
+            grammar=GrammarInfo(int(g["id"]), g.get("name"), g.get("valid")) if g else None,
+            runs=int(raw.get("runCount") or 0),
+            latest_run=RunInfo(
+                int(r["id"]), r.get("name"), r.get("status"), int(r.get("testCount") or 0), r.get("currentGeneration"), r.get("totalGenerations")
+            )
+            if r
+            else None,
+            suite_run_id=raw.get("suiteRunId"),
+            last_execution=ExecutionInfo(
+                e.get("uploadId", ""), e.get("status"), bool(e.get("dryRun")), int(e.get("passed") or 0), int(e.get("failed") or 0), int(e.get("total") or 0)
+            )
+            if e
+            else None,
+        )
+
+
 @dataclass
 class Test:
     """One generated test: a call through the flow."""
@@ -177,6 +308,18 @@ class Execution:
     def failed(self) -> int:
         return sum(1 for v in self.verdicts.values() if v == "FAILED")
 
+    @property
+    def results(self) -> list[Verdict]:
+        """Every test's outcome, with Connect's message where there is one."""
+        return [
+            Verdict(e.get("testId", ""), e.get("status", ""), e.get("message"), e.get("attempts")) for e in self.raw.get("executions", [])
+        ]
+
+    @property
+    def inconclusive(self) -> int:
+        """Tests that ended neither PASSED nor FAILED: they say nothing about the flow."""
+        return sum(1 for v in self.results if not v.conclusive)
+
     def refresh(self) -> "Execution":
         self.raw = self._http.get(f"/test-cases/connect-runs/{self.upload_id}")
         return self
@@ -263,17 +406,42 @@ class Run:
     def status(self) -> str:
         return self.progress.get("status", "INITIALIZING")
 
+    @property
+    def info(self) -> RunProgress:
+        """The latest progress, typed (as of the last refresh)."""
+        return RunProgress.of(self.progress, self.id)
+
     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."""
+    def wait(
+        self,
+        timeout: float = 3600,
+        poll: float = 2,
+        progress: bool | Callable[[RunProgress], Any] = False,
+    ) -> "Run":
+        """Block until the run finishes; raises DitekoError if it failed, TimeoutError if it is slow.
+
+        ``progress=True`` keeps one line on stderr up to date; a callable is called with a
+        :class:`RunProgress` whenever the generation or the status changes, ending with the final state.
+        """
         deadline = time.monotonic() + timeout
-        while self.refresh().status in _RUNNING:
+        report = _progress_printer() if progress is True else (progress or None)
+        last: tuple[int, str] | None = None
+        while True:
+            self.refresh()
+            now = (self.info.generation, self.info.status)
+            if report and now != last:
+                last = now
+                report(self.info)
+            if self.status not in _RUNNING:
+                break
             if time.monotonic() > deadline:
                 raise TimeoutError(f"Run {self.id} still {self.status} after {timeout}s")
             time.sleep(poll)
+        if progress is True:
+            print(file=sys.stderr)
         if self.status != "COMPLETED":
             raise DitekoError(f"Run {self.id} ended {self.status}", body=self.progress)
         return self
@@ -296,6 +464,19 @@ class Run:
         return self.refresh()
 
 
+def _progress_printer() -> Callable[[RunProgress], None]:
+    """One line on stderr, rewritten in place where the terminal allows it."""
+    tty = sys.stderr.isatty()
+
+    def report(p: RunProgress) -> None:
+        if tty:
+            print(f"\r{p}".ljust(80), end="", file=sys.stderr, flush=True)
+        else:
+            print(p, file=sys.stderr, flush=True)
+
+    return report
+
+
 # --------------------------------------------------------------------------- project
 
 
@@ -327,6 +508,11 @@ class Project:
     def connect_flow_id(self) -> str | None:
         return self.summary.get("awsFlowId")
 
+    @property
+    def info(self) -> ProjectInfo:
+        """Grammar, latest run, suite and last execution, typed (as of the last refresh)."""
+        return ProjectInfo.of(self.summary)
+
     def refresh(self) -> "Project":
         self.summary = self._http.get(f"/projects/{self.flow_id}")
         return self
@@ -433,15 +619,17 @@ class Diteko:
 
     def __init__(
         self,
-        url: str = "http://localhost:8888",
+        url: str | None = None,
         *,
         api_key: str | None = None,
         timeout: float = 60.0,
         transport: Any = None,
         check_version: bool = True,
     ):
-        """``api_key`` defaults to ``DITEKO_API_KEY`` and is needed when the server requires keys.
+        """``url`` defaults to ``DITEKO_URL``, then ``http://localhost:8888``. ``api_key`` defaults to
+        ``DITEKO_API_KEY`` and is needed when the server requires keys.
         ``check_version`` makes the first call confirm the server speaks this SDK's API major version."""
+        url = url or os.environ.get("DITEKO_URL") or "http://localhost:8888"
         self._http = Http(url, timeout=timeout, transport=transport, check_version=check_version, api_key=api_key)
         self.projects = Projects(self._http)
 

{diteko-0.2.0 → diteko-0.4.0}/tests/fake_api.py

@@ -99,9 +99,10 @@ class FakeApi:
         if m == "GET" and (mt := re.fullmatch(r"/evolution-runs/(\d+)/progress", path)):
             r = self.runs[int(mt[1])]
             r["polls"] += 1
-            if r["polls"] > 1:
+            if r["polls"] > 3:
                 r["status"] = "COMPLETED"
-            return ok({"status": r["status"], "currentGeneration": 5, "totalGenerations": 5, "bestFitness": 0.8})
+            gen = min(r["polls"] * 2, 5)
+            return ok({"runId": r["id"], "status": r["status"], "currentGeneration": gen, "totalGenerations": 5, "bestFitness": 0.4 + gen / 10})
         if m == "POST" and path == "/test-cases/prioritize":
             return ok(
                 [
@@ -116,7 +117,7 @@ class FakeApi:
         if m == "POST" and path == "/test-cases/upload-to-connect":
             return ok({"uploadId": "u-1", "status": "RUNNING", "dryRun": body["dryRun"], "executions": []}, 202)
         if m == "GET" and path == "/test-cases/connect-runs/u-1":
-            return ok({"uploadId": "u-1", "status": "COMPLETED", "dryRun": True, "executions": [{"testId": "GE-0001", "status": "PASSED"}, {"testId": "GE-0002", "status": "FAILED"}]})
+            return ok({"uploadId": "u-1", "status": "COMPLETED", "dryRun": True, "executions": [{"testId": "GE-0001", "status": "PASSED", "attempts": 2}, {"testId": "GE-0002", "status": "FAILED", "message": "Expected prompt not heard"}, {"testId": "GE-0003", "status": "ERRORED", "message": "Connect could not start the test"}]})
         if m == "GET" and path == "/settings/connect":
             return ok({"enabled": False, "maxConcurrent": 5, "executionBudgetSeconds": 240})
         return ok({"title": f"no fake for {m} {path}"}, 404)

{diteko-0.2.0 → diteko-0.4.0}/tests/test_sdk.py

@@ -165,3 +165,52 @@ def test_a_wrong_key_is_reported_as_refused(api):
 
 def test_whoami_is_none_when_the_server_does_not_require_keys(dk):
     assert dk.whoami() is None
+
+
+def test_wait_reports_progress_each_generation(dk, monkeypatch):
+    monkeypatch.setattr("time.sleep", lambda s: None)
+    project = dk.projects.from_json(FLOW, name="progress")
+    seen = []
+    run = project.evolve(preset="quick").wait(progress=seen.append)
+    states = [(p.generation, p.status) for p in seen]
+    assert len(states) >= 2 and len(states) == len(set(states))  # once per change of generation or status
+    assert [g for g, _ in states] == sorted(g for g, _ in states)
+    assert seen[-1].done and seen[-1].generation == 5 and seen[-1].fraction == 1.0
+    assert run.info.best_fitness == pytest.approx(0.9)
+    assert "generation 5/5" in str(seen[-1])
+
+
+def test_wait_can_print_a_progress_line(dk, monkeypatch, capsys):
+    monkeypatch.setattr("time.sleep", lambda s: None)
+    dk.projects.from_json(FLOW, name="printed").evolve(preset="quick").wait(progress=True)
+    assert "best fitness" in capsys.readouterr().err
+
+
+def test_project_info_is_typed(dk, monkeypatch):
+    monkeypatch.setattr("time.sleep", lambda s: None)
+    project = dk.projects.from_json(FLOW, name="typed")
+    project.grammar.generate()
+    project.evolve(preset="quick").wait()
+    info = project.refresh().info
+    assert info.name == "typed" and info.next_step == "RUN"
+    assert info.grammar is not None and info.grammar.valid
+    assert info.suite_run_id is not None
+
+
+def test_execution_results_separate_inconclusive_tests(dk, monkeypatch):
+    monkeypatch.setattr("time.sleep", lambda s: None)
+    project = dk.projects.from_json(FLOW, name="verdicts")
+    execution = project.evolve(preset="quick").wait().suite().publish_to_connect()
+    assert [(v.test_id, v.conclusive) for v in execution.results] == [("GE-0001", True), ("GE-0002", True), ("GE-0003", False)]
+    assert execution.results[1].message == "Expected prompt not heard"
+    assert execution.results[0].passed_on_rerun and execution.results[0].attempts == 2
+    assert not execution.results[1].passed_on_rerun
+    assert (execution.passed, execution.failed, execution.inconclusive) == (1, 1, 1)
+
+
+def test_the_address_comes_from_diteko_url_when_not_given(api, monkeypatch):
+    monkeypatch.setenv("DITEKO_URL", "http://diteko.internal:9999")
+    dk = Diteko(transport=httpx.MockTransport(api.handler))
+    assert str(dk._http._client.base_url) == "http://diteko.internal:9999/api/"
+    monkeypatch.delenv("DITEKO_URL")
+    assert str(Diteko(transport=httpx.MockTransport(api.handler))._http._client.base_url) == "http://localhost:8888/api/"

diteko-0.2.0/src/diteko/__init__.py

@@ -1,12 +0,0 @@
-"""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.2.0"