weakincentives 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

weakincentives/{prompts → prompt}/_types.py

@@ -10,7 +10,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Internal typing helpers for the prompts package."""
+"""Internal typing helpers for the :mod:`weakincentives.prompt` package."""
 
 from __future__ import annotations
 

weakincentives/{prompts/text.py → prompt/markdown.py}

@@ -23,32 +23,39 @@ from .errors import PromptRenderError
 from .section import Section
 
 
-class TextSection[ParamsT: SupportsDataclass](Section[ParamsT]):
-    """Render markdown text content using string.Template."""
+class MarkdownSection[ParamsT: SupportsDataclass](Section[ParamsT]):
+    """Render markdown content using :class:`string.Template`."""
 
     def __init__(
         self,
         *,
         title: str,
-        body: str,
-        defaults: ParamsT | None = None,
+        template: str,
+        key: str,
+        default_params: ParamsT | None = None,
         children: Sequence[object] | None = None,
         enabled: Callable[[ParamsT], bool] | None = None,
         tools: Sequence[object] | None = None,
     ) -> None:
+        self.template = template
         super().__init__(
             title=title,
-            defaults=defaults,
+            key=key,
+            default_params=default_params,
             children=children,
             enabled=enabled,
             tools=tools,
         )
-        self.body = body
 
     def render(self, params: ParamsT, depth: int) -> str:
+        return self.render_with_template(self.template, params, depth)
+
+    def render_with_template(
+        self, template_text: str, params: ParamsT, depth: int
+    ) -> str:
         heading_level = "#" * (depth + 2)
         heading = f"{heading_level} {self.title.strip()}"
-        template = Template(textwrap.dedent(self.body).strip())
+        template = Template(textwrap.dedent(template_text).strip())
         try:
             normalized_params = self._normalize_params(params)
             rendered_body = template.substitute(normalized_params)
@@ -63,7 +70,7 @@ class TextSection[ParamsT: SupportsDataclass](Section[ParamsT]):
         return heading
 
     def placeholder_names(self) -> set[str]:
-        template = Template(textwrap.dedent(self.body).strip())
+        template = Template(textwrap.dedent(self.template).strip())
         placeholders: set[str] = set()
         for match in template.pattern.finditer(template.template):
             named = match.group("named")
@@ -85,5 +92,8 @@ class TextSection[ParamsT: SupportsDataclass](Section[ParamsT]):
 
         return {field.name: getattr(params, field.name) for field in fields(params)}
 
+    def original_body_template(self) -> str:
+        return self.template
+
 
-__all__ = ["TextSection"]
+__all__ = ["MarkdownSection"]

weakincentives/{prompts → prompt}/prompt.py

@@ -12,8 +12,9 @@
 
 from __future__ import annotations
 
-from collections.abc import Callable, Iterator, Sequence
+from collections.abc import Callable, Iterator, Mapping, Sequence
 from dataclasses import dataclass, field, fields, is_dataclass, replace
+from types import MappingProxyType
 from typing import Any, ClassVar, Literal, cast, get_args, get_origin
 
 from ._types import SupportsDataclass
@@ -25,19 +26,25 @@ from .errors import (
 from .response_format import ResponseFormatParams, ResponseFormatSection
 from .section import Section
 from .tool import Tool
+from .versioning import PromptVersionStore, ToolOverride
+
+_EMPTY_TOOL_PARAM_DESCRIPTIONS: Mapping[str, Mapping[str, str]] = MappingProxyType({})
 
 
 @dataclass(frozen=True, slots=True)
-class RenderedPrompt[OutputT = Any]:
+class RenderedPrompt[OutputT]:
     """Rendered prompt text paired with structured output metadata."""
 
     text: str
     output_type: type[Any] | None
-    output_container: Literal["object", "array"] | None
+    container: Literal["object", "array"] | None
     allow_extra_keys: bool | None
     _tools: tuple[Tool[SupportsDataclass, SupportsDataclass], ...] = field(
         default_factory=tuple
     )
+    _tool_param_descriptions: Mapping[str, Mapping[str, str]] = field(
+        default=_EMPTY_TOOL_PARAM_DESCRIPTIONS
+    )
 
     def __str__(self) -> str:  # pragma: no cover - convenience for logging
         return self.text
@@ -48,6 +55,14 @@ class RenderedPrompt[OutputT = Any]:
 
         return self._tools
 
+    @property
+    def tool_param_descriptions(
+        self,
+    ) -> Mapping[str, Mapping[str, str]]:
+        """Description patches keyed by tool name."""
+
+        return self._tool_param_descriptions
+
 
 def _clone_dataclass(instance: SupportsDataclass) -> SupportsDataclass:
     """Return a shallow copy of the provided dataclass instance."""
@@ -64,7 +79,7 @@ def _format_specialization_argument(argument: object | None) -> str:
 
 
 @dataclass(frozen=True, slots=True)
-class PromptSectionNode[ParamsT: SupportsDataclass]:
+class SectionNode[ParamsT: SupportsDataclass]:
     """Flattened view of a section within a prompt."""
 
     section: Section[ParamsT]
@@ -72,7 +87,7 @@ class PromptSectionNode[ParamsT: SupportsDataclass]:
     path: SectionPath
 
 
-class Prompt[OutputT = Any]:
+class Prompt[OutputT]:
     """Coordinate prompt sections and their parameter bindings."""
 
     _output_container_spec: ClassVar[Literal["object", "array"] | None] = None
@@ -103,19 +118,29 @@ class Prompt[OutputT = Any]:
     def __init__(
         self,
         *,
+        ns: str,
+        key: str,
         name: str | None = None,
         sections: Sequence[Section[Any]] | None = None,
         inject_output_instructions: bool = True,
         allow_extra_keys: bool = False,
     ) -> None:
+        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: list[Section[SupportsDataclass]] = [
             cast(Section[SupportsDataclass], section) for section in sections or ()
         ]
         self._sections: tuple[Section[SupportsDataclass], ...] = tuple(base_sections)
-        self._section_nodes: list[PromptSectionNode[SupportsDataclass]] = []
+        self._section_nodes: list[SectionNode[SupportsDataclass]] = []
         self._params_registry: dict[
-            type[SupportsDataclass], list[PromptSectionNode[SupportsDataclass]]
+            type[SupportsDataclass], list[SectionNode[SupportsDataclass]]
         ] = {}
         self._defaults_by_path: dict[SectionPath, SupportsDataclass] = {}
         self._defaults_by_type: dict[type[SupportsDataclass], SupportsDataclass] = {}
@@ -134,7 +159,7 @@ class Prompt[OutputT = Any]:
         self.inject_output_instructions = inject_output_instructions
 
         for section in base_sections:
-            self._register_section(section, path=(section.title,), depth=0)
+            self._register_section(section, path=(section.key,), depth=0)
 
         self._response_section: ResponseFormatSection | None = None
         if self._output_type is not None and self._output_container is not None:
@@ -148,52 +173,68 @@ class Prompt[OutputT = Any]:
             self._sections += (section_for_registry,)
             self._register_section(
                 section_for_registry,
-                path=(response_section.title,),
+                path=(response_section.key,),
                 depth=0,
             )
 
-    def render(self, *params: SupportsDataclass) -> RenderedPrompt[OutputT]:
+    def render(
+        self,
+        *params: SupportsDataclass,
+        inject_output_instructions: bool | None = None,
+    ) -> RenderedPrompt[OutputT]:
         """Render the prompt using provided parameter dataclass instances."""
 
         param_lookup = self._collect_param_lookup(params)
-        rendered_sections: list[str] = []
-        collected_tools: list[Tool[SupportsDataclass, SupportsDataclass]] = []
-
-        for node, section_params in self._iter_enabled_sections(param_lookup):
-            params_type = node.section.params
-            try:
-                rendered = node.section.render(section_params, node.depth)
-            except PromptRenderError as error:
-                if error.section_path and error.dataclass_type:
-                    raise
-                raise PromptRenderError(
-                    error.message,
-                    section_path=node.path,
-                    dataclass_type=params_type,
-                    placeholder=error.placeholder,
-                ) from error
-            except Exception as error:  # pragma: no cover - defensive guard
-                raise PromptRenderError(
-                    "Section rendering failed.",
-                    section_path=node.path,
-                    dataclass_type=params_type,
-                ) from error
-
-            section_tools = node.section.tools()
-            if section_tools:
-                collected_tools.extend(section_tools)
-
-            if rendered:
-                rendered_sections.append(rendered)
+        return self._render_internal(
+            param_lookup,
+            inject_output_instructions=inject_output_instructions,
+        )
 
-        text = "\n\n".join(rendered_sections)
+    def render_with_overrides(
+        self,
+        *params: SupportsDataclass,
+        version_store: PromptVersionStore,
+        tag: str = "latest",
+        inject_output_instructions: bool | None = None,
+    ) -> RenderedPrompt[OutputT]:
+        """Render the prompt using overrides supplied by a version store."""
+
+        from .versioning import PromptDescriptor
+
+        descriptor = PromptDescriptor.from_prompt(self)
+        override = version_store.resolve(descriptor=descriptor, tag=tag)
+
+        overrides: dict[SectionPath, str] = {}
+        tool_overrides: dict[str, ToolOverride] = {}
+        if (
+            override is not None
+            and override.ns == descriptor.ns
+            and override.prompt_key == descriptor.key
+        ):
+            descriptor_index = {
+                section.path: section.content_hash for section in descriptor.sections
+            }
+            for path, body in override.overrides.items():
+                if path in descriptor_index:
+                    overrides[path] = body
+            if override.tool_overrides:
+                descriptor_tool_index = {
+                    tool.name: tool.contract_hash for tool in descriptor.tools
+                }
+                for name, tool_override in override.tool_overrides.items():
+                    descriptor_hash = descriptor_tool_index.get(name)
+                    if (
+                        descriptor_hash is not None
+                        and tool_override.expected_contract_hash == descriptor_hash
+                    ):
+                        tool_overrides[name] = tool_override
 
-        return RenderedPrompt(
-            text=text,
-            output_type=self._output_type,
-            output_container=self._output_container,
-            allow_extra_keys=self._allow_extra_keys,
-            _tools=tuple(collected_tools),
+        param_lookup = self._collect_param_lookup(params)
+        return self._render_internal(
+            param_lookup,
+            overrides,
+            tool_overrides,
+            inject_output_instructions=inject_output_instructions,
         )
 
     def _register_section(
@@ -203,7 +244,7 @@ class Prompt[OutputT = Any]:
         path: SectionPath,
         depth: int,
     ) -> None:
-        params_type = section.params
+        params_type = section.param_type
         if not is_dataclass(params_type):
             raise PromptValidationError(
                 "Section params must be a dataclass.",
@@ -211,14 +252,14 @@ class Prompt[OutputT = Any]:
                 dataclass_type=params_type,
             )
 
-        node: PromptSectionNode[SupportsDataclass] = PromptSectionNode(
+        node: SectionNode[SupportsDataclass] = SectionNode(
             section=section, depth=depth, path=path
         )
         self._section_nodes.append(node)
         self._params_registry.setdefault(params_type, []).append(node)
 
-        if section.defaults is not None:
-            default_value = section.defaults
+        if section.default_params is not None:
+            default_value = section.default_params
             if isinstance(default_value, type) or not is_dataclass(default_value):
                 raise PromptValidationError(
                     "Section defaults must be dataclass instances.",
@@ -250,15 +291,15 @@ class Prompt[OutputT = Any]:
         self._register_section_tools(section, path)
 
         for child in section.children:
-            child_path = path + (child.title,)
+            child_path = path + (child.key,)
             self._register_section(child, path=child_path, depth=depth + 1)
 
     @property
-    def sections(self) -> tuple[PromptSectionNode[SupportsDataclass], ...]:
+    def sections(self) -> tuple[SectionNode[SupportsDataclass], ...]:
         return tuple(self._section_nodes)
 
     @property
-    def params_types(self) -> set[type[SupportsDataclass]]:
+    def param_types(self) -> set[type[SupportsDataclass]]:
         return set(self._params_registry.keys())
 
     def _resolve_output_spec(
@@ -335,12 +376,103 @@ class Prompt[OutputT = Any]:
             lookup[params_type] = value
         return lookup
 
+    def _render_internal(
+        self,
+        param_lookup: Mapping[type[SupportsDataclass], SupportsDataclass],
+        overrides: Mapping[SectionPath, str] | None = None,
+        tool_overrides: Mapping[str, ToolOverride] | None = None,
+        *,
+        inject_output_instructions: bool | None = None,
+    ) -> RenderedPrompt[OutputT]:
+        rendered_sections: list[str] = []
+        collected_tools: list[Tool[SupportsDataclass, SupportsDataclass]] = []
+        override_lookup = dict(overrides or {})
+        tool_override_lookup = dict(tool_overrides or {})
+        field_description_patches: dict[str, dict[str, str]] = {}
+
+        for node, section_params in self._iter_enabled_sections(
+            dict(param_lookup),
+            inject_output_instructions=inject_output_instructions,
+        ):
+            override_body = override_lookup.get(node.path)
+            rendered = self._render_section(node, section_params, override_body)
+
+            section_tools = node.section.tools()
+            if section_tools:
+                for tool in section_tools:
+                    override = tool_override_lookup.get(tool.name)
+                    patched_tool = tool
+                    if override is not None:
+                        if (
+                            override.description is not None
+                            and override.description != tool.description
+                        ):
+                            patched_tool = replace(
+                                tool, description=override.description
+                            )
+                        if override.param_descriptions:
+                            field_description_patches[tool.name] = dict(
+                                override.param_descriptions
+                            )
+                    collected_tools.append(patched_tool)
+
+            if rendered:
+                rendered_sections.append(rendered)
+
+        text = "\n\n".join(rendered_sections)
+
+        return RenderedPrompt(
+            text=text,
+            output_type=self._output_type,
+            container=self._output_container,
+            allow_extra_keys=self._allow_extra_keys,
+            _tools=tuple(collected_tools),
+            _tool_param_descriptions=_freeze_tool_param_descriptions(
+                field_description_patches
+            ),
+        )
+
+    def _render_section(
+        self,
+        node: SectionNode[SupportsDataclass],
+        section_params: SupportsDataclass,
+        override_body: str | None,
+    ) -> str:
+        params_type = node.section.param_type
+        try:
+            render_override = getattr(node.section, "render_with_template", None)
+            if override_body is not None and callable(render_override):
+                override_renderer = cast(
+                    Callable[[str, SupportsDataclass, int], str],
+                    render_override,
+                )
+                rendered = override_renderer(override_body, section_params, node.depth)
+            else:
+                rendered = node.section.render(section_params, node.depth)
+        except PromptRenderError as error:
+            if error.section_path and error.dataclass_type:
+                raise
+            raise PromptRenderError(
+                error.message,
+                section_path=node.path,
+                dataclass_type=params_type,
+                placeholder=error.placeholder,
+            ) from error
+        except Exception as error:  # pragma: no cover - defensive guard
+            raise PromptRenderError(
+                "Section rendering failed.",
+                section_path=node.path,
+                dataclass_type=params_type,
+            ) from error
+
+        return rendered
+
     def _resolve_section_params(
         self,
-        node: PromptSectionNode[SupportsDataclass],
+        node: SectionNode[SupportsDataclass],
         param_lookup: dict[type[SupportsDataclass], SupportsDataclass],
     ) -> SupportsDataclass:
-        params_type = node.section.params
+        params_type = node.section.param_type
         section_params: SupportsDataclass | None = param_lookup.get(params_type)
 
         if section_params is None:
@@ -367,7 +499,9 @@ class Prompt[OutputT = Any]:
     def _iter_enabled_sections(
         self,
         param_lookup: dict[type[SupportsDataclass], SupportsDataclass],
-    ) -> Iterator[tuple[PromptSectionNode[SupportsDataclass], SupportsDataclass]]:
+        *,
+        inject_output_instructions: bool | None = None,
+    ) -> Iterator[tuple[SectionNode[SupportsDataclass], SupportsDataclass]]:
         skip_depth: int | None = None
 
         for node in self._section_nodes:
@@ -378,14 +512,19 @@ class Prompt[OutputT = Any]:
 
             section_params = self._resolve_section_params(node, param_lookup)
 
-            try:
-                enabled = node.section.is_enabled(section_params)
-            except Exception as error:  # pragma: no cover - defensive guard
-                raise PromptRenderError(
-                    "Section enabled predicate failed.",
-                    section_path=node.path,
-                    dataclass_type=node.section.params,
-                ) from error
+            if node.section is self._response_section and (
+                inject_output_instructions is not None
+            ):
+                enabled = inject_output_instructions
+            else:
+                try:
+                    enabled = node.section.is_enabled(section_params)
+                except Exception as error:  # pragma: no cover - defensive guard
+                    raise PromptRenderError(
+                        "Section enabled predicate failed.",
+                        section_path=node.path,
+                        dataclass_type=node.section.param_type,
+                    ) from error
 
             if not enabled:
                 skip_depth = node.depth
@@ -408,7 +547,7 @@ class Prompt[OutputT = Any]:
                 raise PromptValidationError(
                     "Section tools() must return Tool instances.",
                     section_path=path,
-                    dataclass_type=section.params,
+                    dataclass_type=section.param_type,
                 )
             tool: Tool[SupportsDataclass, SupportsDataclass] = cast(
                 Tool[SupportsDataclass, SupportsDataclass], tool_candidate
@@ -437,4 +576,15 @@ class Prompt[OutputT = Any]:
             self._tool_name_registry[tool.name] = path
 
 
-__all__ = ["Prompt", "PromptSectionNode", "RenderedPrompt"]
+__all__ = ["Prompt", "RenderedPrompt", "SectionNode"]
+
+
+def _freeze_tool_param_descriptions(
+    descriptions: Mapping[str, dict[str, str]],
+) -> Mapping[str, Mapping[str, str]]:
+    if not descriptions:
+        return MappingProxyType({})
+    frozen: dict[str, Mapping[str, str]] = {}
+    for name, field_mapping in descriptions.items():
+        frozen[name] = MappingProxyType(dict(field_mapping))
+    return MappingProxyType(frozen)

weakincentives/{prompts → prompt}/response_format.py

@@ -14,9 +14,9 @@ from __future__ import annotations
 
 from collections.abc import Callable
 from dataclasses import dataclass
-from typing import Literal
+from typing import Final, Literal
 
-from .text import TextSection
+from .markdown import MarkdownSection
 
 __all__ = ["ResponseFormatParams", "ResponseFormatSection"]
 
@@ -30,14 +30,16 @@ class ResponseFormatParams:
     extra_clause: str
 
 
-_RESPONSE_FORMAT_BODY = """Return ONLY a single fenced JSON code block. Do not include any text
+_RESPONSE_FORMAT_BODY: Final[
+    str
+] = """Return ONLY a single fenced JSON code block. Do not include any text
 before or after the block.
 
 The top-level JSON value MUST be ${article} ${container} that matches the fields
 of the expected schema${extra_clause}"""
 
 
-class ResponseFormatSection(TextSection[ResponseFormatParams]):
+class ResponseFormatSection(MarkdownSection[ResponseFormatParams]):
     """Internal section that appends JSON-only response instructions."""
 
     def __init__(
@@ -48,7 +50,8 @@ class ResponseFormatSection(TextSection[ResponseFormatParams]):
     ) -> None:
         super().__init__(
             title="Response Format",
-            body=_RESPONSE_FORMAT_BODY,
-            defaults=params,
+            key="response-format",
+            template=_RESPONSE_FORMAT_BODY,
+            default_params=params,
             enabled=enabled,
         )

weakincentives/{prompts → prompt}/section.py

@@ -12,15 +12,20 @@
 
 from __future__ import annotations
 
+import re
 from abc import ABC, abstractmethod
 from collections.abc import Callable, Sequence
-from typing import TYPE_CHECKING, ClassVar, cast
+from typing import TYPE_CHECKING, ClassVar, Final, cast
 
 if TYPE_CHECKING:
     from .tool import Tool
 
 from ._types import SupportsDataclass
 
+_SECTION_KEY_PATTERN: Final[re.Pattern[str]] = re.compile(
+    r"^[a-z0-9][a-z0-9._-]{0,63}$"
+)
+
 
 class Section[ParamsT: SupportsDataclass](ABC):
     """Abstract building block for prompt content."""
