openai-sdk-helpers 0.0.8__py3-none-any.whl → 0.0.9__py3-none-any.whl

openai_sdk_helpers/environment.py

@@ -1,27 +1,54 @@
-"""Environment helpers for openai-sdk-helpers."""
+"""Environment helpers for openai-sdk-helpers.
+
+This module provides utility functions and constants for managing paths
+and environment-specific configuration.
+
+Constants
+---------
+DATETIME_FMT : str
+    Standard datetime format string for file naming ("%Y%m%d_%H%M%S").
+DEFAULT_MODEL : str
+    Default OpenAI model identifier ("gpt-4o-mini").
+
+Functions
+---------
+get_data_path(name)
+    Return a writable data directory for the given module name.
+"""
 
 from __future__ import annotations
 
 from pathlib import Path
 
 DATETIME_FMT = "%Y%m%d_%H%M%S"
+DEFAULT_MODEL = "gpt-4o-mini"
 
 
-def get_data_path(module_name: str) -> Path:
+def get_data_path(name: str) -> Path:
     """Return a writable data directory for the given module name.
 
+    Creates a module-specific directory under ~/.openai-sdk-helpers/ for
+    storing data, logs, or other persistent files.
+
     Parameters
     ----------
-    module_name : str
+    name : str
         Name of the module requesting a data directory.
 
     Returns
     -------
     Path
-        Directory path under ``~/.openai-sdk-helpers`` specific to ``module_name``. The
-        directory is created if it does not already exist.
+        Directory path under ~/.openai-sdk-helpers specific to name.
+        The directory is created if it does not exist.
+
+    Examples
+    --------
+    >>> from openai_sdk_helpers.environment import get_data_path
+    >>> path = get_data_path("my_module")
+    >>> path.exists()
+    True
     """
     base = Path.home() / ".openai-sdk-helpers"
-    path = base / module_name
+    path = base / name
     path.mkdir(parents=True, exist_ok=True)
     return path

openai_sdk_helpers/errors.py

@@ -0,0 +1,133 @@
+"""Custom exception hierarchy for openai-sdk-helpers.
+
+Provides specific exception types for different error scenarios,
+improving error handling and debugging capabilities.
+"""
+
+import logging
+from collections.abc import Mapping
+
+from openai_sdk_helpers.utils.core import log
+
+
+class OpenAISDKError(Exception):
+    """Base exception for openai-sdk-helpers library.
+
+    All custom exceptions in this library inherit from this class,
+    allowing callers to catch all SDK-specific errors.
+
+    Parameters
+    ----------
+    message : str
+        Human-readable error message
+    context : Mapping[str, object] | None
+        Additional context information for debugging. Default is None.
+
+    Examples
+    --------
+    >>> try:
+    ...     raise OpenAISDKError("Something went wrong", context={"step": "init"})
+    ... except OpenAISDKError as exc:
+    ...     print(f"SDK Error: {exc}")
+    ...     print(f"Context: {exc.context}")
+    """
+
+    def __init__(
+        self,
+        message: str,
+        context: Mapping[str, object] | None = None,
+    ) -> None:
+        """Initialize the exception with message and optional context."""
+        super().__init__(message)
+        self.context = dict(context) if context is not None else {}
+        self._log_context()
+
+    def _log_context(self) -> None:
+        """Log error with context for debugging."""
+        context_str = f"\nContext: {self.context}" if self.context else ""
+        log(
+            f"{self.__class__.__name__}: {str(self)}{context_str}",
+            level=logging.ERROR,
+        )
+
+
+class ConfigurationError(OpenAISDKError):
+    """Configuration validation or initialization failed.
+
+    Raised when configuration is missing, invalid, or inconsistent.
+    """
+
+    pass
+
+
+class PromptNotFoundError(OpenAISDKError):
+    """Prompt template file not found or cannot be read.
+
+    Raised when a required prompt template file is missing or inaccessible.
+    """
+
+    pass
+
+
+class AgentExecutionError(OpenAISDKError):
+    """Agent execution failed.
+
+    Raised when an agent encounters an error during execution.
+    May wrap underlying exceptions with additional context.
+    """
+
+    pass
+
+
+class VectorStorageError(OpenAISDKError):
+    """Vector storage operation failed.
+
+    Raised when vector store operations (upload, download, cleanup) fail.
+    """
+
+    pass
+
+
+class ToolExecutionError(OpenAISDKError):
+    """Tool execution failed.
+
+    Raised when a tool handler encounters an error.
+    """
+
+    pass
+
+
+class ResponseGenerationError(OpenAISDKError):
+    """Response generation failed.
+
+    Raised when generating responses from structured output fails.
+    """
+
+    pass
+
+
+class InputValidationError(OpenAISDKError):
+    """Input validation failed.
+
+    Raised when provided input doesn't meet required constraints.
+    """
+
+    pass
+
+
+class AsyncExecutionError(OpenAISDKError):
+    """Asynchronous operation failed.
+
+    Raised when async/await operations fail or timeout.
+    """
+
+    pass
+
+
+class ResourceCleanupError(OpenAISDKError):
+    """Resource cleanup failed.
+
+    Raised when cleanup of resources fails, but may not be fatal.
+    """
+
+    pass

