openai-sdk-helpers 0.0.8__py3-none-any.whl → 0.0.9__py3-none-any.whl

openai_sdk_helpers/response/config.py

@@ -0,0 +1,176 @@
+"""Module defining the ResponseConfiguration dataclass for managing OpenAI SDK responses."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Generic, Optional, Sequence, Type, TypeVar
+from openai.types.responses.response_text_config_param import ResponseTextConfigParam
+
+from ..config import OpenAISettings
+from ..structure.base import BaseStructure
+from ..response.base import BaseResponse, ToolHandler
+
+TIn = TypeVar("TIn", bound="BaseStructure")
+TOut = TypeVar("TOut", bound="BaseStructure")
+
+
+@dataclass(frozen=True, slots=True)
+class ResponseConfiguration(Generic[TIn, TOut]):
+    """
+    Represent an immutable configuration describing input and output structures.
+
+    Encapsulate all metadata required to define how a request is interpreted and
+    how a response is structured, while enforcing strict type and runtime safety.
+
+    Parameters
+    ----------
+    name : str
+        Unique configuration identifier. Must be a non-empty string.
+    instructions : str or Path
+        Plain text instructions or a path to a Jinja template file whose
+        contents are loaded at runtime.
+    tools : Sequence[object], optional
+        Tool definitions associated with the configuration. Default is None.
+    input_structure : Type[BaseStructure], optional
+        Structure class used to parse or validate input. Must subclass
+        BaseStructure. Default is None.
+    output_structure : Type[BaseStructure], optional
+        Structure class used to format or validate output. Schema is
+        automatically generated from this structure. Must subclass
+        BaseStructure. Default is None.
+
+    Raises
+    ------
+    TypeError
+        If name is not a non-empty string.
+        If instructions is not a string or Path.
+        If tools is provided and is not a sequence.
+        If input_structure or output_structure is not a class.
+        If input_structure or output_structure does not subclass BaseStructure.
+    ValueError
+        If instructions is a string that is empty or only whitespace.
+    FileNotFoundError
+        If instructions is a Path that does not point to a readable file.
+
+    Methods
+    -------
+    __post_init__()
+        Validate configuration invariants and enforce BaseStructure subclassing.
+    instructions_text
+        Return the resolved instruction content as a string.
+
+    Examples
+    --------
+    >>> config = Configuration(
+    ...     name="targeting_to_plan",
+    ...     tools=None,
+    ...     input_structure=PromptStructure,
+    ...     output_structure=WebSearchStructure,
+    ... )
+    >>> config.name
+    'prompt_to_websearch'
+    """
+
+    name: str
+    instructions: str | Path
+    tools: Optional[list]
+    input_structure: Optional[Type[TIn]]
+    output_structure: Optional[Type[TOut]]
+
+    def __post_init__(self) -> None:
+        """
+        Validate configuration invariants after initialization.
+
+        Enforce non-empty naming, correct typing of structures, and ensure that
+        any declared structure subclasses BaseStructure.
+
+        Raises
+        ------
+        TypeError
+            If name is not a non-empty string.
+            If tools is provided and is not a sequence.
+            If input_structure or output_structure is not a class.
+            If input_structure or output_structure does not subclass BaseStructure.
+        """
+        if not self.name or not isinstance(self.name, str):
+            raise TypeError("Configuration.name must be a non-empty str")
+
+        instructions_value = self.instructions
+        if isinstance(instructions_value, str):
+            if not instructions_value.strip():
+                raise ValueError("Configuration.instructions must be a non-empty str")
+        elif isinstance(instructions_value, Path):
+            instruction_path = instructions_value.expanduser()
+            if not instruction_path.is_file():
+                raise FileNotFoundError(
+                    f"Instruction template not found: {instruction_path}"
+                )
+        else:
+            raise TypeError("Configuration.instructions must be a str or Path")
+
+        for attr in ("input_structure", "output_structure"):
+            cls = getattr(self, attr)
+            if cls is None:
+                continue
+            if not isinstance(cls, type):
+                raise TypeError(
+                    f"Configuration.{attr} must be a class (Type[BaseStructure]) or None"
+                )
+            if not issubclass(cls, BaseStructure):
+                raise TypeError(f"Configuration.{attr} must subclass BaseStructure")
+
+        if self.tools is not None and not isinstance(self.tools, Sequence):
+            raise TypeError("Configuration.tools must be a Sequence or None")
+
+    @property
+    def instructions_text(self) -> str:
+        """Return the resolved instruction text.
+
+        Returns
+        -------
+        str
+            Plain-text instructions, loading template files when necessary.
+        """
+        return self._resolve_instructions()
+
+    def _resolve_instructions(self) -> str:
+        if isinstance(self.instructions, Path):
+            instruction_path = self.instructions.expanduser()
+            try:
+                return instruction_path.read_text(encoding="utf-8")
+            except OSError as exc:
+                raise ValueError(
+                    f"Unable to read instructions at '{instruction_path}': {exc}"
+                ) from exc
+        return self.instructions
+
+    def gen_response(
+        self,
+        openai_settings: OpenAISettings,
+        tool_handlers: dict[str, ToolHandler] = {},
+    ) -> BaseResponse[TOut]:
+        """Generate a BaseResponse instance based on the configuration.
+
+        Parameters
+        ----------
+        openai_settings : OpenAISettings
+            Authentication and model settings applied to the generated
+            :class:`BaseResponse`.
+        tool_handlers : dict[str, Callable], optional
+            Mapping of tool names to handler callables. Defaults to an empty
+            dictionary when not provided.
+
+        Returns
+        -------
+        BaseResponse[TOut]
+            An instance of BaseResponse configured with ``openai_settings``.
+        """
+        return BaseResponse[TOut](
+            name=self.name,
+            instructions=self.instructions_text,
+            tools=self.tools,
+            output_structure=self.output_structure,
+            tool_handlers=tool_handlers,
+            openai_settings=openai_settings,
+        )

openai_sdk_helpers/response/messages.py

@@ -1,10 +1,15 @@
-"""Message containers for shared OpenAI responses."""
+"""Message containers for OpenAI response conversations.
+
+This module provides dataclasses for managing conversation history including
+user inputs, assistant outputs, system messages, and tool calls. Messages are
+stored with timestamps and metadata, and can be serialized to JSON.
+"""
 
 from __future__ import annotations
 
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
-from typing import Dict, List, Union, cast
+from typing import cast
 
 from openai.types.responses.response_function_tool_call import ResponseFunctionToolCall
 from openai.types.responses.response_function_tool_call_param import (
@@ -25,12 +30,26 @@ from .tool_call import ResponseToolCall
 
 @dataclass
 class ResponseMessage(JSONSerializable):
-    """Single message exchanged with the OpenAI client.
+    """Single message exchanged with the OpenAI API.
+
+    Represents a complete message with role, content, timestamp, and
+    optional metadata. Can be serialized to JSON for persistence.
+
+    Attributes
+    ----------
+    role : str
+        Message role: "user", "assistant", "tool", or "system".
+    content : ResponseInputItemParam | ResponseOutputMessage | ResponseFunctionToolCallParam | FunctionCallOutput | ResponseInputMessageContentListParam
+        Message content in OpenAI format.
+    timestamp : datetime
+        UTC timestamp when the message was created.
+    metadata : dict[str, str | float | bool]
+        Optional metadata for tracking or debugging.
 
     Methods
     -------
     to_openai_format()
-        Return the payload in the format expected by the OpenAI client.
+        Return the message content in OpenAI API format.
     """
 
     role: str  # "user", "assistant", "tool", etc.