@@ -31,7 +36,8 @@ class Section[ParamsT: SupportsDataclass](ABC):
         self,
         *,
         title: str,
-        defaults: ParamsT | None = None,
+        key: str,
+        default_params: ParamsT | None = None,
         children: Sequence[object] | None = None,
         enabled: Callable[[ParamsT], bool] | None = None,
         tools: Sequence[object] | None = None,
@@ -45,9 +51,10 @@ class Section[ParamsT: SupportsDataclass](ABC):
             )
 
         self.params_type: type[ParamsT] = params_type
-        self.params: type[ParamsT] = params_type
+        self.param_type: type[ParamsT] = params_type
         self.title = title
-        self.defaults = defaults
+        self.key = self._normalize_key(key)
+        self.default_params = default_params
 
         normalized_children: list[Section[SupportsDataclass]] = []
         for child in children or ():
@@ -81,6 +88,11 @@ class Section[ParamsT: SupportsDataclass](ABC):
 
         return self._tools
 
+    def original_body_template(self) -> str | None:
+        """Return the template text that participates in hashing, when available."""
+
+        return None
+
     @classmethod
     def __class_getitem__(cls, item: object) -> type[Section[SupportsDataclass]]:
         params_type = cls._normalize_generic_argument(item)
@@ -94,6 +106,15 @@ class Section[ParamsT: SupportsDataclass](ABC):
         _SpecializedSection._params_type = cast(type[SupportsDataclass], params_type)
         return _SpecializedSection  # type: ignore[return-value]
 
