Metadata-Version: 2.4
Name: aquant-trade
Version: 0.1.0
Summary: AQuant 量化框架 —— Crypto 优先·纯 Python·JSON 驱动
License: MIT
License-File: LICENSE
Author: AQuant Team
Author-email: team@aquant.dev
Requires-Python: >=3.11,<4.0
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.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Dist: aiohttp (>=3.9,<4.0)
Requires-Dist: aiosqlite (>=0.20,<0.21)
Requires-Dist: click (>=8.0,<9.0)
Requires-Dist: numpy (>=1.26,<2.0)
Requires-Dist: onnxruntime (>=1.18,<2.0)
Requires-Dist: orjson (>=3.9,<4.0)
Requires-Dist: pandas (>=2.0,<3.0)
Requires-Dist: polars (>=1.0,<2.0)
Requires-Dist: pyarrow (>=17.0,<18.0)
Requires-Dist: pydantic (>=2.0,<3.0)
Requires-Dist: rich (>=13.0,<14.0)
Requires-Dist: scipy (>=1.12,<2.0)
Requires-Dist: sqlalchemy (>=2.0,<3.0)
Requires-Dist: structlog (>=24.0,<25.0)
Requires-Dist: websockets (>=12.0,<13.0)
Project-URL: Homepage, https://github.com/aquant/aquant
Project-URL: Repository, https://github.com/aquant/aquant
Description-Content-Type: text/markdown

# AQuant

> 一个纯 Python、Crypto 优先、JSON 驱动的量化交易框架。

