prettyplay 0.0.2__py3-none-any.whl

prettyplay/engine/polling/.usages/settle.md

@@ -0,0 +1,55 @@
+# Settle window
+
+Domain: how transient page-state failures are absorbed before any costly move. Audience: engineers tuning polling_timeout and reasoning about retry behavior.
+
+## The window
+
+One settle window per step execution: the step executor creates it from the polling settings and threads it into
+every execution of the step's code — cached code and generation candidates alike, replay-strict included.
+
+```python
+from prettyplay.engine.polling import SettleWindow, settle
+
+window = SettleWindow(timeout=config.polling_timeout, delay=config.polling_delay)
+settle(execute=run_step_code, code=cached_step.code, page=page, window=window)
+```
+
+`run_step_code` comes from `prettyplay.engine` — the execution routine the caller threads in.
+
+- The window starts at the first execution of the step code — never at the first failure; the step code's own
+  auto-waits count inside it, and the first execution may consume the whole window: no repetitions follow
+- The window gates repetitions, never kills a running attempt: the remaining-time check happens only before a repeat
+- A failure re-executes the same code after `polling_delay` when its kind is pollable and time remains — until
+  success or window end; success continues the step normally
+- Everything else propagates as-is: locator ambiguity, Python-level errors, non-pollable and unknown kinds. On
+  cached code such a failure goes straight to classification; on a generation candidate it feeds the next
+  regeneration request with the fresh error
+
+## Visibility
+
+Each repetition writes a `settle_retry` record to the logger prettyplay at INFO — the attempt counter and the failure
+text. Re-executions emit no hook events: hook events fire per step or per LLM attempt, never per execution retry.
+
+## Budgets
+
+Re-executions consume no generation or healing budgets and make no LLM requests — polling is cheaper than one
+regeneration attempt.
+
+## Rules
+
+- `polling_timeout` None (default) and 0 keep polling off — the settle call degenerates to a single execution
+- `polling_delay` 0 re-executes without a pause
+- The settle window never re-arms: one window per step execution, shared by every execution inside it
+
+## Count-bounded re-execution (tries)
+
+A step declared with a retry count replaces the time bound for that step's loop with a count
+bound: `SettleWindow(timeout=..., delay=..., tries=3)` — the code unit executes at most 3 times in
+total (the first execution included; 1 — no re-execution). The pollable filter and the `delay`
+pause keep applying between executions; retries appear as `settle_retry` records; exhaustion
+propagates the failure to the ordinary path. Each `settle` call counts from zero — the cached code
+and every generated candidate each get their own full count. No LLM budget is consumed.
+
+## Result carriage
+
+`settle` returns the result of the successful execution — `run_step_code` returns the step's dictionary for steps with capture declarations and None otherwise. The loop passes the successful result through untouched; validation and publication belong to the calling cycle. A repeated execution's success returns that re-execution's result.

prettyplay/engine/polling/__init__.py

@@ -0,0 +1,6 @@
+"""Facade of the prettyplay.engine.polling cell: the settle window and the re-execution loop."""
+
+from .settle import settle
+from .window import SettleWindow
+
+__all__ = ["SettleWindow", "settle"]

prettyplay/engine/polling/settle.py

