patchahead 0.3.0__py3-none-any.whl

patchahead/ingest/structured.py

@@ -0,0 +1,218 @@
+"""Parsing structured change descriptions (JSON and YAML).
+
+The escape hatch for when release-note prose is not good enough: a user (or a
+future spec-diff tool) states the change explicitly and PatchAhead does no
+guessing. Structured input therefore defaults to ``Confidence.HIGH`` -- the
+uncertainty in the Markdown path is entirely about *reading English*, and that
+uncertainty is absent here.
+
+Schema, as a single change or a list of them under ``changes``::
+
+    {
+      "title":          "Order field renamed",          # required
+      "kind":           "field_rename",                  # required
+      "old_behavior":   "...",
+      "new_behavior":   "...",
+      "migration_hint": "...",
+      "severity":       "high" | "medium" | "low",
+      "confidence":     "high" | "medium" | "low",
+      "target":     {"symbol": "total", "replacement": "amount", "owner": "order",
+                     "owner_explicit": true},
+      "pagination": {"page_param": "page", "total_pages_key": "total_pages", ...},
+      "evidence":   ["quoted line", {"quote": "...", "line": 12, "note": "..."}]
+    }
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+from patchahead.domain.change import (
+    BreakingChange,
+    ChangeKind,
+    Confidence,
+    Evidence,
+    PaginationContract,
+    Severity,
+    SymbolTarget,
+)
+from patchahead.ingest.base import ChangeDocument, ChangeParser, IngestError, register
+
+log = logging.getLogger(__name__)
+
+_VALID_KINDS = ", ".join(sorted(k.value for k in ChangeKind))
+
+
+def _parse_yaml(text: str, path: str) -> Any:
+    try:
+        import yaml
+    except ImportError:  # pragma: no cover - depends on the environment
+        raise IngestError(
+            f"cannot parse {path}: YAML support requires PyYAML "
+            "(pip install 'patchahead[yaml]'). JSON change documents work without it."
+        ) from None
+    try:
+        return yaml.safe_load(text)
+    except Exception as exc:
+        raise IngestError(f"{path} is not valid YAML: {exc}") from exc
+
+
+def _evidence_from(raw: Any) -> list[Evidence]:
+    if not isinstance(raw, list):
+        return []
+    evidence: list[Evidence] = []
+    for item in raw:
+        if isinstance(item, str):
+            evidence.append(Evidence(quote=item))
+        elif isinstance(item, dict):
+            line = item.get("line")
+            evidence.append(
+                Evidence(
+                    quote=str(item.get("quote", "")),
+                    line=int(line) if isinstance(line, int) else None,
+                    note=str(item.get("note", "")),
+                )
+            )
+    return evidence
+
+
+def change_from_mapping(data: dict[str, Any], path: str, source: str) -> BreakingChange:
+    """Build one :class:`BreakingChange` from a mapping, validating as we go."""
+    title = data.get("title")
+    if not isinstance(title, str) or not title.strip():
+        raise IngestError(f"{path}: each change needs a non-empty `title`")
+
+    raw_kind = data.get("kind") or data.get("change_type")
+    if not isinstance(raw_kind, str):
+        raise IngestError(f"{path}: change {title!r} needs a `kind`. One of: {_VALID_KINDS}")
+    try:
+        kind = ChangeKind(raw_kind.strip().lower())
+    except ValueError:
+        raise IngestError(
+            f"{path}: change {title!r} has unknown kind {raw_kind!r}. One of: {_VALID_KINDS}"
+        ) from None
+
+    raw_target = data.get("target") or {}
+    if not isinstance(raw_target, dict):
+        raise IngestError(f"{path}: change {title!r} has a non-mapping `target`")
+    owner = str(raw_target.get("owner", "") or "")
+    explicit = raw_target.get("owner_explicit", True)
+    if not isinstance(explicit, bool):
+        raise IngestError(f"{path}: change {title!r} has a non-boolean `owner_explicit`")
+    target = SymbolTarget(
+        symbol=str(raw_target.get("symbol", "") or ""),
+        replacement=str(raw_target.get("replacement", "") or ""),
+        owner=owner,
+        # Someone typed this into a field named `owner`, which is an assertion
+        # by construction -- a receiver mismatch refuses rather than guessing.
+        # A generator that knows the class but not what callers name its
+        # instance (`api-diff`) writes `"owner_explicit": false` instead.
+        owner_is_explicit=bool(owner) and explicit,
+    )
+
+    raw_pagination = data.get("pagination")
+    if raw_pagination is not None and not isinstance(raw_pagination, dict):
+        raise IngestError(f"{path}: change {title!r} has a non-mapping `pagination`")
+
+    return BreakingChange(
+        title=title.strip(),
+        kind=kind,
+        target=target,
+        old_behavior=str(data.get("old_behavior", "") or ""),
+        new_behavior=str(data.get("new_behavior", "") or ""),
+        migration_hint=str(data.get("migration_hint", "") or ""),
+        severity=Severity.parse(data.get("severity"), Severity.MEDIUM),
+        # Structured input is an explicit assertion by whoever wrote it; take it
+        # at face value unless it says otherwise.
+        confidence=Confidence.parse(data.get("confidence"), Confidence.HIGH),
+        evidence=_evidence_from(data.get("evidence")),
+        pagination=PaginationContract.from_dict(raw_pagination),
+        source=source,
+        classification_reason=str(
+            data.get("classification_reason")
+            or f"declared explicitly as `{kind.value}` in a structured change document"
+        ),
+    )
+
+
+def change_to_mapping(change: BreakingChange) -> dict[str, Any]:
+    """The inverse of :func:`change_from_mapping`: a change as a structured document entry."""
+    entry: dict[str, Any] = {
+        "title": change.title,
+        "kind": change.kind.value,
+        "severity": change.severity.value,
+        "confidence": change.confidence.value,
+        "classification_reason": change.classification_reason,
+    }
+    if change.target.symbol or change.target.owner:
+        entry["target"] = {
+            "symbol": change.target.symbol,
+            "replacement": change.target.replacement,
+            "owner": change.target.owner,
+            "owner_explicit": change.target.owner_is_explicit,
+        }
+    if change.kind is ChangeKind.PAGINATION_PAGE_TO_CURSOR:
+        entry["pagination"] = change.pagination.to_dict()
+    if change.evidence:
+        entry["evidence"] = [
+            {"quote": e.quote, "line": e.line, "note": e.note}
+            if e.line
+            else {"quote": e.quote, "note": e.note}
+            for e in change.evidence
+        ]
+    return entry
+
+
+class StructuredChangeParser(ChangeParser):
+    """Parses JSON and YAML change descriptions."""
+
+    name = "structured"
+    suffixes = (".json", ".yaml", ".yml")
+
+    def supports(self, document: ChangeDocument) -> bool:
+        return document.suffix in self.suffixes
+
+    def parse(self, document: ChangeDocument) -> list[BreakingChange]:
+        if document.suffix == ".json":
+            try:
+                data = json.loads(document.text)
+            except json.JSONDecodeError as exc:
+                raise IngestError(
+                    f"{document.path} is not valid JSON: {exc.msg} "
+                    f"(line {exc.lineno}, column {exc.colno})"
+                ) from exc
+        else:
+            data = _parse_yaml(document.text, document.path)
+
+        if isinstance(data, dict) and "changes" in data:
+            entries = data["changes"]
+        elif isinstance(data, list):
+            entries = data
+        elif isinstance(data, dict):
+            entries = [data]
+        else:
+            raise IngestError(
+                f"{document.path}: expected an object, a list of objects, or an "
+                f"object with a `changes` list; got {type(data).__name__}"
+            )
+
+        if not isinstance(entries, list):
+            raise IngestError(f"{document.path}: `changes` must be a list")
+        if not entries:
+            raise IngestError(f"{document.path}: contains no changes")
+
+        changes = []
+        for entry in entries:
+            if not isinstance(entry, dict):
+                raise IngestError(
+                    f"{document.path}: each change must be an object, got {type(entry).__name__}"
+                )
+            changes.append(change_from_mapping(entry, document.path, self.name))
+
+        log.debug("parsed %s: %d structured change(s)", document.path, len(changes))
+        return changes
+
+
+register(StructuredChangeParser())

patchahead/llm/__init__.py

@@ -0,0 +1,28 @@
+"""Optional LLM assistance. PatchAhead has no runtime dependency on it.
+
+The model is a proposal engine, never the authority: everything it returns is
+structurally checked by :mod:`patchahead.llm.proposer` and then put through the
+same validation gates as a deterministic patch.
+"""
+
+from patchahead.llm.client import (
+    DEFAULT_MODEL,
+    LLMClient,
+    LLMError,
+    LLMResponse,
+    LLMUnavailable,
+    available,
+    model_name,
+)
+from patchahead.llm.proposer import LLMProposer
+
+__all__ = [
+    "DEFAULT_MODEL",
+    "LLMClient",
+    "LLMError",
+    "LLMProposer",
+    "LLMResponse",
+    "LLMUnavailable",
+    "available",
+    "model_name",
+]

patchahead/llm/client.py

@@ -0,0 +1,152 @@
+"""A thin, honest wrapper over the Anthropic API.
+
+Two things this does that the prototype did not:
+
+**It distinguishes failure modes.** The prototype wrapped every call in
+``except Exception: return None``, so a bad API key, a network outage, a
+malformed response, and "the LLM is switched off" were indistinguishable
+(``docs/assessment.md`` §2.6). Here each raises or returns a typed
+:class:`LLMError` with a message a user can act on.
+
+**It never sends more than it was given.** The caller assembles the prompt from
+a named, bounded set of inputs. This module adds nothing, reads no files, and
+logs no prompt content above debug level.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass
+
+log = logging.getLogger(__name__)
+
+#: Default model. Overridable with ``PATCHAHEAD_MODEL``.
+DEFAULT_MODEL = "claude-opus-5"
+DEFAULT_MAX_TOKENS = 8000
+
+
+class LLMError(Exception):
+    """A structured LLM failure. Carries a message meant for the user."""
+
+    def __init__(self, message: str, *, retryable: bool = False) -> None:
+        super().__init__(message)
+        self.retryable = retryable
+
+
+class LLMUnavailable(LLMError):
+    """The LLM path cannot run at all: no SDK, or no credentials."""
+
+
+@dataclass
+class LLMResponse:
+    """A completed model response."""
+
+    text: str
+    model: str
+    input_tokens: int = 0
+    output_tokens: int = 0
+    stop_reason: str = ""
+
+
+def available() -> tuple[bool, str]:
+    """Whether the LLM path can run, and why not if it cannot."""
+    try:
+        import anthropic  # noqa: F401
+    except ImportError:
+        return False, ("the `anthropic` package is not installed (pip install 'patchahead[llm]')")
+    if not (os.environ.get("ANTHROPIC_API_KEY") or os.environ.get("ANTHROPIC_AUTH_TOKEN")):
+        return False, "no ANTHROPIC_API_KEY (or ANTHROPIC_AUTH_TOKEN) is set"
+    return True, ""
+
+
+def model_name() -> str:
+    return os.environ.get("PATCHAHEAD_MODEL", DEFAULT_MODEL)
+
+
+class LLMClient:
+    """Sends one request and returns the text, or raises :class:`LLMError`."""
+
+    def __init__(self, model: str | None = None, max_tokens: int = DEFAULT_MAX_TOKENS) -> None:
+        self.model = model or model_name()
+        self.max_tokens = max_tokens
+        self._client = None
+
+    def _ensure_client(self):
+        if self._client is not None:
+            return self._client
+        ok, reason = available()
+        if not ok:
+            raise LLMUnavailable(reason)
+        import anthropic
+
+        try:
+            self._client = anthropic.Anthropic()
+        except Exception as exc:
+            raise LLMUnavailable(f"could not construct the Anthropic client: {exc}") from exc
+        return self._client
+
+    def complete(self, system: str, user: str) -> LLMResponse:
+        """Send one request. Raises :class:`LLMError` on any failure."""
+        # `_ensure_client` first: it turns a missing package or missing
+        # credentials into an LLMUnavailable the caller can report. Importing
+        # `anthropic` before that check would raise ModuleNotFoundError straight
+        # past every handler in the stack.
+        client = self._ensure_client()
+        import anthropic
+
+        log.debug("llm request: model=%s, %d chars of input", self.model, len(user))
+
+        try:
+            message = client.messages.create(
+                model=self.model,
+                max_tokens=self.max_tokens,
+                system=system,
+                thinking={"type": "adaptive"},
+                messages=[{"role": "user", "content": user}],
+            )
+        except anthropic.AuthenticationError as exc:
+            raise LLMError(f"the Anthropic API rejected the credentials: {exc}") from exc
+        except anthropic.RateLimitError as exc:
+            raise LLMError(f"rate limited by the Anthropic API: {exc}", retryable=True) from exc
+        except anthropic.APIConnectionError as exc:
+            raise LLMError(f"could not reach the Anthropic API: {exc}", retryable=True) from exc
+        except anthropic.APIStatusError as exc:
+            raise LLMError(
+                f"the Anthropic API returned {exc.status_code}: {exc}",
+                retryable=exc.status_code >= 500,
+            ) from exc
+        except Exception as exc:  # unexpected SDK-level failure
+            raise LLMError(f"unexpected error calling the Anthropic API: {exc}") from exc
+
+        if getattr(message, "stop_reason", "") == "refusal":
+            details = getattr(message, "stop_details", None)
+            category = getattr(details, "category", "") if details else ""
+            raise LLMError(
+                "the model declined to answer" + (f" (category: {category})" if category else "")
+            )
+
+        text = "".join(
+            block.text for block in message.content if getattr(block, "type", "") == "text"
+        )
+        if not text.strip():
+            raise LLMError(
+                f"the model returned no text (stop_reason: "
+                f"{getattr(message, 'stop_reason', 'unknown')})"
+            )
+
+        usage = getattr(message, "usage", None)
+        response = LLMResponse(
+            text=text,
+            model=getattr(message, "model", self.model),
+            input_tokens=getattr(usage, "input_tokens", 0) if usage else 0,
+            output_tokens=getattr(usage, "output_tokens", 0) if usage else 0,
+            stop_reason=getattr(message, "stop_reason", "") or "",
+        )
+        log.debug(
+            "llm response: %d in / %d out tokens, stop_reason=%s",
+            response.input_tokens,
+            response.output_tokens,
+            response.stop_reason,
+        )
+        return response