oscura 0.0.1__py3-none-any.whl → 0.1.0__py3-none-any.whl

oscura/core/memoize.py

@@ -0,0 +1,171 @@
+"""Memory-safe memoization decorators for TraceKit analyzer functions.
+
+This module provides lightweight memoization decorators optimized for analyzer
+functions that process numpy arrays. Unlike the full TraceKitCache, these
+decorators provide simple in-memory caching with bounded size.
+
+
+Example:
+    >>> from oscura.core.memoize import memoize_analysis
+    >>> @memoize_analysis(maxsize=32)
+    ... def expensive_fft(signal, nperseg):
+    ...     return scipy.fft.fft(signal, n=nperseg)
+    >>> result = expensive_fft(signal_array, 1024)  # Computed
+    >>> result = expensive_fft(signal_array, 1024)  # Cached
+
+References:
+    functools.lru_cache for standard Python memoization
+    hashlib for stable array hashing
+"""
+
+from __future__ import annotations
+
+import hashlib
+from functools import wraps
+from typing import TYPE_CHECKING, Any, TypeVar
+
+import numpy as np
+from numpy.typing import NDArray
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+T = TypeVar("T")
+
+
+def array_hash(arr: NDArray[Any], sample_size: int = 10000) -> str:
+    """Create stable hash for numpy array.
+
+    Uses first `sample_size` bytes of array data to create a hash key.
+    This is faster than hashing the entire array while maintaining
+    good cache hit rates for typical analysis workflows.
+
+    Args:
+        arr: Numpy array to hash.
+        sample_size: Number of bytes to sample for hashing (default: 10KB).
+
+    Returns:
+        16-character hex hash string.
+
+    Example:
+        >>> arr = np.arange(1000000, dtype=np.float32)
+        >>> hash1 = array_hash(arr)
+        >>> hash2 = array_hash(arr)
+        >>> assert hash1 == hash2
+    """
+    # Use shape, dtype, and sample of data for hash
+    hash_obj = hashlib.sha256()
+
+    # Include shape and dtype
+    hash_obj.update(str(arr.shape).encode())
+    hash_obj.update(str(arr.dtype).encode())
+
+    # Sample first N bytes of data
+    data_bytes = arr.tobytes()[:sample_size]
+    hash_obj.update(data_bytes)
+
+    return hash_obj.hexdigest()[:16]
+
+
+def memoize_analysis(maxsize: int = 32) -> Callable[[Callable[..., T]], Callable[..., T]]:
+    """Decorator for memoizing analysis functions with numpy arrays.
+
+    Automatically hashes numpy array arguments for cache keys.
+    Memory-safe with bounded cache size using LRU eviction.
+
+
+    Args:
+        maxsize: Maximum number of cached results (default: 32).
+
+    Returns:
+        Decorator function.
+
+    Example:
+        >>> @memoize_analysis(maxsize=16)
+        ... def detect_edges(signal, threshold):
+        ...     # Expensive edge detection...
+        ...     return edges
+        >>> # First call computes
+        >>> edges1 = detect_edges(signal_array, 0.5)
+        >>> # Second call uses cache
+        >>> edges2 = detect_edges(signal_array, 0.5)
+        >>> assert edges1 is edges2
+
+    Note:
+        Cache is stored per-function. Use TraceKitCache from core.cache
+        for persistent cross-function caching.
+
+    References:
+        PERF-001: Performance optimization requirements
+    """
+
+    def decorator(func: Callable[..., T]) -> Callable[..., T]:
+        cache: dict[str, T] = {}
+        cache_order: list[str] = []  # Track insertion order for LRU
+
+        @wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> T:
+            # Build cache key from args
+            key_parts: list[str] = []
+
+            for arg in args:
+                if isinstance(arg, np.ndarray):
+                    key_parts.append(f"arr_{len(arg)}_{array_hash(arg)}")
+                else:
+                    key_parts.append(str(arg))
+
+            for k, v in sorted(kwargs.items()):
+                if isinstance(v, np.ndarray):
+                    key_parts.append(f"{k}=arr_{len(v)}_{array_hash(v)}")
+                else:
+                    key_parts.append(f"{k}={v}")
+
+            cache_key = ":".join(key_parts)
+
+            # Check cache
+            if cache_key in cache:
+                # Move to end (most recently used)
+                cache_order.remove(cache_key)
+                cache_order.append(cache_key)
+                return cache[cache_key]
+
+            # Compute result
+            result = func(*args, **kwargs)
+
+            # Evict oldest if at capacity
+            if len(cache) >= maxsize:
+                oldest = cache_order.pop(0)
+                del cache[oldest]
+
+            # Store result
+            cache[cache_key] = result
+            cache_order.append(cache_key)
+
+            return result
+
+        def cache_clear() -> None:
+            """Clear all cached results."""
+            cache.clear()
+            cache_order.clear()
+
+        def cache_info() -> dict[str, Any]:
+            """Get cache statistics.
+
+            Returns:
+                Dictionary with cache size and maxsize.
+            """
+            return {"size": len(cache), "maxsize": maxsize}
+
+        # Attach utility methods
+        wrapper.cache_clear = cache_clear  # type: ignore[attr-defined]
+        wrapper.cache_info = cache_info  # type: ignore[attr-defined]
+
+        return wrapper
+
+    return decorator
+
+
+__all__ = [
+    "array_hash",
+    "memoize_analysis",
+]

oscura/core/memory_check.py

@@ -0,0 +1,274 @@
+"""Pre-flight memory checking for TraceKit operations.
+
+This module provides automatic memory verification before executing
+memory-intensive operations to prevent OOM crashes.
+
+
+Example:
+    >>> from oscura.core.memory_check import check_operation_memory, require_memory
+    >>> check = check_operation_memory('spectrogram', samples=1e9, nperseg=4096)
+    >>> if not check.sufficient:
+    ...     print(check.recommendation)
+
+References:
+    See oscura.utils.memory for memory estimation functions.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from oscura.utils.memory import (
+    MemoryCheck,
+    MemoryCheckError,
+    check_memory_available,
+    require_memory,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+
+# Operations that automatically perform memory checks
+_AUTO_CHECK_OPERATIONS = {
+    "fft",
+    "psd",
+    "spectrogram",
+    "eye_diagram",
+    "correlate",
+    "filter",
+    "stft",
+    "cwt",
+    "dwt",
+}
+
+# Global flag to bypass memory checks (use with caution)
+_force_memory = False
+
+
+def set_force_memory(enabled: bool) -> None:
+    """Enable or disable forced memory bypass.
+
+
+    Args:
+        enabled: If True, bypass memory checks (dangerous).
+
+    Warning:
+        Bypassing memory checks can lead to system crashes.
+        Only use when you are certain the operation will succeed.
+
+    Example:
+        >>> set_force_memory(True)  # Bypass all memory checks
+        >>> # ... perform operation ...
+        >>> set_force_memory(False)  # Re-enable checks
+    """
+    global _force_memory
+    _force_memory = enabled
+
+
+def is_force_memory() -> bool:
+    """Check if memory checks are bypassed.
+
+    Returns:
+        True if memory checks are disabled.
+    """
+    return _force_memory
+
+
+def check_operation_memory(
+    operation: str,
+    samples: int | float | None = None,
+    **kwargs: Any,
+) -> MemoryCheck:
+    """Check if sufficient memory is available for an operation.
+
+
+    This is a convenience wrapper around utils.memory.check_memory_available
+    with automatic bypass support.
+
+    Args:
+        operation: Operation name (fft, psd, spectrogram, etc.).
+        samples: Number of samples to process.
+        **kwargs: Additional operation-specific parameters.
+
+    Returns:
+        MemoryCheck with sufficiency status and recommendations.
+
+    Example:
+        >>> check = check_operation_memory('fft', samples=1e9, nfft=8192)
+        >>> if not check.sufficient:
+        ...     print(f"Insufficient memory: {check.recommendation}")
+    """
+    # Bypass check if forced
+    if _force_memory:
+        return MemoryCheck(
+            sufficient=True,
+            available=0,
+            required=0,
+            recommendation="Memory check bypassed (--force-memory enabled)",
+        )
+
+    return check_memory_available(operation, samples, **kwargs)
+
+
+def auto_check_memory(
+    operation: str,
+    samples: int | float | None = None,
+    **kwargs: Any,
+) -> None:
+    """Automatically check memory and raise error if insufficient.
+
+
+    This function is called automatically by operations that support
+    memory checking (fft, psd, spectrogram, etc.).
+
+    Args:
+        operation: Operation name.
+        samples: Number of samples.
+        **kwargs: Additional parameters.
+
+    Example:
+        >>> try:
+        ...     auto_check_memory('spectrogram', samples=1e9, nperseg=4096)
+        ... except MemoryCheckError as e:
+        ...     print(f"Memory check failed: {e}")
+        ...     print(f"Suggestion: {e.recommendation}")
+
+    Note:
+        May raise MemoryCheckError if insufficient memory and not forced.
+    """
+    # Skip check if operation doesn't require it
+    if operation not in _AUTO_CHECK_OPERATIONS:
+        return
+
+    # Bypass if forced
+    if _force_memory:
+        return
+
+    # Perform check
+    require_memory(operation, samples, **kwargs)
+
+
+def with_memory_check(func: Callable) -> Callable:  # type: ignore[type-arg]
+    """Decorator to add automatic memory checking to a function.
+
+
+    The decorated function must accept 'samples' as a keyword argument
+    and should have an 'operation' attribute or name that matches
+    a supported operation type.
+
+    Args:
+        func: Function to decorate.
+
+    Returns:
+        Decorated function with memory checking.
+
+    Example:
+        >>> @with_memory_check
+        ... def my_fft(signal, samples=None, **kwargs):
+        ...     # ... FFT implementation ...
+        ...     pass
+        >>> my_fft.operation = 'fft'  # Specify operation type
+    """
+
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        # Extract operation name
+        operation = getattr(func, "operation", func.__name__)
+
+        # Extract samples if available
+        samples = kwargs.get("samples")
+        if samples is None and len(args) > 0:
+            # Try to infer from first argument
+            try:
+                import numpy as np
+
+                if isinstance(args[0], np.ndarray):
+                    samples = len(args[0])
+            except (ImportError, TypeError):
+                pass
+
+        # Perform check
+        if operation in _AUTO_CHECK_OPERATIONS and not _force_memory:
+            auto_check_memory(operation, samples, **kwargs)
+
+        # Call original function
+        return func(*args, **kwargs)
+
+    # Preserve function metadata
+    wrapper.__name__ = func.__name__
+    wrapper.__doc__ = func.__doc__
+    wrapper.__module__ = func.__module__
+
+    return wrapper
+
+
+def register_auto_check_operation(operation: str) -> None:
+    """Register an operation for automatic memory checking.
+
+    Args:
+        operation: Operation name to register.
+
+    Example:
+        >>> register_auto_check_operation('custom_transform')
+        >>> # Now custom_transform will automatically check memory
+    """
+    _AUTO_CHECK_OPERATIONS.add(operation)
+
+
+def unregister_auto_check_operation(operation: str) -> None:
+    """Unregister an operation from automatic memory checking.
+
+    Args:
+        operation: Operation name to unregister.
+
+    Example:
+        >>> unregister_auto_check_operation('custom_transform')
+        >>> # Now custom_transform will not automatically check memory
+    """
+    _AUTO_CHECK_OPERATIONS.discard(operation)
+
+
+def _reset_auto_check_operations() -> None:
+    """Reset AUTO_CHECK_OPERATIONS to default state.
+
+    WARNING: This is for testing only. It resets the global state to defaults.
+    """
+    global _AUTO_CHECK_OPERATIONS
+    _AUTO_CHECK_OPERATIONS = {
+        "fft",
+        "psd",
+        "spectrogram",
+        "eye_diagram",
+        "correlate",
+        "filter",
+        "stft",
+        "cwt",
+        "dwt",
+    }
+
+
+def get_auto_check_operations() -> set[str]:
+    """Get set of operations that automatically check memory.
+
+    Returns:
+        Set of operation names.
+
+    Example:
+        >>> ops = get_auto_check_operations()
+        >>> print(f"Auto-checked operations: {', '.join(sorted(ops))}")
+    """
+    return _AUTO_CHECK_OPERATIONS.copy()
+
+
+__all__ = [
+    "MemoryCheck",
+    "MemoryCheckError",
+    "auto_check_memory",
+    "check_operation_memory",
+    "get_auto_check_operations",
+    "is_force_memory",
+    "register_auto_check_operation",
+    "set_force_memory",
+    "unregister_auto_check_operation",
+    "with_memory_check",
+]