prettyplay 0.0.2__py3-none-any.whl

prettyplay/groups.py

@@ -0,0 +1,276 @@
+"""The authoring group block of the facade: one coherent mini-scenario with a shared goal."""
+
+from __future__ import annotations
+
+import math
+import time
+from collections.abc import Callable
+from types import TracebackType
+from typing import TYPE_CHECKING
+
+from .failures import PrettyplayError
+
+if TYPE_CHECKING:
+    from .driver import PageFacade
+    from .engine.groups import GroupStepOutcome
+    from .executor import StepExecutor
+    from .reporting import StepReporter
+
+
+def _validate_tries(tries: int | None) -> None:
+    """Validate the declared retry count of one step; ``None`` — the global polling settings.
+
+    Args:
+        tries: the declared total number of executions of the step's code,
+            the first execution included.
+
+    Raises:
+        PrettyplayError: the value is a bool, not an integer or below one —
+            the loud failure names the parameter, the received value and the
+            allowed form; a bad value never reaches the executor.
+    """
+    if tries is None:
+        return
+
+    if isinstance(tries, bool) or not isinstance(tries, int) or tries < 1:
+        raise PrettyplayError(
+            f"invalid tries {tries!r} — a positive integer, keyword-only "
+            "(the total number of executions of the step's code, the first execution included)"
+        )
+
+
+def _validate_delay(delay: float | None) -> None:
+    """Validate the declared quiet pause of one step or group; ``None`` — no pause.
+
+    Args:
+        delay: the declared pause in seconds — non-negative, fractional
+            allowed, bools never coerced.
+
+    Raises:
+        PrettyplayError: the value is a bool, not a number, not finite or
+            negative — the loud failure names the parameter, the received
+            value and the allowed form.
+    """
+    if delay is None:
+        return
+
+    if isinstance(delay, bool) or not isinstance(delay, (int, float)) or not math.isfinite(delay) or delay < 0:
+        raise PrettyplayError(f"invalid delay {delay!r} — a non-negative number of seconds, keyword-only")
+
+
+def _validate_vars(vars: dict[str, str] | None) -> None:
+    """Validate the call-local string inputs of one step; ``None`` — no inputs.
+
+    Args:
+        vars: the declared input mapping of the step — every value must be
+            a string, bools never coerced; the names reach the template's
+            ``vars`` namespace at render time.
+
+    Raises:
+        PrettyplayError: the value is not a mapping or some value is not a
+            string — the loud failure names the parameter, the received
+            value and the allowed form.
+    """
+    if vars is None:
+        return
+
+    if not isinstance(vars, dict):
+        raise PrettyplayError(f"invalid vars {vars!r} — a mapping of input names to string values, keyword-only")
+
+    for value in vars.values():
+        if not isinstance(value, str):  # a bool is never a string — no coercion
+            raise PrettyplayError(f"invalid vars value {value!r} — every value must be a string, keyword-only")
+
+
+class StepGroup:
+    """The authoring group object yielded by :meth:`PrettyPlay.group`: one coherent mini-scenario with a shared goal.
+
+    Attributes:
+        _speed: the group pace, 0-100; ``None`` — no between-step pauses;
+            the pace pause is a plain library wait, never ``slow_mo``.
+        _delay: the quiet pause before the group's first step, seconds;
+            ``None`` — no entry pause.
+        _executor: the step cycle executor of the owning test — every step
+            delegates to it with this group as the context.
+        _reporter: the visibility point of the owning test — the group
+            lifecycle events dispatch through it.
+        _traces: the verbatim trace records of the group's steps, appended
+            by the executor once per executed group step.
+        _delegated: the internal first-step marker — set immediately before
+            a step delegates to the executor, never read from the traces: a
+            first step that dies without a trace record must not re-arm the
+            entry pause for a later step of the same group.
+        _open_page: the owning test's lazy page opener, bound by
+            :meth:`PrettyPlay.group`; the declared constructor stays
+            five-parameter, the group is only ever constructed there.
+    """
+
+    def __init__(
+        self,
+        prompt: str,
+        speed: int | None,
+        delay: float | None,
+        executor: StepExecutor,
+        reporter: StepReporter,
+    ) -> None:
+        """Keep the group framing, the pace settings and the owning executor and reporter.
+
+        Args:
+            prompt: the group prompt, verbatim — reaches generation and
+                diagnosis requests and the lifecycle events.
+            speed: the group pace, 0-100; ``None`` — no between-step pauses.
+            delay: the quiet pause before the group's first step, seconds;
+                ``None`` — no pause.
+            executor: the step cycle executor of the owning test.
+            reporter: the visibility point of the owning test — the group
+                lifecycle events dispatch through it.
+        """
+        self._prompt = prompt
+        self._speed = speed
+        self._delay = delay
+        self._executor = executor
+        self._reporter = reporter
+        self._traces: list[GroupStepOutcome] = []
+        self._delegated = False
+        self._open_page: Callable[[], PageFacade] | None = None
+
+    @property
+    def prompt(self) -> str:
+        """The group prompt, verbatim."""
+        return self._prompt
+
+    @property
+    def traces(self) -> list[GroupStepOutcome]:
+        """The verbatim trace records of the group's steps, in execution order — never rewritten."""
+        return self._traces
+
+    def __enter__(self) -> StepGroup:
+        """Enter the group block: the on_group_started event with the group prompt verbatim.
+
+        Returns:
+            This group object. The entry pause is applied lazily immediately
+            before the group's first executed step — a zero-step group is a
+            quiet no-op: the lifecycle events and nothing else.
+        """
+        self._reporter.emit("on_group_started", {"group_prompt": self._prompt})
+
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        """Leave the group block: the outcome event, then the closing event; never suppresses.
+
+        Args:
+            exc_type: the type of the block exception, if any.
+            exc_value: the block exception, if any.
+            traceback: the traceback of the block exception, if any.
+
+        Returns:
+            Nothing — a falsy return keeps the exception propagating.
+            ``on_group_failed`` fires when the block exits through an
+            exception, ``on_group_passed`` when it completes without one —
+            a healed step counts as success; ``on_group_finished`` closes
+            exactly once.
+        """
+        outcome_event = "on_group_failed" if exc_type is not None else "on_group_passed"
+
+        self._reporter.emit(outcome_event, {"group_prompt": self._prompt})
+        self._reporter.emit("on_group_finished", {"group_prompt": self._prompt})
+
+    def step(
+        self,
+        text: str,
+        *,
+        tries: int | None = None,
+        delay: float | None = None,
+        vars: dict[str, str] | None = None,
+    ) -> None:
+        """Execute the action step ``text`` inside the group.
+
+        Args:
+            text: the sentence of the action as written by the engineer.
+            tries: keyword-only — the total number of executions of the
+                step's code, the first execution included; ``None`` — the
+                time-bounded settle mode of the polling settings.
+            delay: keyword-only — the quiet pre-step pause in seconds;
+                ``None`` — no pause.
+            vars: keyword-only — the call-local string inputs of the step;
+                every value must be a string. ``None`` — no inputs; a
+                separate namespace from memory — ``{{ vars.name }}`` reads
+                these values at render time.
+
+        Raises:
+            PrettyplayError: ``tries``, ``delay`` or ``vars`` is invalid —
+                the loud failure names the parameter, the received value
+                and the allowed form; the executor is never reached.
+        """
+        self._delegate(text, "action", tries, delay, vars)
+
+    def expect(
+        self,
+        text: str,
+        *,
+        tries: int | None = None,
+        delay: float | None = None,
+        vars: dict[str, str] | None = None,
+    ) -> None:
+        """Execute the assertion step ``text`` inside the group — the same delegation, assertion kind.
+
+        Args:
+            text: the sentence of the assertion as written by the engineer.
+            tries: keyword-only — the total number of executions of the
+                step's code, the first execution included; ``None`` — the
+                time-bounded settle mode of the polling settings.
+            delay: keyword-only — the quiet pre-step pause in seconds;
+                ``None`` — no pause.
+            vars: keyword-only — the call-local string inputs of the step;
+                every value must be a string. ``None`` — no inputs; a
+                separate namespace from memory — ``{{ vars.name }}`` reads
+                these values at render time.
+
+        Raises:
+            PrettyplayError: ``tries``, ``delay`` or ``vars`` is invalid —
+                the loud failure names the parameter, the received value
+                and the allowed form; the executor is never reached.
+        """
+        self._delegate(text, "assertion", tries, delay, vars)
+
+    def _delegate(
+        self,
+        text: str,
+        step_type: str,
+        tries: int | None,
+        delay: float | None,
+        vars: dict[str, str] | None,
+    ) -> None:
+        """Validate, pause and delegate one group step to the executor.
+
+        Args:
+            text: the raw sentence of the step, verbatim.
+            step_type: action or assertion.
+            tries: the declared retry count of this execution; ``None`` —
+                the global polling settings govern the step.
+            delay: the declared start pause of this execution; ``None`` —
+                no pause.
+            vars: the validated call-local string inputs of this
+                execution; ``None`` — no inputs.
+
+        Raises:
+            PrettyplayError: ``tries``, ``delay`` or ``vars`` is invalid.
+        """
+        _validate_tries(tries)
+        _validate_delay(delay)
+        _validate_vars(vars)
+
+        if not self._delegated:
+            if self._delay is not None:
+                time.sleep(self._delay)  # the lazy entry pause — quiet, library-level
+        elif self._speed is not None:
+            time.sleep(int((100 - self._speed) * 30) / 1000)  # the between-step pace — never slow_mo
+
+        self._delegated = True
+        self._executor.execute(text, step_type, self._open_page(), group=self, tries=tries, delay=delay, vars=vars)

