prettyplay 0.0.0__py3-none-any.whl

prettyplay/llm/openai_provider.py

@@ -0,0 +1,187 @@
+"""The openai SDK implementation of the LlmProvider port."""
+
+import os
+
+from openai import OpenAI, OpenAIError
+
+from ..config import Config
+from ..failures import LlmUnavailableError
+from ._request import (
+    build_classification_fields,
+    build_fields_text,
+    extract_code_block,
+    openai_user_content,
+    parse_classification_line,
+    require_completion_text,
+    unparsable_classification,
+)
+from .models import FailureClassification
+from .provider import LlmProvider
+
+
+def _first_choice_text(response: object) -> str | None:
+    """Extract the message text of the first choice of an openai response.
+
+    Args:
+        response: the SDK response of a ``chat.completions.create`` call.
+
+    Returns:
+        The text of the first choice message, or ``None`` when the response
+        carries no choice at all (empty or missing ``choices``/``message``).
+    """
+    choices = getattr(response, "choices", None) or []
+    message = getattr(choices[0], "message", None) if choices else None
+
+    return getattr(message, "content", None)
+
+
+class OpenAiProvider(LlmProvider):
+    """The LlmProvider implementation served by the openai SDK.
+
+    Full parity with :class:`AnthropicProvider`: the same operations, the
+    same inputs, the same output shapes. The constructor reads no
+    environment and constructs no client; the SDK client is created lazily
+    on the first request, so the library starts without LLM credentials.
+    Every service failure maps to
+    :class:`~prettyplay.failures.LlmUnavailableError` naming the provider;
+    the API key is read from the environment only and never logged.
+    """
+
+    def __init__(self, config: Config) -> None:
+        """Keep the config; the SDK client stays unconstructed until the first request.
+
+        Args:
+            config: project settings; the effective models and the optional
+                base_url endpoint override come from it.
+        """
+        self._config = config
+        self._client: OpenAI | None = None
+
+    def _get_client(self) -> OpenAI:
+        """Construct the SDK client on the first request.
+
+        Returns:
+            The lazily constructed openai SDK client.
+
+        Raises:
+            LlmUnavailableError: the OPENAI_API_KEY environment variable is
+                missing or empty — generation and healing are blocked.
+        """
+        if self._client is None:
+            api_key = os.environ.get("OPENAI_API_KEY")
+
+            if not api_key:
+                raise LlmUnavailableError("llm unavailable: openai: OPENAI_API_KEY is not set")
+
+            self._client = OpenAI(api_key=api_key, base_url=self._config.base_url or None)
+        return self._client
+
+    def generate_step_code(  # noqa: PLR0913, PLR0917 — the signature is fixed by the port contract
+        self,
+        prompt: str,
+        user_instructions: str,
+        step_text: str,
+        previous_steps: list[str],
+        snapshot: str,
+        screenshot: bytes | None,
+        page_api: str,
+        existing_code: str | None,
+        error: str | None,
+    ) -> str:
+        """Generate step code of the fixed form working only through the driver facade.
+
+        Args:
+            prompt: the system prompt text supplied by the calling engine;
+                applied verbatim as the system message.
+            user_instructions: the project's code style instructions from the
+                generation_prompt setting; empty — the request carries no
+                instructions block, non-empty — rendered verbatim as a
+                separate USER INSTRUCTIONS block of the user content,
+                identically to the anthropic implementation.
+            step_text: the sentence of the step to generate.
+            previous_steps: the sentences of the previous steps of the test,
+                in execution order — scenario context.
+            snapshot: the accessibility snapshot of the current page.
+            screenshot: an optional PNG image of the page; passed only when
+                the project enables screenshots.
+            page_api: the exact page facade surface listing — the calls the
+                model may use.
+            existing_code: the existing step code that failed; non-empty only
+                on regeneration requests.
+            error: the failure description of the existing code; non-empty
+                only on regeneration requests.
+
+        Returns:
+            The generated step code of the fixed form.
+
+        Raises:
+            LlmUnavailableError: the SDK client is unavailable or the
+                service request failed.
+        """
+        text = build_fields_text(user_instructions, step_text, previous_steps, snapshot, page_api, existing_code, error)
+        messages = [
+            {"role": "system", "content": prompt},
+            {"role": "user", "content": openai_user_content(text, screenshot)},
+        ]
+
+        try:
+            response = self._get_client().chat.completions.create(
+                model=self._config.effective_generation_model,
+                messages=messages,
+            )
+        except OpenAIError as sdk_error:
+            raise LlmUnavailableError("llm unavailable: openai request failed") from sdk_error
+
+        return extract_code_block(require_completion_text(_first_choice_text(response), "openai"))
+
+    def classify_failure(  # noqa: PLR0913, PLR0917 — the signature is fixed by the port contract
+        self,
+        prompt: str,
+        step_text: str,
+        code: str,
+        error: str,
+        snapshot: str,
+        screenshot: bytes | None,
+    ) -> FailureClassification:
+        """Classify a failed cached step.
+
+        Args:
+            prompt: the system prompt text supplied by the calling engine;
+                applied verbatim as the system message.
+            step_text: the sentence of the failed step.
+            code: the existing step code that failed.
+            error: the human-readable description of the failure.
+            snapshot: the accessibility snapshot of the current page.
+            screenshot: an optional PNG image of the page; passed only when
+                the project enables screenshots.
+
+        Returns:
+            The classification verdict; an unparsable or unknown answer maps
+            protectively to the incurable category.
+
+        Raises:
+            LlmUnavailableError: the SDK client is unavailable or the
+                service request failed.
+        """
+        text = build_classification_fields(step_text, code, error, snapshot)
+        messages = [
+            {"role": "system", "content": prompt},
+            {"role": "user", "content": openai_user_content(text, screenshot)},
+        ]
+
+        try:
+            response = self._get_client().chat.completions.create(
+                model=self._config.effective_classification_model,
+                messages=messages,
+            )
+        except OpenAIError as sdk_error:
+            raise LlmUnavailableError("llm unavailable: openai request failed") from sdk_error
+
+        answer = require_completion_text(_first_choice_text(response), "openai")
+        parsed = parse_classification_line(answer)
+
+        if parsed is None:
+            return FailureClassification(**unparsable_classification())
+
+        category, explanation, recommendation = parsed
+        return FailureClassification(category=category, explanation=explanation, recommendation=recommendation)

