aponyx 0.1.15

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 with YAML Config (Recommended)

Create a workflow configuration file:

# workflow.yaml
label: my_test
signal: cdx_etf_basis
product: cdx_ig_5y
strategy: balanced

Run the workflow:

aponyx run workflow.yaml
# Or use example configs
aponyx run examples/workflow_minimal.yaml

Option B: Python API

from aponyx.data import fetch_cdx, fetch_etf, FileSource
from aponyx.models import (
    IndicatorRegistry, TransformationRegistry, SignalRegistry,
    compute_indicator, compose_signal
)
from aponyx.backtest import run_backtest, BacktestConfig
from aponyx.evaluation.performance import compute_all_metrics
from aponyx.evaluation.suitability import evaluate_signal_suitability, SuitabilityConfig
from aponyx.config import INDICATOR_CATALOG_PATH, TRANSFORMATION_CATALOG_PATH, SIGNAL_CATALOG_PATH

# 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")

# SIGNAL COMPOSITION: Every signal is ALWAYS composed from indicator + transformation
# 1. Indicator = economically interpretable metric (e.g., CDX-ETF basis in bps)
# 2. Transformation = signal processing (e.g., z-score normalization)
# This separation enables reuse and runtime experimentation

market_data = {"cdx": cdx_df, "etf": etf_df}
indicator_registry = IndicatorRegistry(INDICATOR_CATALOG_PATH)
transformation_registry = TransformationRegistry(TRANSFORMATION_CATALOG_PATH)
signal_registry = SignalRegistry(SIGNAL_CATALOG_PATH)

# Compose signal: indicator (cdx_etf_spread_diff) + transformation (z_score_20d)
signal = compose_signal(
    signal_metadata=signal_registry.get_metadata("cdx_etf_basis"),
    market_data=market_data,
    indicator_registry=indicator_registry,
    transformation_registry=transformation_registry
)

# 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

All workflows are configured via YAML files. Create a config file with required fields:

Minimal configuration (workflow.yaml):

label: minimal_test
signal: spread_momentum
product: cdx_ig_5y
strategy: balanced

Complete configuration with all options:

label: complete_test
signal: cdx_etf_basis
product: cdx_ig_5y
strategy: balanced

# Optional overrides
indicator: cdx_etf_spread_diff
transformation: z_score_20d
securities:
  cdx: cdx_ig_5y
  etf: lqd
data: synthetic
steps: [data, signal, suitability, backtest, performance, visualization]
force: true

Run workflows:

# Execute full 6-step workflow with minimal config
aponyx run workflow.yaml

# Use example configs
aponyx run examples/workflow_minimal.yaml
aponyx run examples/workflow_complete.yaml

Available YAML fields:

Field	Type	Required	Default	Description
label	string	✓	-	Workflow label (lowercase letters, numbers, underscores; must start with letter)
signal	string	✓	-	Signal name from signal_catalog.json
product	string	✓	-	Product identifier (e.g., "cdx_ig_5y")
strategy	string	✓	-	Strategy name from strategy_catalog.json
indicator	string		from signal	Override indicator computation
transformation	string		from signal	Override transformation
securities	dict		from indicator	Custom security mapping
data	string		"synthetic"	Data source (synthetic, file, bloomberg)
steps	list		all	Specific steps to execute
force	boolean		false	Force re-run (skip cache)

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

Generate Reports

# Console output with formatted tables (by label)
aponyx report minimal_test

# By numeric index (0 = most recent, ephemeral)
aponyx report 0

# Markdown file (default location: reports/)
aponyx report minimal_test --format markdown

# HTML file with styled formatting
aponyx report minimal_test --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
aponyx list workflows    # View workflow results (sorted by timestamp, newest first)
aponyx list workflows --label minimal_test  # Filter workflows by label

Clean Workflow Cache

# Preview workflow cleanup
aponyx clean --workflows --all --dry-run

# Clean workflows older than 30 days
aponyx clean --workflows --older-than 30d

# Clean specific label's workflows
aponyx clean --workflows --label minimal_test --older-than 7d

Using Configuration Files

Create workflow.yaml:

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

Run with config:

aponyx run workflow.yaml

Output format:

=== Workflow Configuration ===
Label:           minimal_test [config]
Product:         cdx_ig_5y [config]
Signal:          spread_momentum [config]
Indicator:       spread_momentum_5d [from signal]
Securities:      cdx:cdx_ig_5y [from indicator]
Transformation:  volatility_adjust_20d [from signal]
Strategy:        balanced [config]
Data:            synthetic [default]
Steps:           all [default]
Force re-run:    False [default]
==============================

Completed 6 steps in 15.2s
Skipped 0 cached steps
Results: data/workflows/minimal_test_20251202_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	Indicators, transformations, and signal composition	IndicatorRegistry, TransformationRegistry, compute_indicator, compose_signal
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 (indicator computation + signal composition)
    ↓
[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: December 2, 2025