ml4t-diagnostic 0.1.0a1__py3-none-any.whl

ml4t/diagnostic/caching/smart_cache.py

@@ -0,0 +1,339 @@
+"""Smart cache with Polars DataFrame fingerprinting.
+
+This module provides a memory-only cache optimized for signal analysis workloads,
+featuring fast and stable DataFrame fingerprinting using Polars' hash_rows().
+
+The SmartCache is designed for exploration workflows where signals are frequently
+re-analyzed with different parameters. It uses LRU eviction and optional TTL
+expiration to manage memory usage.
+
+Examples
+--------
+>>> from ml4t.diagnostic.caching.smart_cache import SmartCache
+>>> cache = SmartCache(max_items=100, ttl_seconds=3600)
+>>>
+>>> # Generate cache key for a signal
+>>> key = cache.make_key("momentum", signal_df, config)
+>>>
+>>> # Check cache
+>>> result = cache.get(key)
+>>> if result is None:
+...     result = expensive_analysis(signal_df)
+...     cache.set(key, result)
+
+References
+----------
+Polars hash_rows: https://pola-rs.github.io/polars/py-polars/html/reference/dataframe.html
+"""
+
+from __future__ import annotations
+
+import hashlib
+import time
+from collections import OrderedDict
+from typing import TYPE_CHECKING, Any
+
+import polars as pl
+
+if TYPE_CHECKING:
+    from ml4t.diagnostic.config.base import BaseConfig
+
+
+class SmartCache:
+    """Memory cache with Polars DataFrame fingerprinting.
+
+    Provides fast, stable caching for signal analysis results using
+    content-based keys generated from DataFrames and configurations.
+
+    Features
+    --------
+    - **Polars fingerprinting**: Uses pl.hash_rows() for fast, stable hashing
+    - **LRU eviction**: Automatically removes least recently used items
+    - **TTL expiration**: Optional time-based expiration
+    - **Memory-only**: No disk persistence (simpler, exploration-focused)
+
+    Parameters
+    ----------
+    max_items : int, default 100
+        Maximum number of items in cache. When exceeded, LRU eviction occurs.
+    ttl_seconds : int | None, default 3600
+        Time-to-live in seconds. None disables expiration.
+
+    Examples
+    --------
+    >>> cache = SmartCache(max_items=200, ttl_seconds=None)  # No expiration
+    >>>
+    >>> # Cache individual signal results
+    >>> for name, df in signals.items():
+    ...     key = cache.make_key(name, df, config)
+    ...     result = cache.get(key)
+    ...     if result is None:
+    ...         result = analyzer.analyze(df)
+    ...         cache.set(key, result)
+    """
+
+    def __init__(self, max_items: int = 100, ttl_seconds: int | None = 3600):
+        """Initialize SmartCache.
+
+        Parameters
+        ----------
+        max_items : int
+            Maximum cache size (LRU eviction when exceeded)
+        ttl_seconds : int | None
+            Time-to-live in seconds (None = no expiration)
+        """
+        self._cache: OrderedDict[str, tuple[Any, float]] = OrderedDict()
+        self.max_items = max_items
+        self.ttl_seconds = ttl_seconds
+        self._hits = 0
+        self._misses = 0
+
+    @staticmethod
+    def polars_fingerprint(df: pl.DataFrame, seed: int = 42) -> str:
+        """Generate stable hash from Polars DataFrame.
+
+        Uses pl.hash_rows() for fast row-wise hashing, combined with
+        schema and shape information for collision resistance.
+
+        Parameters
+        ----------
+        df : pl.DataFrame
+            DataFrame to fingerprint
+        seed : int, default 42
+            Seed for hash_rows() reproducibility
+
+        Returns
+        -------
+        str
+            MD5 hex digest of the DataFrame content
+
+        Notes
+        -----
+        The fingerprint includes:
+        - Column names and dtypes (schema)
+        - DataFrame shape
+        - Row-wise content hash using pl.hash_rows()
+
+        This ensures different DataFrames produce different fingerprints,
+        while identical DataFrames always produce the same fingerprint.
+
+        Examples
+        --------
+        >>> df1 = pl.DataFrame({"a": [1, 2, 3], "b": [4.0, 5.0, 6.0]})
+        >>> fp1 = SmartCache.polars_fingerprint(df1)
+        >>>
+        >>> # Same data = same fingerprint
+        >>> df2 = pl.DataFrame({"a": [1, 2, 3], "b": [4.0, 5.0, 6.0]})
+        >>> fp2 = SmartCache.polars_fingerprint(df2)
+        >>> assert fp1 == fp2
+        >>>
+        >>> # Different data = different fingerprint
+        >>> df3 = pl.DataFrame({"a": [1, 2, 4], "b": [4.0, 5.0, 6.0]})
+        >>> fp3 = SmartCache.polars_fingerprint(df3)
+        >>> assert fp1 != fp3
+        """
+        # Build schema string for deterministic ordering
+        schema_str = str([(c, str(d)) for c, d in zip(df.columns, df.dtypes)])
+
+        # Compute row hashes using Polars' optimized function
+        row_hashes = df.hash_rows(seed=seed)
+
+        # Combine into final hash
+        hasher = hashlib.md5()
+        hasher.update(schema_str.encode())
+        hasher.update(row_hashes.to_numpy().tobytes())
+        hasher.update(f"{df.shape}".encode())
+
+        return hasher.hexdigest()
+
+    def make_key(
+        self,
+        signal_name: str,
+        signal_df: pl.DataFrame,
+        config: BaseConfig,
+    ) -> str:
+        """Generate cache key from signal name, data, and configuration.
+
+        Parameters
+        ----------
+        signal_name : str
+            Unique identifier for the signal
+        signal_df : pl.DataFrame
+            Signal data
+        config : BaseConfig
+            Analysis configuration
+
+        Returns
+        -------
+        str
+            Cache key combining signal, data fingerprint, and config hash
+
+        Examples
+        --------
+        >>> key = cache.make_key("momentum_12m", momentum_df, config)
+        >>> key
+        'momentum_12m_a1b2c3d4e5f6_g7h8i9j0k1l2'
+        """
+        # DataFrame fingerprint (first 12 chars)
+        df_hash = self.polars_fingerprint(signal_df)[:12]
+
+        # Config hash (first 12 chars)
+        config_hash = hashlib.md5(config.model_dump_json().encode()).hexdigest()[:12]
+
+        return f"{signal_name}_{df_hash}_{config_hash}"
+
+    def get(self, key: str) -> Any | None:
+        """Retrieve value from cache.
+
+        Parameters
+        ----------
+        key : str
+            Cache key (from make_key())
+
+        Returns
+        -------
+        Any | None
+            Cached value, or None if not found/expired
+
+        Notes
+        -----
+        Updates LRU ordering on hit. Automatically removes expired entries.
+        """
+        if key not in self._cache:
+            self._misses += 1
+            return None
+
+        value, timestamp = self._cache[key]
+
+        # Check TTL expiration
+        if self.ttl_seconds is not None:
+            age = time.time() - timestamp
+            if age > self.ttl_seconds:
+                del self._cache[key]
+                self._misses += 1
+                return None
+
+        # Move to end (most recently used)
+        self._cache.move_to_end(key)
+        self._hits += 1
+        return value
+
+    def set(self, key: str, value: Any) -> None:
+        """Store value in cache.
+
+        Parameters
+        ----------
+        key : str
+            Cache key
+        value : Any
+            Value to cache
+
+        Notes
+        -----
+        Triggers LRU eviction if cache exceeds max_items.
+        """
+        # Evict oldest entries if at capacity
+        while len(self._cache) >= self.max_items:
+            self._cache.popitem(last=False)
+
+        # Add/update entry
+        self._cache[key] = (value, time.time())
+        self._cache.move_to_end(key)
+
+    def invalidate(self, key: str) -> bool:
+        """Remove specific entry from cache.
+
+        Parameters
+        ----------
+        key : str
+            Cache key to invalidate
+
+        Returns
+        -------
+        bool
+            True if key existed and was removed, False otherwise
+        """
+        if key in self._cache:
+            del self._cache[key]
+            return True
+        return False
+
+    def clear(self) -> None:
+        """Remove all entries from cache."""
+        self._cache.clear()
+        self._hits = 0
+        self._misses = 0
+
+    def invalidate_signal(self, signal_name: str) -> int:
+        """Invalidate all cache entries for a specific signal.
+
+        Useful when signal data has been updated and all cached
+        analysis results need to be discarded.
+
+        Parameters
+        ----------
+        signal_name : str
+            Signal name prefix to match
+
+        Returns
+        -------
+        int
+            Number of entries removed
+        """
+        prefix = f"{signal_name}_"
+        keys_to_remove = [k for k in self._cache if k.startswith(prefix)]
+        for key in keys_to_remove:
+            del self._cache[key]
+        return len(keys_to_remove)
+
+    @property
+    def size(self) -> int:
+        """Current number of items in cache."""
+        return len(self._cache)
+
+    @property
+    def hit_rate(self) -> float:
+        """Cache hit rate (0.0 to 1.0)."""
+        total = self._hits + self._misses
+        return self._hits / total if total > 0 else 0.0
+
+    @property
+    def stats(self) -> dict[str, Any]:
+        """Cache statistics.
+
+        Returns
+        -------
+        dict
+            Dictionary with hits, misses, hit_rate, size, max_items, ttl_seconds
+        """
+        return {
+            "hits": self._hits,
+            "misses": self._misses,
+            "hit_rate": self.hit_rate,
+            "size": self.size,
+            "max_items": self.max_items,
+            "ttl_seconds": self.ttl_seconds,
+        }
+
+    def __repr__(self) -> str:
+        """Developer representation."""
+        return (
+            f"SmartCache(size={self.size}/{self.max_items}, "
+            f"hit_rate={self.hit_rate:.1%}, ttl={self.ttl_seconds}s)"
+        )
+
+    def __contains__(self, key: str) -> bool:
+        """Check if key exists in cache (does not update LRU or count as hit)."""
+        if key not in self._cache:
+            return False
+        # Check expiration without modifying state
+        if self.ttl_seconds is not None:
+            _, timestamp = self._cache[key]
+            age = time.time() - timestamp
+            if age > self.ttl_seconds:
+                return False
+        return True
+
+    def __len__(self) -> int:
+        """Return number of items in cache."""
+        return len(self._cache)