prettyplay/llm/provider.py

@@ -0,0 +1,115 @@
+"""The unified LLM port of the library and the provider factory."""
+
+from ..config import Config
+from .models import FailureClassification
+
+
+class LlmProvider:
+    """The single LLM port: step code generation and failure classification.
+
+    One contract, two interchangeable SDK implementations selected by
+    configuration — the provider choice is never a capability difference.
+    The port itself is never instantiated at runtime; implementations own
+    one completion request per attempt (attempt budgets live in the calling
+    engine) and map every service failure to
+    :class:`~prettyplay.failures.LlmUnavailableError` naming the provider.
+    """
+
+    def generate_step_code(  # noqa: PLR0913, PLR0917 — the signature is fixed by the port contract
+        self,
+        prompt: str,
+        user_instructions: str,
+        step_text: str,
+        previous_steps: list[str],
+        snapshot: str,
+        screenshot: bytes | None,
+        page_api: str,
+        existing_code: str | None,
+        error: str | None,
+    ) -> str:
+        """Generate step code of the fixed form working only through the driver facade.
+
+        Args:
+            prompt: the system prompt text supplied by the calling engine;
+                applied verbatim as the system message.
+            user_instructions: the project's code style instructions supplied
+                by the calling engine from the generation_prompt setting;
+                empty — the request carries no instructions block, non-empty —
+                rendered verbatim as a separate USER INSTRUCTIONS block of the
+                user content, identically in both implementations.
+            step_text: the sentence of the step to generate.
+            previous_steps: the sentences of the previous steps of the test,
+                in execution order — scenario context.
+            snapshot: the accessibility snapshot of the current page.
+            screenshot: an optional PNG image of the page; passed only when
+                the project enables screenshots.
+            page_api: the exact page facade surface listing — the calls the
+                model may use.
+            existing_code: the existing step code that failed; non-empty only
+                on regeneration requests.
+            error: the failure description of the existing code; non-empty
+                only on regeneration requests.
+
+        Returns:
+            The generated step code of the fixed form.
+
+        Raises:
+            NotImplementedError: the port itself carries no implementation.
+        """
+        raise NotImplementedError("LlmProvider is a port; use create_provider() to select an implementation")
+
+    def classify_failure(  # noqa: PLR0913, PLR0917 — the signature is fixed by the port contract
+        self,
+        prompt: str,
+        step_text: str,
+        code: str,
+        error: str,
+        snapshot: str,
+        screenshot: bytes | None,
+    ) -> FailureClassification:
+        """Classify a failed cached step.
+
+        Args:
+            prompt: the system prompt text supplied by the calling engine;
+                applied verbatim as the system message.
+            step_text: the sentence of the failed step.
+            code: the existing step code that failed.
+            error: the human-readable description of the failure.
+            snapshot: the accessibility snapshot of the current page.
+            screenshot: an optional PNG image of the page; passed only when
+                the project enables screenshots.
+
+        Returns:
+            The classification verdict.
+
+        Raises:
+            NotImplementedError: the port itself carries no implementation.
+        """
+        raise NotImplementedError("LlmProvider is a port; use create_provider() to select an implementation")
+
+
+def create_provider(config: Config) -> LlmProvider:
+    """Select and construct the LLM provider from configuration.
+
+    Args:
+        config: project settings; the provider setting selects the SDK
+            implementation.
+
+    Returns:
+        The selected provider implementation.
+
+    Raises:
+        ValueError: the provider setting names no supported provider.
+    """
+    # deferred: the implementations subclass the port defined in this module,
+    # so a top-level import here would be circular
+    from .anthropic_provider import AnthropicProvider  # noqa: PLC0415
+    from .openai_provider import OpenAiProvider  # noqa: PLC0415
+
+    if config.provider == "openai":
+        return OpenAiProvider(config)
+
+    if config.provider == "anthropic":
+        return AnthropicProvider(config)
+
+    raise ValueError(f"unsupported provider {config.provider!r}: expected one of openai, anthropic")

