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

openai_sdk_helpers/prompt/extractor_config_generator.jinja

@@ -0,0 +1,37 @@
+Build a DocumentExtractorConfig using the details below:
+Name: {{ name }}
+Prompt description: {{ prompt_description }}
+Extraction classes:
+{% for item in extraction_classes -%}
+- {{ item }}
+{% else -%}
+- None provided
+{% endfor %}
+
+Example requirements:
+{% for requirement in example_requirements -%}
+- {{ requirement }}
+{% endfor %}
+
+Attributes guidance:
+- Every extraction must include an "attributes" object.
+- Use attributes to capture meaningful structured details (e.g., confidence, type, qualifiers).
+- If no attributes apply, provide an empty object {}.
+
+Examples (JSON):
+{{ examples_json }}
+
+Source files for grounding:
+{% if example_files -%}
+{% for file in example_files -%}
+- Path: {{ file.path }}
+  Content:
+{{ file.content }}
+{% endfor %}
+{% else -%}
+- None provided.
+{% endif %}
+
+Grounding requirements:
+- Use source file content to craft example text when available.
+- Prefer quoting or lightly paraphrasing source text over inventing details.

openai_sdk_helpers/prompt/extractor_config_generator_instructions.jinja

@@ -0,0 +1,9 @@
+Generate a DocumentExtractorConfig using the provided inputs.
+Requirements:
+- Generate high-quality examples that match the prompt and extraction classes.
+- Ensure examples include realistic source text and cover all extraction classes.
+- Include meaningful attributes on each extraction when applicable.
+- If source files are provided, ground example text in that content.
+- Set the configuration name exactly as provided.
+- Preserve the provided prompt description and extraction classes.
+- Do not add or remove extraction classes.

openai_sdk_helpers/prompt/extractor_prompt_optimizer_agent_instructions.jinja

@@ -0,0 +1,4 @@
+Optimize the extraction prompt for clarity and precision. Return the optimized prompt
+as structured output.
+
+{{ prompt_schema }}

openai_sdk_helpers/prompt/extractor_prompt_optimizer_request.jinja

@@ -0,0 +1,11 @@
+Optimize the extraction prompt using the details below:
+User prompt: {{ prompt }}
+Extraction classes:
+{% for item in extraction_classes -%}
+- {{ item }}
+{% else -%}
+- None provided
+{% endfor %}
+{% if additional_context -%}
+Additional context: {{ additional_context }}
+{% endif %}

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

@@ -13,6 +13,7 @@ import inspect
 import json
 import logging
 import threading
+import traceback
 import uuid
 from pathlib import Path
 from typing import (
@@ -46,6 +47,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 +60,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 +82,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 +95,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 +122,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()
@@ -135,6 +138,8 @@ class ResponseBase(Generic[T]):
         Construct a StreamlitAppConfig using this class as the builder.
     save(filepath=None)
         Serialize the message history to a JSON file.
+    save_error(exc)
+        Persist error details to a file named with the response UUID.
     close()
         Clean up remote resources including vector stores.
 
@@ -158,11 +163,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 +183,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 +196,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 +229,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 +247,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 +350,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 +381,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 +503,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 +528,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
@@ -510,91 +558,117 @@ class ResponseBase(Generic[T]):
         log(f"{self.__class__.__name__}::run_response")
         parsed_result: T | None = None
 
-        self._build_input(
-            content=content,
-            files=(ensure_list(files) if files else None),
-            use_vector_store=use_vector_store,
-        )
-
-        kwargs = {
-            "input": self.messages.to_openai_payload(),
-            "model": self._model,
-        }
-        if not self._tools and self._output_structure is not None:
-            kwargs["text"] = self._output_structure.response_format()
-
-        if self._tools:
-            kwargs["tools"] = self._tools
-            kwargs["tool_choice"] = "auto"
-        response = self._client.responses.create(**kwargs)
+        try:
+            self._build_input(
+                content=content,
+                files=(ensure_list(files) if files else None),
+                use_vector_store=use_vector_store,
+            )
 
-        if not response.output:
-            log("No output returned from OpenAI.", level=logging.ERROR)
-            raise RuntimeError("No output returned from OpenAI.")
+            kwargs = {
+                "input": self.messages.to_openai_payload(),
+                "model": self._model,
+            }
+            if not self._tools and self._output_structure is not None:
+                kwargs["text"] = self._output_structure.response_format()
 
-        for response_output in response.output:
-            if isinstance(response_output, ResponseFunctionToolCall):
-                log(
-                    f"Tool call detected. Executing {response_output.name}.",
-                    level=logging.INFO,
-                )
+            if self._tools:
+                kwargs["tools"] = self._tools
+                kwargs["tool_choice"] = "auto"
+            response = self._client.responses.create(**kwargs)
 
-                tool_name = response_output.name
-                handler = self._tool_handlers.get(tool_name)
+            if not response.output:
+                log("No output returned from OpenAI.", level=logging.ERROR)
+                raise RuntimeError("No output returned from OpenAI.")
 
-                if handler is None:
+            for response_output in response.output:
+                if isinstance(response_output, ResponseFunctionToolCall):
                     log(
-                        f"No handler found for tool '{tool_name}'",
-                        level=logging.ERROR,
+                        f"Tool call detected. Executing {response_output.name}.",
+                        level=logging.INFO,
                     )
-                    raise ValueError(f"No handler for tool: {tool_name}")
 
-                try:
-                    if inspect.iscoroutinefunction(handler):
-                        tool_result_json = await handler(response_output)
-                    else:
-                        tool_result_json = handler(response_output)
-                    if isinstance(tool_result_json, str):
-                        tool_result = json.loads(tool_result_json)
-                        tool_output = tool_result_json
+                    tool_name = response_output.name
+                    registration = self._tool_handlers.get(tool_name)
+
+                    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)
+                        else:
+                            tool_result_json = handler(response_output)
+                        if isinstance(tool_result_json, str):
+                            tool_result = json.loads(tool_result_json)
+                            tool_output = tool_result_json
+                        else:
+                            tool_result = coerce_jsonable(tool_result_json)
+                            tool_output = json.dumps(tool_result, cls=customJSONEncoder)
+                        self.messages.add_tool_message(
+                            content=response_output, output=tool_output
+                        )
+                        self.save()
+                    except Exception as exc:
+                        log(
+                            f"Error executing tool handler '{tool_name}': {exc}",
+                            level=logging.ERROR,
+                            exc=exc,
+                        )
+                        raise RuntimeError(
+                            f"Error in tool handler '{tool_name}': {exc}"
+                        )
+
+                    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:
-                        tool_result = coerce_jsonable(tool_result_json)
-                        tool_output = json.dumps(tool_result, cls=customJSONEncoder)
-                    self.messages.add_tool_message(
-                        content=response_output, output=tool_output
+                        print(tool_result)
+                        parsed_result = cast(T, tool_result)
+
+                if isinstance(response_output, ResponseOutputMessage):
+                    self.messages.add_assistant_message(
+                        response_output, metadata=kwargs
                     )
                     self.save()
-                except Exception as exc:
-                    log(
-                        f"Error executing tool handler '{tool_name}': {exc}",
-                        level=logging.ERROR,
-                    )
-                    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()
-                    parsed_result = output_dict
-                else:
-                    print(tool_result)
-                    parsed_result = cast(T, tool_result)
-
-            if isinstance(response_output, ResponseOutputMessage):
-                self.messages.add_assistant_message(response_output, metadata=kwargs)
-                self.save()
-                if hasattr(response, "output_text") and response.output_text:
-                    raw_text = response.output_text
-                    log("No tool call. Parsing output_text.")
-                    try:
-                        output_dict = json.loads(raw_text)
-                        if self._output_structure:
-                            return self._output_structure.from_raw_input(output_dict)
-                        return output_dict
-                    except Exception:
-                        print(raw_text)
-        if parsed_result is not None:
-            return parsed_result
-        return None
+                    if hasattr(response, "output_text") and response.output_text:
+                        raw_text = response.output_text
+                        log("No tool call. Parsing output_text.")
+                        try:
+                            output_dict = json.loads(raw_text)
+                            if self._output_structure:
+                                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 response.output_text
+        except Exception as exc:
+            try:
+                self.save_error(exc)
+            except Exception as save_exc:
+                log(
+                    f"Failed to save error details for response {self.uuid}: {save_exc}",
+                    level=logging.ERROR,
+                    exc=save_exc,
+                )
+            log(
+                f"Error running response '{self._name}': {exc}",
+                level=logging.ERROR,
+                exc=exc,
+            )
+            raise
 
     def run_sync(
         self,
@@ -602,7 +676,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 +701,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 +728,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 +739,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 +750,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.
 
@@ -874,6 +889,36 @@ class ResponseBase(Generic[T]):
         self.messages.to_json_file(str(checked))
         log(f"Saved messages to {target}")
 
+    def save_error(self, exc: BaseException) -> Path:
+        """Persist error details to a file named with the response UUID.
+
+        Parameters
+        ----------
+        exc : BaseException
+            Exception instance to serialize.
+
+        Returns
+        -------
+        Path
+            Path to the error file written to disk.
+
+        Examples
+        --------
+        >>> try:
+        ...     response.run_sync("trigger error")
+        ... except Exception as exc:
+        ...     response.save_error(exc)
+        """
+        error_text = "".join(
+            traceback.format_exception(type(exc), exc, exc.__traceback__)
+        )
+        filename = f"{str(self.uuid).lower()}_error.txt"
+        target = self._data_path / self._name / filename
+        checked = check_filepath(filepath=target)
+        checked.write_text(error_text, encoding="utf-8")
+        log(f"Saved error details to {checked}")
+        return checked
+
     def __repr__(self) -> str:
         """Return a detailed string representation of the response session.
 
@@ -945,7 +990,19 @@ class ResponseBase(Generic[T]):
                         f"Files API cleanup: {successful}/{len(cleanup_results)} files deleted"
                     )
         except Exception as exc:
-            log(f"Error cleaning up Files API uploads: {exc}", level=logging.WARNING)
+            try:
+                self.save_error(exc)
+            except Exception as save_exc:
+                log(
+                    f"Failed to save error details for response {self.uuid}: {save_exc}",
+                    level=logging.ERROR,
+                    exc=save_exc,
+                )
+            log(
+                f"Error cleaning up Files API uploads: {exc}",
+                level=logging.WARNING,
+                exc=exc,
+            )
 
         # Always clean user vector storage if it exists
         try:
@@ -953,6 +1010,18 @@ class ResponseBase(Generic[T]):
                 self._user_vector_storage.delete()
                 log("User vector store deleted.")
         except Exception as exc:
-            log(f"Error deleting user vector store: {exc}", level=logging.WARNING)
+            try:
+                self.save_error(exc)
+            except Exception as save_exc:
+                log(
+                    f"Failed to save error details for response {self.uuid}: {save_exc}",
+                    level=logging.ERROR,
+                    exc=save_exc,
+                )
+            log(
+                f"Error deleting user vector store: {exc}",
+                level=logging.WARNING,
+                exc=exc,
+            )
         # System vector store cleanup is now handled via tool configuration
         log(f"Session {self.uuid} closed.")