weakincentives 0.9.0__py3-none-any.whl

weakincentives/prompt/markdown.py

@@ -0,0 +1,108 @@
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+import textwrap
+from collections.abc import Callable, Sequence
+from dataclasses import fields, is_dataclass
+from string import Template
+from typing import Any, TypeVar, override
+
+from ._types import SupportsDataclass
+from .errors import PromptRenderError
+from .section import Section
+
+MarkdownParamsT = TypeVar("MarkdownParamsT", bound=SupportsDataclass, covariant=True)
+
+
+class MarkdownSection(Section[MarkdownParamsT]):
+    """Render markdown content using :class:`string.Template`."""
+
+    def __init__(
+        self,
+        *,
+        title: str,
+        template: str,
+        key: str,
+        default_params: MarkdownParamsT | None = None,
+        children: Sequence[Section[SupportsDataclass]] | None = None,
+        enabled: Callable[[SupportsDataclass], bool] | None = None,
+        tools: Sequence[object] | None = None,
+        accepts_overrides: bool = True,
+    ) -> None:
+        self.template = template
+        super().__init__(
+            title=title,
+            key=key,
+            default_params=default_params,
+            children=children,
+            enabled=enabled,
+            tools=tools,
+            accepts_overrides=accepts_overrides,
+        )
+
+    @override
+    def render(self, params: SupportsDataclass | None, depth: int) -> str:
+        return self.render_with_template(self.template, params, depth)
+
+    def render_with_template(
+        self, template_text: str, params: SupportsDataclass | None, depth: int
+    ) -> str:
+        heading_level = "#" * (depth + 2)
+        heading = f"{heading_level} {self.title.strip()}"
+        template = Template(textwrap.dedent(template_text).strip())
+        try:
+            normalized_params = self._normalize_params(params)
+            rendered_body = template.substitute(normalized_params)
+        except KeyError as error:
+            missing = error.args[0]
+            raise PromptRenderError(
+                "Missing placeholder during render.",
+                placeholder=str(missing),
+            ) from error
+        if rendered_body:
+            return f"{heading}\n\n{rendered_body.strip()}"
+        return heading
+
+    @override
+    def placeholder_names(self) -> set[str]:
+        template = Template(textwrap.dedent(self.template).strip())
+        placeholders: set[str] = set()
+        for match in template.pattern.finditer(template.template):
+            named = match.group("named")
+            if named:
+                placeholders.add(named)
+                continue
+            braced = match.group("braced")
+            if braced:
+                placeholders.add(braced)
+        return placeholders
+
+    @staticmethod
+    def _normalize_params(params: SupportsDataclass | None) -> dict[str, Any]:
+        if params is None:
+            return {}
+        if not is_dataclass(params) or isinstance(params, type):
+            raise PromptRenderError(
+                "Section params must be a dataclass instance.",
+                dataclass_type=type(params),
+            )
+
+        return {field.name: getattr(params, field.name) for field in fields(params)}
+
+    @override
+    def original_body_template(self) -> str:
+        return self.template
+
+
+__all__ = ["MarkdownSection"]

weakincentives/prompt/overrides/__init__.py