+    @staticmethod
+    def _normalize_key(key: str) -> str:
+        normalized = key.strip().lower()
+        if not normalized:
+            raise ValueError("Section key must be a non-empty string.")
+        if not _SECTION_KEY_PATTERN.match(normalized):
+            raise ValueError("Section key must match ^[a-z0-9][a-z0-9._-]{0,63}$.")
+        return normalized
+
     @staticmethod
     def _normalize_generic_argument(item: object) -> object:
         if isinstance(item, tuple):

weakincentives/{prompts/structured.py → prompt/structured_output.py}

@@ -15,14 +15,18 @@ from __future__ import annotations
 import json
 import re
 from collections.abc import Mapping
-from typing import Any, Literal, cast
+from typing import Any, Final, Literal, cast
 
 from ..serde.dataclass_serde import parse as parse_dataclass
 from .prompt import RenderedPrompt
 
-__all__ = ["OutputParseError", "parse_output"]
+__all__ = ["ARRAY_WRAPPER_KEY", "OutputParseError", "parse_structured_output"]
 
-_JSON_FENCE_PATTERN = re.compile(r"```json\s*\n(.*?)```", re.IGNORECASE | re.DOTALL)
+ARRAY_WRAPPER_KEY: Final[str] = "items"
+
+_JSON_FENCE_PATTERN: Final[re.Pattern[str]] = re.compile(
+    r"```json\s*\n(.*?)```", re.IGNORECASE | re.DOTALL
+)
 
 
 class OutputParseError(Exception):
@@ -39,13 +43,13 @@ class OutputParseError(Exception):
         self.dataclass_type = dataclass_type
 
 
-def parse_output[PayloadT](
+def parse_structured_output[PayloadT](
     output_text: str, rendered: RenderedPrompt[PayloadT]
 ) -> PayloadT:
     """Parse a model response into the structured output type declared by the prompt."""
 
     dataclass_type = rendered.output_type
-    container = rendered.output_container
+    container = rendered.container
     allow_extra_keys = rendered.allow_extra_keys
 
     if dataclass_type is None or container is None:
@@ -72,6 +76,13 @@ def parse_output[PayloadT](
         return cast(PayloadT, parsed)
 
     if container == "array":
+        if isinstance(payload, Mapping):
+            if ARRAY_WRAPPER_KEY not in payload:
+                raise OutputParseError(
+                    "Expected top-level JSON array.",
+                    dataclass_type=dataclass_type,
+                )
+            payload = cast(Mapping[str, object], payload)[ARRAY_WRAPPER_KEY]
         if not isinstance(payload, list):
             raise OutputParseError(
                 "Expected top-level JSON array.",