Metadata-Version: 2.4
Name: PyAlgoEngine
Version: 0.12.3
Summary: Basic algo engine
Author-email: Han Bolun <Bolun.Han@outlook.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/BolunHan/PyAlgoEngine
Project-URL: Repository, https://github.com/BolunHan/PyAlgoEngine
Project-URL: Issues, https://github.com/BolunHan/PyAlgoEngine/issues
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: exchange_calendars
Requires-Dist: PyCyBase
Requires-Dist: PyEventEngine
Requires-Dist: cython
Provides-Extra: webapps
Requires-Dist: flask; extra == "webapps"
Requires-Dist: waitress; extra == "webapps"
Requires-Dist: bokeh; extra == "webapps"
Provides-Extra: docs
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: furo; extra == "docs"
Dynamic: license-file

# PyAlgoEngine

[![docs](https://github.com/BolunHan/PyAlgoEngine/actions/workflows/build-page-docs.yml/badge.svg)](https://github.com/BolunHan/PyAlgoEngine/actions/workflows/build-page-docs.yml)
[![pypi-linux](https://github.com/BolunHan/PyAlgoEngine/actions/workflows/publish-posix-to-pypi.yml/badge.svg)](https://github.com/BolunHan/PyAlgoEngine/actions/workflows/publish-posix-to-pypi.yml)
[![pypi-windows](https://github.com/BolunHan/PyAlgoEngine/actions/workflows/publish-nt-to-pypi.yml/badge.svg)](https://github.com/BolunHan/PyAlgoEngine/actions/workflows/publish-nt-to-pypi.yml)

**High-Performance Algorithmic Trading Engine in Python, Cython, and C**

PyAlgoEngine is a low-latency trading engine for HFT (High-Frequency Trading)
systems. It provides C-level market data structures, shared-memory buffers,
an event-driven engine architecture, backtesting with simulated order matching,
exchange calendar profiles, and web-based visualization — all with Cython
acceleration for latency-critical paths.

## Features

| Category                | Capabilities                                                                                                                          |
|-------------------------|---------------------------------------------------------------------------------------------------------------------------------------|
| **Market Data**         | `TickData`, `TickDataLite`, `BarData`, `DailyBar`, `OrderBook`, `TransactionData`, `OrderData`, `TradeData` — all C-backed via Cython |
| **Buffers**             | `MarketDataBuffer`, `MarketDataRingBuffer`, `MarketDataConcurrentBuffer`, `MarketDataBufferCache`                                     |
| **Engines**             | `EVENT_ENGINE` (pub/sub), `MDS` (Market Data Service), `ALGO_ENGINE` (algo lifecycle), trade engine (DMA, positions, risk)            |
| **Exchange Profiles**   | CN (A-share) and default global calendars, session phases, holidays via `PROFILE`, `PROFILE_CN`, `PROFILE_DEFAULT`                    |
| **Backtesting**         | `SimpleReplay`, `ProgressReplay`, `SimMatch` (simulated matching), `TradeMetrics`                                                     |
| **Strategy Framework**  | `StrategyEngine`, `AlgoTemplate`, global singletons (`BALANCE`, `DMA`, `STRATEGY_ENGINE`)                                             |
| **Web Apps**            | Flask + Bokeh dashboards, candlestick charts, strategy tester UI                                                                      |
| **Compile-Time Config** | `BOOK_SIZE`, `ID_SIZE`, `LONG_ID_SIZE`, `MD_BUF_PTR_DEFAULT_CAP`, `MD_BUF_DATA_DEFAULT_CAP` via env vars                              |

## Quick Install

```bash
git clone https://github.com/BolunHan/PyAlgoEngine.git
cd PyAlgoEngine
./build.sh -i
```

Requires **Python 3.12+** and a C compiler (GCC, Clang, or MSVC).
See the [Setup Guide](docs/source/setup.rst) for
detailed instructions, compile-time configuration, and optional dependencies.

## Quick Verify

```python
import algo_engine

print(algo_engine.__version__)

from algo_engine.base import CONFIG

print(CONFIG)  # compile-time and runtime configuration
```

## Documentation

Build locally:

```bash
cd docs && ./update_docs.sh
# open build/html/index.html
```

- **Read the Docs:** [pyalgoengine.readthedocs.io](https://pyalgoengine.readthedocs.io)
- **GitHub Pages:** [bolunhan.github.io/PyAlgoEngine](https://bolunhan.github.io/PyAlgoEngine)

## Architecture

```
┌──────────────────────────────────────────────────────┐
│  apps/          Web visualization (Flask, Bokeh)     │
├──────────────────────────────────────────────────────┤
│  strategy/      Strategy framework, global singletons│
├──────────────────────────────────────────────────────┤
│  engine/        Event, Market, Algo, Trade engines   │
├──────────────────────────────────────────────────────┤
│  backtest/      Replay, SimMatch, Metrics            │
├──────────────────────────────────────────────────────┤
│  base/          Market data types, buffers (Cython/C)│
├──────────────────────────────────────────────────────┤
│  exchange_profile/  Calendars, sessions (CN + global)│
├──────────────────────────────────────────────────────┤
│  monitor/       Synthetic order book, bar monitor    │
├──────────────────────────────────────────────────────┤
│  utils/         Time-series indices, fake data       │
└──────────────────────────────────────────────────────┘
```

## Build System

| Command          | Description                                      |
|------------------|--------------------------------------------------|
| `./build.sh -i`  | Clean, build Cython extensions in-place, install |
| `make build`     | Clean and build extensions in-place              |
| `make install`   | Build + pip install                              |
| `./build.sh -l`  | List all compile-time macros and defaults        |
| `make list-args` | Same as above                                    |

Override compile-time constants:

```bash
BOOK_SIZE=20 ./build.sh -i
```

## Dependencies

- **Runtime:** numpy, pandas, exchange_calendars, PyCyBase, PyEventEngine, Cython
- **Web (optional):** flask, waitress, bokeh
- **Docs (optional):** sphinx, sphinx-rtd-theme

## License

MIT — [Han Bolun](https://github.com/BolunHan)
