openai-sdk-helpers 0.1.1__py3-none-any.whl → 0.1.4__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,8 @@ rendering, response execution, and resource cleanup.
 from __future__ import annotations
 
 import json
+import os
+import tempfile
 from pathlib import Path
 from typing import Any
 
@@ -29,6 +31,70 @@ from openai_sdk_helpers.utils import (
     log,
 )
 
+# Supported file extensions for OpenAI Assistants file search and vision
+SUPPORTED_FILE_EXTENSIONS = (
+    ".csv",
+    ".docx",
+    ".gif",
+    ".html",
+    ".json",
+    ".jpeg",
+    ".jpg",
+    ".md",
+    ".pdf",
+    ".png",
+    ".pptx",
+    ".txt",
+    ".webp",
+    ".xlsx",
+)
+
+
+def _validate_file_type(filename: str) -> bool:
+    """Check if a file has a supported extension for upload.
+
+    Supports both document formats (for file search) and image formats
+    (for vision analysis).
+
+    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 _cleanup_temp_files(file_paths: list[str] | None = None) -> None:
+    """Delete temporary files that were created for uploads.
+
+    Parameters
+    ----------
+    file_paths : list[str] or None, default None
+        Specific file paths to delete. If None, deletes all tracked
+        temporary files from session state.
+
+    Notes
+    -----
+    Silently ignores errors when deleting files that may have already
+    been removed or are inaccessible.
+    """
+    paths_to_delete = file_paths or st.session_state.get("temp_file_paths", [])
+    for path in paths_to_delete:
+        try:
+            if os.path.exists(path):
+                os.remove(path)
+        except (OSError, IOError):
+            pass  # Silently ignore if file already deleted or inaccessible
+
+    if file_paths is None:
+        st.session_state["temp_file_paths"] = []
+
 
 def _extract_assistant_text(response: BaseResponse[Any]) -> str:
     """Extract the latest assistant message as readable text.
@@ -55,15 +121,33 @@ def _extract_assistant_text(response: BaseResponse[Any]) -> str:
     if message is None:
         return ""
 
+    # Check if the message content has output_text attribute
+    output_text = getattr(message.content, "output_text", None)
+    if output_text:
+        return str(output_text)
+
     content = getattr(message.content, "content", None)
     if content is None:
         return ""
 
     text_parts: list[str] = []
     for part in ensure_list(content):
-        text_value = getattr(getattr(part, "text", None), "value", None)
-        if text_value:
-            text_parts.append(text_value)
+        # Handle both dict-like parts and object-like parts
+        text_content = None
+        if hasattr(part, "text"):
+            text_content = getattr(part, "text", None)
+        elif isinstance(part, dict):
+            text_content = part.get("text")
+
+        if text_content:
+            # If text_content is a string, use it directly (dict-style)
+            if isinstance(text_content, str):
+                text_parts.append(text_content)
+            # If text_content is an object with a value attribute, extract that value (object-style)
+            else:
+                text_value = getattr(text_content, "value", None)
+                if text_value:
+                    text_parts.append(text_value)
     if text_parts:
         return "\n\n".join(text_parts)
     return ""
@@ -192,7 +276,8 @@ def _reset_chat(close_response: bool = True) -> None:
     """Clear conversation and optionally close the response session.
 
     Saves the current conversation to disk, closes the response to clean
-    up resources, and clears the chat history from session state.
+    up resources, and clears the chat history from session state. Also
+    cleans up any temporary files that were created for uploads.
 
     Parameters
     ----------
@@ -203,13 +288,17 @@ def _reset_chat(close_response: bool = True) -> None:
     Notes
     -----
     This function mutates st.session_state in-place, clearing the
-    chat_history and response_instance keys.
+    chat_history, response_instance, and temp_file_paths keys.
     """
     response = st.session_state.get("response_instance")
     if close_response and isinstance(response, BaseResponse):
         filepath = f"./data/{response.name}.{response.uuid}.json"
         response.save(filepath)
         response.close()
+
+    # Clean up temporary files
+    _cleanup_temp_files()
+
     st.session_state["chat_history"] = []
     st.session_state.pop("response_instance", None)
 
@@ -218,7 +307,8 @@ def _init_session_state() -> None:
     """Initialize Streamlit session state for chat functionality.
 
     Creates the chat_history list in session state if it doesn't exist,
-    enabling conversation persistence across Streamlit reruns.
+    enabling conversation persistence across Streamlit reruns. Also
+    initializes a list for tracking temporary file paths that need cleanup.
 
     Notes
     -----
@@ -227,6 +317,12 @@ def _init_session_state() -> None:
     """
     if "chat_history" not in st.session_state:
         st.session_state["chat_history"] = []
