# Trade Processors

**Parent**: [/python/opendeviationbar/CLAUDE.md](/python/opendeviationbar/CLAUDE.md) | **Hub**: [/CLAUDE.md](/CLAUDE.md)

Trade processing pipeline bridging raw trades to open deviation bars. Wraps the Rust `PyOpenDeviationBarProcessor` via PyO3 and provides multiple entry points for different input formats (pandas, Polars, iterators).

---

## Files

| File          | Purpose                                                                                                                                                                           |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `__init__.py` | Package exports: `OpenDeviationBarProcessor`, `process_trades_chunked`, `process_trades_polars`, `process_trades_to_dataframe`, `process_trades_to_dataframe_cached`              |
| `api.py`      | High-level convenience functions: `process_trades_to_dataframe()` (pandas), `process_trades_polars()` (Polars, 2-3x faster), `process_trades_chunked()` (iterator, memory-safe)   |
| `core.py`     | `OpenDeviationBarProcessor` class: Pythonic wrapper around Rust `PyOpenDeviationBarProcessor` with checkpoint support, DataFrame conversion, and inter-bar lookback configuration |

## Processing Pipeline

1. **`core.py` -- `OpenDeviationBarProcessor`**: Stateful processor that wraps the Rust engine. Accepts threshold (dbps), symbol, inter-bar lookback config. Key methods:
   - `process_trades(trades)` -- feed trades, get completed bars
   - `to_dataframe(bars)` -- convert bars to backtesting.py-compatible pandas DataFrame
   - `create_checkpoint()` / `from_checkpoint()` -- cross-session continuity
   - `reset_at_ouroboros()` -- state reset at Ouroboros boundaries (legacy, not used in Aion mode)

2. **`api.py` -- Convenience functions**: Format-specific entry points that create a processor internally:
   - `process_trades_to_dataframe()` -- accepts `list[dict]` or pandas DataFrame
   - `process_trades_polars()` -- accepts Polars DataFrame, uses Arrow zero-copy path (`_arrow_bars_to_pandas()`)
   - `process_trades_chunked()` -- accepts iterator, processes in bounded-memory chunks
   - `process_trades_to_dataframe_cached()` -- cached variant with ClickHouse integration

## Related

- [/python/opendeviationbar/CLAUDE.md](/python/opendeviationbar/CLAUDE.md) -- Parent: Python API layer
- [/CLAUDE.md](/CLAUDE.md) -- Hub: project overview and architecture
- [/crates/CLAUDE.md](/crates/CLAUDE.md) -- Rust `PyOpenDeviationBarProcessor` implementation in `opendeviationbar-core`
- [/python/opendeviationbar/orchestration/CLAUDE.md](/python/opendeviationbar/orchestration/CLAUDE.md) -- Orchestration layer that calls these processors
