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

openai_sdk_helpers/response/__init__.py

@@ -24,8 +24,6 @@ run_sync
     Execute a response workflow synchronously with resource cleanup.
 run_async
     Execute a response workflow asynchronously with resource cleanup.
-run_streamed
-    Execute a response workflow and return the asynchronous result.
 attach_vector_store
     Attach vector stores to a response's file_search tool.
 process_files
@@ -38,8 +36,8 @@ from .base import ResponseBase
 from .configuration import ResponseConfiguration, ResponseRegistry, get_default_registry
 from .files import process_files
 from .messages import ResponseMessage, ResponseMessages
-from .runner import run_async, run_streamed, run_sync
-from .tool_call import ResponseToolCall, parse_tool_arguments
+from .runner import run_async, run_sync
+from .tool_call import ResponseToolCall
 from .vector_store import attach_vector_store
 
 __all__ = [
@@ -51,9 +49,7 @@ __all__ = [
     "ResponseMessages",
     "run_sync",
     "run_async",
-    "run_streamed",
     "ResponseToolCall",
-    "parse_tool_arguments",
     "attach_vector_store",
     "process_files",
 ]

openai_sdk_helpers/response/base.py

@@ -46,6 +46,7 @@ from .messages import ResponseMessage, ResponseMessages
 from ..settings import OpenAISettings
 from ..structure import StructureBase
 from ..types import OpenAIClient
+from ..tools import ToolHandlerRegistration, ToolSpec
 from ..utils import (
     check_filepath,
     coerce_jsonable,
@@ -58,7 +59,6 @@ if TYPE_CHECKING:  # pragma: no cover - only for typing hints
     from openai_sdk_helpers.streamlit_app.configuration import StreamlitAppConfig
 
 T = TypeVar("T", bound=StructureBase)
-ToolHandler = Callable[[ResponseFunctionToolCall], str | Any]
 RB = TypeVar("RB", bound="ResponseBase[StructureBase]")
 
 
@@ -81,8 +81,9 @@ class ResponseBase(Generic[T]):
         and naming vector stores.
     instructions : str
         System instructions provided to the OpenAI API for context.
-    tools : list or None
-        Tool definitions for the OpenAI API request. Pass None for no tools.
+    tools : list[ToolHandlerRegistration] or None
+        Tool handler registrations for the OpenAI API request. Pass None for
+        no tools.
     output_structure : type[StructureBase] or None
         Structure class used to parse tool call outputs. When provided,
         the schema is automatically generated using the structure's
@@ -93,8 +94,9 @@ class ResponseBase(Generic[T]):
         Optional absolute directory path for storing artifacts. If not provided,
         defaults to get_data_path(class_name). Session files are saved as
         data_path / uuid.json.
-    tool_handlers : dict[str, ToolHandler] or None, default None
-        Mapping from tool names to callable handlers. Each handler receives
+    tool_handlers : dict[str, ToolHandlerRegistration] or None, default None
+        Mapping from tool names to handler registrations that include optional
+        ToolSpec metadata to parse tool outputs by name. Each handler receives
         a ResponseFunctionToolCall and returns a string or any serializable
         result. Defaults to an empty dict when not provided.
     openai_settings : OpenAISettings or None, default None
@@ -119,12 +121,12 @@ class ResponseBase(Generic[T]):
 
     Methods
     -------
-    run_async(content, attachments=None)
+    run_async(content, files=None, use_vector_store=False)
         Generate a response asynchronously and return parsed output.
-    run_sync(content, attachments=None)
+    run_sync(content, files=None, use_vector_store=False)
         Execute run_async synchronously with thread management.
-    run_streamed(content, attachments=None)
-        Execute run_async and await the result (streaming not yet supported).
+    register_tool(func, tool_spec)
+        Register a tool handler and definition from a ToolSpec.
     get_last_tool_message()
         Return the most recent tool message or None.
     get_last_user_message()
@@ -158,11 +160,11 @@ class ResponseBase(Generic[T]):
         *,
         name: str,
         instructions: str,
-        tools: list | None,
+        tools: list[ToolHandlerRegistration] | None,
         output_structure: type[T] | None,
         system_vector_store: list[str] | None = None,
         data_path: Path | str | None = None,
-        tool_handlers: dict[str, ToolHandler] | None = None,
+        tool_handlers: dict[str, ToolHandlerRegistration] | None = None,
         openai_settings: OpenAISettings | None = None,
     ) -> None:
         """Initialize a response session with OpenAI configuration.
@@ -178,8 +180,9 @@ class ResponseBase(Generic[T]):
             and naming vector stores.
         instructions : str
             System instructions provided to the OpenAI API for context.
-        tools : list or None
-            Tool definitions for the OpenAI API request. Pass None for no tools.
+        tools : list[ToolHandlerRegistration] or None
+            Tool handler registrations for the OpenAI API request. Pass None for
+            no tools.
         output_structure : type[StructureBase] or None
             Structure class used to parse tool call outputs. When provided,
             the schema is automatically generated using the structure's
@@ -190,8 +193,9 @@ class ResponseBase(Generic[T]):
             Optional absolute directory path for storing artifacts. If not provided,
             defaults to get_data_path(class_name). Session files are saved as
             data_path / uuid.json.
-        tool_handlers : dict[str, ToolHandler] or None, default None
-            Mapping from tool names to callable handlers. Each handler receives
+        tool_handlers : dict[str, ToolHandlerRegistration] or None, default None
+            Mapping from tool names to handler registrations that include optional
+            ToolSpec metadata to parse tool outputs by name. Each handler receives
             a ResponseFunctionToolCall and returns a string or any serializable
             result. Defaults to an empty dict when not provided.
         openai_settings : OpenAISettings or None, default None
@@ -222,9 +226,7 @@ class ResponseBase(Generic[T]):
         if openai_settings is None:
             raise ValueError("openai_settings is required")
 
-        if tool_handlers is None:
-            tool_handlers = {}
-        self._tool_handlers = tool_handlers
+        self._tool_handlers = tool_handlers or {}
         self.uuid = uuid.uuid4()
         self._name = name
 
@@ -242,8 +244,14 @@ class ResponseBase(Generic[T]):
             self._data_path = get_data_path(self.__class__.__name__)
 
         self._instructions = instructions
-        self._tools = tools if tools is not None else []
+        self._tools: list[dict[str, Any]] | None = None
+        if tools is not None:
+            self._tools = [
+                tool_handler.tool_spec.as_tool_definition() for tool_handler in tools
+            ]
+
         self._output_structure = output_structure
+        self._system_vector_store = system_vector_store
         self._openai_settings = openai_settings
 
         if not self._openai_settings.api_key:
@@ -339,7 +347,7 @@ class ResponseBase(Generic[T]):
         return self._instructions
 
     @property
-    def tools(self) -> list | None:
+    def tools(self) -> list[dict[str, Any]] | None:
         """Return the tool definitions for this response.
 
         Returns
@@ -370,6 +378,43 @@ class ResponseBase(Generic[T]):
         """
         return self._output_structure
 
+    def register_tool(
+        self,
+        func: Callable[..., Any],
+        *,
+        tool_spec: ToolSpec,
+    ) -> None:
+        """Register a tool handler and definition using a ToolSpec.
+
+        Parameters
+        ----------
+        func : Callable[..., Any]
+            Tool implementation function to wrap for argument parsing and
+            result serialization.
+        tool_spec : ToolSpec
+            Tool specification describing input/output structures and metadata.
+
+        Returns
+        -------
+        None
+            Register the tool handler and definition for this response session.
+
+        Raises
+        ------
+        ValueError
+            If tool_spec.tool_name is empty.
+
+        Examples
+        --------
+        >>> response.register_tool(run_search, tool_spec=search_tool_spec)
+        """
+        if not tool_spec.tool_name:
+            raise ValueError("tool_spec.tool_name must be a non-empty string")
+        self._tool_handlers[tool_spec.tool_name] = ToolHandlerRegistration(
+            handler=func,
+            tool_spec=tool_spec,
+        )
+
     def _build_input(
         self,
         content: str | list[str],
@@ -455,7 +500,7 @@ class ResponseBase(Generic[T]):
         content: str | list[str],
         files: str | list[str] | None = None,
         use_vector_store: bool = False,
-    ) -> T | None:
+    ) -> T | str:
         """Generate a response asynchronously from the OpenAI API.
 
         Builds input messages, sends the request to OpenAI, processes any
@@ -480,8 +525,8 @@ class ResponseBase(Generic[T]):
 
         Returns
         -------
-        T or None
-            Parsed response object of type output_structure, or None if
+        T or str
+            Parsed response object of type output_structure, or raw string if
             no structured output was produced.
 
         Raises
@@ -540,15 +585,18 @@ class ResponseBase(Generic[T]):
                 )
 
                 tool_name = response_output.name