[![CI](https://github.com/your-org/aquant/actions/workflows/ci.yml/badge.svg)](https://github.com/your-org/aquant/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/aquant)](https://pypi.org/project/aquant/)
[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)

---

## 核心特性

- **纯 Python** — Python 3.11+，asyncio 异步事件驱动，无 C++ 依赖
- **Crypto 优先** — 原生支持 Binance、OKX、Bybit 等主流交易所
- **JSON 驱动** — 一个策略就是一个 JSON 配置文件，声明式定义经纪商/风控/资金/模式
- **回测/实盘一致** — Broker、Risk、Execution 统一抽象，同一套代码两种模式
- **多策略资金隔离** — SubPortfolio 独立风控 + MasterPortfolio 组合归因
- **ML 内建** — ONNX Runtime 推理 + FeaturePipeline + FactorRegistry
- **全局结构化日志** — JSON 日志标准，全系统字段一致，直接对接 Loki/ELK

---

## 快速开始

### 安装

```bash
pip install aquant
```

### 回测一个双均线策略

```bash
# 1. 准备配置
cat > my_strategy.json << 'EOF'
{
  "$schema": "aquant://config/v1",
  "meta": {"strategy_id": "demo_dual_ma", "version": "1.0.0"},
  "mode": "backtest",
  "capital": {"base_currency": "USDT", "initial": 10000},
  "broker": {"exchange": "binance", "market_type": "spot"},
  "data": {
    "feeds": [{
      "symbol": "BTCUSDT", "timeframe": "1h", "source": "parquet",
      "path": "data/BTCUSDT_1h.parquet",
      "start": "2024-01-01T00:00:00Z", "end": "2024-12-31T23:59:59Z"
    }],
    "warmup_bars": 100
  },
  "strategy": {
    "module": "strategies.dual_ma",
    "class": "DualMAStrategy",
    "params": {"fast_period": 10, "slow_period": 30}
  },
  "risk": {
    "pre_trade": {"max_position_ratio": 0.95},
    "stop_loss": {"enabled": true, "type": "fixed", "trigger": 0.05}
  },
  "sizer": {"type": "percent", "params": {"percents": 90}},
  "logging": {"level": "INFO"}
}
EOF

# 2. 运行回测
aquanta backtest my_strategy.json

# 3. 查看报告
aquanta plot my_strategy.json
aquanta report my_strategy.json
```

### 编写自定义策略

```python
from aquant import Strategy, indicators

class MyStrategy(Strategy):
    def __init__(self):
        self.fast = indicators.SMA(period=self.p.fast_period)
        self.slow = indicators.SMA(period=self.p.slow_period)

    def next(self):
        if self.fast > self.slow and not self.position:
            self.buy(size=self.sizer.getsizing())
        elif self.fast < self.slow and self.position:
            self.sell(size=self.position.size)
```

---

## 目录结构

```
AQuant/
├── README.md                   # 本文档
├── LICENSE                     # MIT License
├── pyproject.toml              # Poetry 配置，依赖定义
│
├── docs/                       # 文档（项目唯一真理源）
│   ├── ARCHITECTURE_v1.md      # 架构总览
│   ├── STANDARDS.md            # 项目技术标准与开发规范
│   ├── LOGGING_STANDARD.md     # 全局日志标准
│   ├── JSON_SCHEMA.md          # JSON 配置 Schema
│   ├── DECISIONS.md            # 架构决策记录（ADR）
│   │
│   ├── modules/                # 子模块设计文档（一模块一文档）
│   │   ├── engine.md           # AQuantEngine 核心编排 → 见 docs/modules/engine.md
│   │   ├── strategy.md         # Strategy 基类与生命周期 → 见 docs/modules/strategy.md
│   │   ├── data.md             # DataFeed 与数据源 → 见 docs/modules/data.md
│   │   ├── broker.md           # Broker 抽象与实现 → 见 docs/modules/broker.md
│   │   ├── execution.md        # 订单与执行 → 见 docs/modules/execution.md
│   │   ├── risk.md             # RiskEngine 与规则 → 见 docs/modules/risk.md
│   │   ├── portfolio.md        # 组合与资金隔离 → 见 docs/modules/portfolio.md
│   │   ├── indicators.md       # 技术指标系统 → 见 docs/modules/indicators.md
│   │   ├── ml.md               # 机器学习集成 → 见 docs/modules/ml.md
│   │   ├── alpha.md            # 多因子平台 → 见 docs/modules/alpha.md
│   │   ├── analyzers.md        # 绩效分析器 → 见 docs/modules/analyzers.md
│   │   ├── observers.md        # 监控与绘图 → 见 docs/modules/observers.md
│   │   ├── config.md           # 配置系统 → 见 docs/modules/config.md
│   │   ├── logger.md           # 结构化日志 → 见 docs/modules/logger.md
│   │   ├── events.md           # 事件系统 → 见 docs/modules/events.md
│   │   ├── exceptions.md       # 异常体系 → 见 docs/modules/exceptions.md
│   │   └── cli.md              # 命令行接口 → 见 docs/modules/cli.md
│   │
│   ├── api/                    # API 参考文档
│   │   └── strategy_api.md     # Strategy 开发 API → 见 docs/api/strategy_api.md
│   │
│   └── guides/                 # 用户指南
│       ├── quickstart.md       # 快速入门 → 见 docs/guides/quickstart.md
│       ├── backtesting.md      # 回测指南 → 见 docs/guides/backtesting.md
│       ├── live_trading.md     # 实盘交易指南 → 见 docs/guides/live_trading.md
│       └── custom_strategy.md  # 自定义策略开发 → 见 docs/guides/custom_strategy.md
│
├── aquant/                     # 主 Python 包
│   ├── __init__.py             # 公共 API 暴露
│   ├── __version__.py          # 版本号单一来源
│   ├── engine.py               # AQuantEngine（核心编排入口）
│   ├── config.py               # Pydantic 配置模型（JSON Schema 的代码实现）
│   ├── logger.py               # 结构化日志系统
│   ├── events.py               # 事件定义与事件总线
│   ├── exceptions.py           # 自定义异常树
│   ├── cli.py                  # 命令行入口
│   │
│   ├── core/                   # 核心抽象（借鉴 Backtrader）
│   │   ├── __init__.py
│   │   ├── strategy.py         # Strategy 基类
│   │   ├── data.py             # DataFeed / Bar / Tick 归一化数据结构
│   │   ├── broker.py           # BaseBroker 抽象接口
│   │   ├── sizer.py            # Sizer 基类与内置实现
│   │   ├── observer.py         # Observer 基类
│   │   ├── analyzer.py         # Analyzer 基类
│   │   ├── commission.py       # 手续费模型
│   │   └── slippage.py         # 滑点模型
│   │
│   ├── data/                   # 数据模块
│   │   ├── __init__.py
│   │   ├── feeds/              # 数据源实现
│   │   │   ├── __init__.py
│   │   │   ├── base.py         # BaseDataFeed 抽象
│   │   │   ├── csv.py          # CSV 文件源
│   │   │   ├── parquet.py      # Parquet 文件源
│   │   │   ├── binance.py      # Binance 实时/历史
│   │   │   ├── okx.py          # OKX 实时/历史
│   │   │   └── bybit.py        # Bybit 实时/历史
│   │   ├── store.py            # 数据存储管理
│   │   └── utils.py            # 数据工具（复权、对齐、清洗）
│   │
│   ├── broker/                 # 经纪商实现
│   │   ├── __init__.py
│   │   ├── base.py             # 共享工具（签名、重连、时间同步）
│   │   ├── backtest.py         # 回测撮合引擎
│   │   ├── paper.py            # 模拟交易（连接实盘行情，模拟下单）
│   │   ├── binance.py          # Binance 实盘 Broker
│   │   ├── okx.py              # OKX 实盘 Broker
│   │   └── bybit.py            # Bybit 实盘 Broker
│   │
│   ├── execution/              # 订单与执行
│   │   ├── __init__.py
│   │   ├── order.py            # Order / OrderState / OrderResult 定义
│   │   ├── position.py         # Position 持仓模型
│   │   └── algos/              # 算法执行
│   │       ├── __init__.py
│   │       ├── twap.py
│   │       └── vwap.py
│   │
│   ├── risk/                   # 风控引擎
│   │   ├── __init__.py
│   │   ├── engine.py           # RiskEngine 主类
│   │   ├── rules.py            # 规则库（限额、价格、流量、时间）
│   │   ├── stop.py             # 止损止盈模块
│   │   └── circuit.py          # 熔断器
│   │
│   ├── portfolio/              # 组合管理
│   │   ├── __init__.py
│   │   ├── master.py           # MasterPortfolio（组合级）
│   │   ├── sub.py              # SubPortfolio（策略级隔离）
│   │   ├── allocator.py        # 资金分配策略
│   │   └── attribution.py      # P&L 归因分析
│   │
│   ├── indicators/             # 技术指标
│   │   ├── __init__.py
│   │   ├── base.py             # Indicator 基类（Lines 概念）
│   │   ├── trend.py            # SMA, EMA, MACD, ADX...
│   │   ├── volatility.py       # ATR, Bollinger Bands...
│   │   ├── momentum.py         # RSI, Stochastic, CCI...
│   │   └── volume.py           # OBV, VWAP, MFI...
│   │
│   ├── ml/                     # 机器学习
│   │   ├── __init__.py
│   │   ├── pipeline.py         # FeaturePipeline（特征工程管道）
│   │   ├── onnx_runner.py      # ONNX Runtime 封装
│   │   └── features/           # 内置特征算子
│   │
│   ├── alpha/                  # 多因子平台
│   │   ├── __init__.py
│   │   ├── registry.py         # FactorRegistry（因子注册与计算）
│   │   └── factors/            # 内置因子实现
│   │
│   ├── analyzers/              # 绩效分析器
│   │   ├── __init__.py
│   │   ├── returns.py          # 收益分析
│   │   ├── drawdown.py         # 回撤分析
│   │   ├── sharpe.py           # 夏普/索提诺比率
│   │   └── report.py           # 综合报告生成器
│   │
│   ├── observers/              # 监控与绘图
│   │   ├── __init__.py
│   │   ├── equity.py           # 净值曲线 Observer
│   │   ├── trades.py           # 交易标记 Observer
│   │   └── plotter.py          # Matplotlib / Plotly 绘图引擎
│   │
│   └── utils/                  # 通用工具
│       ├── __init__.py
│       ├── time.py             # 时区/时间工具
│       ├── decimal.py          # Decimal 精度处理
│       └── validation.py       # 通用校验函数
│
├── strategies/                 # 示例策略（用户参考）
│   ├── __init__.py
│   ├── dual_ma.py              # 双均线策略
│   ├── bollinger_bands.py      # 布林带策略
│   ├── ml_enhanced.py          # ML 增强策略
│   └── arbitrage.py            # 套利策略示例
│
├── configs/                    # 配置示例
│   ├── backtest_dual_ma.json
│   ├── paper_dual_ma.json
│   ├── live_dual_ma.json
│   └── portfolio_multi.json
│
├── tests/                      # 测试
│   ├── unit/                   # 单元测试
│   ├── integration/            # 集成测试
│   └── fixtures/               # 测试数据与夹具
│
├── notebooks/                  # Jupyter 示例
│   ├── 01_quickstart.ipynb
│   ├── 02_backtest.ipynb
│   └── 03_ml_strategy.ipynb
│
└── scripts/                    # 辅助脚本
    ├── download_history.py     # 历史数据下载
    └── convert_format.py       # 数据格式转换
```

---

## 架构文档索引

| 文档 | 说明 |
|------|------|
| [`docs/ARCHITECTURE_v1.md`](docs/ARCHITECTURE_v1.md) | 系统全景、核心模块关系、数据流、部署架构 |
| [`docs/STANDARDS.md`](docs/STANDARDS.md) | 开发规范、AI 协作流程、代码规范、依赖白名单 |
| [`docs/LOGGING_STANDARD.md`](docs/LOGGING_STANDARD.md) | 全局 JSON 日志 Schema、事件类型、级别规范 |
| [`docs/JSON_SCHEMA.md`](docs/JSON_SCHEMA.md) | 策略配置 JSON 完整 Schema、校验规则、示例 |
| [`docs/DECISIONS.md`](docs/DECISIONS.md) | 架构决策记录（ADR） |

### 子模块设计文档

所有子模块的详细设计接口与实现规划，参见 `docs/modules/*.md`：

- [`engine.md`](docs/modules/engine.md) — 引擎编排与生命周期
- [`strategy.md`](docs/modules/strategy.md) — 策略基类与事件回调
- [`data.md`](docs/modules/data.md) — 数据源抽象与归一化
- [`broker.md`](docs/modules/broker.md) — 经纪商抽象与撮合
- [`execution.md`](docs/modules/execution.md) — 订单模型与算法执行
- [`risk.md`](docs/modules/risk.md) — 三级风控与熔断
- [`portfolio.md`](docs/modules/portfolio.md) — 组合与资金隔离
- [`indicators.md`](docs/modules/indicators.md) — 技术指标 Lines 系统
- [`ml.md`](docs/modules/ml.md) — ONNX 推理与特征管道
- [`alpha.md`](docs/modules/alpha.md) — 多因子注册与计算
- [`analyzers.md`](docs/modules/analyzers.md) — 绩效分析
- [`observers.md`](docs/modules/observers.md) — 监控与可视化
- [`config.md`](docs/modules/config.md) — Pydantic 配置系统
- [`logger.md`](docs/modules/logger.md) — 结构化日志实现
- [`events.md`](docs/modules/events.md) — 事件总线
- [`exceptions.md`](docs/modules/exceptions.md) — 异常树
- [`cli.md`](docs/modules/cli.md) — 命令行工具

---

## 开发规范

本项目采用 **AI 原生开发 + 文档先行** 模式：

1. **文档先行**：任何子模块在写代码前，必须先完成 `docs/modules/*.md` 设计文档
2. **零扩散**：不允许私自增加功能、修改接口、引入未审批依赖
3. **文档即契约**：代码实现必须与文档一致

详见 [`docs/STANDARDS.md`](docs/STANDARDS.md)。

---

## 许可证

[MIT](LICENSE)

