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

weakincentives/{prompts → prompt}/tool.py

@@ -16,20 +16,20 @@ import inspect
 import re
 from collections.abc import Callable
 from dataclasses import dataclass, field, is_dataclass
-from typing import Annotated, Any, cast, get_args, get_origin, get_type_hints
+from typing import Annotated, Any, Final, cast, get_args, get_origin, get_type_hints
 
 from ._types import SupportsDataclass
 from .errors import PromptValidationError
 
-_NAME_PATTERN = re.compile(r"^[a-z0-9_]{1,64}$")
+_NAME_PATTERN: Final[re.Pattern[str]] = re.compile(r"^[a-z0-9_-]{1,64}$")
 
 
 @dataclass(slots=True)
-class ToolResult[ResultPayloadT]:
+class ToolResult[ResultValueT]:
     """Structured response emitted by a tool handler."""
 
     message: str
-    payload: ResultPayloadT
+    value: ResultValueT
 
 
 @dataclass(slots=True)
@@ -91,13 +91,13 @@ class Tool[ParamsT: SupportsDataclass, ResultT: SupportsDataclass]:
         name_clean = raw_name
         if not name_clean:
             raise PromptValidationError(
-                "Tool name must be non-empty lowercase ASCII up to 64 characters.",
+                "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 use lowercase ASCII letters, digits, or underscores.",
+                "Tool name must match the OpenAI function name constraints (pattern: ^[a-z0-9_-]{1,64}$).",
                 dataclass_type=params_type,
                 placeholder=name_clean,
             )

weakincentives/prompt/versioning.py

