weakincentives 0.9.0__py3-none-any.whl

weakincentives/__init__.py

@@ -0,0 +1,67 @@
+# 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.
+
+"""Curated public surface for :mod:`weakincentives`."""
+
+from __future__ import annotations
+
+from .adapters import PromptResponse
+from .dbc import (
+    dbc_active,
+    dbc_enabled,
+    ensure,
+    invariant,
+    pure,
+    require,
+    skip_invariant,
+)
+from .deadlines import Deadline
+from .prompt import (
+    MarkdownSection,
+    Prompt,
+    SupportsDataclass,
+    Tool,
+    ToolContext,
+    ToolHandler,
+    ToolResult,
+    parse_structured_output,
+)
+from .runtime import StructuredLogger, configure_logging, get_logger
+from .types import JSONValue
+
+__all__ = [
+    "Deadline",
+    "JSONValue",
+    "MarkdownSection",
+    "Prompt",
+    "PromptResponse",
+    "StructuredLogger",
+    "SupportsDataclass",
+    "Tool",
+    "ToolContext",
+    "ToolHandler",
+    "ToolResult",
+    "configure_logging",
+    "dbc_active",
+    "dbc_enabled",
+    "ensure",
+    "get_logger",
+    "invariant",
+    "parse_structured_output",
+    "pure",
+    "require",
+    "skip_invariant",
+]
+
+
+def __dir__() -> list[str]:
+    return sorted({*globals().keys(), *__all__})

weakincentives/adapters/__init__.py

@@ -0,0 +1,37 @@
+# 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.
+
+"""Integration adapters for optional third-party providers."""
+
+from __future__ import annotations
+
+from ._names import LITELLM_ADAPTER_NAME, OPENAI_ADAPTER_NAME, AdapterName
+from .core import (
+    PromptEvaluationError,
+    PromptResponse,
+    ProviderAdapter,
+    SessionProtocol,
+)
+
+__all__ = [
+    "LITELLM_ADAPTER_NAME",
+    "OPENAI_ADAPTER_NAME",
+    "AdapterName",
+    "PromptEvaluationError",
+    "PromptResponse",
+    "ProviderAdapter",
+    "SessionProtocol",
+]
+
+
+def __dir__() -> list[str]:
+    return sorted({*globals().keys(), *(__all__)})

weakincentives/adapters/_names.py

@@ -0,0 +1,32 @@
+# 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.
+
+"""Semantic adapter name definitions shared across provider integrations."""
+
+from __future__ import annotations
+
+from typing import Final, Literal
+
+AdapterName = Literal["openai", "litellm"]
+"""Recognized adapter identifiers for provider integrations."""
+
+OPENAI_ADAPTER_NAME: Final[AdapterName] = "openai"
+"""Canonical label for the OpenAI adapter."""
+
+LITELLM_ADAPTER_NAME: Final[AdapterName] = "litellm"
+"""Canonical label for the LiteLLM adapter."""
+
+__all__ = [
+    "LITELLM_ADAPTER_NAME",
+    "OPENAI_ADAPTER_NAME",
+    "AdapterName",
+]

weakincentives/adapters/_provider_protocols.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.
+
+"""Structural typing primitives shared across provider adapters."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Protocol
+
+__all__ = [
+    "ProviderChoice",
+    "ProviderCompletionCallable",
+    "ProviderCompletionResponse",
+    "ProviderFunctionCall",
+    "ProviderMessage",
+    "ProviderToolCall",
+]
+
+
+class ProviderFunctionCall(Protocol):
+    """Structural Protocol describing a provider function call payload."""
+
+    name: str
+    arguments: str | None
+
+
+class ProviderToolCall(Protocol):
+    """Structural Protocol describing a provider tool call payload."""
+
+    @property
+    def function(self) -> ProviderFunctionCall: ...
+
+
+class ProviderMessage(Protocol):
+    """Structural Protocol describing a provider message payload."""
+
+    content: str | Sequence[object] | None
+    tool_calls: Sequence[ProviderToolCall] | None
+
+
+class ProviderChoice(Protocol):
+    """Structural Protocol describing a provider choice payload."""
+
+    @property
+    def message(self) -> ProviderMessage: ...
+
+
+class ProviderCompletionResponse(Protocol):
+    """Structural Protocol describing a provider completion response."""
+
+    choices: Sequence[ProviderChoice]
+
+
+class ProviderCompletionCallable(Protocol):
+    """Structural Protocol describing a provider completion callable."""
+
+    def __call__(
+        self, *args: object, **kwargs: object
+    ) -> ProviderCompletionResponse: ...

weakincentives/adapters/_tool_messages.py

@@ -0,0 +1,80 @@
+# 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 helpers for serialising tool results into provider messages."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping, Sequence
+from dataclasses import is_dataclass
+from typing import Final, cast
+
+from ..prompt._types import SupportsToolResult
+from ..prompt.tool import ToolResult
+from ..serde import dump
+
+type JsonPrimitive = str | int | float | bool | None
+type JsonValue = JsonPrimitive | list["JsonValue"] | dict[str, "JsonValue"]
+
+_UNSET: Final = object()
+
+
+def serialize_tool_message(
+    result: ToolResult[SupportsToolResult], *, payload: object = _UNSET
+) -> str:
+    """Return a JSON string summarising a tool invocation for provider APIs."""
+
+    message_payload: dict[str, JsonValue | bool | str] = {
+        "message": result.message,
+        "success": result.success,
+    }
+
+    if not result.exclude_value_from_context:
+        value = result.value if payload is _UNSET else payload
+        if value is not None:
+            message_payload["payload"] = _serialize_value(value)
+
+    return json.dumps(message_payload, ensure_ascii=False)
+
+
+def _serialize_value(value: object) -> JsonValue:
+    """Convert tool result payloads to JSON-compatible structures."""
+
+    if is_dataclass(value):
+        return _serialize_str_mapping(dump(value, exclude_none=True))
+
+    if isinstance(value, Mapping):
+        return _serialize_mapping(cast(Mapping[object, object], value))
+
+    if isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray)):
+        sequence_items = cast(Sequence[object], value)
+        return [_serialize_value(item) for item in sequence_items]
+
+    if isinstance(value, (str, int, float, bool)) or value is None:
+        return value
+
+    return str(value)
+
+
+def _serialize_mapping(mapping: Mapping[object, object]) -> dict[str, JsonValue]:
+    serialized: dict[str, JsonValue] = {}
+    for key, item in mapping.items():
+        serialized[str(key)] = _serialize_value(item)
+    return serialized
+
+
+def _serialize_str_mapping(mapping: Mapping[str, object]) -> dict[str, JsonValue]:
+    return {key: _serialize_value(item) for key, item in mapping.items()}
+
+
+__all__ = ["serialize_tool_message"]

weakincentives/adapters/core.py

@@ -0,0 +1,102 @@
+# 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.
+
+"""Core adapter interfaces shared across provider integrations."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Literal, Protocol, TypeVar
+
+from ..deadlines import Deadline
+from ..prompt._types import SupportsDataclass
+from ..runtime.session.protocols import SessionProtocol
+
+if TYPE_CHECKING:
+    from ..prompt.overrides import PromptOverridesStore
+    from ..prompt.prompt import Prompt
+    from ..runtime.events._types import EventBus, ToolInvoked
+
+OutputT = TypeVar("OutputT")
+
+
+class ProviderAdapter(Protocol[OutputT]):
+    """Protocol describing the synchronous adapter contract."""
+
+    def evaluate(
+        self,
+        prompt: Prompt[OutputT],
+        *params: SupportsDataclass,
+        parse_output: bool = True,
+        bus: EventBus,
+        session: SessionProtocol,
+        deadline: Deadline | None = None,
+        overrides_store: PromptOverridesStore | None = None,
+        overrides_tag: str = "latest",
+    ) -> PromptResponse[OutputT]:
+        """Evaluate the prompt and return a structured response."""
+
+        ...
+
+
+@dataclass(slots=True)
+class PromptResponse[OutputT]:
+    """Structured result emitted by an adapter evaluation."""
+
+    prompt_name: str
+    text: str | None
+    output: OutputT | None
+    tool_results: tuple[ToolInvoked, ...]
+    provider_payload: dict[str, Any] | None = None
+
+
+class PromptEvaluationError(RuntimeError):
+    """Raised when evaluation against a provider fails."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        prompt_name: str,
+        phase: PromptEvaluationPhase,
+        provider_payload: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.prompt_name = prompt_name
+        self.phase: PromptEvaluationPhase = phase
+        self.provider_payload = provider_payload
+
+
+PromptEvaluationPhase = Literal["request", "response", "tool"]
+"""Phases where a prompt evaluation error can occur."""
+
+PROMPT_EVALUATION_PHASE_REQUEST: PromptEvaluationPhase = "request"
+"""Prompt evaluation failed while issuing the provider request."""
+
+PROMPT_EVALUATION_PHASE_RESPONSE: PromptEvaluationPhase = "response"
+"""Prompt evaluation failed while handling the provider response."""
+
+PROMPT_EVALUATION_PHASE_TOOL: PromptEvaluationPhase = "tool"
+"""Prompt evaluation failed while handling a tool invocation."""
+
+
+__all__ = [
+    "PROMPT_EVALUATION_PHASE_REQUEST",
+    "PROMPT_EVALUATION_PHASE_RESPONSE",
+    "PROMPT_EVALUATION_PHASE_TOOL",
+    "PromptEvaluationError",
+    "PromptEvaluationPhase",
+    "PromptResponse",
+    "ProviderAdapter",
+    "SessionProtocol",
+]

weakincentives/adapters/litellm.py

@@ -0,0 +1,254 @@
+# 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.
+
+"""Optional LiteLLM adapter utilities."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import replace
+from datetime import timedelta
+from importlib import import_module
+from typing import TYPE_CHECKING, Any, Final, Protocol, cast
+
+from ..deadlines import Deadline
+from ..prompt._types import SupportsDataclass
+from ..prompt.prompt import Prompt
+from ..runtime.events import EventBus
+from ..runtime.logging import StructuredLogger, get_logger
+from . import shared as _shared
+from ._provider_protocols import (
+    ProviderChoice,
+    ProviderCompletionCallable,
+    ProviderCompletionResponse,
+)
+from ._tool_messages import serialize_tool_message
+from .core import (
+    PROMPT_EVALUATION_PHASE_REQUEST,
+    PromptEvaluationError,
+    PromptResponse,
+    SessionProtocol,
+)
+from .shared import (
+    LITELLM_ADAPTER_NAME,
+    ToolChoice,
+    build_json_schema_response_format,
+    deadline_provider_payload,
+    first_choice,
+    format_publish_failures,
+    parse_tool_arguments,
+    run_conversation,
+)
+
+if TYPE_CHECKING:
+    from ..adapters.core import ProviderAdapter
+    from ..prompt.overrides import PromptOverridesStore
+
+_ERROR_MESSAGE: Final[str] = (
+    "LiteLLM support requires the optional 'litellm' dependency. "
+    "Install it with `uv sync --extra litellm` or `pip install weakincentives[litellm]`."
+)
+
+
+class _LiteLLMModule(Protocol):
+    def completion(
+        self, *args: object, **kwargs: object
+    ) -> ProviderCompletionResponse: ...
+
+
+class _LiteLLMCompletionFactory(Protocol):
+    def __call__(self, **kwargs: object) -> ProviderCompletionCallable: ...
+
+
+LiteLLMCompletion = ProviderCompletionCallable
+
+
+def _load_litellm_module() -> _LiteLLMModule:
+    try:
+        module = import_module("litellm")
+    except ModuleNotFoundError as exc:  # pragma: no cover - dependency guard
+        raise RuntimeError(_ERROR_MESSAGE) from exc
+    return cast(_LiteLLMModule, module)
+
+
+def create_litellm_completion(**kwargs: object) -> LiteLLMCompletion:
+    """Return a LiteLLM completion callable, guarding the optional dependency."""
+
+    module = _load_litellm_module()
+    if not kwargs:
+        return module.completion
+
+    def _wrapped_completion(
+        *args: object, **request_kwargs: object
+    ) -> ProviderCompletionResponse:
+        merged: dict[str, object] = dict(kwargs)
+        merged.update(request_kwargs)
+        return module.completion(*args, **merged)
+
+    return _wrapped_completion
+
+
+logger: StructuredLogger = get_logger(
+    __name__, context={"component": "adapter.litellm"}
+)
+
+
+class LiteLLMAdapter:
+    """Adapter that evaluates prompts via LiteLLM's completion helper."""
+
+    def __init__(
+        self,
+        *,
+        model: str,
+        tool_choice: ToolChoice = "auto",
+        completion: LiteLLMCompletion | None = None,
+        completion_factory: _LiteLLMCompletionFactory | None = None,
+        completion_kwargs: Mapping[str, object] | None = None,
+    ) -> None:
+        super().__init__()
+        if completion is not None:
+            if completion_factory is not None:
+                raise ValueError(
+                    "completion_factory cannot be provided when an explicit completion is supplied.",
+                )
+            if completion_kwargs:
+                raise ValueError(
+                    "completion_kwargs cannot be provided when an explicit completion is supplied.",
+                )
+        else:
+            factory = completion_factory or create_litellm_completion
+            completion = factory(**dict(completion_kwargs or {}))
+
+        self._completion = completion
+        self._model = model
+        self._tool_choice: ToolChoice = tool_choice
+
+    def evaluate[OutputT](
+        self,
+        prompt: Prompt[OutputT],
+        *params: SupportsDataclass,
+        parse_output: bool = True,
+        bus: EventBus,
+        session: SessionProtocol,
+        deadline: Deadline | None = None,
+        overrides_store: PromptOverridesStore | None = None,
+        overrides_tag: str = "latest",
+    ) -> PromptResponse[OutputT]:
+        prompt_name = prompt.name or prompt.__class__.__name__
+        render_inputs: tuple[SupportsDataclass, ...] = tuple(params)
+        if deadline is not None and deadline.remaining() <= timedelta(0):
+            raise PromptEvaluationError(
+                "Deadline expired before evaluation started.",
+                prompt_name=prompt_name,
+                phase=PROMPT_EVALUATION_PHASE_REQUEST,
+                provider_payload=deadline_provider_payload(deadline),
+            )
+        has_structured_output = prompt.structured_output is not None
+        should_disable_instructions = (
+            parse_output
+            and has_structured_output
+            and getattr(prompt, "inject_output_instructions", False)
+        )
+
+        if should_disable_instructions:
+            rendered = prompt.render(
+                *params,
+                overrides_store=overrides_store,
+                tag=overrides_tag,
+                inject_output_instructions=False,
+            )
+        else:
+            rendered = prompt.render(
+                *params,
+                overrides_store=overrides_store,
+                tag=overrides_tag,
+            )
+        if deadline is not None:
+            rendered = replace(rendered, deadline=deadline)
+        response_format: dict[str, Any] | None = None
+        should_parse_structured_output = (
+            parse_output
+            and rendered.output_type is not None
+            and rendered.container is not None
+        )
+        if should_parse_structured_output:
+            response_format = build_json_schema_response_format(rendered, prompt_name)
+
+        def _call_provider(
+            messages: list[dict[str, Any]],
+            tool_specs: Sequence[Mapping[str, Any]],
+            tool_choice_directive: ToolChoice | None,
+            response_format_payload: Mapping[str, Any] | None,
+        ) -> object:
+            request_payload: dict[str, Any] = {
+                "model": self._model,
+                "messages": messages,
+            }
+            if tool_specs:
+                request_payload["tools"] = list(tool_specs)
+                if tool_choice_directive is not None:
+                    request_payload["tool_choice"] = tool_choice_directive
+            if response_format_payload is not None:
+                request_payload["response_format"] = response_format_payload
+
+            try:
+                return self._completion(**request_payload)
+            except Exception as error:  # pragma: no cover - network/SDK failure
+                raise PromptEvaluationError(
+                    "LiteLLM request failed.",
+                    prompt_name=prompt_name,
+                    phase=PROMPT_EVALUATION_PHASE_REQUEST,
+                ) from error
+
+        def _select_choice(response: object) -> ProviderChoice:
+            return cast(
+                ProviderChoice,
+                first_choice(response, prompt_name=prompt_name),
+            )
+
+        return run_conversation(
+            adapter_name=LITELLM_ADAPTER_NAME,
+            adapter=cast("ProviderAdapter[OutputT]", self),
+            prompt=prompt,
+            prompt_name=prompt_name,
+            rendered=rendered,
+            render_inputs=render_inputs,
+            initial_messages=[{"role": "system", "content": rendered.text}],
+            parse_output=parse_output,
+            bus=bus,
+            session=session,
+            tool_choice=self._tool_choice,
+            response_format=response_format,
+            require_structured_output_text=True,
+            call_provider=_call_provider,
+            select_choice=_select_choice,
+            serialize_tool_message_fn=serialize_tool_message,
+            format_publish_failures=format_publish_failures,
+            parse_arguments=parse_tool_arguments,
+            logger_override=logger,
+            deadline=deadline,
+        )
+
+
+__all__ = [
+    "LiteLLMAdapter",
+    "LiteLLMCompletion",
+    "create_litellm_completion",
+    "extract_parsed_content",
+    "message_text_content",
+    "parse_schema_constrained_payload",
+]
+
+
+message_text_content = _shared.message_text_content
+extract_parsed_content = _shared.extract_parsed_content
+parse_schema_constrained_payload = _shared.parse_schema_constrained_payload