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

openai_sdk_helpers/response/files.py

@@ -0,0 +1,392 @@
+"""File attachment utilities for responses.
+
+This module provides functions for processing file attachments, automatically
+detecting file types (images vs documents), and preparing them for the OpenAI API
+with appropriate encoding (base64 or vector store). Supports both individual and
+batch file processing.
+"""
+
+from __future__ import annotations
+
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, cast
+
+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 ..utils import create_file_data_url, create_image_data_url, is_image_file, log
+
+if TYPE_CHECKING:  # pragma: no cover
+    from .base import BaseResponse
+
+
+def process_files(
+    response: BaseResponse[Any],
+    files: list[str],
+    use_vector_store: bool = False,
+    batch_size: int = 10,
+    max_workers: int = 5,
+) -> tuple[
+    list[ResponseInputFileParam],
+    list[ResponseInputFileContentParam],
+    list[ResponseInputImageContentParam],
+]:
+    """Process file attachments and prepare them for OpenAI API.
+
+    Automatically categorizes files by type (images vs documents) and
+    processes them appropriately. Supports concurrent processing for efficient
+    handling of multiple files.
+
+    Parameters
+    ----------
+    response : BaseResponse[Any]
+        Response instance that will use the processed files.
+    files : list[str]
+        List of file paths to process.
+    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.
+    batch_size : int, default 10
+        Maximum number of files to submit to thread pool at once.
+        Processes files in chunks to avoid overwhelming the executor.
+    max_workers : int, default 5
+        Maximum number of concurrent workers for processing.
+
+    Returns
+    -------
+    tuple[list, list, list]
+        Three lists containing:
+        1. Vector store file references (ResponseInputFileParam)
+        2. Base64-encoded file content (ResponseInputFileContentParam)
+        3. Base64-encoded image content (ResponseInputImageContentParam)
+
+    Examples
+    --------
+    >>> from openai_sdk_helpers.response import process_files
+    >>> vector_files, base64_files, images = process_files(
+    ...     response,
+    ...     ["photo.jpg", "document.pdf"],
+    ...     use_vector_store=False
+    ... )
+
+    >>> # Batch process many files
+    >>> vector_files, base64_files, images = process_files(
+    ...     response,
+    ...     ["file1.pdf", "file2.pdf", ...],  # Many files
+    ...     batch_size=20,
+    ...     max_workers=10
+    ... )
+    """
+    # Categorize files by type
+    image_files: list[str] = []
+    document_files: list[str] = []
+
+    for file_path in files:
+        if is_image_file(file_path):
+            image_files.append(file_path)
+        else:
+            document_files.append(file_path)
+
+    # Handle document files (vector store or base64)
+    vector_file_refs: list[ResponseInputFileParam] = []
+    base64_files: list[ResponseInputFileContentParam] = []
+
+    if document_files:
+        if use_vector_store:
+            # Upload to vector store (sequential for now)
+            vector_file_refs = _upload_to_vector_store(response, document_files)
+        else:
+            # Use batch processing for base64 encoding
+            base64_files = _encode_documents_base64_batch(
+                document_files, batch_size, max_workers
+            )
+
+    # Handle images (always base64) with batch processing
+    image_contents = _encode_images_base64_batch(image_files, batch_size, max_workers)
+
+    return vector_file_refs, base64_files, image_contents
+
+
+def _upload_to_vector_store(
+    response: BaseResponse[Any], document_files: list[str]
+) -> list[ResponseInputFileParam]:
+    """Upload documents to vector store and return file references.
+
+    Uploads user files with purpose="user_data" for proper categorization
+    and cleanup according to OpenAI Files API conventions.
+
+    Parameters
+    ----------
+    response : BaseResponse[Any]
+        Response instance with vector storage.
+    document_files : list[str]
+        List of document file paths to upload.
+
+    Returns
+    -------
+    list[ResponseInputFileParam]
+        List of file references for vector store files.
+
+    Notes
+    -----
+    Files are uploaded with purpose="user_data" to distinguish them
+    from assistant files. All user files are automatically deleted
+    when the response is closed via the vector store cleanup.
+    """
+    file_refs: list[ResponseInputFileParam] = []
+
+    if response._user_vector_storage is None:
+        from openai_sdk_helpers.vector_storage import VectorStorage
+
+        store_name = f"{response.__class__.__name__.lower()}_{response._name}_{response.uuid}_user"
+        response._user_vector_storage = VectorStorage(
+            store_name=store_name,
+            client=response._client,
+            model=response._model,
+        )
+        user_vector_storage = cast(Any, response._user_vector_storage)
+        if not any(tool.get("type") == "file_search" for tool in response._tools):
+            response._tools.append(
+                {
+                    "type": "file_search",
+                    "vector_store_ids": [user_vector_storage.id],
+                }
+            )
+
+    user_vector_storage = cast(Any, response._user_vector_storage)
+    for file_path in document_files:
+        # Upload with purpose="user_data" for user-uploaded files
+        uploaded_file = user_vector_storage.upload_file(file_path, purpose="user_data")
+        file_refs.append(
+            ResponseInputFileParam(type="input_file", file_id=uploaded_file.id)
+        )
+
+        # Best-effort tracking with FilesAPIManager (if available on the response)
+        files_manager = getattr(response, "_files_manager", None)
+        if files_manager is not None:
+            # Prefer tracking by file ID; fall back to full object if needed.
+            try:
+                files_manager.track_file(uploaded_file.id)
+            except AttributeError:
+                try:
+                    files_manager.track_file(uploaded_file)
+                except AttributeError:
+                    # If the manager does not support tracking in either form,
+                    # silently skip to avoid breaking existing behavior.
+                    pass
+    return file_refs
+
+
+def _encode_documents_base64(
+    document_files: list[str],
+) -> list[ResponseInputFileContentParam]:
+    """Encode documents as base64 for inline attachment.
+
+    Parameters
+    ----------
+    document_files : list[str]
+        List of document file paths to encode.
+
+    Returns
+    -------
+    list[ResponseInputFileContentParam]
+        List of base64-encoded file content parameters.
+    """
+    base64_files: list[ResponseInputFileContentParam] = []
+
+    for file_path in document_files:
+        file_data_url = create_file_data_url(file_path)
+        filename = Path(file_path).name
+        base64_files.append(
+            ResponseInputFileContentParam(
+                type="input_file",
+                file_data=file_data_url,
+                filename=filename,
+            )
+        )
+
+    return base64_files
+
+
+def _encode_documents_base64_batch(
+    document_files: list[str],
+    batch_size: int = 10,
+    max_workers: int = 5,
+) -> list[ResponseInputFileContentParam]:
+    """Encode documents as base64 with batch processing.
+
+    Uses thread pool for concurrent encoding of multiple files.
+
+    Parameters
+    ----------
+    document_files : list[str]
+        List of document file paths to encode.
+    batch_size : int, default 10
+        Number of files to process in each batch.
+    max_workers : int, default 5
+        Maximum number of concurrent workers.
+
+    Returns
+    -------
+    list[ResponseInputFileContentParam]
+        List of base64-encoded file content parameters.
+    """
+    if not document_files:
+        return []
+
+    # If small number of files, process sequentially
+    if len(document_files) <= 3:
+        return _encode_documents_base64(document_files)
+
+    base64_files: list[ResponseInputFileContentParam] = []
+
+    def encode_single_document(file_path: str) -> ResponseInputFileContentParam:
+        """Encode a single document file."""
+        file_data_url = create_file_data_url(file_path)
+        filename = Path(file_path).name
+        return ResponseInputFileContentParam(
+            type="input_file",
+            file_data=file_data_url,
+            filename=filename,
+        )
+
+    # Process files concurrently in batches using thread pool
+    log(
+        f"Processing {len(document_files)} documents in batches of {batch_size} "
+        f"with {max_workers} workers"
+    )
+
+    with ThreadPoolExecutor(max_workers=max_workers) as executor:
+        # Process files in batches to avoid overwhelming the executor
+        for batch_start in range(0, len(document_files), batch_size):
+            batch_end = min(batch_start + batch_size, len(document_files))
+            batch = document_files[batch_start:batch_end]
+
+            # Submit this batch of tasks
+            future_to_file = {
+                executor.submit(encode_single_document, file_path): file_path
+                for file_path in batch
+            }
+
+            # Collect results as they complete
+            for future in as_completed(future_to_file):
+                try:
+                    result = future.result()
+                    base64_files.append(result)
+                except Exception as exc:
+                    file_path = future_to_file[future]
+                    log(f"Error encoding document {file_path}: {exc}")
+                    raise
+
+    return base64_files
+
+
+def _encode_images_base64(
+    image_files: list[str],
+) -> list[ResponseInputImageContentParam]:
+    """Encode images as base64 for inline attachment.
+
+    Parameters
+    ----------
+    image_files : list[str]
+        List of image file paths to encode.
+
+    Returns
+    -------
+    list[ResponseInputImageContentParam]
+        List of base64-encoded image content parameters.
+    """
+    image_contents: list[ResponseInputImageContentParam] = []
+
+    for image_path in image_files:
+        image_url, detail = create_image_data_url(image_path, detail="auto")
+        image_contents.append(
+            ResponseInputImageContentParam(
+                type="input_image",
+                image_url=image_url,
+                detail=detail,
+            )
+        )
+
+    return image_contents
+
+
+def _encode_images_base64_batch(
+    image_files: list[str],
+    batch_size: int = 10,
+    max_workers: int = 5,
+) -> list[ResponseInputImageContentParam]:
+    """Encode images as base64 with batch processing.
+
+    Uses thread pool for concurrent encoding of multiple images.
+
+    Parameters
+    ----------
+    image_files : list[str]
+        List of image file paths to encode.
+    batch_size : int, default 10
+        Number of images to process in each batch.
+    max_workers : int, default 5
+        Maximum number of concurrent workers.
+
+    Returns
+    -------
+    list[ResponseInputImageContentParam]
+        List of base64-encoded image content parameters.
+    """
+    if not image_files:
+        return []
+
+    # If small number of files, process sequentially
+    if len(image_files) <= 3:
+        return _encode_images_base64(image_files)
+
+    image_contents: list[ResponseInputImageContentParam] = []
+
+    def encode_single_image(image_path: str) -> ResponseInputImageContentParam:
+        """Encode a single image file."""
+        image_url, detail = create_image_data_url(image_path, detail="auto")
+        return ResponseInputImageContentParam(
+            type="input_image",
+            image_url=image_url,
+            detail=detail,
+        )
+
+    # Process images concurrently in batches using thread pool
+    log(
+        f"Processing {len(image_files)} images in batches of {batch_size} "
+        f"with {max_workers} workers"
+    )
+
+    with ThreadPoolExecutor(max_workers=max_workers) as executor:
+        # Process images in batches to avoid overwhelming the executor
+        for batch_start in range(0, len(image_files), batch_size):
+            batch_end = min(batch_start + batch_size, len(image_files))
+            batch = image_files[batch_start:batch_end]
+
+            # Submit this batch of tasks
+            future_to_file = {
+                executor.submit(encode_single_image, image_path): image_path
+                for image_path in batch
+            }
+
+            # Collect results as they complete
+            for future in as_completed(future_to_file):
+                try:
+                    result = future.result()
+                    image_contents.append(result)
+                except Exception as exc:
+                    image_path = future_to_file[future]
+                    log(f"Error encoding image {image_path}: {exc}")
+                    raise
+
+    return image_contents
+
+
+__all__ = ["process_files"]

openai_sdk_helpers/streamlit_app/app.py

@@ -8,6 +8,7 @@ rendering, response execution, and resource cleanup.
 from __future__ import annotations
 
 import json
+import tempfile
 from pathlib import Path
 from typing import Any
 
@@ -29,6 +30,36 @@ from openai_sdk_helpers.utils import (
     log,
 )
 
+# Supported file extensions for OpenAI Assistants file search
+SUPPORTED_FILE_EXTENSIONS = (
+    ".csv",
+    ".docx",
+    ".html",
+    ".json",
+    ".md",
+    ".pdf",
+    ".pptx",
+    ".txt",
+    ".xlsx",
+)
+
+
+def _validate_file_type(filename: str) -> bool:
+    """Check if a file has a supported extension for vector storage.
+
+    Parameters
+    ----------
+    filename : str
+        Name of the file to validate.
+
+    Returns
+    -------
+    bool
+        True if the file extension is supported, False otherwise.
+    """
+    file_ext = Path(filename).suffix.lower()
+    return file_ext in SUPPORTED_FILE_EXTENSIONS
+
 
 def _extract_assistant_text(response: BaseResponse[Any]) -> str:
     """Extract the latest assistant message as readable text.
@@ -227,6 +258,8 @@ def _init_session_state() -> None:
     """
     if "chat_history" not in st.session_state:
         st.session_state["chat_history"] = []
