weakincentives 0.9.0__py3-none-any.whl

weakincentives/prompt/overrides/versioning.py

@@ -0,0 +1,269 @@
+# 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
+from dataclasses import dataclass, field
+from hashlib import sha256
+from typing import Literal, Protocol, TypeVar, overload
+
+from ...serde.schema import schema
+from .._types import SupportsDataclass
+
+
+def _section_override_mapping_factory() -> dict[tuple[str, ...], SectionOverride]:
+    return {}
+
+
+def _tool_override_mapping_factory() -> dict[str, ToolOverride]:
+    return {}
+
+
+def _param_description_mapping_factory() -> dict[str, str]:
+    return {}
+
+
+class ToolContractProtocol(Protocol):
+    name: str
+    description: str
+    params_type: type[SupportsDataclass]
+    result_type: type[SupportsDataclass]
+    result_container: Literal["object", "array"]
+    accepts_overrides: bool
+
+
+class SectionLike(Protocol):
+    def original_body_template(self) -> str | None: ...
+
+    def tools(self) -> tuple[ToolContractProtocol, ...]: ...
+
+    accepts_overrides: bool
+
+
+class SectionNodeLike(Protocol):
+    path: tuple[str, ...]
+    section: SectionLike
+
+
+class PromptLike(Protocol):
+    ns: str
+    key: str
+
+    @property
+    def sections(self) -> tuple[SectionNodeLike, ...]: ...
+
+
+_HEX_DIGEST_RE = re.compile(r"^[0-9a-f]{64}$")
+
+_HexDigestT = TypeVar("_HexDigestT", bound="HexDigest")
+
+
+class HexDigest(str):
+    """A validated lowercase hexadecimal SHA-256 digest."""
+
+    __slots__ = ()
+
+    def __new__(cls: type[_HexDigestT], value: object) -> _HexDigestT:
+        if not isinstance(value, str):
+            msg = "HexDigest value must be a string."
+            raise TypeError(msg)
+        if not _HEX_DIGEST_RE.fullmatch(value):
+            msg = f"Invalid hex digest value: {value!r}"
+            raise ValueError(msg)
+        return str.__new__(cls, value)
+
+
+@overload
+def ensure_hex_digest(value: HexDigest, *, field_name: str) -> HexDigest: ...
+
+
+@overload
+def ensure_hex_digest(value: str, *, field_name: str) -> HexDigest: ...
+
+
+def ensure_hex_digest(value: object, *, field_name: str) -> HexDigest:
+    """Normalize an object to a :class:`HexDigest` with helpful errors."""
+
+    if isinstance(value, HexDigest):
+        return value
+    if isinstance(value, str):
+        try:
+            return HexDigest(value)
+        except ValueError as error:
+            msg = f"{field_name} must be a 64 character lowercase hex digest."
+            raise PromptOverridesError(msg) from error
+    msg = f"{field_name} must be a string."
+    raise PromptOverridesError(msg)
+
+
+@dataclass(slots=True)
+class SectionDescriptor:
+    """Hash metadata for a single section within a prompt."""
+
+    path: tuple[str, ...]
+    content_hash: HexDigest
+
+
+@dataclass(slots=True)
+class ToolDescriptor:
+    """Stable metadata describing a tool exposed by a prompt."""
+
+    path: tuple[str, ...]
+    name: str
+    contract_hash: HexDigest
+
+
+@dataclass(slots=True)
+class PromptDescriptor:
+    """Stable metadata describing a prompt and its hash-aware sections."""
+
+    ns: str
+    key: str
+    sections: list[SectionDescriptor]
+    tools: list[ToolDescriptor]
+
+    @classmethod
+    def from_prompt(cls, prompt: PromptLike) -> PromptDescriptor:
+        sections: list[SectionDescriptor] = []
+        tools: list[ToolDescriptor] = []
+        for node in prompt.sections:
+            if getattr(node.section, "accepts_overrides", True):
+                template = node.section.original_body_template()
+                if template is not None:
+                    content_hash = hash_text(template)
+                    sections.append(SectionDescriptor(node.path, content_hash))
+            tool_descriptors = [
+                ToolDescriptor(
+                    path=node.path,
+                    name=tool.name,
+                    contract_hash=_tool_contract_hash(tool),
+                )
+                for tool in node.section.tools()
+                if tool.accepts_overrides
+            ]
+            tools.extend(tool_descriptors)
+        return cls(prompt.ns, prompt.key, sections, tools)
+
+
+@dataclass(slots=True)
+class SectionOverride:
+    """Override payload for a prompt section validated by hash."""
+
+    expected_hash: HexDigest
+    body: str
+
+
+@dataclass(slots=True)
+class ToolOverride:
+    """Description overrides validated against a tool contract hash."""
+
+    name: str
+    expected_contract_hash: HexDigest
+    description: str | None = None
+    param_descriptions: dict[str, str] = field(
+        default_factory=_param_description_mapping_factory
+    )
+
+
+@dataclass(slots=True)
+class PromptOverride:
+    """Runtime replacements for prompt sections validated by an overrides store."""
+
+    ns: str
+    prompt_key: str
+    tag: str
+    sections: dict[tuple[str, ...], SectionOverride] = field(
+        default_factory=_section_override_mapping_factory
+    )
+    tool_overrides: dict[str, ToolOverride] = field(
+        default_factory=_tool_override_mapping_factory
+    )
+
+
+class PromptOverridesError(Exception):
+    """Raised when prompt overrides fail validation or persistence."""
+
+
+class PromptOverridesStore(Protocol):
+    """Lookup interface for resolving prompt overrides at render time."""
+
+    def resolve(
+        self,
+        descriptor: PromptDescriptor,
+        tag: str = "latest",
+    ) -> PromptOverride | None: ...
+
+    def upsert(
+        self,
+        descriptor: PromptDescriptor,
+        override: PromptOverride,
+    ) -> PromptOverride: ...
+
+    def delete(
+        self,
+        *,
+        ns: str,
+        prompt_key: str,
+        tag: str,
+    ) -> None: ...
+
+    def seed_if_necessary(
+        self,
+        prompt: PromptLike,
+        *,
+        tag: str = "latest",
+    ) -> PromptOverride: ...
+
+
+__all__ = [
+    "HexDigest",
+    "PromptDescriptor",
+    "PromptOverride",
+    "PromptOverridesError",
+    "PromptOverridesStore",
+    "SectionDescriptor",
+    "SectionOverride",
+    "ToolDescriptor",
+    "ToolOverride",
+    "ensure_hex_digest",
+]
+
+
+def _tool_contract_hash(tool: ToolContractProtocol) -> HexDigest:
+    description_hash = hash_text(tool.description)
+    params_schema_hash = hash_json(schema(tool.params_type, extra="forbid"))
+    if getattr(tool, "result_container", "object") == "array":
+        item_schema = schema(tool.result_type, extra="ignore")
+        result_schema = {
+            "title": f"{tool.result_type.__name__}List",
+            "type": "array",
+            "items": item_schema,
+        }
+    else:
+        result_schema = schema(tool.result_type, extra="ignore")
+    result_schema_hash = hash_json(result_schema)
+    return hash_text(
+        "::".join((description_hash, params_schema_hash, result_schema_hash))
+    )
+
+
+def hash_text(value: str) -> HexDigest:
+    return HexDigest(sha256(value.encode("utf-8")).hexdigest())
+
+
+def hash_json(value: object) -> HexDigest:
+    canonical = json.dumps(
+        value, sort_keys=True, separators=(",", ":"), ensure_ascii=True
+    )
+    return hash_text(canonical)

