weakincentives 0.9.0__py3-none-any.whl

weakincentives/prompt/_generic_params_specializer.py

@@ -0,0 +1,64 @@
+# 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 typing import ClassVar, Generic, TypeVar, cast
+
+from ._types import SupportsDataclass
+
+ParamsT = TypeVar("ParamsT", bound=SupportsDataclass, covariant=True)
+
+SelfClass = TypeVar(
+    "SelfClass",
+    bound="GenericParamsSpecializer[SupportsDataclass]",
+    covariant=True,
+)
+
+
+class GenericParamsSpecializer(Generic[ParamsT]):  # noqa: UP046
+    """Mixin providing ``ParamsT`` specialization for prompt components."""
+
+    _params_type: ClassVar[type[SupportsDataclass] | None] = None
+    _generic_owner_name: ClassVar[str | None] = None
+
+    @classmethod
+    def __class_getitem__(cls: type[SelfClass], item: object) -> type[SelfClass]:
+        params_type = cls._normalize_generic_argument(item)
+        specialized = cast(
+            "type[SelfClass]",
+            type(cls.__name__, (cls,), {}),
+        )
+        specialized.__name__ = cls.__name__
+        specialized.__qualname__ = cls.__qualname__
+        specialized.__module__ = cls.__module__
+        specialized._params_type = cast(type[SupportsDataclass], params_type)
+        return specialized
+
+    @classmethod
+    def _normalize_generic_argument(cls, item: object) -> object:
+        if isinstance(item, tuple):
+            raise TypeError(f"{cls._owner_name()}[...] expects a single type argument.")
+        return item
+
+    @classmethod
+    def _owner_name(cls) -> str:
+        owner_name = getattr(cls, "_generic_owner_name", None)
+        if isinstance(owner_name, str) and owner_name:
+            return owner_name
+        name = getattr(cls, "__name__", None)
+        if isinstance(name, str) and name:
+            return name
+        return "Component"
+
+
+__all__ = ["GenericParamsSpecializer"]

weakincentives/prompt/_normalization.py

@@ -0,0 +1,48 @@
+# 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.
+
+"""Shared utilities for normalizing prompt component identifiers."""
+
+from __future__ import annotations
+
+import re
+from typing import Final
+
+COMPONENT_KEY_PATTERN: Final[re.Pattern[str]] = re.compile(
+    r"^[a-z0-9][a-z0-9._-]{0,63}$"
+)
+
+
+def normalize_component_key(key: str, *, owner: str) -> str:
+    """Normalize component keys across prompt primitives.
+
+    Args:
+        key: The user supplied identifier that should be normalized.
+        owner: Human-friendly label for the component requesting normalization.
+
+    Returns:
+        The sanitized key that downstream consumers may safely use.
+
+    Raises:
+        ValueError: When ``key`` is empty or fails to match
+            :data:`COMPONENT_KEY_PATTERN`.
+    """
+
+    normalized = key.strip().lower()
+    if not normalized:
+        raise ValueError(f"{owner} key must be a non-empty string.")
+    if not COMPONENT_KEY_PATTERN.match(normalized):
+        raise ValueError(f"{owner} key must match {COMPONENT_KEY_PATTERN.pattern}.")
+    return normalized
+
+
+__all__ = ["COMPONENT_KEY_PATTERN", "normalize_component_key"]

weakincentives/prompt/_overrides_protocols.py

@@ -0,0 +1,33 @@
+# 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.
+
+"""Lightweight interfaces shared between prompt overrides and protocols."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from .overrides import PromptDescriptor, PromptOverride
+
+
+class PromptOverridesStoreProtocol(Protocol):
+    """Structural interface satisfied by prompt overrides stores."""
+
+    def resolve(
+        self,
+        descriptor: PromptDescriptor,
+        tag: str = "latest",
+    ) -> PromptOverride | None: ...
+
+
+__all__ = ["PromptOverridesStoreProtocol"]

weakincentives/prompt/_types.py

@@ -0,0 +1,34 @@
+# 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.
+
+"""Internal typing helpers for the :mod:`weakincentives.prompt` package."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import Field
+from typing import Any, ClassVar, Protocol, runtime_checkable
+
+type DataclassFieldMapping = dict[str, Field[Any]]
+
+
+@runtime_checkable
+class SupportsDataclass(Protocol):
+    """Protocol satisfied by dataclass types and instances."""
+
+    __dataclass_fields__: ClassVar[DataclassFieldMapping]
+
+
+SupportsToolResult = SupportsDataclass | Sequence[SupportsDataclass]
+
+
+__all__ = ["DataclassFieldMapping", "SupportsDataclass", "SupportsToolResult"]

weakincentives/prompt/chapter.py

@@ -0,0 +1,146 @@
+# 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.
+
+"""Chapter primitives controlling coarse-grained prompt visibility."""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import ClassVar, TypeVar, cast
+
+from ._generic_params_specializer import GenericParamsSpecializer
+from ._normalization import normalize_component_key
+from ._types import SupportsDataclass
+from .section import Section
+
+
+class ChaptersExpansionPolicy(StrEnum):
+    """Strategies describing how adapters may open prompt chapters."""
+
+    ALL_INCLUDED = "all_included"
+    INTENT_CLASSIFIER = "intent_classifier"
+
+
+ChapterParamsT = TypeVar("ChapterParamsT", bound=SupportsDataclass, covariant=True)
+EnabledPredicate = Callable[[SupportsDataclass], bool] | Callable[[], bool]
+
+
+@dataclass
+class Chapter(GenericParamsSpecializer[ChapterParamsT]):
+    """Container grouping sections under a shared visibility boundary."""
+
+    key: str
+    title: str
+    description: str | None = None
+    sections: tuple[Section[SupportsDataclass], ...] = ()
+    default_params: ChapterParamsT | None = None
+    enabled: EnabledPredicate | None = None
+    _enabled_callable: Callable[[SupportsDataclass | None], bool] | None = field(
+        init=False, repr=False, default=None
+    )
+
+    _generic_owner_name: ClassVar[str | None] = "Chapter"
+
+    def __post_init__(self) -> None:
+        params_candidate = getattr(self.__class__, "_params_type", None)
+        candidate_type = (
+            params_candidate if isinstance(params_candidate, type) else None
+        )
+        params_type = cast(type[SupportsDataclass] | None, candidate_type)
+        self.key = self._normalize_key(self.key)
+
+        self.sections = tuple(self.sections or ())
+
+        self._enabled_callable = self._normalize_enabled(self.enabled, params_type)
+
+        if params_type is None:
+            if self.default_params is not None:
+                raise TypeError(
+                    "Chapter without parameters cannot define default_params."
+                )
+        elif self.default_params is not None and not isinstance(
+            self.default_params, params_type
+        ):
+            raise TypeError(
+                "Chapter default_params must match the declared ParamsT type."
+            )
+
+    @property
+    def params_type(self) -> type[ChapterParamsT] | None:
+        params_candidate = getattr(self.__class__, "_params_type", None)
+        candidate_type = (
+            params_candidate if isinstance(params_candidate, type) else None
+        )
+        return cast(type[ChapterParamsT] | None, candidate_type)
+
+    @property
+    def param_type(self) -> type[ChapterParamsT] | None:
+        return self.params_type
+
+    def is_enabled(self, params: SupportsDataclass | None) -> bool:
+        """Return True when the chapter should open for the provided params."""
+
+        if self._enabled_callable is None:
+            return True
+        if params is None and self.param_type is not None:
+            raise TypeError("Chapter parameters are required for enabled predicates.")
+        return bool(self._enabled_callable(params))
+
+    @staticmethod
+    def _normalize_key(key: str) -> str:
+        return normalize_component_key(key, owner="Chapter")
+
+    @staticmethod
+    def _normalize_enabled(
+        enabled: EnabledPredicate | None,
+        params_type: type[SupportsDataclass] | None,
+    ) -> Callable[[SupportsDataclass | None], bool] | None:
+        if enabled is None:
+            return None
+        if params_type is None and not _callable_requires_positional_argument(enabled):
+            zero_arg = cast(Callable[[], bool], enabled)
+
+            def _without_params(_: SupportsDataclass | None) -> bool:
+                return bool(zero_arg())
+
+            return _without_params
+
+        coerced = cast(Callable[[SupportsDataclass], bool], enabled)
+
+        def _with_params(value: SupportsDataclass | None) -> bool:
+            return bool(coerced(cast(SupportsDataclass, value)))
+
+        return _with_params
+
+
+def _callable_requires_positional_argument(callback: EnabledPredicate) -> bool:
+    try:
+        signature = inspect.signature(callback)
+    except (TypeError, ValueError):
+        return True
+    for parameter in signature.parameters.values():
+        if (
+            parameter.kind
+            in (
+                inspect.Parameter.POSITIONAL_ONLY,
+                inspect.Parameter.POSITIONAL_OR_KEYWORD,
+            )
+            and parameter.default is inspect.Signature.empty
+        ):
+            return True
+    return False
+
+
+__all__ = ["Chapter", "ChaptersExpansionPolicy"]

weakincentives/prompt/composition.py

@@ -0,0 +1,281 @@
+# 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.
+
+"""Utilities for composing delegation prompts from rendered parents."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field, replace
+from types import MappingProxyType
+from typing import Any, ClassVar, Generic, TypeVar, cast, override
+
+from ._types import SupportsDataclass
+from .errors import PromptRenderError
+from .markdown import MarkdownSection
+from .prompt import Prompt, RenderedPrompt
+from .protocols import PromptProtocol
+from .response_format import ResponseFormatParams, ResponseFormatSection
+from .section import Section
+
+ParentOutputT = TypeVar("ParentOutputT")
+DelegationOutputT = TypeVar("DelegationOutputT")
+
+
+@dataclass(slots=True)
+class DelegationParams:
+    """Delegation summary fields surfaced to the delegated agent."""
+
+    reason: str
+    expected_result: str
+    may_delegate_further: str
+    recap_lines: tuple[str, ...] = field(default_factory=tuple)
+
+    def __post_init__(self) -> None:
+        self.recap_lines = tuple(self.recap_lines)
+
+
+@dataclass(slots=True)
+class ParentPromptParams:
+    """Container for the verbatim parent prompt body."""
+
+    body: str
+
+
+@dataclass(slots=True)
+class RecapParams:
+    """Bullet-style recap directives rendered after the parent prompt."""
+
+    bullets: tuple[str, ...]
+
+
+class DelegationSummarySection(MarkdownSection[DelegationParams]):
+    """Delegation summary rendered as a fixed bullet list."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            title="Delegation Summary",
+            key="delegation-summary",
+            template=(
+                "- **Reason** - ${reason}\n"
+                "- **Expected result** - ${expected_result}\n"
+                "- **May delegate further?** - ${may_delegate_further}"
+            ),
+        )
+
+
+class ParentPromptSection(Section[ParentPromptParams]):
+    """Embed the parent prompt verbatim between explicit markers."""
+
+    def __init__(
+        self,
+        *,
+        tools: Sequence[object] | None = None,
+        default_params: ParentPromptParams | None = None,
+    ) -> None:
+        super().__init__(
+            title="Parent Prompt (Verbatim)",
+            key="parent-prompt",
+            tools=tools,
+            default_params=default_params,
+        )
+
+    @override
+    def render(self, params: SupportsDataclass | None, depth: int) -> str:
+        if not isinstance(params, ParentPromptParams):
+            raise PromptRenderError(
+                "Parent prompt section requires parameters.",
+                dataclass_type=ParentPromptParams,
+            )
+        heading = "#" * (depth + 2)
+        prefix = f"{heading} {self.title}"
+        body = params.body
+        suffix = "" if body.endswith("\n") else "\n"
+        return (
+            f"{prefix}\n\n"
+            "<!-- PARENT PROMPT START -->\n"
+            f"{body}{suffix}"
+            "<!-- PARENT PROMPT END -->"
+        )
+
+
+class RecapSection(Section[RecapParams]):
+    """Render a concise recap of inherited parent prompt directives."""
+
+    def __init__(self) -> None:
+        super().__init__(title="Recap", key="recap")
+
+    @override
+    def render(self, params: SupportsDataclass | None, depth: int) -> str:
+        if not isinstance(params, RecapParams):
+            raise PromptRenderError(
+                "Recap section requires parameters.",
+                dataclass_type=RecapParams,
+            )
+        heading = "#" * (depth + 2)
+        prefix = f"{heading} {self.title}"
+        bullets = params.bullets
+        bullet_lines = "\n".join(f"- {line}" for line in bullets)
+        if bullet_lines:
+            return f"{prefix}\n\n{bullet_lines}"
+        return prefix
+
+
+class DelegationPrompt(Generic[ParentOutputT, DelegationOutputT]):  # noqa: UP046
+    """Wrap a rendered parent prompt for subagent delegation."""
+
+    _parent_output_type: ClassVar[type[Any] | None] = None
+    _delegation_output_type: ClassVar[type[Any] | None] = None
+
+    def __class_getitem__(
+        cls, item: tuple[type[Any], type[Any]]
+    ) -> type["DelegationPrompt[Any, Any]"]:  # noqa: UP037
+        parent_output, delegation_output = item
+
+        name = f"{cls.__name__}[{parent_output.__name__}, {delegation_output.__name__}]"
+        namespace = {
+            "__module__": cls.__module__,
+            "_parent_output_type": parent_output,
+            "_delegation_output_type": delegation_output,
+        }
+        specialized = type(name, (cls,), namespace)
+        return cast("type[DelegationPrompt[Any, Any]]", specialized)
+
+    def __init__(
+        self,
+        parent_prompt: PromptProtocol[ParentOutputT] | Prompt[ParentOutputT],
+        rendered_parent: RenderedPrompt[ParentOutputT],
+        *,
+        include_response_format: bool = False,
+    ) -> None:
+        super().__init__()
+        self._rendered_parent = rendered_parent
+        summary_section = DelegationSummarySection()
+        parent_section = ParentPromptSection(
+            tools=rendered_parent.tools,
+            default_params=ParentPromptParams(body=rendered_parent.text),
+        )
+        sections: list[Section[SupportsDataclass]] = [summary_section]
+
+        if include_response_format:
+            response_section = self._build_response_format_section(rendered_parent)
+            if response_section is not None:
+                sections.append(response_section)
+
+        sections.append(parent_section)
+
+        self._recap_section = RecapSection()
+        sections.append(self._recap_section)
+
+        delegation_output_type = self._resolve_delegation_output_type()
+        prompt_cls: type[Prompt[DelegationOutputT]] = Prompt[delegation_output_type]
+        self._prompt = prompt_cls(
+            ns=f"{parent_prompt.ns}.delegation",
+            key=f"{parent_prompt.key}-wrapper",
+            sections=tuple(sections),
+            inject_output_instructions=False,
+            allow_extra_keys=bool(rendered_parent.allow_extra_keys),
+        )
+
+    def _resolve_delegation_output_type(self) -> type[DelegationOutputT]:
+        candidate = getattr(type(self), "_delegation_output_type", None)
+        if isinstance(candidate, type):
+            return cast(type[DelegationOutputT], candidate)
+
+        msg = "Specialize DelegationPrompt with an explicit output type"
+        raise TypeError(msg)
+
+    def _build_response_format_section(
+        self,
+        rendered_parent: RenderedPrompt[ParentOutputT],
+    ) -> ResponseFormatSection | None:
+        container = rendered_parent.container
+        if container is None:
+            return None
+
+        article = "an" if container.startswith(tuple("aeiou")) else "a"
+        extra_clause = (
+            "." if rendered_parent.allow_extra_keys else ". Do not add extra keys."
+        )
+
+        return ResponseFormatSection(
+            params=ResponseFormatParams(
+                article=article, container=container, extra_clause=extra_clause
+            )
+        )
+
+    @property
+    def prompt(self) -> Prompt[DelegationOutputT]:
+        """Expose the composed prompt for direct access when required."""
+
+        return self._prompt
+
+    def render(
+        self,
+        summary: DelegationParams,
+        parent: ParentPromptParams | None = None,
+        recap: RecapParams | None = None,
+    ) -> RenderedPrompt[DelegationOutputT]:
+        params: list[SupportsDataclass] = [summary]
+        parent_params = parent or ParentPromptParams(body=self._rendered_parent.text)
+        params.append(parent_params)
+
+        default_recap = RecapParams(bullets=tuple(summary.recap_lines))
+        recap_params = recap or default_recap
+        params.append(recap_params)
+
+        rendered = self._prompt.render(*tuple(params))
+        parent_deadline = self._rendered_parent.deadline
+        if parent_deadline is not None and rendered.deadline is not parent_deadline:
+            rendered = replace(rendered, deadline=parent_deadline)
+        merged_descriptions = _merge_tool_param_descriptions(
+            self._rendered_parent.tool_param_descriptions,
+            rendered.tool_param_descriptions,
+        )
+        if merged_descriptions is rendered.tool_param_descriptions:
+            return rendered
+        return replace(rendered, _tool_param_descriptions=merged_descriptions)
+
+
+def _merge_tool_param_descriptions(
+    parent_descriptions: Mapping[str, Mapping[str, str]],
+    rendered_descriptions: Mapping[str, Mapping[str, str]],
+) -> Mapping[str, Mapping[str, str]]:
+    if not parent_descriptions:
+        return rendered_descriptions
+
+    merged: dict[str, dict[str, str]] = {
+        name: dict(fields) for name, fields in parent_descriptions.items()
+    }
+    for name, fields in rendered_descriptions.items():
+        if name not in merged:
+            merged[name] = dict(fields)
+        else:
+            merged[name].update(fields)
+
+    return MappingProxyType(
+        {
+            name: MappingProxyType(dict(field_mapping))
+            for name, field_mapping in merged.items()
+        }
+    )
+
+
+__all__ = [
+    "DelegationParams",
+    "DelegationPrompt",
+    "DelegationSummarySection",
+    "ParentPromptParams",
+    "ParentPromptSection",
+    "RecapParams",
+    "RecapSection",
+]

weakincentives/prompt/errors.py

@@ -0,0 +1,57 @@
+# 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 Sequence
+
+SectionPath = tuple[str, ...]
+
+
+def _normalize_section_path(section_path: Sequence[str] | None) -> SectionPath:
+    if section_path is None:
+        return ()
+    return tuple(section_path)
+
+
+class PromptError(Exception):
+    """Base class for prompt-related failures providing structured context."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        section_path: Sequence[str] | None = None,
+        dataclass_type: type | None = None,
+        placeholder: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.section_path: SectionPath = _normalize_section_path(section_path)
+        self.dataclass_type = dataclass_type
+        self.placeholder = placeholder
+
+
+class PromptValidationError(PromptError):
+    """Raised when prompt construction validation fails."""
+
+
+class PromptRenderError(PromptError):
+    """Raised when rendering a prompt fails."""
+
+
+__all__ = [
+    "PromptError",
+    "PromptRenderError",
+    "PromptValidationError",
+    "SectionPath",
+]