-                handler = self._tool_handlers.get(tool_name)
+                registration = self._tool_handlers.get(tool_name)
 
-                if handler is None:
+                if registration is None:
                     log(
                         f"No handler found for tool '{tool_name}'",
                         level=logging.ERROR,
                     )
                     raise ValueError(f"No handler for tool: {tool_name}")
 
+                handler = registration.handler
+                tool_spec = registration.tool_spec
+
                 try:
                     if inspect.iscoroutinefunction(handler):
                         tool_result_json = await handler(response_output)
@@ -571,9 +619,11 @@ class ResponseBase(Generic[T]):
                     )
                     raise RuntimeError(f"Error in tool handler '{tool_name}': {exc}")
 
-                if self._output_structure:
-                    output_dict = self._output_structure.from_raw_input(tool_result)
-                    output_dict.console_print()
+                if tool_spec is not None:
+                    output_dict = tool_spec.output_structure.from_json(tool_result)
+                    parsed_result = cast(T, output_dict)
+                elif self._output_structure:
+                    output_dict = self._output_structure.from_json(tool_result)
                     parsed_result = output_dict
                 else:
                     print(tool_result)
@@ -588,13 +638,13 @@ class ResponseBase(Generic[T]):
                     try:
                         output_dict = json.loads(raw_text)
                         if self._output_structure:
-                            return self._output_structure.from_raw_input(output_dict)
+                            return self._output_structure.from_json(output_dict)
                         return output_dict
                     except Exception:
                         print(raw_text)
         if parsed_result is not None:
             return parsed_result
-        return None
+        return response.output_text
 
     def run_sync(
         self,
@@ -602,7 +652,7 @@ class ResponseBase(Generic[T]):
         *,
         files: str | list[str] | None = None,
         use_vector_store: bool = False,
-    ) -> T | None:
+    ) -> T | str:
         """Execute run_async synchronously with proper event loop handling.
 
         Automatically detects if an event loop is already running and uses
@@ -627,8 +677,8 @@ class ResponseBase(Generic[T]):
 
         Returns
         -------
-        T or None
-            Parsed response object of type output_structure, or None.
+        T or str
+            Parsed response object of type output_structure, or raw string.
 
         Raises
         ------
@@ -654,7 +704,7 @@ class ResponseBase(Generic[T]):
         ... )
         """
 
-        async def runner() -> T | None:
+        async def runner() -> T | str:
             return await self.run_async(
                 content=content,
                 files=files,
@@ -665,7 +715,7 @@ class ResponseBase(Generic[T]):
             asyncio.get_running_loop()
         except RuntimeError:
             return asyncio.run(runner())
-        result: T | None = None
+        result: T | str = ""
 
         def _thread_func() -> None:
             nonlocal result
@@ -676,65 +726,6 @@ class ResponseBase(Generic[T]):
         thread.join()
         return result
 
-    def run_streamed(
-        self,
-        content: str | list[str],
-        *,
-        files: str | list[str] | None = None,
-        use_vector_store: bool = False,
-    ) -> T | None:
-        """Execute run_async and await the result.
-
-        Streaming responses are not yet fully supported, so this method
-        simply awaits run_async to provide API compatibility with agent
-        interfaces.
-
-        Automatically detects file types:
-        - Images are sent as base64-encoded images
-        - Documents are sent as base64-encoded files (default)
-        - Documents can optionally use vector stores for RAG
-
-        Parameters
-        ----------
-        content : str or list[str]
-            Prompt text or list of prompt texts to send.
-        files : str, list[str], or None, default None
-            Optional file path or list of file paths. Each file is
-            automatically processed based on its type.
-        use_vector_store : bool, default False
-            If True, non-image files are uploaded to a vector store
-            for RAG-enabled search instead of inline base64 encoding.
-
-        Returns
-        -------
-        T or None
-            Parsed response object of type output_structure, or None.
-
-        Raises
-        ------
-        RuntimeError
-            If the API returns no output.
-            If a tool handler raises an exception.
-        ValueError
-            If the API invokes a tool with no registered handler.
-
-        Notes
-        -----
-        This method exists for API consistency but does not currently
-        provide true streaming functionality.
-
-        Examples
-        --------
-        >>> result = response.run_streamed("Analyze these files")
-        """
-        return asyncio.run(
-            self.run_async(
-                content=content,
-                files=files,
-                use_vector_store=use_vector_store,
-            )
-        )
-
     def get_last_tool_message(self) -> ResponseMessage | None:
         """Return the most recent tool message from conversation history.
 

openai_sdk_helpers/response/configuration.py

@@ -8,7 +8,8 @@ from typing import Generic, Optional, Sequence, Type, TypeVar
 
 from ..settings import OpenAISettings
 from ..structure.base import StructureBase
-from .base import ResponseBase, ToolHandler
+from .base import ResponseBase
+from ..tools import ToolHandlerRegistration
 from ..utils.json.data_class import DataclassJSONSerializable
 from ..utils.registry import RegistryBase
 from ..utils.instructions import resolve_instructions_from_path
@@ -23,6 +24,21 @@ class ResponseRegistry(RegistryBase["ResponseConfiguration"]):
     Inherits from RegistryBase to provide centralized storage and retrieval
     of response configurations, enabling reusable response specs across the application.
 
+    Methods
+    -------
+    register(configuration)
+        Add a configuration to the registry.
+    get(name)
+        Retrieve a configuration by name.
+    list_names()
+        Return all registered configuration names.
+    clear()
+        Remove all registered configurations.
+    save_to_directory(path)
+        Export all registered configurations to JSON files.
+    load_from_directory(path, config_class)
+        Load configurations from JSON files in a directory.
+
     Examples
     --------
     >>> registry = ResponseRegistry()
@@ -61,12 +77,11 @@ def get_default_registry() -> ResponseRegistry:
 
 @dataclass(frozen=True, slots=True)
 class ResponseConfiguration(DataclassJSONSerializable, Generic[TIn, TOut]):
-    """
-    Represent an immutable configuration describing input and output structures.
+    """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 DataclassJSONSerializable to support serialization to JSON format.
+    Inherit from DataclassJSONSerializable to support serialization to JSON format.
 
     Parameters
     ----------
@@ -87,9 +102,11 @@ class ResponseConfiguration(DataclassJSONSerializable, Generic[TIn, TOut]):
     system_vector_store : list[str], optional
         Optional list of vector store names to attach as system context.
         Default is None.
-    data_path : Path, str, or None, optional
-        Optional absolute directory path for storing artifacts. If not provided,
-        defaults to get_data_path(class_name). Default is None.
+    add_output_instructions : bool, optional
+        Whether to append output structure instructions to the prompt.
+        Default is False.
+    add_web_search_tool : bool, optional
+        Whether to append a web_search tool to the tool list. Default is False.
 
     Raises
     ------
@@ -108,6 +125,12 @@ class ResponseConfiguration(DataclassJSONSerializable, Generic[TIn, TOut]):
     -------
     __post_init__()
         Validate configuration invariants and enforce StructureBase subclassing.
+    get_resolved_instructions()
+        Return instructions with optional output structure guidance appended.
+    get_resolved_tools()
+        Return tools list with optional web_search tool appended.
+    gen_response(openai_settings, data_path=None, tool_handlers=None)
+        Build a ResponseBase instance from this configuration.
     to_json()
         Return a JSON-compatible dict representation (inherited from JSONSerializable).
     to_json_file(filepath)
@@ -119,7 +142,7 @@ class ResponseConfiguration(DataclassJSONSerializable, Generic[TIn, TOut]):
 
     Examples
     --------
-    >>> configuration = Configuration(
+    >>> configuration = ResponseConfiguration(
     ...     name="targeting_to_plan",
     ...     tools=None,
     ...     input_structure=PromptStructure,
@@ -139,8 +162,7 @@ class ResponseConfiguration(DataclassJSONSerializable, Generic[TIn, TOut]):
     add_web_search_tool: bool = False
 
     def __post_init__(self) -> None:
-        """
-        Validate configuration invariants after initialization.
+        """Validate configuration invariants after initialization.
 
         Enforce non-empty naming, correct typing of structures, and ensure that
         any declared structure subclasses StructureBase.
@@ -222,7 +244,7 @@ class ResponseConfiguration(DataclassJSONSerializable, Generic[TIn, TOut]):
         *,
         openai_settings: OpenAISettings,
         data_path: Optional[Path] = None,
-        tool_handlers: dict[str, ToolHandler] | None = None,
+        tool_handlers: dict[str, ToolHandlerRegistration] | None = None,
     ) -> ResponseBase[TOut]:
         """Generate a ResponseBase instance based on the configuration.
 
@@ -230,9 +252,12 @@ class ResponseConfiguration(DataclassJSONSerializable, Generic[TIn, TOut]):
         ----------
         openai_settings : OpenAISettings
             Authentication and model settings applied to the generated
-            :class:`ResponseBase`.
-        tool_handlers : dict[str, Callable], optional
-            Mapping of tool names to handler callables. Defaults to an empty
+            ResponseBase.
+        data_path : Path or None, default None
+            Optional override for the response artifact directory.
+        tool_handlers : dict[str, ToolHandlerRegistration], optional
+            Mapping of tool names to handler registrations. Registrations can include
+            ToolSpec metadata to parse tool outputs by name. Defaults to an empty
             dictionary when not provided.
 
         Returns

openai_sdk_helpers/response/files.py

@@ -151,6 +151,8 @@ def _upload_to_vector_store(
             model=response._model,
         )
         user_vector_storage = cast(Any, response._user_vector_storage)
+        if response._tools is None:
+            response._tools = []
         if not any(tool.get("type") == "file_search" for tool in response._tools):
             response._tools.append(
                 {

openai_sdk_helpers/response/runner.py

@@ -7,12 +7,10 @@ They simplify common usage patterns for both synchronous and asynchronous contex
 
 from __future__ import annotations
 
-import asyncio
 from typing import Any, TypeVar
 
 from .base import ResponseBase
 
-
 R = TypeVar("R", bound=ResponseBase[Any])
 
 
@@ -100,49 +98,4 @@ async def run_async(
         response.close()
 
 
-def run_streamed(
-    response_cls: type[R],
-    *,
-    content: str,
-    response_kwargs: dict[str, Any] | None = None,
-) -> Any:
-    """Execute a response workflow and return the awaited result.
-
-    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 : type[ResponseBase]
-        Response class to instantiate for the workflow.
-    content : str
-        Prompt text to send to the OpenAI API.
-    response_kwargs : dict[str, Any] or None, default None
-        Optional keyword arguments forwarded to response_cls constructor.
-
-    Returns
-    -------
-    Any
-        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)
-    )
-
-
-__all__ = ["run_sync", "run_async", "run_streamed"]
+__all__ = ["run_sync", "run_async"]