prettyplay/reporting/.usages/hooks.md

@@ -0,0 +1,41 @@
+# Step and healing hooks
+
+Domain: event callbacks of prettyplay. Audience: integrators building custom reporting, metrics or CI reactions on top of step execution.
+
+StepHooks is a thin callback contract. The library calls the matching method synchronously while a step executes. The base implementation of every method is a no-op — override only the events you need. Hook implementations are registered on the main library object at the start of a test.
+
+## Events
+
+| Method | When | Payload |
+|---|---|---|
+| on_step_started | a step started executing | step_text, step_type (action or assertion) |
+| on_step_passed | the step finished successfully | step_text, step_type |
+| on_step_failed | the step failed | step_text, step_type, error (short description) |
+| on_step_verdict | the terminal failure carried a verdict (fires after on_step_failed) | step_text, category (rot, product_defect, incurable), explanation, recommendation |
+| on_generation_started | a generation attempt started | step_text, attempt (1-based) |
+| on_healing_started | healing of a failed cached step started | step_text, category (rot, product_defect, incurable) |
+| on_healed | the step healed, cache updated | step_text, explanation (why rot, what changed) |
+| on_cache_saved | step code written to the cache | step_text, filename |
+| on_cache_skipped | cache write skipped | step_text, reason (e.g. read-only cache) |
+
+## Example
+
+```python
+from prettyplay.reporting import StepHooks
+
+
+class HealingMonitor(StepHooks):
+    def on_step_verdict(self, step_text: str, category: str, explanation: str, recommendation: str) -> None:
+        print(f"verdict [{category}]: {step_text} — {explanation} → {recommendation}")
+
+    def on_healed(self, step_text: str, explanation: str) -> None:
+        print(f"healed: {step_text} — {explanation}")
+```
+
+## Rules
+
+- Handlers run synchronously inside step execution: keep them fast
+- A raising handler is logged as a warning and skipped — the test run never fails because of a hook
+- on_step_verdict fires only when the verdict exists: LLM unavailability skips the verdict quietly (WARNING in the log)
+- Payload values are plain strings; the attempt counter of on_generation_started is an int
+- Step texts land in logs and hooks: never put secrets or personal data into a step sentence

