openai-sdk-helpers 0.1.1__tar.gz → 0.1.4__tar.gz

{openai_sdk_helpers-0.1.1 → openai_sdk_helpers-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openai-sdk-helpers
-Version: 0.1.1
+Version: 0.1.4
 Summary: Composable helpers for OpenAI SDK agents, prompts, and storage
 Author: openai-sdk-helpers maintainers
 License: MIT
@@ -306,6 +306,99 @@ response.close()
 
 ## Advanced Usage
 
+### Image and File Analysis
+
+The `response` module automatically detects file types and handles them appropriately:
+
+```python
+from openai_sdk_helpers.response import BaseResponse
+from openai_sdk_helpers import OpenAISettings
+
+settings = OpenAISettings.from_env()
+
+with BaseResponse(
+    name="analyzer",
+    instructions="You are a helpful assistant that can analyze files.",
+    tools=None,
+    output_structure=None,
+    tool_handlers={},
+    openai_settings=settings,
+) as response:
+    # Automatic type detection - single files parameter
+    # Images are sent as base64-encoded images
+    # Documents are sent as base64-encoded file data
+    result = response.run_sync(
+        "Analyze these files",
+        files=["photo.jpg", "document.pdf"]
+    )
+    print(result)
+    
+    # Single file - automatically detected
+    result = response.run_sync(
+        "What's in this image?",
+        files="photo.jpg"  # Automatically detected as image
+    )
+    print(result)
+    
+    # Use vector store for RAG (Retrieval-Augmented Generation)
+    result = response.run_sync(
+        "Search these documents",
+        files=["doc1.pdf", "doc2.pdf"],
+        use_vector_store=True  # Enable RAG with vector stores
+    )
+    print(result)
+```
+
+**How It Works:**
+
+- **Images** (jpg, png, gif, etc.) are automatically sent as base64-encoded images
+- **Documents** (pdf, txt, xlsx, etc.) are sent as base64-encoded file data by default
+- **Vector Stores** can optionally be used for documents when `use_vector_store=True`
+- **Batch Processing** is automatically used for multiple files (>3) for efficient encoding
+
+**Advanced File Processing:**
+
+```python
+from openai_sdk_helpers.response import process_files
+
+# Process files directly with the dedicated module
+vector_files, base64_files, images = process_files(
+    response,
+    files=["photo1.jpg", "photo2.jpg", "doc1.pdf", "doc2.pdf"],
+    use_vector_store=False,
+    batch_size=20,      # Files per batch
+    max_workers=10,     # Concurrent workers
+)
+```
+
+**Base64 Encoding Utilities:**
+
+```python
+from openai_sdk_helpers.utils import (
+    encode_image,
+    encode_file,
+    is_image_file,
+    create_image_data_url,
+    create_file_data_url,
+)
+
+# Check if a file is an image
+is_image_file("photo.jpg")  # True
+is_image_file("document.pdf")  # False
+
+# Encode an image to base64
+base64_image = encode_image("photo.jpg")
+
+# Create a data URL for an image
+image_url, detail = create_image_data_url("photo.jpg", detail="high")
+
+# Encode a file to base64
+base64_file = encode_file("document.pdf")
+
+# Create a data URL for a file
+file_data = create_file_data_url("document.pdf")
+```
+
 ### Custom Prompt Templates
 
 Create custom Jinja2 templates for specialized agent behaviors:

{openai_sdk_helpers-0.1.1 → openai_sdk_helpers-0.1.4}/README.md

@@ -271,6 +271,99 @@ response.close()
 
 ## Advanced Usage
 
+### Image and File Analysis
+
+The `response` module automatically detects file types and handles them appropriately:
+
+```python
+from openai_sdk_helpers.response import BaseResponse
+from openai_sdk_helpers import OpenAISettings
+
+settings = OpenAISettings.from_env()
+
+with BaseResponse(
+    name="analyzer",
+    instructions="You are a helpful assistant that can analyze files.",
+    tools=None,
+    output_structure=None,
+    tool_handlers={},
+    openai_settings=settings,
+) as response:
+    # Automatic type detection - single files parameter
+    # Images are sent as base64-encoded images
+    # Documents are sent as base64-encoded file data
+    result = response.run_sync(
+        "Analyze these files",
+        files=["photo.jpg", "document.pdf"]
+    )
+    print(result)
+    
+    # Single file - automatically detected
+    result = response.run_sync(
+        "What's in this image?",
+        files="photo.jpg"  # Automatically detected as image
+    )
+    print(result)
+    
+    # Use vector store for RAG (Retrieval-Augmented Generation)
+    result = response.run_sync(
+        "Search these documents",
+        files=["doc1.pdf", "doc2.pdf"],
+        use_vector_store=True  # Enable RAG with vector stores
+    )
+    print(result)
+```
+
+**How It Works:**
+
+- **Images** (jpg, png, gif, etc.) are automatically sent as base64-encoded images
+- **Documents** (pdf, txt, xlsx, etc.) are sent as base64-encoded file data by default
+- **Vector Stores** can optionally be used for documents when `use_vector_store=True`
+- **Batch Processing** is automatically used for multiple files (>3) for efficient encoding
+
+**Advanced File Processing:**
+
+```python
+from openai_sdk_helpers.response import process_files
+
+# Process files directly with the dedicated module
+vector_files, base64_files, images = process_files(
+    response,
+    files=["photo1.jpg", "photo2.jpg", "doc1.pdf", "doc2.pdf"],
+    use_vector_store=False,
+    batch_size=20,      # Files per batch
+    max_workers=10,     # Concurrent workers
+)
+```
+
+**Base64 Encoding Utilities:**
+
+```python
+from openai_sdk_helpers.utils import (
+    encode_image,
+    encode_file,
+    is_image_file,
+    create_image_data_url,
+    create_file_data_url,
+)
+
+# Check if a file is an image
+is_image_file("photo.jpg")  # True
+is_image_file("document.pdf")  # False
+
+# Encode an image to base64
+base64_image = encode_image("photo.jpg")
+
+# Create a data URL for an image
+image_url, detail = create_image_data_url("photo.jpg", detail="high")
+
+# Encode a file to base64
+base64_file = encode_file("document.pdf")
+
+# Create a data URL for a file
+file_data = create_file_data_url("document.pdf")
+```
+
 ### Custom Prompt Templates
 
 Create custom Jinja2 templates for specialized agent behaviors:

{openai_sdk_helpers-0.1.1 → openai_sdk_helpers-0.1.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "openai-sdk-helpers"
-version = "0.1.1"
+version = "0.1.4"
 requires-python = ">=3.10"
 readme = "README.md"
 description = "Composable helpers for OpenAI SDK agents, prompts, and storage"

{openai_sdk_helpers-0.1.1 → openai_sdk_helpers-0.1.4}/src/openai_sdk_helpers/__init__.py

@@ -51,6 +51,7 @@ from .structure import (
 )
 from .prompt import PromptRenderer
 from .config import OpenAISettings
+from .files_api import FilesAPIManager, FilePurpose
 from .vector_storage import VectorStorage, VectorStorageFileInfo, VectorStorageFileStats
 from .agent import (
     AgentBase,
@@ -138,6 +139,8 @@ __all__ = [
     "spec_field",
     "PromptRenderer",
     "OpenAISettings",
+    "FilesAPIManager",
+    "FilePurpose",
     "VectorStorage",
     "VectorStorageFileInfo",
     "VectorStorageFileStats",

openai_sdk_helpers-0.1.4/src/openai_sdk_helpers/files_api.py

@@ -0,0 +1,373 @@
+"""Comprehensive OpenAI Files API wrapper.
+
+This module provides a complete, professional implementation of the OpenAI Files API
+with automatic file tracking, lifecycle management, and cleanup capabilities.
+
+References
+----------
+OpenAI Files API: https://platform.openai.com/docs/api-reference/files
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any, BinaryIO, Literal, cast
+
+from openai import OpenAI, NOT_GIVEN
+from openai.types import FileDeleted, FileObject
+from openai.pagination import SyncCursorPage
+
+from .utils import log
+
+# Valid purposes for file uploads
+FilePurpose = Literal[
+    "assistants",
+    "batch",
+    "fine-tune",
+    "user_data",
+    "vision",
+]
+
+
+class FilesAPIManager:
+    """Comprehensive manager for OpenAI Files API operations.
+
+    Provides full access to the OpenAI Files API with automatic file tracking,
+    lifecycle management, and cleanup capabilities. Tracks all uploaded files
+    and ensures proper deletion on cleanup.
+
+    Parameters
+    ----------
+    client : OpenAI
+        OpenAI client instance for API calls.
+    auto_track : bool, default True
+        Automatically track uploaded files for cleanup.
+
+    Attributes
+    ----------
+    tracked_files : dict[str, FileObject]
+        Dictionary of tracked file IDs to FileObject instances.
+
+    Methods
+    -------
+    create(file, purpose)
+        Upload a file to OpenAI Files API.
+    retrieve(file_id)
+        Retrieve information about a specific file.
+    list(purpose, limit)
+        List files, optionally filtered by purpose.
+    delete(file_id)
+        Delete a specific file.
+    retrieve_content(file_id)
+        Download file content.
+    cleanup()
+        Delete all tracked files.
+
+    Examples
+    --------
+    >>> from openai import OpenAI
+    >>> from openai_sdk_helpers.files_api import FilesAPIManager
+    >>>
+    >>> client = OpenAI()
+    >>> files_manager = FilesAPIManager(client)
+    >>>
+    >>> # Upload a file
+    >>> with open("document.pdf", "rb") as f:
+    ...     file_obj = files_manager.create(f, purpose="user_data")
+    >>>
+    >>> # List all user data files
+    >>> user_files = files_manager.list(purpose="user_data")
+    >>>
+    >>> # Retrieve file content
+    >>> content = files_manager.retrieve_content(file_obj.id)
+    >>>
+    >>> # Clean up all tracked files
+    >>> files_manager.cleanup()
+    """
+
+    def __init__(self, client: OpenAI, auto_track: bool = True):
+        """Initialize the Files API manager.
+
+        Parameters
+        ----------
+        client : OpenAI
+            OpenAI client instance.
+        auto_track : bool, default True
+            Automatically track uploaded files for cleanup.
+        """
+        self._client = client
+        self._auto_track = auto_track
+        self.tracked_files: dict[str, FileObject] = {}
+
+    def create(
+        self,
+        file: BinaryIO | Path | str,
+        purpose: FilePurpose,
+        track: bool | None = None,
+        expires_after: int | None = None,
+    ) -> FileObject:
+        """Upload a file to the OpenAI Files API.
+
+        Parameters
+        ----------
+        file : BinaryIO, Path, or str
+            File-like object, path to file, or file path string.
+        purpose : FilePurpose
+            The intended purpose of the uploaded file.
+            Options: "assistants", "batch", "fine-tune", "user_data", "vision"
+        track : bool or None, default None
+            Override auto_track for this file. If None, uses instance setting.
+        expires_after : int or None, default None
+            Number of seconds after which the file expires and is deleted.
+            If None and purpose is "user_data", defaults to 86400 (24 hours).
+            For other purposes, files don't expire unless explicitly set.
+
+        Returns
+        -------
+        FileObject
+            Information about the uploaded file.
+
+        Raises
+        ------
+        FileNotFoundError
+            If file path doesn't exist.
+        ValueError
+            If purpose is invalid.
+
+        Examples
+        --------
+        >>> # Upload from file path (user_data expires in 24h by default)
+        >>> file_obj = manager.create("data.jsonl", purpose="user_data")
+        >>>
+        >>> # Upload with custom expiration (1 hour)
+        >>> file_obj = manager.create("temp.txt", purpose="user_data", expires_after=3600)
+        >>>
+        >>> # Upload from file handle
+        >>> with open("image.png", "rb") as f:
+        ...     file_obj = manager.create(f, purpose="vision")
+        >>>
+        >>> # Upload without tracking
+        >>> file_obj = manager.create("temp.txt", purpose="user_data", track=False)
+        """
+        should_track = track if track is not None else self._auto_track
+
+        # Default to 24 hours expiration for user_data files
+        if expires_after is None and purpose == "user_data":
+            expires_after = 86400  # 24 hours in seconds
+
+        # Handle different file input types
+        # Prepare expires_after in OpenAI API format if provided
+        expires_after_param = None
+        if expires_after is not None:
+            expires_after_param = cast(
+                Any, {"anchor": "created_at", "seconds": expires_after}
+            )
+
+        if isinstance(file, (Path, str)):
+            file_path = Path(file).resolve()
+            if not file_path.exists():
+                raise FileNotFoundError(f"File not found: {file}")
+
+            # Use only the basename as filename (remove path)
+            filename = file_path.name
+            with open(file_path, "rb") as f:
+                # Pass tuple (filename, file_data) to set custom filename
+                if expires_after_param is not None:
+                    file_obj = self._client.files.create(
+                        file=(filename, f),
+                        purpose=purpose,
+                        expires_after=expires_after_param,
+                    )
+                else:
+                    file_obj = self._client.files.create(
+                        file=(filename, f), purpose=purpose
+                    )
+        else:
+            # Assume it's a BinaryIO
+            if expires_after_param is not None:
+                file_obj = self._client.files.create(
+                    file=file,
+                    purpose=purpose,
+                    expires_after=expires_after_param,
+                )
+            else:
+                file_obj = self._client.files.create(file=file, purpose=purpose)
+
+        if should_track:
+            self.tracked_files[file_obj.id] = file_obj
+            expiry_msg = f" (expires in {expires_after}s)" if expires_after else ""
+            log(
+                f"Uploaded and tracking file {file_obj.id} ({file_obj.filename}) "
+                f"with purpose '{purpose}'{expiry_msg}"
+            )
+        else:
+            log(
+                f"Uploaded file {file_obj.id} ({file_obj.filename}) "
+                f"with purpose '{purpose}' (not tracked)"
+            )
+
+        return file_obj
+
+    def retrieve(self, file_id: str) -> FileObject:
+        """Retrieve information about a specific file.
+
+        Parameters
+        ----------
+        file_id : str
+            The ID of the file to retrieve.
+
+        Returns
+        -------
+        FileObject
+            Information about the file.
+
+        Examples
+        --------
+        >>> file_info = manager.retrieve("file-abc123")
+        >>> print(f"Filename: {file_info.filename}")
+        >>> print(f"Size: {file_info.bytes} bytes")
+        """
+        return self._client.files.retrieve(file_id)
+
+    def list(
+        self,
+        purpose: FilePurpose | None = None,
+        limit: int | None = None,
+    ) -> SyncCursorPage[FileObject]:
+        """List files, optionally filtered by purpose.
+
+        Parameters
+        ----------
+        purpose : FilePurpose or None, default None
+            Filter files by purpose. If None, returns all files.
+        limit : int or None, default None
+            Maximum number of files to return. If None, returns all.
+
+        Returns
+        -------
+        SyncCursorPage[FileObject]
+            Page of file objects matching the criteria.
+
+        Examples
+        --------
+        >>> # List all files
+        >>> all_files = manager.list()
+        >>>
+        >>> # List user data files
+        >>> user_files = manager.list(purpose="user_data")
+        >>>
+        >>> # List up to 10 files
+        >>> recent_files = manager.list(limit=10)
+        """
+        limit_param = NOT_GIVEN if limit is None else limit
+        if purpose is not None:
+            return self._client.files.list(
+                purpose=purpose, limit=cast(Any, limit_param)
+            )
+        return self._client.files.list(limit=cast(Any, limit_param))
+
+    def delete(self, file_id: str, untrack: bool = True) -> FileDeleted:
+        """Delete a specific file from OpenAI Files API.
+
+        Parameters
+        ----------
+        file_id : str
+            The ID of the file to delete.
+        untrack : bool, default True
+            Remove from tracked files after deletion.
+
+        Returns
+        -------
+        FileDeleted
+            Confirmation of file deletion.
+
+        Examples
+        --------
+        >>> result = manager.delete("file-abc123")
+        >>> print(f"Deleted: {result.deleted}")
+        """
+        result = self._client.files.delete(file_id)
+
+        if untrack and file_id in self.tracked_files:
+            del self.tracked_files[file_id]
+            log(f"Deleted and untracked file {file_id}")
+        else:
+            log(f"Deleted file {file_id}")
+
+        return result
+
+    def retrieve_content(self, file_id: str) -> bytes:
+        """Download and retrieve the content of a file.
+
+        Parameters
+        ----------
+        file_id : str
+            The ID of the file to download.
+
+        Returns
+        -------
+        bytes
+            The raw bytes of the file content.
+
+        Examples
+        --------
+        >>> content = manager.retrieve_content("file-abc123")
+        >>> with open("downloaded.pdf", "wb") as f:
+        ...     f.write(content)
+        """
+        return self._client.files.content(file_id).read()
+
+    def cleanup(self) -> dict[str, bool]:
+        """Delete all tracked files.
+
+        Returns
+        -------
+        dict[str, bool]
+            Dictionary mapping file IDs to deletion success status.
+
+        Examples
+        --------
+        >>> results = manager.cleanup()
+        >>> print(f"Deleted {sum(results.values())} files")
+        """
+        results = {}
+        file_ids = list(self.tracked_files.keys())
+
+        for file_id in file_ids:
+            try:
+                self.delete(file_id, untrack=True)
+                results[file_id] = True
+            except Exception as exc:
+                log(
+                    f"Error deleting tracked file {file_id}: {exc}",
+                    level=logging.WARNING,
+                )
+                results[file_id] = False
+
+        if results:
+            successful = sum(results.values())
+            log(f"Cleanup complete: {successful}/{len(results)} files deleted")
+        else:
+            log("No tracked files to clean up")
+
+        return results
+
+    def __enter__(self) -> FilesAPIManager:
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Context manager exit with automatic cleanup."""
+        self.cleanup()
+
+    def __len__(self) -> int:
+        """Return number of tracked files."""
+        return len(self.tracked_files)
+
+    def __repr__(self) -> str:
+        """Return string representation of the manager."""
+        return f"FilesAPIManager(tracked_files={len(self.tracked_files)})"
+
+
+__all__ = ["FilesAPIManager", "FilePurpose"]

{openai_sdk_helpers-0.1.1 → openai_sdk_helpers-0.1.4}/src/openai_sdk_helpers/response/__init__.py

@@ -1,9 +1,9 @@
 """Response handling for OpenAI API interactions.
 
 This module provides comprehensive support for managing OpenAI API responses,
-including message handling, tool execution, vector store attachments, and
-structured output parsing. It serves as the foundation for building
-sophisticated AI agents with persistent conversation state.
+including message handling, tool execution, vector store attachments, file
+processing, and structured output parsing. It serves as the foundation for
+building sophisticated AI agents with persistent conversation state.
 
 Classes
 -------
@@ -28,12 +28,15 @@ run_streamed
     Execute a response workflow and return the asynchronous result.
 attach_vector_store
     Attach vector stores to a response's file_search tool.
+process_files
+    Process file attachments with automatic type detection.
 """
 
 from __future__ import annotations
 
 from .base import BaseResponse
 from .config import ResponseConfiguration, ResponseRegistry, get_default_registry
+from .files import process_files
 from .messages import ResponseMessage, ResponseMessages
 from .runner import run_async, run_streamed, run_sync
 from .tool_call import ResponseToolCall, parse_tool_arguments
@@ -52,4 +55,5 @@ __all__ = [
     "ResponseToolCall",
     "parse_tool_arguments",
     "attach_vector_store",
+    "process_files",
 ]