weakincentives 0.9.0__py3-none-any.whl

weakincentives/runtime/events/_types.py

@@ -0,0 +1,110 @@
+# 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 typing primitives for event integrations."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import TYPE_CHECKING, Protocol, cast, override
+from uuid import UUID, uuid4
+
+from ...prompt._types import SupportsDataclass
+from ...prompt.tool_result import ToolResult
+
+if TYPE_CHECKING:
+    from ...adapters._names import AdapterName
+
+EventHandler = Callable[[object], None]
+
+
+class EventBus(Protocol):
+    """Minimal synchronous publish/subscribe abstraction."""
+
+    def subscribe(self, event_type: type[object], handler: EventHandler) -> None:
+        """Register a handler for the given event type."""
+        ...
+
+    def publish(self, event: object) -> PublishResult:
+        """Publish an event instance to subscribers."""
+        ...
+
+
+@dataclass(slots=True, frozen=True)
+class HandlerFailure:
+    """Container describing a handler error captured during publish."""
+
+    handler: EventHandler
+    error: BaseException
+
+    @override
+    def __str__(self) -> str:
+        return f"{self.handler!r} -> {self.error!r}"
+
+
+@dataclass(slots=True, frozen=True)
+class PublishResult:
+    """Summary of an event publish invocation."""
+
+    event: object
+    handlers_invoked: tuple[EventHandler, ...]
+    errors: tuple[HandlerFailure, ...]
+    handled_count: int = field(init=False)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "handled_count", len(self.handlers_invoked))
+
+    @property
+    def ok(self) -> bool:
+        """Return ``True`` when no handler failures were recorded."""
+
+        return not self.errors
+
+    def raise_if_errors(self) -> None:
+        """Raise an ``ExceptionGroup`` if any handlers failed."""
+
+        if not self.errors:
+            return
+
+        failures = ", ".join(str(failure) for failure in self.errors)
+        message = f"Errors while publishing {type(self.event).__name__}: {failures}"
+        raise ExceptionGroup(
+            message,
+            tuple(cast(Exception, failure.error) for failure in self.errors),
+        )
+
+
+@dataclass(slots=True, frozen=True)
+class ToolInvoked:
+    """Event emitted after an adapter executes a tool handler."""
+
+    prompt_name: str
+    adapter: AdapterName
+    name: str
+    params: SupportsDataclass
+    result: ToolResult[object]
+    session_id: UUID | None
+    created_at: datetime
+    value: SupportsDataclass | None = None
+    call_id: str | None = None
+    event_id: UUID = field(default_factory=uuid4)
+
+
+__all__ = [
+    "EventBus",
+    "EventHandler",
+    "HandlerFailure",
+    "PublishResult",
+    "ToolInvoked",
+]

weakincentives/runtime/logging.py

