openai-sdk-helpers 0.2.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

openai_sdk_helpers/response/config.py

@@ -5,35 +5,23 @@ 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
-from ..utils import JSONSerializable
-from ..utils.path_utils import ensure_directory
+from ..structure.base import StructureBase
+from ..response.base import ResponseBase, ToolHandler
+from ..utils.json.data_class import DataclassJSONSerializable
+from ..utils.registry import BaseRegistry
+from ..utils.instructions import resolve_instructions_from_path
 
-TIn = TypeVar("TIn", bound="BaseStructure")
-TOut = TypeVar("TOut", bound="BaseStructure")
+TIn = TypeVar("TIn", bound="StructureBase")
+TOut = TypeVar("TOut", bound="StructureBase")
 
 
-class ResponseRegistry:
+class ResponseRegistry(BaseRegistry["ResponseConfiguration"]):
     """Registry for managing ResponseConfiguration instances.
 
-    Provides centralized storage and retrieval of response configurations,
-    enabling reusable response specs across the application. Configurations
-    are stored by name and can be retrieved or listed as needed.
-
-    Methods
-    -------
-    register(config)
-        Add a ResponseConfiguration to the registry.
-    get(name)
-        Retrieve a configuration by name.
-    list_names()
-        Return all registered configuration names.
-    clear()
-        Remove all registered configurations.
+    Inherits from BaseRegistry to provide centralized storage and retrieval
+    of response configurations, enabling reusable response specs across the application.
 
     Examples
     --------
@@ -51,134 +39,7 @@ class ResponseRegistry:
     'test'
     """
 
-    def __init__(self) -> None:
-        """Initialize an empty registry."""
-        self._configs: dict[str, ResponseConfiguration] = {}
-
-    def register(self, config: ResponseConfiguration) -> None:
-        """Add a ResponseConfiguration to the registry.
-
-        Parameters
-        ----------
-        config : ResponseConfiguration
-            Configuration to register.
-
-        Raises
-        ------
-        ValueError
-            If a configuration with the same name is already registered.
-
-        Examples
-        --------
-        >>> registry = ResponseRegistry()
-        >>> config = ResponseConfiguration(...)
-        >>> registry.register(config)
-        """
-        if config.name in self._configs:
-            raise ValueError(
-                f"Configuration '{config.name}' is already registered. "
-                "Use a unique name or clear the registry first."
-            )
-        self._configs[config.name] = config
-
-    def get(self, name: str) -> ResponseConfiguration:
-        """Retrieve a configuration by name.
-
-        Parameters
-        ----------
-        name : str
-            Configuration name to look up.
-
-        Returns
-        -------
-        ResponseConfiguration
-            The registered configuration.
-
-        Raises
-        ------
-        KeyError
-            If no configuration with the given name exists.
-
-        Examples
-        --------
-        >>> registry = ResponseRegistry()
-        >>> config = registry.get("test")
-        """
-        if name not in self._configs:
-            raise KeyError(
-                f"No configuration named '{name}' found. "
-                f"Available: {list(self._configs.keys())}"
-            )
-        return self._configs[name]
-
-    def list_names(self) -> list[str]:
-        """Return all registered configuration names.
-
-        Returns
-        -------
-        list[str]
-            Sorted list of configuration names.
-
-        Examples
-        --------
-        >>> registry = ResponseRegistry()
-        >>> registry.list_names()
-        []
-        """
-        return sorted(self._configs.keys())
-
-    def clear(self) -> None:
-        """Remove all registered configurations.
-
-        Examples
-        --------
-        >>> registry = ResponseRegistry()
-        >>> registry.clear()
-        """
-        self._configs.clear()
-
-    def save_to_directory(self, path: Path | str) -> None:
-        """Export all registered configurations to JSON files in a directory.
-
-        Serializes each registered ResponseConfiguration to an individual JSON file
-        named after the configuration. Creates the directory if it does not exist.
-
-        Parameters
-        ----------
-        path : Path or str
-            Directory path where JSON files will be saved. Will be created if
-            it does not already exist.
-
-        Returns
-        -------
-        None
-
-        Raises
-        ------
-        OSError
-            If the directory cannot be created or files cannot be written.
-
-        Examples
-        --------
-        >>> registry = ResponseRegistry()
-        >>> registry.save_to_directory("./data")
-        >>> registry.save_to_directory(Path("exports"))
-        """
-        dir_path = ensure_directory(Path(path))
-        config_names = self.list_names()
-
-        if not config_names:
-            return
-
-        for config_name in config_names:
-            config = self.get(config_name)
-            filename = f"{config_name}.json"
-            filepath = dir_path / filename
-            config.to_json_file(filepath)
-
-
-# Global default registry instance
-_default_registry = ResponseRegistry()
+    pass
 
 
 def get_default_registry() -> ResponseRegistry:
@@ -199,13 +60,13 @@ def get_default_registry() -> ResponseRegistry:
 
 
 @dataclass(frozen=True, slots=True)
-class ResponseConfiguration(JSONSerializable, Generic[TIn, TOut]):
+class ResponseConfiguration(DataclassJSONSerializable, 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.
-    Inherits from JSONSerializable to support serialization to JSON format.
+    Inherits from DataclassJSONSerializable to support serialization to JSON format.
 
     Parameters
     ----------
@@ -216,13 +77,13 @@ class ResponseConfiguration(JSONSerializable, Generic[TIn, TOut]):
         contents are loaded at runtime.
     tools : Sequence[object], optional
         Tool definitions associated with the configuration. Default is None.
-    input_structure : Type[BaseStructure], optional
+    input_structure : Type[StructureBase], optional
         Structure class used to parse or validate input. Must subclass
-        BaseStructure. Default is None.
-    output_structure : Type[BaseStructure], optional
+        StructureBase. Default is None.
+    output_structure : Type[StructureBase], optional
         Structure class used to format or validate output. Schema is
         automatically generated from this structure. Must subclass
-        BaseStructure. Default is None.
+        StructureBase. Default is None.
     system_vector_store : list[str], optional
         Optional list of vector store names to attach as system context.
         Default is None.
@@ -237,7 +98,7 @@ class ResponseConfiguration(JSONSerializable, Generic[TIn, TOut]):
         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.
+        If input_structure or output_structure does not subclass StructureBase.
     ValueError
         If instructions is a string that is empty or only whitespace.
     FileNotFoundError
@@ -246,7 +107,7 @@ class ResponseConfiguration(JSONSerializable, Generic[TIn, TOut]):
     Methods
     -------
     __post_init__()
-        Validate configuration invariants and enforce BaseStructure subclassing.
+        Validate configuration invariants and enforce StructureBase subclassing.
     instructions_text
         Return the resolved instruction content as a string.
     to_json()
@@ -276,14 +137,14 @@ class ResponseConfiguration(JSONSerializable, Generic[TIn, TOut]):
     input_structure: Optional[Type[TIn]]
     output_structure: Optional[Type[TOut]]
     system_vector_store: Optional[list[str]] = None
-    data_path: Optional[Path | str] = None
+    add_output_instructions: bool = True
 
     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.
+        any declared structure subclasses StructureBase.
 
         Raises
         ------
@@ -291,7 +152,7 @@ class ResponseConfiguration(JSONSerializable, Generic[TIn, TOut]):
             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 input_structure or output_structure does not subclass StructureBase.
         """
         if not self.name or not isinstance(self.name, str):
             raise TypeError("Configuration.name must be a non-empty str")
@@ -315,10 +176,10 @@ class ResponseConfiguration(JSONSerializable, Generic[TIn, TOut]):
                 continue
             if not isinstance(cls, type):
                 raise TypeError(
-                    f"Configuration.{attr} must be a class (Type[BaseStructure]) or None"
+                    f"Configuration.{attr} must be a class (Type[StructureBase]) or None"
                 )
-            if not issubclass(cls, BaseStructure):
-                raise TypeError(f"Configuration.{attr} must subclass BaseStructure")
+            if not issubclass(cls, StructureBase):
+                raise TypeError(f"Configuration.{attr} must subclass StructureBase")
 
         if self.tools is not None and not isinstance(self.tools, Sequence):
             raise TypeError("Configuration.tools must be a Sequence or None")
@@ -332,62 +193,51 @@ class ResponseConfiguration(JSONSerializable, Generic[TIn, TOut]):
         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
+        resolved_instructions: str = resolve_instructions_from_path(self.instructions)
+        output_instructions = ""
+        if self.output_structure is not None and self.add_output_instructions:
+            output_instructions = self.output_structure.get_prompt(
+                add_enum_values=False
+            )
+            if output_instructions:
+                return f"{resolved_instructions}\n{output_instructions}"
+
+        return resolved_instructions
 
     def gen_response(
         self,
+        *,
         openai_settings: OpenAISettings,
-        tool_handlers: dict[str, ToolHandler] = {},
-        add_output_instructions: bool = True,
-    ) -> BaseResponse[TOut]:
-        """Generate a BaseResponse instance based on the configuration.
+        data_path: Optional[Path] = None,
+        tool_handlers: dict[str, ToolHandler] | None = None,
+    ) -> ResponseBase[TOut]:
+        """Generate a ResponseBase instance based on the configuration.
 
         Parameters
         ----------
         openai_settings : OpenAISettings
             Authentication and model settings applied to the generated
-            :class:`BaseResponse`.
+            :class:`ResponseBase`.
         tool_handlers : dict[str, Callable], optional
             Mapping of tool names to handler callables. Defaults to an empty
             dictionary when not provided.
-        add_output_instructions : bool, default=True
-            Whether to append the structured output prompt to the instructions.
 
         Returns
         -------
-        BaseResponse[TOut]
-            An instance of BaseResponse configured with ``openai_settings``.
+        ResponseBase[TOut]
+            An instance of ResponseBase configured with ``openai_settings``.
         """
