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

openai_sdk_helpers/deprecation.py

@@ -0,0 +1,167 @@
+"""Deprecation utilities for managing deprecated features.
+
+This module provides infrastructure for marking and managing deprecated
+functions, classes, and features with consistent warning messages.
+
+Functions
+---------
+deprecated
+    Decorator to mark functions or classes as deprecated.
+warn_deprecated
+    Emit a deprecation warning with optional custom message.
+
+Classes
+-------
+DeprecationHelper
+    Utility class for managing deprecation warnings and versions.
+"""
+
+from __future__ import annotations
+
+import functools
+import warnings
+from typing import Any, Callable, TypeVar
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+class DeprecationHelper:
+    """Utility class for managing deprecation warnings.
+
+    Provides consistent formatting and control of deprecation warnings
+    across the package.
+
+    Methods
+    -------
+    warn
+        Emit a deprecation warning with standard formatting.
+    """
+
+    @staticmethod
+    def warn(
+        feature_name: str,
+        removal_version: str,
+        alternative: str | None = None,
+        extra_message: str | None = None,
+    ) -> None:
+        """Emit a deprecation warning for a feature.
+
+        Parameters
+        ----------
+        feature_name : str
+            Name of the deprecated feature (e.g., "MyClass.old_method").
+        removal_version : str
+            Version in which the feature will be removed.
+        alternative : str, optional
+            Recommended alternative to use instead.
+        extra_message : str, optional
+            Additional context or migration instructions.
+
+        Raises
+        ------
+        DeprecationWarning
+            Always issues a DeprecationWarning to stderr.
+        """
+        msg = f"{feature_name} is deprecated and will be removed in version {removal_version}."
+        if alternative:
+            msg += f" Use {alternative} instead."
+        if extra_message:
+            msg += f" {extra_message}"
+
+        warnings.warn(msg, DeprecationWarning, stacklevel=3)
+
+
+def deprecated(
+    removal_version: str,
+    alternative: str | None = None,
+    extra_message: str | None = None,
+) -> Callable[[F], F]:
+    """Mark a function or class as deprecated.
+
+    Parameters
+    ----------
+    removal_version : str
+        Version in which the decorated feature will be removed.
+    alternative : str, optional
+        Recommended alternative to use instead.
+    extra_message : str, optional
+        Additional context or migration instructions.
+
+    Returns
+    -------
+    Callable
+        Decorator function that wraps the target function or class.
+
+    Examples
+    --------
+    >>> @deprecated("1.0.0", "new_function")
+    ... def old_function():
+    ...     pass
+
+    >>> class OldClass:
+    ...     @deprecated("1.0.0", "NewClass")
+    ...     def old_method(self):
+    ...         pass
+    """
+
+    def decorator(func_or_class: F) -> F:
+        feature_name = f"{func_or_class.__module__}.{func_or_class.__qualname__}"
+
+        if isinstance(func_or_class, type):
+            # Handle class deprecation
+            original_init = func_or_class.__init__
+
+            @functools.wraps(original_init)
+            def new_init(self: Any, *args: Any, **kwargs: Any) -> None:
+                DeprecationHelper.warn(
+                    feature_name,
+                    removal_version,
+                    alternative,
+                    extra_message,
+                )
+                original_init(self, *args, **kwargs)
+
+            func_or_class.__init__ = new_init
+        else:
+            # Handle function deprecation
+            @functools.wraps(func_or_class)
+            def wrapper(*args: Any, **kwargs: Any) -> Any:
+                DeprecationHelper.warn(
+                    feature_name,
+                    removal_version,
+                    alternative,
+                    extra_message,
+                )
+                return func_or_class(*args, **kwargs)
+
+            return wrapper  # type: ignore
+
+        return func_or_class  # type: ignore[return-value]
+
+    return decorator
+
+
+def warn_deprecated(
+    feature_name: str,
+    removal_version: str,
+    alternative: str | None = None,
+    extra_message: str | None = None,
+) -> None:
+    """Issue a deprecation warning.
+
+    Parameters
+    ----------
+    feature_name : str
+        Name of the deprecated feature.
+    removal_version : str
+        Version in which the feature will be removed.
+    alternative : str, optional
+        Recommended alternative to use instead.
+    extra_message : str, optional
+        Additional context or migration instructions.
+
+    Examples
+    --------
+    >>> warn_deprecated("old_config_key", "1.0.0", "new_config_key")
+    """
+    DeprecationHelper.warn(feature_name, removal_version, alternative, extra_message)

openai_sdk_helpers/environment.py

@@ -20,6 +20,8 @@ from __future__ import annotations
 
 from pathlib import Path
 
+from openai_sdk_helpers.utils import ensure_directory
+
 DATETIME_FMT = "%Y%m%d_%H%M%S"
 DEFAULT_MODEL = "gpt-4o-mini"
 
@@ -50,5 +52,4 @@ def get_data_path(name: str) -> Path:
     """
     base = Path.home() / ".openai-sdk-helpers"
     path = base / name
-    path.mkdir(parents=True, exist_ok=True)
-    return path
+    return ensure_directory(path)

openai_sdk_helpers/errors.py

@@ -4,11 +4,8 @@ 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.
@@ -40,15 +37,6 @@ class OpenAISDKError(Exception):
         """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):

openai_sdk_helpers/logging_config.py