@@ -0,0 +1,59 @@
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Prompt override infrastructure used by :mod:`weakincentives.prompt`."""
+
+from __future__ import annotations
+
+from .inspection import (
+    OverrideFileMetadata,
+    iter_override_files,
+    resolve_overrides_root,
+)
+from .local_store import LocalPromptOverridesStore
+from .validation import filter_override_for_descriptor
+from .versioning import (
+    HexDigest,
+    PromptDescriptor,
+    PromptLike,
+    PromptOverride,
+    PromptOverridesError,
+    PromptOverridesStore,
+    SectionDescriptor,
+    SectionOverride,
+    ToolDescriptor,
+    ToolOverride,
+    ensure_hex_digest,
+    hash_json,
+    hash_text,
+)
+
+__all__ = [
+    "HexDigest",
+    "LocalPromptOverridesStore",
+    "OverrideFileMetadata",
+    "PromptDescriptor",
+    "PromptLike",
+    "PromptOverride",
+    "PromptOverridesError",
+    "PromptOverridesStore",
+    "SectionDescriptor",
+    "SectionOverride",
+    "ToolDescriptor",
+    "ToolOverride",
+    "ensure_hex_digest",
+    "filter_override_for_descriptor",
+    "hash_json",
+    "hash_text",
+    "iter_override_files",
+    "resolve_overrides_root",
+]

weakincentives/prompt/overrides/_fs.py

@@ -0,0 +1,164 @@
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+import json
+import re
+
+# Bandit false positive: git invocation uses explicit arguments for root
+# discovery.
+import subprocess  # nosec B404
+import tempfile
+from collections.abc import Iterator, Mapping
+from contextlib import contextmanager
+from pathlib import Path
+from threading import RLock
+from typing import Any
+
+from .versioning import PromptOverridesError
+
+_IDENTIFIER_PATTERN = r"^[a-z0-9][a-z0-9._-]{0,63}$"
+
+
+class OverrideFilesystem:
+    """Handle filesystem interactions for prompt overrides."""
+
+    def __init__(
+        self,
+        *,
+        explicit_root: Path | None,
+        overrides_relative_path: Path,
+    ) -> None:
+        super().__init__()
+        self._explicit_root = explicit_root
+        self._overrides_relative_path = overrides_relative_path
+        self._root_lock = RLock()
+        self._root: Path | None = None
+        self._path_locks: dict[Path, RLock] = {}
+        self._path_locks_lock = RLock()
+
+    def resolve_root(self) -> Path:
+        """Resolve the repository root for overrides operations."""
+
+        with self._root_lock:
+            if self._root is not None:
+                return self._root
+            if self._explicit_root is not None:
+                self._root = self._explicit_root
+                return self._root
+
+            git_root = self._git_toplevel()
+            if git_root is not None:
+                self._root = git_root
+                return self._root
+
+            traversal_root = self._walk_to_git_root()
+            if traversal_root is None:
+                raise PromptOverridesError(
+                    "Failed to locate repository root. Provide root_path explicitly."
+                )
+            self._root = traversal_root
+            return self._root
+
+    def overrides_dir(self) -> Path:
+        return self.resolve_root() / self._overrides_relative_path
+
+    def override_file_path(
+        self,
+        *,
+        ns: str,
+        prompt_key: str,
+        tag: str,
+    ) -> Path:
+        segments = self._split_namespace(ns)
+        prompt_component = self.validate_identifier(prompt_key, "prompt key")
+        tag_component = self.validate_identifier(tag, "tag")
+        directory = self.overrides_dir().joinpath(*segments, prompt_component)
+        return directory / f"{tag_component}.json"
+
+    def validate_identifier(self, value: str, label: str) -> str:
+        stripped = value.strip()
+        if not stripped:
+            raise PromptOverridesError(
+                f"{label.capitalize()} must be a non-empty string."
+            )
+        pattern = _IDENTIFIER_PATTERN
+        if not re.fullmatch(pattern, stripped):
+            raise PromptOverridesError(
+                f"{label.capitalize()} must match pattern {pattern}."
+            )
+        return stripped
+
+    @contextmanager
+    def locked_override_path(self, file_path: Path) -> Iterator[None]:
+        lock = self._get_override_path_lock(file_path)
+        with lock:
+            yield
+
+    def atomic_write(self, file_path: Path, payload: Mapping[str, Any]) -> None:
+        directory = file_path.parent
+        directory.mkdir(parents=True, exist_ok=True)
+        with tempfile.NamedTemporaryFile(
+            "w", dir=directory, delete=False, encoding="utf-8"
+        ) as handle:
+            json.dump(payload, handle, indent=2, sort_keys=True)
+            _ = handle.write("\n")
+            temp_name = Path(handle.name)
+        _ = Path(temp_name).replace(file_path)
+
+    def _get_override_path_lock(self, file_path: Path) -> RLock:
+        with self._path_locks_lock:
+            lock = self._path_locks.get(file_path)
+            if lock is None:
+                lock = RLock()
+                self._path_locks[file_path] = lock
+            return lock
+
+    def _split_namespace(self, ns: str) -> tuple[str, ...]:
+        stripped = ns.strip()
+        if not stripped:
+            raise PromptOverridesError("Namespace must be a non-empty string.")
+        segments = tuple(part.strip() for part in stripped.split("/") if part.strip())
+        if not segments:
+            raise PromptOverridesError("Namespace must contain at least one segment.")
+        return tuple(
+            self.validate_identifier(segment, "namespace segment")
+            for segment in segments
+        )
+
+    def _git_toplevel(self) -> Path | None:
+        try:
+            # Bandit false positive: git invocation uses explicit arguments.
+            result = subprocess.run(  # nosec B603 B607
+                ["git", "rev-parse", "--show-toplevel"],
+                check=True,
+                capture_output=True,
+                text=True,
+            )
+        except (FileNotFoundError, subprocess.CalledProcessError):
+            return None
+        path = result.stdout.strip()
+        if not path:
+            return None
+        return Path(path).resolve()
+
+    def _walk_to_git_root(self) -> Path | None:
+        current = Path.cwd().resolve()
+        for candidate in (current, *current.parents):
+            git_dir = candidate / ".git"
+            if git_dir.exists():
+                return candidate
+        return None
+
+
+__all__ = ["OverrideFilesystem"]

weakincentives/prompt/overrides/inspection.py

@@ -0,0 +1,141 @@
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Helpers for inspecting prompt override files on disk."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterator
+from dataclasses import dataclass
+from hashlib import sha256
+from pathlib import Path
+from typing import Any, cast
+
+from .local_store import LocalPromptOverridesStore
+from .versioning import HexDigest, PromptOverridesError
+
+
+@dataclass(frozen=True, slots=True)
+class OverrideFileMetadata:
+    """Summary information about a prompt override file."""
+
+    path: Path
+    relative_segments: tuple[str, ...]
+    modified_time: float
+    content_hash: HexDigest
+    section_count: int
+    tool_count: int
+
+
+class _InspectableLocalStore(LocalPromptOverridesStore):
+    """Expose internal path resolution for read-only inspection helpers."""
+
+    def overrides_dir(self) -> Path:
+        return self._filesystem.overrides_dir()
+
+
+def resolve_overrides_root(
+    *,
+    root_path: str | Path | None = None,
+    overrides_relative_path: str | Path | None = None,
+) -> Path:
+    """Return the directory that stores local prompt overrides."""
+
+    if overrides_relative_path is None:
+        store = _InspectableLocalStore(root_path=root_path)
+    else:
+        store = _InspectableLocalStore(
+            root_path=root_path,
+            overrides_relative_path=overrides_relative_path,
+        )
+    return store.overrides_dir()
+
+
+def iter_override_files(
+    *,
+    overrides_root: Path | None = None,
+    root_path: str | Path | None = None,
+    overrides_relative_path: str | Path | None = None,
+) -> Iterator[OverrideFileMetadata]:
+    """Yield metadata for every JSON override file on disk."""
+
+    root = (
+        overrides_root
+        if overrides_root is not None
+        else resolve_overrides_root(
+            root_path=root_path, overrides_relative_path=overrides_relative_path
+        )
+    ).resolve()
+
+    if not root.exists():
+        return
+
+    for file_path in sorted(root.rglob("*.json")):
+        if not file_path.is_file():
+            continue
+        yield _build_metadata(file_path, root)
+
+
+def _build_metadata(file_path: Path, overrides_root: Path) -> OverrideFileMetadata:
+    try:
+        raw = file_path.read_bytes()
+    except OSError as error:  # pragma: no cover - exercised in practice.
+        raise PromptOverridesError(
+            f"Failed to read override file: {file_path}"
+        ) from error
+
+    try:
+        stat_result = file_path.stat()
+    except OSError as error:  # pragma: no cover - exercised in practice.
+        raise PromptOverridesError(
+            f"Failed to stat override file: {file_path}"
+        ) from error
+
+    try:
+        payload_obj = json.loads(raw.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as error:
+        raise PromptOverridesError(
+            f"Failed to parse prompt override JSON: {file_path}"
+        ) from error
+
+    if not isinstance(payload_obj, dict):
+        raise PromptOverridesError(
+            f"Prompt override payload must be an object: {file_path}"
+        )
+    payload = cast(dict[str, Any], payload_obj)
+
+    sections_obj = payload.get("sections", {})
+    if not isinstance(sections_obj, dict):
+        raise PromptOverridesError(
+            f"Override file sections must be a mapping: {file_path}"
+        )
+    sections = cast(dict[str, Any], sections_obj)
+
+    tools_obj = payload.get("tools", {})
+    if not isinstance(tools_obj, dict):
+        raise PromptOverridesError(
+            f"Override file tools must be a mapping: {file_path}"
+        )
+    tools = cast(dict[str, Any], tools_obj)
+
+    relative_segments = file_path.resolve().relative_to(overrides_root).parts
+    content_hash = HexDigest(sha256(raw).hexdigest())
+
+    return OverrideFileMetadata(
+        path=file_path.resolve(),
+        relative_segments=relative_segments,
+        modified_time=stat_result.st_mtime,
+        content_hash=content_hash,
+        section_count=len(sections),
+        tool_count=len(tools),
+    )