aponyx 0.1.0__tar.gz

aponyx-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+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.

aponyx-0.1.0/PKG-INFO

@@ -0,0 +1,271 @@
+Metadata-Version: 2.3
+Name: aponyx
+Version: 0.1.0
+Summary: Systematic research framework for tactical credit strategies
+Keywords: finance,investing
+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 :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+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: xbbg>=0.7.0
+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-Python: >=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: 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.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A modular Python framework for developing and backtesting systematic credit strategies.
+
+> **⚠️ Bloomberg Terminal Required**: Data loading via `BloombergSource` requires an active Bloomberg Terminal session. File-based alternatives (`FileSource`) are also supported.
+
+## Quick Start
+
+### Installation from PyPI
+
+```bash
+pip install aponyx
+
+# Optional: visualization dependencies
+pip install aponyx[viz]
+```
+
+### Installation from Source
+
+Requires **Python 3.13+** and [`uv`](https://docs.astral.sh/uv/) for environment management.
+
+```bash
+# Clone repository
+git clone https://github.com/stabilefrisur/aponyx.git
+cd aponyx
+
+# Create virtual environment with uv
+uv venv
+source .venv/Scripts/activate  # Windows: .venv\Scripts\activate
+
+# Install dependencies
+uv sync
+
+# Install visualization dependencies (optional)
+uv sync --extra viz
+
+# Run examples
+uv run python examples/backtest_demo.py
+```
+
+### Basic Usage
+
+```python
+from aponyx.data import fetch_cdx, fetch_etf, FileSource, BloombergSource
+from aponyx.models import compute_cdx_etf_basis, SignalConfig
+from aponyx.backtest import run_backtest, BacktestConfig
+
+# Load market data with validation (file-based)
+cdx_df = fetch_cdx(FileSource("data/raw/cdx_data.parquet"), index_name="CDX_IG_5Y")
+etf_df = fetch_etf(FileSource("data/raw/etf_data.parquet"), ticker="HYG")
+
+# Or use Bloomberg Terminal (requires active session and xbbg package)
+# source = BloombergSource()
+# cdx_df = fetch_cdx(source, index_name="CDX_IG", tenor="5Y")
+# etf_df = fetch_etf(source, ticker="HYG")
+
+# Generate signal
+signal_config = SignalConfig(lookback=20, min_periods=10)
+signal = compute_cdx_etf_basis(cdx_df, etf_df, signal_config)
+
+# Run backtest
+backtest_config = BacktestConfig(entry_threshold=1.5, exit_threshold=0.75)
+results = run_backtest(signal, cdx_df["spread"], backtest_config)
+print(f"Sharpe Ratio: {results.metrics['sharpe_ratio']:.2f}")
+```
+
+## Project Structure
+
+```
+aponyx/
+├── src/aponyx/       # Core framework
+│   ├── data/              # Data loading, validation, transformation
+│   ├── models/            # Signal generation for credit strategies
+│   ├── backtest/          # Backtesting engine and metrics
+│   ├── visualization/     # Plotly charts and Streamlit dashboard
+│   ├── persistence/       # Parquet/JSON I/O and registry
+│   └── config/            # Configuration and constants
+├── examples/              # Runnable demonstrations
+├── tests/                 # Unit tests
+└── docs/                  # Architecture and design docs
+```
+
+### Key Layers
+
+| Layer | Purpose | Entry Point |
+|-------|---------|-------------|
+| **Data** | Load, validate, transform market data | `aponyx.data` |
+| **Models** | Generate signals for independent evaluation | `aponyx.models` |
+| **Backtest** | Simulate execution and compute metrics | `aponyx.backtest` |
+| **Visualization** | Interactive charts and dashboards | `aponyx.visualization` |
+| **Persistence** | Save/load data with metadata registry | `aponyx.persistence` |
+
+## Documentation
+
+### Getting Started
+- **[Python Guidelines](docs/python_guidelines.md)** - Code standards and best practices
+- **[Examples](examples/)** - Runnable demos for each layer
+
+### Strategy & Architecture
+- **[CDX Overlay Strategy](docs/cdx_overlay_strategy.md)** - Investment thesis and pilot implementation
+- **[Documentation Structure](docs/documentation_structure.md)** - Single source of truth principles
+
+### Design Guides
+- **[Logging Design](docs/logging_design.md)** - Logging conventions and metadata tracking
+- **[Signal Registry Usage](docs/signal_registry_usage.md)** - Signal management and research workflow
+- **[Visualization Design](docs/visualization_design.md)** - Chart architecture and integration patterns
+- **[Caching Design](docs/caching_design.md)** - Cache layer architecture and usage
+- **[Adding Data Providers](docs/adding_data_providers.md)** - Provider extension guide
+
+## Features
+
+✅ **Type-safe data loading** with schema validation  
+✅ **Modular signal framework** with composable transformations  
+✅ **Deterministic backtesting** with transaction cost modeling  
+✅ **Interactive visualization** with Plotly charts (equity, signals, drawdown)  
+✅ **Parquet-based persistence** with JSON metadata registry  
+✅ **Comprehensive logging** with run metadata tracking  
+✅ **Bloomberg Terminal integration** via xbbg wrapper (included by default, requires active Terminal session)
+
+**Planned Features:**
+- 🔜 Streamlit dashboard (stub exists, not yet implemented)
+- 🔜 Advanced attribution charts (stubs with NotImplementedError)
+
+## Development
+
+### Running Tests
+
+```bash
+# All tests
+uv run pytest
+
+# With coverage
+uv run pytest --cov=aponyx --cov-report=term-missing
+
+# Specific module
+uv run pytest tests/models/
+```
+
+### Code Quality
+
+```bash
+# Format code
+uv run black src/ tests/
+
+# Lint
+uv run ruff check src/ tests/
+
+# Type check
+uv run mypy src/
+```
+
+### Examples
+
+Each example demonstrates a specific layer with synthetic data:
+
+```bash
+uv run python examples/data_demo.py          # Data loading and transformation
+uv run python examples/models_demo.py        # Signal generation
+uv run python examples/backtest_demo.py      # Complete backtest workflow
+uv run python examples/visualization_demo.py # Interactive charts (requires viz extra)
+uv run python examples/persistence_demo.py   # Data I/O and registry
+```
+
+## Design Principles
+
+1. **Modularity** - Separate data, models, backtest, and persistence layers
+2. **Reproducibility** - Deterministic outputs with seed control and metadata logging
+3. **Type safety** - Strict type hints and runtime validation
+4. **Simplicity** - Prefer functions over classes, explicit over implicit
+5. **Transparency** - Clear separation between strategy logic and infrastructure
+
+## Architecture Notes
+
+### Signal Convention
+
+All model signals follow a **consistent sign convention**:
+- **Positive values** → Long credit risk (buy CDX / sell protection)
+- **Negative values** → Short credit risk (sell CDX / buy protection)
+
+This convention ensures clear interpretation when evaluating signals individually
+or when combining signals in future experiments.
+
+### Data Flow
+
+```
+Raw Data (Parquet/CSV)
+    ↓
+Data Layer (load, validate, transform)
+    ↓
+Models Layer (signal computation)
+    ↓
+Backtest Layer (simulation, metrics)
+    ↓
+Persistence Layer (save results, metadata)
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Contributing
+
+This is a research project under active development. See [Python Guidelines](docs/python_guidelines.md) for code standards.
+
+---
+
+**Maintained by stabilefrisur**  
+Version 0.1.0 | Last Updated: October 31, 2025

aponyx-0.1.0/README.md

@@ -0,0 +1,212 @@
+# Aponyx
+
+[![PyPI version](https://img.shields.io/pypi/v/aponyx.svg)](https://pypi.org/project/aponyx/)
+[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A modular Python framework for developing and backtesting systematic credit strategies.
+
+> **⚠️ Bloomberg Terminal Required**: Data loading via `BloombergSource` requires an active Bloomberg Terminal session. File-based alternatives (`FileSource`) are also supported.
+
+## Quick Start
+
+### Installation from PyPI
+
+```bash
+pip install aponyx
+
+# Optional: visualization dependencies
+pip install aponyx[viz]
+```
+
+### Installation from Source
+
+Requires **Python 3.13+** and [`uv`](https://docs.astral.sh/uv/) for environment management.
+
+```bash
+# Clone repository
+git clone https://github.com/stabilefrisur/aponyx.git
+cd aponyx
+
+# Create virtual environment with uv
+uv venv
+source .venv/Scripts/activate  # Windows: .venv\Scripts\activate
+
+# Install dependencies
+uv sync
+
+# Install visualization dependencies (optional)
+uv sync --extra viz
+
+# Run examples
+uv run python examples/backtest_demo.py
+```
+
+### Basic Usage
+
+```python
+from aponyx.data import fetch_cdx, fetch_etf, FileSource, BloombergSource
+from aponyx.models import compute_cdx_etf_basis, SignalConfig
+from aponyx.backtest import run_backtest, BacktestConfig
+
+# Load market data with validation (file-based)
+cdx_df = fetch_cdx(FileSource("data/raw/cdx_data.parquet"), index_name="CDX_IG_5Y")
+etf_df = fetch_etf(FileSource("data/raw/etf_data.parquet"), ticker="HYG")
+
+# Or use Bloomberg Terminal (requires active session and xbbg package)
+# source = BloombergSource()
+# cdx_df = fetch_cdx(source, index_name="CDX_IG", tenor="5Y")
+# etf_df = fetch_etf(source, ticker="HYG")
+
+# Generate signal
+signal_config = SignalConfig(lookback=20, min_periods=10)
+signal = compute_cdx_etf_basis(cdx_df, etf_df, signal_config)
+
+# Run backtest
+backtest_config = BacktestConfig(entry_threshold=1.5, exit_threshold=0.75)
+results = run_backtest(signal, cdx_df["spread"], backtest_config)
+print(f"Sharpe Ratio: {results.metrics['sharpe_ratio']:.2f}")
+```
+
+## Project Structure
+
+```
+aponyx/
+├── src/aponyx/       # Core framework
+│   ├── data/              # Data loading, validation, transformation
+│   ├── models/            # Signal generation for credit strategies
+│   ├── backtest/          # Backtesting engine and metrics
+│   ├── visualization/     # Plotly charts and Streamlit dashboard
+│   ├── persistence/       # Parquet/JSON I/O and registry
+│   └── config/            # Configuration and constants
+├── examples/              # Runnable demonstrations
+├── tests/                 # Unit tests
+└── docs/                  # Architecture and design docs
+```
+
+### Key Layers
+
+| Layer | Purpose | Entry Point |
+|-------|---------|-------------|
+| **Data** | Load, validate, transform market data | `aponyx.data` |
+| **Models** | Generate signals for independent evaluation | `aponyx.models` |
+| **Backtest** | Simulate execution and compute metrics | `aponyx.backtest` |
+| **Visualization** | Interactive charts and dashboards | `aponyx.visualization` |
+| **Persistence** | Save/load data with metadata registry | `aponyx.persistence` |
+
+## Documentation
+
+### Getting Started
+- **[Python Guidelines](docs/python_guidelines.md)** - Code standards and best practices
+- **[Examples](examples/)** - Runnable demos for each layer
+
+### Strategy & Architecture
+- **[CDX Overlay Strategy](docs/cdx_overlay_strategy.md)** - Investment thesis and pilot implementation
+- **[Documentation Structure](docs/documentation_structure.md)** - Single source of truth principles
+
+### Design Guides
+- **[Logging Design](docs/logging_design.md)** - Logging conventions and metadata tracking
+- **[Signal Registry Usage](docs/signal_registry_usage.md)** - Signal management and research workflow
+- **[Visualization Design](docs/visualization_design.md)** - Chart architecture and integration patterns
+- **[Caching Design](docs/caching_design.md)** - Cache layer architecture and usage
+- **[Adding Data Providers](docs/adding_data_providers.md)** - Provider extension guide
+
+## Features
+
+✅ **Type-safe data loading** with schema validation  
+✅ **Modular signal framework** with composable transformations  
+✅ **Deterministic backtesting** with transaction cost modeling  
+✅ **Interactive visualization** with Plotly charts (equity, signals, drawdown)  
+✅ **Parquet-based persistence** with JSON metadata registry  
+✅ **Comprehensive logging** with run metadata tracking  
+✅ **Bloomberg Terminal integration** via xbbg wrapper (included by default, requires active Terminal session)
+
+**Planned Features:**
+- 🔜 Streamlit dashboard (stub exists, not yet implemented)
+- 🔜 Advanced attribution charts (stubs with NotImplementedError)
+
+## Development
+
+### Running Tests
+
+```bash
+# All tests
+uv run pytest
+
+# With coverage
+uv run pytest --cov=aponyx --cov-report=term-missing
+
+# Specific module
+uv run pytest tests/models/
+```
+
+### Code Quality
+
+```bash
+# Format code
+uv run black src/ tests/
+
+# Lint
+uv run ruff check src/ tests/
+
+# Type check
+uv run mypy src/
+```
+
+### Examples
+
+Each example demonstrates a specific layer with synthetic data:
+
+```bash
+uv run python examples/data_demo.py          # Data loading and transformation
+uv run python examples/models_demo.py        # Signal generation
+uv run python examples/backtest_demo.py      # Complete backtest workflow
+uv run python examples/visualization_demo.py # Interactive charts (requires viz extra)
+uv run python examples/persistence_demo.py   # Data I/O and registry
+```
+
+## Design Principles
+
+1. **Modularity** - Separate data, models, backtest, and persistence layers
+2. **Reproducibility** - Deterministic outputs with seed control and metadata logging
+3. **Type safety** - Strict type hints and runtime validation
+4. **Simplicity** - Prefer functions over classes, explicit over implicit
+5. **Transparency** - Clear separation between strategy logic and infrastructure
+
+## Architecture Notes
+
+### Signal Convention
+
+All model signals follow a **consistent sign convention**:
+- **Positive values** → Long credit risk (buy CDX / sell protection)
+- **Negative values** → Short credit risk (sell CDX / buy protection)
+
+This convention ensures clear interpretation when evaluating signals individually
+or when combining signals in future experiments.
+
+### Data Flow
+
+```
+Raw Data (Parquet/CSV)
+    ↓
+Data Layer (load, validate, transform)
+    ↓
+Models Layer (signal computation)
+    ↓
+Backtest Layer (simulation, metrics)
+    ↓
+Persistence Layer (save results, metadata)
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Contributing
+
+This is a research project under active development. See [Python Guidelines](docs/python_guidelines.md) for code standards.
+
+---
+
+**Maintained by stabilefrisur**  
+Version 0.1.0 | Last Updated: October 31, 2025

aponyx-0.1.0/pyproject.toml

@@ -0,0 +1,78 @@
+[project]
+name = "aponyx"
+description = "Systematic research framework for tactical credit strategies"
+version = "0.1.0"
+readme = "README.md"
+license = {file = "LICENSE"}
+authors = [
+    { name = "Stabile Frisur", email = "26568863+stabilefrisur@users.noreply.github.com" }
+]
+requires-python = ">=3.13"
+keywords = [
+    "finance",
+    "investing",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Financial and Insurance Industry",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business :: Financial :: Investment",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pandas>=2.2.0",
+    "numpy>=2.0.0",
+    "pyarrow>=17.0.0",
+    "xbbg>=0.7.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/stabilefrisur/aponyx"
+Repository = "https://github.com/stabilefrisur/aponyx"
+Documentation = "https://github.com/stabilefrisur/aponyx/blob/master/README.md"
+Issues = "https://github.com/stabilefrisur/aponyx/issues"
+Changelog = "https://github.com/stabilefrisur/aponyx/blob/master/CHANGELOG.md"
+
+[build-system]
+requires = ["uv_build>=0.9.5,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+# optional overrides; defaults expect a single module under src/<name>
+module-root = "src"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=5.0.0",
+    "ruff>=0.6.0",
+    "black>=24.0.0",
+    "mypy>=1.11.0",
+    "pandas-stubs>=2.0.0",
+]
+viz = [
+    "plotly>=5.24.0",
+    "streamlit>=1.39.0",
+    "nbformat>=5.10.0",
+    "ipykernel>=6.29.0",
+]
+
+[tool.pytest.ini_options]
+pythonpath = "src"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py313"
+
+[tool.black]
+line-length = 100
+target-version = ["py313"]
+
+[tool.mypy]
+python_version = "3.13"
+strict = true
+warn_return_any = true
+warn_unused_configs = true

aponyx-0.1.0/src/aponyx/__init__.py

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

aponyx-0.1.0/src/aponyx/backtest/__init__.py

@@ -0,0 +1,29 @@
+"""
+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
+- metrics: Performance and risk statistics
+- config: Backtest parameters and constraints
+- protocols: Abstract interfaces for extensibility
+"""
+
+from .config import BacktestConfig
+from .engine import run_backtest, BacktestResult
+from .metrics import compute_performance_metrics, PerformanceMetrics
+from .protocols import BacktestEngine, PerformanceCalculator
+
+__all__ = [
+    "BacktestConfig",
+    "run_backtest",
+    "BacktestResult",
+    "compute_performance_metrics",
+    "PerformanceMetrics",
+    "BacktestEngine",
+    "PerformanceCalculator",
+]