@@ -0,0 +1,144 @@
+# 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
+from dataclasses import dataclass, field
+from hashlib import sha256
+from typing import TYPE_CHECKING, Any, Protocol
+
+from ..serde.dataclass_serde import schema
+from .tool import Tool
+
+
+def _tool_override_mapping_factory() -> dict[str, ToolOverride]:
+    return {}
+
+
+def _param_description_mapping_factory() -> dict[str, str]:
+    return {}
+
+
+if TYPE_CHECKING:
+    from .prompt import Prompt
+
+
+@dataclass(slots=True)
+class SectionDescriptor:
+    """Hash metadata for a single section within a prompt."""
+
+    path: tuple[str, ...]
+    content_hash: str
+
+
+@dataclass(slots=True)
+class ToolDescriptor:
+    """Stable metadata describing a tool exposed by a prompt."""
+
+    path: tuple[str, ...]
+    name: str
+    contract_hash: str
+
+
+@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: Prompt[Any]) -> PromptDescriptor:
+        sections: list[SectionDescriptor] = []
+        tools: list[ToolDescriptor] = []
+        for node in prompt.sections:
+            template = node.section.original_body_template()
+            if template is not None:
+                content_hash = sha256(template.encode("utf-8")).hexdigest()
+                sections.append(SectionDescriptor(node.path, content_hash))
+            for tool in node.section.tools():
+                tools.append(
+                    ToolDescriptor(
+                        path=node.path,
+                        name=tool.name,
+                        contract_hash=_tool_contract_hash(tool),
+                    )
+                )
+        return cls(prompt.ns, prompt.key, sections, tools)
+
+
+@dataclass(slots=True)
+class ToolOverride:
+    """Description overrides validated against a tool contract hash."""
+
+    name: str
+    expected_contract_hash: str
+    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 a version store."""
+
+    ns: str
+    prompt_key: str
+    tag: str
+    overrides: dict[tuple[str, ...], str]
+    tool_overrides: dict[str, ToolOverride] = field(
+        default_factory=_tool_override_mapping_factory
+    )
+
+
+class PromptVersionStore(Protocol):
+    """Lookup interface for resolving prompt overrides at render time."""
+
+    def resolve(
+        self,
+        descriptor: PromptDescriptor,
+        tag: str = "latest",
+    ) -> PromptOverride | None: ...
+
+
+__all__ = [
+    "PromptDescriptor",
+    "PromptOverride",
+    "PromptVersionStore",
+    "SectionDescriptor",
+    "ToolDescriptor",
+    "ToolOverride",
+]
+
+
+def _tool_contract_hash(tool: Tool[Any, Any]) -> str:
+    description_hash = hash_text(tool.description)
+    params_schema_hash = hash_json(schema(tool.params_type, extra="forbid"))
+    result_schema_hash = hash_json(schema(tool.result_type, extra="ignore"))
+    return hash_text(
+        "::".join((description_hash, params_schema_hash, result_schema_hash))
+    )
+
+
+def hash_text(value: str) -> str:
+    return sha256(value.encode("utf-8")).hexdigest()
+
+
+def hash_json(value: object) -> str:
+    canonical = json.dumps(
+        value, sort_keys=True, separators=(",", ":"), ensure_ascii=True
+    )
+    return hash_text(canonical)

weakincentives/serde/__init__.py

@@ -10,20 +10,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# Copyright 2025 weak incentives
-#
-# 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.
-
 """Stdlib dataclass serde utilities."""
 
 from .dataclass_serde import clone, dump, parse, schema

weakincentives/serde/dataclass_serde.py

@@ -10,20 +10,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# Copyright 2025 weak incentives
-#
-# 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 dataclasses
@@ -36,10 +22,10 @@ from enum import Enum
 from pathlib import Path
 from re import Pattern
 from typing import Any as _AnyType
-from typing import Literal, Union, cast, get_args, get_origin, get_type_hints
+from typing import Final, Literal, Union, cast, get_args, get_origin, get_type_hints
 from uuid import UUID
 
-MISSING_SENTINEL: object = object()
+MISSING_SENTINEL: Final[object] = object()
 
 
 class _ExtrasDescriptor:
@@ -63,7 +49,7 @@ class _ExtrasDescriptor:
             self._store[key] = dict(value)
 
 
-_SLOTTED_EXTRAS: dict[type[object], _ExtrasDescriptor] = {}
+_SLOTTED_EXTRAS: Final[dict[type[object], _ExtrasDescriptor]] = {}
 
 
 def _ordered_values(values: Iterable[object]) -> list[object]:

weakincentives/session/__init__.py

@@ -0,0 +1,31 @@
+# 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.
+
+"""Session state container for agent runs."""
+
+from .reducers import append, replace_latest, upsert_by
+from .selectors import select_all, select_latest, select_where
+from .session import DataEvent, PromptData, Session, ToolData, TypedReducer
+
+__all__ = [
+    "Session",
+    "DataEvent",
+    "ToolData",
+    "PromptData",
+    "TypedReducer",
+    "append",
+    "upsert_by",
+    "replace_latest",
+    "select_all",
+    "select_latest",
+    "select_where",
+]

weakincentives/session/reducers.py

@@ -0,0 +1,60 @@
+# 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.
+
+"""Built-in reducers for Session state slices."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import cast
+
+from .session import DataEvent, TypedReducer
+
+
+def append[T](slice_values: tuple[T, ...], event: DataEvent) -> tuple[T, ...]:
+    """Append the event value if it is not already present."""
+
+    value = cast(T, event.value)
+    if value in slice_values:
+        return slice_values
+    return slice_values + (value,)
+
+
+def upsert_by[T, K](key_fn: Callable[[T], K]) -> TypedReducer[T]:
+    """Return a reducer that upserts items sharing the same derived key."""
+
+    def reducer(slice_values: tuple[T, ...], event: DataEvent) -> tuple[T, ...]:
+        value = cast(T, event.value)
+        key = key_fn(value)
+        updated: list[T] = []
+        replaced = False
+        for existing in slice_values:
+            if key_fn(existing) == key:
+                if not replaced:
+                    updated.append(value)
+                    replaced = True
+                continue
+            updated.append(existing)
+        if not replaced:
+            updated.append(value)
+        return tuple(updated)
+
+    return reducer
+
+
+def replace_latest[T](slice_values: tuple[T, ...], event: DataEvent) -> tuple[T, ...]:
+    """Keep only the most recent event value."""
+
+    return (cast(T, event.value),)
+
+
+__all__ = ["append", "upsert_by", "replace_latest"]