prettyplay/llm/.usages/classification.md

@@ -0,0 +1,31 @@
+# Failure classification
+
+Domain: classifying a failed cached step before healing. Audience: engineers reasoning about healing decisions.
+
+## Categories
+
+| Category | Meaning | Consequence |
+|---|---|---|
+| rot | the UI changed: selectors, texts, structure | the step is regenerated from the current page and retried |
+| product_defect | the expectation legitimately failed | the test fails loudly — never healed green |
+| fixable | the step code is at fault (ambiguous or wrong locator/strategy); the intent is satisfiable | the step is regenerated for the same intent, the request carrying the classification recommendation |
+| incurable | regeneration cannot help: budget exhausted, text no longer matches reality, ambiguity | the incurable failure carries step, reason, recommendation |
+
+An unrecognized label of the model answer parses to `incurable` — the protective fallback: an unknown verdict never grants a regeneration.
+
+## Call
+
+```python
+classification = provider.classify_step_failure(
+    prompt=system_prompt,  # the system prompt text comes from the calling engine
+    user_instructions="",  # the classification instructions from the classification_prompt setting; empty — no block
+    step_text="click the «Sign in» button",
+    code=step_code,
+    error="element not found: button «Sign in»",
+    snapshot=snapshot_text,
+    screenshot=None,
+)
+print(classification.category, classification.explanation, classification.recommendation)
+```
+
+A non-empty `user_instructions` renders as a separate USER INSTRUCTIONS block in the request — the final block of the user content, after all classification inputs. It comes from the classification_prompt setting of the project; generation requests never see it, and classification requests never see the generation instructions.

prettyplay/llm/.usages/providers.md

@@ -0,0 +1,127 @@
+# Providers
+
+Domain: LLM provider selection and parity. Audience: integrators choosing a provider and setting models.
+
+## Select a provider
+
+```python
+from prettyplay.config import Config
+from prettyplay.llm import create_provider
+
+config = Config(provider="anthropic", model="claude-sonnet-4-5")
+provider = create_provider(config)
+```
+
+The provider is a project setting: openai or anthropic; env override PRETTYPLAY_PROVIDER. API keys come only from environment variables: OPENAI_API_KEY for openai, ANTHROPIC_API_KEY for anthropic.
+
+## Models
+
+| Setting | Purpose | Fallback |
+|---|---|---|
+| model | the default model for all four operations | — |
+| generation_model | code generation only | model |
+| classification_model | failure classification, group diagnosis and the compliance gate | model |
+
+The instruction compliance gate runs on the effective classification model (classification_model
+or model). Set classification_model to a different model when the verdict should come from
+a model other than the one that wrote the candidate; the defaults can select the same model.
+
+base_url overrides the provider endpoint when set.
+
+## Parity
+
+Both providers expose the same four operations — generate_step_code, classify_step_failure, classify_group_failure and check_instruction_compliance — with identical inputs, identical output shapes and the identical failure taxonomy: a provider transport failure resends the identical request inside one logical attempt (bounded transport retries) and raises LLMUnavailableError only on exhaustion, a permanent rejection or an over-cap Retry-After; cached step code never depends on the provider. One logical attempt per engine attempt; attempt budgets belong to the calling engine and are never consumed by transport retries.
+
+The classification operation is named `classify_step_failure` — the former `classify_failure`, a nominal rename.
+
+User instructions parity: each operation carries its own instructions — generation requests render the generation_prompt setting, classification requests render the classification_prompt setting — as a verbatim USER INSTRUCTIONS block with identical placement semantics in both providers. A parity requirement, not a capability difference.
+
+Scenario-context parity: the previous steps of a generation request arrive as typed records — each carrying the raw sentence, prepared instruction and permanent group membership — and render their instruction fields as the PREVIOUS STEPS block with the group entries marked; the group prompt of the current step renders as the GROUP PROMPT block before PREVIOUS STEPS. A parity requirement, not a capability difference.
+
+Step-type parity: every generation request and every compliance verdict request renders the STEP TYPE line — action or assertion — immediately before the STEP line, identically in both providers. A parity requirement, not a capability difference.
+
+Attempt-history parity: a generation request may carry the attempt history of the step — attempt_history, a list of complete multi-line records composed by the calling engine (the attempt outcome, the URL before -> after line, the complete candidate code, the complete error; the original cached code anchors the list as record 0 when it exists). Non-empty — rendered as the HISTORY block after the USER INSTRUCTIONS block, every record verbatim, never collapsed, never size-limited; the block replaces the former CODE/ERROR request pair and the former steering-only history. The request tail order is fixed: HISTORY, RECOMMENDATION (the classification diagnosis), USER GUIDANCE (the engineer message of the interactive steering). Both providers render every non-empty block identically at the same position. A parity requirement, not a capability difference.
+
+Page-URL parity: a generation request with a non-empty page URL renders it as its own PAGE URL line immediately after the PAGE SNAPSHOT block — identically in both providers. The URL reaches every generation and regeneration request of the engine and the guided requests of the steering. A parity requirement, not a capability difference.
+
+Cheat-sheet parity: every generation request renders the CHEAT SHEET block after the scenario inputs and
+immediately before the USER INSTRUCTIONS block — the compact standard Playwright sync API reference supplied by the
+calling engine; guidance, not an allowlist. Both providers render it identically at the same position.
+
+Prepared-instruction parity: every generation request renders the prepared instruction — the plain-text sentence with actual values produced by rendering — as the STEP block; the raw template sentence never appears. Scenario records render their instruction field; the model never sees raw Jinja. A parity requirement, not a capability difference.
+
+Input-bindings and result-declarations parity: a non-empty inputs mapping renders as the INPUTS block immediately after the STEP line (one name = value line per binding); a non-empty declarations list renders as the RESULTS block immediately after INPUTS stating the result contract — the code returns a dictionary of exactly the declared names to non-blank observed page strings; empty inputs — no INPUTS block, empty declarations — no RESULTS block and the success-without-result form. Both providers render the blocks identically at the same positions. A parity requirement, not a capability difference.
+
+Compliance parity: the gate request uses the same prepared instruction, INPUTS and RESULTS representation in both providers. The reviewer sees the exact result contract next to the STEP line before ATTEMPT HISTORY and CODE; it never sees the raw template sentence.
+
+Classification parity: ordinary classification renders its `step_text` input as the prepared instruction in the STEP block, identically in both providers. Group diagnosis renders prior scenario and group trace instruction fields, plus the prepared failed STEP. Raw template sentences stay local to cache addressing and re-rendering.
+
+## Transport retries
+
+Transient provider outages no longer kill a logical attempt: every SDK call of all four
+operations passes through the shared bounded retry mechanism inside the port.
+
+- Retryable: connection failures, timeouts, HTTP 408/429 and any 5xx — the identical request is
+  resent after a computed pause (base 1, 2, 4, 8, 10, 10… s + 0–25% jitter, cap 10 s; a valid
+  Retry-After ≤ 10 s lifts the pause to the asked wait)
+- Permanent — authentication, authorization, invalid request, an explicitly exhausted quota —
+  fails immediately; an explicit permanent cause wins over a retryable status
+- Retry-After above 10 s terminates with an actionable LLMUnavailableError — never an early
+  resend, never a cap-breaking wait
+- The send budget per logical attempt: llm_request_attempts (default 3, initial send included,
+  1 disables retries); SDK built-in retries are off (max_retries=0) — the budget is also the
+  maximum number of physical sends
+- Each retry logs one WARNING (provider, operation, attempt, category, delay) to the logger
+  prettyplay — no secrets, no payloads; KeyboardInterrupt during a wait stops the retrying
+- Generation, healing and group budgets are untouched: one logical LLM attempt per budget
+  attempt, with or without transport retries
+
+## The compliance operation
+
+check_instruction_compliance is the verdict request of the two-dimension gate — instruction
+compliance and step adequacy judged in one request: the engine calls it once per successfully
+executed candidate before caching — never for replayed cached code, never when generation_approve
+is off or generation_prompt is empty (zero calls).
+
+The request carries the gate system prompt and INSTRUCTIONS, STEP (with its STEP TYPE line),
+optional INPUTS and RESULTS, ATTEMPT HISTORY and CODE blocks; the answer is a JSON list of findings:
+
+[{"instruction": "...", "priority": "high", "explanation": "...", "dimension": "instruction"}]
+
+- the dimension is instruction or adequacy: instruction findings quote the violated project
+  instruction; adequacy findings quote the fragment of the step sentence the code fails to
+  accomplish, or — for behavior exceeding the step — the code line performing it — judged
+  from the step type and the attempt history
+- the priority is high, medium or low; only high blocks the candidate, in either dimension —
+  the calling engine owns that decision
+- the model behind the call is the effective classification model (classification_model or model)
+- a JSON syntax glitch of the answer is salvaged once (the json-repair library) before the
+  strict validation — a model dropping a quote, a comma or a bracket does not fail the run; an
+  answer that still is not the required shape — including an old-shaped finding without a
+  dimension, or an emptiness reached only through the salvage — raises
+  ComplianceVerdictError and a provider failure raises LLMUnavailableError — both hard: the
+  candidate is not cached unchecked
+
+## The group diagnosis operation
+
+The fourth port operation `classify_group_failure` — one logical request per diagnosis, with
+bounded resends of the identical SDK request inside it, through the
+effective classification model, both providers in full parity:
+
+- inputs: the group prompt (verbatim), prior scenario instructions with group membership, the
+  group step traces (prepared instruction, outcome, URL transition — one per step), the failed
+  step's prepared instruction, its rendered attempt history, the page snapshot and
+  the optional screenshot; the classification instructions of the project reach it exactly as a
+  classification request
+- the answer parses strictly through `parse_group_failure_classification`: JSON with the four
+  fields, one json-repair salvage of a syntax glitch, the closed label set
+  recoverable | product_defect | incurable
+- a garbage or incomplete answer degrades conservatively to incurable with the raw answer logged —
+  never a granted regeneration
+- provider unavailability raises LLMUnavailableError; one logical request per diagnosis, with
+  bounded resends of the identical SDK request inside it, budgets belong to
+  the calling engine
+
+## Answer shape
+
+generate_step_code returns step code of the fixed form. Models often answer with a fenced python block (```python … ```); the provider unwraps the first fenced block before returning, so the engine receives clean code either way — an answer with no closed fence is returned verbatim and, if unparsable, keeps failing downstream in execution.

prettyplay/llm/.usages/transport.md

@@ -0,0 +1,81 @@
+# Transport helpers
+
+Domain: using the LLM cell's transport facade. Audience: provider adapter authors and
+engineers diagnosing SDK failures. Built-in providers already apply this policy; configure
+them with `Config(llm_request_attempts=3)` rather than wrapping a provider operation again.
+
+## Inspect a failure without sending a request
+
+```python
+from prettyplay.llm import (
+    TransportFailureClassification,
+    classify_anthropic_failure,
+    classify_openai_failure,
+    compute_transport_pause,
+)
+
+failure: TransportFailureClassification = classify_openai_failure(ValueError("unknown failure"))
+assert failure.category == "invalid_request"
+assert failure.retryable is False
+assert classify_anthropic_failure(ValueError("unknown failure")).retryable is False
+
+# When planning a retry after the first transient failure:
+pause = compute_transport_pause(failed_attempt=1, retry_after=5.0)
+assert pause == 5.0
+```
+
+Pass the original SDK exception to the corresponding classifier. The returned verdict exposes
+`category`, `retry_after` and the computed `retryable` property. Quota evidence can reside in
+the SDK exception attributes or its dictionary response body, including the nested error
+object; older SDKs need not provide parsed attributes. Unknown failures are permanent.
+
+`compute_transport_pause` draws random jitter but does not sleep. Pass a positive, one-based
+failed attempt number. A Retry-After above 10 seconds is a terminal condition for the retry
+loop; do not call the pause helper to turn that value into a shorter wait.
+
+## Wrap one SDK send
+
+```python
+import os
+
+from openai import OpenAI
+
+from prettyplay.config import Config
+from prettyplay.failures import LLMUnavailableError
+from prettyplay.llm import classify_openai_failure, send_with_retries
+
+config = Config(model="gpt-5", llm_request_attempts=3)
+client = OpenAI(api_key=os.environ["OPENAI_API_KEY"], max_retries=0)
+request = {
+    "model": config.effective_generation_model,
+    "messages": [{"role": "user", "content": "Return a short greeting."}],
+}
+
+try:
+    response = send_with_retries(
+        provider="openai",
+        operation="generation",
+        attempts=config.llm_request_attempts,
+        classify=classify_openai_failure,
+        send=lambda: client.chat.completions.create(**request),
+    )
+except LLMUnavailableError as error:
+    # The original SDK failure is available through error.__cause__.
+    raise
+else:
+    # Validate successful response content after the transport loop.
+    text = response.choices[0].message.content
+finally:
+    client.close()
+```
+
+The closure performs exactly one send and reuses the same request. Supply a positive total
+send budget; `1` disables retries. For Anthropic, use an `Anthropic(max_retries=0, ...)`
+client, `classify_anthropic_failure`, and a closure calling `client.messages.create`.
+The adapter supplies the provider's usual request parameters, including Anthropic's
+required `max_tokens`.
+
+The helper sleeps synchronously between transient failures and logs one WARNING per retry.
+Permanent rejection, excessive Retry-After and exhaustion raise `LLMUnavailableError` with
+the original cause. `KeyboardInterrupt` propagates. Keep engine budget accounting and
+successful-response validation outside the closure.

prettyplay/llm/__init__.py

@@ -0,0 +1,38 @@
+"""Facade of the prettyplay.llm cell: the LLM port and its implementations."""
+
+from ._request import (
+    TransportFailureClassification,
+    classify_anthropic_failure,
+    classify_openai_failure,
+    compute_transport_pause,
+    send_with_retries,
+)
+from .anthropic_provider import AnthropicProvider
+from .models import (
+    ComplianceFinding,
+    FailureClassification,
+    GroupFailureClassification,
+    ScenarioStep,
+    parse_compliance_verdict,
+    parse_group_failure_classification,
+)
+from .openai_provider import OpenAIProvider
+from .provider import LLMProvider, create_provider
+
+__all__ = [
+    "AnthropicProvider",
+    "ComplianceFinding",
+    "FailureClassification",
+    "GroupFailureClassification",
+    "LLMProvider",
+    "OpenAIProvider",
+    "ScenarioStep",
+    "TransportFailureClassification",
+    "classify_anthropic_failure",
+    "classify_openai_failure",
+    "compute_transport_pause",
+    "create_provider",
+    "parse_compliance_verdict",
+    "parse_group_failure_classification",
+    "send_with_retries",
+]