prettyplay 0.0.0__py3-none-any.whl

prettyplay/engine/healer.py

@@ -0,0 +1,116 @@
+"""Healing of failed cached steps: classification verdict decides the branch."""
+
+from ..cache import CachedStep, RunBudgets, StepCache
+from ..config import Config
+from ..driver import PageFacade
+from ..failures import FailureVerdict, IncurableStepError, ProductDefectError
+from ..llm import LlmProvider
+from ..reporting import StepReporter
+from .classification import classify_step_failure
+from .generator import StepGenerator
+
+
+class StepHealer:
+    """Heals a failed cached step according to the classification verdict.
+
+    The healer never heals blindly. It first asks the provider to classify
+    the failure of the cached code, then follows the verdict: a product
+    defect propagates loudly as the signal the test suite exists for
+    (the cache stays untouched — nothing to regenerate), an incurable step
+    propagates with the verdict fields, and rot delegates to the generator,
+    which regenerates the code and rewrites the cache only after the healed
+    candidate has actually worked on the page.
+
+    Attributes:
+        _config: project settings; the screenshot flag feeds the requests.
+        _provider: the LLM port implementation classifying the failure.
+        _generator: the regeneration loop of the rot branch.
+        _reporter: the visibility point for healing events.
+    """
+
+    def __init__(  # noqa: PLR0913, PLR0917 — the signature is fixed by the engine contract
+        self,
+        config: Config,
+        provider: LlmProvider,
+        generator: StepGenerator,
+        cache: StepCache,  # noqa: ARG002 — written by the generator only; kept for contract symmetry
+        budgets: RunBudgets,  # noqa: ARG002 — spent by the generator only; kept for contract symmetry
+        reporter: StepReporter,
+    ) -> None:
+        """Keep the collaborators of the healing branch.
+
+        Args:
+            config: project settings; ``send_screenshots`` attaches page images.
+            provider: the LLM port implementation classifying the failure.
+            generator: the regeneration loop handling the rot verdict.
+            cache: the store of the failed step; written by the generator
+                only — accepted for contract symmetry, never read here.
+            budgets: the per-test attempt registry; spent by the generator —
+                accepted for contract symmetry, never read here.
+            reporter: the visibility point for engine events.
+        """
+        self._config = config
+        self._provider = provider
+        self._generator = generator
+        self._reporter = reporter
+
+    def heal(
+        self,
+        step: CachedStep,
+        error: str,
+        previous_steps: list[str],
+        page: PageFacade,
+    ) -> CachedStep:
+        """Heal a failed cached step according to the classification verdict.
+
+        Args:
+            step: the cached step whose code failed.
+            error: the failure description of the cached code.
+            previous_steps: the sentences of the previous steps of the test.
+            page: the live page facade the healed code runs against.
+
+        Returns:
+            The healed step with proven code, already cached by the generator.
+
+        Raises:
+            ProductDefectError: the expectation of the step is genuinely
+                broken in the product; the cache stays untouched.
+            IncurableStepError: the verdict says regeneration cannot help,
+                or the regeneration attempt budget is exhausted — the
+                exhaustion reuses the verdict of this classification, no
+                second LLM request is made.
+            LlmUnavailableError: the provider service failed; no retry.
+        """
+        step_text = step.identity.normalized_text
+        classification = classify_step_failure(self._config, self._provider, step_text, step.code, error, page)
+
+        verdict = FailureVerdict(
+            category=classification.category,
+            explanation=classification.explanation,
+            recommendation=classification.recommendation,
+        )
+
+        self._reporter.emit("on_healing_started", {"step_text": step_text, "category": classification.category})
+
+        if classification.category == "product_defect":
+            raise ProductDefectError(step_text, classification.explanation, verdict)
+        if classification.category == "incurable":
+            raise IncurableStepError(step_text, classification.explanation, verdict)
+
+        try:
+            healed = self._generator.regenerate(
+                identity=step.identity,
+                step_text=step_text,
+                previous_steps=previous_steps,
+                page=page,
+                existing_code=step.code,
+                error=error,
+            )
+        except IncurableStepError as incurable:
+            if incurable.verdict is None:
+                # regeneration exhausted: verdict of this classification, no second LLM request
+                raise IncurableStepError(step_text, incurable.reason, verdict) from incurable
+            raise  # a fresh failed-check verdict is never overwritten
+
+        self._reporter.emit("on_healed", {"step_text": step_text, "explanation": classification.explanation})
+        return healed

