prettyplay 0.0.0__py3-none-any.whl

prettyplay/cache/models.py

@@ -0,0 +1,60 @@
+"""In-memory models of the step cache: step addressing and a cached unit.
+
+``StepIdentity`` is the address of a step: the triple (cache key, step type,
+normalized sentence) plus the filename derived from it. ``CachedStep`` is one
+unit of the cache in memory: the identity, the generated code, and the date
+of its creation.
+"""
+
+import hashlib
+
+from pydantic import BaseModel, ConfigDict
+
+#: Unit Separator: makes the identity concatenation unambiguous.
+_IDENTITY_SEPARATOR = "\x1f"
+
+
+class StepIdentity(BaseModel):
+    """The address of a step in the repository cache.
+
+    Attributes:
+        cache_key: the key of the test the step belongs to.
+        step_type: the kind of the step sentence ({action, assertion}).
+        normalized_text: the normalized step sentence.
+    """
+
+    model_config = ConfigDict(kw_only=True)
+
+    cache_key: str
+    step_type: str
+    normalized_text: str
+
+    @property
+    def filename(self) -> str:
+        """Return the cache filename deterministically derived from the triple.
+
+        The three parts are joined with the Unit Separator (so no pair of
+        values can collide with another pair), hashed with sha256, and given
+        the ``.py`` extension. The name does not have to be a Python
+        identifier: the cache loader parses the file text and never imports
+        the module by name.
+        """
+        identity_string = _IDENTITY_SEPARATOR.join((self.cache_key, self.step_type, self.normalized_text))
+        digest = hashlib.sha256(identity_string.encode("utf-8")).hexdigest()
+        return f"{digest}.py"
+
+
+class CachedStep(BaseModel):
+    """One unit of the step cache: a working step bound to its identity.
+
+    Attributes:
+        identity: the address of the step.
+        code: the step code of the fixed form ``def step(page) -> None:``.
+        created_at: the date the code was generated (ISO format).
+    """
+
+    model_config = ConfigDict(kw_only=True)
+
+    identity: StepIdentity
+    code: str
+    created_at: str

prettyplay/cache/store.py