+    if "temp_file_paths" not in st.session_state:
+        st.session_state["temp_file_paths"] = []
+    if "current_attachments" not in st.session_state:
+        st.session_state["current_attachments"] = []
+    if "attachment_names" not in st.session_state:
+        st.session_state["attachment_names"] = []
 
 
 def _render_chat_history() -> None:
@@ -252,9 +348,19 @@ def _render_chat_history() -> None:
                         st.json(raw_output)
             else:
                 st.markdown(message.get("content", ""))
-
-
-def _handle_user_message(prompt: str, config: StreamlitAppConfig) -> None:
+                attachments = message.get("attachments", [])
+                if attachments:
+                    st.caption(
+                        f"📎 {len(attachments)} file(s) attached: {', '.join(attachments)}"
+                    )
+
+
+def _handle_user_message(
+    prompt: str,
+    config: StreamlitAppConfig,
+    attachment_paths: list[str] | None = None,
+    attachment_names: list[str] | None = None,
+) -> None:
     """Process user input and generate assistant response.
 
     Appends the user message to chat history, executes the response
@@ -267,6 +373,10 @@ 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.
+    attachment_names : list[str] or None, default None
+        Optional list of original filenames for display purposes.
 
     Notes
     -----
@@ -274,7 +384,16 @@ 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})
+    # Use provided display names or fall back to extracting from paths
+    display_names = (
+        attachment_names
+        if attachment_names
+        else [Path(p).name for p in attachment_paths] if attachment_paths else []
+    )
+
+    st.session_state["chat_history"].append(
+        {"role": "user", "content": prompt, "attachments": display_names}
+    )
     try:
         response = _get_response_instance(config)
     except Exception as exc:  # pragma: no cover - surfaced in UI
@@ -283,7 +402,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 +460,64 @@ def main(config_path: Path) -> None:
 
     _render_chat_history()
 
+    # File uploader form - auto-clears on submit
+    with st.form("file_upload_form", clear_on_submit=True):
+        uploaded_files = st.file_uploader(
+            "Attach files (optional)",
+            accept_multiple_files=True,
+            help=f"Supported formats: {', '.join(sorted(SUPPORTED_FILE_EXTENSIONS))}",
+        )
+        submit_files = st.form_submit_button("Attach files")
+
+    # Process uploaded files if form was submitted
+    attachment_paths: list[str] = []
+    original_filenames: list[str] = []
+    if submit_files and 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
+
+            # Create temporary file with the uploaded content
+            with tempfile.NamedTemporaryFile(
+                delete=False, suffix=Path(uploaded_file.name).suffix
+            ) as tmp_file:
+                tmp_file.write(uploaded_file.getbuffer())
+                tmp_file.flush()
+                attachment_paths.append(tmp_file.name)
+                original_filenames.append(uploaded_file.name)
+                # Track for cleanup
+                if tmp_file.name not in st.session_state.get("temp_file_paths", []):
+                    st.session_state["temp_file_paths"].append(tmp_file.name)
+
+        if invalid_files:
+            st.warning(
+                f"⚠️ Unsupported file types: {', '.join(invalid_files)}. "
+                f"Supported: {', '.join(sorted(SUPPORTED_FILE_EXTENSIONS))}"
+            )
+        if attachment_paths:
+            st.session_state["current_attachments"] = attachment_paths
+            st.session_state["attachment_names"] = original_filenames
+            st.info(f"📎 {len(attachment_paths)} file(s) attached")
+
+    # Get attachment paths from session state if they were previously attached
+    attachment_paths = st.session_state.get("current_attachments", [])
+    attachment_display_names = st.session_state.get("attachment_names", [])
+    if attachment_paths:
+        st.caption(f"Ready to send: {', '.join(attachment_display_names)}")
+
     prompt = st.chat_input("Message the assistant")
     if prompt:
-        _handle_user_message(prompt, config)
+        # Clear attachments before rerun to prevent them from being sent again
+        st.session_state["current_attachments"] = []
+        st.session_state["attachment_names"] = []
+        _handle_user_message(
+            prompt,
+            config,
+            attachment_paths or None,
+            attachment_display_names or None,
+        )
 
 
 if __name__ == "__main__":