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

openai_sdk_helpers/files_api.py

@@ -40,9 +40,10 @@ class FilesAPIManager:
     Parameters
     ----------
     client : OpenAI
-        OpenAI client instance for API calls.
-    auto_track : bool, default True
-        Automatically track uploaded files for cleanup.
+        An initialized OpenAI client instance used for making API calls.
+    auto_track : bool, default=True
+        If True, automatically tracks all files uploaded through the `create`
+        method, making them eligible for automatic deletion via `cleanup()`.
 
     Attributes
     ----------
@@ -95,6 +96,17 @@ class FilesAPIManager:
             OpenAI client instance.
         auto_track : bool, default True
             Automatically track uploaded files for cleanup.
+
+        Raises
+        ------
+        ValueError
+            If the client is not a valid OpenAI client.
+
+        Examples
+        --------
+        >>> from openai import OpenAI
+        >>> client = OpenAI()
+        >>> manager = FilesAPIManager(client)
         """
         self._client = client
         self._auto_track = auto_track
@@ -222,6 +234,11 @@ class FilesAPIManager:
         FileObject
             Information about the file.
 
+        Raises
+        ------
+        NotFoundError
+            If the file ID does not exist.
+
         Examples
         --------
         >>> file_info = manager.retrieve("file-abc123")
@@ -249,6 +266,11 @@ class FilesAPIManager:
         SyncCursorPage[FileObject]
             Page of file objects matching the criteria.
 
+        Raises
+        ------
+        APIError
+            If the OpenAI API call fails.
+
         Examples
         --------
         >>> # List all files
@@ -282,6 +304,11 @@ class FilesAPIManager:
         FileDeleted
             Confirmation of file deletion.
 
+        Raises
+        ------
+        NotFoundError
+            If the file ID does not exist.
+
         Examples
         --------
         >>> result = manager.delete("file-abc123")
@@ -310,6 +337,11 @@ class FilesAPIManager:
         bytes
             The raw bytes of the file content.
 
+        Raises
+        ------
+        NotFoundError
+            If the file ID does not exist.
+
         Examples
         --------
         >>> content = manager.retrieve_content("file-abc123")

openai_sdk_helpers/prompt/base.py

@@ -32,6 +32,12 @@ class PromptRenderer:
     prompt package directory) or can be specified with absolute paths.
     Autoescape is disabled by default since prompts are plain text.
 
+    Parameters
+    ----------
+    base_dir : Path or None, default None
+        Base directory containing Jinja2 templates. If None, uses the
+        prompt package directory containing built-in templates.
+
     Attributes
     ----------
     base_dir : Path

openai_sdk_helpers/response/__init__.py

@@ -7,7 +7,7 @@ building sophisticated AI agents with persistent conversation state.
 
 Classes
 -------
-BaseResponse
+ResponseBase
     Core response manager for OpenAI interactions with structured outputs.
 ResponseConfiguration
     Immutable configuration for defining request/response structures.
@@ -34,7 +34,7 @@ process_files
 
 from __future__ import annotations
 
-from .base import BaseResponse
+from .base import ResponseBase
 from .config import ResponseConfiguration, ResponseRegistry, get_default_registry
 from .files import process_files
 from .messages import ResponseMessage, ResponseMessages
@@ -43,7 +43,7 @@ from .tool_call import ResponseToolCall, parse_tool_arguments
 from .vector_store import attach_vector_store
 
 __all__ = [
-    "BaseResponse",
+    "ResponseBase",
     "ResponseConfiguration",
     "ResponseRegistry",
     "get_default_registry",

openai_sdk_helpers/response/base.py

@@ -1,6 +1,6 @@
 """Core response management for OpenAI API interactions.
 
-This module implements the BaseResponse class, which manages the complete
+This module implements the ResponseBase class, which manages the complete
 lifecycle of OpenAI API interactions including input construction, tool
 execution, message history, vector store attachments, and structured output
 parsing.
@@ -44,7 +44,7 @@ from openai.types.responses.response_output_message import ResponseOutputMessage
 
 from .messages import ResponseMessage, ResponseMessages
 from ..config import OpenAISettings
