Metadata-Version: 2.3
Name: aponyx
Version: 0.1.9
Summary: Early-stage research framework for backtesting systematic credit strategies (not for production use)
Keywords: finance,investing,research,backtesting
Author: Stabile Frisur
Author-email: Stabile Frisur <26568863+stabilefrisur@users.noreply.github.com>
License: MIT License
         
         Copyright (c) 2025 Stabile Frisur
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Typing :: Typed
Requires-Dist: pandas>=2.2.0
Requires-Dist: numpy>=2.0.0
Requires-Dist: pyarrow>=17.0.0
Requires-Dist: statsmodels>=0.14.0
Requires-Dist: xbbg>=0.7.0 ; extra == 'bloomberg'
Requires-Dist: pytest>=8.0.0 ; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0 ; extra == 'dev'
Requires-Dist: ruff>=0.6.0 ; extra == 'dev'
Requires-Dist: black>=24.0.0 ; extra == 'dev'
Requires-Dist: mypy>=1.11.0 ; extra == 'dev'
Requires-Dist: pandas-stubs>=2.0.0 ; extra == 'dev'
Requires-Dist: plotly>=5.24.0 ; extra == 'viz'
Requires-Dist: streamlit>=1.39.0 ; extra == 'viz'
Requires-Dist: nbformat>=5.10.0 ; extra == 'viz'
Requires-Dist: ipykernel>=6.29.0 ; extra == 'viz'
Requires-Dist: tabulate>=0.9.0 ; extra == 'viz'
Requires-Dist: jupyter>=1.0.0 ; extra == 'viz'
Requires-Python: >=3.12, <3.13
Project-URL: Changelog, https://github.com/stabilefrisur/aponyx/blob/master/CHANGELOG.md
Project-URL: Documentation, https://github.com/stabilefrisur/aponyx/blob/master/README.md
Project-URL: Homepage, https://github.com/stabilefrisur/aponyx
Project-URL: Issues, https://github.com/stabilefrisur/aponyx/issues
Project-URL: Repository, https://github.com/stabilefrisur/aponyx
Provides-Extra: bloomberg
Provides-Extra: dev
Provides-Extra: viz
Description-Content-Type: text/markdown

# Aponyx

[![PyPI version](https://img.shields.io/pypi/v/aponyx.svg)](https://pypi.org/project/aponyx/)
[![Python 3.12](https://img.shields.io/badge/python-3.12-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

> **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

- **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

## Installation

### From PyPI (Recommended)

```bash
pip install aponyx
```

**Optional dependencies:**

```bash
# 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`](https://docs.astral.sh/uv/):

```bash
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. Download `blpapi` from Bloomberg's API Library
2. Install: `pip install path/to/blpapi-*.whl`
3. Install Bloomberg extra: `pip install aponyx[bloomberg]`

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

## Quick Start

```python
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

# Load validated market data
cdx_df = fetch_cdx(FileSource("data/raw/cdx_data.parquet"), security="cdx_ig_5y")
etf_df = fetch_etf(FileSource("data/raw/etf_data.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)
from aponyx.evaluation import evaluate_signal_suitability, SuitabilityConfig
suitability_config = SuitabilityConfig(rolling_window=252)  # ~1 year daily data
result = evaluate_signal_suitability(signal, cdx_df["spread"], suitability_config)
print(f"Suitability score: {result.composite_score:.2f}")
print(f"Stability: {result.sign_consistency_ratio:.1%} sign consistency, CV={result.beta_cv:.3f}")

# 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"Max Drawdown: ${metrics.max_drawdown:,.0f}")
print(f"Hit Rate: {metrics.hit_rate:.2%}")
```

**Bloomberg Terminal alternative:**

```python
from aponyx.data import BloombergSource

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

## Architecture

Aponyx follows a **layered architecture** with clean separation of concerns:

| Layer | Purpose | Key Modules |
|-------|---------|-------------|
| **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` |

### Research Workflow

```
Raw Data (Parquet/CSV/Bloomberg)
    ↓
Data Layer (load, validate, transform)
    ↓
Models Layer (signal computation)
    ↓
Evaluation Layer (signal-product suitability)
    ↓
Backtest Layer (execution simulation)
    ↓
Evaluation Layer (performance metrics & analysis)
    ↓
Visualization Layer (charts)
    ↓
Persistence Layer (results)
```

## Research Notebooks

Complete workflow notebooks are included in the package for end-to-end research workflows.

**Access installed notebooks:**

```python
# Locate notebook directory
from pathlib import Path
import aponyx
notebooks_dir = Path(aponyx.__file__).parent / "notebooks"
print(notebooks_dir)
```

**Workflow notebooks:**

| Notebook | Description |
|----------|-------------|
| `01_data_download.ipynb` | Download market data from Bloomberg Terminal |
| `02_signal_computation.ipynb` | Generate signals using SignalRegistry |
| `03_suitability_evaluation.ipynb` | Pre-backtest signal screening and evaluation |
| `04_backtest_execution.ipynb` | Execute backtests and save raw results |
| `05_performance_analysis.ipynb` | Comprehensive post-backtest performance analysis |
| `06_single_signal_template.ipynb` | End-to-end single-signal research template |

> **Note:** Notebook 01 requires Bloomberg Terminal. Notebooks 02-06 work with any data source (file-based or Bloomberg).

**Usage:**

```bash
# Copy notebooks to your workspace
pip install aponyx[viz]  # Install with notebook dependencies
python -c "from pathlib import Path; import aponyx, shutil; src = Path(aponyx.__file__).parent / 'notebooks'; shutil.copytree(src, 'notebooks')"
jupyter notebook notebooks/
```

Notebooks demonstrate the complete systematic research workflow from data acquisition through performance analysis.

## Documentation

Documentation is **included with the package** and available after installation:

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

**Available documentation:**

**Strategy & Research:**
- [`cdx_overlay_strategy.md`](https://github.com/stabilefrisur/aponyx/blob/master/src/aponyx/docs/cdx_overlay_strategy.md) - Investment thesis and pilot implementation
- [`signal_registry_usage.md`](https://github.com/stabilefrisur/aponyx/blob/master/src/aponyx/docs/signal_registry_usage.md) - Signal management workflow
- [`signal_suitability_design.md`](https://github.com/stabilefrisur/aponyx/blob/master/src/aponyx/docs/signal_suitability_design.md) - Pre-backtest evaluation framework
- [`performance_evaluation_design.md`](https://github.com/stabilefrisur/aponyx/blob/master/src/aponyx/docs/performance_evaluation_design.md) - Post-backtest analysis framework

**Architecture & Design:**
- [`governance_design.md`](https://github.com/stabilefrisur/aponyx/blob/master/src/aponyx/docs/governance_design.md) - Registry, catalog, and config patterns
- [`caching_design.md`](https://github.com/stabilefrisur/aponyx/blob/master/src/aponyx/docs/caching_design.md) - Cache layer architecture
- [`visualization_design.md`](https://github.com/stabilefrisur/aponyx/blob/master/src/aponyx/docs/visualization_design.md) - Chart architecture and patterns
- [`logging_design.md`](https://github.com/stabilefrisur/aponyx/blob/master/src/aponyx/docs/logging_design.md) - Logging conventions and metadata

**Development:**
- [`python_guidelines.md`](https://github.com/stabilefrisur/aponyx/blob/master/src/aponyx/docs/python_guidelines.md) - Code standards and best practices
- [`adding_data_providers.md`](https://github.com/stabilefrisur/aponyx/blob/master/src/aponyx/docs/adding_data_providers.md) - Provider extension guide
- [`documentation_structure.md`](https://github.com/stabilefrisur/aponyx/blob/master/src/aponyx/docs/documentation_structure.md) - Documentation organization principles

**All documentation** is included in the package and also available on [GitHub](https://github.com/stabilefrisur/aponyx/tree/master/src/aponyx/docs).

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

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

### Code Quality

```bash
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](CONTRIBUTING.md) for technical guidelines if you'd like to contribute.

## Security

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

## License

MIT License - see [LICENSE](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**  
**Version**: 0.1.9  
**Last Updated**: November 15, 2025