openai_sdk_helpers/logging_config.py

@@ -0,0 +1,105 @@
+"""Centralized logging configuration for openai-sdk-helpers.
+
+Provides a centralized factory for creating and configuring loggers
+with consistent formatting and handler management.
+"""
+
+import logging
+import threading
+from typing import Any
+
+
+class LoggerFactory:
+    """Centralized logger creation and configuration.
+
+    Manages logger initialization and configuration to ensure consistent
+    logging behavior across the entire SDK. Thread-safe.
+
+    Examples
+    --------
+    Configure logging once at application startup:
+
+    >>> from openai_sdk_helpers.logging_config import LoggerFactory
+    >>> import logging
+    >>> LoggerFactory.configure(
+    ...     level=logging.DEBUG,
+    ...     handlers=[logging.StreamHandler()],
+    ... )
+
+    Get a logger instance in your module:
+
+    >>> logger = LoggerFactory.get_logger("openai_sdk_helpers.agent")
+    >>> logger.debug("Debug message")
+    """
+
+    _initialized = False
+    _log_level = logging.INFO
+    _handlers: list[logging.Handler] = []
+    _lock = threading.Lock()
+
+    @classmethod
+    def configure(
+        cls,
+        level: int = logging.INFO,
+        handlers: list[logging.Handler] | None = None,
+    ) -> None:
+        """Configure logging globally.
+
+        Parameters
+        ----------
+        level : int
+            Logging level (e.g., logging.DEBUG, logging.INFO).
+            Default is logging.INFO.
+        handlers : list[logging.Handler] | None
+            List of logging handlers. If None, a default
+            StreamHandler is created. Default is None.
+
+        Notes
+        -----
+        This method is thread-safe and can be called multiple times.
+        """
+        with cls._lock:
+            cls._log_level = level
+            if handlers:
+                cls._handlers = handlers
+            else:
+                handler = logging.StreamHandler()
+                handler.setLevel(level)
+                formatter = logging.Formatter(
+                    "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+                )
+                handler.setFormatter(formatter)
+                cls._handlers = [handler]
+            cls._initialized = True
+
+    @classmethod
+    def get_logger(cls, name: str) -> logging.Logger:
+        """Get configured logger instance.
+
+        Parameters
+        ----------
+        name : str
+            Logger name, typically __name__ of calling module.
+
+        Returns
+        -------
+        logging.Logger
+            Configured logger instance.
+        """
+        logger = logging.getLogger(name)
+
+        # Skip configuration if already configured
+        if logger.handlers:
+            return logger
+
+        with cls._lock:
+            if not cls._initialized:
+                cls.configure()
+
+            for handler in cls._handlers:
+                logger.addHandler(handler)
+
+            logger.setLevel(cls._log_level)
+            logger.propagate = False
+
+        return logger

openai_sdk_helpers/prompt/__init__.py

@@ -1,77 +1,16 @@
-"""Core prompt rendering utilities."""
+"""Prompt rendering utilities for template-based text generation.
 
-from __future__ import annotations
-
-import warnings
-from pathlib import Path
-from typing import Any, Mapping, Optional
-
-from dotenv import load_dotenv
-from jinja2 import Environment, FileSystemLoader, Template
-
-load_dotenv()
-warnings.filterwarnings("ignore")
-
-
-class PromptRenderer:
-    """Render prompts using Jinja2 templates.
-
-    The renderer loads templates from a base directory (defaulting to the
-    ``prompt`` package directory) and exposes a rendering helper for
-    injecting context values.
+This module provides Jinja2-based template rendering functionality for
+creating dynamic prompts with variable substitution and template inheritance.
 
-    Methods
-    -------
-    render(template_path, context)
-        Render the template at ``template_path`` with the supplied context.
-    """
+Classes
+-------
+PromptRenderer
+    Jinja2-based template renderer for dynamic prompt generation.
+"""
 
-    def __init__(self, base_dir: Optional[Path] = None) -> None:
-        """Initialize the renderer with a Jinja2 environment.
-
-        Parameters
-        ----------
-        base_dir : Path or None, default=None
-            Base directory containing Jinja2 templates. Defaults to the
-            ``prompt`` directory adjacent to this file when ``None``.
-
-        Returns
-        -------
-        None
-        """
-        if base_dir is None:
-            # Defaults to the directory containing this file, which also
-            # contains the builtin prompt templates.
-            self.base_dir = Path(__file__).resolve().parent
-        else:
-            self.base_dir = base_dir
-
-        self._env = Environment(
-            loader=FileSystemLoader(str(self.base_dir)),
-            autoescape=False,  # Prompts are plain text
-        )
-
-    def render(
-        self, template_path: str, context: Optional[Mapping[str, Any]] = None
-    ) -> str:
-        """Render a Jinja2 template with the given context.
-
-        Parameters
-        ----------
-        template_path : str
-            Path to the template file, relative to ``base_dir``.
-        context : Mapping[str, Any] or None, default=None
-            Context variables passed to the template.
-
-        Returns
-        -------
-        str
-            Rendered prompt as a string.
-        """
-        template_path_ = Path(self.base_dir, template_path)
-        template_path_text = template_path_.read_text()
-        template = Template(template_path_text)
-        return template.render(context or {})
+from __future__ import annotations
 
+from .base import PromptRenderer
 
 __all__ = ["PromptRenderer"]

openai_sdk_helpers/prompt/base.py

@@ -0,0 +1,172 @@
+"""Core prompt rendering implementation.
+
+This module provides the PromptRenderer class for loading and rendering
+Jinja2 templates with context variables. Templates can be loaded from a
+specified directory or by absolute path.
+"""
+
+from __future__ import annotations
+
+import warnings
+from pathlib import Path
+from typing import Any
+
+from dotenv import load_dotenv
+from jinja2 import Environment, FileSystemLoader, Template
+
+load_dotenv()
+warnings.filterwarnings("ignore")
+
+
+class PromptRenderer:
+    """Jinja2-based template renderer for dynamic prompt generation.
+
+    Loads and renders Jinja2 templates from a base directory or by absolute
+    path. The renderer supports variable substitution, template inheritance,
+    and all standard Jinja2 features for creating dynamic prompts.
+
+    Templates are loaded from a base directory (defaulting to the built-in
+    prompt package directory) or can be specified with absolute paths.
+    Autoescape is disabled by default since prompts are plain text.
+
+    Attributes
+    ----------
+    base_dir : Path
+        Base directory for template loading.
+
+    Methods
+    -------
+    render(template_path, context=None)
+        Render a Jinja2 template with the given context variables.
+
+    Examples
+    --------
+    Basic template rendering with custom base directory:
+
+    >>> from pathlib import Path
+    >>> from openai_sdk_helpers.prompt import PromptRenderer
+    >>> renderer = PromptRenderer(base_dir=Path("./templates"))
+    >>> prompt = renderer.render(
+    ...     "greeting.jinja",
+    ...     context={"name": "Alice", "language": "English"}
+    ... )
+    >>> print(prompt)
+
+    Using absolute path (no base_dir required):
+
+    >>> renderer = PromptRenderer()
+    >>> prompt = renderer.render(
+    ...     "/absolute/path/to/template.jinja",
+    ...     context={"name": "Bob"}
+    ... )
+
+    Using built-in templates:
+
+    >>> renderer = PromptRenderer()  # Uses built-in templates
+    >>> prompt = renderer.render("summarizer.jinja", context={})
+    """
+
+    def __init__(self, base_dir: Path | None = None) -> None:
+        """Initialize the renderer with a Jinja2 environment.
+
+        Sets up the Jinja2 environment with a FileSystemLoader pointing to
+        the specified base directory. If no base directory is provided,
+        defaults to the built-in prompt package directory containing
+        standard templates.
+
+        Parameters
+        ----------
+        base_dir : Path or None, default None
+            Base directory containing Jinja2 templates. If None, uses the
+            prompt package directory containing built-in templates.
+
+        Examples
+        --------
+        >>> from pathlib import Path
+        >>> renderer = PromptRenderer(base_dir=Path("./my_templates"))
+        >>> renderer.base_dir
+        PosixPath('.../my_templates')
+
+        >>> default_renderer = PromptRenderer()
+        >>> default_renderer.base_dir.name
+        'prompt'
+        """
+        if base_dir is None:
+            # Defaults to the directory containing this file, which also
+            # contains the builtin prompt templates.
+            self.base_dir = Path(__file__).resolve().parent
+        else:
+            self.base_dir = base_dir
+
+        self._env = Environment(
+            loader=FileSystemLoader(str(self.base_dir)),
+            autoescape=False,  # Prompts are plain text
+        )
+
+    def render(self, template_path: str, context: dict[str, Any] | None = None) -> str:
+        """Render a Jinja2 template with the given context variables.
+
+        Loads the template from either an absolute path or a path relative
+        to the base directory. The template is rendered with the provided
+        context dictionary using Jinja2's template engine.
+
+        For security, relative paths are validated to prevent path traversal
+        attacks. Absolute paths are allowed but should be used with caution
+        as they bypass base directory restrictions.
+
+        Parameters
+        ----------
+        template_path : str
+            Path to the template file. Can be an absolute path or relative
+            to base_dir.
+        context : dict[str, Any] or None, default None
+            Context variables to pass to the template. If None, an empty
+            dictionary is used.
+
+        Returns
+        -------
+        str
+            Fully rendered template as a string.
+
+        Raises
+        ------
+        FileNotFoundError
+            If the template file does not exist at the specified path.
+        InputValidationError
+            If the path contains suspicious patterns or attempts to escape
+            the base directory.
+
+        Examples
+        --------
+        >>> renderer = PromptRenderer()
+        >>> context = {"name": "Alice", "age": 30}
+        >>> result = renderer.render("greeting.jinja", context)
+        >>> "Alice" in result
+        True
+
+        With absolute path:
+
+        >>> result = renderer.render(
+        ...     "/path/to/template.jinja",
+        ...     context={"key": "value"}
+        ... )
+        """
+        from openai_sdk_helpers.validation import validate_safe_path
+
+        path = Path(template_path)
+        if path.is_absolute():
+            # Absolute paths allowed but not validated against base_dir
+            template_path_ = path
+        else:
+            # Relative paths validated to prevent directory traversal
+            template_path_ = validate_safe_path(
+                self.base_dir / template_path,
+                base_dir=self.base_dir,
+                field_name="template_path",
+            )
+        template_path_text = template_path_.read_text()
+        template = Template(template_path_text)
+        return template.render(context or {})
+
+
+__all__ = ["PromptRenderer"]

openai_sdk_helpers/response/__init__.py

@@ -1,15 +1,47 @@
-"""Shared response helpers for OpenAI interactions."""
+"""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.
+
+Classes
+-------
+BaseResponse
+    Core response manager for OpenAI interactions with structured outputs.
+ResponseConfiguration
+    Immutable configuration for defining request/response structures.
+ResponseMessage
+    Single message exchanged with the OpenAI client.
+ResponseMessages
+    Collection of messages in a response conversation.
+ResponseToolCall
+    Container for tool call data and formatting.
+
+Functions
+---------
+run_sync
+    Execute a response workflow synchronously with resource cleanup.
+run_async
+    Execute a response workflow asynchronously with resource cleanup.
+run_streamed
+    Execute a response workflow and return the asynchronous result.
+attach_vector_store
+    Attach vector stores to a response's file_search tool.
+"""
 
 from __future__ import annotations
 
 from .base import BaseResponse
+from .config import ResponseConfiguration
 from .messages import ResponseMessage, ResponseMessages
-from .runner import run_sync, run_async, run_streamed
-from .vector_store import attach_vector_store
+from .runner import run_async, run_streamed, run_sync
 from .tool_call import ResponseToolCall
+from .vector_store import attach_vector_store
 
 __all__ = [
     "BaseResponse",
+    "ResponseConfiguration",
     "ResponseMessage",
     "ResponseMessages",
     "run_sync",