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

weakincentives/adapters/openai.py

@@ -15,19 +15,25 @@
 from __future__ import annotations
 
 import json
+import re
 from collections.abc import Mapping, Sequence
 from importlib import import_module
-from typing import Any, Protocol, cast
-
-from ..prompts._types import SupportsDataclass
-from ..prompts.prompt import Prompt
-from ..prompts.structured import OutputParseError
-from ..prompts.structured import parse_output as parse_structured_output
-from ..prompts.tool import Tool
-from ..serde import dump, parse, schema
-from .core import PromptEvaluationError, PromptResponse, ToolCallRecord
+from typing import Any, Final, Literal, Protocol, cast
+
+from ..events import EventBus, PromptExecuted, ToolInvoked
+from ..prompt._types import SupportsDataclass
+from ..prompt.prompt import Prompt, RenderedPrompt
+from ..prompt.structured_output import (
+    ARRAY_WRAPPER_KEY,
+    OutputParseError,
+    parse_structured_output,
+)
+from ..prompt.tool import Tool, ToolResult
+from ..serde import parse, schema
+from ..tools.errors import ToolValidationError
+from .core import PromptEvaluationError, PromptResponse
 
-_ERROR_MESSAGE = (
+_ERROR_MESSAGE: Final[str] = (
     "OpenAI support requires the optional 'openai' dependency. "
     "Install it with `uv sync --extra openai` or `pip install weakincentives[openai]`."
 )
@@ -44,7 +50,7 @@ class _ToolCall(Protocol):
 
 
 class _Message(Protocol):
-    content: str | None
+    content: str | Sequence[object] | None
     tool_calls: Sequence[_ToolCall] | None
 
 
@@ -96,6 +102,10 @@ def create_openai_client(**kwargs: object) -> _OpenAIProtocol:
     return openai_module.OpenAI(**kwargs)
 
 
+ToolChoice = Literal["auto"] | Mapping[str, Any] | None
+"""Supported tool choice directives for provider APIs."""
+
+
 class OpenAIAdapter:
     """Adapter that evaluates prompts against OpenAI's Responses API."""
 
@@ -103,7 +113,8 @@ class OpenAIAdapter:
         self,
         *,
         model: str,
-        tool_choice: str | Mapping[str, Any] | None = "auto",
+        tool_choice: ToolChoice = "auto",
+        use_native_response_format: bool = True,
         client: _OpenAIProtocol | None = None,
         client_factory: _OpenAIClientFactory | None = None,
         client_kwargs: Mapping[str, object] | None = None,
@@ -123,25 +134,56 @@ class OpenAIAdapter:
 
         self._client = client
         self._model = model
-        self._tool_choice = tool_choice
+        self._tool_choice: ToolChoice = tool_choice
+        self._use_native_response_format = use_native_response_format
 
     def evaluate[OutputT](
         self,
         prompt: Prompt[OutputT],
         *params: SupportsDataclass,
         parse_output: bool = True,
+        bus: EventBus,
     ) -> PromptResponse[OutputT]:
         prompt_name = prompt.name or prompt.__class__.__name__
-        rendered = prompt.render(*params)  # type: ignore[reportArgumentType]
+
+        has_structured_output = (
+            getattr(prompt, "_output_type", None) is not None
+            and getattr(prompt, "_output_container", None) is not None
+        )
+        should_disable_instructions = (
+            parse_output
+            and has_structured_output
+            and self._use_native_response_format
+            and getattr(prompt, "inject_output_instructions", False)
+        )
+
+        if should_disable_instructions:
+            rendered = prompt.render(
+                *params,
+                inject_output_instructions=False,
+            )  # type: ignore[reportArgumentType]
+        else:
+            rendered = prompt.render(*params)  # type: ignore[reportArgumentType]
         messages: list[dict[str, Any]] = [
             {"role": "system", "content": rendered.text},
         ]
 
+        should_parse_structured_output = (
+            parse_output
+            and rendered.output_type is not None
+            and rendered.container is not None
+        )
+        response_format: dict[str, Any] | None = None
+        if should_parse_structured_output and self._use_native_response_format:
+            response_format = _build_json_schema_response_format(rendered, prompt_name)
+
         tools = list(rendered.tools)
         tool_specs = [_tool_to_openai_spec(tool) for tool in tools]
         tool_registry = {tool.name: tool for tool in tools}
-        tool_records: list[ToolCallRecord[Any, Any]] = []
+        tool_events: list[ToolInvoked] = []
         provider_payload: dict[str, Any] | None = None
+        # Allow forcing a specific tool once, then fall back to provider defaults.
+        next_tool_choice: ToolChoice = self._tool_choice
 
         while True:
             request_payload: dict[str, Any] = {
@@ -150,8 +192,10 @@ class OpenAIAdapter:
             }
             if tool_specs:
                 request_payload["tools"] = tool_specs
-                if self._tool_choice is not None:
-                    request_payload["tool_choice"] = self._tool_choice
+                if next_tool_choice is not None:
+                    request_payload["tool_choice"] = next_tool_choice
+            if response_format is not None:
+                request_payload["response_format"] = response_format
 
             try:
                 response = self._client.chat.completions.create(**request_payload)
@@ -159,7 +203,7 @@ class OpenAIAdapter:
                 raise PromptEvaluationError(
                     "OpenAI request failed.",
                     prompt_name=prompt_name,
-                    stage="request",
+                    phase="request",
                 ) from error
 
             provider_payload = _extract_payload(response)
@@ -168,33 +212,55 @@ class OpenAIAdapter:
             tool_calls = list(message.tool_calls or [])
 
             if not tool_calls:
-                final_text = message.content or ""
+                final_text = _message_text_content(message.content)
                 output: OutputT | None = None
                 text_value: str | None = final_text or None
 
-                if (
-                    parse_output
-                    and rendered.output_type is not None
-                    and rendered.output_container is not None
-                ):
-                    try:
-                        output = parse_structured_output(final_text, rendered)
-                    except OutputParseError as error:
-                        raise PromptEvaluationError(
-                            error.message,
-                            prompt_name=prompt_name,
-                            stage="response",
-                            provider_payload=provider_payload,
-                        ) from error
-                    text_value = None
-
-                return PromptResponse(
+                if should_parse_structured_output:
+                    parsed_payload = _extract_parsed_content(message)
+                    if parsed_payload is not None:
+                        try:
+                            output = cast(
+                                OutputT,
+                                _parse_schema_constrained_payload(
+                                    parsed_payload, rendered
+                                ),
+                            )
+                        except (TypeError, ValueError) as error:
+                            raise PromptEvaluationError(
+                                str(error),
+                                prompt_name=prompt_name,
+                                phase="response",
+                                provider_payload=provider_payload,
+                            ) from error
+                    else:
+                        try:
+                            output = parse_structured_output(final_text, rendered)
+                        except OutputParseError as error:
+                            raise PromptEvaluationError(
+                                error.message,
+                                prompt_name=prompt_name,
+                                phase="response",
+                                provider_payload=provider_payload,
+                            ) from error
+                    if output is not None:
+                        text_value = None
+
+                response = PromptResponse(
                     prompt_name=prompt_name,
                     text=text_value,
                     output=output,
-                    tool_results=tuple(tool_records),
+                    tool_results=tuple(tool_events),
                     provider_payload=provider_payload,
                 )
+                bus.publish(
+                    PromptExecuted(
+                        prompt_name=prompt_name,
+                        adapter="openai",
+                        result=cast(PromptResponse[object], response),
+                    )
+                )
+                return response
 
             assistant_tool_calls = [_serialize_tool_call(call) for call in tool_calls]
             messages.append(
@@ -213,14 +279,14 @@ class OpenAIAdapter:
                     raise PromptEvaluationError(
                         f"Unknown tool '{tool_name}' requested by provider.",
                         prompt_name=prompt_name,
-                        stage="tool",
+                        phase="tool",
                         provider_payload=provider_payload,
                     )
                 if tool.handler is None:
                     raise PromptEvaluationError(
                         f"Tool '{tool_name}' does not have a registered handler.",
                         prompt_name=prompt_name,
-                        stage="tool",
+                        phase="tool",
                         provider_payload=provider_payload,
                     )
 
@@ -240,42 +306,50 @@ class OpenAIAdapter:
                     raise PromptEvaluationError(
                         f"Failed to parse params for tool '{tool_name}'.",
                         prompt_name=prompt_name,
-                        stage="tool",
+                        phase="tool",
                         provider_payload=provider_payload,
                     ) from error
 
                 try:
                     tool_result = tool.handler(tool_params)
+                except ToolValidationError as error:
+                    tool_result = ToolResult(
+                        message=f"Tool validation failed: {error}",
+                        value=tool_params,
+                    )
                 except Exception as error:  # pragma: no cover - handler bug
                     raise PromptEvaluationError(
                         f"Tool '{tool_name}' raised an exception.",
                         prompt_name=prompt_name,
-                        stage="tool",
+                        phase="tool",
                         provider_payload=provider_payload,
                     ) from error
 
-                tool_records.append(
-                    ToolCallRecord(
-                        name=tool_name,
-                        params=tool_params,
-                        result=tool_result,
-                        call_id=getattr(tool_call, "id", None),
-                    )
+                invocation = ToolInvoked(
+                    prompt_name=prompt_name,
+                    adapter="openai",
+                    name=tool_name,
+                    params=tool_params,
+                    result=cast(ToolResult[object], tool_result),
+                    call_id=getattr(tool_call, "id", None),
                 )
+                tool_events.append(invocation)
+                bus.publish(invocation)
 
-                payload = dump(tool_result.payload, exclude_none=True)
-                tool_content = {
-                    "message": tool_result.message,
-                    "payload": payload,
-                }
                 messages.append(
                     {
                         "role": "tool",
                         "tool_call_id": getattr(tool_call, "id", None),
-                        "content": json.dumps(tool_content),
+                        "content": tool_result.message,
                     }
                 )
 
+            if isinstance(next_tool_choice, Mapping):
+                tool_choice_mapping = cast(Mapping[str, object], next_tool_choice)
+                if tool_choice_mapping.get("type") == "function":
+                    # Relax forced single-function choice after the first call.
+                    next_tool_choice = "auto"
+
 
 def _tool_to_openai_spec(tool: Tool[Any, Any]) -> dict[str, Any]:
     parameters_schema = schema(tool.params_type, extra="forbid")
@@ -306,6 +380,161 @@ def _extract_payload(response: _CompletionResponse) -> dict[str, Any] | None:
     return None
 
 
+def _build_json_schema_response_format(
+    rendered: RenderedPrompt[Any], prompt_name: str
+) -> dict[str, Any] | None:
+    output_type = rendered.output_type
+    container = rendered.container
+    allow_extra_keys = rendered.allow_extra_keys
+
+    if output_type is None or container is None:
+        return None
+
+    extra_mode: Literal["ignore", "forbid"] = "ignore" if allow_extra_keys else "forbid"
+    base_schema = schema(output_type, extra=extra_mode)
+    base_schema.pop("title", None)
+
+    if container == "array":
+        schema_payload = cast(
+            dict[str, Any],
+            {
+                "type": "object",
+                "properties": {
+                    ARRAY_WRAPPER_KEY: {
+                        "type": "array",
+                        "items": base_schema,
+                    }
+                },
+                "required": [ARRAY_WRAPPER_KEY],
+            },
+        )
+        if not allow_extra_keys:
+            schema_payload["additionalProperties"] = False
+    else:
+        schema_payload = base_schema
+
+    schema_name = _schema_name(prompt_name)
+    return {
+        "type": "json_schema",
+        "json_schema": {
+            "name": schema_name,
+            "schema": schema_payload,
+        },
+    }
+
+
+def _schema_name(prompt_name: str) -> str:
+    sanitized = re.sub(r"[^a-zA-Z0-9_-]+", "_", prompt_name.strip())
+    cleaned = sanitized.strip("_") or "prompt"
+    return f"{cleaned}_schema"
+
+
+def _message_text_content(content: object) -> str:
+    if isinstance(content, str) or content is None:
+        return content or ""
+    if isinstance(content, Sequence) and not isinstance(
+        content, (str, bytes, bytearray)
+    ):
+        fragments: list[str] = []
+        sequence_content = cast(Sequence[object], content)  # pyright: ignore[reportUnnecessaryCast]
+        for part in sequence_content:
+            fragments.append(_content_part_text(part))
+        return "".join(fragments)
+    return str(content)
+
+
+def _content_part_text(part: object) -> str:
+    if part is None:
+        return ""
+    if isinstance(part, Mapping):
+        mapping_part = cast(Mapping[str, object], part)
+        part_type = mapping_part.get("type")
+        if part_type in {"output_text", "text"}:
+            text_value = mapping_part.get("text")
+            if isinstance(text_value, str):
+                return text_value
+        return ""
+    part_type = getattr(part, "type", None)
+    if part_type in {"output_text", "text"}:
+        text_value = getattr(part, "text", None)
+        if isinstance(text_value, str):
+            return text_value
+    return ""
+
+
+def _extract_parsed_content(message: _Message) -> object | None:
+    parsed = getattr(message, "parsed", None)
+    if parsed is not None:
+        return parsed
+
+    content = message.content
+    if isinstance(content, Sequence) and not isinstance(
+        content, (str, bytes, bytearray)
+    ):
+        sequence_content = cast(Sequence[object], content)  # pyright: ignore[reportUnnecessaryCast]
+        for part in sequence_content:
+            payload = _parsed_payload_from_part(part)
+            if payload is not None:
+                return payload
+    return None
+
+
+def _parsed_payload_from_part(part: object) -> object | None:
+    if isinstance(part, Mapping):
+        mapping_part = cast(Mapping[str, object], part)
+        if mapping_part.get("type") == "output_json":
+            return mapping_part.get("json")
+        return None
+    part_type = getattr(part, "type", None)
+    if part_type == "output_json":
+        return getattr(part, "json", None)
+    return None
+
+
+def _parse_schema_constrained_payload(
+    payload: object, rendered: RenderedPrompt[Any]
+) -> object:
+    dataclass_type = rendered.output_type
+    container = rendered.container
+    allow_extra_keys = rendered.allow_extra_keys
+
+    if dataclass_type is None or container is None:
+        raise TypeError("Prompt does not declare structured output.")
+
+    extra_mode: Literal["ignore", "forbid"] = "ignore" if allow_extra_keys else "forbid"
+
+    if container == "object":
+        if not isinstance(payload, Mapping):
+            raise TypeError("Expected provider payload to be a JSON object.")
+        return parse(
+            dataclass_type, cast(Mapping[str, object], payload), extra=extra_mode
+        )
+
+    if container == "array":
+        if isinstance(payload, Mapping):
+            if ARRAY_WRAPPER_KEY not in payload:
+                raise TypeError("Expected provider payload to be a JSON array.")
+            payload = cast(Mapping[str, object], payload)[ARRAY_WRAPPER_KEY]
+        if not isinstance(payload, Sequence) or isinstance(
+            payload, (str, bytes, bytearray)
+        ):
+            raise TypeError("Expected provider payload to be a JSON array.")
+        parsed_items: list[object] = []
+        sequence_payload = cast(Sequence[object], payload)  # pyright: ignore[reportUnnecessaryCast]
+        for index, item in enumerate(sequence_payload):
+            if not isinstance(item, Mapping):
+                raise TypeError(f"Array item at index {index} is not an object.")
+            parsed_item = parse(
+                dataclass_type,
+                cast(Mapping[str, object], item),
+                extra=extra_mode,
+            )
+            parsed_items.append(parsed_item)
+        return parsed_items
+
+    raise TypeError("Unknown output container declared.")
+
+
 def _first_choice(
     response: _CompletionResponse, *, prompt_name: str
 ) -> _CompletionChoice:
@@ -315,7 +544,7 @@ def _first_choice(
         raise PromptEvaluationError(
             "Provider response did not include any choices.",
             prompt_name=prompt_name,
-            stage="response",
+            phase="response",
         ) from error
 
 
@@ -345,14 +574,14 @@ def _parse_tool_arguments(
         raise PromptEvaluationError(
             "Failed to decode tool call arguments.",
             prompt_name=prompt_name,
-            stage="tool",
+            phase="tool",
             provider_payload=provider_payload,
         ) from error
     if not isinstance(parsed, Mapping):
         raise PromptEvaluationError(
             "Tool call arguments must be a JSON object.",
             prompt_name=prompt_name,
-            stage="tool",
+            phase="tool",
             provider_payload=provider_payload,
         )
     return dict(cast(Mapping[str, Any], parsed))

weakincentives/events.py

@@ -0,0 +1,103 @@
+# 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
+
+import logging
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Protocol
+
+from .prompt._types import SupportsDataclass
+
+if TYPE_CHECKING:
+    from .adapters.core import PromptResponse
+    from .prompt.tool import ToolResult
+
+EventHandler = Callable[[object], None]
+
+logger = logging.getLogger(__name__)
+
+
+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) -> None:
+        """Publish an event instance to subscribers."""
+
+
+class NullEventBus:
+    """Event bus implementation that discards all events."""
+
+    def subscribe(self, event_type: type[object], handler: EventHandler) -> None:  # noqa: D401
+        """No-op subscription hook."""
+
+    def publish(self, event: object) -> None:  # noqa: D401
+        """Drop the provided event instance."""
+
+
+class InProcessEventBus:
+    """Process-local event bus that delivers events synchronously."""
+
+    def __init__(self) -> None:
+        self._handlers: dict[type[object], list[EventHandler]] = {}
+
+    def subscribe(self, event_type: type[object], handler: EventHandler) -> None:
+        handlers = self._handlers.setdefault(event_type, [])
+        handlers.append(handler)
+
+    def publish(self, event: object) -> None:
+        handlers = tuple(self._handlers.get(type(event), ()))
+        for handler in handlers:
+            try:
+                handler(event)
+            except Exception:  # noqa: BLE001
+                logger.exception(
+                    "Error delivering event %s to handler %r",
+                    type(event).__name__,
+                    handler,
+                )
+
+
+@dataclass(slots=True, frozen=True)
+class PromptExecuted:
+    """Event emitted after an adapter finishes evaluating a prompt."""
+
+    prompt_name: str
+    adapter: str
+    result: PromptResponse[object]
+
+
+@dataclass(slots=True, frozen=True)
+class ToolInvoked:
+    """Event emitted after an adapter executes a tool handler."""
+
+    prompt_name: str
+    adapter: str
+    name: str
+    params: SupportsDataclass
+    result: ToolResult[object]
+    call_id: str | None = None
+
+
+__all__ = [
+    "EventBus",
+    "InProcessEventBus",
+    "NullEventBus",
+    "PromptExecuted",
+    "ToolInvoked",
+]

weakincentives/examples/__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.
+
+"""Example scripts and shared utilities for the weakincentives project."""
+
+from .code_review_prompt import (
+    ReviewGuidance,
+    ReviewResponse,
+    ReviewTurnParams,
+    build_code_review_prompt,
+)
+from .code_review_session import (
+    CodeReviewSession,
+    SupportsReviewEvaluate,
+    ToolCallLog,
+)
+from .code_review_tools import (
+    MAX_OUTPUT_CHARS,
+    REPO_ROOT,
+    BranchListParams,
+    BranchListResult,
+    GitLogParams,
+    GitLogResult,
+    TagListParams,
+    TagListResult,
+    TimeQueryParams,
+    TimeQueryResult,
+    branch_list_handler,
+    build_tools,
+    current_time_handler,
+    git_log_handler,
+    tag_list_handler,
+)
+
+__all__ = [
+    "MAX_OUTPUT_CHARS",
+    "REPO_ROOT",
+    "BranchListParams",
+    "BranchListResult",
+    "GitLogParams",
+    "GitLogResult",
+    "TagListParams",
+    "TagListResult",
+    "TimeQueryParams",
+    "TimeQueryResult",
+    "ReviewGuidance",
+    "ReviewResponse",
+    "ReviewTurnParams",
+    "ToolCallLog",
+    "SupportsReviewEvaluate",
+    "CodeReviewSession",
+    "build_tools",
+    "build_code_review_prompt",
+    "git_log_handler",
+    "current_time_handler",
+    "branch_list_handler",
+    "tag_list_handler",
+]