aponyx 0.1.18__py3-none-any.whl

aponyx/__init__.py

@@ -0,0 +1,14 @@
+"""
+Aponyx - Systematic Macro Credit Strategy Framework.
+
+A modular Python framework for developing and backtesting systematic credit strategies.
+"""
+
+from importlib.metadata import version
+
+__version__ = version("aponyx")
+
+
+def hello() -> str:
+    """Return greeting message."""
+    return "Hello from aponyx!"

aponyx/backtest/__init__.py

@@ -0,0 +1,31 @@
+"""
+Backtesting engine for CDX overlay strategy.
+
+This module provides a lightweight backtesting framework optimized for
+credit index strategies. The design prioritizes transparency and extensibility,
+with clean interfaces that can wrap more powerful libraries later.
+
+Core Components
+---------------
+- engine: Position generation and P&L simulation
+- config: Backtest parameters and constraints
+- protocols: Abstract interfaces for extensibility
+- registry: Strategy catalog management
+
+Note: Performance metrics have been moved to aponyx.evaluation.performance
+"""
+
+from .config import BacktestConfig
+from .engine import run_backtest, BacktestResult
+from .protocols import BacktestEngine, PerformanceCalculator
+from .registry import StrategyRegistry, StrategyMetadata
+
+__all__ = [
+    "BacktestConfig",
+    "run_backtest",
+    "BacktestResult",
+    "BacktestEngine",
+    "PerformanceCalculator",
+    "StrategyRegistry",
+    "StrategyMetadata",
+]

aponyx/backtest/adapters.py

@@ -0,0 +1,77 @@
+"""
+Protocol interfaces for third-party backtest library integration.
+
+Defines protocols for backtest engines and portfolio simulators,
+enabling future integration with vectorbt, bt, or other backtesting
+frameworks without modifying core code.
+"""
+
+from typing import Protocol
+
+import pandas as pd
+
+from .config import BacktestConfig
+from .engine import BacktestResult
+
+
+class BacktestEngine(Protocol):
+    """
+    Protocol for backtest execution engines.
+
+    Defines interface for running backtests from signal data.
+    Enables integration with third-party libraries like vectorbt
+    or custom simulation engines.
+
+    Examples
+    --------
+    >>> class VectorBTAdapter:
+    ...     def run(
+    ...         self,
+    ...         signal: pd.Series,
+    ...         spread: pd.Series,
+    ...         config: BacktestConfig | None = None,
+    ...     ) -> BacktestResult:
+    ...         import vectorbt as vbt
+    ...         entries = signal > config.entry_threshold
+    ...         exits = signal.abs() < config.exit_threshold
+    ...         portfolio = vbt.Portfolio.from_signals(
+    ...             close=spread,
+    ...             entries=entries,
+    ...             exits=exits,
+    ...             size=config.position_size,
+    ...             fees=config.transaction_cost_bps / 10000,
+    ...         )
+    ...         # Convert vectorbt results to BacktestResult
+    ...         return BacktestResult(...)
+    """
+
+    def run(
+        self,
+        signal: pd.Series,
+        spread: pd.Series,
+        config: BacktestConfig | None = None,
+    ) -> BacktestResult:
+        """
+        Execute backtest from signal data.
+
+        Parameters
+        ----------
+        signal : pd.Series
+            Trading signal with DatetimeIndex.
+        spread : pd.Series
+            Market spread data with DatetimeIndex.
+        config : BacktestConfig | None
+            Backtest configuration parameters.
+
+        Returns
+        -------
+        BacktestResult
+            Standardized backtest results.
+        """
+        ...
+
+
+# Future adapter implementations:
+# - VectorBTBacktestEngine
+# - ZiplineBacktestEngine
+# - CustomEventDrivenEngine

aponyx/backtest/config.py

@@ -0,0 +1,84 @@
+"""
+Configuration for backtest engine.
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class BacktestConfig:
+    """
+    Backtest parameters and trading constraints.
+
+    Attributes
+    ----------
+    position_size_mm : float
+        Notional position size in millions (e.g., 10.0 = $10MM).
+    sizing_mode : str
+        Position sizing mode: 'binary' (full position for any non-zero signal)
+        or 'proportional' (scaled by signal magnitude).
+    stop_loss_pct : float | None
+        Stop loss as percentage of initial position value. None to disable.
+    take_profit_pct : float | None
+        Take profit as percentage of initial position value. None to disable.
+    max_holding_days : int | None
+        Maximum days to hold a position before forced exit. None for no limit.
+    transaction_cost_bps : float
+        Round-trip transaction cost in basis points.
+        Typical CDX costs: 0.5-2.0 bps depending on liquidity.
+    dv01_per_million : float
+        DV01 per $1MM notional for risk calculations.
+        CDX IG 5Y with ~4.75 year duration: ~475.
+    signal_lag : int
+        Number of days to lag the signal before execution.
+        0 = same-day execution (idealized), 1 = next-day execution (realistic).
+        Helps prevent look-ahead bias in backtests.
+        Default is 1 for realistic execution timing.
+
+    Notes
+    -----
+    - Signal-based triggers: non-zero signal = enter, zero signal = exit.
+    - Proportional sizing: position scaled by signal magnitude (default).
+    - Binary sizing: full position for any non-zero signal (use as runtime override).
+    - PnL-based exits (stop loss, take profit) trigger cooldown before re-entry.
+    - Transaction costs are applied symmetrically on entry and exit.
+    - signal_lag models realistic execution timing and prevents look-ahead bias.
+    """
+
+    position_size_mm: float
+    sizing_mode: str
+    stop_loss_pct: float | None
+    take_profit_pct: float | None
+    max_holding_days: int | None
+    transaction_cost_bps: float
+    dv01_per_million: float
+    signal_lag: int = 1
+
+    def __post_init__(self) -> None:
+        """Validate configuration parameters."""
+        if self.position_size_mm <= 0:
+            raise ValueError(
+                f"position_size_mm must be positive, got {self.position_size_mm}"
+            )
+        if self.sizing_mode not in {"binary", "proportional"}:
+            raise ValueError(
+                f"sizing_mode must be 'binary' or 'proportional', got '{self.sizing_mode}'"
+            )
+        if self.stop_loss_pct is not None and not (0 < self.stop_loss_pct <= 100):
+            raise ValueError(
+                f"stop_loss_pct must be in (0, 100], got {self.stop_loss_pct}"
+            )
+        if self.take_profit_pct is not None and not (0 < self.take_profit_pct <= 100):
+            raise ValueError(
+                f"take_profit_pct must be in (0, 100], got {self.take_profit_pct}"
+            )
+        if self.max_holding_days is not None and self.max_holding_days <= 0:
+            raise ValueError(
+                f"max_holding_days must be positive, got {self.max_holding_days}"
+            )
+        if self.transaction_cost_bps < 0:
+            raise ValueError(
+                f"transaction_cost_bps must be non-negative, got {self.transaction_cost_bps}"
+            )
+        if self.signal_lag < 0:
+            raise ValueError(f"signal_lag must be non-negative, got {self.signal_lag}")