@@ -1,105 +1,34 @@
-"""Centralized logging configuration for openai-sdk-helpers.
-
-Provides a centralized factory for creating and configuring loggers
-with consistent formatting and handler management.
-"""
+"""Centralized logging configuration for openai-sdk-helpers."""
 
 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.
+def log(
+    message: str,
+    level: int = logging.INFO,
+    *,
+    logger_name: str = "openai_sdk_helpers",
+) -> None:
+    """Log a message using Python's standard logging.
+
+    Parameters
+    ----------
+    message : str
+        The message to log.
+    level : int
+        Logging level (e.g., logging.DEBUG, logging.INFO).
+        Default is logging.INFO.
+    logger_name : str
+        Name of the logger. Default is "openai_sdk_helpers".
 
     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")
+    >>> from openai_sdk_helpers.logging_config import log
+    >>> log("Operation completed")
+    >>> log("Debug info", level=logging.DEBUG)
     """
+    logger = logging.getLogger(logger_name)
+    logger.log(level, 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
+__all__ = ["log"]

openai_sdk_helpers/prompt/base.py

@@ -2,12 +2,14 @@
 
 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.
+specified directory or by absolute path. Includes template caching for
+improved performance.
 """
 
 from __future__ import annotations
 
 import warnings
+from functools import lru_cache
 from pathlib import Path
 from typing import Any
 
@@ -23,7 +25,8 @@ class PromptRenderer:
 
     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.
+    and all standard Jinja2 features for creating dynamic prompts. Templates
+    are cached using LRU cache for improved performance on repeated renders.
 
     Templates are loaded from a base directory (defaulting to the built-in
     prompt package directory) or can be specified with absolute paths.
@@ -38,6 +41,8 @@ class PromptRenderer:
     -------
     render(template_path, context=None)
         Render a Jinja2 template with the given context variables.
+    clear_cache()
+        Clear the template compilation cache.
 
     Examples
     --------
@@ -103,12 +108,30 @@ class PromptRenderer:
             autoescape=False,  # Prompts are plain text
         )
 
+    @lru_cache(maxsize=128)
+    def _compile_template(self, template_path_str: str) -> Template:
+        """Compile a template by path with LRU caching.
+
+        Parameters
+        ----------
+        template_path_str : str
+            Absolute path to the template file.
+
+        Returns
+        -------
+        Template
+            Compiled Jinja2 template ready for rendering.
+        """
+        template_text = Path(template_path_str).read_text()
+        return Template(template_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.
+        context dictionary using Jinja2's template engine. Templates are
+        cached for improved performance on repeated renders.
 
         For security, relative paths are validated to prevent path traversal
         attacks. Absolute paths are allowed but should be used with caution
@@ -135,6 +158,8 @@ class PromptRenderer:
         InputValidationError
             If the path contains suspicious patterns or attempts to escape
             the base directory.
+        TemplateNotFound
+            If the template cannot be loaded by Jinja2.
 
         Examples
         --------
@@ -151,7 +176,7 @@ class PromptRenderer:
         ...     context={"key": "value"}
         ... )
         """
-        from openai_sdk_helpers.validation import validate_safe_path
+        from openai_sdk_helpers.utils.validation import validate_safe_path
 
         path = Path(template_path)
         if path.is_absolute():
@@ -164,9 +189,34 @@ class PromptRenderer:
                 base_dir=self.base_dir,
                 field_name="template_path",
             )
-        template_path_text = template_path_.read_text()
-        template = Template(template_path_text)
+
+        # Check if template exists and provide clear error message
+        if not template_path_.exists():
+            raise FileNotFoundError(
+                f"Template not found: {template_path_}. "
+                f"Ensure the template exists in {self.base_dir} or provide an absolute path."
+            )
+
+        # Cache-compile template by path (not by content)
+        template = self._compile_template(str(template_path_))
         return template.render(context or {})
 
+    def clear_cache(self) -> None:
+        """Clear the template compilation cache.
+
+        Useful when templates are modified during runtime and need to be
+        reloaded. Call this method to force re-compilation of all templates
+        on next render.
+
+        Examples
+        --------
+        >>> renderer = PromptRenderer()
+        >>> renderer.render("template.jinja", {})  # Compiles and caches
+        >>> # ... modify template.jinja ...
+        >>> renderer.clear_cache()  # Clear cache
+        >>> renderer.render("template.jinja", {})  # Re-compiles
+        """
+        self._compile_template.cache_clear()
+
 
 __all__ = ["PromptRenderer"]

openai_sdk_helpers/response/__init__.py

@@ -33,20 +33,23 @@ attach_vector_store
 from __future__ import annotations
 
 from .base import BaseResponse
-from .config import ResponseConfiguration
+from .config import ResponseConfiguration, ResponseRegistry, get_default_registry
 from .messages import ResponseMessage, ResponseMessages
 from .runner import run_async, run_streamed, run_sync
-from .tool_call import ResponseToolCall
+from .tool_call import ResponseToolCall, parse_tool_arguments
 from .vector_store import attach_vector_store
 
 __all__ = [
     "BaseResponse",
     "ResponseConfiguration",
+    "ResponseRegistry",
+    "get_default_registry",
     "ResponseMessage",
     "ResponseMessages",
     "run_sync",
     "run_async",
     "run_streamed",
     "ResponseToolCall",
+    "parse_tool_arguments",
     "attach_vector_store",
 ]