weakincentives/session/selectors.py

@@ -0,0 +1,45 @@
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Helpers for querying Session slices."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from .session import Session
+
+
+def select_all[T](session: Session, slice_type: type[T]) -> tuple[T, ...]:
+    """Return the entire slice for the provided type."""
+
+    return session.select_all(slice_type)
+
+
+def select_latest[T](session: Session, slice_type: type[T]) -> T | None:
+    """Return the most recent item in the slice, if any."""
+
+    values = session.select_all(slice_type)
+    if not values:
+        return None
+    return values[-1]
+
+
+def select_where[T](
+    session: Session, slice_type: type[T], predicate: Callable[[T], bool]
+) -> tuple[T, ...]:
+    """Return items that satisfy the predicate."""
+
+    return tuple(value for value in session.select_all(slice_type) if predicate(value))
+
+
+__all__ = ["select_all", "select_latest", "select_where"]

weakincentives/session/session.py

@@ -0,0 +1,168 @@
+# 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.
+
+"""Session state container synchronized with the event bus."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass, is_dataclass
+from typing import Any, cast
+
+from ..events import EventBus, NullEventBus, PromptExecuted, ToolInvoked
+from ..prompt._types import SupportsDataclass
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(slots=True, frozen=True)
+class ToolData[T: SupportsDataclass]:
+    """Wrapper containing tool payloads and their originating event."""
+
+    value: T
+    source: ToolInvoked
+
+
+@dataclass(slots=True, frozen=True)
+class PromptData[T: SupportsDataclass]:
+    """Wrapper containing prompt outputs and their originating event."""
+
+    value: T
+    source: PromptExecuted
+
+
+type DataEvent = ToolData[SupportsDataclass] | PromptData[SupportsDataclass]
+
+type TypedReducer[S] = Callable[[tuple[S, ...], DataEvent], tuple[S, ...]]
+
+
+@dataclass(slots=True)
+class _ReducerRegistration:
+    reducer: TypedReducer[Any]
+    slice_type: type[Any]
+
+
+class Session:
+    """Collect dataclass payloads from prompt executions and tool invocations."""
+
+    def __init__(
+        self,
+        *,
+        bus: EventBus | None = None,
+        session_id: str | None = None,
+        created_at: str | None = None,
+    ) -> None:
+        self.session_id = session_id
+        self.created_at = created_at
+        self._bus = bus or NullEventBus()
+        self._reducers: dict[type[SupportsDataclass], list[_ReducerRegistration]] = {}
+        self._state: dict[type[Any], tuple[Any, ...]] = {}
+
+        if bus is not None:
+            bus.subscribe(ToolInvoked, self._on_tool_invoked)
+            bus.subscribe(PromptExecuted, self._on_prompt_executed)
+
+    def register_reducer[S](
+        self,
+        data_type: type[SupportsDataclass],
+        reducer: TypedReducer[S],
+        *,
+        slice_type: type[S] | None = None,
+    ) -> None:
+        """Register a reducer for the provided data type."""
+
+        target_slice_type: type[Any] = data_type if slice_type is None else slice_type
+        registration = _ReducerRegistration(
+            reducer=cast(TypedReducer[Any], reducer),
+            slice_type=target_slice_type,
+        )
+        bucket = self._reducers.setdefault(data_type, [])
+        bucket.append(registration)
+        self._state.setdefault(target_slice_type, ())
+
+    def select_all[S](self, slice_type: type[S]) -> tuple[S, ...]:
+        """Return the tuple slice maintained for the provided type."""
+
+        return cast(tuple[S, ...], self._state.get(slice_type, ()))
+
+    def _on_tool_invoked(self, event: object) -> None:
+        if isinstance(event, ToolInvoked):
+            self._handle_tool_invoked(event)
+
+    def _on_prompt_executed(self, event: object) -> None:
+        if isinstance(event, PromptExecuted):
+            self._handle_prompt_executed(event)
+
+    def _handle_tool_invoked(self, event: ToolInvoked) -> None:
+        payload = event.result.value
+        if not _is_dataclass_instance(payload):
+            return
+        dataclass_payload = cast(SupportsDataclass, payload)
+        data = ToolData(value=dataclass_payload, source=event)
+        self._dispatch_data_event(type(dataclass_payload), data)
+
+    def _handle_prompt_executed(self, event: PromptExecuted) -> None:
+        output = event.result.output
+        if _is_dataclass_instance(output):
+            dataclass_output = cast(SupportsDataclass, output)
+            data = PromptData(value=dataclass_output, source=event)
+            self._dispatch_data_event(type(dataclass_output), data)
+            return
+        if isinstance(output, Iterable) and not isinstance(output, (str, bytes)):
+            for item in cast(Iterable[object], output):
+                if _is_dataclass_instance(item):
+                    dataclass_item = cast(SupportsDataclass, item)
+                    data = PromptData(value=dataclass_item, source=event)
+                    self._dispatch_data_event(type(dataclass_item), data)
+
+    def _dispatch_data_event(
+        self, data_type: type[SupportsDataclass], event: DataEvent
+    ) -> None:
+        registrations = self._reducers.get(data_type)
+        if not registrations:
+            from .reducers import append
+
+            registrations = [
+                _ReducerRegistration(
+                    reducer=cast(TypedReducer[Any], append),
+                    slice_type=data_type,
+                )
+            ]
+
+        for registration in registrations:
+            slice_type = registration.slice_type
+            previous = self._state.get(slice_type, ())
+            try:
+                result = registration.reducer(previous, event)
+            except Exception:  # noqa: BLE001
+                logger.exception(
+                    "Reducer %r failed for data type %s",
+                    registration.reducer,
+                    data_type,
+                )
+                continue
+            normalized = tuple(result)
+            self._state[slice_type] = normalized
+
+
+def _is_dataclass_instance(value: object) -> bool:
+    return is_dataclass(value) and not isinstance(value, type)
+
+
+__all__ = [
+    "Session",
+    "ToolData",
+    "PromptData",
+    "DataEvent",
+    "TypedReducer",
+]

weakincentives/tools/__init__.py

@@ -0,0 +1,69 @@
+# 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.
+
+"""Public surface for built-in tool suites."""
+
+from __future__ import annotations
+
+from .errors import ToolValidationError
+from .planning import (
+    AddStep,
+    ClearPlan,
+    MarkStep,
+    NewPlanStep,
+    Plan,
+    PlanningToolsSection,
+    PlanStatus,
+    PlanStep,
+    ReadPlan,
+    SetupPlan,
+    StepStatus,
+    UpdateStep,
+)
+from .vfs import (
+    DeleteEntry,
+    HostMount,
+    ListDirectory,
+    ListDirectoryResult,
+    ReadFile,
+    VfsFile,
+    VfsPath,
+    VfsToolsSection,
+    VirtualFileSystem,
+    WriteFile,
+)
+
+__all__ = [
+    "ToolValidationError",
+    "Plan",
+    "PlanStep",
+    "PlanStatus",
+    "StepStatus",
+    "NewPlanStep",
+    "SetupPlan",
+    "AddStep",
+    "UpdateStep",
+    "MarkStep",
+    "ClearPlan",
+    "ReadPlan",
+    "PlanningToolsSection",
+    "VirtualFileSystem",
+    "VfsFile",
+    "VfsPath",
+    "HostMount",
+    "ListDirectory",
+    "ListDirectoryResult",
+    "ReadFile",
+    "WriteFile",
+    "DeleteEntry",
+    "VfsToolsSection",
+]

weakincentives/tools/errors.py

@@ -0,0 +1,22 @@
+# 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 error types for built-in tools."""
+
+from __future__ import annotations
+
+
+class ToolValidationError(ValueError):
+    """Raised when tool parameters fail validation checks."""
+
+
+__all__ = ["ToolValidationError"]