@@ -0,0 +1,284 @@
+# 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.
+
+"""Structured logging helpers for :mod:`weakincentives`."""
+
+from __future__ import annotations
+
+import json
+import logging
+import logging.config
+import os
+from collections.abc import Mapping, MutableMapping
+from datetime import UTC, datetime
+from typing import Protocol, cast, override
+
+from ..types import JSONValue
+
+type StructuredLogPayload = Mapping[str, JSONValue]
+
+
+class SupportsLogMessage(Protocol):
+    """Protocol describing values that logging can stringify."""
+
+    @override
+    def __str__(self) -> str: ...
+
+
+__all__ = [
+    "JSONValue",
+    "StructuredLogPayload",
+    "StructuredLogger",
+    "SupportsLogMessage",
+    "configure_logging",
+    "get_logger",
+]
+
+_LOG_LEVEL_ENV = "WEAKINCENTIVES_LOG_LEVEL"
+_LOG_FORMAT_ENV = "WEAKINCENTIVES_LOG_FORMAT"
+_LEVEL_NAMES = {
+    "CRITICAL": logging.CRITICAL,
+    "ERROR": logging.ERROR,
+    "WARNING": logging.WARNING,
+    "INFO": logging.INFO,
+    "DEBUG": logging.DEBUG,
+    "NOTSET": logging.NOTSET,
+}
+
+
+class StructuredLogger(logging.LoggerAdapter[logging.Logger]):
+    """Logger adapter enforcing a minimal structured event schema."""
+
+    def __init__(
+        self,
+        logger: logging.Logger,
+        *,
+        context: StructuredLogPayload | None = None,
+    ) -> None:
+        base_context: dict[str, JSONValue] = (
+            dict(context) if context is not None else {}
+        )
+        super().__init__(logger, base_context)
+        self._context: dict[str, JSONValue] = base_context
+
+    def bind(self, **context: JSONValue) -> StructuredLogger:
+        """Return a new adapter with ``context`` merged into the baseline payload."""
+
+        merged: dict[str, JSONValue] = {**dict(self._context), **context}
+        return type(self)(self.logger, context=merged)
+
+    @override
+    def process(
+        self, msg: SupportsLogMessage, kwargs: MutableMapping[str, object]
+    ) -> tuple[SupportsLogMessage, MutableMapping[str, object]]:
+        extra_value = kwargs.setdefault("extra", {})
+        if extra_value is None:
+            extra_mapping: MutableMapping[str, JSONValue] = {}
+            kwargs["extra"] = extra_mapping
+        elif isinstance(extra_value, MutableMapping):
+            extra_mapping = cast(MutableMapping[str, JSONValue], extra_value)
+        else:  # pragma: no cover - defensive guard
+            raise TypeError(
+                "Structured logs require a mutable mapping for extra context."
+            )
+
+        context_payload: dict[str, JSONValue] = dict(self._context)
+
+        inline_context = kwargs.pop("context", None)
+        if inline_context is not None:
+            if isinstance(inline_context, Mapping):
+                context_payload.update(cast(StructuredLogPayload, inline_context))
+            else:  # pragma: no cover - defensive guard
+                raise TypeError("context must be a mapping when provided.")
+
+        for key in tuple(extra_mapping.keys()):
+            if key == "event":
+                continue
+            context_payload[key] = extra_mapping.pop(key)
+
+        event_obj = kwargs.pop("event", None)
+        if event_obj is None:
+            event_obj = extra_mapping.pop("event", None)
+        if not isinstance(event_obj, str):
+            raise TypeError("Structured logs require an 'event' field.")
+
+        extra_mapping.clear()
+        extra_mapping.update(
+            {
+                "event": event_obj,
+                "context": context_payload,
+            }
+        )
+        return msg, kwargs
+
+
+def get_logger(
+    name: str,
+    *,
+    logger_override: logging.Logger
+    | logging.LoggerAdapter[logging.Logger]
+    | None = None,
+    context: StructuredLogPayload | None = None,
+) -> StructuredLogger:
+    """Return a :class:`StructuredLogger` scoped to ``name``.
+
+    When ``logger_override`` is provided, the returned adapter reuses the supplied
+    logger and merges its contextual ``extra`` payload when available.
+    """
+
+    base_context: dict[str, JSONValue] = dict(context or {})
+    base_logger: logging.Logger
+
+    if isinstance(logger_override, StructuredLogger):
+        base_logger = logger_override.logger
+        base_context = {
+            **dict(cast(StructuredLogPayload, logger_override.extra)),
+            **base_context,
+        }
+    elif isinstance(logger_override, logging.Logger):
+        base_logger = logger_override
+    elif isinstance(logger_override, logging.LoggerAdapter):
+        base_logger = _unwrap_logger(cast(_SupportsNestedLogger, logger_override))
+        adapter_extra = getattr(logger_override, "extra", None)
+        if isinstance(adapter_extra, Mapping):
+            base_context = {
+                **dict(cast(StructuredLogPayload, adapter_extra)),
+                **base_context,
+            }
+    else:
+        base_logger = logging.getLogger(name)
+
+    return StructuredLogger(base_logger, context=base_context)
+
+
+def configure_logging(
+    *,
+    level: int | str | None = None,
+    json_mode: bool | None = None,
+    env: Mapping[str, str] | None = None,
+    force: bool = False,
+) -> None:
+    """Configure the root logger with sensible defaults.
+
+    ``level`` and ``json_mode`` can be supplied directly or via the
+    ``WEAKINCENTIVES_LOG_LEVEL`` and ``WEAKINCENTIVES_LOG_FORMAT`` environment
+    variables respectively (``json`` enables structured output, ``text`` keeps the
+    plain formatter).
+
+    The function avoids installing duplicate handlers when the host application has
+    already configured logging unless ``force=True`` is supplied.
+    """
+
+    env = env or os.environ
+
+    if level is not None:
+        resolved_level = _coerce_level(level)
+    else:
+        resolved_level = _coerce_level(env.get(_LOG_LEVEL_ENV))
+
+    if json_mode is None:
+        format_value = env.get(_LOG_FORMAT_ENV)
+        if format_value is not None:
+            json_mode = format_value.lower() == "json"
+        else:
+            json_mode = False
+
+    root_logger = logging.getLogger()
+
+    if root_logger.handlers and not force:
+        root_logger.setLevel(resolved_level)
+        return
+
+    formatter_key = "json" if json_mode else "text"
+    logging.config.dictConfig(
+        {
+            "version": 1,
+            "disable_existing_loggers": False,
+            "formatters": {
+                "text": {
+                    "format": "%(asctime)s %(levelname)s %(name)s %(event)s %(message)s %(context)s",
+                    "datefmt": "%Y-%m-%d %H:%M:%S",
+                },
+                "json": {
+                    "()": "weakincentives.runtime.logging._JsonFormatter",
+                },
+            },
+            "handlers": {
+                "stderr": {
+                    "class": "logging.StreamHandler",
+                    "stream": "ext://sys.stderr",
+                    "formatter": formatter_key,
+                }
+            },
+            "root": {
+                "handlers": ["stderr"],
+                "level": resolved_level,
+            },
+        }
+    )
+
+
+class _SupportsNestedLogger(Protocol):
+    logger: logging.Logger | logging.LoggerAdapter[logging.Logger]
+
+
+class _JsonFormatter(logging.Formatter):
+    """Formatter that renders structured records as compact JSON."""
+
+    @override
+    def format(self, record: logging.LogRecord) -> str:
+        payload: dict[str, JSONValue] = {
+            "timestamp": datetime.fromtimestamp(record.created, tz=UTC).isoformat(),
+            "level": record.levelname,
+            "logger": record.name,
+            "message": record.getMessage(),
+        }
+        event = getattr(record, "event", None)
+        if event is not None:
+            payload["event"] = event
+        context = getattr(record, "context", None)
+        if context:
+            payload["context"] = context
+        if record.exc_info:
+            payload["exc_info"] = self.formatException(record.exc_info)
+        return json.dumps(payload, default=_json_default, separators=(",", ":"))
+
+
+def _json_default(value: object) -> JSONValue:
+    """Fallback serializer returning ``repr`` for unsupported values."""
+
+    return repr(value)
+
+
+_JSON_FORMATTER_CLASS = _JsonFormatter
+
+
+def _unwrap_logger(adapter: _SupportsNestedLogger) -> logging.Logger:
+    """Return the underlying :class:`logging.Logger` from an adapter."""
+
+    logger_value = cast(object, adapter.logger)
+    if isinstance(logger_value, logging.LoggerAdapter):
+        return _unwrap_logger(cast(_SupportsNestedLogger, logger_value))
+    if isinstance(logger_value, logging.Logger):
+        return logger_value
+    raise TypeError("LoggerAdapter.logger must be a logging.Logger instance.")
+
+
+def _coerce_level(level: int | str | None) -> int:
+    if isinstance(level, int):
+        return level
+    if isinstance(level, str):
+        try:
+            return _LEVEL_NAMES[level.upper()]
+        except KeyError:  # pragma: no cover - defensive guard
+            raise TypeError(f"Unknown log level: {level!r}") from None
+    return logging.INFO