-        output_instructions = ""
-        if self.output_structure is not None and add_output_instructions:
-            output_instructions = self.output_structure.get_prompt(
-                add_enum_values=False
-            )
-
-        instructions = (
-            f"{self.instructions_text}\n{output_instructions}"
-            if output_instructions
-            else self.instructions_text
-        )
-
-        return BaseResponse[TOut](
+        return ResponseBase[TOut](
             name=self.name,
-            instructions=instructions,
+            instructions=self.instructions_text,
             tools=self.tools,
             output_structure=self.output_structure,
             system_vector_store=self.system_vector_store,
-            data_path=self.data_path,
+            data_path=data_path,
             tool_handlers=tool_handlers,
             openai_settings=openai_settings,
         )
+
+
+# Global default registry instance
+_default_registry = ResponseRegistry()

openai_sdk_helpers/response/files.py

@@ -23,11 +23,11 @@ from openai.types.responses.response_input_image_content_param import (
 from ..utils import create_file_data_url, create_image_data_url, is_image_file, log
 
 if TYPE_CHECKING:  # pragma: no cover
-    from .base import BaseResponse
+    from .base import ResponseBase
 
 
 def process_files(
-    response: BaseResponse[Any],
+    response: ResponseBase[Any],
     files: list[str],
     use_vector_store: bool = False,
     batch_size: int = 10,
@@ -45,7 +45,7 @@ def process_files(
 
     Parameters
     ----------
-    response : BaseResponse[Any]
+    response : ResponseBase[Any]
         Response instance that will use the processed files.
     files : list[str]
         List of file paths to process.
@@ -114,7 +114,7 @@ def process_files(
 
 
 def _upload_to_vector_store(
-    response: BaseResponse[Any], document_files: list[str]
+    response: ResponseBase[Any], document_files: list[str]
 ) -> list[ResponseInputFileParam]:
     """Upload documents to vector store and return file references.
 
@@ -123,7 +123,7 @@ def _upload_to_vector_store(
 
     Parameters
     ----------
-    response : BaseResponse[Any]
+    response : ResponseBase[Any]
         Response instance with vector storage.
     document_files : list[str]
         List of document file paths to upload.

openai_sdk_helpers/response/messages.py

@@ -24,12 +24,12 @@ from openai.types.responses.response_input_param import (
 )
 from openai.types.responses.response_output_message import ResponseOutputMessage
 
-from ..utils import JSONSerializable
+from ..utils.json.data_class import DataclassJSONSerializable
 from .tool_call import ResponseToolCall
 
 
 @dataclass
-class ResponseMessage(JSONSerializable):
+class ResponseMessage(DataclassJSONSerializable):
     """Single message exchanged with the OpenAI API.
 
     Represents a complete message with role, content, timestamp, and
@@ -91,7 +91,7 @@ class ResponseMessage(JSONSerializable):
 
 
 @dataclass
-class ResponseMessages(JSONSerializable):
+class ResponseMessages(DataclassJSONSerializable):
     """Collection of messages in a conversation.
 
     Manages the complete history of messages exchanged during an OpenAI

openai_sdk_helpers/response/runner.py

@@ -10,10 +10,10 @@ from __future__ import annotations
 import asyncio
 from typing import Any, TypeVar
 
-from .base import BaseResponse
+from .base import ResponseBase
 
 
-R = TypeVar("R", bound=BaseResponse[Any])
+R = TypeVar("R", bound=ResponseBase[Any])
 
 
 def run_sync(
@@ -29,7 +29,7 @@ def run_sync(
 
     Parameters
     ----------
-    response_cls : type[BaseResponse]
+    response_cls : type[ResponseBase]
         Response class to instantiate for the workflow.
     content : str
         Prompt text to send to the OpenAI API.
@@ -39,7 +39,7 @@ def run_sync(
     Returns
     -------
     Any
-        Parsed response from BaseResponse.run_sync, typically a structured
+        Parsed response from ResponseBase.run_sync, typically a structured
         output or None.
 
     Examples
@@ -71,7 +71,7 @@ async def run_async(
 
     Parameters
     ----------
-    response_cls : type[BaseResponse]
+    response_cls : type[ResponseBase]
         Response class to instantiate for the workflow.
     content : str
         Prompt text to send to the OpenAI API.
@@ -81,7 +81,7 @@ async def run_async(
     Returns
     -------
     Any
-        Parsed response from BaseResponse.run_async, typically a structured
+        Parsed response from ResponseBase.run_async, typically a structured
         output or None.
 
     Examples
@@ -114,7 +114,7 @@ def run_streamed(
 
     Parameters
     ----------
-    response_cls : type[BaseResponse]
+    response_cls : type[ResponseBase]
         Response class to instantiate for the workflow.
     content : str
         Prompt text to send to the OpenAI API.

openai_sdk_helpers/response/tool_call.py

@@ -9,16 +9,18 @@ from __future__ import annotations
 
 import ast
 import json
+import re
 from dataclasses import dataclass
 
 from openai.types.responses.response_function_tool_call_param import (
     ResponseFunctionToolCallParam,
 )
 from openai.types.responses.response_input_param import FunctionCallOutput
+from ..utils.json.data_class import DataclassJSONSerializable
 
 
 @dataclass
-class ResponseToolCall:
+class ResponseToolCall(DataclassJSONSerializable):
     """Container for tool call data in a conversation.
 
     Stores the complete information about a tool invocation including
@@ -94,6 +96,85 @@ class ResponseToolCall:
         return function_call, function_call_output
 
 
+def _to_snake_case(name: str) -> str:
+    """Convert a PascalCase or camelCase string to snake_case.
+
+    Parameters
+    ----------
+    name : str
+        The name to convert.
+
+    Returns
+    -------
+    str
+        The snake_case version of the name.
+
+    Examples
+    --------
+    >>> _to_snake_case("ExampleStructure")
+    'example_structure'
+    >>> _to_snake_case("MyToolName")
+    'my_tool_name'
+    """
+    # First regex: Insert underscore before uppercase letters followed by
+    # lowercase letters (e.g., "Tool" in "ExampleTool" becomes "_Tool")
+    s1 = re.sub("(.)([A-Z][a-z]+)", r"\1_\2", name)
+    # Second regex: Insert underscore between lowercase/digit and uppercase
+    # (e.g., "e3" followed by "T" becomes "e3_T")
+    return re.sub("([a-z0-9])([A-Z])", r"\1_\2", s1).lower()
+
+
+def _unwrap_arguments(parsed: dict, tool_name: str) -> dict:
+    """Unwrap arguments if wrapped in a single-key dict.
+
+    Some responses wrap arguments under a key matching the structure class
+    name (e.g., {"ExampleStructure": {...}}) or snake_case variant
+    (e.g., {"example_structure": {...}}). This function detects and unwraps
+    such wrappers to normalize the payload.
+
+    Parameters
+    ----------
+    parsed : dict
+        The parsed arguments dictionary.
+    tool_name : str
+        The tool name, used to match potential wrapper keys.
+
+    Returns
+    -------
+    dict
+        Unwrapped arguments dictionary, or original if no wrapper detected.
+
+    Examples
+    --------
+    >>> _unwrap_arguments({"ExampleTool": {"arg": "value"}}, "ExampleTool")
+    {'arg': 'value'}
+    >>> _unwrap_arguments({"example_tool": {"arg": "value"}}, "ExampleTool")
+    {'arg': 'value'}
+    >>> _unwrap_arguments({"arg": "value"}, "ExampleTool")
+    {'arg': 'value'}
+    """
+    # Only unwrap if dict has exactly one key
+    if not isinstance(parsed, dict) or len(parsed) != 1:
+        return parsed
+
+    wrapper_key = next(iter(parsed))
+    wrapped_value = parsed[wrapper_key]
+
+    # Only unwrap if the value is also a dict
+    if not isinstance(wrapped_value, dict):
+        return parsed
+
+    # Check if wrapper key matches tool name (case-insensitive or snake_case)
+    tool_name_lower = tool_name.lower()
+    tool_name_snake = _to_snake_case(tool_name)
+    wrapper_key_lower = wrapper_key.lower()
+
+    if wrapper_key_lower in (tool_name_lower, tool_name_snake):
+        return wrapped_value
+
+    return parsed
+
+
 def parse_tool_arguments(arguments: str, tool_name: str) -> dict:
     """Parse tool call arguments with fallback for malformed JSON.
 
@@ -102,6 +183,9 @@ def parse_tool_arguments(arguments: str, tool_name: str) -> dict:
     formatting issues like single quotes instead of double quotes.
     Provides clear error context including tool name and raw payload.
 
+    Also handles unwrapping of arguments that are wrapped in a single-key
+    dictionary matching the tool name (e.g., {"ExampleStructure": {...}}).
+
     Parameters
     ----------
     arguments : str
@@ -112,7 +196,7 @@ def parse_tool_arguments(arguments: str, tool_name: str) -> dict:
     Returns
     -------
     dict
-        Parsed dictionary of tool arguments.
+        Parsed dictionary of tool arguments, with wrapper unwrapped if present.
 
     Raises
     ------
@@ -127,12 +211,15 @@ def parse_tool_arguments(arguments: str, tool_name: str) -> dict:
 
     >>> parse_tool_arguments("{'key': 'value'}", tool_name="search")
     {'key': 'value'}
+
+    >>> parse_tool_arguments('{"ExampleTool": {"arg": "value"}}', "ExampleTool")
+    {'arg': 'value'}
     """
     try:
-        return json.loads(arguments)
+        parsed = json.loads(arguments)
     except json.JSONDecodeError:
         try:
-            return ast.literal_eval(arguments)
+            parsed = ast.literal_eval(arguments)
         except Exception as exc:  # noqa: BLE001
             # Build informative error message with context
             payload_preview = (
@@ -142,3 +229,6 @@ def parse_tool_arguments(arguments: str, tool_name: str) -> dict:
                 f"Failed to parse tool arguments for tool '{tool_name}'. "
                 f"Raw payload: {payload_preview}"
             ) from exc
+
+    # Unwrap if wrapped in a single-key dict matching tool name
+    return _unwrap_arguments(parsed, tool_name)

openai_sdk_helpers/response/vector_store.py

@@ -11,11 +11,11 @@ from typing import Any, Sequence
 from openai import OpenAI
 
 from ..utils import ensure_list
-from .base import BaseResponse
+from .base import ResponseBase
 
 
 def attach_vector_store(
-    response: BaseResponse[Any],
+    response: ResponseBase[Any],
     vector_stores: str | Sequence[str],
     api_key: str | None = None,
 ) -> list[str]:
@@ -27,7 +27,7 @@ def attach_vector_store(
 
     Parameters
     ----------
-    response : BaseResponse[Any]
+    response : ResponseBase[Any]
         Response instance whose tool configuration will be updated.
     vector_stores : str or Sequence[str]
         Single vector store name or sequence of names to attach.