prettyplay/engine/text.py

@@ -0,0 +1,19 @@
+"""Shared short-failure text of the engine: one truncation policy for reports and requests."""
+
+#: Upper bound of the short failure description carried by reports and healing requests.
+SHORT_ERROR_LENGTH = 200
+
+
+def first_line_short(exc: Exception) -> str:
+    """Return the first line of the exception text, cut to 200 characters.
+
+    A message-less exception (a bare ``assert`` in step code) yields an
+    empty description instead of crashing the reporting and healing paths.
+
+    Args:
+        exc: the exception raised by the failed step or candidate branch.
+
+    Returns:
+        The short failure description carried by reports and requests.
+    """
+    return str(exc).partition("\n")[0][:SHORT_ERROR_LENGTH]

prettyplay/executor.py

@@ -0,0 +1,109 @@
+"""The step cycle: cache hit — execute; cache miss — generate; cached failure — heal."""
+
+from .cache import RunBudgets, StepCache, StepIdentity, normalize_step_text
+from .driver import PageFacade
+from .engine import StepGenerator, StepHealer, run_step_code
+from .engine.text import first_line_short
+from .failures import IncurableStepError, ProductDefectError
+from .reporting import StepReporter
+
+
+class StepExecutor:
+    """The owner of the step cycle of one test.
+
+    One step goes through the full cycle: a cache hit executes the cached
+    code with no LLM involvement whatsoever; a miss delegates to the
+    generator, which stores the step after the candidate has actually
+    worked; a failed cached step delegates to the healer, whose verdict
+    decides between a loud product defect, an incurable step, and rot
+    regeneration. The scenario context — the sentences of the previous
+    steps of this test — feeds every generation and healing request.
+
+    Attributes:
+        cache_key: the context key of the owning test object.
+        _cache: the step cache of the test.
+        _generator: the generation engine of the cycle.
+        _healer: the healing engine of the cycle.
+        _reporter: the visibility point of the test.
+        _scenario: the sentences of the previous steps of this test.
+    """
+
+    def __init__(  # noqa: PLR0913, PLR0917 — the signature is fixed by the root cell contract
+        self,
+        cache_key: str,
+        cache: StepCache,
+        generator: StepGenerator,
+        healer: StepHealer,
+        budgets: RunBudgets,  # noqa: ARG002 — spent by the engine; kept for contract symmetry
+        reporter: StepReporter,
+    ) -> None:
+        """Keep the collaborators of the step cycle and reset the scenario context.
+
+        Args:
+            cache_key: the context key of the owning test object.
+            cache: the step cache of the test.
+            generator: the generation engine of the cycle.
+            healer: the healing engine of the cycle.
+            budgets: the per-test attempt registry; attempts are spent
+                by the engine, not by the executor.
+            reporter: the visibility point of the test.
+        """
+        self.cache_key = cache_key
+        self._cache = cache
+        self._generator = generator
+        self._healer = healer
+        self._reporter = reporter
+        self._scenario: list[str] = []  # test scenario context
+
+    def execute(self, step_text: str, step_type: str, page: PageFacade) -> None:
+        """Run one step through the full cycle.
+
+        Args:
+            step_text: the sentence of the step as written by the engineer.
+            step_type: the kind of the step sentence ({action, assertion}).
+            page: the live page facade of the current test.
+
+        Raises:
+            ProductDefectError: the healed step verdict says the expectation
+                of the step is genuinely broken in the product.
+            IncurableStepError: the step never generated successfully, or the
+                verdict says regeneration cannot help.
+            LlmUnavailableError: the provider service failed; no retry.
+        """
+        try:
+            self._reporter.emit("on_step_started", {"step_text": step_text, "step_type": step_type})
+
+            identity = StepIdentity(
+                cache_key=self.cache_key,
+                step_type=step_type,
+                normalized_text=normalize_step_text(step_text),
+            )
+            cached = self._cache.load(identity)
+
+            if cached is not None:
+                try:
+                    run_step_code(cached.code, page)
+                except Exception as error:  # cached code failed — context goes to healing
+                    self._healer.heal(cached, first_line_short(error), self._scenario, page)  # healed = re-executed
+            else:
+                self._generator.generate(identity, step_text, self._scenario, page)
+
+            self._scenario.append(step_text)
+            self._reporter.emit("on_step_passed", {"step_text": step_text, "step_type": step_type})
+        except Exception as error:
+            self._reporter.emit(
+                "on_step_failed",
+                {"step_text": step_text, "step_type": step_type, "error": first_line_short(error)},
+            )
+
+            if isinstance(error, (ProductDefectError, IncurableStepError)) and error.verdict is not None:
+                self._reporter.emit(
+                    "on_step_verdict",
+                    {
+                        "step_text": step_text,
+                        "category": error.verdict.category,
+                        "explanation": error.verdict.explanation,
+                        "recommendation": error.verdict.recommendation,
+                    },
+                )
+            raise