@@ -0,0 +1,98 @@
+"""Execution of step code under the settle window: the re-execution loop of transient page-state failures."""
+
+import logging
+import time
+from collections.abc import Callable
+
+from ...driver import PageFacade, is_pollable_failure
+from .window import SettleWindow
+
+logger = logging.getLogger("prettyplay")
+
+
+def settle(
+    execute: Callable[[str, PageFacade], dict[str, str] | None],
+    code: str,
+    page: PageFacade,
+    window: SettleWindow,
+) -> dict[str, str] | None:
+    """Execute step code under the settle window and carry the successful execution's result back.
+
+    Args:
+        execute: the step-code execution routine passed by the caller — returns
+            the step's result (a dictionary of declared names to observed
+            strings, or None for a declaration-free step).
+        code: the step code text.
+        page: the page facade of the current test.
+        window: the settle window of the current step execution — a declared
+            ``tries`` count bounds the loop by executions (the counter is
+            local to this call), otherwise the time window applies; each
+            repetition logs ``settle_retry`` at INFO.
+
+    Returns:
+        The result returned by the successful execution — untouched: the loop
+        never inspects, validates or alters it; validation belongs to the
+        calling cycle.
+    """
+    window.start()
+
+    if window.count_bounded:
+        return _settle_by_count(execute, code, page, window)
+
+    attempt = 0
+
+    while True:
+        try:
+            return execute(code, page)
+
+        except Exception as failure:
+            attempt += 1
+
+            if window.enabled and is_pollable_failure(failure) and window.has_remaining():
+                logger.info("settle_retry", extra={"attempt": attempt, "error": str(failure)})
+                time.sleep(window.delay)
+
+                continue
+
+            raise
+
+
+def _settle_by_count(
+    execute: Callable[[str, PageFacade], dict[str, str] | None],
+    code: str,
+    page: PageFacade,
+    window: SettleWindow,
+) -> dict[str, str] | None:
+    """Execute step code up to the window's declared tries count and return the successful execution's result.
+
+    Args:
+        execute: the step-code execution routine passed by the caller — returns
+            the step's result (a dictionary of declared names to observed
+            strings, or None for a declaration-free step).
+        code: the step code text.
+        page: the page facade of the current test.
+        window: the count-bounded settle window — re-execute iff enabled,
+            pollable and under the declared count; exhaustion propagates
+            the failure as-is.
+
+    Returns:
+        The result returned by the successful execution — including the result
+        of a successful re-execution; the loop never touches it beyond the
+        pass-through.
+    """
+    executed = 0
+
+    while True:
+        try:
+            return execute(code, page)
+
+        except Exception as failure:
+            executed += 1
+
+            if window.enabled and is_pollable_failure(failure) and executed < window.tries:
+                logger.info("settle_retry", extra={"attempt": executed, "error": str(failure)})
+                time.sleep(window.delay)
+
+                continue
+
+            raise

prettyplay/engine/polling/window.py

@@ -0,0 +1,72 @@
+"""The settle window of one step execution: the re-execution horizon of step code."""
+
+import time
+
+
+class SettleWindow:
+    """The settle horizon of one step execution — pure bookkeeping: gates repetitions, never kills a running attempt.
+
+    Attributes:
+        timeout: the total window in seconds; ``None`` — polling disabled;
+            ``0`` — an explicit disable, equivalent to ``None``; positive —
+            the window.
+        delay: the pause between re-executions in seconds; ``0`` —
+            re-execute without a pause.
+        tries: the total number of executions of one code unit within its
+            re-execution loop, the first execution included (``1`` — no
+            re-execution); ``None`` — the time-bounded mode of today.
+    """
+
+    def __init__(self, timeout: float | None, delay: float, tries: int | None = None) -> None:
+        """Keep the settle horizon of one step execution.
+
+        Args:
+            timeout: the total window in seconds; ``None`` — polling
+                disabled; ``0`` — an explicit disable, equivalent to
+                ``None``.
+            delay: the pause between re-executions in seconds; ``0`` —
+                re-execute without a pause.
+            tries: the declared retry count; ``None`` — the time-bounded
+                mode; a positive integer — the count-bounded mode.
+        """
+        self.timeout = timeout
+        self.delay = delay
+        self.tries = tries
+        self._started_at: float | None = None
+
+    @property
+    def count_bounded(self) -> bool:
+        """Whether the window bounds this loop by execution count.
+
+        Returns:
+            True when a ``tries`` count is declared.
+        """
+        return self.tries is not None
+
+    @property
+    def enabled(self) -> bool:
+        """Whether polling is active: a positive timeout is set or the window is count-bounded.
+
+        Returns:
+            True when the window carries a positive timeout or a declared
+            ``tries`` count — a count-bounded window stays alive even with
+            the time window disabled.
+        """
+        return (self.timeout is not None and self.timeout > 0) or self.count_bounded
+
+    def start(self) -> None:
+        """Mark the window start at the first execution of the step code; idempotent."""
+        if self._started_at is None:
+            self._started_at = time.monotonic()
+
+    def has_remaining(self) -> bool:
+        """Whether the window still allows a repetition.
+
+        Returns:
+            True when time remains and the window is enabled and started.
+            Time-bounded mode alone — the count-bounded loop checks its own
+            counter; checked only before a repetition, never mid-attempt.
+        """
+        if not self.enabled or self._started_at is None or self.timeout is None:
+            return False
+        return (time.monotonic() - self._started_at) < self.timeout

