aponyx 0.1.0__py3-none-any.whl

aponyx/data/validation.py

@@ -0,0 +1,231 @@
+"""
+Data validation utilities for market data quality checks.
+
+Validates schema compliance, data types, and business logic constraints.
+"""
+
+import logging
+
+import pandas as pd
+
+from .schemas import CDXSchema, VIXSchema, ETFSchema
+
+logger = logging.getLogger(__name__)
+
+
+def _ensure_datetime_index(df: pd.DataFrame, date_col: str) -> pd.DataFrame:
+    """
+    Convert DataFrame to use DatetimeIndex if not already.
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+        DataFrame to process.
+    date_col : str
+        Name of date column to use as index.
+
+    Returns
+    -------
+    pd.DataFrame
+        DataFrame with DatetimeIndex, sorted by date.
+    """
+    if not isinstance(df.index, pd.DatetimeIndex):
+        df = df.copy()
+        df[date_col] = pd.to_datetime(df[date_col])
+        df = df.set_index(date_col)
+    
+    return df.sort_index()
+
+
+def _check_duplicate_dates(df: pd.DataFrame, context: str = "") -> None:
+    """
+    Check for and log duplicate dates in DataFrame index.
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+        DataFrame with DatetimeIndex to check.
+    context : str, optional
+        Additional context for log message (e.g., ticker name).
+    """
+    if df.index.duplicated().any():
+        n_dups = df.index.duplicated().sum()
+        if context:
+            logger.warning("Found %d duplicate dates for %s", n_dups, context)
+        else:
+            logger.warning("Found %d duplicate dates", n_dups)
+
+
+def validate_cdx_schema(df: pd.DataFrame, schema: CDXSchema = CDXSchema()) -> pd.DataFrame:
+    """
+    Validate CDX index data against expected schema.
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+        Raw CDX data to validate.
+    schema : CDXSchema, default CDXSchema()
+        Schema definition with column names and constraints.
+
+    Returns
+    -------
+    pd.DataFrame
+        Validated DataFrame with DatetimeIndex.
+
+    Raises
+    ------
+    ValueError
+        If required columns are missing or data violates constraints.
+
+    Notes
+    -----
+    - Converts date column to DatetimeIndex
+    - Validates spread values are within bounds
+    - Checks for duplicate dates per index
+    """
+    logger.info("Validating CDX schema: %d rows", len(df))
+
+    # Check required columns (except date if already indexed)
+    required_cols = list(schema.required_cols)
+    if isinstance(df.index, pd.DatetimeIndex):
+        # Already has DatetimeIndex, don't require date column
+        required_cols = [col for col in required_cols if col != schema.date_col]
+
+    missing_cols = [col for col in required_cols if col not in df.columns]
+    if missing_cols:
+        raise ValueError(f"Missing required columns: {missing_cols}")
+
+    # Validate spread bounds
+    if not df[schema.spread_col].between(schema.min_spread, schema.max_spread).all():
+        invalid = df[
+            ~df[schema.spread_col].between(schema.min_spread, schema.max_spread)
+        ]
+        logger.warning(
+            "Found %d invalid spread values outside [%.1f, %.1f]",
+            len(invalid),
+            schema.min_spread,
+            schema.max_spread,
+        )
+        raise ValueError(f"Spread values outside valid range: {invalid.head()}")
+
+    # Convert to DatetimeIndex and sort
+    df = _ensure_datetime_index(df, schema.date_col)
+
+    # Check for duplicates
+    _check_duplicate_dates(df)
+
+    logger.debug("CDX validation passed: date_range=%s to %s", df.index.min(), df.index.max())
+    return df
+
+
+def validate_vix_schema(df: pd.DataFrame, schema: VIXSchema = VIXSchema()) -> pd.DataFrame:
+    """
+    Validate VIX volatility data against expected schema.
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+        Raw VIX data to validate.
+    schema : VIXSchema, default VIXSchema()
+        Schema definition with column names and constraints.
+
+    Returns
+    -------
+    pd.DataFrame
+        Validated DataFrame with DatetimeIndex.
+
+    Raises
+    ------
+    ValueError
+        If required columns are missing or data violates constraints.
+    """
+    logger.info("Validating VIX schema: %d rows", len(df))
+
+    # Check required columns (except date if already indexed)
+    required_cols = list(schema.required_cols)
+    if isinstance(df.index, pd.DatetimeIndex):
+        # Already has DatetimeIndex, don't require date column
+        required_cols = [col for col in required_cols if col != schema.date_col]
+
+    missing_cols = [col for col in required_cols if col not in df.columns]
+    if missing_cols:
+        raise ValueError(f"Missing required columns: {missing_cols}")
+
+    # Validate VIX bounds
+    if not df[schema.close_col].between(schema.min_vix, schema.max_vix).all():
+        invalid = df[~df[schema.close_col].between(schema.min_vix, schema.max_vix)]
+        logger.warning(
+            "Found %d invalid VIX values outside [%.1f, %.1f]",
+            len(invalid),
+            schema.min_vix,
+            schema.max_vix,
+        )
+        raise ValueError(f"VIX values outside valid range: {invalid.head()}")
+
+    # Convert to DatetimeIndex and sort
+    df = _ensure_datetime_index(df, schema.date_col)
+
+    # Check for duplicates (remove duplicates for VIX)
+    if df.index.duplicated().any():
+        _check_duplicate_dates(df)
+        df = df[~df.index.duplicated(keep="first")]
+
+    logger.debug("VIX validation passed: date_range=%s to %s", df.index.min(), df.index.max())
+    return df
+
+
+def validate_etf_schema(df: pd.DataFrame, schema: ETFSchema = ETFSchema()) -> pd.DataFrame:
+    """
+    Validate credit ETF data against expected schema.
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+        Raw ETF data to validate.
+    schema : ETFSchema, default ETFSchema()
+        Schema definition with column names and constraints.
+
+    Returns
+    -------
+    pd.DataFrame
+        Validated DataFrame with DatetimeIndex.
+
+    Raises
+    ------
+    ValueError
+        If required columns are missing or data violates constraints.
+    """
+    logger.info("Validating ETF schema: %d rows", len(df))
+
+    # Check required columns (except date if already indexed)
+    required_cols = list(schema.required_cols)
+    if isinstance(df.index, pd.DatetimeIndex):
+        # Already has DatetimeIndex, don't require date column
+        required_cols = [col for col in required_cols if col != schema.date_col]
+
+    missing_cols = [col for col in required_cols if col not in df.columns]
+    if missing_cols:
+        raise ValueError(f"Missing required columns: {missing_cols}")
+
+    # Validate price bounds
+    if not df[schema.close_col].between(schema.min_price, schema.max_price).all():
+        invalid = df[~df[schema.close_col].between(schema.min_price, schema.max_price)]
+        logger.warning(
+            "Found %d invalid price values outside [%.1f, %.1f]",
+            len(invalid),
+            schema.min_price,
+            schema.max_price,
+        )
+        raise ValueError(f"Price values outside valid range: {invalid.head()}")
+
+    # Convert to DatetimeIndex and sort
+    df = _ensure_datetime_index(df, schema.date_col)
+
+    # Check for duplicates per ticker
+    if schema.ticker_col in df.columns:
+        for ticker in df[schema.ticker_col].unique():
+            ticker_df = df[df[schema.ticker_col] == ticker]
+            _check_duplicate_dates(ticker_df, context=f"ticker {ticker}")
+
+    logger.debug("ETF validation passed: date_range=%s to %s", df.index.min(), df.index.max())
+    return df