prettyplay/failures/.usages/taxonomy.md

@@ -0,0 +1,40 @@
+# Failure taxonomy
+
+Domain: failure kinds of prettyplay. Audience: integrators wiring library failures into runner and CI reporting.
+
+Every step failure is one of three distinct kinds; all derive from `PrettyplayError`, so one except clause catches any prettyplay failure. A fourth kind — the configuration error — joins the base from the config cell.
+
+| Exception | Meaning | When it happens | Recommended reaction |
+|---|---|---|---|
+| ProductDefectError | real product regression | an assertion expectation legitimately failed | treat as a bug: file it, fix the product — this failure is the value of the suite |
+| IncurableStepError | the step cannot be (re)generated | attempt budget exhausted, step text no longer matches reality, ambiguity | follow `recommendation`: reword the step or refresh the cache |
+| LlmUnavailableError | LLM infrastructure down | generation or healing ran while the provider was unavailable | restore provider access or keys; cached steps are unaffected |
+| ConfigurationError | settings are invalid | the first library use loaded an invalid [tool.prettyplay] section | fix the named setting — the message lists the allowed values |
+
+## Verdicts on terminal failures
+
+ProductDefectError and IncurableStepError carry an optional verdict: category, explanation, recommendation. It is fully present in the exception message, the on_step_verdict hook event and the log. When the LLM is unavailable the verdict is skipped quietly (WARNING in the log) — the failure itself is never delayed or distorted.
+
+```python
+import pytest
+
+from prettyplay.failures import IncurableStepError
+
+
+def test_reports_only_library_failures():
+    with pytest.raises(IncurableStepError) as info:
+        ...
+    assert info.value.recommendation
+    # info.value.verdict may be None when the LLM was unavailable
+```
+
+## Assertion semantics
+
+ProductDefectError is also an AssertionError: unittest reports the failed check as a failure (not an error), pytest shows it as an ordinary assertion failure, the traceback is folded to the library boundary. Catch it with `except PrettyplayError` or `except AssertionError` — both work.
+
+## Rules
+
+- Every failure message is actionable: what happened, on which step, what to do next
+- A healed run never turns a ProductDefectError into a green test
+- LlmUnavailableError never occurs on the cached path — a cached suite runs without any LLM
+- The verdict explanation never replaces the primary failure — it is appended

