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

openai_sdk_helpers/utils/encoding.py

@@ -0,0 +1,189 @@
+"""Utilities for encoding files and images to base64.
+
+This module provides helper functions for encoding images and files
+to base64 format for use with OpenAI API's input_image and input_file
+content types.
+"""
+
+import base64
+import mimetypes
+from pathlib import Path
+from typing import Literal
+
+
+def is_image_file(file_path: str | Path) -> bool:
+    """Check if a file is an image based on its MIME type.
+
+    Parameters
+    ----------
+    file_path : str or Path
+        Path to the file to check.
+
+    Returns
+    -------
+    bool
+        True if the file is an image, False otherwise.
+
+    Examples
+    --------
+    >>> is_image_file("photo.jpg")
+    True
+    >>> is_image_file("document.pdf")
+    False
+    """
+    mime_type = get_mime_type(file_path)
+    return mime_type.startswith("image/")
+
+
+def encode_image(image_path: str | Path) -> str:
+    """Encode an image file to base64.
+
+    Parameters
+    ----------
+    image_path : str or Path
+        Path to the image file to encode. Relative paths are converted
+        to absolute paths.
+
+    Returns
+    -------
+    str
+        Base64-encoded string representation of the image.
+
+    Raises
+    ------
+    FileNotFoundError
+        If the image file does not exist.
+    IOError
+        If the file cannot be read.
+
+    Examples
+    --------
+    >>> base64_image = encode_image("photo.jpg")
+    >>> image_url = f"data:image/jpeg;base64,{base64_image}"
+    """
+    path = Path(image_path).resolve()
+    if not path.exists():
+        raise FileNotFoundError(f"Image file not found: {image_path}")
+
+    with open(path, "rb") as image_file:
+        return base64.b64encode(image_file.read()).decode("utf-8")
+
+
+def encode_file(file_path: str | Path) -> str:
+    """Encode a file to base64.
+
+    Parameters
+    ----------
+    file_path : str or Path
+        Path to the file to encode. Relative paths are converted
+        to absolute paths.
+
+    Returns
+    -------
+    str
+        Base64-encoded string representation of the file.
+
+    Raises
+    ------
+    FileNotFoundError
+        If the file does not exist.
+    IOError
+        If the file cannot be read.
+
+    Examples
+    --------
+    >>> base64_file = encode_file("document.pdf")
+    >>> file_data = f"data:application/pdf;base64,{base64_file}"
+    """
+    path = Path(file_path).resolve()
+    if not path.exists():
+        raise FileNotFoundError(f"File not found: {file_path}")
+
+    with open(path, "rb") as f:
+        return base64.b64encode(f.read()).decode("utf-8")
+
+
+def get_mime_type(file_path: str | Path) -> str:
+    """Get the MIME type of a file.
+
+    Parameters
+    ----------
+    file_path : str or Path
+        Path to the file.
+
+    Returns
+    -------
+    str
+        MIME type of the file, or "application/octet-stream" if unknown.
+
+    Examples
+    --------
+    >>> get_mime_type("photo.jpg")
+    'image/jpeg'
+    >>> get_mime_type("document.pdf")
+    'application/pdf'
+    """
+    path = Path(file_path)
+    mime_type, _ = mimetypes.guess_type(str(path))
+    return mime_type or "application/octet-stream"
+
+
+def create_image_data_url(
+    image_path: str | Path, detail: Literal["low", "high", "auto"] = "auto"
+) -> tuple[str, Literal["low", "high", "auto"]]:
+    """Create a data URL for an image with MIME type detection.
+
+    Parameters
+    ----------
+    image_path : str or Path
+        Path to the image file.
+    detail : {"low", "high", "auto"}, default "auto"
+        Detail level for image processing.
+
+    Returns
+    -------
+    tuple[str, str]
+        A tuple containing the data URL and detail level.
+
+    Raises
+    ------
+    FileNotFoundError
+        If the image file does not exist.
+
+    Examples
+    --------
+    >>> image_url, detail = create_image_data_url("photo.jpg", "high")
+    >>> # Use with ResponseInputImageContentParam
+    """
+    mime_type = get_mime_type(image_path)
+    base64_image = encode_image(image_path)
+    data_url = f"data:{mime_type};base64,{base64_image}"
+    return data_url, detail
+
+
+def create_file_data_url(file_path: str | Path) -> str:
+    """Create a data URL for a file with MIME type detection.
+
+    Parameters
+    ----------
+    file_path : str or Path
+        Path to the file.
+
+    Returns
+    -------
+    str
+        Data URL with MIME type and base64-encoded content.
+
+    Raises
+    ------
+    FileNotFoundError
+        If the file does not exist.
+
+    Examples
+    --------
+    >>> file_data = create_file_data_url("document.pdf")
+    >>> # Use with ResponseInputFileContentParam
+    """
+    mime_type = get_mime_type(file_path)
+    base64_file = encode_file(file_path)
+    return f"data:{mime_type};base64,{base64_file}"