+    if "uploaded_files" not in st.session_state:
+        st.session_state["uploaded_files"] = []
 
 
 def _render_chat_history() -> None:
@@ -252,9 +285,16 @@ def _render_chat_history() -> None:
                         st.json(raw_output)
             else:
                 st.markdown(message.get("content", ""))
+                attachments = message.get("attachments", [])
+                if attachments:
+                    st.caption(
+                        f"📎 {len(attachments)} file(s) attached: {', '.join(attachments)}"
+                    )
 
 
-def _handle_user_message(prompt: str, config: StreamlitAppConfig) -> None:
+def _handle_user_message(
+    prompt: str, config: StreamlitAppConfig, attachment_paths: list[str] | None = None
+) -> None:
     """Process user input and generate assistant response.
 
     Appends the user message to chat history, executes the response
@@ -267,6 +307,8 @@ def _handle_user_message(prompt: str, config: StreamlitAppConfig) -> None:
         User-entered text to send to the assistant.
     config : StreamlitAppConfig
         Loaded configuration with response handler definition.
+    attachment_paths : list[str] or None, default None
+        Optional list of file paths to attach to the message.
 
     Notes
     -----
@@ -274,7 +316,12 @@ def _handle_user_message(prompt: str, config: StreamlitAppConfig) -> None:
     chat transcript rather than crashing the application. The function
     triggers a Streamlit rerun after successful response generation.
     """
