weakincentives 0.9.0__py3-none-any.whl

weakincentives/prompt/tool.py

@@ -0,0 +1,397 @@
+# 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 inspect
+import re
+from collections.abc import Callable
+from collections.abc import Sequence as SequenceABC
+from dataclasses import dataclass, field
+from typing import (
+    TYPE_CHECKING,
+    Annotated,
+    Any,
+    Final,
+    Literal,
+    Protocol,
+    TypeVar,
+    cast,
+    get_args,
+    get_origin,
+    get_type_hints,
+)
+
+from ..deadlines import Deadline
+from ._types import SupportsDataclass, SupportsToolResult
+from .errors import PromptValidationError
+from .tool_result import ToolResult
+
+_NAME_PATTERN: Final[re.Pattern[str]] = re.compile(r"^[a-z0-9_-]{1,64}$")
+
+
+if TYPE_CHECKING:
+    from ..runtime.events._types import EventBus
+    from ..runtime.session.protocols import SessionProtocol
+    from .protocols import (
+        PromptProtocol,
+        ProviderAdapterProtocol,
+        RenderedPromptProtocol,
+    )
+
+ParamsT_contra = TypeVar("ParamsT_contra", bound=SupportsDataclass, contravariant=True)
+ResultT_co = TypeVar("ResultT_co", bound=SupportsToolResult)
+
+
+@dataclass(slots=True, frozen=True)
+class ToolContext:
+    """Immutable container exposing prompt execution state to handlers."""
+
+    prompt: PromptProtocol[Any]
+    rendered_prompt: RenderedPromptProtocol[Any] | None
+    adapter: ProviderAdapterProtocol[Any]
+    session: SessionProtocol
+    event_bus: EventBus
+    deadline: Deadline | None = None
+
+
+def _normalize_specialization(item: object) -> tuple[object, object]:
+    if not isinstance(item, tuple):
+        raise TypeError("Tool[...] expects two type arguments (ParamsT, ResultT).")
+    normalized = cast(SequenceABC[object], item)
+    if len(normalized) != 2:
+        raise TypeError("Tool[...] expects two type arguments (ParamsT, ResultT).")
+    return normalized[0], normalized[1]
+
+
+class ToolHandler(Protocol[ParamsT_contra, ResultT_co]):
+    """Callable protocol implemented by tool handlers."""
+
+    def __call__(
+        self, params: ParamsT_contra, *, context: ToolContext
+    ) -> ToolResult[ResultT_co]: ...
+
+
+@dataclass(slots=True)
+class Tool[ParamsT: SupportsDataclass, ResultT: SupportsToolResult]:
+    """Describe a callable tool exposed by prompt sections."""
+
+    name: str
+    description: str
+    handler: ToolHandler[ParamsT, ResultT] | None
+    params_type: type[ParamsT] = field(init=False, repr=False)
+    result_type: type[SupportsDataclass] = field(init=False, repr=False)
+    result_container: Literal["object", "array"] = field(
+        init=False,
+        repr=False,
+    )
+    _result_annotation: ResultT = field(init=False, repr=False)
+    accepts_overrides: bool = True
+
+    def __post_init__(self) -> None:
+        params_attr = getattr(self, "params_type", None)
+        params_type: type[SupportsDataclass] | None = (
+            params_attr if isinstance(params_attr, type) else None
+        )
+        raw_result_annotation = getattr(self, "_result_annotation", None)
+        if params_type is None or raw_result_annotation is None:
+            origin = getattr(self, "__orig_class__", None)
+            if origin is not None:  # pragma: no cover - interpreter-specific path
+                args = get_args(origin)
+                if len(args) == 2:
+                    params_arg, result_arg = args
+                    if isinstance(params_arg, type):
+                        params_type = params_arg
+                        raw_result_annotation = cast(ResultT, result_arg)
+        if params_type is None or raw_result_annotation is None:
+            raise PromptValidationError(
+                "Tool must be instantiated with concrete type arguments.",
+                placeholder="type_arguments",
+            )
+
+        result_type, result_container = self._normalize_result_annotation(
+            raw_result_annotation,
+            params_type,
+        )
+
+        self.params_type = cast(type[ParamsT], params_type)
+        self.result_type = result_type
+        self.result_container = result_container
+        self._result_annotation = raw_result_annotation
+
+        raw_name = self.name
+        stripped_name = raw_name.strip()
+        if raw_name != stripped_name:
+            normalized_name = stripped_name
+            raise PromptValidationError(
+                "Tool name must not contain surrounding whitespace.",
+                dataclass_type=params_type,
+                placeholder=normalized_name,
+            )
+
+        name_clean = raw_name
+        if not name_clean:
+            raise PromptValidationError(
+                "Tool name must match the OpenAI function name constraints (1-64 lowercase ASCII letters, digits, underscores, or hyphens).",
+                dataclass_type=params_type,
+                placeholder=stripped_name,
+            )
+        if len(name_clean) > 64 or not _NAME_PATTERN.fullmatch(name_clean):
+            raise PromptValidationError(
+                "Tool name must match the OpenAI function name constraints (pattern: ^[a-z0-9_-]{1,64}$).",
+                dataclass_type=params_type,
+                placeholder=name_clean,
+            )
+
+        description_clean = self.description.strip()
+        if not description_clean or len(description_clean) > 200:
+            raise PromptValidationError(
+                "Tool description must be 1-200 ASCII characters.",
+                dataclass_type=params_type,
+                placeholder="description",
+            )
+        try:
+            _ = description_clean.encode("ascii")
+        except UnicodeEncodeError as error:
+            raise PromptValidationError(
+                "Tool description must be ASCII.",
+                dataclass_type=params_type,
+                placeholder="description",
+            ) from error
+
+        handler = self.handler
+        if handler is not None:
+            self._validate_handler(
+                handler,
+                params_type,
+                raw_result_annotation,
+            )
+
+        self.name = name_clean
+        self.description = description_clean
+
+    def _validate_handler(
+        self,
+        handler: object,
+        params_type: type[SupportsDataclass],
+        result_annotation: object,
+    ) -> None:
+        if not callable(handler):
+            raise PromptValidationError(
+                "Tool handler must be callable.",
+                dataclass_type=params_type,
+                placeholder="handler",
+            )
+
+        callable_handler = cast(Callable[..., ToolResult[ResultT]], handler)
+        signature = inspect.signature(callable_handler)
+        parameters = list(signature.parameters.values())
+
+        if len(parameters) != 2:
+            raise PromptValidationError(
+                "Tool handler must accept exactly one positional argument and the keyword-only 'context' parameter.",
+                dataclass_type=params_type,
+                placeholder="handler",
+            )
+
+        parameter = parameters[0]
+        context_parameter = parameters[1]
+
+        if parameter.kind not in (
+            inspect.Parameter.POSITIONAL_ONLY,
+            inspect.Parameter.POSITIONAL_OR_KEYWORD,
+        ):
+            raise PromptValidationError(
+                "Tool handler parameter must be positional.",
+                dataclass_type=params_type,
+                placeholder="handler",
+            )
+
+        if context_parameter.kind is not inspect.Parameter.KEYWORD_ONLY:
+            raise PromptValidationError(
+                "Tool handler must declare a keyword-only 'context' parameter.",
+                dataclass_type=params_type,
+                placeholder="handler",
+            )
+        if context_parameter.default is not inspect.Signature.empty:
+            raise PromptValidationError(
+                "Tool handler 'context' parameter must not define a default value.",
+                dataclass_type=params_type,
+                placeholder="handler",
+            )
+        if context_parameter.name != "context":
+            raise PromptValidationError(
+                "Tool handler must name the keyword-only context parameter 'context'.",
+                dataclass_type=params_type,
+                placeholder="handler",
+            )
+
+        try:
+            hints = get_type_hints(callable_handler, include_extras=True)
+        except Exception:
+            hints = {}
+
+        annotation = hints.get(parameter.name, parameter.annotation)
+        if annotation is inspect.Parameter.empty:
+            raise PromptValidationError(
+                "Tool handler parameter must be annotated with ParamsT.",
+                dataclass_type=params_type,
+                placeholder="handler",
+            )
+        if get_origin(annotation) is Annotated:
+            annotation = get_args(annotation)[0]
+        if annotation is not params_type:
+            raise PromptValidationError(
+                "Tool handler parameter annotation must match ParamsT.",
+                dataclass_type=params_type,
+                placeholder="handler",
+            )
+
+        context_annotation = hints.get(
+            context_parameter.name, context_parameter.annotation
+        )
+        if context_annotation is inspect.Parameter.empty:
+            raise PromptValidationError(
+                "Tool handler must annotate the 'context' parameter with ToolContext.",
+                dataclass_type=params_type,
+                placeholder="handler",
+            )
+        if get_origin(context_annotation) is Annotated:
+            context_annotation = get_args(context_annotation)[0]
+        if context_annotation is not ToolContext:
+            raise PromptValidationError(
+                "Tool handler 'context' annotation must be ToolContext.",
+                dataclass_type=params_type,
+                placeholder="handler",
+            )
+
+        return_annotation = hints.get("return", signature.return_annotation)
+        if return_annotation is inspect.Signature.empty:
+            raise PromptValidationError(
+                "Tool handler must annotate its return value with ToolResult[ResultT].",
+                dataclass_type=params_type,
+                placeholder="return",
+            )
+        if get_origin(return_annotation) is Annotated:
+            return_annotation = get_args(return_annotation)[0]
+
+        origin = get_origin(return_annotation)
+        if origin is ToolResult:
+            result_args_raw = get_args(return_annotation)
+            if result_args_raw and self._matches_result_annotation(
+                result_args_raw[0],
+                result_annotation,
+            ):
+                return
+        raise PromptValidationError(
+            "Tool handler return annotation must be ToolResult[ResultT].",
+            dataclass_type=params_type,
+            placeholder="return",
+        )
+
+    @staticmethod
+    def _normalize_result_annotation(
+        annotation: ResultT,
+        params_type: type[SupportsDataclass],
+    ) -> tuple[type[SupportsDataclass], Literal["object", "array"]]:
+        if isinstance(annotation, type):
+            return cast(type[SupportsDataclass], annotation), "object"
+
+        origin = get_origin(annotation)
+        if origin not in {list, tuple, SequenceABC}:
+            raise PromptValidationError(
+                "Tool ResultT must be a dataclass type or a sequence of dataclasses.",
+                dataclass_type=params_type,
+                placeholder="ResultT",
+            )
+
+        args = get_args(annotation)
+        element: object | None = None
+        if origin is tuple:
+            if len(args) != 2 or args[1] is not Ellipsis:
+                raise PromptValidationError(
+                    "Variadic Tuple[ResultT, ...] is required for Tool sequence results.",
+                    dataclass_type=params_type,
+                    placeholder="ResultT",
+                )
+            element = args[0]
+        elif len(args) == 1:
+            element = args[0]
+
+        if not isinstance(element, type):
+            raise PromptValidationError(
+                "Tool ResultT must be a dataclass type or a sequence of dataclasses.",
+                dataclass_type=params_type,
+                placeholder="ResultT",
+            )
+
+        return cast(type[SupportsDataclass], element), "array"
+
+    @staticmethod
+    def _matches_result_annotation(candidate: object, expected: object) -> bool:
+        if candidate is expected:
+            return True
+
+        candidate_origin = get_origin(candidate)
+        expected_origin = get_origin(expected)
+
+        if candidate_origin is None or expected_origin is None:
+            return False
+
+        sequence_origins = {list, tuple, SequenceABC}
+        if candidate_origin in sequence_origins and expected_origin in sequence_origins:
+            candidate_args = get_args(candidate)
+            expected_args = get_args(expected)
+            candidate_element = (
+                candidate_args[0]
+                if candidate_origin is not tuple
+                else candidate_args[0]
+                if len(candidate_args) == 2
+                else None
+            )
+            expected_element = (
+                expected_args[0]
+                if expected_origin is not tuple
+                else expected_args[0]
+                if len(expected_args) == 2
+                else None
+            )
+            return candidate_element is expected_element
+
+        return False
+
+    @classmethod
+    def __class_getitem__(
+        cls, item: object
+    ) -> type[Tool[SupportsDataclass, SupportsToolResult]]:
+        params_candidate, result_candidate = _normalize_specialization(item)
+        if not isinstance(params_candidate, type):
+            raise TypeError("Tool ParamsT type argument must be a type.")
+        params_type = cast(type[SupportsDataclass], params_candidate)
+        result_annotation = cast(ResultT, result_candidate)
+
+        class _SpecializedTool(cls):
+            def __post_init__(self) -> None:
+                self.params_type = cast(type[ParamsT], params_type)
+                self._result_annotation = result_annotation
+                super().__post_init__()
+
+        _SpecializedTool.__name__ = cls.__name__
+        _SpecializedTool.__qualname__ = cls.__qualname__
+        _SpecializedTool.__module__ = cls.__module__
+        return cast(
+            "type[Tool[SupportsDataclass, SupportsToolResult]]",
+            _SpecializedTool,
+        )
+
+
+__all__ = ["Tool", "ToolContext", "ToolHandler", "ToolResult"]

