openai-sdk-helpers 0.2.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,
@@ -57,12 +57,12 @@ from ..utils import (
 if TYPE_CHECKING:  # pragma: no cover - only for typing hints
     from openai_sdk_helpers.streamlit_app.config import StreamlitAppConfig
 
-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
@@ -74,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
     -------
@@ -106,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,
@@ -146,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.
@@ -174,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,
@@ -185,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:
@@ -204,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 []
@@ -226,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)
         ]
@@ -253,6 +286,21 @@ class BaseResponse(Generic[T]):
                 ),
             )
 
+            # Add retrieval guidance to system instructions to encourage RAG usage
+            try:
+                store_names = ", ".join(system_vector_store)
+            except Exception:
+                store_names = "attached vector stores"
+            guidance_text = (
+                "Retrieval guidance: You have access to a file_search tool "
+                f"connected to vector store(s) {store_names}. When relevant, "
+                "use file_search to retrieve supporting passages before answering. "
+                "Cite or reference retrieved content when helpful."
+            )
+            system_content.append(
+                ResponseInputTextParam(type="input_text", text=guidance_text)
+            )
+
         self.messages = ResponseMessages()
         self.messages.add_system_message(content=system_content)
         if self._data_path is not None:
@@ -266,9 +314,62 @@ class BaseResponse(Generic[T]):
         -------
         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
+        -------
+        str
+            System instructions provided to the OpenAI API.
+
+        Examples
+        --------
+        >>> response.instructions_text
+        'You are a helpful assistant.'
+        """
+        return self._instructions
+
+    @property
+    def tools(self) -> list | None:
+        """Return the tool definitions for this response.
+
+        Returns
+        -------
+        list or None
+            Tool definitions provided to the OpenAI API, or None.
+
+        Examples
+        --------
+        >>> response.tools
+        []
+        """
+        return self._tools
+
+    @property
+    def output_structure(self) -> type[T] | None:
+        """Return the output structure class for this response.
+
+        Returns
+        -------
+        type[StructureBase] or None
+            Structure class used to parse tool call outputs, or None.
+
+        Examples
+        --------
+        >>> response.output_structure
+        None
+        """
+        return self._output_structure
+
     def _build_input(
         self,
         content: str | list[str],
@@ -529,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
@@ -601,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(
@@ -621,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()
 
@@ -631,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()
 
@@ -641,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()
 
@@ -707,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
         ----------
@@ -717,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
         --------
@@ -748,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
@@ -787,7 +926,7 @@ class BaseResponse(Generic[T]):
 
         Examples
         --------
-        >>> response = BaseResponse(...)
+        >>> response = ResponseBase(...)
         >>> try:
         ...     result = response.run_sync("query")
         ... finally: