haze-library 1.1.3
High-performance quantitative trading indicators library with Rust backend
Requires Python: >=3.14
Keywords: trading, indicators, quantitative, technical-analysis, rust

# 🌫️ Haze-Library

[![CI](https://github.com/kwannz/haze/actions/workflows/ci.yml/badge.svg)](https://github.com/kwannz/haze/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/haze-library)](https://pypi.org/project/haze-library/)
[![License: Proprietary](https://img.shields.io/badge/License-Proprietary-red.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.14%2B-blue)](https://www.python.org/)
[![Rust](https://img.shields.io/badge/rust-1.75%2B-orange)](https://www.rust-lang.org/)

**基于 Rust 的高性能量化交易指标库**

---

## ✨ 核心特性

| 特性 | 描述 |
|------|------|
| 🚀 **215+ 技术指标** | 完整覆盖 TA-Lib、pandas-ta、谐波形态等 |
| ⚡ **Rust 高性能** | 比纯 Python 快 5-10 倍 |
| 📊 **流式计算** | O(1) 实时增量指标计算 |
| 🤖 **机器学习** | 内置 SVM、线性回归等 ML 模型 |
| 🎯 **LT 组合指标** | 10 个 SFG 专业交易信号 + 市场状态自适应 |
| 🔗 **多框架支持** | NumPy、Pandas、Polars、PyTorch |
| 💹 **交易执行** | CCXT 交易所接口封装 |
| 🎯 **高精度** | 误差容忍度 < 1e-9 |
| 🔒 **类型安全** | 完整的类型注解 |

---

## 📦 安装

### 从 PyPI 安装（推荐）

```bash
# 安装最新版本 (v1.1.1+)
pip install haze-library

# 或指定版本
pip install haze-library==1.1.1
```

### 可选依赖

```bash
# 交易执行功能（CCXT）
pip install haze-library[execution]

# Pandas 支持
pip install haze-library[pandas]

# 完整安装
pip install haze-library[full]
```

### 从源码构建

```bash
git clone https://github.com/kwannz/haze.git
cd haze
pip install maturin
maturin develop --release --features python
```

### 环境要求

- Python 3.14+
- Rust 1.75+（仅源码构建需要）

---

## 🚀 快速开始

### 基础用法

```python
import haze_library as haze

# 价格数据
close = [100.0, 101.0, 102.0, 101.5, 103.0, 102.5, 104.0]
high = [101.0, 102.0, 103.0, 102.5, 104.0, 103.5, 105.0]
low = [99.0, 100.0, 101.0, 100.5, 102.0, 101.5, 103.0]
volume = [1000, 1200, 1100, 1300, 1250, 1150, 1400]

# 移动平均线
sma = haze.sma(close, period=5)
ema = haze.ema(close, period=5)

# 动量指标
rsi = haze.rsi(close, period=14)
macd, signal, hist = haze.macd(close, fast=12, slow=26, signal=9)

# 波动率指标
atr = haze.atr(high, low, close, period=14)
upper, middle, lower = haze.bollinger_bands(close, period=20, std_dev=2.0)

# 趋势指标
supertrend, direction = haze.supertrend(high, low, close, period=10, multiplier=3.0)
adx = haze.adx(high, low, close, period=14)

# 成交量指标
obv = haze.obv(close, volume)
vwap = haze.vwap(high, low, close, volume)
```

### Pandas 集成

```python
import pandas as pd
import haze_library

# 加载数据
df = pd.read_csv('ohlcv.csv')

# 使用 .haze 访问器
df['sma_20'] = df['close'].haze.sma(20)
df['rsi_14'] = df['close'].haze.rsi(14)
df['atr_14'] = df.haze.atr(14)

# 布林带（返回多列）
bb = df['close'].haze.bollinger_bands(20, 2.0)
df['bb_upper'] = bb['upper']
df['bb_middle'] = bb['middle']
df['bb_lower'] = bb['lower']
```

### NumPy 接口

```python
import numpy as np
from haze_library import np_ta

close = np.random.randn(1000) + 100

# 计算指标（返回 np.ndarray）
sma = np_ta.sma(close, period=20)
rsi = np_ta.rsi(close, period=14)
macd, signal, hist = np_ta.macd(close)
```

### 流式计算（实时数据）

```python
from haze_library.streaming import (
    IncrementalSMA,
    IncrementalRSI,
    IncrementalMACD,
    IncrementalBollingerBands,
)

# 创建流式计算器
sma = IncrementalSMA(period=20)
rsi = IncrementalRSI(period=14)
macd = IncrementalMACD(fast=12, slow=26, signal=9)

# 逐个数据点更新（O(1) 复杂度）
for price in realtime_prices:
    sma_value = sma.update(price)
    rsi_value = rsi.update(price)
    macd_line, signal_line, histogram = macd.update(price)

    print(f"SMA: {sma_value:.2f}, RSI: {rsi_value:.2f}")
```

### 谐波形态检测

```python
import haze_library as haze

# 检测 XABCD 谐波形态
# 返回：信号(1=看涨/-1=看跌)、PRZ上沿、PRZ下沿、完成概率
signals, prz_up, prz_lo, prob = haze.harmonics(high, low, close)

# 获取详细形态信息
patterns = haze.harmonics_patterns(high, low, left_bars=5, right_bars=5)
for p in patterns:
    print(f"{p.pattern_type_zh}: {p.state}")
    print(f"  PRZ 中心: {p.prz_center:.2f}")
    print(f"  完成概率: {p.completion_probability:.1%}")
```

### 机器学习模型

```python
from haze_library import ml

# 特征提取
features = ml.extract_features(close, high, low, volume)

# 训练 SVM 模型
model = ml.train_svm(features, labels)

# 预测
predictions = model.predict(new_features)
```

### 🤖 LT 组合指标系统 (v1.1.0+)

**LT (Long-Term) 组合指标系统**集成了 10 个 SFG (Smart Financial Group) 专业交易信号指标，具备市场状态自适应权重调整和加权集成投票逻辑，适用于中长期趋势交易。

#### 快速开始

```python
import numpy as np
from haze_library import lt_indicator

# 准备价格数据（至少 500+ 个数据点以获得稳定信号）
n = 1000
high = np.array([100.0 + i * 0.1 + np.random.rand() * 2 for i in range(n)])
low = np.array([100.0 + i * 0.1 - np.random.rand() * 2 for i in range(n)])
close = np.array([100.0 + i * 0.1 for i in range(n)])
volume = np.array([1000.0 + np.random.rand() * 500 for _ in range(n)])

# 计算 LT 组合指标
result = lt_indicator(high, low, close, volume)

# 查看最终信号
print(f"交易信号: {result['ensemble']['final_signal']}")  # BUY / SELL / NEUTRAL
print(f"信号强度: {result['ensemble']['confidence']:.2%}")  # 0-100%
print(f"市场状态: {result['market_regime']}")  # TRENDING / RANGING / VOLATILE
```

#### 10 个 SFG 指标详解

| # | 指标名称 | 说明 | 适用场景 |
|---|---------|------|---------|
| 1 | **AI SuperTrend** | KNN + SuperTrend 机器学习增强 | 趋势跟踪 + 智能预测 |
| 2 | **ATR2 Signals** | ATR + MLMI 多层次预测 | 波动率自适应入场 |
| 3 | **Pivot Points** | 枢轴点 + 跟踪止损 | 支撑阻力位突破 |
| 4 | **AI Momentum** | KNN + RSI 关系预测 | 动量反转捕捉 |
| 5 | **Volume Profile** | 成交量分布 + POC/VAH/VAL | 高成交量区域识别 |
| 6 | **General Parameters** | 动态 EMA 通道 | 趋势强度确认 |
| 7 | **Market Structure** | BOS/CHoCH + Fair Value Gap | 市场结构转换 |
| 8 | **PD Array** | Premium/Discount + 突破区块 | 价格失衡修复 |
| 9 | **Linear Regression** | 多时间框架支撑阻力 | 均值回归交易 |
| 10 | **Dynamic MACD + HA** | MACD + 平均 K 线 | 趋势延续验证 |

#### 市场状态自适应

系统自动检测 3 种市场状态并动态调整指标权重：

```python
# 查看当前市场状态
regime = result['market_regime']
print(f"市场状态: {regime}")

# 不同市场状态的权重策略
if regime == "TRENDING":
    # 趋势指标权重高 (SuperTrend, MACD, Regression)
    print("→ 适合趋势跟踪策略")
elif regime == "RANGING":
    # 均值回归指标权重高 (Pivot, Volume Profile)
    print("→ 适合区间交易策略")
elif regime == "VOLATILE":
    # 波动率指标权重高 (ATR2, Market Structure)
    print("→ 适合波动率突破策略")
```

#### 详细信号分析

```python
# 查看所有指标的独立信号
for name, data in result['indicators'].items():
    signal = data.get('signal', 'N/A')
    confidence = data.get('confidence', 0.0)
    print(f"{name:30} -> {signal:8} ({confidence:.1%})")

# 示例输出:
# ai_supertrend               -> BUY      (85.3%)
# atr2_signals                -> BUY      (72.1%)
# ai_momentum                 -> NEUTRAL  (45.0%)
# volume_profile              -> SELL     (38.2%)
# ...

# 集成投票结果
ensemble = result['ensemble']
print(f"\n最终信号: {ensemble['final_signal']}")
print(f"多头票数: {ensemble['bullish_votes']}")
print(f"空头票数: {ensemble['bearish_votes']}")
print(f"中性票数: {ensemble['neutral_votes']}")
print(f"综合信心: {ensemble['confidence']:.2%}")
```

#### 实战应用示例

```python
import pandas as pd
from haze_library import lt_indicator

# 加载真实市场数据
df = pd.read_csv('BTC_USDT_1h.csv')  # 至少 500+ 行数据

# 计算 LT 信号
result = lt_indicator(
    df['high'].values,
    df['low'].values,
    df['close'].values,
    df['volume'].values
)

# 获取最新信号
signal = result['ensemble']['final_signal']
confidence = result['ensemble']['confidence']
regime = result['market_regime']

# 交易逻辑
if signal == "BUY" and confidence > 0.6:
    if regime == "TRENDING":
        print("✅ 强烈看涨信号 - 开多仓 (趋势跟踪)")
    elif regime == "RANGING":
        print("✅ 看涨信号 - 区间下沿做多")
    else:
        print("⚠️  看涨信号 - 高波动期谨慎操作")

elif signal == "SELL" and confidence > 0.6:
    if regime == "TRENDING":
        print("❌ 强烈看跌信号 - 开空仓 (趋势跟踪)")
    elif regime == "RANGING":
        print("❌ 看跌信号 - 区间上沿做空")
    else:
        print("⚠️  看跌信号 - 高波动期谨慎操作")

else:
    print("⏸️  中性信号 - 观望等待更明确机会")

# 风险管理建议
if confidence < 0.4:
    print("⚠️  低信心信号 - 建议减小仓位或不交易")
elif confidence < 0.6:
    print("ℹ️  中等信心 - 标准仓位")
else:
    print("💪 高信心信号 - 可适当增加仓位（不超过最大仓位限制）")
```

#### 最佳实践

1. **数据量要求**: 至少 500 个数据点（推荐 1000+）以获得稳定信号
2. **时间周期**: 适用于 1H / 4H / 1D 周期，中长期趋势交易
3. **信号确认**:
   - `confidence > 0.6` 为高质量信号
   - `confidence < 0.4` 建议观望
4. **市场适应**:
   - TRENDING: 顺势交易，持仓时间较长
   - RANGING: 区间交易，快进快出
   - VOLATILE: 谨慎操作，严格止损
5. **风险控制**:
   - 永远设置止损（建议 2-3 倍 ATR）
   - 单笔仓位不超过总资金 5-10%
   - 多个信号确认后再入场

---

## 📊 指标分类

### 移动平均线（16 个）

| 指标 | 说明 | 函数 |
|------|------|------|
| SMA | 简单移动平均 | `sma(close, period)` |
| EMA | 指数移动平均 | `ema(close, period)` |
| WMA | 加权移动平均 | `wma(close, period)` |
| DEMA | 双重指数移动平均 | `dema(close, period)` |
| TEMA | 三重指数移动平均 | `tema(close, period)` |
| KAMA | 考夫曼自适应移动平均 | `kama(close, period)` |
| HMA | 赫尔移动平均 | `hma(close, period)` |
| ZLMA | 零延迟移动平均 | `zlma(close, period)` |
| T3 | T3 移动平均 | `t3(close, period)` |
| ALMA | 阿尔诺德移动平均 | `alma(close, period)` |
| FRAMA | 分形自适应移动平均 | `frama(close, period)` |
| VIDYA | 变量指数动态平均 | `vidya(close, period)` |
| RMA | 相对移动平均 | `rma(close, period)` |
| SWMA | 正弦加权移动平均 | `swma(close)` |
| PWMA | 帕斯卡加权移动平均 | `pwma(close, period)` |
| SINWMA | 正弦权重移动平均 | `sinwma(close, period)` |

### 动量指标（17 个）

| 指标 | 说明 | 函数 |
|------|------|------|
| RSI | 相对强弱指标 | `rsi(close, period)` |
| MACD | 指数平滑异同移动平均 | `macd(close, fast, slow, signal)` |
| Stochastic | 随机指标 | `stochastic(high, low, close, k, d)` |
| CCI | 商品通道指数 | `cci(high, low, close, period)` |
| MFI | 资金流量指标 | `mfi(high, low, close, volume, period)` |
| Williams %R | 威廉指标 | `willr(high, low, close, period)` |
| ROC | 变化率 | `roc(close, period)` |
| MOM | 动量 | `mom(close, period)` |
| KDJ | 随机指标 KDJ | `kdj(high, low, close, k, d, j)` |
| TSI | 真实强度指数 | `tsi(close, fast, slow)` |
| Stoch RSI | 随机 RSI | `stochrsi(close, period)` |
| Ultimate | 终极振荡器 | `ultimate(high, low, close)` |
| Awesome | 动量震荡指标 | `awesome(high, low)` |
| Fisher | 费舍尔变换 | `fisher(high, low, period)` |
| APO | 绝对价格振荡器 | `apo(close, fast, slow)` |
| PPO | 百分比价格振荡器 | `ppo(close, fast, slow)` |
| CMO | 钱德动量振荡器 | `cmo(close, period)` |

### 波动率指标（10 个）

| 指标 | 说明 | 函数 |
|------|------|------|
| ATR | 平均真实波幅 | `atr(high, low, close, period)` |
| NATR | 归一化 ATR | `natr(high, low, close, period)` |
| Bollinger | 布林带 | `bollinger_bands(close, period, std)` |
| Keltner | 肯特纳通道 | `keltner(high, low, close, period)` |
| Donchian | 唐奇安通道 | `donchian(high, low, period)` |
| Chandelier | 吊灯止损 | `chandelier(high, low, close, period)` |
| HV | 历史波动率 | `historical_volatility(close, period)` |
| Ulcer | 溃疡指数 | `ulcer_index(close, period)` |
| Mass | 质量指数 | `mass_index(high, low)` |
| True Range | 真实波幅 | `true_range(high, low, close)` |

### 趋势指标（14 个）

| 指标 | 说明 | 函数 |
|------|------|------|
| SuperTrend | 超级趋势 | `supertrend(high, low, close, period, mult)` |
| ADX | 平均趋向指数 | `adx(high, low, close, period)` |
| SAR | 抛物线转向 | `sar(high, low, accel, max_accel)` |
| Aroon | 阿隆指标 | `aroon(high, low, period)` |
| DMI | 方向移动指数 | `dmi(high, low, close, period)` |
| TRIX | 三重平滑 EMA | `trix(close, period)` |
| DPO | 去趋势价格振荡器 | `dpo(close, period)` |
| Vortex | 涡流指标 | `vortex(high, low, close, period)` |
| Choppiness | 震荡指数 | `choppiness(high, low, close, period)` |
| VHF | 垂直水平过滤器 | `vhf(close, period)` |
| QStick | 量价棒 | `qstick(open, close, period)` |
| DX | 趋向指数 | `dx(high, low, close, period)` |
| +DI | 正向指标 | `plus_di(high, low, close, period)` |
| -DI | 负向指标 | `minus_di(high, low, close, period)` |

### 成交量指标（11 个）

| 指标 | 说明 | 函数 |
|------|------|------|
| OBV | 能量潮 | `obv(close, volume)` |
| VWAP | 成交量加权均价 | `vwap(high, low, close, volume)` |
| CMF | 蔡金资金流量 | `cmf(high, low, close, volume, period)` |
| Force | 劲道指数 | `force_index(close, volume, period)` |
| VO | 成交量振荡器 | `volume_oscillator(volume, fast, slow)` |
| AD | 累积/派发线 | `ad(high, low, close, volume)` |
| PVT | 价量趋势 | `pvt(close, volume)` |
| NVI | 负量指标 | `nvi(close, volume)` |
| PVI | 正量指标 | `pvi(close, volume)` |
| EOM | 简易波动指标 | `eom(high, low, volume, period)` |
| ADOSC | AD 振荡器 | `adosc(high, low, close, volume, fast, slow)` |

### 蜡烛图形态（61 个）

支持所有主流 K 线形态识别：

- **反转形态**：锤子线、上吊线、吞没形态、孕线、十字星、早晨之星、黄昏之星等
- **持续形态**：三白兵、三黑鸦、跳空缺口等
- **中性形态**：高浪线、陀螺线等

```python
# 检测蜡烛图形态
patterns = haze.detect_candlestick_patterns(open, high, low, close)
```

### 其他指标

- **统计指标（13 个）**：线性回归、相关性、Z 分数、贝塔系数等
- **价格变换（4 个）**：平均价格、中间价、典型价格等
- **数学运算（25 个）**：各类数学函数
- **周期指标（5 个）**：希尔伯特变换系列
- **谐波形态（3 个）**：XABCD 形态检测
- **高级信号（4 个）**：AI SuperTrend、动态 MACD 等

---

## 🏗️ 系统架构

```
┌──────────────────────────────────────────────────────────┐
│                    Python 应用层                          │
│            （交易策略 / 数据分析 / 回测系统）               │
└─────────────────────────┬────────────────────────────────┘
                          │
          ┌───────────────┼───────────────┐
          │               │               │
          ▼               ▼               ▼
┌─────────────┐   ┌─────────────┐   ┌─────────────┐
│  np_ta      │   │  pandas     │   │  polars_ta  │
│  (NumPy)    │   │  accessor   │   │  (Polars)   │
└──────┬──────┘   └──────┬──────┘   └──────┬──────┘
       │                 │                 │
       └─────────────────┼─────────────────┘
                         │
                         ▼
┌──────────────────────────────────────────────────────────┐
│              haze_library (PyO3 绑定)                     │
│         215+ 指标函数 + 流式计算器 + ML 模型              │
└─────────────────────────┬────────────────────────────────┘
                          │
                          ▼
┌──────────────────────────────────────────────────────────┐
│                   Rust 核心库                             │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐         │
│  │ indicators │  │  streaming │  │     ml     │         │
│  │ 技术指标   │  │  流式计算   │  │  机器学习   │         │
│  └────────────┘  └────────────┘  └────────────┘         │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐         │
│  │   utils    │  │   types    │  │   errors   │         │
│  │  工具函数   │  │   类型定义  │  │   错误处理  │         │
│  └────────────┘  └────────────┘  └────────────┘         │
└──────────────────────────────────────────────────────────┘
```

---

## 🎯 性能基准

测试环境：10,000 个数据点

| 指标 | pandas-ta | TA-Lib | Haze-Library | 加速比 |
|------|-----------|--------|--------------|--------|
| RSI (14) | 12.5 ms | 8.2 ms | **1.3 ms** | 6.3x |
| Bollinger (20) | 15.8 ms | 10.1 ms | **2.1 ms** | 4.8x |
| MACD (12/26/9) | 18.3 ms | 11.4 ms | **1.9 ms** | 6.0x |
| SuperTrend (10) | 22.1 ms | - | **2.8 ms** | 7.9x |
| ADX (14) | 19.5 ms | 12.3 ms | **2.2 ms** | 5.6x |

---

## 🧮 数值稳定性

Haze-Library 采用多种技术确保数值计算的精确性：

- **f64 精度**：所有计算使用 64 位浮点数
- **Kahan 求和**：长序列累加使用补偿求和算法
- **Welford 算法**：方差/标准差使用增量算法避免数值溢出
- **精度验证**：所有指标与参考实现对比误差 < 1e-9

---

## ⚠️ 错误处理

```python
import haze_library as haze

try:
    # 周期过大
    rsi = haze.rsi([100, 101, 102], period=14)
except ValueError as e:
    print(f"错误: {e}")
    # 输出: Invalid period: 14 (must be > 0 and <= data length 3)

try:
    # 数组长度不匹配
    atr = haze.atr([101, 102], [99, 100], [100, 101, 102], period=2)
except ValueError as e:
    print(f"错误: {e}")
    # 输出: Length mismatch

try:
    # 空数据
    rsi = haze.rsi([], period=14)
except ValueError as e:
    print(f"错误: {e}")
    # 输出: Empty input
```

---

## 💹 交易执行（可选）

需要安装 `haze-library[execution]`：

```python
from haze_library.execution import ExecutionEngine, ExecutionPermissions
from haze_library.execution.providers.ccxt import CCXTProvider

# 创建交易执行引擎
provider = CCXTProvider(
    exchange="binance",
    api_key="your_key",
    api_secret="your_secret",
)

permissions = ExecutionPermissions(
    live_trading=True,
    max_notional_per_order=1000.0,  # 单笔最大 1000 USDT
)

engine = ExecutionEngine(provider=provider, permissions=permissions)

# 下单
from haze_library.execution.models import CreateOrderRequest

order_req = CreateOrderRequest(
    symbol="BTC/USDT",
    side="buy",
    order_type="limit",
    amount=0.001,
    price=50000.0,
)

order, check = engine.place_order(order_req)
print(f"订单 ID: {order.id}")
```

---

## 📜 许可证 / License

本项目为**专有软件**，保留所有权利。

This project is **proprietary software**. All rights reserved.

- ❌ 禁止未经授权的使用 / Unauthorized use prohibited
- ✅ 商业许可可用 / Commercial licenses available

许可咨询 / Licensing inquiries: team@haze-library.com

---

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

详见 [CONTRIBUTING.md](CONTRIBUTING.md)

---

## 🙏 致谢

- [TA-Lib](https://ta-lib.org/) - 技术分析参考实现
- [pandas-ta](https://github.com/twopirllc/pandas-ta) - Pandas 集成灵感
- [PyO3](https://pyo3.rs/) - Rust-Python 绑定
- [Maturin](https://github.com/PyO3/maturin) - 构建工具

---

**Made with ❤️ by the Haze Team**

**版本**: 1.1.3 | **更新日期**: 2025-12-30