weakincentives/prompt/tool_result.py

@@ -0,0 +1,30 @@
+# 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 result container returned by tool handlers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(slots=True)
+class ToolResult[ResultValueT]:
+    """Structured response emitted by a tool handler."""
+
+    message: str
+    value: ResultValueT | None
+    success: bool = True
+    exclude_value_from_context: bool = False
+
+
+__all__ = ["ToolResult"]

weakincentives/runtime/__init__.py

@@ -0,0 +1,82 @@
+# 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.
+
+"""Runtime primitives for :mod:`weakincentives`."""
+
+from __future__ import annotations
+
+from . import events, session
+from .events import (
+    EventBus,
+    HandlerFailure,
+    InProcessEventBus,
+    PromptExecuted,
+    PublishResult,
+    ToolInvoked,
+)
+from .logging import StructuredLogger, configure_logging, get_logger
+from .session import (
+    DataEvent,
+    ReducerContext,
+    ReducerContextProtocol,
+    ReducerEvent,
+    Session,
+    SessionProtocol,
+    Snapshot,
+    SnapshotProtocol,
+    SnapshotRestoreError,
+    SnapshotSerializationError,
+    TypedReducer,
+    append,
+    build_reducer_context,
+    replace_latest,
+    select_all,
+    select_latest,
+    select_where,
+    upsert_by,
+)
+
+__all__ = [
+    "DataEvent",
+    "EventBus",
+    "HandlerFailure",
+    "InProcessEventBus",
+    "PromptExecuted",
+    "PublishResult",
+    "ReducerContext",
+    "ReducerContextProtocol",
+    "ReducerEvent",
+    "Session",
+    "SessionProtocol",
+    "Snapshot",
+    "SnapshotProtocol",
+    "SnapshotRestoreError",
+    "SnapshotSerializationError",
+    "StructuredLogger",
+    "ToolInvoked",
+    "TypedReducer",
+    "append",
+    "build_reducer_context",
+    "configure_logging",
+    "events",
+    "get_logger",
+    "replace_latest",
+    "select_all",
+    "select_latest",
+    "select_where",
+    "session",
+    "upsert_by",
+]
+
+
+def __dir__() -> list[str]:
+    return sorted({*globals().keys(), *__all__})  # pragma: no cover - convenience shim

