prettyplay 0.0.2__py3-none-any.whl

prettyplay/config/loader.py

@@ -0,0 +1,336 @@
+"""Loading of the ``[tool.prettyplay]`` section of pyproject.toml with layered overrides."""
+
+import os
+import sys
+from pathlib import Path
+
+from pydantic import ValidationError
+
+from ..failures import PrettyplayError
+from .models import BrowserConfig, Config
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib
+
+#: The removed legacy env name; set — the load fails loudly before merging.
+_LEGACY_BROWSER_ENV = "PRETTYPLAY_BROWSER"
+
+#: Env variable name of every overridable setting; dotted names address the
+#: browser group, whose flat PRETTYPLAY_BROWSER_* names stay historical.
+_ENV_NAMES: dict[str, str] = {
+    setting: f"PRETTYPLAY_{setting.upper().replace('.', '_')}"
+    for setting in (
+        "provider",
+        "model",
+        "generation_model",
+        "classification_model",
+        "base_url",
+        "cache_root",
+        "generation_prompt",
+        "classification_prompt",
+        "strict",
+        "polling_timeout",
+        "polling_delay",
+        "interactive",
+        "generation_attempts",
+        "healing_attempts",
+        "llm_request_attempts",
+        "send_screenshots",
+        "generation_approve",
+        "browser.name",
+        "browser.screen",
+        "browser.headless",
+        "browser.endpoint",
+        "browser.accept_dialogs",
+        "browser.speed",
+    )
+}
+
+#: The settings whose env values parse as booleans.
+_BOOL_ENV_SETTINGS = frozenset(
+    {
+        "strict",
+        "interactive",
+        "send_screenshots",
+        "generation_approve",
+        "browser.headless",
+        "browser.accept_dialogs",
+    }
+)
+
+#: The settings whose env values parse as decimal integers.
+_INT_ENV_SETTINGS = frozenset({"generation_attempts", "healing_attempts", "llm_request_attempts", "browser.speed"})
+
+#: The settings whose env values parse as decimal floats.
+_FLOAT_ENV_SETTINGS = frozenset({"polling_timeout", "polling_delay"})
+
+#: The removed flat keys of the [tool.prettyplay] level and their new group homes.
+_FLAT_KEY_HOMES: dict[str, str] = {
+    "browser": "name",
+    "headless": "headless",
+    "browser_endpoint": "endpoint",
+}
+
+#: The allowed-values text of the settings the validation render names.
+_ALLOWED_TEXT: dict[str, str] = {
+    "provider": "openai, anthropic",
+    "browser.name": "chromium, firefox, webkit, chrome, msedge",
+    "generation_attempts": "a positive integer",
+    "healing_attempts": "a positive integer",
+    "llm_request_attempts": "a positive integer",
+    "browser.headless": "a boolean",
+    "browser.accept_dialogs": "a boolean",
+    "strict": "a boolean",
+    "polling_timeout": "None or a non-negative number (finite)",
+    "polling_delay": "a non-negative number",
+    "interactive": "a boolean",
+    "send_screenshots": "a boolean",
+    "generation_approve": "a boolean",
+    "model": "a non-empty string",
+    "generation_model": "a non-empty string",
+    "classification_model": "a non-empty string",
+    "base_url": "a non-empty string",
+    "cache_root": "a non-empty string",
+    "generation_prompt": "a non-empty string",
+    "classification_prompt": "a non-empty string",
+    "browser.endpoint": "a valid ws/wss URL",
+    "browser.screen": "an empty value, WxH (must be positive integers), fullscreen or a Playwright device name",
+    "browser.speed": "an integer 0-100 inclusive",
+}
+
+
+class ConfigurationError(PrettyplayError):
+    """An invalid prettyplay configuration: the loaded settings failed validation.
+
+    Args:
+        message: the rendered actionable text — one line per invalid setting
+            or per removed old flat key.
+    """
+
+
+def _find_pyproject() -> Path:
+    """Return the first existing pyproject.toml upward from the cwd.
+
+    Returns:
+        Absolute path of the found pyproject.toml.
+
+    Raises:
+        FileNotFoundError: when no pyproject.toml exists upward from the cwd.
+    """
+    for directory in (Path.cwd(), *Path.cwd().parents):
+        candidate = directory / "pyproject.toml"
+        if candidate.is_file():
+            return candidate
+
+    raise FileNotFoundError("pyproject.toml not found upward from the current directory")
+
+
+def _parse_env_scalar(setting: str, raw: str) -> object:
+    """Parse one environment override by the field type of the setting.
+
+    Args:
+        setting: the dotted setting name the variable overrides.
+        raw: the raw environment value.
+
+    Returns:
+        The parsed value: a bool, a decimal int, a float or the verbatim string.
+
+    Raises:
+        ConfigurationError: when the value does not parse — the message names
+            the setting, the received value and the accepted form.
+    """
+    if setting in _BOOL_ENV_SETTINGS:
+        lowered = raw.lower()
+
+        if lowered in ("true", "1"):
+            return True
+        if lowered in ("false", "0"):
+            return False
+
+        raise ConfigurationError(f"{setting}: received {raw!r} — allowed: a boolean (true/false/1/0)")
+
+    if setting in _INT_ENV_SETTINGS:
+        try:
+            return int(raw)
+        except ValueError:
+            raise ConfigurationError(f"{setting}: received {raw!r} — allowed: a decimal integer") from None
+
+    if setting in _FLOAT_ENV_SETTINGS:
+        try:
+            return float(raw)
+        except ValueError:
+            raise ConfigurationError(f"{setting}: received {raw!r} — allowed: a decimal float") from None
+
+    return raw
+
+
+def _collect_env_overrides() -> dict[str, object]:
+    """Collect and parse the set environment overrides of all supported settings.
+
+    Raises:
+        ConfigurationError: when a set variable does not parse by its field type.
+    """
+    overrides: dict[str, object] = {}
+
+    for setting, env_name in _ENV_NAMES.items():
+        raw = os.environ.get(env_name)
+        if raw is not None:
+            overrides[setting] = _parse_env_scalar(setting, raw)
+
+    return overrides
+
+
+def _render_validation(error: ValidationError) -> str:
+    """Render the pydantic error as actionable per-setting lines.
+
+    Args:
+        error: the pydantic validation failure of the merged settings.
+
+    Returns:
+        One line per invalid setting — the dotted setting name, the received
+        value and the allowed values or range — joined with newlines; no
+        pydantic internals in the user-visible text.
+    """
+    lines: list[str] = []
+
+    for entry in error.errors():
+        field = ".".join(str(part) for part in entry["loc"])
+        received = entry.get("input")
+
+        if entry.get("type") == "extra_forbidden":
+            lines.append(f"{field}: received {received!r} — not a prettyplay setting")
+            continue
+
+        allowed = _ALLOWED_TEXT.get(field, entry["msg"])
+        lines.append(f"{field}: received {received!r} — allowed: {allowed}")
+
+    return "\n".join(lines)
+
+
+def _reject_flat_keys(section: dict) -> None:
+    """Raise when the section carries removed old flat keys.
+
+    Args:
+        section: the raw ``[tool.prettyplay]`` mapping of the file.
+
+    Raises:
+        ConfigurationError: one line per present old flat key — the key name
+            and its new home inside the ``[tool.prettyplay.browser]`` group.
+            A ``browser`` key holding a table is the group itself, not a flat
+            key.
+    """
+    flat_old = [
+        key for key in _FLAT_KEY_HOMES if key in section and not (key == "browser" and isinstance(section[key], dict))
+    ]
+
+    if flat_old:
+        lines = [
+            f"{key}: removed — its new home is [tool.prettyplay.browser] {_FLAT_KEY_HOMES[key]}" for key in flat_old
+        ]
+        raise ConfigurationError("\n".join(lines))
+
+
+def _apply_overrides(file_config: Config, overrides: Config) -> Config:
+    """Overlay the explicitly set fields of ``overrides`` onto the file layer.
+
+    Args:
+        file_config: the validated pyproject+env layer.
+        overrides: the programmatic layer; a field participates when it was
+            passed at construction, is not None and is non-empty for strings —
+            explicitly set values win, untouched model defaults, None and empty
+            strings never overwrite the file layer.
+
+    Returns:
+        The effective configuration: ``file_config`` with the participating
+        overrides applied; the merge reaches inside the browser group —
+        explicitly set fields of a passed :class:`BrowserConfig` win over the
+        file group, untouched group defaults never overwrite it.
+    """
+    update: dict[str, object] = {}
+
+    for name, value in overrides:
+        if name not in overrides.model_fields_set:
+            continue
+        if value is None:  # None means unset (e.g. polling_timeout) — indistinguishable from untouched
+            continue
+        if isinstance(value, str) and not value:
+            continue
+        if isinstance(value, BrowserConfig):
+            group_update = {
+                group_name: group_value
+                for group_name, group_value in value
+                if group_name in value.model_fields_set and (group_value or not isinstance(group_value, str))
+            }
+            if group_update:
+                update["browser"] = file_config.browser.model_copy(update=group_update)
+            # no explicitly set group fields — the file group survives untouched
+        else:
+            update[name] = value
+
+    return file_config.model_copy(update=update)
+
+
+def load_config(pyproject_path: str | None = None, overrides: Config | None = None) -> Config:
+    """Load validated settings layered pyproject → env → explicit programmatic values.
+
+    Args:
+        pyproject_path: explicit pyproject.toml path; ``None`` auto-searches
+            upward from the current working directory.
+        overrides: the programmatic layer, typically a ``PrettyConfig`` built
+            by the integrator; ``None`` (or an instance with no explicitly set
+            fields) returns the validated file layer as is — an explicitly set
+            field (``model_fields_set``, non-None, non-empty for strings)
+            wins over the pyproject+env layer, the merge reaching inside the
+            browser group.
+
+    Returns:
+        Validated configuration.
+
+    Raises:
+        FileNotFoundError: when ``pyproject_path`` is ``None`` and no
+            pyproject.toml is found upward from the cwd.
+        tomllib.TOMLDecodeError: when the file is not valid TOML.
+        ConfigurationError: when merged settings fail validation or carry a
+            removed legacy name — the original ``ValidationError`` chained as
+            the cause when there is one.
+    """
+    path = Path(pyproject_path) if pyproject_path is not None else _find_pyproject()
+
+    with path.open("rb") as stream:
+        data = tomllib.load(stream)
+    section = data.get("tool", {}).get("prettyplay", {})
+
+    if _LEGACY_BROWSER_ENV in os.environ:
+        raise ConfigurationError(f"{_LEGACY_BROWSER_ENV} is no longer supported: use PRETTYPLAY_BROWSER_NAME")
+
+    _reject_flat_keys(section)
+
+    env = _collect_env_overrides()
+
+    merged = {**section, **{setting: value for setting, value in env.items() if "." not in setting}}
+    group_env = {setting.split(".", 1)[1]: value for setting, value in env.items() if "." in setting}
+
+    if group_env:
+        merged["browser"] = {**(merged.get("browser") or {}), **group_env}
+
+    browser_section = merged.get("browser")
+
+    if isinstance(browser_section, dict) and browser_section.get("name") == "":
+        # empty means unset only in the programmatic overlay; from the file or
+        # env layer an empty name is an invalid value, not an omission
+        raise ConfigurationError(f"browser.name: received '' — allowed: {_ALLOWED_TEXT['browser.name']}")
+
+    if not merged.get("cache_root"):
+        merged["cache_root"] = str(Path.cwd() / ".prettyplay" / "cache")
+
+    try:
+        file_config = Config(**merged)
+    except ValidationError as error:
+        raise ConfigurationError(_render_validation(error)) from error
+
+    if overrides is None:
+        return file_config
+
+    return _apply_overrides(file_config, overrides)

