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

openai_sdk_helpers/response/config.py

@@ -5,17 +5,16 @@ 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 ..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(BaseRegistry["ResponseConfiguration"]):
@@ -43,10 +42,6 @@ class ResponseRegistry(BaseRegistry["ResponseConfiguration"]):
     pass
 
 
-# Global default registry instance
-_default_registry = ResponseRegistry()
-
-
 def get_default_registry() -> ResponseRegistry:
     """Return the global default registry instance.
 
@@ -65,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
     ----------
@@ -82,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.
@@ -103,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
@@ -112,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()
@@ -142,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
         ------
@@ -157,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")
@@ -181,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")
@@ -198,54 +193,51 @@ class ResponseConfiguration(JSONSerializable, Generic[TIn, TOut]):
         str
             Plain-text instructions, loading template files when necessary.
         """
-        return self._resolve_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}"
 
-    def _resolve_instructions(self) -> str:
-        return resolve_instructions_from_path(self.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.

openai_sdk_helpers/streamlit_app/app.py

@@ -18,12 +18,12 @@ from dotenv import load_dotenv
 
 load_dotenv()
 
-from openai_sdk_helpers.response import BaseResponse, attach_vector_store
+from openai_sdk_helpers.response import ResponseBase, attach_vector_store
 from openai_sdk_helpers.streamlit_app import (
     StreamlitAppConfig,
     _load_configuration,
 )
-from openai_sdk_helpers.structure.base import BaseStructure
+from openai_sdk_helpers.structure.base import StructureBase
 from openai_sdk_helpers.utils import (
     coerce_jsonable,
     customJSONEncoder,
@@ -96,7 +96,7 @@ def _cleanup_temp_files(file_paths: list[str] | None = None) -> None:
         st.session_state["temp_file_paths"] = []
 
 
-def _extract_assistant_text(response: BaseResponse[Any]) -> str:
+def _extract_assistant_text(response: ResponseBase[Any]) -> str:
     """Extract the latest assistant message as readable text.
 
     Searches the response's message history for the most recent assistant
@@ -104,7 +104,7 @@ def _extract_assistant_text(response: BaseResponse[Any]) -> str:
 
     Parameters
     ----------
-    response : BaseResponse[Any]
+    response : ResponseBase[Any]
         Active response session with message history.
 
     Returns
@@ -153,7 +153,7 @@ def _extract_assistant_text(response: BaseResponse[Any]) -> str:
     return ""
 
 
-def _render_summary(result: Any, response: BaseResponse[Any]) -> str:
+def _render_summary(result: Any, response: ResponseBase[Any]) -> str:
     """Generate display text for the chat transcript.
 
     Converts the response result into a human-readable format suitable
@@ -163,8 +163,8 @@ def _render_summary(result: Any, response: BaseResponse[Any]) -> str:
     Parameters
     ----------
     result : Any
-        Parsed result from BaseResponse.run_sync.
-    response : BaseResponse[Any]
+        Parsed result from ResponseBase.run_sync.
+    response : ResponseBase[Any]
         Response instance containing message history.
 
     Returns
@@ -177,7 +177,7 @@ def _render_summary(result: Any, response: BaseResponse[Any]) -> str:
     Falls back to extracting assistant text from message history if
     the result cannot be formatted directly.
     """
-    if isinstance(result, BaseStructure):
+    if isinstance(result, StructureBase):
         return result.print()
     if isinstance(result, str):
         return result
@@ -196,7 +196,7 @@ def _render_summary(result: Any, response: BaseResponse[Any]) -> str:
     return "No response returned."
 
 
-def _build_raw_output(result: Any, response: BaseResponse[Any]) -> dict[str, Any]:
+def _build_raw_output(result: Any, response: ResponseBase[Any]) -> dict[str, Any]:
     """Assemble raw JSON payload for the expandable transcript section.
 
     Creates a structured dictionary containing both the parsed result
@@ -206,7 +206,7 @@ def _build_raw_output(result: Any, response: BaseResponse[Any]) -> dict[str, Any
     ----------
     result : Any
         Parsed result from the response execution.
-    response : BaseResponse[Any]
+    response : ResponseBase[Any]
         Response session with complete message history.
 
     Returns
@@ -226,8 +226,8 @@ def _build_raw_output(result: Any, response: BaseResponse[Any]) -> dict[str, Any
     }
 
 
-def _get_response_instance(config: StreamlitAppConfig) -> BaseResponse[Any]:
-    """Instantiate and cache the configured BaseResponse.
+def _get_response_instance(config: StreamlitAppConfig) -> ResponseBase[Any]:
+    """Instantiate and cache the configured ResponseBase.
 
     Creates a new response instance from the configuration if not already
     cached in session state. Applies vector store attachments and cleanup
@@ -240,13 +240,13 @@ def _get_response_instance(config: StreamlitAppConfig) -> BaseResponse[Any]:
 
     Returns
     -------
-    BaseResponse[Any]
+    ResponseBase[Any]
         Active response instance for the current Streamlit session.
 
     Raises
     ------
     TypeError
-        If the configured response cannot produce a BaseResponse.
+        If the configured response cannot produce a ResponseBase.
 
     Notes
     -----
@@ -255,7 +255,7 @@ def _get_response_instance(config: StreamlitAppConfig) -> BaseResponse[Any]:
     """
     if "response_instance" in st.session_state:
         cached = st.session_state["response_instance"]
-        if isinstance(cached, BaseResponse):
+        if isinstance(cached, ResponseBase):
             return cached
 
     response = config.create_response()
@@ -291,7 +291,7 @@ def _reset_chat(close_response: bool = True) -> None:
     chat_history, response_instance, and temp_file_paths keys.
     """
     response = st.session_state.get("response_instance")
-    if close_response and isinstance(response, BaseResponse):
+    if close_response and isinstance(response, ResponseBase):
         filepath = f"./data/{response.name}.{response.uuid}.json"
         response.save(filepath)
         response.close()