weakincentives/runtime/events/__init__.py

@@ -0,0 +1,126 @@
+# 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.
+
+"""In-process event primitives for adapter telemetry."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from threading import RLock
+from typing import TYPE_CHECKING
+from uuid import UUID, uuid4
+
+from ...prompt._types import SupportsDataclass
+from ..logging import StructuredLogger, get_logger
+from ._types import EventBus, EventHandler, HandlerFailure, PublishResult, ToolInvoked
+
+if TYPE_CHECKING:
+    from ...adapters._names import AdapterName
+    from ...adapters.core import PromptResponse
+
+
+def _describe_handler(handler: EventHandler) -> str:
+    module_name = getattr(handler, "__module__", None)
+    qualname = getattr(handler, "__qualname__", None)
+    if isinstance(qualname, str):
+        prefix = f"{module_name}." if isinstance(module_name, str) else ""
+        return f"{prefix}{qualname}"
+    return repr(handler)  # pragma: no cover - defensive fallback
+
+
+logger: StructuredLogger = get_logger(__name__, context={"component": "event_bus"})
+
+
+class InProcessEventBus:
+    """Process-local event bus that delivers events synchronously."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._handlers: dict[type[object], list[EventHandler]] = {}
+        self._lock = RLock()
+
+    def subscribe(self, event_type: type[object], handler: EventHandler) -> None:
+        with self._lock:
+            handlers = self._handlers.setdefault(event_type, [])
+            handlers.append(handler)
+
+    def publish(self, event: object) -> PublishResult:
+        with self._lock:
+            handlers = tuple(self._handlers.get(type(event), ()))
+        invoked: list[EventHandler] = []
+        failures: list[HandlerFailure] = []
+        for handler in handlers:
+            invoked.append(handler)
+            try:
+                handler(event)
+            except Exception as error:
+                logger.exception(
+                    "Error delivering event.",
+                    event="event_delivery_failed",
+                    context={
+                        "handler": _describe_handler(handler),
+                        "event_type": type(event).__name__,
+                    },
+                )
+                failures.append(HandlerFailure(handler=handler, error=error))
+
+        return PublishResult(
+            event=event,
+            handlers_invoked=tuple(invoked),
+            errors=tuple(failures),
+        )
+
+
+@dataclass(slots=True, frozen=True)
+class PromptExecuted:
+    """Event emitted after an adapter finishes evaluating a prompt."""
+
+    prompt_name: str
+    adapter: AdapterName
+    result: PromptResponse[object]
+    session_id: UUID | None
+    created_at: datetime
+    value: SupportsDataclass | None = None
+    event_id: UUID = field(default_factory=uuid4)
+
+
+@dataclass(slots=True, frozen=True)
+class PromptRendered:
+    """Event emitted immediately before dispatching a rendered prompt."""
+
+    prompt_ns: str
+    prompt_key: str
+    prompt_name: str | None
+    adapter: AdapterName
+    session_id: UUID | None
+    render_inputs: tuple[SupportsDataclass, ...]
+    rendered_prompt: str
+    created_at: datetime
+    event_id: UUID = field(default_factory=uuid4)
+
+    @property
+    def value(self) -> SupportsDataclass:
+        """Expose the dataclass instance for reducer compatibility."""
+
+        return self
+
+
+__all__ = [
+    "EventBus",
+    "HandlerFailure",
+    "InProcessEventBus",
+    "PromptExecuted",
+    "PromptRendered",
+    "PublishResult",
+    "ToolInvoked",
+]