prettyplay 0.0.0__py3-none-any.whl

prettyplay/llm/CODEMANIFEST

@@ -0,0 +1,125 @@
+Imports:
+  - Types:
+      - Config
+    From: prettyplay/config
+  - Types:
+      - LlmUnavailableError
+    From: prettyplay/failures
+
+Usages:
+  conventions: .goga/usages/conventions.md
+  openai: .goga/usages/cooks/openai.md
+  anthropic: .goga/usages/cooks/anthropic.md
+
+Annotations: |
+  Use `conventions` for code writing rules and testing.
+  Use `openai` and `anthropic` for the SDK call patterns and the error mapping of the two providers.
+
+  Provider parity is absolute: both providers expose the same operations, accept the same inputs, return the same output shapes and map failures to the same taxonomy; the provider choice is a configuration decision, never a capability difference.
+  The user instructions input participates in both provider implementations with identical semantics — a parity requirement, not a capability difference.
+  API keys come only from environment variables; never log keys or payloads containing secrets.
+  One completion request per attempt: attempt budgets are owned by the calling engine, never by a provider.
+  Cached step code never depends on the provider: the provider serves generation and classification only.
+
+---
+
+"LlmProvider()":
+  location: provider.py
+  annotations: |
+    The unified LLM port of the library: code generation for a step and failure classification for healing. One contract, two interchangeable implementations selected by configuration.
+  methods:
+    "generate_step_code(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) -> code: str": |
+      Generate step code of the fixed form.
+
+      `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 by the provider implementations verbatim as a separate USER INSTRUCTIONS block of the user content, identically in both.
+      `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 list of 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.
+      `code`: the generated step code of the fixed form, working only through the driver facade; the first markdown-fenced block of the answer is unwrapped — an answer with no closed fence returns verbatim.
+
+      Requirements:
+      - A provider service failure (connectivity, timeout, rate limit, authentication) raises `LlmUnavailableError` naming the provider
+      - The generated code contains no provider-specific constructs
+    "classify_failure(prompt: str, step_text: str, code: str, error: str, snapshot: str, screenshot: bytes | None) -> classification: FailureClassification": |
+      Classify a failed cached step.
+
+      `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.
+      `classification`: the `FailureClassification` verdict.
+
+"LlmProvider::OpenAiProvider(config: Config)":
+  location: openai_provider.py
+  annotations: |
+    The openai SDK implementation of `LlmProvider` (see `openai`).
+
+    `config`: project settings; the generation model is the effective_generation_model of `config`, the classification model is the effective_classification_model of `config`; the base_url setting of `config` overrides the endpoint when set.
+
+    Algorithm (both operations):
+    1. Build the request: the prompt text as the system message, the user content carrying the inputs — a non-empty user_instructions renders as a separate USER INSTRUCTIONS block placed after the page API block, before the regeneration-only blocks (CODE, ERROR)
+    2. Send one completion request via the SDK
+    3. Extract the text answer; a generation answer unwraps its first markdown-fenced block — an unfenced answer passes through verbatim
+    4. An SDK error maps to `LlmUnavailableError` (see `openai`)
+
+"LlmProvider::AnthropicProvider(config: Config)":
+  location: anthropic_provider.py
+  annotations: |
+    The anthropic SDK implementation of `LlmProvider` (see `anthropic`); full parity with the openai implementation.
+
+    `config`: the same settings semantics as the openai implementation.
+
+    Algorithm (both operations):
+    1. Build the request: the prompt text as the system message, the user content carrying the inputs — a non-empty user_instructions renders as a separate USER INSTRUCTIONS block placed after the page API block, before the regeneration-only blocks (CODE, ERROR)
+    2. Send one message request via the SDK
+    3. Extract the text answer; a generation answer unwraps its first markdown-fenced block — an unfenced answer passes through verbatim
+    4. An SDK error maps to `LlmUnavailableError` (see `anthropic`)
+
+"create_provider(config: Config) -> provider: LlmProvider":
+  location: provider.py
+  annotations: |
+    Select and construct the LLM provider from configuration.
+
+    `config`: project settings.
+    `provider`: the selected provider implementation.
+
+    Algorithm:
+    1. Read the provider choice from `config`
+    2. Construct the matching provider implementation with `config`
+    3. Return it
+
+    Requirements:
+    - An unknown provider value fails loudly with an actionable message listing the supported providers
+
+"FailureClassification(category: str, explanation: str, recommendation: str)":
+  location: models.py
+  annotations: |
+    The verdict of a failure classification: what kind of failure it is and what to do about it.
+
+    `category`: one of rot (the UI changed — regeneration is meaningful), product_defect (the expectation legitimately failed), incurable (regeneration cannot help).
+    `explanation`: why the failure got this category.
+    `recommendation`: the recommended engineer action.
+
+    Requirements:
+    - `category` is always one of the three labels
+  properties:
+    "category -> str": |
+      The classification label: rot, product_defect or incurable.
+    "explanation -> str": |
+      Why the failure got this category.
+    "recommendation -> str": |
+      The recommended engineer action.
+
+---
+
+Author: Goga
+CreatedAt: 07/09/26
+Description: |
+  The LLM port of prettyplay: one contract, the openai and anthropic SDK implementations in full parity, and the failure classification verdict.

prettyplay/llm/__init__.py

@@ -0,0 +1,8 @@
+"""Facade of the prettyplay.llm cell: the LLM port and its implementations."""
+
+from .anthropic_provider import AnthropicProvider
+from .models import FailureClassification
+from .openai_provider import OpenAiProvider
+from .provider import LlmProvider, create_provider
+
+__all__ = ["AnthropicProvider", "FailureClassification", "LlmProvider", "OpenAiProvider", "create_provider"]

prettyplay/llm/_request.py

@@ -0,0 +1,216 @@
+"""Shared request-field building for the LLM provider implementations."""
+
+import base64
+import re
+
+from ..failures import LlmUnavailableError
+
+#: The labels a classification category may take.
+CATEGORY_ROT = "rot"
+CATEGORY_PRODUCT_DEFECT = "product_defect"
+CATEGORY_INCURABLE = "incurable"
+
+#: The frozen set of the three classification labels.
+CATEGORIES = frozenset({CATEGORY_ROT, CATEGORY_PRODUCT_DEFECT, CATEGORY_INCURABLE})
+
+#: Field count of the one-line classification verdict.
+VERDICT_FIELD_COUNT = 3
+
+#: A fenced completion block: three backticks, an optional language tag, the body, the closing fence.
+_FENCED_BLOCK = re.compile(r"```[a-zA-Z0-9_+-]*[ \t]*\r?\n(.*?)```", re.DOTALL)
+
+
+def extract_code_block(answer: str) -> str:
+    """Return the step code of a completion, unwrapping the markdown fence.
+
+    Models answer generation requests with a fenced python block even when told
+    to output only code, so the first fenced block of `answer` is the code; an
+    answer with no closed fence is passed through verbatim — an unfenced code
+    answer stays executable, an unparsable one keeps failing downstream.
+
+    Args:
+        answer: the non-empty completion text of a generation request.
+
+    Returns:
+        The code of the fixed form: the body of the first fenced block, or the
+        answer itself when it carries no closed fence.
+    """
+    match = _FENCED_BLOCK.search(answer)
+
+    if match is None:
+        return answer
+
+    return match.group(1)
+
+
+def require_completion_text(text: str | None, provider: str) -> str:
+    """Return the completion text, refusing an empty answer as a service failure.
+
+    Args:
+        text: the raw text extracted from the provider response; ``None`` or an
+            empty string means the service returned no completion body.
+        provider: the provider name for the failure message.
+
+    Returns:
+        The non-empty completion text.
+
+    Raises:
+        LlmUnavailableError: the completion body is missing — a null/empty
+            content is an infrastructure shape, not a step verdict, so it maps
+            to the same taxonomy as any other service failure.
+    """
+    if not text:
+        raise LlmUnavailableError(f"llm unavailable: {provider} returned empty completion")
+
+    return text
+
+
+def build_fields_text(  # noqa: PLR0913, PLR0917 — the parameters mirror the fixed port signature
+    user_instructions: str,
+    step_text: str,
+    previous_steps: list[str],
+    snapshot: str,
+    page_api: str,
+    existing_code: str | None,
+    error: str | None,
+) -> str:
+    """Build the plain-text generation request fields shared by both providers.
+
+    Args:
+        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 after the page API block.
+        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.
+        page_api: the exact page facade surface listing.
+        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 request fields as one text with STEP / PREVIOUS STEPS /
+        PAGE SNAPSHOT / PAGE API sections, the optional USER INSTRUCTIONS
+        section and, on regeneration requests, CODE / ERROR sections.
+    """
+    sections = [
+        f"STEP:\n{step_text}",
+        _format_previous_steps(previous_steps),
+        f"PAGE SNAPSHOT:\n{snapshot}",
+        f"PAGE API:\n{page_api}",
+    ]
+
+    if user_instructions:
+        sections.append(f"USER INSTRUCTIONS:\n{user_instructions}")
+    if existing_code is not None:
+        sections.append(f"CODE:\n{existing_code}")
+    if error is not None:
+        sections.append(f"ERROR:\n{error}")
+
+    return "\n\n".join(sections)
+
+
+def build_classification_fields(step_text: str, code: str, error: str, snapshot: str) -> str:
+    """Build the plain-text classification request fields shared by both providers.
+
+    Args:
+        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.
+
+    Returns:
+        The request fields as one text with STEP / CODE / ERROR / PAGE
+        SNAPSHOT sections.
+    """
+    return "\n\n".join(
+        [
+            f"STEP:\n{step_text}",
+            f"CODE:\n{code}",
+            f"ERROR:\n{error}",
+            f"PAGE SNAPSHOT:\n{snapshot}",
+        ]
+    )
+
+
+def encode_screenshot(screenshot: bytes) -> str:
+    """Encode a PNG screenshot as the base64 payload of a content block.
+
+    Args:
+        screenshot: the raw PNG image bytes of the page.
+
+    Returns:
+        The base64 text of the image.
+    """
+    return base64.b64encode(screenshot).decode("ascii")
+
+
+def openai_user_content(text: str, screenshot: bytes | None) -> str | list[dict]:
+    """Wrap the request fields as an openai user content payload.
+
+    Args:
+        text: the plain-text request fields shared with the anthropic provider.
+        screenshot: an optional PNG image of the page; passed only when the
+            project enables screenshots.
+
+    Returns:
+        The plain text when no image is attached, otherwise the openai
+        content block list with the data-URI image block.
+    """
+    if screenshot is None:
+        return text
+
+    return [
+        {"type": "text", "text": text},
+        {
+            "type": "image_url",
+            "image_url": {"url": f"data:image/png;base64,{encode_screenshot(screenshot)}"},
+        },
+    ]
+
+
+def unparsable_classification() -> dict[str, str]:
+    """Return the protective verdict fields for an unparsable provider answer.
+
+    Returns:
+        The incurable fallback verdict fields; both providers construct the
+        same defaults, so the field set is shared.
+    """
+    return {
+        "category": CATEGORY_INCURABLE,
+        "explanation": "classification verdict unparsable",
+        "recommendation": "re-run the step or check the provider answer",
+    }
+
+
+def parse_classification_line(answer: str) -> tuple[str, str, str] | None:
+    """Parse the one-line classification answer of the form ``category | explanation | recommendation``.
+
+    Args:
+        answer: the raw completion text.
+
+    Returns:
+        The stripped (category, explanation, recommendation) triple, or None
+        when the answer is not a line of the expected shape or names no
+        known category — the caller applies the protective default.
+    """
+    line = next((stripped for stripped in (line.strip() for line in answer.splitlines()) if stripped), "")
+    parts = [part.strip() for part in line.split("|")]
+
+    if len(parts) == VERDICT_FIELD_COUNT and parts[0] in CATEGORIES:
+        return parts[0], parts[1], parts[2]
+
+    return None
+
+
+def _format_previous_steps(previous_steps: list[str]) -> str:
+    """Render the scenario context section; an empty history stays explicit."""
+    if not previous_steps:
+        return "PREVIOUS STEPS:\n(none)"
+
+    listed = "\n".join(f"- {sentence}" for sentence in previous_steps)
+
+    return f"PREVIOUS STEPS:\n{listed}"

prettyplay/llm/anthropic_provider.py

@@ -0,0 +1,213 @@
+"""The anthropic SDK implementation of the LlmProvider port."""
+
+import os
+
+from anthropic import Anthropic, AnthropicError
+
+from ..config import Config
+from ..failures import LlmUnavailableError
+from ._request import (
+    build_classification_fields,
+    build_fields_text,
+    encode_screenshot,
+    extract_code_block,
+    parse_classification_line,
+    require_completion_text,
+    unparsable_classification,
+)
+from .models import FailureClassification
+from .provider import LlmProvider
+
+REQUEST_MAX_TOKENS = 1024
+
+
+def _first_text_block(response: object) -> str | None:
+    """Extract the text of the first text block of an anthropic response.
+
+    Args:
+        response: the SDK response of a ``messages.create`` call.
+
+    Returns:
+        The text of the first text content block, or ``None`` when the
+        response carries no text block at all (empty or non-text content).
+    """
+    for block in getattr(response, "content", None) or []:
+        if getattr(block, "type", None) == "text":
+            return getattr(block, "text", None)
+
+    return None
+
+
+class AnthropicProvider(LlmProvider):
+    """The LlmProvider implementation served by the anthropic SDK.
+
+    Full parity with :class:`OpenAiProvider`: 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: Anthropic | None = None
+
+    def _get_client(self) -> Anthropic:
+        """Construct the SDK client on the first request.
+
+        Returns:
+            The lazily constructed anthropic SDK client.
+
+        Raises:
+            LlmUnavailableError: the ANTHROPIC_API_KEY environment variable
+                is missing or empty — generation and healing are blocked.
+        """
+        if self._client is None:
+            api_key = os.environ.get("ANTHROPIC_API_KEY")
+
+            if not api_key:
+                raise LlmUnavailableError("llm unavailable: anthropic: ANTHROPIC_API_KEY is not set")
+
+            self._client = Anthropic(api_key=api_key, base_url=self._config.base_url or None)
+        return self._client
+
+    def _user_content(self, text: str, screenshot: bytes | None) -> str | list[dict]:
+        """Wrap the request fields as an anthropic user content payload.
+
+        Args:
+            text: the plain-text request fields shared with the openai provider.
+            screenshot: an optional PNG image of the page; passed only when
+                the project enables screenshots.
+
+        Returns:
+            The plain text when no image is attached, otherwise the
+            anthropic content block list with the base64 image block.
+        """
+        if screenshot is None:
+            return text
+
+        return [
+            {"type": "text", "text": text},
+            {
+                "type": "image",
+                "source": {
+                    "type": "base64",
+                    "media_type": "image/png",
+                    "data": encode_screenshot(screenshot),
+                },
+            },
+        ]
+
+    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 parameter.
+            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 openai 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)
+
+        try:
+            response = self._get_client().messages.create(
+                model=self._config.effective_generation_model,
+                system=prompt,
+                max_tokens=REQUEST_MAX_TOKENS,
+                messages=[{"role": "user", "content": self._user_content(text, screenshot)}],
+            )
+        except AnthropicError as sdk_error:
+            raise LlmUnavailableError("llm unavailable: anthropic request failed") from sdk_error
+
+        return extract_code_block(require_completion_text(_first_text_block(response), "anthropic"))
+
+    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 parameter.
+            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)
+
+        try:
+            response = self._get_client().messages.create(
+                model=self._config.effective_classification_model,
+                system=prompt,
+                max_tokens=REQUEST_MAX_TOKENS,
+                messages=[{"role": "user", "content": self._user_content(text, screenshot)}],
+            )
+        except AnthropicError as sdk_error:
+            raise LlmUnavailableError("llm unavailable: anthropic request failed") from sdk_error
+
+        answer = require_completion_text(_first_text_block(response), "anthropic")
+        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/models.py

@@ -0,0 +1,22 @@
+"""Models of the prettyplay.llm cell: the failure classification verdict."""
+
+from pydantic import BaseModel, ConfigDict
+
+
+class FailureClassification(BaseModel):
+    """The verdict of a failure classification.
+
+    Says what kind of failure a failed cached step hit and what the engineer
+    should do about it.
+
+    Attributes:
+        category: the classification label: rot, product_defect or incurable.
+        explanation: why the failure got this category.
+        recommendation: the recommended engineer action.
+    """
+
+    model_config = ConfigDict(kw_only=True)
+
+    category: str
+    explanation: str
+    recommendation: str