weakincentives/prompt/prompt.py

@@ -0,0 +1,353 @@
+# 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
+
+from collections.abc import Mapping, Sequence
+from dataclasses import is_dataclass
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    ClassVar,
+    Literal,
+    cast,
+    get_args,
+    get_origin,
+)
+
+from ._overrides_protocols import PromptOverridesStoreProtocol
+from ._types import SupportsDataclass
+from .chapter import Chapter, ChaptersExpansionPolicy
+from .errors import PromptValidationError, SectionPath
+from .registry import PromptRegistry, RegistrySnapshot, SectionNode, clone_dataclass
+from .rendering import PromptRenderer, RenderedPrompt
+from .response_format import ResponseFormatParams, ResponseFormatSection
+from .section import Section
+from .structured_output import StructuredOutputConfig
+
+if TYPE_CHECKING:
+    from .overrides import PromptLike, ToolOverride
+
+
+def _format_specialization_argument(argument: object | None) -> str:
+    if argument is None:
+        return "?"
+    if isinstance(argument, type):
+        return argument.__name__
+    return repr(argument)
+
+
+class Prompt[OutputT]:
+    """Coordinate prompt sections and their parameter bindings."""
+
+    _output_container_spec: ClassVar[Literal["object", "array"] | None] = None
+    _output_dataclass_candidate: ClassVar[Any] = None
+
+    def __class_getitem__(cls, item: object) -> type[Prompt[Any]]:
+        origin = get_origin(item)
+        candidate = item
+        container: Literal["object", "array"] | None = "object"
+
+        if origin is list:
+            args = get_args(item)
+            candidate = args[0] if len(args) == 1 else None
+            container = "array"
+            label = f"list[{_format_specialization_argument(candidate)}]"
+        else:
+            container = "object"
+            label = _format_specialization_argument(candidate)
+
+        name = f"{cls.__name__}[{label}]"
+        namespace = {
+            "__module__": cls.__module__,
+            "_output_container_spec": container if candidate is not None else None,
+            "_output_dataclass_candidate": candidate,
+        }
+        return type(name, (cls,), namespace)
+
+    def __init__(
+        self,
+        *,
+        ns: str,
+        key: str,
+        name: str | None = None,
+        sections: Sequence[Section[SupportsDataclass]] | None = None,
+        chapters: Sequence[Chapter[SupportsDataclass]] | None = None,
+        inject_output_instructions: bool = True,
+        allow_extra_keys: bool = False,
+    ) -> None:
+        super().__init__()
+        stripped_ns = ns.strip()
+        if not stripped_ns:
+            raise PromptValidationError("Prompt namespace must be a non-empty string.")
+        stripped_key = key.strip()
+        if not stripped_key:
+            raise PromptValidationError("Prompt key must be a non-empty string.")
+        self.ns = stripped_ns
+        self.key = stripped_key
+        self.name = name
+        base_sections = tuple(sections or ())
+        self._base_sections: tuple[Section[SupportsDataclass], ...] = base_sections
+        self._sections: tuple[Section[SupportsDataclass], ...] = base_sections
+        self._registry = PromptRegistry()
+        self.placeholders: dict[SectionPath, set[str]] = {}
+        self._allow_extra_keys_requested = allow_extra_keys
+
+        seen_chapter_keys: set[str] = set()
+        provided_chapters = tuple(chapters or ())
+        for chapter in provided_chapters:
+            if chapter.key in seen_chapter_keys:
+                raise PromptValidationError(
+                    "Prompt chapters must use unique keys.",
+                    section_path=(chapter.key,),
+                )
+            seen_chapter_keys.add(chapter.key)
+        self._chapters: tuple[Chapter[SupportsDataclass], ...] = provided_chapters
+        self._chapter_key_registry: dict[str, Chapter[SupportsDataclass]] = {
+            chapter.key: chapter for chapter in self._chapters
+        }
+
+        self._structured_output: StructuredOutputConfig[SupportsDataclass] | None
+        self._structured_output = self._resolve_output_spec(allow_extra_keys)
+
+        self.inject_output_instructions = inject_output_instructions
+
+        self._registry.register_sections(self._sections)
+
+        self._response_section: ResponseFormatSection | None = None
+        if self._structured_output is not None:
+            response_params = self._build_response_format_params()
+            response_section = ResponseFormatSection(
+                params=response_params,
+                enabled=lambda _params, prompt=self: prompt.inject_output_instructions,
+            )
+            self._response_section = response_section
+            section_for_registry = cast(Section[SupportsDataclass], response_section)
+            self._sections += (section_for_registry,)
+            self._registry.register_section(
+                section_for_registry, path=(response_section.key,), depth=0
+            )
+
+        snapshot = self._registry.snapshot()
+        self._registry_snapshot: RegistrySnapshot = snapshot
+        self.placeholders = {
+            path: set(names) for path, names in snapshot.placeholders.items()
+        }
+
+        self._renderer: PromptRenderer[OutputT] = PromptRenderer(
+            registry=snapshot,
+            structured_output=self._structured_output,
+            response_section=self._response_section,
+        )
+
+    def render(
+        self,
+        *params: SupportsDataclass,
+        overrides_store: PromptOverridesStoreProtocol | None = None,
+        tag: str = "latest",
+        inject_output_instructions: bool | None = None,
+    ) -> RenderedPrompt[OutputT]:
+        """Render the prompt and apply overrides when an overrides store is supplied."""
+
+        overrides: dict[SectionPath, str] | None = None
+        tool_overrides: dict[str, ToolOverride] | None = None
+
+        if overrides_store is not None:
+            from .overrides import PromptDescriptor
+
+            descriptor = PromptDescriptor.from_prompt(cast("PromptLike", self))
+            override = overrides_store.resolve(descriptor=descriptor, tag=tag)
+
+            if override is not None:
+                overrides = {
+                    path: section_override.body
+                    for path, section_override in override.sections.items()
+                }
+                tool_overrides = dict(override.tool_overrides)
+
+        param_lookup = self._renderer.build_param_lookup(params)
+        return self._renderer.render(
+            param_lookup,
+            overrides,
+            tool_overrides,
+            inject_output_instructions=inject_output_instructions,
+        )
+
+    @property
+    def sections(self) -> tuple[SectionNode[SupportsDataclass], ...]:
+        return self._registry_snapshot.sections
+
+    @property
+    def param_types(self) -> set[type[SupportsDataclass]]:
+        return self._registry_snapshot.param_types
+
+    @property
+    def structured_output(self) -> StructuredOutputConfig[SupportsDataclass] | None:
+        """Resolved structured output declaration, when present."""
+
+        return self._structured_output
+
+    @property
+    def chapters(self) -> tuple[Chapter[SupportsDataclass], ...]:
+        return self._chapters
+
+    def expand_chapters(
+        self,
+        policy: ChaptersExpansionPolicy,
+        *,
+        chapter_params: Mapping[str, SupportsDataclass | None] | None = None,
+    ) -> Prompt[OutputT]:
+        """Return a prompt snapshot with chapters opened per the supplied policy."""
+
+        if not self._chapters:
+            return self
+
+        if policy is ChaptersExpansionPolicy.ALL_INCLUDED:
+            return self._expand_chapters_all_included(
+                chapter_params=chapter_params or {}
+            )
+
+        raise NotImplementedError(
+            f"Chapters expansion policy '{policy.value}' is not supported."
+        )
+
+    def _expand_chapters_all_included(
+        self,
+        *,
+        chapter_params: Mapping[str, SupportsDataclass | None],
+    ) -> Prompt[OutputT]:
+        provided_lookup = dict(chapter_params)
+        unknown_keys = set(provided_lookup) - set(self._chapter_key_registry.keys())
+        if unknown_keys:
+            unknown_key = sorted(unknown_keys)[0]
+            raise PromptValidationError(
+                "Chapter parameters reference unknown chapter key.",
+                section_path=(unknown_key,),
+            )
+
+        open_sections: list[Section[SupportsDataclass]] = list(self._base_sections)
+
+        for chapter in self._chapters:
+            key_present = chapter.key in provided_lookup
+            params = provided_lookup.get(chapter.key)
+            if key_present:
+                params = self._normalize_chapter_params(chapter, params)
+            elif chapter.default_params is not None:
+                params = clone_dataclass(chapter.default_params)
+
+            if chapter.enabled is not None:
+                if params is None and chapter.param_type is not None:
+                    raise PromptValidationError(
+                        "Chapter requires parameters for enabled predicate.",
+                        section_path=(chapter.key,),
+                        dataclass_type=chapter.param_type,
+                    )
+                try:
+                    enabled = chapter.is_enabled(params)
+                except Exception as error:
+                    raise PromptValidationError(
+                        "Chapter enabled predicate failed.",
+                        section_path=(chapter.key,),
+                        dataclass_type=chapter.param_type,
+                    ) from error
+                if not enabled:
+                    continue
+
+            open_sections.extend(chapter.sections)
+
+        prompt_cls = type(self)
+
+        return prompt_cls(
+            ns=self.ns,
+            key=self.key,
+            name=self.name,
+            sections=open_sections,
+            chapters=(),
+            inject_output_instructions=self.inject_output_instructions,
+            allow_extra_keys=self._allow_extra_keys_requested,
+        )
+
+    def _normalize_chapter_params(
+        self,
+        chapter: Chapter[SupportsDataclass],
+        params: SupportsDataclass | None,
+    ) -> SupportsDataclass | None:
+        params_type = chapter.param_type
+        if params_type is None:
+            if params is not None:
+                raise PromptValidationError(
+                    "Chapter does not accept parameters.",
+                    section_path=(chapter.key,),
+                )
+            return None
+
+        if params is None:
+            raise PromptValidationError(
+                "Chapter requires parameters.",
+                section_path=(chapter.key,),
+                dataclass_type=params_type,
+            )
+        return params
+
+    def _resolve_output_spec(
+        self, allow_extra_keys: bool
+    ) -> StructuredOutputConfig[SupportsDataclass] | None:
+        candidate = getattr(type(self), "_output_dataclass_candidate", None)
+        container = cast(
+            Literal["object", "array"] | None,
+            getattr(type(self), "_output_container_spec", None),
+        )
+
+        if candidate is None or container is None:
+            return None
+
+        if not isinstance(candidate, type):
+            candidate_type = cast(type[Any], type(candidate))
+            raise PromptValidationError(
+                "Prompt output type must be a dataclass.",
+                dataclass_type=candidate_type,
+            )
+
+        if not is_dataclass(candidate):
+            bad_dataclass = cast(type[Any], candidate)
+            raise PromptValidationError(
+                "Prompt output type must be a dataclass.",
+                dataclass_type=bad_dataclass,
+            )
+
+        dataclass_type = cast(type[SupportsDataclass], candidate)
+        return StructuredOutputConfig(
+            dataclass_type=dataclass_type,
+            container=container,
+            allow_extra_keys=allow_extra_keys,
+        )
+
+    def _build_response_format_params(self) -> ResponseFormatParams:
+        spec = self._structured_output
+        if spec is None:
+            raise RuntimeError(
+                "Output container missing during response format construction."
+            )
+        container = spec.container
+
+        article: Literal["a", "an"] = (
+            "an" if container.startswith(("a", "e", "i", "o", "u")) else "a"
+        )
+        extra_clause = "." if spec.allow_extra_keys else ". Do not add extra keys."
+        return ResponseFormatParams(
+            article=article,
+            container=container,
+            extra_clause=extra_clause,
+        )
+
+
+__all__ = ["Prompt", "RenderedPrompt", "SectionNode"]