aponyx/main.py

@@ -0,0 +1,7 @@
+def main() -> None:
+    """Main entry point."""
+    print("Hello from aponyx!")
+
+
+if __name__ == "__main__":
+    main()

aponyx/models/__init__.py

@@ -0,0 +1,24 @@
+"""
+Models layer for systematic credit strategies.
+
+This module provides signal generation and strategy logic for the CDX overlay pilot.
+"""
+
+from .signals import (
+    compute_cdx_etf_basis,
+    compute_cdx_vix_gap,
+    compute_spread_momentum,
+)
+from .config import SignalConfig
+from .registry import SignalRegistry, SignalMetadata
+from .catalog import compute_registered_signals
+
+__all__ = [
+    "compute_cdx_etf_basis",
+    "compute_cdx_vix_gap",
+    "compute_spread_momentum",
+    "SignalConfig",
+    "SignalRegistry",
+    "SignalMetadata",
+    "compute_registered_signals",
+]

aponyx/models/catalog.py

@@ -0,0 +1,167 @@
+"""
+Signal computation orchestration using registry pattern.
+"""
+
+import logging
+
+import pandas as pd
+
+from . import signals
+from .config import SignalConfig
+from .registry import SignalRegistry, SignalMetadata
+
+logger = logging.getLogger(__name__)
+
+
+def compute_registered_signals(
+    registry: SignalRegistry,
+    market_data: dict[str, pd.DataFrame],
+    config: SignalConfig,
+) -> dict[str, pd.Series]:
+    """
+    Compute all enabled signals from registry using provided market data.
+
+    Validates data requirements, resolves compute functions dynamically,
+    and executes signal computations in registration order.
+
+    Parameters
+    ----------
+    registry : SignalRegistry
+        Signal registry containing metadata and catalog.
+    market_data : dict[str, pd.DataFrame]
+        Market data mapping. Keys should match signal data_requirements.
+        Example: {"cdx": cdx_df, "etf": etf_df, "vix": vix_df}
+    config : SignalConfig
+        Configuration parameters for signal computation (lookback, min_periods).
+
+    Returns
+    -------
+    dict[str, pd.Series]
+        Mapping from signal name to computed signal series.
+
+    Raises
+    ------
+    ValueError
+        If required market data is missing or lacks required columns.
+    AttributeError
+        If compute function name does not exist in signals module.
+
+    Examples
+    --------
+    >>> registry = SignalRegistry("signal_catalog.json")
+    >>> market_data = {"cdx": cdx_df, "etf": etf_df, "vix": vix_df}
+    >>> config = SignalConfig(lookback=20)
+    >>> signals_dict = compute_registered_signals(registry, market_data, config)
+    """
+    enabled_signals = registry.get_enabled()
+
+    logger.info(
+        "Computing %d enabled signals: %s",
+        len(enabled_signals),
+        ", ".join(sorted(enabled_signals.keys())),
+    )
+
+    results: dict[str, pd.Series] = {}
+
+    for signal_name, metadata in enabled_signals.items():
+        try:
+            signal_series = _compute_signal(metadata, market_data, config)
+            results[signal_name] = signal_series
+
+            logger.debug(
+                "Computed signal '%s': valid_obs=%d",
+                signal_name,
+                signal_series.notna().sum(),
+            )
+
+        except Exception as e:
+            logger.error(
+                "Failed to compute signal '%s': %s",
+                signal_name,
+                e,
+                exc_info=True,
+            )
+            raise
+
+    logger.info("Successfully computed %d signals", len(results))
+    return results
+
+
+def _compute_signal(
+    metadata: SignalMetadata,
+    market_data: dict[str, pd.DataFrame],
+    config: SignalConfig,
+) -> pd.Series:
+    """
+    Compute a single signal using metadata specification.
+
+    Parameters
+    ----------
+    metadata : SignalMetadata
+        Signal metadata with data requirements and function mapping.
+    market_data : dict[str, pd.DataFrame]
+        Available market data.
+    config : SignalConfig
+        Signal computation parameters.
+
+    Returns
+    -------
+    pd.Series
+        Computed signal.
+
+    Raises
+    ------
+    ValueError
+        If required data is missing or lacks required columns.
+    AttributeError
+        If compute function does not exist in signals module.
+    """
+    # Validate all required data is available
+    _validate_data_requirements(metadata, market_data)
+
+    # Resolve compute function from signals module
+    compute_fn = getattr(signals, metadata.compute_function_name)
+
+    # Build positional arguments from arg_mapping
+    args = [market_data[key] for key in metadata.arg_mapping]
+
+    # Call compute function with market data and config
+    signal = compute_fn(*args, config)
+
+    return signal
+
+
+def _validate_data_requirements(
+    metadata: SignalMetadata,
+    market_data: dict[str, pd.DataFrame],
+) -> None:
+    """
+    Validate market data satisfies signal's data requirements.
+
+    Parameters
+    ----------
+    metadata : SignalMetadata
+        Signal metadata with data requirements.
+    market_data : dict[str, pd.DataFrame]
+        Available market data.
+
+    Raises
+    ------
+    ValueError
+        If required data key is missing or DataFrame lacks required column.
+    """
+    for data_key, required_column in metadata.data_requirements.items():
+        # Check data key exists
+        if data_key not in market_data:
+            raise ValueError(
+                f"Signal '{metadata.name}' requires market data key '{data_key}'. "
+                f"Available keys: {sorted(market_data.keys())}"
+            )
+
+        # Check required column exists in DataFrame
+        df = market_data[data_key]
+        if required_column not in df.columns:
+            raise ValueError(
+                f"Signal '{metadata.name}' requires column '{required_column}' "
+                f"in '{data_key}' data. Available columns: {list(df.columns)}"
+            )

aponyx/models/config.py

@@ -0,0 +1,33 @@
+"""
+Configuration dataclasses for signal generation.
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class SignalConfig:
+    """
+    Configuration parameters for individual signal computation.
+
+    Attributes
+    ----------
+    lookback : int
+        Rolling window size for normalization and statistics.
+    min_periods : int
+        Minimum observations required for valid calculation.
+    """
+
+    lookback: int = 20
+    min_periods: int = 10
+
+    def __post_init__(self) -> None:
+        """Validate configuration parameters."""
+        if self.lookback <= 0:
+            raise ValueError(f"lookback must be positive, got {self.lookback}")
+        if self.min_periods <= 0:
+            raise ValueError(f"min_periods must be positive, got {self.min_periods}")
+        if self.min_periods > self.lookback:
+            raise ValueError(
+                f"min_periods ({self.min_periods}) cannot exceed lookback ({self.lookback})"
+            )

aponyx/models/registry.py

@@ -0,0 +1,200 @@
+"""
+Signal registry for managing signal metadata and catalog persistence.
+"""
+
+import json
+import logging
+from dataclasses import dataclass, asdict
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class SignalMetadata:
+    """
+    Metadata for a registered signal computation.
+
+    Attributes
+    ----------
+    name : str
+        Unique signal identifier (e.g., "cdx_etf_basis").
+    description : str
+        Human-readable description of signal purpose and logic.
+    compute_function_name : str
+        Name of the compute function in signals module (e.g., "compute_cdx_etf_basis").
+    data_requirements : dict[str, str]
+        Mapping from market data keys to required column names.
+        Example: {"cdx": "spread", "etf": "close"}
+    arg_mapping : list[str]
+        Ordered list of data keys to pass as positional arguments to compute function.
+        Example: ["cdx", "etf"] means call compute_fn(market_data["cdx"], market_data["etf"], config)
+    enabled : bool
+        Whether signal should be included in computation.
+    """
+
+    name: str
+    description: str
+    compute_function_name: str
+    data_requirements: dict[str, str]
+    arg_mapping: list[str]
+    enabled: bool = True
+
+    def __post_init__(self) -> None:
+        """Validate signal metadata."""
+        if not self.name:
+            raise ValueError("Signal name cannot be empty")
+        if not self.compute_function_name:
+            raise ValueError("Compute function name cannot be empty")
+        if not self.arg_mapping:
+            raise ValueError("arg_mapping cannot be empty")
+        # Validate arg_mapping is subset of data_requirements keys
+        missing_args = set(self.arg_mapping) - set(self.data_requirements.keys())
+        if missing_args:
+            raise ValueError(
+                f"arg_mapping contains keys not in data_requirements: {missing_args}"
+            )
+
+
+class SignalRegistry:
+    """
+    Registry for signal metadata with JSON catalog persistence.
+
+    Manages signal definitions, enabling/disabling signals, and catalog I/O.
+    Follows pattern from persistence.registry.DataRegistry.
+
+    Parameters
+    ----------
+    catalog_path : str | Path
+        Path to JSON catalog file containing signal metadata.
+
+    Examples
+    --------
+    >>> registry = SignalRegistry("src/aponyx/models/signal_catalog.json")
+    >>> enabled = registry.get_enabled()
+    >>> metadata = registry.get_metadata("cdx_etf_basis")
+    """
+
+    def __init__(self, catalog_path: str | Path) -> None:
+        """
+        Initialize registry and load catalog from JSON file.
+
+        Parameters
+        ----------
+        catalog_path : str | Path
+            Path to JSON catalog file.
+
+        Raises
+        ------
+        FileNotFoundError
+            If catalog file does not exist.
+        ValueError
+            If catalog JSON is invalid or contains duplicate signal names.
+        """
+        self._catalog_path = Path(catalog_path)
+        self._signals: dict[str, SignalMetadata] = {}
+        self._load_catalog()
+
+        logger.info(
+            "Loaded signal registry: catalog=%s, signals=%d, enabled=%d",
+            self._catalog_path,
+            len(self._signals),
+            len(self.get_enabled()),
+        )
+
+    def _load_catalog(self) -> None:
+        """Load signal metadata from JSON catalog file."""
+        if not self._catalog_path.exists():
+            raise FileNotFoundError(
+                f"Signal catalog not found: {self._catalog_path}"
+            )
+
+        with open(self._catalog_path, "r", encoding="utf-8") as f:
+            catalog_data = json.load(f)
+
+        if not isinstance(catalog_data, list):
+            raise ValueError("Signal catalog must be a JSON array")
+
+        for entry in catalog_data:
+            try:
+                metadata = SignalMetadata(**entry)
+                if metadata.name in self._signals:
+                    raise ValueError(
+                        f"Duplicate signal name in catalog: {metadata.name}"
+                    )
+                self._signals[metadata.name] = metadata
+            except TypeError as e:
+                raise ValueError(
+                    f"Invalid signal metadata in catalog: {entry}. Error: {e}"
+                ) from e
+
+        logger.debug("Loaded %d signals from catalog", len(self._signals))
+
+    def get_metadata(self, name: str) -> SignalMetadata:
+        """
+        Retrieve metadata for a specific signal.
+
+        Parameters
+        ----------
+        name : str
+            Signal name.
+
+        Returns
+        -------
+        SignalMetadata
+            Signal metadata.
+
+        Raises
+        ------
+        KeyError
+            If signal name is not registered.
+        """
+        if name not in self._signals:
+            raise KeyError(
+                f"Signal '{name}' not found in registry. "
+                f"Available signals: {sorted(self._signals.keys())}"
+            )
+        return self._signals[name]
+
+    def get_enabled(self) -> dict[str, SignalMetadata]:
+        """
+        Get all enabled signals.
+
+        Returns
+        -------
+        dict[str, SignalMetadata]
+            Mapping from signal name to metadata for enabled signals only.
+        """
+        return {
+            name: meta for name, meta in self._signals.items() if meta.enabled
+        }
+
+    def list_all(self) -> dict[str, SignalMetadata]:
+        """
+        Get all registered signals (enabled and disabled).
+
+        Returns
+        -------
+        dict[str, SignalMetadata]
+            Mapping from signal name to metadata for all signals.
+        """
+        return self._signals.copy()
+
+    def save_catalog(self, path: str | Path | None = None) -> None:
+        """
+        Save signal metadata to JSON catalog file.
+
+        Parameters
+        ----------
+        path : str | Path | None
+            Output path. If None, overwrites original catalog file.
+        """
+        output_path = Path(path) if path else self._catalog_path
+
+        catalog_data = [asdict(meta) for meta in self._signals.values()]
+
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        with open(output_path, "w", encoding="utf-8") as f:
+            json.dump(catalog_data, f, indent=2)
+
+        logger.info("Saved signal catalog: path=%s, signals=%d", output_path, len(catalog_data))

aponyx/models/signal_catalog.json

@@ -0,0 +1,34 @@
+[
+  {
+    "name": "cdx_etf_basis",
+    "description": "Flow-driven mispricing signal from CDX-ETF basis divergence",
+    "compute_function_name": "compute_cdx_etf_basis",
+    "data_requirements": {
+      "cdx": "spread",
+      "etf": "close"
+    },
+    "arg_mapping": ["cdx", "etf"],
+    "enabled": true
+  },
+  {
+    "name": "cdx_vix_gap",
+    "description": "Cross-asset risk sentiment divergence between credit and equity volatility",
+    "compute_function_name": "compute_cdx_vix_gap",
+    "data_requirements": {
+      "cdx": "spread",
+      "vix": "close"
+    },
+    "arg_mapping": ["cdx", "vix"],
+    "enabled": true
+  },
+  {
+    "name": "spread_momentum",
+    "description": "Short-term volatility-adjusted momentum in CDX spreads",
+    "compute_function_name": "compute_spread_momentum",
+    "data_requirements": {
+      "cdx": "spread"
+    },
+    "arg_mapping": ["cdx"],
+    "enabled": true
+  }
+]