@@ -0,0 +1,260 @@
+"""Repository store of cached steps: deterministic addressing, atomic best-effort writes."""
+
+import ast
+import contextlib
+import os
+import tempfile
+import time
+from pathlib import Path
+
+from ..config import Config
+from ..reporting import StepReporter
+from .models import CachedStep, StepIdentity
+
+#: Header constants of a cache file: metadata first, then the step code.
+_HEADER_FIELDS = ("STEP_TEXT", "CACHE_KEY", "STEP_TYPE", "CREATED_AT")
+
+#: Marker of the step code tail; the leading newline stays out of the loaded code.
+_STEP_MARKER = "\ndef step("
+
+#: Replace attempts and backoff for a busy target (Windows keeps the file open).
+_REPLACE_ATTEMPTS = 3
+_REPLACE_BACKOFF_SECONDS = 0.1
+
+
+class StepCache:
+    """The repository store of cache steps: addressing, atomic writes and the read-only mode.
+
+    The cache is always read: any structural error of a cache file is a
+    protective miss (``None``), never a failed run — the step is simply
+    regenerated. Writes are best-effort: a read-only cache or a busy target
+    skips the write loudly through the reporter and the run continues.
+
+    Attributes:
+        _root: the cache root from the settings (absolute after ``load_config``).
+        _subdir: the optional subdirectory; part of the address, so steps of
+            different subdirectories never collide.
+        _reporter: the visibility point for the cache events.
+        _writable: the lazily probed writability flag; ``None`` until first use.
+    """
+
+    def __init__(
+        self,
+        config: Config,
+        path: str | None = None,
+        reporter: StepReporter | None = None,
+    ) -> None:
+        """Keep the settings, the optional subdirectory and the reporter.
+
+        Args:
+            config: project settings; the ``cache_root`` setting is the cache root.
+            path: the optional subdirectory inside the cache; ``None`` — shared root.
+            reporter: the visibility point — cache events go through it; a
+                missing reporter falls back to the hook-less default reporter,
+                so construction and saves never crash on it.
+
+        Raises:
+            ValueError: ``path`` is absolute or escapes the cache root.
+        """
+        self._root = Path(config.cache_root)
+        self._subdir = self._validated_subdir(path)
+        self._reporter = reporter if reporter is not None else StepReporter(hooks=[])
+        self._writable: bool | None = None
+
+    @property
+    def root(self) -> str:
+        """Return the effective cache root."""
+        return str(self._root)
+
+    @property
+    def writable(self) -> bool:
+        """Return whether the cache directory accepts writes.
+
+        Probed lazily once: the target directory is created (parents included)
+        and checked with ``os.access``; any ``OSError`` counts as read-only.
+        """
+        if self._writable is None:
+            try:
+                target_dir = self._target_dir()
+                target_dir.mkdir(parents=True, exist_ok=True)
+                self._writable = os.access(target_dir, os.W_OK)
+            except OSError:
+                self._writable = False
+
+        return self._writable
+
+    def load(self, identity: StepIdentity) -> CachedStep | None:
+        """Load the cached step by address; any structural damage is a miss, not a failure.
+
+        Args:
+            identity: the address of the step.
+
+        Returns:
+            The cached step, or ``None`` when the file is missing, damaged, or
+            its metadata does not match the address.
+        """
+        target = self._target_dir() / identity.filename
+        if not target.exists():
+            return None
+
+        try:
+            text = target.read_text(encoding="utf-8")
+            fields = _parse_header(text)
+
+            marker = text.find(_STEP_MARKER)
+            if marker == -1:
+                raise KeyError("def step(")
+            code = text[marker + 1 :]
+
+            if fields["CACHE_KEY"] != identity.cache_key or fields["STEP_TYPE"] != identity.step_type:
+                return None
+            if fields["STEP_TEXT"] != identity.normalized_text:
+                return None
+
+            return CachedStep(identity=identity, code=code, created_at=fields["CREATED_AT"])
+        except (ValueError, SyntaxError, KeyError, IndexError, OSError):
+            return None  # cache corruption never cripples the run
+
+    def save(self, step: CachedStep) -> None:
+        """Store the step atomically, best-effort: no write error ever fails the run.
+
+        Args:
+            step: the working step to store.
+        """
+        if not self.writable:
+            self._emit_skipped(step, "read-only cache")
+            return
+
+        body = _serialize(step)
+        try:
+            handle, tmp_name = tempfile.mkstemp(dir=self._target_dir(), prefix=".tmp-", suffix=".py")
+        except OSError:
+            self._emit_skipped(step, "cache target busy")
+            return
+
+        try:
+            with os.fdopen(handle, "w", encoding="utf-8") as tmp_file:
+                tmp_file.write(body)
+                tmp_file.flush()
+                os.fsync(tmp_file.fileno())
+        except (OSError, ValueError):  # ValueError: unencodable text (e.g. surrogates)
+            _remove_quietly(tmp_name)
+            self._emit_skipped(step, "cache target busy")
+            return
+
+        for _ in range(_REPLACE_ATTEMPTS):
+            try:
+                os.replace(tmp_name, self._target_dir() / step.identity.filename)
+                break
+            except PermissionError:
+                time.sleep(_REPLACE_BACKOFF_SECONDS)  # Windows: target busy
+            except (OSError, ValueError):  # ValueError: unencodable address (e.g. surrogates)
+                _remove_quietly(tmp_name)
+                self._emit_skipped(step, "cache target busy")
+                return
+        else:
+            _remove_quietly(tmp_name)
+            self._emit_skipped(step, "cache target busy")
+            return
+
+        self._reporter.emit(
+            "on_cache_saved",
+            {"step_text": step.identity.normalized_text, "filename": step.identity.filename},
+        )
+
+    def _target_dir(self) -> Path:
+        """Return the directory holding the steps of this address."""
+        return self._root / self._subdir if self._subdir else self._root
+
+    @staticmethod
+    def _validated_subdir(path: str | None) -> Path | None:
+        """Return the subdirectory path, rejecting addresses outside the cache root.
+
+        Args:
+            path: the integrator-supplied subdirectory; ``None`` — shared root.
+
+        Returns:
+            The validated relative subdirectory, or ``None`` for the shared root.
+
+        Raises:
+            ValueError: the path is absolute or resolves outside the cache root.
+        """
+        if path is None or path == "":
+            return None
+
+        subdir = Path(path)
+
+        if subdir.is_absolute():
+            raise ValueError(f"cache path must be a subdirectory, got absolute {path!r}")
+        if ".." in subdir.parts:
+            raise ValueError(f"cache path must stay inside the cache root, got {path!r}")
+
+        return subdir
+
+    def _emit_skipped(self, step: CachedStep, reason: str) -> None:
+        """Report a skipped write through the visibility point."""
+        self._reporter.emit(
+            "on_cache_skipped",
+            {"step_text": step.identity.normalized_text, "reason": reason},
+        )
+
+
+def _parse_header(text: str) -> dict[str, str]:
+    """Parse the header constants of a cache file into a field map.
+
+    Args:
+        text: the whole cache file text.
+
+    Returns:
+        The map of the header constants found in the module.
+
+    Raises:
+        SyntaxError: the file is not a parseable Python module.
+        ValueError: a header value is not a literal.
+        KeyError: any of the header constants is missing.
+    """
+    module = ast.parse(text)
+
+    fields: dict[str, str] = {}
+    for node in module.body:
+        if not isinstance(node, ast.Assign) or len(node.targets) != 1:
+            continue
+
+        target = node.targets[0]
+
+        if isinstance(target, ast.Name) and target.id in _HEADER_FIELDS:
+            fields[target.id] = ast.literal_eval(node.value)
+
+    missing = [name for name in _HEADER_FIELDS if name not in fields]
+
+    if missing:
+        raise KeyError(", ".join(missing))
+
+    return fields
+
+
+def _serialize(step: CachedStep) -> str:
+    """Serialize a step into the module text: metadata literals first, then the code.
+
+    Args:
+        step: the step to serialize.
+
+    Returns:
+        The text of a valid Python module carrying the step.
+    """
+    header = "".join(
+        f"{name} = {value!r}\n"
+        for name, value in (
+            ("STEP_TEXT", step.identity.normalized_text),
+            ("CACHE_KEY", step.identity.cache_key),
+            ("STEP_TYPE", step.identity.step_type),
+            ("CREATED_AT", step.created_at),
+        )
+    )
+    return header + "\n" + step.code + "\n"
+
+
+def _remove_quietly(path: str) -> None:
+    """Remove a temporary file, ignoring a failure: the write is already skipped."""
+    with contextlib.suppress(OSError):
+        Path(path).unlink()

prettyplay/cache/text.py

@@ -0,0 +1,35 @@
+"""Normalization of step sentences for cache identity and addressing.
+
+The same normalized sentence in the same context is one step: normalization
+erases incidental differences (unicode composition, surrounding and internal
+whitespace runs, letter case) while keeping distinct sentences distinct.
+"""
+
+import re
+import unicodedata
+
+#: Pattern of any whitespace run, collapsed to a single space by :func:`normalize_step_text`.
+_WHITESPACE_RUN = re.compile(r"\s+")
+
+
+def normalize_step_text(text: str) -> str:
+    """Normalize a step sentence for identity and addressing.
+
+    Pipeline: Unicode NFC normalization, trimming of leading and trailing
+    whitespace, collapsing of internal whitespace runs to single spaces,
+    casefold. «Нажать Войти» and «нажать  войти » normalize to the same
+    string; a Russian sentence and its English translation stay different.
+
+    Args:
+        text: the raw step sentence as written by the engineer.
+
+    Returns:
+        The normalized sentence.
+    """
+    normalized = unicodedata.normalize("NFC", text)
+
+    normalized = normalized.strip()
+
+    normalized = _WHITESPACE_RUN.sub(" ", normalized)
+
+    return normalized.casefold()

prettyplay/config/.usages/configuration.md

@@ -0,0 +1,87 @@
+# Project configuration
+
+Domain: prettyplay settings. Audience: integrators configuring a test project and CI.
+
+The immutable part of the settings lives in the [tool.prettyplay] section of pyproject.toml. Load it once per test; a test can additionally override specific values programmatically through PrettyConfig.
+
+```toml
+[tool.prettyplay]
+provider = "openai"
+browser = "chromium"
+headless = true             # false — run with a visible window
+model = "gpt-5"
+generation_model = ""      # optional: empty -> model
+classification_model = ""  # optional: empty -> model
+base_url = ""
+cache_root = ""            # empty -> <repo>/.prettyplay/cache/
+generation_attempts = 3
+healing_attempts = 2
+send_screenshots = false
+generation_prompt = ""     # user instructions for generation requests; empty -> no instructions block
+browser_endpoint = ""      # ws endpoint of a remote browser; empty -> local launch
+```
+
+## Environment overrides
+
+Every setting has an override for CI — env variable PRETTYPLAY_<SETTING> in upper case:
+
+| Setting | Env override |
+|---|---|
+| provider | PRETTYPLAY_PROVIDER |
+| browser | PRETTYPLAY_BROWSER_NAME |
+| headless | PRETTYPLAY_BROWSER_HEADLESS |
+| model | PRETTYPLAY_MODEL |
+| generation_model | PRETTYPLAY_GENERATION_MODEL |
+| classification_model | PRETTYPLAY_CLASSIFICATION_MODEL |
+| base_url | PRETTYPLAY_BASE_URL |
+| cache_root | PRETTYPLAY_CACHE_ROOT |
+| generation_attempts | PRETTYPLAY_GENERATION_ATTEMPTS |
+| healing_attempts | PRETTYPLAY_HEALING_ATTEMPTS |
+| send_screenshots | PRETTYPLAY_SEND_SCREENSHOTS |
+| generation_prompt | PRETTYPLAY_GENERATION_PROMPT |
+| browser_endpoint | PRETTYPLAY_BROWSER_ENDPOINT |
+
+## Per-test overrides — layered merge
+
+PrettyConfig is the public name of the full settings model. A config passed to the test object carries only the explicitly set values; everything else resolves from pyproject+env:
+
+```python
+from prettyplay import PrettyTest, PrettyConfig
+
+test = PrettyTest(
+    cache_key="login-flow",
+    config=PrettyConfig(
+        browser="firefox",
+        browser_endpoint="ws://ci-grid:3000/playwright/firefox",
+    ),
+)
+```
+
+- An explicitly set field wins over pyproject+env; a field left at its default (an empty string) falls back to the file layer
+- File values you did not touch survive: base_url and model set only in pyproject.toml keep working when a config is passed
+- One model — one place of validation: file and programmatic values validate identically
+
+## Browsers
+
+The browser matrix: chromium, firefox, webkit (Playwright-bundled engines) plus chrome and msedge — channels that launch the locally installed browser through the chromium engine. A channel requires the real browser installed on the machine; a missing browser fails loudly with an actionable message.
+
+## Remote execution
+
+A non-empty browser_endpoint switches the test to connecting over the Playwright ws endpoint — a Playwright Server or a hosted browser grid. The endpoint is an address, not a secret: it is valid in the config file; CI rotation goes through the env override. An empty endpoint keeps the local launch; headless does not apply to a connect — window visibility is controlled by the endpoint server.
+
+## Rules
+
+- LLM API keys are never stored in the config file — secrets come only from environment variables: OPENAI_API_KEY for openai, ANTHROPIC_API_KEY for anthropic
+- Invalid configuration fails loudly: ConfigurationError names the setting, the received value and the allowed values; the raw pydantic error stays chained for debugging
+- The provider set: openai, anthropic
+- A non-empty browser_endpoint must be a valid ws/wss URL
+- The cache root default: <repo root>/.prettyplay/cache/ — resolved from the located pyproject.toml
+
+## Loading
+
+```python
+from prettyplay.config import load_config
+
+config = load_config(pyproject_path=None)  # locates pyproject.toml upwards from the current directory
+print(config.browser, config.headless, config.generation_attempts)
+```

prettyplay/config/CODEMANIFEST

@@ -0,0 +1,132 @@
+Imports:
+  - Types:
+      - PrettyplayError
+    Usages:
+      - taxonomy
+    From: prettyplay/failures
+
+Usages:
+  conventions: .goga/usages/conventions.md
+  pydantic: .goga/usages/cooks/pydantic.md
+
+Annotations: |
+  Use `conventions` for code writing rules and testing.
+  Use `pydantic` for data models and TOML loading.
+  Use `taxonomy` from Imports for the failure base the configuration error joins.
+
+  All data models — pydantic v2, kw_only=True, empty defaults (None only for explicit absence).
+  Naming: PascalCase for classes; snake_case for functions, methods, properties.
+  Type hints mandatory; no *args/**kwargs; generics parameterized.
+  A validation failure never surfaces as a raw pydantic error: the loader wraps it into the loud actionable `ConfigurationError`.
+  Layered resolution: a value passed programmatically wins over the pyproject+env layer only when explicitly set; empty string means unset for string fields. One model — one place of validation — file and programmatic values validate identically. `Config` is publicly known as PrettyConfig.
+
+---
+
+"PrettyplayError::ConfigurationError(message: str)":
+  location: loader.py
+  annotations: |
+    An invalid prettyplay configuration: the loaded [tool.prettyplay] section failed validation.
+
+    `message`: the rendered actionable text — one line per invalid setting: the setting name, the received value, the allowed values or range.
+
+    Requirements:
+    - Raised by `load_config` with the original pydantic ValidationError chained
+    - Catchable with the single library except clause: derives from `PrettyplayError` (see `taxonomy` from Imports)
+    - Never carries a verdict: a configuration failure is not a step failure
+  properties:
+    "message -> str": |
+      The rendered actionable validation text.
+
+"Config(provider: str, browser: str, model: str, generation_model: str, classification_model: str, base_url: str, cache_root: str, generation_prompt: str, browser_endpoint: str, generation_attempts: int, healing_attempts: int, send_screenshots: bool, headless: bool)":
+  location: models.py
+  annotations: |
+    Validated project settings — the single source of the immutable configuration part.
+
+    `provider`: the LLM provider of the {openai, anthropic} set; default openai.
+    `browser`: browser of the {chromium, firefox, webkit, chrome, msedge} set; chrome and msedge launch the locally installed browser through the driver channel mechanism; default chromium.
+    `model`: main LLM model name.
+    `generation_model`: optional generation override; empty — fallback to `model`.
+    `classification_model`: optional classification override; empty — fallback to `model`.
+    `base_url`: optional custom LLM API endpoint.
+    `cache_root`: cache root; empty — default <repo root>/.prettyplay/cache/ resolved by `load_config`.
+    `generation_prompt`: user instructions for generation requests; non-empty — a separate USER INSTRUCTIONS block in generation and regeneration requests; empty — no block; default empty.
+    `browser_endpoint`: ws endpoint of a remote browser; empty — local launch; default empty.
+    `generation_attempts`: generation attempt budget per step per test; default 3.
+    `healing_attempts`: healing attempt budget per step per test; default 2.
+    `send_screenshots`: optional screenshot input to the LLM; default False.
+    `headless`: run the browser without a visible window of a local launch; default True.
+
+    Requirements:
+    - kw_only construction; every field has an empty default
+    - provider validated against {openai, anthropic}; browser against the five-value set; invalid value — loud actionable error
+    - attempts are positive integers
+    - a non-empty browser_endpoint is a valid ws/wss URL — otherwise a loud actionable error
+
+    Constraints:
+    - No secret values in fields: LLM API keys are never stored in the config; keys come only from environment variables
+  properties:
+    "provider -> str": |
+      The LLM provider setting: openai or anthropic.
+    "browser -> str": |
+      The browser setting of the {chromium, firefox, webkit, chrome, msedge} set.
+    "model -> str": |
+      The main LLM model name.
+    "generation_model -> str": |
+      The optional generation model override.
+    "classification_model -> str": |
+      The optional classification model override.
+    "base_url -> str": |
+      The optional custom LLM API endpoint.
+    "cache_root -> str": |
+      The cache root; empty means the default resolved at load.
+    "generation_prompt -> str": |
+      The user instructions for generation requests; empty means no instructions block.
+    "browser_endpoint -> str": |
+      The ws endpoint of a remote browser; empty means the local launch.
+    "generation_attempts -> int": |
+      The generation attempt budget per step per test.
+    "healing_attempts -> int": |
+      The healing attempt budget per step per test.
+    "send_screenshots -> bool": |
+      Whether screenshots are attached to LLM requests.
+    "headless -> bool": |
+      Whether the browser runs without a visible window of a local launch; ignored on a remote connect.
+    "effective_generation_model -> str": |
+      generation_model when non-empty, otherwise model.
+    "effective_classification_model -> str": |
+      classification_model when non-empty, otherwise model.
+
+"load_config(pyproject_path: str | None, overrides: Config | None) -> config: Config":
+  location: loader.py
+  annotations: |
+    Load project configuration from pyproject.toml with environment overrides and explicit per-test values.
+
+    `pyproject_path`: optional explicit path to pyproject.toml; empty — the first pyproject.toml found upwards from the current directory.
+    `overrides`: the programmatically passed values — the same full model; None — no programmatic layer, the file layer resolves everything.
+    `config`: fully resolved and validated `Config`.
+
+    Algorithm:
+    1. Resolve the pyproject.toml path: given `pyproject_path` or the first match found upwards from the current directory
+    2. Parse TOML: stdlib tomllib on Python 3.11+, tomli on 3.10 (see `pydantic`)
+    3. Extract the tool.prettyplay section; a missing section is an empty section
+    4. Apply environment overrides: each setting is overridden by PRETTYPLAY_<SETTING_UPPERCASE> when the variable is set; the browser override is PRETTYPLAY_BROWSER_NAME, the headless override is PRETTYPLAY_BROWSER_HEADLESS
+    5. Construct `Config`; on a validation failure render the actionable text — one line per invalid setting: the setting name, the received value, the allowed values — and raise `ConfigurationError` with the original ValidationError chained
+    6. `overrides` is None — return the file layer as is
+    7. Overlay the explicitly set fields of `overrides` onto the file layer (the model with empty defaults, model_copy — see `pydantic`): a field participates when it was passed at construction and is non-empty for strings; untouched model defaults never overwrite file values
+    8. Return the effective `Config`
+
+    Requirements:
+    - An env override exists for every setting of `Config` (including PRETTYPLAY_GENERATION_PROMPT and PRETTYPLAY_BROWSER_ENDPOINT)
+    - A raw pydantic.ValidationError never leaves the loader
+    - The empty cache_root setting is resolved to the absolute default <repo root>/.prettyplay/cache/ at load
+
+    Constraints:
+    - Never read or store LLM API keys from any file; keys come only from environment variables
+    - Python 3.10 compatibility via the tomli fallback (see `pydantic`)
+
+---
+
+Author: Goga
+CreatedAt: 07/09/26
+Description: |
+  Project settings of prettyplay: the validated [tool.prettyplay] schema with the browser channels, the headless mode, the generation instructions and the remote browser endpoint, and the loader with environment overrides, explicit per-test merging and the actionable configuration error.

prettyplay/config/__init__.py

@@ -0,0 +1,6 @@
+"""Facade of the prettyplay.config cell: validated project settings."""
+
+from .loader import ConfigurationError, load_config
+from .models import Config, PrettyConfig
+
+__all__ = ["Config", "ConfigurationError", "PrettyConfig", "load_config"]