weakincentives/runtime/session/__init__.py

@@ -0,0 +1,46 @@
+# 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 ._types import ReducerContextProtocol, ReducerEvent, TypedReducer
+from .protocols import SessionProtocol, SnapshotProtocol
+from .reducer_context import ReducerContext, build_reducer_context
+from .reducers import append, replace_latest, upsert_by
+from .selectors import select_all, select_latest, select_where
+from .session import DataEvent, Session
+from .snapshots import (
+    Snapshot,
+    SnapshotRestoreError,
+    SnapshotSerializationError,
+)
+
+__all__ = [
+    "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",
+]

weakincentives/runtime/session/_slice_types.py

@@ -0,0 +1,24 @@
+# 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 slice typing helpers for :mod:`weakincentives.runtime.session`."""
+
+from __future__ import annotations
+
+from ...prompt._types import SupportsDataclass
+
+type SessionSliceType = type[SupportsDataclass]
+
+type SessionSlice = tuple[SupportsDataclass, ...]
+
+
+__all__ = ["SessionSlice", "SessionSliceType"]

weakincentives/runtime/session/_types.py

@@ -0,0 +1,55 @@
+# 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 typing helpers for session reducers."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, TypeVar
+
+from ...prompt._types import SupportsDataclass
+from ..events import EventBus
+
+if TYPE_CHECKING:
+    from .protocols import SessionProtocol
+
+
+class ReducerEvent(Protocol):
+    """Structural type satisfied by session data events."""
+
+    @property
+    def value(self) -> SupportsDataclass | None: ...
+
+
+S = TypeVar("S", bound=SupportsDataclass)
+
+
+class ReducerContextProtocol(Protocol):
+    """Protocol implemented by reducer context objects."""
+
+    session: SessionProtocol
+    event_bus: EventBus
+
+
+class TypedReducer(Protocol[S]):
+    """Protocol for reducer callables maintained by :class:`Session`."""
+
+    def __call__(
+        self,
+        slice_values: tuple[S, ...],
+        event: ReducerEvent,
+        *,
+        context: ReducerContextProtocol,
+    ) -> tuple[S, ...]: ...
+
+
+__all__ = ["ReducerContextProtocol", "ReducerEvent", "TypedReducer"]