@@ -42,7 +61,7 @@ class ResponseMessage(JSONSerializable):
         | ResponseInputMessageContentListParam
     )
     timestamp: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
-    metadata: Dict[str, Union[str, float, bool]] = field(default_factory=dict)
+    metadata: dict[str, str | float | bool] = field(default_factory=dict)
 
     def to_openai_format(
         self,
@@ -65,10 +84,16 @@ class ResponseMessage(JSONSerializable):
 
 @dataclass
 class ResponseMessages(JSONSerializable):
-    """Represent a collection of messages in a response.
+    """Collection of messages in a conversation.
+
+    Manages the complete history of messages exchanged during an OpenAI
+    API interaction. Provides methods for adding different message types
+    and converting to formats required by the OpenAI API.
 
-    This dataclass encapsulates user inputs and assistant outputs during an
-    OpenAI API interaction.
+    Attributes
+    ----------
+    messages : list[ResponseMessage]
+        Ordered list of all messages in the conversation.
 
     Methods
     -------
@@ -81,10 +106,16 @@ class ResponseMessages(JSONSerializable):
     add_tool_message(content, output, **metadata)
         Record a tool call and its output.
     to_openai_payload()
-        Convert stored messages to the OpenAI input payload.
+        Convert stored messages to OpenAI input payload format.
+    get_last_assistant_message()
+        Return the most recent assistant message or None.
+    get_last_tool_message()
+        Return the most recent tool message or None.
+    get_last_user_message()
+        Return the most recent user message or None.
     """
 
-    messages: List[ResponseMessage] = field(default_factory=list)
+    messages: list[ResponseMessage] = field(default_factory=list)
 
     def add_system_message(
         self, content: ResponseInputMessageContentListParam, **metadata
@@ -97,10 +128,6 @@ class ResponseMessages(JSONSerializable):
             System message content in OpenAI format.
         **metadata
             Optional metadata to store with the message.
-
-        Returns
-        -------
-        None
         """
         response_input = cast(
             ResponseInputItemParam, {"role": "system", "content": content}
@@ -120,10 +147,6 @@ class ResponseMessages(JSONSerializable):
             Message payload supplied by the user.
         **metadata
             Optional metadata to store with the message.
-
-        Returns
-        -------
-        None
         """
         self.messages.append(
             ResponseMessage(role="user", content=input_content, metadata=metadata)
@@ -132,20 +155,16 @@ class ResponseMessages(JSONSerializable):
     def add_assistant_message(
         self,
         content: ResponseOutputMessage,
-        metadata: Dict[str, Union[str, float, bool]],
+        metadata: dict[str, str | float | bool],
     ) -> None:
         """Append an assistant message to the conversation.
 
         Parameters
         ----------
         content : ResponseOutputMessage
-            Assistant response message.
-        metadata : dict[str, Union[str, float, bool]]
+            Assistant response message from the OpenAI API.
+        metadata : dict[str, str | float | bool]
             Optional metadata to store with the message.
-
-        Returns
-        -------
-        None
         """
         self.messages.append(
             ResponseMessage(role="assistant", content=content, metadata=metadata)
@@ -154,20 +173,16 @@ class ResponseMessages(JSONSerializable):
     def add_tool_message(
         self, content: ResponseFunctionToolCall, output: str, **metadata
     ) -> None:
-        """Record a tool call and its output in the conversation history.
+        """Record a tool call and its output in the conversation.
 
         Parameters
         ----------
         content : ResponseFunctionToolCall
-            Tool call received from OpenAI.
+            Tool call received from the OpenAI API.
         output : str
-            JSON string returned by the executed tool.
+            JSON string returned by the executed tool handler.
         **metadata
             Optional metadata to store with the message.
-
-        Returns
-        -------
-        None
         """
         tool_call = ResponseToolCall(
             call_id=content.call_id,
@@ -187,24 +202,25 @@ class ResponseMessages(JSONSerializable):
 
     def to_openai_payload(
         self,
-    ) -> List[
+    ) -> list[
         ResponseInputItemParam
         | ResponseOutputMessage
         | ResponseFunctionToolCallParam
         | FunctionCallOutput
         | ResponseInputMessageContentListParam
     ]:
-        """Convert stored messages to the input payload expected by OpenAI.
-
-        Notes
-        -----
-        Assistant messages are model outputs and are not included in the
-        next request's input payload.
+        """Convert stored messages to OpenAI API input format.
 
         Returns
         -------
         list
-            List of message payloads excluding assistant outputs.
+            List of message payloads suitable for the OpenAI API.
+            Assistant messages are excluded as they are outputs, not inputs.
+
+        Notes
+        -----
+        Assistant messages are not included in the returned payload since
+        they represent model outputs rather than inputs for the next request.
         """
         return [
             msg.to_openai_format() for msg in self.messages if msg.role != "assistant"

openai_sdk_helpers/response/runner.py

@@ -1,10 +1,14 @@
-"""Convenience runners for response workflows."""
+"""Convenience functions for executing response workflows.
+
+This module provides high-level functions that handle the complete lifecycle
+of response workflows including instantiation, execution, and resource cleanup.
+They simplify common usage patterns for both synchronous and asynchronous contexts.
+"""
 
 from __future__ import annotations
 
 import asyncio
-
-from typing import Any, Optional, Type, TypeVar
+from typing import Any, TypeVar
 
 from .base import BaseResponse
 
@@ -13,26 +17,39 @@ R = TypeVar("R", bound=BaseResponse[Any])
 
 
 def run_sync(
-    response_cls: Type[R],
+    response_cls: type[R],
     *,
     content: str,
-    response_kwargs: Optional[dict[str, Any]] = None,
+    response_kwargs: dict[str, Any] | None = None,
 ) -> Any:
-    """Run a response workflow synchronously and close resources.
+    """Execute a response workflow synchronously with automatic cleanup.
+
+    Instantiates the response class, executes run_sync with the provided
+    content, and ensures cleanup occurs even if an exception is raised.
 
     Parameters
     ----------
-    response_cls
-        Response class to instantiate.
-    content
+    response_cls : type[BaseResponse]
+        Response class to instantiate for the workflow.
+    content : str
         Prompt text to send to the OpenAI API.
-    response_kwargs
-        Keyword arguments forwarded to ``response_cls``. Default ``None``.
+    response_kwargs : dict[str, Any] or None, default None
+        Optional keyword arguments forwarded to response_cls constructor.
 
     Returns
     -------
     Any
-        Parsed response from :meth:`BaseResponse.run_response`.
+        Parsed response from BaseResponse.run_sync, typically a structured
+        output or None.
+
+    Examples
+    --------
+    >>> from openai_sdk_helpers.response import run_sync
+    >>> result = run_sync(
+    ...     MyResponse,
+    ...     content="Analyze this text",
+    ...     response_kwargs={"openai_settings": settings}
+    ... )
     """
     response = response_cls(**(response_kwargs or {}))
     try:
@@ -42,26 +59,39 @@ def run_sync(
 
 
 async def run_async(
-    response_cls: Type[R],
+    response_cls: type[R],
     *,
     content: str,
-    response_kwargs: Optional[dict[str, Any]] = None,
+    response_kwargs: dict[str, Any] | None = None,
 ) -> Any:
-    """Run a response workflow asynchronously and close resources.
+    """Execute a response workflow asynchronously with automatic cleanup.
+
+    Instantiates the response class, executes run_async with the provided
+    content, and ensures cleanup occurs even if an exception is raised.
 
     Parameters
     ----------
-    response_cls
-        Response class to instantiate.
-    content
+    response_cls : type[BaseResponse]
+        Response class to instantiate for the workflow.
+    content : str
         Prompt text to send to the OpenAI API.
-    response_kwargs
-        Keyword arguments forwarded to ``response_cls``. Default ``None``.
+    response_kwargs : dict[str, Any] or None, default None
+        Optional keyword arguments forwarded to response_cls constructor.
 
     Returns
     -------
     Any
-        Parsed response from :meth:`BaseResponse.run_response_async`.
+        Parsed response from BaseResponse.run_async, typically a structured
+        output or None.
+
+    Examples
+    --------
+    >>> from openai_sdk_helpers.response import run_async
+    >>> result = await run_async(
+    ...     MyResponse,
+    ...     content="Summarize this document",
+    ...     response_kwargs={"openai_settings": settings}
+    ... )
     """
     response = response_cls(**(response_kwargs or {}))
     try:
@@ -71,30 +101,44 @@ async def run_async(
 
 
 def run_streamed(
-    response_cls: Type[R],
+    response_cls: type[R],
     *,
     content: str,
-    response_kwargs: Optional[dict[str, Any]] = None,
+    response_kwargs: dict[str, Any] | None = None,
 ) -> Any:
-    """Run a response workflow and return the asynchronous result.
+    """Execute a response workflow and return the awaited result.
 
-    This mirrors the agent API for discoverability. Streaming responses are not
-    currently supported by :class:`BaseResponse`, so this returns the same value
-    as :func:`run_async`.
+    Provides API compatibility with agent interfaces. Streaming responses
+    are not currently fully supported, so this executes run_async and
+    awaits the result.
 
     Parameters
     ----------
-    response_cls
-        Response class to instantiate.
-    content
+    response_cls : type[BaseResponse]
+        Response class to instantiate for the workflow.
+    content : str
         Prompt text to send to the OpenAI API.
-    response_kwargs
-        Keyword arguments forwarded to ``response_cls``. Default ``None``.
+    response_kwargs : dict[str, Any] or None, default None
+        Optional keyword arguments forwarded to response_cls constructor.
 
     Returns
     -------
     Any
-        Parsed response returned from :func:`run_async`.
+        Parsed response from run_async, typically a structured output or None.
+
+    Notes
+    -----
+    This function exists for API consistency but does not currently provide
+    true streaming functionality.
+
+    Examples
+    --------
+    >>> from openai_sdk_helpers.response import run_streamed
+    >>> result = run_streamed(
+    ...     MyResponse,
+    ...     content="Process this text",
+    ...     response_kwargs={"openai_settings": settings}
+    ... )
     """
     return asyncio.run(
         run_async(response_cls, content=content, response_kwargs=response_kwargs)

openai_sdk_helpers/response/tool_call.py

@@ -1,11 +1,15 @@
-"""Tool call representation for shared responses."""
+"""Tool call representation and argument parsing.
+
+This module provides data structures and utilities for managing tool calls
+in OpenAI response conversations, including conversion to OpenAI API formats
+and robust argument parsing.
+"""
 
 from __future__ import annotations
 
-from dataclasses import dataclass
-from typing import Tuple
-import json
 import ast
+import json
+from dataclasses import dataclass
 
 from openai.types.responses.response_function_tool_call_param import (
     ResponseFunctionToolCallParam,
@@ -15,23 +19,27 @@ from openai.types.responses.response_input_param import FunctionCallOutput
 
 @dataclass
 class ResponseToolCall:
-    """Container for tool call data used in a conversation.
+    """Container for tool call data in a conversation.
+
+    Stores the complete information about a tool invocation including
+    the call identifier, tool name, input arguments, and execution output.
+    Can convert to OpenAI API format for use in subsequent requests.
 
     Attributes
     ----------
     call_id : str
-        Identifier of the tool call.
+        Unique identifier for this tool call.
     name : str
-        Name of the tool invoked.
+        Name of the tool that was invoked.
     arguments : str
-        JSON string with the arguments passed to the tool.
+        JSON string containing the arguments passed to the tool.
     output : str
-        JSON string representing the result produced by the tool.
+        JSON string representing the result produced by the tool handler.
 
     Methods
     -------
     to_response_input_item_param()
-        Convert stored data into OpenAI tool call objects.
+        Convert to OpenAI API tool call format.
     """
 
     call_id: str
@@ -41,14 +49,28 @@ class ResponseToolCall:
 
     def to_response_input_item_param(
         self,
-    ) -> Tuple[ResponseFunctionToolCallParam, FunctionCallOutput]:
-        """Convert stored data into OpenAI tool call objects.
+    ) -> tuple[ResponseFunctionToolCallParam, FunctionCallOutput]:
+        """Convert stored data into OpenAI API tool call objects.
+
+        Creates the function call parameter and corresponding output object
+        required by the OpenAI API for tool interaction.
 
         Returns
         -------
         tuple[ResponseFunctionToolCallParam, FunctionCallOutput]
-            The function call object and the corresponding output object
-            suitable for inclusion in an OpenAI request.
+            A two-element tuple containing:
+            - ResponseFunctionToolCallParam: The function call representation
+            - FunctionCallOutput: The function output representation
+
+        Examples
+        --------
+        >>> tool_call = ResponseToolCall(
+        ...     call_id="call_123",
+        ...     name="search",
+        ...     arguments='{"query": "test"}',
+        ...     output='{"results": []}'
+        ... )
+        >>> func_call, func_output = tool_call.to_response_input_item_param()
         """
         from typing import cast
 
@@ -73,32 +95,34 @@ class ResponseToolCall:
 
 
 def parse_tool_arguments(arguments: str) -> dict:
-    """Parse tool call arguments which may not be valid JSON.
+    """Parse tool call arguments with fallback for malformed JSON.
 
-    The OpenAI API is expected to return well-formed JSON for tool arguments,
-    but minor formatting issues (such as the use of single quotes) can occur.
-    This helper first tries ``json.loads`` and falls back to
-    ``ast.literal_eval`` for simple cases.
+    Attempts to parse arguments as JSON first, then falls back to
+    ast.literal_eval for cases where the OpenAI API returns minor
+    formatting issues like single quotes instead of double quotes.
 
     Parameters
     ----------
-    arguments
-        Raw argument string from the tool call.
+    arguments : str
+        Raw argument string from a tool call, expected to be JSON.
 
     Returns
     -------
     dict
-        Parsed dictionary of arguments.
+        Parsed dictionary of tool arguments.
 
     Raises
     ------
     ValueError
-        If the arguments cannot be parsed as JSON.
+        If the arguments cannot be parsed as valid JSON or Python literal.
 
     Examples
     --------
-    >>> parse_tool_arguments('{"key": "value"}')["key"]
-    'value'
+    >>> parse_tool_arguments('{"key": "value"}')
+    {'key': 'value'}
+
+    >>> parse_tool_arguments("{'key': 'value'}")
+    {'key': 'value'}
     """
     try:
         return json.loads(arguments)