Metadata-Version: 2.4
Name: alpha-risk-kit
Version: 0.1.0
Summary: Portfolio analytics toolkit with interactive widgets for quants - return analysis, drawdown visualization, and benchmark comparison
Project-URL: Homepage, https://github.com/daviddwlee84/alpha-risk-kit
Project-URL: Documentation, https://daviddwlee84.github.io/alpha-risk-kit
Project-URL: Repository, https://github.com/daviddwlee84/alpha-risk-kit
Project-URL: Issues, https://github.com/daviddwlee84/alpha-risk-kit/issues
Author-email: Da-Wei Lee <daviddwlee84@gmail.com>
License: MIT
License-File: LICENSE
Keywords: analytics,backtesting,drawdown,finance,portfolio,quantitative,returns,widget
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.10
Requires-Dist: anywidget>=0.9.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: scipy>=1.11.0
Requires-Dist: traitlets>=5.0.0
Provides-Extra: all
Requires-Dist: ipykernel>=7.1.0; extra == 'all'
Requires-Dist: marimo>=0.1.0; extra == 'all'
Requires-Dist: matplotlib>=3.7.0; extra == 'all'
Requires-Dist: mkdocs-material>=9.5.0; extra == 'all'
Requires-Dist: mkdocs>=1.5.0; extra == 'all'
Requires-Dist: mkdocstrings[python]>=0.24.0; extra == 'all'
Requires-Dist: mypy>=1.0.0; extra == 'all'
Requires-Dist: nbformat>=5.10.4; extra == 'all'
Requires-Dist: pandas-stubs>=2.0.0; extra == 'all'
Requires-Dist: plotly>=5.18.0; extra == 'all'
Requires-Dist: pytest-cov>=4.0.0; extra == 'all'
Requires-Dist: pytest>=7.0.0; extra == 'all'
Requires-Dist: ruff>=0.1.0; extra == 'all'
Requires-Dist: streamlit>=1.30.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pandas-stubs>=2.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5.0; extra == 'docs'
Requires-Dist: mkdocs>=1.5.0; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.24.0; extra == 'docs'
Provides-Extra: jupyter
Requires-Dist: ipykernel>=7.1.0; extra == 'jupyter'
Requires-Dist: nbformat>=5.10.4; extra == 'jupyter'
Provides-Extra: marimo
Requires-Dist: marimo>=0.1.0; extra == 'marimo'
Provides-Extra: plots
Requires-Dist: matplotlib>=3.7.0; extra == 'plots'
Requires-Dist: plotly>=5.18.0; extra == 'plots'
Provides-Extra: streamlit
Requires-Dist: plotly>=5.18.0; extra == 'streamlit'
Requires-Dist: streamlit>=1.30.0; extra == 'streamlit'
Description-Content-Type: text/markdown

# Alpha Risk Kit

[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)

**Portfolio analytics toolkit with interactive widgets for quants**

Alpha Risk Kit is a comprehensive Python library for analyzing portfolio returns, inspired by [QuantStats](https://github.com/ranaroussi/quantstats) and [VectorBT](https://vectorbt.dev/). It provides:

- **Interactive Widgets**: AnyWidget-based components for Jupyter, Marimo, and VS Code
- **Static Charts**: Matplotlib and Plotly visualizations
- **Pandas Accessor**: VectorBT-style `returns.ark.stats()` pattern
- **Bilingual Support**: English and Chinese (中文) interfaces

## Quick Start

```bash
uv sync --extra all

uv run jupyter notebook
uv run marimo edit --watch usages/marimo/demo.py
uv run streamlit run usages/streamlit/app.py
```

```python
import alpha_risk_kit as ark
import pandas as pd

# Your returns data
returns = pd.Series([0.01, -0.02, 0.015, -0.005, 0.02])

# Get comprehensive statistics
returns.ark.stats()

# Create interactive widget
from alpha_risk_kit.widgets import ReturnsWidget
widget = ReturnsWidget(returns=returns)
widget  # Display in Jupyter
```

## Installation

```bash
# Basic installation
pip install alpha-risk-kit

# With plotting support
pip install alpha-risk-kit[plots]

# All dependencies
pip install alpha-risk-kit[all]

# Development installation
pip install -e ".[all]"
```

## Features

### Core Metrics

```python
# Using pandas accessor
returns.ark.sharpe()           # Sharpe Ratio
returns.ark.sortino()          # Sortino Ratio
returns.ark.max_drawdown()     # Maximum Drawdown
returns.ark.calmar()           # Calmar Ratio
returns.ark.win_rate()         # Win Rate

# With benchmark comparison
returns.ark.stats(benchmark=sp500_returns)
```

### Interactive Widgets

```python
from alpha_risk_kit.widgets import ReturnsWidget, ComparisonWidget, DashboardWidget

# Single strategy analysis
widget = ReturnsWidget(returns=my_returns, benchmark=benchmark)

# Strategy vs benchmark comparison
comparison = ComparisonWidget(returns=strategy, benchmark=benchmark)

# Multi-strategy dashboard
dashboard = DashboardWidget(returns=strategies_df, benchmarks=benchmarks_df)
```

### Static Charts

```python
# Matplotlib
fig = ark.plot_combined(returns, benchmark=benchmark, backend='matplotlib')

# Plotly (interactive)
fig = ark.plot_combined(returns, benchmark=benchmark, backend='plotly')
fig.show()
```

### Bilingual Support

```python
ark.set_language('zh')  # Switch to Chinese (中文)
ark.set_language('en')  # Switch to English
```

## Widget Gallery

| Widget             | Description                                   |
| ------------------ | --------------------------------------------- |
| `ReturnsWidget`    | Cumulative returns + drawdown + key metrics   |
| `ComparisonWidget` | Strategy vs benchmark with excess returns     |
| `DashboardWidget`  | Multi-strategy comparison with sortable table |

## Platform Support

| Platform         | Widgets | Static Charts |
| ---------------- | ------- | ------------- |
| Jupyter Notebook | ✅       | ✅             |
| JupyterLab       | ✅       | ✅             |
| VS Code          | ✅       | ✅             |
| Marimo           | ✅       | ✅             |
| Streamlit        | ❌       | ✅             |
| Google Colab     | ✅       | ✅             |

## Project Structure

```
alpha-risk-kit/
├── src/alpha_risk_kit/
│   ├── stats.py          # Core metrics
│   ├── plots.py          # Chart generation
│   ├── accessors.py      # Pandas accessor
│   ├── i18n.py           # Translations
│   ├── utils.py          # Utilities
│   └── widgets/          # AnyWidget components
├── usages/
│   ├── jupyter/          # Jupyter notebook demo
│   ├── streamlit/        # Streamlit app demo
│   └── marimo/           # Marimo notebook demo
└── docs/                 # MkDocs documentation
```

## Comparison with Other Tools

| Feature             | Alpha Risk Kit | QuantStats | VectorBT |
| ------------------- | -------------- | ---------- | -------- |
| Interactive Widgets | ✅ AnyWidget    | ❌          | ❌        |
| Pandas Accessor     | ✅ `.ark`       | ❌          | ✅ `.vbt` |
| Bilingual (EN/ZH)   | ✅              | ❌          | ❌        |
| Plotly Charts       | ✅              | ✅          | ✅        |
| Matplotlib Charts   | ✅              | ✅          | ✅        |

## Documentation

Full documentation is available at: https://daviddwlee84.github.io/alpha-risk-kit

## Contributing

Contributions are welcome! Please see [AGENTS.md](AGENTS.md) for development guidelines.

## License

MIT License - see [LICENSE](LICENSE) for details.
