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

openai_sdk_helpers/enums/base.py

@@ -1,29 +1,88 @@
-"""Base enum helpers."""
+"""Base enum classes with metadata support.
+
+This module defines specialized enum base classes that extend the standard
+library's Enum class with additional metadata and serialization capabilities.
+"""
 
 from __future__ import annotations
 
 from enum import Enum
+from typing import Any
 
 
 class CrosswalkJSONEnum(str, Enum):
-    """Enum base class with crosswalk metadata hooks.
+    """String-based enum with crosswalk metadata support.
+
+    Extends both str and Enum to provide string-compatible enum values
+    with optional metadata mappings. Subclasses must implement the
+    CROSSWALK class method to provide structured metadata for each
+    enum member.
+
+    This design allows enums to carry additional context beyond their
+    values, useful for configuration, validation, or documentation purposes.
 
     Methods
     -------
     CROSSWALK()
-        Return metadata describing enum values keyed by name.
+        Return metadata describing enum values keyed by member name.
+
+    Examples
+    --------
+    >>> class Status(CrosswalkJSONEnum):
+    ...     ACTIVE = "active"
+    ...     INACTIVE = "inactive"
+    ...
+    ...     @classmethod
+    ...     def CROSSWALK(cls):
+    ...         return {
+    ...             "ACTIVE": {"description": "Currently active"},
+    ...             "INACTIVE": {"description": "Not active"}
+    ...         }
+    >>> Status.ACTIVE.value
+    'active'
+    >>> Status.CROSSWALK()["ACTIVE"]["description"]
+    'Currently active'
     """
 
     @classmethod
-    def CROSSWALK(cls) -> dict[str, dict[str, object]]:
-        """Return metadata describing enum values keyed by name.
+    def CROSSWALK(cls) -> dict[str, dict[str, Any]]:
+        """Return metadata describing enum values keyed by member name.
+
+        Subclasses must override this method to provide structured
+        metadata for each enum member. The outer dictionary keys
+        correspond to enum member names, and values are dictionaries
+        containing arbitrary metadata.
 
         Returns
         -------
-        dict[str, dict[str, object]]
-            Mapping of enum member names to structured metadata details.
+        dict[str, dict[str, Any]]
+            Mapping of enum member names to their metadata dictionaries.
+            Each metadata dictionary can contain any relevant key-value
+            pairs describing that enum member.
+
+        Raises
+        ------
+        NotImplementedError
+            If called on a subclass that has not implemented this method.
+
+        Examples
+        --------
+        >>> class Priority(CrosswalkJSONEnum):
+        ...     HIGH = "high"
+        ...     LOW = "low"
+        ...
+        ...     @classmethod
+        ...     def CROSSWALK(cls):
+        ...         return {
+        ...             "HIGH": {"value": "high", "weight": 10},
+        ...             "LOW": {"value": "low", "weight": 1}
+        ...         }
+        >>> Priority.CROSSWALK()["HIGH"]["weight"]
+        10
         """
-        raise NotImplementedError("CROSSWALK must be implemented by subclasses.")
+        raise NotImplementedError(
+            f"{cls.__name__}.CROSSWALK() must be implemented by subclasses"
+        )
 
 
 __all__ = ["CrosswalkJSONEnum"]

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"]