prettyplay/engine/renderer/.usages/memory.md

@@ -0,0 +1,24 @@
+# Test memory
+
+Domain: the per-test memory of captured observations. Audience: library internals — the executor owning the memory and the engines publishing at acceptance.
+
+## Lifecycle
+
+```python
+from prettyplay.engine.renderer import StepMemory
+
+memory = StepMemory()  # empty at construction, one per test execution
+values = memory.snapshot()  # the render source — a stable copy
+memory.publish({"name": "Book"})  # atomic, after full acceptance only
+```
+
+- Rendering reads a snapshot: a step's own new captures stay invisible to its template; a same-step read observes the previous value or fails
+- All captures of one step publish together after full acceptance (including the compliance gate); a failed or rejected step publishes nothing
+- A successful recapture replaces the previous value; absent names keep theirs
+- Memory survives navigation and never crosses test boundaries — concurrent tests stay isolated
+
+## Who publishes
+
+- The executor — after a validated successful replay of cached code
+- The engines — at the candidate acceptance point (after the compliance gate)
+- The group recovery — per accepted row step; a later group failure never rolls back accepted publications

prettyplay/engine/renderer/.usages/rendering.md

@@ -0,0 +1,44 @@
+# Rendering step sentences
+
+Domain: preparing a step sentence into a plain-text instruction with capture declarations. Audience: library internals — the step executor and the recovery engine calling the render point.
+
+## Render a step
+
+```python
+from prettyplay.engine.renderer import StepMemory, render_step
+
+memory = StepMemory()
+memory.publish({"name": "Book"})  # a previously accepted observation
+
+prepared = render_step(
+    text="For the item named {{ name }}, read its tags into {% var tags %}",
+    step_type="action",
+    memory=memory,
+    vars=None,
+)
+prepared.instruction  # "For the item named Book, read its tags into " — plain text, actual values
+prepared.inputs  # {} — the call's vars
+prepared.declarations  # ["tags"] — reached capture tags only
+```
+
+- The render starts from a snapshot: later publications never change a taken render
+- `{{ name }}` reads memory; `{{ vars.expected }}` reads the call input — separate namespaces, neither overwrites the other
+- A reached `{% var name %}` renders to empty text and declares a result slot; an inactive branch declares nothing
+- Capture declarations are invalid for assertion steps (`expect`)
+
+## Authoring errors
+
+Raised as the loud actionable `PrettyplayError` before any browser execution:
+
+- a duplicate capture name within one render
+- the reserved capture name `vars` or a non-Jinja-identifier name
+- an unavailable ordinary reference — the message names it; author-written `| default(...)` and `is defined` behave as authored
+- a capture declaration in an assertion step
+
+## Literal Jinja in a sentence
+
+```python
+t.expect("The page contains {% raw %}{{ name }}{% endraw %}")
+```
+
+Use standard `raw` blocks to output literal Jinja syntax.

prettyplay/engine/renderer/.usages/validation.md

@@ -0,0 +1,20 @@
+# Validating step results
+
+Domain: deterministic acceptance of returned step results. Audience: library internals — the executor and the engines validating executions.
+
+## Validate an execution result
+
+```python
+from prettyplay.engine.renderer import PreparedStep, StepMemory, validate_step_result
+
+memory = StepMemory()
+prepared = PreparedStep(instruction="Read the item name", declarations=["name"])
+result = {"name": "Book"}  # returned by the executed step after reading the page
+captures = validate_step_result(prepared, result)
+memory.publish(captures)  # accepted cached replay; candidates must pass compliance first
+```
+
+- Exact declared keys: missing or unexpected names violate; string values only; blank (empty or whitespace-only) values violate
+- A declaration-free step accepts None and validates to empty captures — the success-without-result behavior
+- A violation raises AssertionError with a deterministic text — it enters the existing failed-check paths: classification and bounded corrective generation where non-strict execution permits, strict failure without generation
+- Publish only validated captures — never fabricated or repaired values

prettyplay/engine/renderer/__init__.py

@@ -0,0 +1,7 @@
+"""Facade of the prettyplay.engine.renderer cell: step-sentence preparation — rendering, memory, validation."""
+
+from .memory import StepMemory
+from .render import PreparedStep, render_step
+from .validation import validate_step_result
+
+__all__: list[str] = ["PreparedStep", "StepMemory", "render_step", "validate_step_result"]

prettyplay/engine/renderer/memory.py

@@ -0,0 +1,37 @@
+"""The per-test-execution memory of captured observations."""
+
+from __future__ import annotations
+
+
+class StepMemory:
+    """The names namespace of rendering — captured observations of one test execution.
+
+    Owned by the step executor of one test: rendering reads snapshots, publication
+    happens only at acceptance points. Constructs empty, survives navigation and
+    never crosses test boundaries.
+    """
+
+    def __init__(self) -> None:
+        """Construct an empty memory."""
+        self._values: dict[str, str] = {}
+
+    def snapshot(self) -> dict[str, str]:
+        """Return a stable copy of the current values — the render source.
+
+        Returns:
+            The copy of the current values; later publications never mutate a
+            taken snapshot.
+        """
+        return dict(self._values)
+
+    def publish(self, captures: dict[str, str]) -> None:
+        """Publish validated captures atomically.
+
+        Replaces the value of every present name — a successful recapture
+        replaces the previous value; names absent from ``captures`` keep theirs.
+
+        Args:
+            captures: The validated dictionary of one accepted step execution.
+        """
+        for name, value in captures.items():
+            self._values[name] = value

prettyplay/engine/renderer/render.py

@@ -0,0 +1,184 @@
+"""The render point: step templates become prepared instructions with capture declarations."""
+
+import re
+from typing import ClassVar
+
+from jinja2 import Environment, StrictUndefined, UndefinedError, nodes
+from jinja2.exceptions import TemplateSyntaxError
+from jinja2.ext import Extension
+from jinja2.parser import Parser
+from pydantic import BaseModel, ConfigDict
+
+from ...failures import PrettyplayError
+from .memory import StepMemory
+
+#: The Jinja error text of an attribute miss on the inputs namespace — ``'dict object' has
+#: no attribute 'x'``. The vars namespace is the only plain-dict root of the render context,
+#: so a miss names the qualified ``vars.x`` form.
+_ATTRIBUTE_MISS = re.compile(r"^'dict object' has no attribute '([^']+)'$")
+
+
+class PreparedStep(BaseModel):
+    """The render product of one step sentence — what the agent cycle works with after preparation.
+
+    Args:
+        instruction: The prepared plain-text instruction with actual values embedded.
+        inputs: The call-local input bindings of this step; empty — none.
+        declarations: The reached capture-tag names, in execution order; empty — no memory writes.
+    """
+
+    model_config = ConfigDict(kw_only=True, frozen=True)
+
+    instruction: str = ""
+    inputs: dict[str, str] = {}
+    declarations: list[str] = []
+
+    @property
+    def has_declarations(self) -> bool:
+        """Report whether the step declared any result captures.
+
+        Returns:
+            Whether at least one capture tag was reached during rendering.
+        """
+        return bool(self.declarations)
+
+
+class VarExtension(Extension):
+    """The ``{% var name %}`` capture-declaration tag of step templates.
+
+    A reached tag records its name into the per-render declaration list of the
+    extension instance and renders to empty text — it declares a result slot,
+    it supplies no value. One instance lives in one environment, and one
+    environment serves one render, so the declaration list is per-render.
+    """
+
+    tags: ClassVar[set[str]] = {"var"}
+
+    def __init__(self, environment: Environment) -> None:
+        """Construct the extension with an empty per-render declaration list.
+
+        Args:
+            environment: The Jinja environment this extension is registered in.
+        """
+        super().__init__(environment)
+
+        self.declarations: list[str] = []
+
+    def parse(self, parser: Parser) -> nodes.Output:
+        """Parse one capture tag into an output node that records its name when reached.
+
+        Args:
+            parser: The active Jinja parser positioned at the ``var`` tag token.
+
+        Returns:
+            The output node rendering to empty text and recording the capture name.
+
+        Raises:
+            PrettyplayError: The token after ``var`` is not a single Jinja identifier.
+        """
+        tag_token = parser.stream.expect("name:var")
+        name_token = next(parser.stream)
+
+        if name_token.type != "name":
+            raise PrettyplayError(
+                f"the var capture tag expects a single Jinja identifier name, got {name_token.value!r}"
+            )
+
+        call = self.call_method("_record", [nodes.Const(name_token.value)], lineno=tag_token.lineno)
+
+        return nodes.Output([call]).set_lineno(tag_token.lineno)  # type: ignore[return-value]
+
+    def _record(self, name: str) -> str:
+        """Record one reached capture name and render to empty text.
+
+        Args:
+            name: The capture name reached during rendering.
+
+        Returns:
+            The empty text the tag renders to.
+
+        Raises:
+            PrettyplayError: The name is the reserved ``vars`` namespace or is already recorded.
+        """
+        if name == "vars":
+            raise PrettyplayError("the capture name 'vars' is reserved for the call inputs namespace")
+
+        if name in self.declarations:
+            raise PrettyplayError(f"the capture name {name!r} is declared twice in one step")
+
+        self.declarations.append(name)
+
+        return ""
+
+
+def _unavailable_name(error: UndefinedError, inputs: dict[str, str]) -> str:
+    """Name the unavailable value of one render failure.
+
+    Args:
+        error: The undefined-value error raised by the render.
+        inputs: The call-local input bindings of the render.
+
+    Returns:
+        The unavailable name — the qualified ``vars.x`` form for a miss on the
+        inputs namespace, the Jinja diagnostic text otherwise.
+    """
+    match = _ATTRIBUTE_MISS.match(str(error))
+
+    if match and match.group(1) not in inputs:
+        return f"'vars.{match.group(1)}' is undefined"
+
+    return str(error)
+
+
+def render_step(text: str, step_type: str, memory: StepMemory, vars: dict[str, str] | None) -> PreparedStep:
+    """Render one step sentence from a snapshot of memory and call inputs into a prepared step.
+
+    Compiles the sentence through a fresh Jinja environment — plain text, strict
+    undefined values, the ``{% var %}`` capture extension — and renders it with
+    the memory snapshot and the inputs namespace. All authoring errors raise
+    ``PrettyplayError`` naming the problem and the offending name, before any
+    browser execution.
+
+    Args:
+        text: The raw step sentence as written by the engineer — the template source.
+        step_type: The step kind — action or assertion.
+        memory: The test memory; the render reads its snapshot and never mutates it.
+        vars: The call-local string inputs; None — none.
+
+    Returns:
+        The render product of the sentence.
+
+    Raises:
+        PrettyplayError: The template is malformed, a capture name is invalid or
+            duplicated, a value is unavailable, or an assertion declares captures.
+    """
+    snapshot = memory.snapshot()
+    inputs = {} if vars is None else dict(vars)
+
+    environment = Environment(autoescape=False, undefined=StrictUndefined, extensions=[VarExtension])
+    extension = next(ext for ext in environment.extensions.values() if isinstance(ext, VarExtension))
+
+    try:
+        template = environment.from_string(text)
+    except TemplateSyntaxError as error:
+        raise PrettyplayError(f"the step template is malformed: {error.message} (line {error.lineno})") from error
+
+    try:
+        instruction = template.render(snapshot, vars=inputs)
+    except UndefinedError as error:
+        name = _unavailable_name(error, inputs)
+
+        raise PrettyplayError(f"the step template references an unavailable name: {name}") from error
+    except PrettyplayError:
+        raise
+    except Exception as error:
+        raise PrettyplayError(f"the step template {text!r} failed to evaluate: {error}") from error
+
+    declarations = list(extension.declarations)
+
+    if step_type == "assertion" and declarations:
+        names = ", ".join(declarations)
+
+        raise PrettyplayError(f"a step expectation cannot declare result captures: {names}")
+
+    return PreparedStep(instruction=instruction, inputs=inputs, declarations=declarations)

