openai-sdk-helpers 0.4.2__py3-none-any.whl → 0.5.0__py3-none-any.whl

openai_sdk_helpers/response/tool_call.py

@@ -7,9 +7,6 @@ and robust argument parsing.
 
 from __future__ import annotations
 
-import ast
-import json
-import re
 from dataclasses import dataclass
 
 from openai.types.responses.response_function_tool_call_param import (
@@ -94,141 +91,3 @@ class ResponseToolCall(DataclassJSONSerializable):
             },
         )
         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.
-
-    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.
-    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
-        Raw argument string from a tool call, expected to be JSON.
-    tool_name : str
-        Tool name for improved error context (required).
-
-    Returns
-    -------
-    dict
-        Parsed dictionary of tool arguments, with wrapper unwrapped if present.
-
-    Raises
-    ------
-    ValueError
-        If the arguments cannot be parsed as valid JSON or Python literal.
-        Error message includes tool name and payload excerpt for debugging.
-
-    Examples
-    --------
-    >>> parse_tool_arguments('{"key": "value"}', tool_name="search")
-    {'key': 'value'}
-
-    >>> parse_tool_arguments("{'key': 'value'}", tool_name="search")
-    {'key': 'value'}
-
-    >>> parse_tool_arguments('{"ExampleTool": {"arg": "value"}}', "ExampleTool")
-    {'arg': 'value'}
-    """
-    try:
-        parsed = json.loads(arguments)
-    except json.JSONDecodeError:
-        try:
-            parsed = ast.literal_eval(arguments)
-        except Exception as exc:  # noqa: BLE001
-            # Build informative error message with context
-            payload_preview = (
-                arguments[:100] + "..." if len(arguments) > 100 else arguments
-            )
-            raise ValueError(
-                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

@@ -73,13 +73,16 @@ def attach_vector_store(
             raise ValueError(f"Vector store '{store}' not found.")
         if match not in resolved_ids:
             resolved_ids.append(match)
-
-    file_search_tool = next(
-        (tool for tool in response._tools if tool.get("type") == "file_search"),
-        None,
-    )
+    file_search_tool = None
+    if response._tools is not None:
+        file_search_tool = next(
+            (tool for tool in response._tools if tool.get("type") == "file_search"),
+            None,
+        )
 
     if file_search_tool is None:
+        if response._tools is None:
+            response._tools = []
         response._tools.append(
             {"type": "file_search", "vector_store_ids": resolved_ids}
         )

openai_sdk_helpers/streamlit_app/__init__.py

@@ -17,7 +17,7 @@ _load_configuration
     Load configuration with user-friendly error handling for Streamlit UI.
 """
 
