[//]: # SSoT-OK

# opendeviationbar-py

High-performance open deviation bar construction for quantitative trading, with Python bindings via PyO3/maturin.

[![PyPI](https://img.shields.io/pypi/v/opendeviationbar.svg)](https://pypi.org/project/opendeviationbar/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/terrylica/opendeviationbar-py/blob/main/LICENSE)
[![Python](https://img.shields.io/pypi/pyversions/opendeviationbar.svg)](https://pypi.org/project/opendeviationbar/)

| Resource              | URL                                                       |
| --------------------- | --------------------------------------------------------- |
| PyPI                  | <https://pypi.org/project/opendeviationbar/>              |
| Repository            | <https://github.com/terrylica/opendeviationbar-py>        |
| Performance Dashboard | <https://terrylica.github.io/opendeviationbar-py/>        |
| API Reference         | [docs/api/INDEX.md](/docs/api/INDEX.md)                   |
| Issues                | <https://github.com/terrylica/opendeviationbar-py/issues> |

## Installation

```bash
pip install opendeviationbar
```

Pre-built wheels: Linux (x86_64), macOS (ARM64), Python 3.13. Source build requires Rust toolchain and maturin.

## Quick Start

```python
from opendeviationbar import get_open_deviation_bars

# Fetch data and generate open deviation bars in one call
df = get_open_deviation_bars("BTCUSDT", "2024-01-01", "2024-06-30")

# Use with backtesting.py
from backtesting import Backtest, Strategy
bt = Backtest(df, MyStrategy, cash=10000, commission=0.0002)
stats = bt.run()
```

Output: pandas DataFrame with DatetimeIndex and OHLCV columns, compatible with [backtesting.py](https://github.com/kernc/backtesting.py).

## API Overview

| Function                      | Use Case                        |
| ----------------------------- | ------------------------------- |
| `get_open_deviation_bars()`   | Date-bounded, auto-fetch        |
| `get_n_open_deviation_bars()` | Exact N bars (ML training)      |
| `process_trades_polars()`     | Polars DataFrames (2-3x faster) |
| `process_trades_chunked()`    | Large datasets (>10M trades)    |
| `populate_cache_resumable()`  | Long ranges (>30 days)          |
| `run_sidecar()`               | Real-time streaming sidecar     |

```python
# Count-bounded (ML training)
from opendeviationbar import get_n_open_deviation_bars
df = get_n_open_deviation_bars("BTCUSDT", n_bars=10000)

# Polars (2-3x faster)
import polars as pl
from opendeviationbar import process_trades_polars
bars = process_trades_polars(pl.scan_parquet("trades.parquet"), threshold_decimal_bps=250)

# With microstructure features (57 columns: OFI, Kyle lambda, Hurst, etc.)
df = get_open_deviation_bars("BTCUSDT", "2024-01-01", "2024-06-30", include_microstructure=True)

# Real-time streaming sidecar
from opendeviationbar import run_sidecar, SidecarConfig
config = SidecarConfig(symbol="BTCUSDT", threshold_decimal_bps=250)
run_sidecar(config)
```

## Designed for Claude Code

This repository uses a [CLAUDE.md](/CLAUDE.md) network that provides comprehensive project context for AI-assisted development via Anthropic's [Claude Code](https://code.claude.com/) CLI.

```bash
npm install -g @anthropic-ai/claude-code
cd opendeviationbar-py
claude
```

Claude Code reads the CLAUDE.md files automatically and understands the full architecture, API, build system, and development workflow.

## Development

```bash
git clone https://github.com/terrylica/opendeviationbar-py.git
cd opendeviationbar-py
mise install          # Setup tools (Rust, Python, zig)
mise run build        # maturin develop
mise run test         # Rust tests
mise run test-py      # Python tests
```

## Requirements

**Runtime**: Python >= 3.13, pandas >= 2.0, numpy >= 1.24, polars >= 1.0

**Build**: Rust toolchain, maturin >= 1.7

## License

MIT License. See [LICENSE](/LICENSE).

## Citation

```bibtex
@software{opendeviationbar-py,
  title = {opendeviationbar-py: High-performance open deviation bar construction for quantitative trading},
  author = {Terry Li},
  url = {https://github.com/terrylica/opendeviationbar-py}
}
```
