openai-sdk-helpers 0.1.0__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/response/messages.py

@@ -155,6 +155,7 @@ class ResponseMessages(JSONSerializable):
     def add_assistant_message(
         self,
         content: ResponseOutputMessage,
+        *,
         metadata: dict[str, str | float | bool],
     ) -> None:
         """Append an assistant message to the conversation.

openai_sdk_helpers/retry.py

@@ -15,7 +15,7 @@ from typing import Any, Callable, ParamSpec, TypeVar
 from openai import APIError, RateLimitError
 
 from openai_sdk_helpers.errors import AsyncExecutionError
-from openai_sdk_helpers.utils.core import log
+from openai_sdk_helpers.logging_config import log
 
 P = ParamSpec("P")
 T = TypeVar("T")

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
 
@@ -22,7 +23,42 @@ from openai_sdk_helpers.streamlit_app import (
     _load_configuration,
 )
 from openai_sdk_helpers.structure.base import BaseStructure
-from openai_sdk_helpers.utils import coerce_jsonable, ensure_list, log
+from openai_sdk_helpers.utils import (
+    coerce_jsonable,
+    customJSONEncoder,
+    ensure_list,
+    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:
@@ -90,10 +126,16 @@ def _render_summary(result: Any, response: BaseResponse[Any]) -> str:
     """
     if isinstance(result, BaseStructure):
         return result.print()
+    if isinstance(result, str):
+        return result
     if isinstance(result, dict):
-        return json.dumps(result, indent=2)
+        return json.dumps(coerce_jsonable(result), indent=2, cls=customJSONEncoder)
     if result:
-        return str(result)
+        coerced = coerce_jsonable(result)
+        try:
+            return json.dumps(coerced, indent=2, cls=customJSONEncoder)
+        except TypeError:
+            return str(result)
 
     fallback_text = _extract_assistant_text(response)
     if fallback_text:
@@ -216,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:
@@ -241,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
@@ -256,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
     -----
@@ -263,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
@@ -272,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(
@@ -330,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/streamlit_app/streamlit_web_search.py

@@ -6,7 +6,8 @@ from openai_sdk_helpers.config import OpenAISettings
 from openai_sdk_helpers.response.base import BaseResponse
 from openai_sdk_helpers.structure.web_search import WebSearchStructure
 from openai_sdk_helpers.structure.prompt import PromptStructure
-from openai_sdk_helpers.utils.core import customJSONEncoder
+from openai_sdk_helpers.tools import ToolSpec, build_tool_definitions
+from openai_sdk_helpers.utils import coerce_jsonable, customJSONEncoder
 from openai_sdk_helpers.environment import DEFAULT_MODEL
 
 
@@ -24,13 +25,18 @@ class StreamlitWebSearch(BaseResponse[WebSearchStructure]):
         if not settings.default_model:
             settings = settings.model_copy(update={"default_model": DEFAULT_MODEL})
         super().__init__(
+            name="streamlit_web_search",
             instructions="Perform web searches and generate reports.",
-            tools=[
-                PromptStructure.response_tool_definition(
-                    tool_name="perform_search",
-                    tool_description="Tool to perform web searches and generate reports.",
-                )
-            ],
+            tools=build_tool_definitions(
+                [
+                    ToolSpec(
+                        structure=PromptStructure,
+                        tool_name="perform_search",
+                        tool_description="Tool to perform web searches and generate reports.",
+                        output_structure=WebSearchStructure,
+                    )
+                ]
+            ),
             output_structure=WebSearchStructure,
             tool_handlers={"perform_search": perform_search},
             openai_settings=settings,
@@ -43,7 +49,8 @@ async def perform_search(tool) -> str:
     web_result = await WebAgentSearch(default_model=DEFAULT_MODEL).run_web_agent_async(
         structured_data.prompt
     )
-    return json.dumps(web_result.to_json(), cls=customJSONEncoder)
+    payload = coerce_jsonable(web_result)
+    return json.dumps(payload, cls=customJSONEncoder)
 
 
 APP_CONFIG = {

openai_sdk_helpers/structure/base.py

@@ -233,7 +233,7 @@ class BaseStructure(BaseModel):
         return prompt_lines
 
     @classmethod
-    def assistant_tool_definition(cls, name: str, description: str) -> dict:
+    def assistant_tool_definition(cls, name: str, *, description: str) -> dict:
         """Build an Assistant API function tool definition for this structure.
 
         Creates a tool definition compatible with the OpenAI Assistant API,
@@ -255,7 +255,7 @@ class BaseStructure(BaseModel):
         --------
         >>> tool = MyStructure.assistant_tool_definition(
         ...     "analyze_data",
-        ...     "Analyze the provided data"
+        ...     description="Analyze the provided data"
         ... )
         """
         from .responses import assistant_tool_definition
@@ -283,7 +283,7 @@ class BaseStructure(BaseModel):
         return assistant_format(cls)
 
     @classmethod
-    def response_tool_definition(cls, tool_name: str, tool_description: str) -> dict:
+    def response_tool_definition(cls, tool_name: str, *, tool_description: str) -> dict:
         """Build a chat completion tool definition for this structure.
 
         Creates a function tool definition compatible with the chat
@@ -305,7 +305,7 @@ class BaseStructure(BaseModel):
         --------
         >>> tool = MyStructure.response_tool_definition(
         ...     "process_data",
-        ...     "Process the input data"
+        ...     tool_description="Process the input data"
         ... )
         """
         from .responses import response_tool_definition
@@ -725,7 +725,7 @@ class BaseStructure(BaseModel):
         return cls.from_raw_input(structured_data)
 
     @staticmethod
-    def format_output(label: str, value: Any) -> str:
+    def format_output(label: str, *, value: Any) -> str:
         """
         Format a label and value for string output.
 
@@ -772,7 +772,7 @@ class BaseStructure(BaseModel):
         """
         return "\n".join(
             [
-                BaseStructure.format_output(field, value)
+                BaseStructure.format_output(field, value=value)
                 for field, value in self.model_dump().items()
             ]
         )

openai_sdk_helpers/structure/plan/helpers.py

@@ -122,6 +122,7 @@ def execute_task(
 def execute_plan(
     plan: PlanStructure,
     agent_registry: AgentRegistry,
+    *,
     halt_on_error: bool = True,
 ) -> list[str]:
     """Execute a plan using registered agent callables.