-from .config import (
+from .configuration import (
     StreamlitAppConfig,
     StreamlitAppRegistry,
     _load_configuration,

openai_sdk_helpers/streamlit_app/app.py

@@ -28,7 +28,6 @@ from openai_sdk_helpers.utils import (
     coerce_jsonable,
     customJSONEncoder,
     ensure_list,
-    log,
 )
 
 # Supported file extensions for OpenAI Assistants file search and vision
@@ -178,7 +177,7 @@ def _render_summary(result: Any, response: ResponseBase[Any]) -> str:
     the result cannot be formatted directly.
     """
     if isinstance(result, StructureBase):
-        return result.print()
+        return str(result)
     if isinstance(result, str):
         return result
     if isinstance(result, dict):
@@ -226,7 +225,7 @@ def _build_raw_output(result: Any, response: ResponseBase[Any]) -> dict[str, Any
     }
 
 
-def _get_response_instance(config: StreamlitAppConfig) -> ResponseBase[Any]:
+def _get_response_instance(configuration: StreamlitAppConfig) -> ResponseBase[Any]:
     """Instantiate and cache the configured ResponseBase.
 
     Creates a new response instance from the configuration if not already
@@ -235,7 +234,7 @@ def _get_response_instance(config: StreamlitAppConfig) -> ResponseBase[Any]:
 
     Parameters
     ----------
-    config : StreamlitAppConfig
+    configuration : StreamlitAppConfig
         Loaded configuration with response handler definition.
 
     Returns
@@ -258,13 +257,13 @@ def _get_response_instance(config: StreamlitAppConfig) -> ResponseBase[Any]:
         if isinstance(cached, ResponseBase):
             return cached
 
-    response = config.create_response()
+    response = configuration.create_response()
 
-    if config.preserve_vector_stores:
+    if configuration.preserve_vector_stores:
         setattr(response, "_cleanup_system_vector_storage", False)
         setattr(response, "_cleanup_user_vector_storage", False)
 
-    vector_stores = config.normalized_vector_stores()
+    vector_stores = configuration.normalized_vector_stores()
     if vector_stores:
         attach_vector_store(response=response, vector_stores=vector_stores)
 
@@ -357,7 +356,7 @@ def _render_chat_history() -> None:
 
 def _handle_user_message(
     prompt: str,
-    config: StreamlitAppConfig,
+    configuration: StreamlitAppConfig,
     attachment_paths: list[str] | None = None,
     attachment_names: list[str] | None = None,
 ) -> None:
@@ -371,7 +370,7 @@ def _handle_user_message(
     ----------
     prompt : str
         User-entered text to send to the assistant.
-    config : StreamlitAppConfig
+    configuration : StreamlitAppConfig
         Loaded configuration with response handler definition.
     attachment_paths : list[str] or None, default None
         Optional list of file paths to attach to the message.
@@ -395,7 +394,7 @@ def _handle_user_message(
         {"role": "user", "content": prompt, "attachments": display_names}
     )
     try:
-        response = _get_response_instance(config)
+        response = _get_response_instance(configuration)
     except Exception as exc:  # pragma: no cover - surfaced in UI
         st.error(f"Failed to start response session: {exc}")
         return
@@ -442,15 +441,15 @@ def main(config_path: Path) -> None:
     >>> from pathlib import Path
     >>> main(Path("./my_config.py"))
     """
-    config = _load_configuration(config_path)
-    st.set_page_config(page_title=config.display_title, layout="wide")
+    configuration = _load_configuration(config_path)
+    st.set_page_config(page_title=configuration.display_title, layout="wide")
     _init_session_state()
 
-    st.title(config.display_title)
-    if config.description:
-        st.caption(config.description)
-    if config.model:
-        st.caption(f"Model: {config.model}")
+    st.title(configuration.display_title)
+    if configuration.description:
+        st.caption(configuration.description)
+    if configuration.model:
+        st.caption(f"Model: {configuration.model}")
 
     close_col, _ = st.columns([1, 5])
     with close_col:
@@ -514,7 +513,7 @@ def main(config_path: Path) -> None:
         st.session_state["attachment_names"] = []
         _handle_user_message(
             prompt,
-            config,
+            configuration,
             attachment_paths or None,
             attachment_display_names or None,
         )

openai_sdk_helpers/streamlit_app/{config.py → configuration.py}

@@ -54,7 +54,7 @@ class StreamlitAppConfig(BaseModelJSONSerializable):
     Examples
     --------
     >>> from openai_sdk_helpers.streamlit_app import StreamlitAppConfig
-    >>> config = StreamlitAppConfig(
+    >>> configuration = StreamlitAppConfig(
     ...     response=MyResponse,
     ...     display_title="My Assistant",
     ...     description="A helpful AI assistant"
@@ -180,7 +180,7 @@ class StreamlitAppConfig(BaseModelJSONSerializable):
 
         Examples
         --------
-        >>> config.normalized_vector_stores()
+        >>> configuration.normalized_vector_stores()
         ['docs', 'knowledge_base']
         """
         return list(self.system_vector_store or [])
@@ -224,7 +224,7 @@ class StreamlitAppConfig(BaseModelJSONSerializable):
 
         Examples
         --------
-        >>> response = config.create_response()
+        >>> response = configuration.create_response()
         >>> result = response.run_sync("Hello")
         """
         return _instantiate_response(self.response)
@@ -238,7 +238,7 @@ class StreamlitAppRegistry(RegistryBase[StreamlitAppConfig]):
 
     Methods
     -------
-    register(config)
+    register(configuration)
         Add a configuration to the registry.
     get(name)
         Retrieve a configuration by name.
@@ -256,9 +256,9 @@ class StreamlitAppRegistry(RegistryBase[StreamlitAppConfig]):
     Examples
     --------
     >>> registry = StreamlitAppRegistry()
-    >>> config = StreamlitAppConfig(response=MyResponse)
-    >>> registry.register(config)
-    >>> registry.get(config.name)
+    >>> configuration = StreamlitAppConfig(response=MyResponse)
+    >>> registry.register(configuration)
+    >>> registry.get(configuration.name)
     StreamlitAppConfig(...)
     """
 
@@ -295,7 +295,7 @@ class StreamlitAppRegistry(RegistryBase[StreamlitAppConfig]):
         Examples
         --------
         >>> from pathlib import Path
-        >>> config = StreamlitAppRegistry.load_app_config(
+        >>> configuration = StreamlitAppRegistry.load_app_config(
         ...     Path("./my_config.py")
         ... )
         """
@@ -328,7 +328,7 @@ def _import_config_module(config_path: Path) -> ModuleType:
 
     Examples
     --------
-    >>> module = _import_config_module(Path("./config.py"))
+    >>> module = _import_config_module(Path("./configuration.py"))
     >>> hasattr(module, 'APP_CONFIG')
     True
     """
@@ -349,7 +349,7 @@ def _extract_config(module: ModuleType) -> StreamlitAppConfig:
 
     Looks for APP_CONFIG in the module and converts it to a validated
     StreamlitAppConfig instance. Supports multiple input formats including
-    dictionaries, ResponseBase instances, and existing config objects.
+    dictionaries, ResponseBase instances, and existing configuration objects.
 
     Parameters
     ----------
@@ -371,8 +371,8 @@ def _extract_config(module: ModuleType) -> StreamlitAppConfig:
 
     Examples
     --------
-    >>> config = _extract_config(module)
-    >>> isinstance(config, StreamlitAppConfig)
+    >>> configuration = _extract_config(module)
+    >>> isinstance(configuration, StreamlitAppConfig)
     True
     """
     if not hasattr(module, "APP_CONFIG"):
@@ -455,7 +455,7 @@ def _config_from_mapping(raw_config: dict) -> StreamlitAppConfig:
 
     Examples
     --------
-    >>> config = _config_from_mapping({
+    >>> configuration = _config_from_mapping({
     ...     'response': MyResponse,
     ...     'display_title': 'My App'
     ... })

openai_sdk_helpers/structure/__init__.py

@@ -53,6 +53,10 @@ VectorSearchReportStructure
     Complete vector search report.
 ValidationResultStructure
     Validation results with pass/fail status.
+ExtractionItem
+    Extracted item with source span data.
+ExtractionResult
+    Structured extraction results for a document.
 
 Functions
 ---------
@@ -72,6 +76,13 @@ from __future__ import annotations
 
 from .agent_blueprint import AgentBlueprint
 from .base import *
+from .extraction import (
+    AnnotatedDocumentStructure,
+    AttributeStructure,
+    DocumentStructure,
+    ExampleDataStructure,
+    ExtractionStructure,
+)
 from .plan import *
 from .prompt import PromptStructure
 from .responses import *
@@ -109,6 +120,11 @@ __all__ = [
     "VectorSearchPlanStructure",
     "VectorSearchStructure",
     "ValidationResultStructure",
+    "AnnotatedDocumentStructure",
+    "AttributeStructure",
+    "DocumentStructure",
+    "ExampleDataStructure",
+    "ExtractionStructure",
     "assistant_tool_definition",
     "assistant_format",
     "response_tool_definition",