openai_sdk_helpers/utils/json_utils.py

@@ -0,0 +1,98 @@
+"""JSON serialization helpers for helper types."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, is_dataclass
+from datetime import datetime
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+from .path_utils import check_filepath
+
+
+def _to_jsonable(value: Any) -> Any:
+    """Convert common helper types to JSON-serializable forms."""
+    from openai_sdk_helpers.structure.base import BaseStructure
+
+    if value is None:
+        return None
+    if isinstance(value, Enum):
+        return value.value
+    if isinstance(value, Path):
+        return str(value)
+    if isinstance(value, datetime):
+        return value.isoformat()
+    if is_dataclass(value) and not isinstance(value, type):
+        return {k: _to_jsonable(v) for k, v in asdict(value).items()}
+    if hasattr(value, "model_dump"):
+        model_dump = getattr(value, "model_dump")
+        return model_dump()
+    if isinstance(value, dict):
+        return {str(k): _to_jsonable(v) for k, v in value.items()}
+    if isinstance(value, (list, tuple, set)):
+        return [_to_jsonable(v) for v in value]
+    if isinstance(value, BaseStructure):
+        return value.model_dump()
+    return value
+
+
+def coerce_jsonable(value: Any) -> Any:
+    """Convert value into a JSON-serializable representation."""
+    from openai_sdk_helpers.response.base import BaseResponse
+
+    if value is None:
+        return None
+    if isinstance(value, BaseResponse):
+        return coerce_jsonable(value.messages.to_json())
+    if is_dataclass(value) and not isinstance(value, type):
+        return {key: coerce_jsonable(item) for key, item in asdict(value).items()}
+    coerced = _to_jsonable(value)
+    try:
+        json.dumps(coerced)
+        return coerced
+    except TypeError:
+        return str(coerced)
+
+
+class customJSONEncoder(json.JSONEncoder):
+    """JSON encoder for common helper types like enums and paths."""
+
+    def default(self, o: Any) -> Any:  # noqa: D401
+        """Return JSON-serializable representation of ``o``."""
+        return _to_jsonable(o)
+
+
+class JSONSerializable:
+    """Mixin for classes that can be serialized to JSON."""
+
+    def to_json(self) -> dict[str, Any]:
+        """Return a JSON-compatible dict representation."""
+        if is_dataclass(self) and not isinstance(self, type):
+            return {k: _to_jsonable(v) for k, v in asdict(self).items()}
+        if hasattr(self, "model_dump"):
+            model_dump = getattr(self, "model_dump")
+            return _to_jsonable(model_dump())
+        return _to_jsonable(self.__dict__)
+
+    def to_json_file(self, filepath: str | Path) -> str:
+        """Write serialized JSON data to a file path."""
+        target = Path(filepath)
+        check_filepath(fullfilepath=str(target))
+        with open(target, "w", encoding="utf-8") as handle:
+            json.dump(
+                self.to_json(),
+                handle,
+                indent=2,
+                ensure_ascii=False,
+                cls=customJSONEncoder,
+            )
+        return str(target)
+
+
+__all__ = [
+    "coerce_jsonable",
+    "JSONSerializable",
+    "customJSONEncoder",
+]