prettyplay 0.0.2__py3-none-any.whl

prettyplay/engine/groups/.usages/recovery.md

@@ -0,0 +1,71 @@
+# Group recovery
+
+Domain: the diagnosis-driven recovery of step groups. Audience: library internals and engineers
+reasoning about recovered group runs.
+
+## When recovery runs
+
+Every classification point of a group step on a non-strict run routes here instead of the per-step
+classification-and-heal: a failed check of a generation candidate, a failed cached replay and the
+generation-budget exhaustion. Inside a group there is no isolated per-step healing. Strict mode
+never runs recovery — the classification-only path stays.
+
+## The cycle
+
+```python
+from prettyplay.engine.renderer import PreparedStep
+
+healed = recovery.recover(
+    group_prompt="accept cookies, fill and submit the order form",
+    traces=group_traces,  # GroupStepOutcome per group step, execution order
+    prepared=PreparedStep(instruction="the status shows order confirmed"),  # the render product of the failed step
+    step_type="assertion",
+    previous_steps=scenario,  # the typed scenario records of the test, execution order
+    identity=identity,
+    attempt_history=history,
+    page=page,
+    window=window,
+    memory=memory,
+)
+```
+
+1. One group-level diagnosis request — the classification model and instructions, the group
+   prompt, the step traces with outcomes and URL transitions, the current page state, the failed
+   step's attempt history. Labels: `recoverable | product_defect | incurable`; a garbage answer
+   degrades to incurable with the raw answer logged.
+2. `product_defect` fails loudly; `incurable` fails terminally; a root named outside the group
+   ends in the honest terminal failure naming that step.
+3. `recoverable`: the row runs from the earliest affected group step through the failed step —
+   each step is
+   re-rendered against the current context (its template sentence, its recorded inputs, the current memory),
+   regenerates as its own unit (the diagnosis recommendation + the group framing ride the request), re-executes
+   immediately on the current page, validates its returned result, passes the two-dimension compliance gate,
+   publishes its captures to the test memory and writes back to the cache per step.
+4. A repeat failure re-enters a fresh diagnosis and a new cycle while cycles remain; every new
+   cycle grants each row step a fresh full healing counter; the number of cycles per group is
+   capped by `healing_attempts` — never infinite.
+
+## Reporting
+
+Diagnosis and regeneration requests use the provider's bounded transport retries. Resending
+an identical request consumes no additional group cycle or per-step healing attempt. A final
+`LLMUnavailableError` propagates out of recovery; it never opens another recovery cycle.
+
+The block itself reports through the four group lifecycle hook events — `on_group_started`,
+then `on_group_passed` (a recovered group reports passed) or `on_group_failed`, closed by
+`on_group_finished`. `on_healing_started` / `on_healed` fire per recovered step; the diagnosis
+itself and the row composition stay log-only records.
+
+## Memory and re-render
+
+- Row steps re-render through `render_step` — recovery never reuses a stale instruction: the current memory and
+  the step's recorded inputs produce the fresh one
+- Recovery keeps local copies of previous scenario records and group traces. After each accepted row step, its
+  newly prepared instruction replaces that occurrence in the local views used by later row requests and diagnoses;
+  the test's stored records and appended traces remain immutable
+- A failed row regeneration becomes the active failure for the next diagnosis: STEP and HISTORY describe that row
+  step and its latest attempt; a complete row still returns the healed code of the originally failed step
+- Every accepted row step publishes its captures immediately; a later failure in the row never rolls back accepted
+  values — steps left behind keep their last accepted observations
+- Traces carry the instruction (what the model saw and what the row matcher quotes) and the original `vars` of
+  each step's call

prettyplay/engine/groups/__init__.py

@@ -0,0 +1,7 @@
+"""Facade of the prettyplay.engine.groups cell: the diagnosis-driven recovery of step groups."""
+
+from .diagnosis import classify_group_failure
+from .outcome import GroupStepOutcome
+from .recovery import GroupRecovery
+
+__all__ = ["GroupRecovery", "GroupStepOutcome", "classify_group_failure"]

prettyplay/engine/groups/diagnosis.py

@@ -0,0 +1,128 @@
+"""The single group diagnosis request: the whole interaction in view, one verdict."""
+
+import logging
+
+from ...config import Config
+from ...driver import PageFacade
+from ...llm import GroupFailureClassification, LLMProvider, ScenarioStep
+from ..attempts import StepAttempt
+from .outcome import GroupStepOutcome
+
+logger = logging.getLogger("prettyplay")
+
+#: System prompt of every group diagnosis request; applied verbatim by the provider.
+#: Frozen mirror of ``.goga/usages/prompts/group_diagnosis.md`` (the section after the ``---``
+#: separator) — the single source of the prompt; the constant changes only together with the file.
+GROUP_DIAGNOSIS_PROMPT = """\
+You diagnose a failure of one step inside a group of steps that form one coherent interaction with
+a shared goal.
+
+Input you receive:
+- GROUP PROMPT: the shared goal of the group, verbatim
+- PREVIOUS STEPS: the prepared instructions of the prior scenario of the test, in execution order —
+  the group entries marked
+- GROUP STEPS: every step of the group in execution order — each with its recorded prepared
+  instruction, its outcome (passed or failed) and its URL before -> after transition
+- STEP: the failed step's prepared instruction
+- HISTORY: the verbatim record of every attempt of the failed step so far
+- PAGE SNAPSHOT: the accessibility snapshot of the current page
+- SCREENSHOT: an image of the page, when attached
+- USER INSTRUCTIONS: the project's binding classification guidance, when configured — follow it;
+  it never overrides the fixed answer format below
+
+Answer with exactly one JSON object of the form:
+{"category": "recoverable | product_defect | incurable",
+ "root_cause": "<one short sentence>",
+ "earliest_step": "<the verbatim sentence of the earliest affected step>",
+ "recommendation": "<one short sentence what should be regenerated or done>"}
+
+Category calibration:
+- recoverable — the failure stems from one or more earlier steps of the group (a step that did not
+  land what its sentence says) and regenerating the affected steps of the group can fix the run
+- product_defect — the application is genuinely broken; regenerating steps cannot and must not
+  turn this green
+- incurable — the root cannot be reached from inside the group (it lives in an earlier step of the
+  test outside the group), or regeneration cannot help
+
+Rules:
+- earliest_step must quote a visible instruction verbatim: a group step's instruction when the
+  category is recoverable; when the root lives outside the group, quote that outside step's
+  instruction from PREVIOUS STEPS verbatim and answer incurable; raw template sentences are not
+  request content
+- Output only the JSON object, no other text"""
+
+
+def classify_group_failure(  # noqa: PLR0913, PLR0917 — the parameter list is fixed by the recovery contract
+    config: Config,
+    provider: LLMProvider,
+    group_prompt: str,
+    traces: list[GroupStepOutcome],
+    previous_steps: list[ScenarioStep],
+    step_text: str,
+    step_type: str,  # noqa: ARG001 — the contract parameter; the kind rides the traces, not the port call
+    attempt_history: list[StepAttempt],
+    page: PageFacade,
+) -> GroupFailureClassification:
+    """Diagnose a failed group step with the whole interaction in view.
+
+    Args:
+        config: project settings; ``send_screenshots`` attaches the page
+            image and ``classification_prompt`` supplies the user
+            instructions of the request.
+        provider: the LLM port implementation diagnosing the failure.
+        group_prompt: the group prompt of the diagnosed group, verbatim.
+        traces: the group's step traces in execution order — every record
+            renders its recorded prepared instruction into the GROUP STEPS
+            block; the raw sentences stay local.
+        previous_steps: the typed scenario records of the test, in
+            execution order — the provider renders their prepared
+            instructions as the PREVIOUS STEPS block, the group entries
+            marked; the basis of the outside-group root diagnosis.
+        step_text: the prepared instruction of the failed step, verbatim —
+            never the raw template sentence.
+        step_type: the step kind: action or assertion.
+        attempt_history: the per-step attempt history of the failed step,
+            grown to the failure — every record rendered verbatim into the
+            HISTORY block.
+        page: the page facade of the current test.
+
+    Returns:
+        The diagnosis verdict — a garbage answer arrives as the
+        conservative incurable, never as a granted regeneration.
+
+    Raises:
+        LLMUnavailableError: the provider service failed after the bounded
+            transport retries; an explicit infrastructure failure — the
+            calling recovery decides.
+    """
+    snapshot = page.aria_snapshot()
+    screenshot = page.screenshot() if config.send_screenshots else None
+
+    verdict = provider.classify_group_failure(
+        prompt=GROUP_DIAGNOSIS_PROMPT,
+        user_instructions=config.classification_prompt,
+        group_prompt=group_prompt,
+        group_steps=[trace.render() for trace in traces],
+        previous_steps=previous_steps,
+        step_text=step_text,
+        attempt_history=[record.render() for record in attempt_history],
+        snapshot=snapshot,
+        screenshot=screenshot,
+    )
+
+    if verdict.degraded:
+        logger.warning(
+            "group_diagnosis_degraded",
+            extra={"group": group_prompt, "answer": verdict.root_cause},
+        )
+
+    logger.info(
+        "group_diagnosed",
+        extra={
+            "group": group_prompt,
+            "category": verdict.category,
+            "earliest": verdict.earliest_step,
+        },
+    )
+
+    return verdict

prettyplay/engine/groups/outcome.py

@@ -0,0 +1,55 @@
+"""The verbatim trace record of a group step: the unit the GROUP STEPS block renders."""
+
+from pydantic import BaseModel, ConfigDict
+
+from ...cache import StepIdentity
+
+
+class GroupStepOutcome(BaseModel):
+    """One verbatim trace record of a group step's execution — never rewritten or truncated.
+
+    Attributes:
+        sentence: the raw sentence of the group step (the template source),
+            verbatim — the re-render source of the row mechanics, never
+            rendered into requests.
+        instruction: the prepared instruction recorded at the step's
+            execution — what the GROUP STEPS block renders and the matcher
+            matches against; equals ``sentence`` for a non-template step.
+        step_type: the step kind: action or assertion.
+        tries: the declared retry count of the step; None — the step is
+            governed by the global polling settings.
+        delay: the declared start pause of the step in seconds; None — no
+            pause.
+        vars: the call-local input bindings of the step's original call —
+            the re-render input of the row mechanics.
+        outcome: the execution outcome: passed or failed.
+        url_before: the page URL read immediately before the step's
+            execution.
+        url_after: the page URL read immediately after the step's execution.
+        identity: the cache address of the step — recorded by the executor
+            when the trace is appended; the addressing metadata of the row
+            mechanics, never rendered into the GROUP STEPS block.
+    """
+
+    model_config = ConfigDict(kw_only=True, frozen=True)
+
+    sentence: str = ""
+    instruction: str = ""
+    step_type: str = ""
+    tries: int | None = None
+    delay: float | None = None
+    vars: dict[str, str] = {}
+    outcome: str = ""
+    url_before: str = ""
+    url_after: str = ""
+    identity: StepIdentity
+
+    def render(self) -> str:
+        """Render the complete verbatim trace — the unit the GROUP STEPS block renders.
+
+        Returns:
+            The multi-line trace text — the pinned three-line format:
+            instruction, outcome label, URL pair; the sentence and the
+            identity never render.
+        """
+        return f"{self.instruction}\noutcome: {self.outcome}\nurl: {self.url_before} -> {self.url_after}"