prettyplay/reporting/CODEMANIFEST

@@ -0,0 +1,79 @@
+Usages:
+  conventions: .goga/usages/conventions.md
+
+Annotations: |
+  Use `conventions` for code writing rules and testing.
+
+  Visibility goes through the standard logging library: the logger is named prettyplay.
+  Log messages: lowercase, concise operational wording, stable event names, contextual metadata attached.
+  Never log secrets, credentials, tokens or personal sensitive data.
+  Step lifecycle events — including the verdict event — are logged at INFO; a skipped cache write and a failed hook call — WARNING.
+
+---
+
+"StepHooks()":
+  location: hooks.py
+  annotations: |
+    Thin callback contract for integrators: consumer-side reactions to step, generation, healing and cache events. The library calls the hooks synchronously; the integrator overrides the events of interest. No event bus, no queuing, no delivery retries.
+
+    The base implementation of every method is a no-op: override only the events you need.
+  methods:
+    "on_step_started(step_text: str, step_type: str)": |
+      A step started executing; `step_type` is action or assertion.
+    "on_step_passed(step_text: str, step_type: str)": |
+      The step finished successfully.
+    "on_step_failed(step_text: str, step_type: str, error: str)": |
+      The step failed; `error` is a short human-readable failure description.
+    "on_step_verdict(step_text: str, category: str, explanation: str, recommendation: str)": |
+      The terminal failure of the step carried a verdict; fires after on_step_failed.
+
+      `step_text`: the sentence of the failed step.
+      `category`: the verdict label — rot, product_defect or incurable.
+      `explanation`: what the LLM saw on the page at the moment of the failure.
+      `recommendation`: the recommended engineer action.
+
+      Requirements:
+      - Not fired when the verdict was skipped: LLM unavailability logs a WARNING and raises no event
+      - Payload values are plain strings, uniform with the other events
+    "on_generation_started(step_text: str, attempt: int)": |
+      A code generation attempt started; `attempt` is the 1-based attempt number.
+    "on_healing_started(step_text: str, category: str)": |
+      Healing of a failed cached step started; `category` is the classification label: rot, product_defect, incurable.
+    "on_healed(step_text: str, explanation: str)": |
+      The step was healed and the cache updated; `explanation` says why it was rot and what changed.
+    "on_cache_saved(step_text: str, filename: str)": |
+      Step code was written to the cache file `filename`.
+    "on_cache_skipped(step_text: str, reason: str)": |
+      The cache write was skipped; `reason` names the cause, e.g. a read-only cache.
+
+"StepReporter(hooks: list[StepHooks])":
+  location: reporter.py
+  annotations: |
+    The single visibility point of the library: every step, generation, healing and cache event goes through the emit method — written to the logger prettyplay and forwarded to the registered `StepHooks` implementations.
+
+    `hooks`: callback implementations registered by the integrator; the list may be empty.
+  methods:
+    "emit(event: str, payload: dict[str, str | int])": |
+      Dispatch one event.
+
+      `event`: the event name — equals a `StepHooks` method name exactly.
+      `payload`: the payload fields of the event; values are strings, the attempt counter is an int.
+
+      Algorithm:
+      1. Write a structured log record to the logger prettyplay: the event name as the message, the payload fields as contextual metadata
+      2. For each registered hook, in registration order, call the method named `event` with the payload values as arguments
+      3. A hook that raises is logged as a warning and skipped; the run continues
+
+      Requirements:
+      - Log levels: step, generation and healing lifecycle — INFO; a skipped cache write and a failed hook call — WARNING
+
+      Constraints:
+      - No secrets in log records (see `conventions`)
+      - No own event bus: the emit call is a synchronous fan-out, nothing more
+
+---
+
+Author: Goga
+CreatedAt: 07/09/26
+Description: |
+  Visibility of prettyplay: the logger prettyplay plus the thin StepHooks callback contract.

prettyplay/reporting/__init__.py

@@ -0,0 +1,6 @@
+"""Facade of the prettyplay.reporting cell: the visibility of step execution."""
+
+from .hooks import StepHooks
+from .reporter import StepReporter
+
+__all__ = ["StepHooks", "StepReporter"]

prettyplay/reporting/hooks.py

@@ -0,0 +1,37 @@
+"""Thin callback contract for integrator-side reactions to step execution events.
+
+The library calls the matching method synchronously while a step executes; the
+base implementation of every method is a no-op — override only the events you
+need. No event bus, no queuing, no delivery retries.
+"""
+
+
+class StepHooks:
+    """Callback contract of the nine prettyplay events; every base method is a no-op."""
+
+    def on_step_started(self, step_text: str, step_type: str) -> None:
+        """A step started executing; ``step_type`` is action or assertion."""
+
+    def on_step_passed(self, step_text: str, step_type: str) -> None:
+        """The step finished successfully."""
+
+    def on_step_failed(self, step_text: str, step_type: str, error: str) -> None:
+        """The step failed; ``error`` is a short human-readable failure description."""
+
+    def on_step_verdict(self, step_text: str, category: str, explanation: str, recommendation: str) -> None:
+        """The terminal failure of the step carried a verdict; fires after on_step_failed."""
+
+    def on_generation_started(self, step_text: str, attempt: int) -> None:
+        """A code generation attempt started; ``attempt`` is the 1-based attempt number."""
+
+    def on_healing_started(self, step_text: str, category: str) -> None:
+        """Healing of a failed cached step started; ``category`` is rot, product_defect or incurable."""
+
+    def on_healed(self, step_text: str, explanation: str) -> None:
+        """The step was healed and the cache updated; ``explanation`` says why and what changed."""
+
+    def on_cache_saved(self, step_text: str, filename: str) -> None:
+        """Step code was written to the cache file ``filename``."""
+
+    def on_cache_skipped(self, step_text: str, reason: str) -> None:
+        """The cache write was skipped; ``reason`` names the cause, e.g. a read-only cache."""

prettyplay/reporting/reporter.py

@@ -0,0 +1,70 @@
+"""The single visibility point of prettyplay: the ``prettyplay`` logger plus hook fan-out."""
+
+import logging
+
+from .hooks import StepHooks
+
+#: Events written at WARNING; every other event is step/generation/healing lifecycle INFO.
+_WARNING_EVENTS = frozenset({"on_cache_skipped"})
+
+#: Attributes Logger.makeRecord forbids overwriting: collision keys get a ``ctx_`` prefix
+#: in the log record only — hooks always receive the original payload kwargs.
+_LOG_RECORD_RESERVED = frozenset(
+    {
+        "name",
+        "msg",
+        "message",
+        "args",
+        "levelname",
+        "levelno",
+        "pathname",
+        "filename",
+        "module",
+        "exc_info",
+        "funcName",
+        "lineno",
+        "created",
+        "msecs",
+        "relativeCreated",
+        "thread",
+        "threadName",
+        "process",
+        "processName",
+        "stack_info",
+        "asctime",
+        "taskName",
+    }
+)
+
+
+class StepReporter:
+    """Dispatches every step, generation, healing and cache event to the logger and hooks."""
+
+    def __init__(self, hooks: list[StepHooks]) -> None:
+        """Keep the hooks list by reference in the public ``hooks`` attribute.
+
+        Args:
+            hooks: callback implementations registered by the integrator; may be empty.
+                ``add_hooks`` of the main object appends into this same list.
+        """
+        self.hooks = hooks
+        self._logger = logging.getLogger("prettyplay")
+
+    def emit(self, event: str, payload: dict[str, str | int]) -> None:
+        """Dispatch one event to the logger and to every hook, in registration order.
+
+        Args:
+            event: the event name — equals a ``StepHooks`` method name exactly.
+            payload: the payload fields of the event; values are strings, the
+                attempt counter is an int.
+        """
+        level = logging.WARNING if event in _WARNING_EVENTS else logging.INFO
+        extra = {f"ctx_{key}" if key in _LOG_RECORD_RESERVED else key: value for key, value in payload.items()}
+
+        self._logger.log(level, event, extra=extra)
+
+        for hook in self.hooks:
+            try:
+                getattr(hook, event)(**payload)
+            except Exception:
+                self._logger.warning("hook call failed", extra={"event": event, "hook": type(hook).__name__})