prettyplay/config/models.py

@@ -0,0 +1,288 @@
+"""Validated project settings of prettyplay — secrets never live here, LLM API keys come only from the environment."""
+
+import math
+import re
+from typing import Literal
+from urllib.parse import urlparse
+
+from pydantic import BaseModel, ConfigDict, PositiveInt, field_validator
+
+#: The browser matrix the group ``name`` setting is validated against.
+_BROWSER_MATRIX = ("chromium", "firefox", "webkit", "chrome", "msedge")
+
+#: The inclusive pace range, in percent, the group ``speed`` setting accepts.
+_SPEED_RANGE = range(0, 101)
+
+
+class BrowserConfig(BaseModel):
+    """The nested browser group of the project settings — every field defaults empty, load_config fills it.
+
+    Attributes:
+        name: browser of the {chromium, firefox, webkit, chrome, msedge} set;
+            chrome and msedge launch the locally installed browser through the
+            driver channel mechanism; default chromium; empty means unset in
+            the programmatic overlay — ``load_config`` rejects an empty name
+            arriving from the file or env layer.
+        screen: the single size setting; empty — the Playwright default; WxH —
+            a fixed viewport; fullscreen — the maximized window of a local
+            headed launch, a fixed 1920x1080 elsewhere; any other value — a
+            Playwright device name applied as the full descriptor. Validated
+            at format level only: a WxH-shaped value must carry positive
+            integers; every other value — including fullscreen and device
+            names — passes through unresolved, because the device registry
+            belongs to the running Playwright, never to the config.
+        headless: run the browser without a visible window of a local launch;
+            default True; ignored on a remote connect.
+        endpoint: ws endpoint of a remote browser; empty means the local
+            launch.
+        accept_dialogs: how the resolver of last resort settles a dialog
+            no in-step stock dialog capture claims — True accepts it,
+            False dismisses it (the Playwright default outcome); default
+            False. The resolution runs at the tail of the driver-thread
+            unit, not at the moment the dialog fires: a dialog unclaimed
+            by the step blocks the page until the unit ends.
+        speed: the pace of the run as a percentage; 100 — full speed, the
+            default, a behavior identical to today; lower values slow the
+            run linearly; 0 — the slowest supported pace; valid 0-100
+            inclusive — an out-of-range or non-integer value fails loudly
+            with the received value named, never a silent ignore.
+    """
+
+    model_config = ConfigDict(kw_only=True, extra="forbid")
+
+    name: str = "chromium"
+    screen: str = ""
+    headless: bool = True
+    endpoint: str = ""
+    accept_dialogs: bool = False
+    speed: int = 100
+
+    @field_validator("name")
+    @classmethod
+    def _validate_name(cls, value: str) -> str:
+        """Check that a non-empty name belongs to the browser matrix.
+
+        Args:
+            value: the raw name setting; empty means unset in the programmatic
+                overlay and passes through — ``load_config`` rejects an empty
+                name arriving from the file or env layer.
+
+        Returns:
+            The unchanged name when empty or inside the matrix.
+
+        Raises:
+            ValueError: when a non-empty name is outside the matrix.
+        """
+        if value and value not in _BROWSER_MATRIX:
+            raise ValueError("must be one of: chromium, firefox, webkit, chrome, msedge")
+
+        return value
+
+    @field_validator("endpoint")
+    @classmethod
+    def _validate_endpoint(cls, value: str) -> str:
+        """Check that a non-empty endpoint is a ws/wss URL.
+
+        Args:
+            value: the raw endpoint setting; empty means the local launch.
+
+        Returns:
+            The unchanged endpoint when empty or a valid ws/wss URL.
+
+        Raises:
+            ValueError: when a non-empty endpoint is not a ws/wss URL.
+        """
+        if not value:
+            return value
+
+        parsed = urlparse(value)
+
+        if parsed.scheme not in {"ws", "wss"} or not parsed.netloc:
+            raise ValueError("must be a valid ws/wss URL")
+
+        return value
+
+    @field_validator("screen")
+    @classmethod
+    def _validate_screen(cls, value: str) -> str:
+        """Check the format of a WxH-shaped screen value; pass everything else through.
+
+        Args:
+            value: the raw screen setting; empty, fullscreen and device names
+                stay unresolved by design.
+
+        Returns:
+            The unchanged screen value.
+
+        Raises:
+            ValueError: when a WxH-shaped value carries a non-positive
+                width or height.
+        """
+        if not value:
+            return value
+
+        match = re.fullmatch(r"(\d+)x(\d+)", value)
+        if match is None:
+            return value  # fullscreen, device names — the driver resolves them
+
+        width, height = int(match.group(1)), int(match.group(2))
+        if width <= 0 or height <= 0:
+            raise ValueError("must be positive integers in WxH form")
+
+        return value
+
+    @field_validator("speed", mode="before")
+    @classmethod
+    def _validate_speed(cls, value: object) -> object:
+        """Check that the pace is an integer 0-100 inclusive.
+
+        Args:
+            value: the raw speed setting; booleans are rejected explicitly
+                before the integer check — ``True`` is not a pace.
+
+        Returns:
+            The unchanged speed when an integer inside the 0-100 range.
+
+        Raises:
+            ValueError: when the value is a boolean, not an integer or
+                outside 0-100 — the received value is named, never a
+                silent ignore.
+        """
+        if isinstance(value, bool) or not isinstance(value, int) or value not in _SPEED_RANGE:
+            raise ValueError(f"must be an integer 0-100 inclusive — received {value!r}")
+
+        return value
+
+
+class Config(BaseModel):
+    """Validated project settings loaded from ``[tool.prettyplay]`` — fields default empty, load_config fills them.
+
+    Attributes:
+        provider: the LLM provider of the {openai, anthropic} set; default openai.
+        browser: the nested browser group — a :class:`BrowserConfig` with the
+            engine, the screen mode, the window visibility and the remote
+            endpoint.
+        model: main LLM model name.
+        generation_model: optional generation override; empty falls back to ``model``.
+        classification_model: optional classification override; empty falls back to ``model``.
+        base_url: optional custom LLM API endpoint.
+        cache_root: cache root; empty means the default resolved at load.
+        generation_prompt: user instructions for generation requests; non-empty
+            renders a separate USER INSTRUCTIONS block in generation and
+            regeneration requests; empty means no block.
+        classification_prompt: user instructions for classification requests;
+            non-empty renders a separate USER INSTRUCTIONS block in
+            classification requests only; takes no part in the step address;
+            empty means no block.
+        strict: replay-only mode; True — cached code executes honestly and
+            nothing is ever (re)generated; default False.
+        polling_timeout: the settle horizon of one step execution in seconds;
+            None — polling off (the default); 0 — an explicit disable
+            equivalent to None; a finite non-negative number — failed step
+            code is re-executed inside the window to absorb transient
+            page-state failures. Sizing: the window must exceed the longest
+            auto-wait of the step code the engineer wants to absorb — the
+            Playwright expect default is 5 s, so 6.0 covers one exhausted
+            expectation plus one re-execution; a 30 s action wait consumes any
+            sane window alone, polling targets expectation/element-state races.
+        polling_delay: the pause between settle re-executions in seconds;
+            default 0.5; 0 — repetition without a pause; must be a finite
+            non-negative number.
+        interactive: open the opt-in steering REPL when an otherwise terminal
+            step failure occurs on a non-strict interactive run; default
+            False — an accidentally enabled REPL must never hang CI.
+        generation_attempts: generation attempt budget per step per test; default 3.
+        healing_attempts: healing attempt budget per step per test; default 2.
+        llm_request_attempts: the total attempt budget of one LLM request —
+            the maximum number of physical request sends of one logical LLM
+            attempt of the port (generation, failure classification, group
+            diagnosis, compliance verdict alike), the initial request
+            included; default 3; 1 — request retries disabled, fully the
+            single-send behavior; the retry delays themselves are fixed
+            policy, never configurable; participates in the layered merge
+            like every other scalar setting.
+        send_screenshots: whether screenshots are attached to LLM requests.
+        generation_approve: whether the instruction compliance gate runs before
+            caching a generated step; True — every successfully executed
+            generation and regeneration candidate is verified against the user
+            instructions (the non-empty generation_prompt) before it is cached;
+            False — the gate never runs, fully the old behavior; default True
+            (the opt-out default).
+    """
+
+    model_config = ConfigDict(kw_only=True, extra="forbid")
+
+    provider: Literal["openai", "anthropic"] = "openai"
+    browser: BrowserConfig = BrowserConfig()
+    model: str = ""
+    generation_model: str = ""
+    classification_model: str = ""
+    base_url: str = ""
+    cache_root: str = ""
+    generation_prompt: str = ""
+    classification_prompt: str = ""
+    strict: bool = False
+    polling_timeout: float | None = None
+    polling_delay: float = 0.5
+    interactive: bool = False
+    generation_attempts: PositiveInt = 3
+    healing_attempts: PositiveInt = 2
+    llm_request_attempts: PositiveInt = 3
+    send_screenshots: bool = False
+    generation_approve: bool = True
+
+    @field_validator("polling_timeout")
+    @classmethod
+    def _validate_polling_timeout(cls, value: float | None) -> float | None:
+        """Check that a set timeout is a finite non-negative number.
+
+        Args:
+            value: the raw timeout setting; None means the settle window is
+                off; 0 is an explicit disable and stays legal.
+
+        Returns:
+            The unchanged timeout when None or a finite non-negative number.
+
+        Raises:
+            ValueError: when the value is negative or non-finite (inf/nan).
+        """
+        if value is None:
+            return value
+
+        if not math.isfinite(value) or value < 0:
+            raise ValueError("must be None or a non-negative number")
+
+        return value
+
+    @field_validator("polling_delay")
+    @classmethod
+    def _validate_polling_delay(cls, value: float) -> float:
+        """Check that the delay is a finite non-negative number.
+
+        Args:
+            value: the raw delay setting; 0 — repetition without a pause.
+
+        Returns:
+            The unchanged delay when finite and non-negative.
+
+        Raises:
+            ValueError: when the value is negative or non-finite (inf/nan).
+        """
+        if not math.isfinite(value) or value < 0:
+            raise ValueError("must be a non-negative number")
+
+        return value
+
+    @property
+    def effective_generation_model(self) -> str:
+        """Return generation_model when non-empty, otherwise model."""
+        return self.generation_model if self.generation_model else self.model
+
+    @property
+    def effective_classification_model(self) -> str:
+        """Return classification_model when non-empty, otherwise model."""
+        return self.classification_model if self.classification_model else self.model
+
+
+#: The public name of ``Config``: the integrator-facing settings model.
+PrettyConfig = Config

prettyplay/driver/.usages/error_kinds.md

@@ -0,0 +1,26 @@
+# Error kinds — the pollable map
+
+Domain: which failed step-code exceptions the settle window may absorb. Audience: engineers tuning polling and reasoning about why a failure did or did not retry.
+
+The driver ships a fixed map: `is_pollable_failure(exc)` returns True when the exception kind is transient page state — the settle window may re-execute the same code; False when the failure is deterministic or unknown — it goes straight to classification. Recognition is by exception type and message pattern; no LLM, no settings.
+
+| Kind | Message signature | Pollable |
+|---|---|---|
+| timeout | `Timeout NNNms exceeded` — locator, action, expectation or navigation wait | yes |
+| element state | `element is not visible`, `element is not enabled`, `element is outside of the viewport`, detached/stale element | yes |
+| navigation / context | `Execution context was destroyed`, `Target closed`, navigation interrupted mid-flight | yes |
+| failed expectation | plain `AssertionError` from a failed expect(...) chain or a plain Python assert on an immediate read — the check executed and did not hold | yes |
+| locator ambiguity | `strict mode violation: locator resolved to N elements` | no — the elements are there; waiting will not collapse them to one |
+| Python-level error | syntax, name and type errors of the step code itself | no — not a driver error at all |
+| unrecognized | anything else | no — conservative default, straight to classification |
+
+## Reading the map
+
+- Pollable kinds typically reflect a page-state race: the previous action finished while a state transition was still in flight; re-executing the same code once the state settles is honest retrying, not masking.
+- A failed expectation is pollable because the same code passing later means the state caught up — the check itself stays intact.
+- Locator ambiguity is deterministic: the locator itself is at fault, the classification labels it `fixable` and regeneration produces an unambiguous locator.
+
+## Rules
+
+- The map is fixed in code: it never reads settings and never asks an LLM.
+- The decision takes only the exception object — pure and deterministic.