prettyplay/engine/renderer/validation.py

@@ -0,0 +1,76 @@
+"""The deterministic acceptance gate for returned step results."""
+
+from .render import PreparedStep
+
+
+def _validate_values(result: dict[object, object]) -> None:
+    """Validate every captured value of an accepted result dictionary.
+
+    Args:
+        result: The result dictionary whose keys already match the declarations.
+
+    Raises:
+        AssertionError: A value is not a string or is blank.
+    """
+    for name, value in result.items():
+        if not isinstance(value, str):
+            raise AssertionError(f"the result value of {name!r} must be a string, got {type(value).__name__}")
+
+        if value.strip() == "":
+            raise AssertionError(f"the result value of {name!r} is blank")
+
+
+def validate_step_result(prepared: PreparedStep, result: object) -> dict[str, str]:
+    """Deterministically validate the returned result of one step execution.
+
+    Compares the untrusted step function's return against the declaration set of
+    the render product: a declaration-free step accepts None, a declaring step
+    must return exactly the declared names as non-blank strings. A violation
+    raises ``AssertionError`` with the deterministic violation text — the
+    failed-check channel of the calling cycle. Never fabricates or repairs.
+
+    Args:
+        prepared: The render product of the executed step — the declaration set.
+        result: The untrusted step function's return — expected to be the
+            dictionary of declared names to observed strings, or None for a
+            declaration-free step.
+
+    Returns:
+        The validated captures, ready for publication; empty for a
+        declaration-free step.
+
+    Raises:
+        AssertionError: The result violates the declared contract — a wrong
+            type, a missing or unexpected name, or a non-string or blank value.
+    """
+    if not prepared.declarations:
+        if result is None:
+            return {}
+
+        raise AssertionError("unexpected result without declarations")
+
+    if result is None:
+        names = ", ".join(prepared.declarations)
+
+        raise AssertionError(f"missing result: the step declares {names}")
+
+    if not isinstance(result, dict):
+        raise AssertionError(f"result must be a dictionary, got {type(result).__name__}")
+
+    missing = sorted(set(prepared.declarations) - set(result), key=repr)
+    unexpected = sorted(set(result) - set(prepared.declarations), key=repr)
+
+    if missing or unexpected:
+        problems = []
+
+        if missing:
+            problems.append(f"missing {', '.join(repr(name) for name in missing)}")
+
+        if unexpected:
+            problems.append(f"unexpected {', '.join(repr(name) for name in unexpected)}")
+
+        raise AssertionError(f"result keys do not match the declared captures: {'; '.join(problems)}")
+
+    _validate_values(result)
+
+    return dict(result)