prettyplay/runtime.py

@@ -0,0 +1,107 @@
+"""Per-test composition root of the library: the objects one test owns.
+
+One :class:`PrettyplayRuntime` serves exactly one test: it composes the
+validated settings, the per-test attempt registry, the browser driver and
+the LLM provider of that single test. Nothing is shared between tests —
+two tests in one process build two runtimes with fresh budgets and
+independent browser sessions. The driver and the provider construct
+lazily — building the runtime (and any test object on top of it) never
+requires LLM credentials and never launches a browser.
+"""
+
+from __future__ import annotations
+
+import atexit
+
+from .cache import RunBudgets
+from .config import Config
+from .driver import DriverSession, PageFacade
+from .llm import LlmProvider, create_provider
+
+
+class PrettyplayRuntime:
+    """The composition root: the per-test objects one test composes.
+
+    The config and the attempt registry build eagerly — both are cheap and
+    credential-free. The browser driver and the LLM provider construct lazily
+    on first access; the provider client itself stays unconstructed until the
+    first request, so no LLM key is needed to build the runtime. Every
+    instance registers its own close with ``atexit``, so the browser and the
+    Playwright driver of the test stop synchronously before the process exits
+    even when the test never calls close explicitly. A manual ``close``
+    unregisters the hook — a closed runtime never stays pinned for the rest
+    of the process — and a driver started after a close re-arms it.
+
+    Attributes:
+        _config: validated project settings of the test.
+        _budgets: the per-test attempt registry owned by this runtime.
+        _driver: the browser driver of the test; ``None`` until first access.
+        _provider: the LLM provider of the test; ``None`` until first access.
+    """
+
+    def __init__(self, config: Config) -> None:
+        """Compose the eager per-test objects from the config.
+
+        Args:
+            config: validated project settings of the test.
+        """
+        self._config = config
+        self._budgets = RunBudgets(config.generation_attempts, config.healing_attempts)
+        self._driver: DriverSession | None = None
+        self._provider: LlmProvider | None = None
+        atexit.register(self.close)
+
+    @property
+    def config(self) -> Config:
+        """The validated settings of the test."""
+        return self._config
+
+    @property
+    def budgets(self) -> RunBudgets:
+        """The per-test attempt registry owned by this one runtime."""
+        return self._budgets
+
+    @property
+    def driver(self) -> DriverSession:
+        """The browser driver of the test, constructed lazily exactly once.
+
+        A construction after a ``close`` re-arms the ``atexit`` hook the
+        close dropped: a freshly started browser always has its exit stop.
+        """
+        if self._driver is None:
+            self._driver = DriverSession(self._config)
+            atexit.register(self.close)
+
+        return self._driver
+
+    @property
+    def provider(self) -> LlmProvider:
+        """The LLM provider of the test, constructed lazily exactly once."""
+        if self._provider is None:
+            self._provider = create_provider(self._config)
+
+        return self._provider
+
+    def open_page(self) -> PageFacade:
+        """Open a fresh isolated page of the test driver.
+
+        Returns:
+            The facade of the new page of a fresh isolated context.
+        """
+        return self.driver.open_context()
+
+    def close(self) -> None:
+        """Stop the browser driver of the test; safe when nothing was started.
+
+        Idempotent: a call before any driver access and repeated calls are
+        no-ops. The call also drops the ``atexit`` hook registered in
+        ``__init__`` — a closed runtime and its objects are collectible, not
+        pinned until process exit — and a driver started later re-arms the
+        hook. The runtime itself stays usable after the call: the next
+        driver access constructs a fresh session.
+        """
+        atexit.unregister(self.close)
+
+        if self._driver is not None:
+            self._driver.close()
+            self._driver = None