openai-sdk-helpers 0.1.0__py3-none-any.whl → 0.1.2__py3-none-any.whl

openai_sdk_helpers/response/base.py

@@ -25,8 +25,16 @@ from typing import (
     cast,
 )
 
-from openai.types.responses.response_function_tool_call import ResponseFunctionToolCall
+from openai.types.responses.response_function_tool_call import (
+    ResponseFunctionToolCall,
+)
+from openai.types.responses.response_input_file_content_param import (
+    ResponseInputFileContentParam,
+)
 from openai.types.responses.response_input_file_param import ResponseInputFileParam
+from openai.types.responses.response_input_image_content_param import (
+    ResponseInputImageContentParam,
+)
 from openai.types.responses.response_input_message_content_list_param import (
     ResponseInputMessageContentListParam,
 )
@@ -38,16 +46,19 @@ from .messages import ResponseMessage, ResponseMessages
 from ..config import OpenAISettings
 from ..structure import BaseStructure
 from ..types import OpenAIClient
-from ..utils import ensure_list, log
+from ..utils import (
+    check_filepath,
+    coerce_jsonable,
+    customJSONEncoder,
+    ensure_list,
+    log,
+)
 
 if TYPE_CHECKING:  # pragma: no cover - only for typing hints
     from openai_sdk_helpers.streamlit_app.config import StreamlitAppConfig
 
 T = TypeVar("T", bound=BaseStructure)
 ToolHandler = Callable[[ResponseFunctionToolCall], str | Any]
-ProcessContent = Callable[[str], tuple[str, list[str]]]
-
-
 RB = TypeVar("RB", bound="BaseResponse[BaseStructure]")
 
 
@@ -111,16 +122,14 @@ class BaseResponse(Generic[T]):
     def __init__(
         self,
         *,
+        name: str,
         instructions: str,
         tools: list | None,
         output_structure: type[T] | None,
         tool_handlers: dict[str, ToolHandler],
         openai_settings: OpenAISettings,
-        process_content: ProcessContent | None = None,
-        name: str | None = None,
         system_vector_store: list[str] | None = None,
-        data_path_fn: Callable[[str], Path] | None = None,
-        save_path: Path | str | None = None,
+        data_path: Path | str | None = None,
     ) -> None:
         """Initialize a response session with OpenAI configuration.
 
@@ -130,6 +139,9 @@ class BaseResponse(Generic[T]):
 
         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
@@ -144,18 +156,12 @@ class BaseResponse(Generic[T]):
             result.
         openai_settings : OpenAISettings
             Fully configured OpenAI settings with API key and default model.
-        process_content : callable or None, default None
-            Optional callback that processes input text and extracts file
-            attachments. Must return a tuple of (processed_text, attachment_list).
-        name : str or None, default None
-            Module name used for data path construction when data_path_fn is set.
         system_vector_store : list[str] or None, default None
             Optional list of vector store names to attach as system context.
-        data_path_fn : callable or None, default None
-            Function mapping name to a base directory path for artifact storage.
-        save_path : Path, str, or None, default None
-            Optional path to a directory or file where message history is saved.
-            If a directory, files are named using the session UUID.
+        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.
 
         Raises
         ------
@@ -170,18 +176,30 @@ class BaseResponse(Generic[T]):
         >>> from openai_sdk_helpers import BaseResponse, OpenAISettings
         >>> settings = OpenAISettings(api_key="sk-...", default_model="gpt-4")
         >>> response = BaseResponse(
+        ...     name="my_session",
         ...     instructions="You are helpful",
         ...     tools=None,
         ...     output_structure=None,
         ...     tool_handlers={},
-        ...     openai_settings=settings
+        ...     openai_settings=settings,
         ... )
         """
         self._tool_handlers = tool_handlers
-        self._process_content = process_content
         self._name = name
-        self._data_path_fn = data_path_fn
-        self._save_path = Path(save_path) if save_path is not None else None
+
+        # Resolve data_path with class name appended
+        class_name = self.__class__.__name__.lower()
+        if data_path is not None:
+            data_path_obj = Path(data_path)
+            if data_path_obj.name == class_name:
+                self._data_path = data_path_obj
+            else:
+                self._data_path = data_path_obj / class_name
+        else:
+            from ..environment import get_data_path
+
+            self._data_path = get_data_path(class_name)
+
         self._instructions = instructions
         self._tools = tools if tools is not None else []
         self._output_structure = output_structure
@@ -203,7 +221,6 @@ class BaseResponse(Generic[T]):
             )
 
         self.uuid = uuid.uuid4()
-        self.name = self.__class__.__name__.lower()
 
         system_content: ResponseInputMessageContentListParam = [
             ResponseInputTextParam(type="input_text", text=instructions)
@@ -211,6 +228,11 @@ class BaseResponse(Generic[T]):
 
         self._user_vector_storage: Any | None = None
 
+        # Initialize Files API manager for tracking uploaded files
+        from ..files_api import FilesAPIManager
+
+        self._files_manager = FilesAPIManager(self._client, auto_track=True)
+
         # New logic: system_vector_store is a list of vector store names to attach
         if system_vector_store:
             from .vector_store import attach_vector_store
@@ -227,106 +249,93 @@ class BaseResponse(Generic[T]):
 
         self.messages = ResponseMessages()
         self.messages.add_system_message(content=system_content)
-        if self._save_path is not None or (
-            self._data_path_fn is not None and self._name is not None
-        ):
+        if self._data_path is not None:
             self.save()
 
     @property
-    def data_path(self) -> Path:
-        """Return the directory for persisting session artifacts.
-
-        Constructs a path using data_path_fn, name, class name, and the
-        session name. Both data_path_fn and name must be set during
-        initialization for this property to work.
+    def name(self) -> str:
+        """Return the name of this response session.
 
         Returns
         -------
-        Path
-            Absolute path for persisting response artifacts and message history.
-
-        Raises
-        ------
-        RuntimeError
-            If data_path_fn or name were not provided during initialization.
-
-        Examples
-        --------
-        >>> response.data_path
-        PosixPath('/data/myapp/baseresponse/session_123')
+        str
+            Name used for organizing artifacts and naming vector stores.
         """
-        if self._data_path_fn is None or self._name is None:
-            raise RuntimeError(
-                "data_path_fn and name are required to build data paths."
-            )
-        base_path = self._data_path_fn(self._name)
-        return base_path / self.__class__.__name__.lower() / self.name
+        return self._name
 
     def _build_input(
         self,
         content: str | list[str],
-        attachments: list[str] | None = None,
+        files: list[str] | None = None,
+        use_vector_store: bool = False,
     ) -> None:
         """Construct input messages for the OpenAI API request.
 
-        Processes content through the optional process_content callback,
-        uploads any file attachments to vector stores, and adds all
-        messages to the conversation history.
+        Automatically detects file types and handles them appropriately:
+        - Images (jpg, png, gif, etc.) are sent as base64-encoded images
+        - Documents are sent as base64-encoded file data by default
+        - Documents can optionally be uploaded to vector stores for RAG
 
         Parameters
         ----------
         content : str or list[str]
             String or list of strings to include as user messages.
-        attachments : list[str] or None, default None
-            Optional list of file paths to upload and attach to the message.
+        files : list[str] or None, default None
+            Optional list of file paths. Each file is automatically processed
+            based on its type:
+            - Images are base64-encoded as input_image
+            - Documents are base64-encoded as input_file (default)
+            - Documents can be uploaded to vector stores if use_vector_store=True
+        use_vector_store : bool, default False
+            If True, non-image files are uploaded to a vector store for
+            RAG-enabled file search instead of inline base64 encoding.
 
         Notes
         -----
-        If attachments are provided and no user vector storage exists, this
-        method automatically creates one and adds a file_search tool to
-        the tools list.
+        When use_vector_store is True, this method automatically creates
+        a vector store and adds a file_search tool for document retrieval.
+        Images are always base64-encoded regardless of this setting.
+
+        Examples
+        --------
+        >>> # Automatic handling - images as base64, docs inline
+        >>> response._build_input("Analyze these", files=["photo.jpg", "doc.pdf"])
+
+        >>> # Use vector store for documents (RAG)
+        >>> response._build_input(
+        ...     "Search these documents",
+        ...     files=["doc1.pdf", "doc2.pdf"],
+        ...     use_vector_store=True
+        ... )
         """
+        from .files import process_files
+
         contents = ensure_list(content)
+        all_files = files or []
 
+        # Process files using the dedicated files module
+        vector_file_refs, base64_files, image_contents = process_files(
+            self, all_files, use_vector_store
+        )
+
+        # Add each content as a separate message with the same attachments
         for raw_content in contents:
-            if self._process_content is None:
-                processed_text, content_attachments = raw_content, []
-            else:
-                processed_text, content_attachments = self._process_content(raw_content)
-            input_content: list[ResponseInputTextParam | ResponseInputFileParam] = [
-                ResponseInputTextParam(type="input_text", text=processed_text)
-            ]
-
-            all_attachments = (attachments or []) + content_attachments
-
-            for file_path in all_attachments:
-                if self._user_vector_storage is None:
-                    from openai_sdk_helpers.vector_storage import VectorStorage
-
-                    store_name = f"{self.__class__.__name__.lower()}_{self.name}_{self.uuid}_user"
-                    self._user_vector_storage = VectorStorage(
-                        store_name=store_name,
-                        client=self._client,
-                        model=self._model,
-                    )
-                    user_vector_storage = cast(Any, self._user_vector_storage)
-                    if not any(
-                        tool.get("type") == "file_search" for tool in self._tools
-                    ):
-                        self._tools.append(
-                            {
-                                "type": "file_search",
-                                "vector_store_ids": [user_vector_storage.id],
-                            }
-                        )
-                    else:
-                        # If system vector store is attached, its ID will be in tool config
-                        pass
-                user_vector_storage = cast(Any, self._user_vector_storage)
-                uploaded_file = user_vector_storage.upload_file(file_path)
-                input_content.append(
-                    ResponseInputFileParam(type="input_file", file_id=uploaded_file.id)
-                )
+            processed_text = raw_content.strip()
+            input_content: list[
+                ResponseInputTextParam
+                | ResponseInputFileParam
+                | ResponseInputFileContentParam
+                | ResponseInputImageContentParam
+            ] = [ResponseInputTextParam(type="input_text", text=processed_text)]
+
+            # Add vector store file references
+            input_content.extend(vector_file_refs)
+
+            # Add base64 files
+            input_content.extend(base64_files)
+
+            # Add images
+            input_content.extend(image_contents)
 
             message = cast(
                 ResponseInputItemParam,
@@ -337,7 +346,8 @@ class BaseResponse(Generic[T]):
     async def run_async(
         self,
         content: str | list[str],
-        attachments: str | list[str] | None = None,
+        files: str | list[str] | None = None,
+        use_vector_store: bool = False,
     ) -> T | None:
         """Generate a response asynchronously from the OpenAI API.
 
@@ -345,12 +355,21 @@ class BaseResponse(Generic[T]):
         tool calls with registered handlers, and optionally parses the
         result into the configured output_structure.
 
+        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.
-        attachments : str, list[str], or None, default None
-            Optional file path or list of file paths to upload and attach.
+        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
         -------
@@ -368,15 +387,26 @@ class BaseResponse(Generic[T]):
 
         Examples
         --------
-        >>> result = await response.run_async("Analyze this text")
-        >>> print(result)
+        >>> # Automatic type detection
+        >>> result = await response.run_async(
+        ...     "Analyze these files",
+        ...     files=["photo.jpg", "document.pdf"]
+        ... )
+
+        >>> # Use vector store for documents
+        >>> result = await response.run_async(
+        ...     "Search these documents",
+        ...     files=["doc1.pdf", "doc2.pdf"],
+        ...     use_vector_store=True
+        ... )
         """
         log(f"{self.__class__.__name__}::run_response")
         parsed_result: T | None = None
 
         self._build_input(
             content=content,
-            attachments=(ensure_list(attachments) if attachments else None),
+            files=(ensure_list(files) if files else None),
+            use_vector_store=use_vector_store,
         )
 
         kwargs = {
@@ -421,8 +451,8 @@ class BaseResponse(Generic[T]):
                         tool_result = json.loads(tool_result_json)
                         tool_output = tool_result_json
                     else:
-                        tool_result = tool_result_json
-                        tool_output = json.dumps(tool_result)
+                        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
                     )
@@ -443,7 +473,7 @@ class BaseResponse(Generic[T]):
                     parsed_result = cast(T, tool_result)
 
             if isinstance(response_output, ResponseOutputMessage):
-                self.messages.add_assistant_message(response_output, kwargs)
+                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
@@ -462,7 +492,9 @@ class BaseResponse(Generic[T]):
     def run_sync(
         self,
         content: str | list[str],
-        attachments: str | list[str] | None = None,
+        *,
+        files: str | list[str] | None = None,
+        use_vector_store: bool = False,
     ) -> T | None:
         """Execute run_async synchronously with proper event loop handling.
 
@@ -470,12 +502,21 @@ class BaseResponse(Generic[T]):
         a separate thread if necessary. This enables safe usage in both
         synchronous and asynchronous contexts.
 
+        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.
-        attachments : str, list[str], or None, default None
-            Optional file path or list of file paths to upload and attach.
+        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
         -------
@@ -484,12 +525,26 @@ class BaseResponse(Generic[T]):
 
         Examples
         --------
-        >>> result = response.run_sync("Summarize this document")
-        >>> print(result)
+        >>> # Automatic type detection
+        >>> result = response.run_sync(
+        ...     "Analyze these files",
+        ...     files=["photo.jpg", "document.pdf"]
+        ... )
+
+        >>> # Use vector store for documents
+        >>> result = response.run_sync(
+        ...     "Search these documents",
+        ...     files=["doc1.pdf", "doc2.pdf"],
+        ...     use_vector_store=True
+        ... )
         """
 
         async def runner() -> T | None:
-            return await self.run_async(content=content, attachments=attachments)
+            return await self.run_async(
+                content=content,
+                files=files,
+                use_vector_store=use_vector_store,
+            )
 
         try:
             asyncio.get_running_loop()
@@ -509,7 +564,9 @@ class BaseResponse(Generic[T]):
     def run_streamed(
         self,
         content: str | list[str],
-        attachments: str | list[str] | None = None,
+        *,
+        files: str | list[str] | None = None,
+        use_vector_store: bool = False,
     ) -> T | None:
         """Execute run_async and await the result.
 
@@ -517,12 +574,21 @@ class BaseResponse(Generic[T]):
         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.
-        attachments : str, list[str], or None, default None
-            Optional file path or list of file paths to upload and attach.
+        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
         -------
@@ -534,7 +600,13 @@ class BaseResponse(Generic[T]):
         This method exists for API consistency but does not currently
         provide true streaming functionality.
         """
-        return asyncio.run(self.run_async(content=content, attachments=attachments))
+        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.
@@ -629,44 +701,32 @@ 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, save_path from initialization,
-        or data_path_fn if configured.
+        is determined by filepath parameter, or data_path if configured.
 
         Parameters
         ----------
         filepath : str, Path, or None, default None
-            Optional explicit path for the JSON file. If None, uses save_path
-            or constructs path from data_path_fn and session UUID.
+            Optional explicit path for the JSON file. If None, constructs
+            path from data_path and session UUID.
 
         Notes
         -----
-        If no save location is configured (no filepath, save_path, or
-        data_path_fn), the save operation is silently skipped.
+        If no filepath is provided and no data_path was configured during
+        initialization, the save operation is silently skipped.
 
         Examples
         --------
         >>> response.save("/path/to/session.json")
-        >>> response.save()  # Uses configured save_path or data_path
+        >>> response.save()  # Uses data_path / uuid.json
         """
         if filepath is not None:
             target = Path(filepath)
-        elif self._save_path is not None:
-            if self._save_path.suffix == ".json":
-                target = self._save_path
-            else:
-                filename = f"{str(self.uuid).lower()}.json"
-                target = self._save_path / filename
-        elif self._data_path_fn is not None and self._name is not None:
-            filename = f"{str(self.uuid).lower()}.json"
-            target = self.data_path / filename
         else:
-            log(
-                "Skipping save: no filepath, save_path, or data_path_fn configured.",
-                level=logging.DEBUG,
-            )
-            return
+            filename = f"{str(self.uuid).lower()}.json"
+            target = self._data_path / self._name / filename
 
-        self.messages.to_json_file(str(target))
+        checked = check_filepath(filepath=target)
+        self.messages.to_json_file(str(checked))
         log(f"Saved messages to {target}")
 
     def __repr__(self) -> str:
@@ -677,12 +737,9 @@ class BaseResponse(Generic[T]):
         str
             String showing class name, model, UUID, message count, and data path.
         """
-        data_path = None
-        if self._data_path_fn is not None and self._name is not None:
-            data_path = self.data_path
         return (
             f"<{self.__class__.__name__}(model={self._model}, uuid={self.uuid}, "
-            f"messages={len(self.messages.messages)}, data_path={data_path}>"
+            f"messages={len(self.messages.messages)}, data_path={self._data_path}>"
         )
 
     def __enter__(self) -> BaseResponse[T]:
@@ -710,11 +767,11 @@ class BaseResponse(Generic[T]):
         self.close()
 
     def close(self) -> None:
-        """Clean up session resources including vector stores.
+        """Clean up session resources including vector stores and uploaded files.
 
-        Saves the current message history and deletes managed vector stores.
-        User vector stores are always cleaned up. System vector store cleanup
-        is handled via tool configuration.
+        Saves the current message history, deletes managed vector stores, and
+        cleans up all tracked Files API uploads. User vector stores are always
+        cleaned up. System vector store cleanup is handled via tool configuration.
 
         Notes
         -----
@@ -732,6 +789,19 @@ class BaseResponse(Generic[T]):
         """
         log(f"Closing session {self.uuid} for {self.__class__.__name__}")
         self.save()
+
+        # Clean up tracked Files API uploads
+        try:
+            if hasattr(self, "_files_manager") and self._files_manager:
+                cleanup_results = self._files_manager.cleanup()
+                if cleanup_results:
+                    successful = sum(cleanup_results.values())
+                    log(
+                        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)
+
         # Always clean user vector storage if it exists
         try:
             if self._user_vector_storage:

openai_sdk_helpers/response/config.py

@@ -291,6 +291,7 @@ class ResponseConfiguration(Generic[TIn, TOut]):
         self,
         openai_settings: OpenAISettings,
         tool_handlers: dict[str, ToolHandler] = {},
+        add_output_instructions: bool = True,
     ) -> BaseResponse[TOut]:
         """Generate a BaseResponse instance based on the configuration.
 
@@ -302,15 +303,29 @@ class ResponseConfiguration(Generic[TIn, TOut]):
         tool_handlers : dict[str, Callable], optional
             Mapping of tool names to handler callables. Defaults to an empty
             dictionary when not provided.
+        add_output_instructions : bool, default=True
+            Whether to append the structured output prompt to the instructions.
 
         Returns
         -------
         BaseResponse[TOut]
             An instance of BaseResponse configured with ``openai_settings``.
         """
+        output_instructions = ""
+        if self.output_structure is not None and add_output_instructions:
+            output_instructions = self.output_structure.get_prompt(
+                add_enum_values=False
+            )
+
+        instructions = (
+            f"{self.instructions_text}\n{output_instructions}"
+            if output_instructions
+            else self.instructions_text
+        )
+
         return BaseResponse[TOut](
             name=self.name,
-            instructions=self.instructions_text,
+            instructions=instructions,
             tools=self.tools,
             output_structure=self.output_structure,
             tool_handlers=tool_handlers,