aponyx 0.1.14

Early-stage research framework for backtesting systematic credit strategies (not for production use)

Aponyx

Early-stage research framework — Not for production use

A modular Python framework for developing and backtesting systematic credit strategies.

Type-safe, reproducible research environment for tactical fixed-income strategies with clean separation between strategy logic, data infrastructure, and backtesting workflows.

Key Features

• CLI orchestrator for automated end-to-end research workflows (run, report, list, clean)
• Workflow engine with smart caching and dependency tracking across pipeline steps
• Type-safe data loading with schema validation (Parquet, CSV, Bloomberg Terminal)
• Modular signal framework with composable transformations and registry management
• Deterministic backtesting with transaction cost modeling and comprehensive metrics
• Interactive visualization with Plotly charts (equity curves, signals, drawdown)
• File-based persistence with metadata tracking and versioning
• Strategy governance with centralized registry and configuration management
• Multi-format reporting with console, markdown, and HTML output

Installation

From PyPI (Recommended)

pip install aponyx

Optional dependencies:

# Visualization (Plotly, Streamlit)
pip install aponyx[viz]

# Bloomberg Terminal support (requires manual blpapi install)
pip install aponyx[bloomberg]

# Development tools
pip install aponyx[dev]

From Source

Requires Python 3.12 and uv:

git clone https://github.com/stabilefrisur/aponyx.git
cd aponyx
uv sync                    # Install dependencies
uv sync --extra viz        # Include visualization

Bloomberg Terminal Setup (Optional)

Note: Bloomberg data loading requires an active Terminal session and manual blpapi installation.

1. Install blpapi by following the instructions here: Bloomberg API Library
2. Install Bloomberg extra: pip install aponyx[bloomberg]

File-based data loading (FileSource) works without Bloomberg dependencies.

Quick Start

1. Run Analysis

Option A: Use CLI (Recommended)

aponyx run --signal cdx_etf_basis --strategy balanced

Option B: Python API

from aponyx.data import fetch_cdx, fetch_etf, FileSource
from aponyx.models import compute_cdx_etf_basis, SignalConfig
from aponyx.backtest import run_backtest, BacktestConfig
from aponyx.evaluation.performance import compute_all_metrics
from aponyx.evaluation.suitability import evaluate_signal_suitability, SuitabilityConfig

# Load validated market data
# Note: After generating synthetic data, find actual filenames in data/raw/synthetic/
# Files use hash-based naming: cdx_ig_5y_<hash>.parquet, hyg_<hash>.parquet
cdx_df = fetch_cdx(FileSource("data/raw/synthetic/cdx_ig_5y_<hash>.parquet"), security="cdx_ig_5y")
etf_df = fetch_etf(FileSource("data/raw/synthetic/hyg_<hash>.parquet"), security="hyg")

# Generate signal with configuration
signal_config = SignalConfig(lookback=20, min_periods=10)
signal = compute_cdx_etf_basis(cdx_df, etf_df, signal_config)

# Evaluate signal-product suitability (optional pre-backtest assessment)
suitability_config = SuitabilityConfig(rolling_window=252)  # ~1 year daily data
suitability = evaluate_signal_suitability(signal, cdx_df["spread"], suitability_config)
print(f"Suitability: {suitability.composite_score:.2f} ({suitability.decision})")

# Run backtest with transaction costs
backtest_config = BacktestConfig(
    entry_threshold=1.5,
    exit_threshold=0.75,
    transaction_cost_bps=1.0
)
results = run_backtest(signal, cdx_df["spread"], backtest_config)

# Compute comprehensive performance metrics
metrics = compute_all_metrics(results.pnl, results.positions)

# Analyze results
print(f"Sharpe Ratio: {metrics.sharpe_ratio:.2f}")
print(f"Total Return: ${metrics.total_return:,.0f}")
print(f"Win Rate: {metrics.hit_rate:.1%}")

Bloomberg Terminal alternative:

from aponyx.data import BloombergSource

source = BloombergSource()
cdx_df = fetch_cdx(source, security="cdx_ig_5y")

Command-Line Interface

Aponyx provides a complete CLI orchestrator for running research workflows from data loading through performance analysis.

Get started:

aponyx --help  # or aponyx -h

Run Complete Workflow

# Execute full 6-step workflow with synthetic data
aponyx run --signal spread_momentum --strategy balanced

# Use Bloomberg data (requires active Terminal session)
aponyx run --signal spread_momentum --strategy balanced --data bloomberg

# Custom security mapping (override signal defaults)
aponyx run --signal cdx_etf_basis --strategy balanced --securities cdx:cdx_hy_5y,etf:hyg

# Run specific steps only
aponyx run --signal spread_momentum --strategy balanced --steps signal,backtest,performance

# Force re-run (skip cache, regenerate all outputs)
aponyx run --signal spread_momentum --strategy balanced --force

# Custom product
aponyx run --signal cdx_etf_basis --strategy aggressive --product cdx_hy_5y

Workflow steps: data → signal → suitability → backtest → performance → visualization

Generate Reports

# Console output with formatted tables
aponyx report --signal spread_momentum --strategy balanced

# Markdown file (default location: reports/)
aponyx report --signal spread_momentum --strategy balanced --format markdown

# HTML file with styled formatting
aponyx report --signal spread_momentum --strategy balanced --format html --output custom_report.html

Reports aggregate suitability evaluation and performance analysis with comprehensive metrics and visualizations.

List Available Items

aponyx list signals      # View signal catalog
aponyx list strategies   # View strategy catalog
aponyx list datasets     # View data registry

Clean Workflow Cache

# Remove cached workflow outputs for specific signal-strategy
aponyx clean --signal spread_momentum --strategy balanced

# Clean all cached workflows
aponyx clean --all

Using Configuration Files

Create workflow.yaml:

signal: spread_momentum
strategy: balanced
product: cdx_ig_5y
data: synthetic
security_mapping:
  cdx: cdx_ig_5y
  etf: lqd
steps:
  - signal
  - backtest
  - performance
force: false

Run with config:

aponyx run --config workflow.yaml

Output format:

Signal: spread_momentum (cdx:cdx_ig_5y)
Strategy: balanced
Product: cdx_ig_5y
Data: synthetic
Steps: all
Force re-run: False

Completed 6 steps in 15.2s
Results: data/workflows/spread_momentum_balanced_20251123_143230/

Benefits:

• Reproducible workflows via YAML configuration
• Smart caching skips completed steps automatically
• Dependency tracking ensures correct execution order
• Error handling with partial result preservation
• Progress logging with step completion times (WARNING level default, use -v for DEBUG)

See CLI Guide for complete documentation and advanced usage.

Architecture

Aponyx follows a layered architecture with clean separation of concerns:

Layer	Purpose	Key Modules
CLI	Command-line orchestration and user interface	aponyx run, aponyx report, aponyx list, aponyx clean
Workflows	Pipeline orchestration with dependency tracking	WorkflowEngine, WorkflowConfig, StepRegistry, concrete steps
Reporting	Multi-format report generation	generate_report, console/markdown/HTML formatters
Data	Load, validate, transform market data	fetch_cdx, fetch_vix, fetch_etf, apply_transform, FileSource, BloombergSource
Models	Generate signals for independent evaluation	compute_cdx_etf_basis, compute_cdx_vix_gap, SignalRegistry
Evaluation	Pre-backtest screening (rolling window stability) and post-backtest analysis	evaluate_signal_suitability, analyze_backtest_performance, PerformanceRegistry
Backtest	Simulate execution and generate P&L	run_backtest, BacktestConfig, StrategyRegistry
Visualization	Interactive charts and dashboards	plot_equity_curve, plot_signal, plot_drawdown
Persistence	Save/load data with metadata registry	save_parquet, load_parquet, DataRegistry

Data Storage

data/
  raw/              # Original source data (permanent)
    bloomberg/      # Bloomberg Terminal downloads
    synthetic/      # Synthetic test data
  cache/            # Temporary performance cache (security-based naming: {security}_{hash}.parquet)
  workflows/        # Timestamped workflow results ({signal}_{strategy}_{timestamp}/)
  .registries/      # Runtime metadata (not in git)

Research Workflow

CLI-Orchestrated Pipeline:

CLI Command (aponyx run)
    ↓
Workflow Engine (dependency tracking + caching)
    ↓
[Step 1] Data Layer (load, validate, transform)
    ↓
[Step 2] Models Layer (signal computation)
    ↓
[Step 3] Evaluation Layer (signal-product suitability)
    ↓
[Step 4] Backtest Layer (execution simulation)
    ↓
[Step 5] Evaluation Layer (performance metrics & analysis)
    ↓
[Step 6] Visualization Layer (charts)
    ↓
Reporting Layer (multi-format output)
    ↓
Persistence Layer (results + metadata)

Key Features:

• Smart caching skips completed steps
• Dependency validation ensures correct execution order
• YAML config support for reproducible workflows
• Error handling preserves partial results

Documentation

Documentation is included with the package and available after installation:

# Access docs programmatically
from aponyx.docs import get_docs_dir
docs_path = get_docs_dir()
print(docs_path)  # Path to installed documentation

Getting Started

Document	Description
cli_guide.md	Complete CLI orchestrator reference and advanced usage
cdx_overlay_strategy.md	Investment thesis and pilot signal implementations

Research Workflow

Document	Description
signal_registry_usage.md	Signal management and catalog workflow
signal_suitability_design.md	Pre-backtest signal-product evaluation framework
performance_evaluation_design.md	Post-backtest performance analysis framework

System Architecture

Document	Description
governance_design.md	Registry, catalog, and config governance patterns
visualization_design.md	Chart architecture and Plotly/Streamlit patterns
logging_design.md	Logging conventions and metadata tracking

Development Reference

Document	Description
python_guidelines.md	Code standards, type hints, and best practices
adding_data_providers.md	Data provider extension guide

All documentation is included in the package and available on GitHub.

What's Included

Three pilot signals for CDX overlay strategies:

1. CDX-ETF Basis - Flow-driven mispricing from cash-derivative basis
2. CDX-VIX Gap - Cross-asset risk sentiment divergence
3. Spread Momentum - Short-term continuation in credit spreads

Core capabilities: Type-safe data loading • Signal registry • Pre/post-backtest evaluation • Deterministic backtesting • Interactive visualizations • Comprehensive testing (>90% coverage)

Development

Running Tests

pytest                              # All tests
pytest --cov=aponyx                # With coverage
pytest tests/models/                # Specific module

Code Quality

black src/ tests/                   # Format code
ruff check src/ tests/              # Lint
mypy src/                          # Type check

All tools are configured in pyproject.toml with project-specific settings.

Design Philosophy

Core Principles

1. Modularity - Clean separation between data, models, backtest, and infrastructure
2. Reproducibility - Deterministic outputs with seed control and metadata logging
3. Type Safety - Strict type hints and runtime validation throughout
4. Simplicity - Prefer functions over classes, explicit over implicit
5. Transparency - Clear separation between strategy logic and execution
6. No Legacy Support - Breaking changes without deprecation warnings; always use latest patterns

Signal Convention

All signals follow a consistent sign convention for interpretability:

• Positive values → Long credit risk (buy CDX = sell protection)
• Negative values → Short credit risk (sell CDX = buy protection)

This ensures clarity when evaluating signals independently or combining them in future research.

Requirements

• Python 3.12 (no backward compatibility with 3.11 or earlier)
• Modern type syntax (str | None, not Optional[str])
• Optional: Bloomberg Terminal with blpapi for live data

Breaking changes: This is an early-stage project under active development. Breaking changes may occur between versions without deprecation warnings or backward compatibility.

Contributing

This is an early-stage personal research project. See CONTRIBUTING.md for technical guidelines if you'd like to contribute.

Security

Security issues addressed on a best-effort basis. See SECURITY.md for reporting guidelines and scope.

License

MIT License - see LICENSE for details.

Links

• PyPI: https://pypi.org/project/aponyx/
• Repository: https://github.com/stabilefrisur/aponyx
• Issues: https://github.com/stabilefrisur/aponyx/issues
• Changelog: https://github.com/stabilefrisur/aponyx/blob/master/CHANGELOG.md

---

Maintained by stabilefrisur
Last Updated: November 23, 2025