ml4t/diagnostic/config/AGENT.md

@@ -0,0 +1,24 @@
+# config/ - Pydantic Configuration
+
+10 primary configs with `.for_quick_analysis()`, `.for_research()` presets.
+
+## Primary Configs
+
+| Config | Purpose |
+|--------|---------|
+| DiagnosticConfig | Feature diagnostics |
+| StatisticalConfig | DSR, RAS, FDR |
+| PortfolioConfig | Portfolio analysis |
+| SignalConfig | Signal analysis |
+| TradeConfig | Trade analysis |
+| EventConfig | Event studies |
+| BarrierConfig | Barrier analysis |
+| ReportConfig | Report generation |
+| RuntimeConfig | Execution settings |
+
+## Pattern
+
+```python
+config = DiagnosticConfig.for_research()
+config.stationarity.enabled  # Single-level nesting
+```

ml4t/diagnostic/config/README.md

@@ -0,0 +1,267 @@
+# ML4T Diagnostic Configuration System
+
+Type-safe, validated configuration using Pydantic v2.
+
+## Overview
+
+The configuration system provides 10 primary config classes:
+
+| Config | Purpose |
+|--------|---------|
+| `DiagnosticConfig` | Feature diagnostics (stationarity, IC, volatility) |
+| `StatisticalConfig` | Statistical tests (PSR, DSR, MinTRL, FDR) |
+| `PortfolioConfig` | Portfolio analysis (metrics, Bayesian, drawdown) |
+| `TradeConfig` | Trade analysis (extraction, SHAP, clustering) |
+| `SignalConfig` | Signal analysis (IC, quantiles, RAS) |
+| `EventConfig` | Event studies |
+| `BarrierConfig` | Triple barrier analysis |
+| `ReportConfig` | Report generation (HTML, JSON, output) |
+| `RuntimeConfig` | Execution settings (n_jobs, cache, verbose) |
+| `MultiSignalAnalysisConfig` | Multi-signal comparison |
+
+## Quick Start
+
+```python
+from ml4t.diagnostic.config import (
+    DiagnosticConfig,
+    PortfolioConfig,
+    StatisticalConfig,
+    RuntimeConfig,
+)
+
+# Use defaults (sensible out-of-the-box)
+config = DiagnosticConfig()
+portfolio_config = PortfolioConfig()
+
+# Use presets
+quick_config = DiagnosticConfig.for_quick_analysis()
+research_config = DiagnosticConfig.for_research()
+production_config = DiagnosticConfig.for_production()
+
+# Load from YAML
+config = DiagnosticConfig.from_yaml("config.yaml")
+
+# Save to YAML
+config.to_yaml("config.yaml")
+```
+
+## Architecture
+
+### File Structure
+
+```
+config/
+├── __init__.py              # Public API exports
+├── base.py                  # BaseConfig, RuntimeConfig
+├── validation.py            # Custom validators and types
+├── feature_config.py        # DiagnosticConfig + Settings
+├── portfolio_config.py      # PortfolioConfig + Settings
+├── sharpe_config.py         # StatisticalConfig + Settings
+├── signal_config.py         # SignalConfig + Settings
+├── trade_analysis_config.py # TradeConfig + Settings
+├── event_config.py          # EventConfig + WindowSettings
+├── barrier_config.py        # BarrierConfig + Settings
+├── multi_signal_config.py   # MultiSignalAnalysisConfig
+└── report_config.py         # ReportConfig + Settings
+```
+
+### Design Pattern: Single-Level Nesting
+
+All configs use a flat structure with Settings classes for grouping:
+
+```python
+from ml4t.diagnostic.config import DiagnosticConfig, StationaritySettings
+
+config = DiagnosticConfig(
+    stationarity=StationaritySettings(
+        enabled=True,
+        significance_level=0.01,
+    )
+)
+
+# Access: config.stationarity.enabled
+```
+
+## Module Configurations
+
+### Feature Diagnostics
+
+```python
+from ml4t.diagnostic.config import (
+    DiagnosticConfig,
+    StationaritySettings,
+    ICSettings,
+)
+
+config = DiagnosticConfig(
+    stationarity=StationaritySettings(
+        significance_level=0.01,
+        adf_enabled=True,
+        kpss_enabled=True,
+    ),
+    ic=ICSettings(
+        lag_structure=[0, 1, 5, 10, 21],
+        hac_adjustment=True,
+    ),
+)
+```
+
+**Settings**: StationaritySettings, ACFSettings, VolatilitySettings, DistributionSettings,
+CorrelationSettings, PCASettings, ClusteringSettings, RedundancySettings, ICSettings,
+BinaryClassificationSettings, ThresholdAnalysisSettings, MLDiagnosticsSettings
+
+### Portfolio Analysis
+
+```python
+from ml4t.diagnostic.config import (
+    PortfolioConfig,
+    MetricsSettings,
+    PortfolioMetric,
+)
+
+config = PortfolioConfig(
+    metrics=MetricsSettings(
+        metrics=[
+            PortfolioMetric.SHARPE,
+            PortfolioMetric.SORTINO,
+            PortfolioMetric.MAX_DRAWDOWN,
+        ],
+        risk_free_rate=0.02,
+        periods_per_year=252,
+    ),
+)
+```
+
+**Settings**: MetricsSettings, BayesianSettings, TimeAggregationSettings, DrawdownSettings
+
+### Statistical Testing
+
+```python
+from ml4t.diagnostic.config import (
+    StatisticalConfig,
+    PSRSettings,
+    DSRSettings,
+)
+
+config = StatisticalConfig(
+    psr=PSRSettings(
+        target_sharpe=1.0,
+        confidence_level=0.95,
+    ),
+    dsr=DSRSettings(
+        n_trials=500,
+        prob_zero_sharpe=0.5,
+    ),
+)
+```
+
+**Settings**: PSRSettings, MinTRLSettings, DSRSettings, FDRSettings
+
+### Trade Analysis
+
+```python
+from ml4t.diagnostic.config import (
+    TradeConfig,
+    ExtractionSettings,
+    ClusteringSettings,
+)
+
+config = TradeConfig(
+    extraction=ExtractionSettings(n_worst=50, n_best=20),
+    clustering=ClusteringSettings(min_cluster_size=10),
+)
+```
+
+**Settings**: ExtractionSettings, FilterSettings, AlignmentSettings, ClusteringSettings, HypothesisSettings
+
+### Signal Analysis
+
+```python
+from ml4t.diagnostic.config import SignalConfig, ICSignalSettings
+
+config = SignalConfig(
+    ic=ICSignalSettings(
+        method="spearman",
+        periods=[1, 5, 10, 21],
+    ),
+)
+```
+
+**Settings**: ICSignalSettings, QuantileSettings, RASSettings, VisualizationSettings
+
+## Presets
+
+Each config provides common presets:
+
+```python
+# Quick exploratory analysis
+config = DiagnosticConfig.for_quick_analysis()
+config = PortfolioConfig.for_quick_analysis()
+
+# Comprehensive research
+config = DiagnosticConfig.for_research()
+config = StatisticalConfig.for_research()
+
+# Production monitoring
+config = DiagnosticConfig.for_production()
+config = TradeConfig.for_production()
+```
+
+## Serialization
+
+```python
+# YAML (recommended for human editing)
+config.to_yaml("config.yaml")
+config = DiagnosticConfig.from_yaml("config.yaml")
+
+# JSON (better for APIs)
+config.to_json("config.json")
+config = DiagnosticConfig.from_json("config.json")
+
+# Auto-detect from extension
+config = DiagnosticConfig.from_file("config.yaml")
+
+# Dictionary
+config = DiagnosticConfig.from_dict({"verbose": True})
+d = config.to_dict()
+```
+
+## Validation
+
+```python
+# Automatic validation on construction
+from pydantic import ValidationError
+
+try:
+    config = StationaritySettings(significance_level=0.5)  # Invalid
+except ValidationError as e:
+    print(e)  # "significance_level must be <= 0.10"
+
+# Manual validation
+config = DiagnosticConfig()
+errors = config.validate_fully()
+```
+
+## Runtime Configuration
+
+Runtime settings are separate to avoid coupling with analysis configs:
+
+```python
+from ml4t.diagnostic.config import RuntimeConfig
+
+runtime = RuntimeConfig(
+    n_jobs=-1,           # Use all CPU cores
+    cache_enabled=True,  # Cache expensive computations
+    verbose=True,        # Show progress
+    random_state=42,     # Reproducibility
+)
+
+# Pass as separate parameter
+result = analyze_features(df, config=DiagnosticConfig(), runtime=runtime)
+```
+
+## References
+
+- **Pydantic v2**: https://docs.pydantic.dev/latest/
+- **López de Prado, M.**: "Advances in Financial Machine Learning"
+- **Bailey & López de Prado**: Multiple testing papers