-    st.session_state["chat_history"].append({"role": "user", "content": prompt})
+    attachment_names = (
+        [Path(p).name for p in attachment_paths] if attachment_paths else []
+    )
+    st.session_state["chat_history"].append(
+        {"role": "user", "content": prompt, "attachments": attachment_names}
+    )
     try:
         response = _get_response_instance(config)
     except Exception as exc:  # pragma: no cover - surfaced in UI
@@ -283,7 +330,7 @@ def _handle_user_message(prompt: str, config: StreamlitAppConfig) -> None:
 
     try:
         with st.spinner("Thinking..."):
-            result = response.run_sync(content=prompt)
+            result = response.run_sync(content=prompt, files=attachment_paths)
         summary = _render_summary(result, response)
         raw_output = _build_raw_output(result, response)
         st.session_state["chat_history"].append(
@@ -341,9 +388,41 @@ def main(config_path: Path) -> None:
 
     _render_chat_history()
 
+    # File uploader for attachments
+    uploaded_files = st.file_uploader(
+        "Attach files (optional)",
+        accept_multiple_files=True,
+        key="file_uploader",
+        help=f"Supported formats: {', '.join(sorted(SUPPORTED_FILE_EXTENSIONS))}",
+    )
+
+    # Save uploaded files to temporary directory and track paths
+    attachment_paths: list[str] = []
+    if uploaded_files:
+        invalid_files = []
+        for uploaded_file in uploaded_files:
+            if not _validate_file_type(uploaded_file.name):
+                invalid_files.append(uploaded_file.name)
+                continue
+            with tempfile.NamedTemporaryFile(
+                delete=False, suffix=Path(uploaded_file.name).suffix
+            ) as tmp_file:
+                tmp_file.write(uploaded_file.getbuffer())
+                attachment_paths.append(tmp_file.name)
+
+        if invalid_files:
+            st.warning(
+                f"⚠️ Unsupported file types skipped: {', '.join(invalid_files)}. "
+                f"Supported formats: {', '.join(sorted(SUPPORTED_FILE_EXTENSIONS))}"
+            )
+        if attachment_paths:
+            st.caption(f"📎 {len(attachment_paths)} file(s) ready to attach")
+
     prompt = st.chat_input("Message the assistant")
     if prompt:
-        _handle_user_message(prompt, config)
+        _handle_user_message(
+            prompt, config, attachment_paths if attachment_paths else None
+        )
 
 
 if __name__ == "__main__":

openai_sdk_helpers/utils/__init__.py

@@ -7,6 +7,7 @@ The utils package collects cross-cutting helpers used across the project:
 * Concurrency: async bridging helpers.
 * Output validation: JSON Schema and semantic validators.
 * Instrumentation helpers: deprecation utilities.
+* Encoding: base64 encoding for images and files.
 
 Import style
 ------------
@@ -32,6 +33,8 @@ output_validation
     JSON Schema and semantic output validation utilities.
 deprecation
     Deprecation helpers and warning utilities.
+encoding
+    Base64 encoding helpers for images and files.
 """
 
 from __future__ import annotations
@@ -69,6 +72,14 @@ from .output_validation import (
     validate_output,
 )
 from .deprecation import DeprecationHelper, deprecated, warn_deprecated
+from .encoding import (
+    create_file_data_url,
+    create_image_data_url,
+    encode_file,
+    encode_image,
+    get_mime_type,
+    is_image_file,
+)
 
 __all__ = [
     "ensure_list",
@@ -104,4 +115,11 @@ __all__ = [
     "deprecated",
     "warn_deprecated",
     "DeprecationHelper",
+    # Encoding
+    "encode_image",
+    "encode_file",
+    "get_mime_type",
+    "create_image_data_url",
+    "create_file_data_url",
+    "is_image_file",
 ]