prettyplay/failures/CODEMANIFEST

@@ -0,0 +1,117 @@
+Usages:
+  conventions: .goga/usages/conventions.md
+
+Annotations: |
+  Use `conventions` for code writing rules and testing.
+
+  The failure taxonomy of the library: three distinct, user-distinguishable step failure kinds plus the shared verdict type; every failure carries an actionable message.
+  All failure types derive from the single library base `PrettyplayError`; ProductDefectError additionally derives from AssertionError — the failed check is a failure, never an error, in any runner.
+  The rendered message of a terminal failure starts with its primary reason; the verdict render is appended, never interleaved.
+
+---
+
+"PrettyplayError(message: str)":
+  location: errors.py
+  annotations: |
+    The common base of every library failure. Exists for one consumer need: catch any prettyplay failure with a single except clause at the test-suite boundary.
+
+    `message`: the failure description.
+
+"FailureVerdict(category: str, explanation: str, recommendation: str)":
+  location: errors.py
+  annotations: |
+    The verdict of a terminal step failure: what the LLM saw on the page at the moment of the failure and what the engineer should do next.
+
+    `category`: the classification label: rot, product_defect or incurable.
+    `explanation`: what happened on the page — one short sentence.
+    `recommendation`: the recommended engineer action — one short sentence.
+
+    Requirements:
+    - Built by the engines from the failure classification; the failure types never request it themselves
+  properties:
+    "category -> str": |
+      The classification label: rot, product_defect or incurable.
+    "explanation -> str": |
+      What happened on the page at the moment of the failure.
+    "recommendation -> str": |
+      The recommended engineer action.
+  methods:
+    "render() -> text: str": |
+      Render the verdict as stable labelled lines — the single render used by the exception message tail, the hook event payload and the log record.
+
+      `text`: the rendered verdict.
+
+      Algorithm:
+      1. Build one line per non-empty field: category:, explanation:, recommendation:
+      2. Join the lines
+
+      Requirements:
+      - Labels are stable lowercase words — integrators parse them
+
+"PrettyplayError::ProductDefectError(step_text: str, message: str, verdict: FailureVerdict | None)":
+  location: errors.py
+  annotations: |
+    A real functional product defect: the expectation of an assertion step legitimately did not hold against the current application state. This is the signal the test suite exists for.
+
+    `step_text`: the sentence of the failed step.
+    `message`: what exactly was expected and what was observed — the primary reason.
+    `verdict`: the optional `FailureVerdict`; absent when the LLM was unavailable — the failure never waits for it.
+
+    Requirements:
+    - Derives from `PrettyplayError` and AssertionError: catchable as any library failure and as an assertion failure in the same except clauses
+    - The rendered message starts with `message`; the `verdict` render is appended when present
+    - The traceback a runner sees starts at the library boundary — internal library frames are folded away
+    - Propagates to the test runner as a failing test: no retry, no healing
+
+    Constraints:
+    - The library facade stays framework-agnostic: the runner alignment is done by the type itself, never by a runner plugin or integration
+  properties:
+    "step_text -> str": |
+      The sentence of the failed step.
+    "message -> str": |
+      What exactly was expected and what was observed.
+    "verdict -> FailureVerdict | None": |
+      The optional failure verdict; None — the explicit absence when the LLM was unavailable.
+
+"PrettyplayError::IncurableStepError(step_text: str, reason: str, verdict: FailureVerdict | None)":
+  location: errors.py
+  annotations: |
+    An incurable step: regeneration cannot produce working code — the attempt budget is exhausted, the step text no longer matches the application reality, or the intent is ambiguous.
+
+    `step_text`: the sentence of the failed step.
+    `reason`: the specific incurability cause — the primary reason of the rendered message.
+    `verdict`: the optional `FailureVerdict` — reused from a classification that already happened or requested at budget exhaustion; absent when the LLM was unavailable.
+
+    Requirements:
+    - The recommendation is carried by `verdict`; the recommendation property derives from it, falling back to the built-in path guidance when the verdict is absent
+    - The rendered message starts with `reason`, then appends the `verdict` render when present; the fallback recommendation keeps the message actionable without a verdict
+    - An execution failure, not a failed check: derives from `PrettyplayError` only, never from AssertionError
+  properties:
+    "step_text -> str": |
+      The sentence of the failed step.
+    "reason -> str": |
+      The specific incurability cause.
+    "recommendation -> str": |
+      The recommended engineer action: verdict recommendation when present, the built-in path guidance otherwise.
+    "verdict -> FailureVerdict | None": |
+      The optional failure verdict; None — the explicit absence when the LLM was unavailable.
+
+"PrettyplayError::LlmUnavailableError(message: str)":
+  location: errors.py
+  annotations: |
+    LLM infrastructure failure: the provider service is unreachable, times out, rate-limits or rejects authentication. Blocks only code generation and healing; cached steps keep running.
+
+    `message`: the failure description naming the provider.
+
+    Requirements:
+    - Raised only on generation or healing paths; never on a cached step execution path
+  properties:
+    "message -> str": |
+      The failure description naming the provider.
+
+---
+
+Author: Goga
+CreatedAt: 07/09/26
+Description: |
+  The failure taxonomy of prettyplay: product defect, incurable step, LLM infrastructure — mutations of one library base — and the shared verdict of a terminal failure.

prettyplay/failures/__init__.py

@@ -0,0 +1,17 @@
+"""Facade of the prettyplay.failures cell: the failure taxonomy of the library."""
+
+from .errors import (
+    FailureVerdict,
+    IncurableStepError,
+    LlmUnavailableError,
+    PrettyplayError,
+    ProductDefectError,
+)
+
+__all__ = [
+    "FailureVerdict",
+    "IncurableStepError",
+    "LlmUnavailableError",
+    "PrettyplayError",
+    "ProductDefectError",
+]

prettyplay/failures/errors.py

@@ -0,0 +1,147 @@
+"""The failure taxonomy of prettyplay: three distinct kinds, one library base.
+
+Every failure the library raises derives from :class:`PrettyplayError`, so a
+test suite catches any prettyplay failure with a single ``except`` clause at
+its boundary. Each kind carries actionable fields instead of an opaque string.
+The rendered message of a terminal failure starts with its primary reason;
+the verdict render is appended, never interleaved.
+"""
+
+from dataclasses import dataclass
+
+
+class PrettyplayError(Exception):
+    """The common base of every library failure.
+
+    Args:
+        message: the failure description.
+    """
+
+    def __init__(self, message: str) -> None:
+        self.message = message
+
+        super().__init__(message)
+
+
+@dataclass(frozen=True)
+class FailureVerdict:
+    """The verdict of a terminal step failure, carried by the errors that stop the run.
+
+    Built by the engines from a :class:`~prettyplay.llm.FailureClassification`;
+    the failure types never request it themselves. A plain frozen value object,
+    not a pydantic model — the source classification already validated the data,
+    and failure paths stay cheap.
+
+    Args:
+        category: the classification label: rot, product_defect or incurable.
+        explanation: what happened on the page — one short sentence.
+        recommendation: the recommended engineer action — one short sentence.
+    """
+
+    category: str
+    explanation: str
+    recommendation: str
+
+    def render(self) -> str:
+        """Render the verdict as stable labelled lines.
+
+        The single render used by the exception message tail, the hook event
+        payload content and the log record; the labels are stable lowercase
+        words integrators parse. An empty field yields no line.
+
+        Returns:
+            The rendered verdict — one line per non-empty field, joined with newlines.
+        """
+        fields = (
+            ("category", self.category),
+            ("explanation", self.explanation),
+            ("recommendation", self.recommendation),
+        )
+
+        return "\n".join(f"{label}: {value}" for label, value in fields if value)
+
+
+class ProductDefectError(PrettyplayError, AssertionError):
+    """A real functional product defect: the expectation of an assertion step did not hold.
+
+    The signal the test suite exists for: no retry, no healing — propagates to
+    the test runner as a failing test. Derives from both :class:`PrettyplayError`
+    and ``AssertionError``, so any runner counts it as a failure, never an error.
+
+    Args:
+        step_text: the sentence of the failed step.
+        message: what exactly was expected and what was observed — the primary reason.
+        verdict: the optional :class:`FailureVerdict`; ``None`` — the explicit
+            absence when the LLM was unavailable, the failure never waits for it.
+    """
+
+    def __init__(self, step_text: str, message: str, verdict: FailureVerdict | None = None) -> None:
+        self.step_text = step_text
+        self.message = message
+        self.verdict = verdict
+
+        PrettyplayError.__init__(self, message)
+
+    def __str__(self) -> str:
+        if self.verdict is None:
+            return self.message
+
+        return self.message + "\n" + self.verdict.render()
+
+
+class IncurableStepError(PrettyplayError):
+    """An incurable step: regeneration cannot produce working code.
+
+    Raised when the attempt budget is exhausted, the step text no longer
+    matches the application reality, or the intent is ambiguous. An execution
+    failure, not a failed check — derives from :class:`PrettyplayError` only,
+    never from ``AssertionError``.
+
+    Args:
+        step_text: the sentence of the failed step.
+        reason: the specific incurability cause — the primary reason.
+        verdict: the optional :class:`FailureVerdict` — reused from a
+            classification that already happened or requested at budget
+            exhaustion; ``None`` when the LLM was unavailable.
+    """
+
+    def __init__(self, step_text: str, reason: str, verdict: FailureVerdict | None = None) -> None:
+        self.step_text = step_text
+        self.reason = reason
+        self.verdict = verdict
+
+        super().__init__(reason)
+
+    @property
+    def recommendation(self) -> str:
+        """The recommended engineer action.
+
+        Returns:
+            The verdict recommendation when present, the built-in path guidance otherwise.
+        """
+        if self.verdict is not None:
+            return self.verdict.recommendation
+
+        return "reword the step or refresh the cache"
+
+    def __str__(self) -> str:
+        if self.verdict is not None:
+            return self.reason + "\n" + self.verdict.render()
+
+        return self.reason + "\nrecommendation: reword the step or refresh the cache"
+
+
+class LlmUnavailableError(PrettyplayError):
+    """LLM infrastructure failure: the provider service is unreachable or rejects the request.
+
+    Blocks only code generation and healing; cached steps keep running. No
+    retries.
+
+    Args:
+        message: the failure description naming the provider.
+    """
+
+    def __init__(self, message: str) -> None:
+        self.message = message
+
+        super().__init__(message)

prettyplay/llm/.usages/classification.md

@@ -0,0 +1,25 @@
+# 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 |
+| incurable | regeneration cannot help: budget exhausted, text no longer matches reality, ambiguity | the incurable failure carries step, reason, recommendation |
+
+## Call
+
+```python
+classification = provider.classify_failure(
+    prompt=system_prompt,  # the system prompt text comes from the calling engine
+    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)
+```

prettyplay/llm/.usages/providers.md

@@ -0,0 +1,33 @@
+# 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 main model for both operations | — |
+| generation_model | code generation only | model |
+| classification_model | failure classification only | model |
+
+base_url overrides the provider endpoint when set.
+
+## Parity
+
+Both providers expose the same two operations — generate_step_code and classify_failure — with identical inputs, identical output shapes and the identical failure taxonomy: a provider service failure raises LlmUnavailableError; cached step code never depends on the provider. One request per attempt; attempt 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.