aponyx 0.1.18__py3-none-any.whl

aponyx/config/__init__.py

@@ -0,0 +1,82 @@
+"""
+Configuration module for paths, constants, and environment settings.
+
+Defines project-wide constants including data paths and caching configuration.
+"""
+
+from pathlib import Path
+from typing import Final
+
+# Package root (where this config module is installed)
+# From src/aponyx/config/__init__.py -> src/aponyx
+PACKAGE_ROOT: Final[Path] = Path(__file__).parent.parent
+
+# Config directory (package-relative, included in distribution)
+CONFIG_DIR: Final[Path] = PACKAGE_ROOT / "config"
+
+# Project root for development (when working in repo)
+# From src/aponyx/config/__init__.py -> src/aponyx -> src -> project_root
+PROJECT_ROOT: Final[Path] = Path(__file__).parent.parent.parent.parent
+
+# Data directories (project-level, not package-level)
+DATA_DIR: Final[Path] = PROJECT_ROOT / "data"
+LOGS_DIR: Final[Path] = PROJECT_ROOT / "logs"
+
+# Cache configuration
+CACHE_ENABLED: Final[bool] = True
+CACHE_TTL_DAYS: Final[int] = 1  # Daily refresh for market data
+CACHE_DIR: Final[Path] = DATA_DIR / "cache"
+INDICATOR_CACHE_DIR: Final[Path] = CACHE_DIR / "indicators"
+
+# Raw data and workflow directories
+RAW_DIR: Final[Path] = DATA_DIR / "raw"
+DATA_WORKFLOWS_DIR: Final[Path] = DATA_DIR / "workflows"
+DATA_REGISTRIES_DIR: Final[Path] = DATA_DIR / ".registries"
+
+# Registry paths (project-level, mutable)
+REGISTRY_PATH: Final[Path] = DATA_REGISTRIES_DIR / "registry.json"
+
+# Catalog paths (package-relative, included in distribution)
+SIGNAL_CATALOG_PATH: Final[Path] = PACKAGE_ROOT / "models/signal_catalog.json"
+STRATEGY_CATALOG_PATH: Final[Path] = PACKAGE_ROOT / "backtest/strategy_catalog.json"
+
+# Transformation catalog paths (three-stage pipeline)
+INDICATOR_TRANSFORMATION_PATH: Final[Path] = (
+    PACKAGE_ROOT / "models/indicator_transformation.json"
+)
+SCORE_TRANSFORMATION_PATH: Final[Path] = (
+    PACKAGE_ROOT / "models/score_transformation.json"
+)
+SIGNAL_TRANSFORMATION_PATH: Final[Path] = (
+    PACKAGE_ROOT / "models/signal_transformation.json"
+)
+
+# Bloomberg configuration paths (package-relative, included in distribution)
+BLOOMBERG_SECURITIES_PATH: Final[Path] = PACKAGE_ROOT / "data/bloomberg_securities.json"
+BLOOMBERG_INSTRUMENTS_PATH: Final[Path] = (
+    PACKAGE_ROOT / "data/bloomberg_instruments.json"
+)
+
+# Evaluation layer registry paths (project-level, mutable)
+SUITABILITY_REGISTRY_PATH: Final[Path] = DATA_REGISTRIES_DIR / "suitability.json"
+PERFORMANCE_REGISTRY_PATH: Final[Path] = DATA_REGISTRIES_DIR / "performance.json"
+
+
+def ensure_directories() -> None:
+    """
+    Create required directories if they don't exist.
+
+    Creates data, logs, cache, and other necessary directories for the project.
+    Safe to call multiple times.
+    """
+    DATA_DIR.mkdir(parents=True, exist_ok=True)
+    LOGS_DIR.mkdir(parents=True, exist_ok=True)
+    CACHE_DIR.mkdir(parents=True, exist_ok=True)
+    INDICATOR_CACHE_DIR.mkdir(parents=True, exist_ok=True)
+    RAW_DIR.mkdir(parents=True, exist_ok=True)
+    DATA_WORKFLOWS_DIR.mkdir(parents=True, exist_ok=True)
+    DATA_REGISTRIES_DIR.mkdir(parents=True, exist_ok=True)
+
+
+# Initialize directories on module import
+ensure_directories()

aponyx/data/__init__.py

@@ -0,0 +1,99 @@
+"""
+Data layer for systematic macro credit strategy.
+
+This module handles data fetching, cleaning, and transformation for:
+- CDX indices (IG, HY, XO) across tenors
+- VIX equity volatility index
+- Credit ETFs (HYG, LQD) used for signal generation
+
+All fetch functions produce standardized DataFrames with DatetimeIndex and validated schemas.
+Supports multiple data providers: local files, Bloomberg Terminal, APIs.
+
+Provides dataset registry for tracking and managing available market data files.
+Time series transformations (diff, pct_change, log_return, z_score, normalized_change)
+available for signal generation and analysis.
+"""
+
+import logging
+
+from ..config import RAW_DIR
+from .fetch import fetch_cdx, fetch_vix, fetch_etf
+from .sources import FileSource, BloombergSource, APISource, DataSource
+from .validation import (
+    validate_cdx_schema,
+    validate_vix_schema,
+    validate_etf_schema,
+    handle_duplicate_index,
+)
+from .bloomberg_config import validate_bloomberg_registry
+from .registry import DataRegistry, DatasetEntry
+from .transforms import apply_transform, TransformType
+from .requirements import get_required_data_keys
+from .fetch_registry import get_fetch_spec, list_instruments
+from .loaders import load_instrument_from_raw, load_signal_required_data
+
+logger = logging.getLogger(__name__)
+
+
+def get_available_sources() -> list[str]:
+    """Get list of available data sources from RAW_DIR subdirectories.
+
+    Returns
+    -------
+    list[str]
+        List of available source names (subdirectory names under RAW_DIR).
+
+    Notes
+    -----
+    Scans RAW_DIR for subdirectories and returns their names.
+    Logs warning if subdirectory exists but is empty.
+    """
+    if not RAW_DIR.exists():
+        logger.warning("RAW_DIR does not exist: %s", RAW_DIR)
+        return []
+
+    sources = []
+    for item in RAW_DIR.iterdir():
+        if item.is_dir():
+            source_name = item.name
+            sources.append(source_name)
+
+            # Warn if directory is empty
+            if not any(item.iterdir()):
+                logger.debug("Data source directory is empty: %s", source_name)
+
+    return sorted(sources)
+
+
+__all__ = [
+    # Fetch functions
+    "fetch_cdx",
+    "fetch_vix",
+    "fetch_etf",
+    # Data sources
+    "FileSource",
+    "BloombergSource",
+    "APISource",
+    "DataSource",
+    "get_available_sources",
+    # Validation
+    "validate_cdx_schema",
+    "validate_vix_schema",
+    "validate_etf_schema",
+    "validate_bloomberg_registry",
+    "handle_duplicate_index",
+    # Registry
+    "DataRegistry",
+    "DatasetEntry",
+    # Transformations
+    "apply_transform",
+    "TransformType",
+    # Requirements
+    "get_required_data_keys",
+    # Fetch registry
+    "get_fetch_spec",
+    "list_instruments",
+    # Loaders
+    "load_instrument_from_raw",
+    "load_signal_required_data",
+]

aponyx/data/bloomberg_config.py

@@ -0,0 +1,306 @@
+"""Bloomberg instrument and security registry.
+
+Centralizes Bloomberg configuration in JSON catalogs including instrument
+specifications, field mappings, and security-to-ticker mappings.
+"""
+
+import json
+import logging
+from dataclasses import dataclass
+from typing import Any
+
+from ..config import BLOOMBERG_SECURITIES_PATH, BLOOMBERG_INSTRUMENTS_PATH
+
+logger = logging.getLogger(__name__)
+
+_INSTRUMENTS_PATH = BLOOMBERG_INSTRUMENTS_PATH
+_SECURITIES_PATH = BLOOMBERG_SECURITIES_PATH
+_INSTRUMENTS_CATALOG: dict[str, Any] | None = None
+_SECURITIES_CATALOG: dict[str, Any] | None = None
+
+
+@dataclass(frozen=True)
+class BloombergInstrumentSpec:
+    """Bloomberg instrument specification with field mappings."""
+
+    instrument_type: str
+    description: str
+    bloomberg_fields: tuple[str, ...]
+    field_mapping: dict[str, str]
+    requires_security_metadata: bool
+
+
+@dataclass(frozen=True)
+class BloombergSecuritySpec:
+    """Bloomberg security specification with ticker mapping."""
+
+    security_id: str
+    description: str
+    bloomberg_ticker: str
+    instrument_type: str
+
+
+def _load_instruments_catalog() -> dict[str, Any]:
+    """Load Bloomberg instruments catalog from JSON file."""
+    global _INSTRUMENTS_CATALOG
+    if _INSTRUMENTS_CATALOG is None:
+        with open(_INSTRUMENTS_PATH, encoding="utf-8") as f:
+            _INSTRUMENTS_CATALOG = json.load(f)
+        logger.debug("Loaded Bloomberg instruments catalog from %s", _INSTRUMENTS_PATH)
+    return _INSTRUMENTS_CATALOG
+
+
+def _load_securities_catalog() -> dict[str, Any]:
+    """Load Bloomberg securities catalog from JSON file."""
+    global _SECURITIES_CATALOG
+    if _SECURITIES_CATALOG is None:
+        with open(_SECURITIES_PATH, encoding="utf-8") as f:
+            _SECURITIES_CATALOG = json.load(f)
+        logger.debug("Loaded Bloomberg securities catalog from %s", _SECURITIES_PATH)
+    return _SECURITIES_CATALOG
+
+
+def validate_bloomberg_registry() -> tuple[dict[str, Any], dict[str, Any]]:
+    """
+    Load and validate Bloomberg instrument and security registries.
+
+    Ensures all securities reference valid instrument types defined in the
+    instruments catalog. This validates the configuration integrity at startup.
+
+    Returns
+    -------
+    tuple[dict[str, Any], dict[str, Any]]
+        (instruments, securities) dictionaries.
+
+    Raises
+    ------
+    ValueError
+        If any security references an undefined instrument type.
+
+    Examples
+    --------
+    >>> instruments, securities = validate_bloomberg_registry()
+    >>> len(instruments)
+    3
+    >>> len(securities)
+    8
+    """
+    instruments = _load_instruments_catalog()
+    securities = _load_securities_catalog()
+
+    # Validate all securities reference valid instrument types
+    valid_types = set(instruments.keys())
+    invalid_refs = []
+
+    for sec_id, sec_config in securities.items():
+        inst_type = sec_config.get("instrument_type")
+        if inst_type not in valid_types:
+            invalid_refs.append((sec_id, inst_type))
+
+    if invalid_refs:
+        error_msg = "Securities reference undefined instrument types:\n"
+        for sec_id, inst_type in invalid_refs:
+            error_msg += f"  - '{sec_id}' references '{inst_type}'\n"
+        error_msg += f"Valid instrument types: {', '.join(sorted(valid_types))}"
+        raise ValueError(error_msg)
+
+    logger.info(
+        "Bloomberg registry validated: %d instruments, %d securities",
+        len(instruments),
+        len(securities),
+    )
+    return instruments, securities
+
+
+def get_instrument_spec(instrument_type: str) -> BloombergInstrumentSpec:
+    """
+    Get Bloomberg instrument specification.
+
+    Parameters
+    ----------
+    instrument_type : str
+        Instrument type identifier ('cdx', 'vix', 'etf').
+
+    Returns
+    -------
+    BloombergInstrumentSpec
+        Specification with field mappings and metadata requirements.
+
+    Raises
+    ------
+    ValueError
+        If instrument type not found in catalog.
+    """
+    catalog = _load_instruments_catalog()
+
+    if instrument_type not in catalog:
+        available = ", ".join(sorted(catalog.keys()))
+        raise ValueError(
+            f"Unknown instrument type: {instrument_type}. Available: {available}"
+        )
+
+    spec_data = catalog[instrument_type]
+    return BloombergInstrumentSpec(
+        instrument_type=instrument_type,
+        description=spec_data["description"],
+        bloomberg_fields=tuple(spec_data["bloomberg_fields"]),
+        field_mapping=spec_data["field_mapping"],
+        requires_security_metadata=spec_data["requires_security_metadata"],
+    )
+
+
+def get_security_spec(security_id: str) -> BloombergSecuritySpec:
+    """
+    Get Bloomberg security specification.
+
+    Parameters
+    ----------
+    security_id : str
+        Internal security identifier (e.g., 'cdx_ig_5y', 'hyg').
+
+    Returns
+    -------
+    BloombergSecuritySpec
+        Security specification with Bloomberg ticker and instrument type.
+
+    Raises
+    ------
+    ValueError
+        If security not found in catalog.
+    """
+    catalog = _load_securities_catalog()
+
+    if security_id not in catalog:
+        available = ", ".join(sorted(catalog.keys()))
+        raise ValueError(
+            f"Security '{security_id}' not found in catalog. Available: {available}"
+        )
+
+    spec_data = catalog[security_id]
+    return BloombergSecuritySpec(
+        security_id=security_id,
+        description=spec_data["description"],
+        bloomberg_ticker=spec_data["bloomberg_ticker"],
+        instrument_type=spec_data["instrument_type"],
+    )
+
+
+def get_bloomberg_ticker(security_id: str) -> str:
+    """
+    Get Bloomberg ticker for a security.
+
+    Parameters
+    ----------
+    security_id : str
+        Internal security identifier (e.g., 'cdx_ig_5y', 'hyg').
+
+    Returns
+    -------
+    str
+        Bloomberg Terminal ticker string.
+
+    Raises
+    ------
+    ValueError
+        If security not found in catalog.
+
+    Examples
+    --------
+    >>> get_bloomberg_ticker("cdx_ig_5y")
+    'CDX IG CDSI GEN 5Y Corp'
+    >>> get_bloomberg_ticker("hyg")
+    'HYG US Equity'
+    """
+    spec = get_security_spec(security_id)
+    return spec.bloomberg_ticker
+
+
+def get_security_from_ticker(bloomberg_ticker: str) -> str:
+    """
+    Reverse lookup: get security ID from Bloomberg ticker.
+
+    Parameters
+    ----------
+    bloomberg_ticker : str
+        Bloomberg Terminal ticker string.
+
+    Returns
+    -------
+    str
+        Internal security identifier.
+
+    Raises
+    ------
+    ValueError
+        If Bloomberg ticker not found in catalog.
+
+    Examples
+    --------
+    >>> get_security_from_ticker("CDX IG CDSI GEN 5Y Corp")
+    'cdx_ig_5y'
+    >>> get_security_from_ticker("HYG US Equity")
+    'hyg'
+    """
+    catalog = _load_securities_catalog()
+
+    # Build reverse lookup
+    for sec_id, spec_data in catalog.items():
+        if spec_data["bloomberg_ticker"] == bloomberg_ticker:
+            return sec_id
+
+    raise ValueError(
+        f"Bloomberg ticker '{bloomberg_ticker}' not found in catalog. "
+        "Ticker may not be configured for use in aponyx."
+    )
+
+
+def list_instrument_types() -> list[str]:
+    """
+    Return list of available instrument types.
+
+    Returns
+    -------
+    list[str]
+        Instrument type identifiers.
+    """
+    catalog = _load_instruments_catalog()
+    return list(catalog.keys())
+
+
+def list_securities(instrument_type: str | None = None) -> list[str]:
+    """
+    Return list of available securities.
+
+    Parameters
+    ----------
+    instrument_type : str or None, default None
+        If provided, filter to securities of this instrument type.
+
+    Returns
+    -------
+    list[str]
+        List of security identifiers.
+    """
+    catalog = _load_securities_catalog()
+
+    if instrument_type is None:
+        return list(catalog.keys())
+
+    return [
+        sec_id
+        for sec_id, spec_data in catalog.items()
+        if spec_data["instrument_type"] == instrument_type
+    ]
+
+
+__all__ = [
+    "BloombergInstrumentSpec",
+    "BloombergSecuritySpec",
+    "get_instrument_spec",
+    "get_security_spec",
+    "get_bloomberg_ticker",
+    "get_security_from_ticker",
+    "list_instrument_types",
+    "list_securities",
+    "validate_bloomberg_registry",
+]

aponyx/data/bloomberg_instruments.json

@@ -0,0 +1,26 @@
+{
+  "cdx": {
+    "description": "CDX credit default swap indices",
+    "bloomberg_fields": ["PX_LAST"],
+    "field_mapping": {
+      "PX_LAST": "spread"
+    },
+    "requires_security_metadata": true
+  },
+  "vix": {
+    "description": "CBOE Volatility Index",
+    "bloomberg_fields": ["PX_LAST"],
+    "field_mapping": {
+      "PX_LAST": "level"
+    },
+    "requires_security_metadata": false
+  },
+  "etf": {
+    "description": "Credit ETFs (high yield and investment grade)",
+    "bloomberg_fields": ["YAS_ISPREAD"],
+    "field_mapping": {
+      "YAS_ISPREAD": "spread"
+    },
+    "requires_security_metadata": true
+  }
+}

aponyx/data/bloomberg_securities.json

@@ -0,0 +1,42 @@
+{
+  "cdx_ig_5y": {
+    "description": "CDX North America Investment Grade 5Y",
+    "bloomberg_ticker": "CDX IG CDSI GEN 5Y Corp",
+    "instrument_type": "cdx"
+  },
+  "cdx_ig_10y": {
+    "description": "CDX North America Investment Grade 10Y",
+    "bloomberg_ticker": "CDX IG CDSI GEN 10Y Corp",
+    "instrument_type": "cdx"
+  },
+  "cdx_hy_5y": {
+    "description": "CDX North America High Yield 5Y",
+    "bloomberg_ticker": "CDX HY CDSI GEN 5Y SPRD Corp",
+    "instrument_type": "cdx"
+  },
+  "itrx_xover_5y": {
+    "description": "iTraxx Europe Crossover 5Y",
+    "bloomberg_ticker": "ITRX XOVER CDSI GEN 5Y Corp",
+    "instrument_type": "cdx"
+  },
+  "itrx_eur_5y": {
+    "description": "iTraxx Europe Main 5Y",
+    "bloomberg_ticker": "ITRX EUR CDSI GEN 5Y Corp",
+    "instrument_type": "cdx"
+  },
+  "hyg": {
+    "description": "iShares iBoxx High Yield Corporate Bond ETF",
+    "bloomberg_ticker": "HYG US Equity",
+    "instrument_type": "etf"
+  },
+  "lqd": {
+    "description": "iShares iBoxx Investment Grade Corporate Bond ETF",
+    "bloomberg_ticker": "LQD US Equity",
+    "instrument_type": "etf"
+  },
+  "vix": {
+    "description": "CBOE Volatility Index",
+    "bloomberg_ticker": "VIX Index",
+    "instrument_type": "vix"
+  }
+}