weakincentives/runtime/session/dataclasses.py

@@ -0,0 +1,29 @@
+# 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.
+
+"""Dataclass helper utilities for session modules."""
+
+from __future__ import annotations
+
+from dataclasses import is_dataclass
+from typing import TypeGuard
+
+from ...prompt._types import SupportsDataclass
+
+
+def is_dataclass_instance(value: object) -> TypeGuard[SupportsDataclass]:
+    """Return ``True`` when ``value`` is a dataclass instance."""
+
+    return is_dataclass(value) and not isinstance(value, type)
+
+
+__all__ = ["is_dataclass_instance"]

weakincentives/runtime/session/protocols.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.
+
+"""Protocols describing Session behavior exposed to other modules."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from .snapshots import Snapshot
+
+type SnapshotProtocol = Snapshot
+
+
+class SessionProtocol(Protocol):
+    """Structural protocol implemented by session state containers."""
+
+    def snapshot(self) -> SnapshotProtocol: ...
+
+    def rollback(self, snapshot: SnapshotProtocol) -> None: ...
+
+    def reset(self) -> None: ...
+
+
+__all__ = ["SessionProtocol", "SnapshotProtocol"]

weakincentives/runtime/session/reducer_context.py

@@ -0,0 +1,40 @@
+# 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.
+
+"""Reducer context threaded through session reducer invocations."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ..events import EventBus
+from ._types import ReducerContextProtocol
+from .protocols import SessionProtocol
+
+
+@dataclass(slots=True, frozen=True)
+class ReducerContext(ReducerContextProtocol):
+    """Immutable bundle of runtime services shared with reducers."""
+
+    session: SessionProtocol
+    event_bus: EventBus
+
+
+def build_reducer_context(
+    *, session: SessionProtocol, event_bus: EventBus
+) -> ReducerContext:
+    """Return a :class:`ReducerContext` for the provided session and event bus."""
+
+    return ReducerContext(session=session, event_bus=event_bus)
+
+
+__all__ = ["ReducerContext", "build_reducer_context"]