-from ..structure import BaseStructure
+from ..structure import StructureBase
 from ..types import OpenAIClient
 from ..utils import (
     check_filepath,
@@ -56,14 +56,13 @@ from ..utils import (
 
 if TYPE_CHECKING:  # pragma: no cover - only for typing hints
     from openai_sdk_helpers.streamlit_app.config import StreamlitAppConfig
-    from .config import ResponseConfiguration
 
-T = TypeVar("T", bound=BaseStructure)
+T = TypeVar("T", bound=StructureBase)
 ToolHandler = Callable[[ResponseFunctionToolCall], str | Any]
-RB = TypeVar("RB", bound="BaseResponse[BaseStructure]")
+RB = TypeVar("RB", bound="ResponseBase[StructureBase]")
 
 
-class BaseResponse(Generic[T]):
+class ResponseBase(Generic[T]):
     """Manage OpenAI API interactions for structured responses.
 
     Orchestrates the complete lifecycle of OpenAI API requests including
@@ -75,14 +74,48 @@ class BaseResponse(Generic[T]):
     file attachments via vector stores, and optional parsing into typed
     structured output models. Sessions can be persisted to disk and restored.
 
+    Parameters
+    ----------
+    name : str
+        Name for this response session, used for organizing artifacts
+        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.
+    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
+        response_format() method. Pass None for unstructured responses.
+    system_vector_store : list[str] or None, default None
+        Optional list of vector store names to attach as system context.
+    data_path : Path, str, or None, default None
+        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
+        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
+        Fully configured OpenAI settings with API key and default model.
+        Required for normal operation.
+
     Attributes
     ----------
     uuid : UUID
         Unique identifier for this response session.
     name : str
         Lowercase class name used for path construction.
+    instructions_text : str
+        System instructions provided to the OpenAI API for context.
     messages : ResponseMessages
         Complete message history for this session.
+    output_structure : type[T] | None
+        Structure class used to parse tool call outputs, or None.
+    tools : list | None
+        Tool definitions provided to the OpenAI API, or None.
+
 
     Methods
     -------
@@ -107,9 +140,9 @@ class BaseResponse(Generic[T]):
 
     Examples
     --------
-    >>> from openai_sdk_helpers import BaseResponse, OpenAISettings
+    >>> from openai_sdk_helpers import ResponseBase, OpenAISettings
     >>> settings = OpenAISettings(api_key="...", default_model="gpt-4")
-    >>> response = BaseResponse(
+    >>> response = ResponseBase(
     ...     instructions="You are a helpful assistant",
     ...     tools=None,
     ...     output_structure=None,
@@ -147,7 +180,7 @@ class BaseResponse(Generic[T]):
             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.
-        output_structure : type[BaseStructure] or None
+        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
             response_format() method. Pass None for unstructured responses.
@@ -175,9 +208,9 @@ class BaseResponse(Generic[T]):
 
         Examples
         --------
-        >>> from openai_sdk_helpers import BaseResponse, OpenAISettings
+        >>> from openai_sdk_helpers import ResponseBase, OpenAISettings
         >>> settings = OpenAISettings(api_key="sk-...", default_model="gpt-4")
-        >>> response = BaseResponse(
+        >>> response = ResponseBase(
         ...     name="my_session",
         ...     instructions="You are helpful",
         ...     tools=None,
@@ -186,16 +219,17 @@ class BaseResponse(Generic[T]):
         ...     openai_settings=settings,
         ... )
         """
-        if tool_handlers is None:
-            tool_handlers = {}
         if openai_settings is None:
             raise ValueError("openai_settings is required")
 
+        if tool_handlers is None:
+            tool_handlers = {}
         self._tool_handlers = tool_handlers
+        self.uuid = uuid.uuid4()
         self._name = name
 
         # Resolve data_path with class name appended
-        class_name = self.__class__.__name__.lower()
+        class_name = self.__class__.__name__
         if data_path is not None:
             data_path_obj = Path(data_path)
             if data_path_obj.name == class_name:
@@ -205,7 +239,7 @@ class BaseResponse(Generic[T]):
         else:
             from ..environment import get_data_path
 
-            self._data_path = get_data_path(class_name)
+            self._data_path = get_data_path(self.__class__.__name__)
 
         self._instructions = instructions
         self._tools = tools if tools is not None else []
@@ -227,8 +261,6 @@ class BaseResponse(Generic[T]):
                 "OpenAI model is required. Set 'default_model' on OpenAISettings."
             )
 
-        self.uuid = uuid.uuid4()
-
         system_content: ResponseInputMessageContentListParam = [
             ResponseInputTextParam(type="input_text", text=instructions)
         ]
@@ -274,70 +306,69 @@ class BaseResponse(Generic[T]):
         if self._data_path is not None:
             self.save()
 
-    @classmethod
-    def from_configuration(
-        cls: type[RB],
-        config: "ResponseConfiguration[Any, T]",
-        *,
-        openai_settings: OpenAISettings,
-        tool_handlers: dict[str, ToolHandler] | None = None,
-        add_output_instructions: bool = True,
-    ) -> RB:
-        """Construct a response instance from a configuration object.
+    @property
+    def name(self) -> str:
+        """Return the name of this response session.
 
-        Parameters
-        ----------
-        config : ResponseConfiguration
-            Configuration describing the response inputs, outputs, and tools.
-        openai_settings : OpenAISettings
-            OpenAI authentication and model configuration used for the response.
-        tool_handlers : dict[str, ToolHandler] or None, default None
-            Mapping of tool names to callable handlers. Defaults to an empty
-            dictionary when not provided.
-        add_output_instructions : bool, default True
-            Append structured output instructions when an output structure is
-            present.
+        Returns
+        -------
+        str
+            Name used for organizing artifacts and naming vector stores.
+
+        Examples
+        --------
+        >>> response.name
+        'my_session'
+        """
+        return self._name
+
+    @property
+    def instructions_text(self) -> str:
+        """Return the system instructions for this response.
 
         Returns
         -------
-        BaseResponse
-            Instance of ``cls`` configured from ``config``.
+        str
+            System instructions provided to the OpenAI API.
+
+        Examples
+        --------
+        >>> response.instructions_text
+        'You are a helpful assistant.'
         """
-        handlers = tool_handlers or {}
+        return self._instructions
 
-        output_instructions = ""
-        if config.output_structure is not None and add_output_instructions:
-            output_instructions = config.output_structure.get_prompt(
-                add_enum_values=False
-            )
+    @property
+    def tools(self) -> list | None:
+        """Return the tool definitions for this response.
 
-        instructions = (
-            f"{config.instructions_text}\n{output_instructions}"
-            if output_instructions
-            else config.instructions_text
-        )
+        Returns
+        -------
+        list or None
+            Tool definitions provided to the OpenAI API, or None.
 
-        return cls(
-            name=config.name,
-            instructions=instructions,
-            tools=config.tools,
-            output_structure=config.output_structure,
-            system_vector_store=config.system_vector_store,
-            data_path=config.data_path,
-            tool_handlers=handlers,
-            openai_settings=openai_settings,
-        )
+        Examples
+        --------
+        >>> response.tools
+        []
+        """
+        return self._tools
 
     @property
-    def name(self) -> str:
-        """Return the name of this response session.
+    def output_structure(self) -> type[T] | None:
+        """Return the output structure class for this response.
 
         Returns
         -------
-        str
-            Name used for organizing artifacts and naming vector stores.
+        type[StructureBase] or None
+            Structure class used to parse tool call outputs, or None.
+
+        Examples
+        --------
+        >>> response.output_structure
+        None
         """
-        return self._name
+        return self._output_structure
 
     def _build_input(
         self,
@@ -599,6 +630,14 @@ class BaseResponse(Generic[T]):
         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.
+
         Examples
         --------
         >>> # Automatic type detection
@@ -671,10 +710,22 @@ class BaseResponse(Generic[T]):
         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(
@@ -691,6 +742,10 @@ class BaseResponse(Generic[T]):
         -------
         ResponseMessage or None
             Latest tool message, or None if no tool messages exist.
+
+        Examples
+        --------
+        >>> message = response.get_last_tool_message()
         """
         return self.messages.get_last_tool_message()
 
@@ -701,6 +756,10 @@ class BaseResponse(Generic[T]):
         -------
         ResponseMessage or None
             Latest user message, or None if no user messages exist.
+
+        Examples
+        --------
+        >>> message = response.get_last_user_message()
         """
         return self.messages.get_last_user_message()
 
@@ -711,6 +770,10 @@ class BaseResponse(Generic[T]):
         -------
         ResponseMessage or None
             Latest assistant message, or None if no assistant messages exist.
+
+        Examples
+        --------
+        >>> message = response.get_last_assistant_message()
         """
         return self.messages.get_last_assistant_message()
 
@@ -777,7 +840,7 @@ class BaseResponse(Generic[T]):
         """Serialize the message history to a JSON file.
 
         Saves the complete conversation history to disk. The target path
-        is determined by filepath parameter, or data_path if configured.
+        is determined by filepath parameter, or the configured data_path.
 
         Parameters
         ----------
@@ -787,8 +850,14 @@ class BaseResponse(Generic[T]):
 
         Notes
         -----
-        If no filepath is provided and no data_path was configured during
-        initialization, the save operation is silently skipped.
+        If no filepath is provided, the save operation always writes to
+        the session data path (data_path / name / uuid.json). The data path
+        is configured during initialization and defaults to get_data_path().
+
+        Raises
+        ------
+        IOError
+            If the file cannot be written to disk.
 
         Examples
         --------
@@ -818,12 +887,12 @@ class BaseResponse(Generic[T]):
             f"messages={len(self.messages.messages)}, data_path={self._data_path}>"
         )
 
-    def __enter__(self) -> BaseResponse[T]:
+    def __enter__(self) -> ResponseBase[T]:
         """Enter the context manager for resource management.
 
         Returns
         -------
-        BaseResponse[T]
+        ResponseBase[T]
             Self reference for use in with statements.
         """
         return self
@@ -857,7 +926,7 @@ class BaseResponse(Generic[T]):
 
         Examples
         --------
-        >>> response = BaseResponse(...)
+        >>> response = ResponseBase(...)
         >>> try:
         ...     result = response.run_sync("query")
         ... finally: