Metadata-Version: 2.4
Name: tp-quant
Version: 1.0.0
Summary: Trading Pattern Scanner Identifies complex patterns like head and shoulder, wedge and many more.
Author: Preetam Sharma
License: CC BY-NC-SA 4.0
Requires-Python: ==3.12.*
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: numpy>=2.0.0
Requires-Dist: pandas<4,>=3.0.0
Requires-Dist: kdata-quant==1.0.0
Requires-Dist: mootdx2>=1.0.8
Requires-Dist: TA-Lib>=0.4.32
Requires-Dist: pyyaml>=6.0
Provides-Extra: backtest
Requires-Dist: backtrader>=1.9.78.123; extra == "backtest"
Dynamic: license-file

# tp-quant (Trading Pattern Scanner)

`tp-quant` 是一个高性能的 Python 量化交易模式识别与预筛选库，内置 10+ 种几何经典形态检测、10+ 种 TA-Lib K 线形态识别，以及基于量价与指标体系的综合强度评分系统。

---

## 核心亮点

- **几何与 K 线形态识别**：自动检测头肩顶/底、三角形、楔形、双顶/底、通道等经典形态及多种 K 线组合形态。
- **工业级 TA-Lib 集成**：深度整合 TA-Lib 库，所有基础技术指标（RSI, MACD, ADX, EMA 等）均经过向量化加速与稳定性校验。
- **智能量化评分**：独有的 0-10 分综合评分体系，结合趋势维度、动能因子、成交量配合及确认信号进行动态分级。
- **高并发与高性能**：基于 **Pandas 3.x** 与 **NumPy 2.x** 进行向量化优化，支持多线程并发扫描与大数据集处理。
- **双模体验**：同时提供简洁易用的 **Python API** 以及功能完善的**统一命令行工具 (`tp`)**。
- **策略回测支持**：原生集成 `backtrader` 回测引擎，支持形态买卖信号的快速历史回测与绩效评估。

---

## 安装说明

### 通过 PyPI 安装
```bash
pip install tp-quant
```

### 包含回测模块安装
```bash
pip install "tp-quant[backtest]"
```

### 源码安装（本地开发）
```bash
git clone https://github.com/your-repo/tp-quant.git
cd tp-quant
pip install -e .
```

---

## 快速上手 (Python API)

### 1. 基础形态扫描
```python
import pandas as pd
from tradingpatterns import scan_patterns, get_signals

# 加载您的 K 线数据 (包含 open, high, low, close, volume 字段)
df = pd.read_csv("ohlcv_data.csv")

# 扫描形态并获取评分与信号
results = scan_patterns(df)
print(results)
```

### 2. 高级预筛选流水线
```python
from tradingpatterns import pre_screen_and_scan

# 执行预筛选与形态识别流水线
scan_result = pre_screen_and_scan(df, symbol="AAPL")
print("综合评分:", scan_result.get("score"))
print("通过防线:", scan_result.get("passed"))
```

---

## 命令行工具 (`tp`)

安装本项目后，可直接使用统一终端命令 `tp` 进行**形态扫描**与**策略回测**：

### 1. 扫描分析 (`tp scan`)

```bash
# 使用测试行情进行快速体验
tp -s MOCK_SYMBOL --mock

# 指定分析模式（bottom / trend / all）
tp -s MOCK_SYMBOL -m trend --mock

# 输出精简 JSON 格式（便于下游 LLM / 程序接入）
tp -s MOCK_SYMBOL --mock --json-simple 2>/dev/null

# 打印人类可读彩色表格 + Top 1 完整 JSON 结构
tp -s MOCK_SYMBOL --mock --detail
```

**常用参数表：**

| 参数 | 缩写 | 说明 |
|---|---|---|
| `--stock_code` | `-s` | 单个代码标的 |
| `--stocks` | `-S` | 多个代码（逗号分隔） |
| `--file` | `-f` | YAML / 文本文件标的列表 |
| `--mode` | `-m` | 扫描模式：`all` / `bottom` / `trend` |
| `--min-score` | - | 筛选合格的综合得分下限（默认 6.0） |
| `--mock` | - | 使用内置测试行情进行无网调试 |
| `--workers` | - | 并发线程数（默认自动按 CPU 核心数调度） |
| `--json-simple` | - | 输出精简 JSON 数组 |
| `--json` | - | 输出完整 JSON 字段数据 |
| `--detail` | - | 表格渲染 + 最佳标的 JSON 明细 |

### 2. 策略回测 (`tp backtest`)

```bash
# 基于形态信号执行买卖策略回测
tp backtest -s MOCK_SYMBOL --engine pattern --start 2024-01-01
```

---

## 项目结构与文档

更多详细技术设计与使用指南请参阅 `docs/` 目录：

- **[预筛选机制设计](docs/pre_screening_requirements.md)**：六层过滤漏斗（流动性、趋势、形态等）设计架构。
- **[评分体系说明](docs/scoring_mechanisms.md)**：综合 0-10 分评分体系、因子权重与算法原理。
- **[威科夫量价应用](docs/wyckoff_volume_price_method.md)**：威科夫供需量价分析在 K 线筛选中的实现。
- **[网格策略手册](docs/grid/grid_trading_strategy_design.md)**：网格交易计划生成与风险控制参数。

---

## 单元测试

使用 `pytest` 运行完整测试套件：

```bash
pytest
```

---

## 免责声明与许可

### 免责声明
本项目（`tp-quant`）所包含的代码、算法及模型仅供**技术研究、学术交流及定量分析**使用，不构成任何形式的投资建议、财务咨询或交易依据。金融市场有风险，投资需谨慎。依据本项目识别结果或回测结论所进行的任何实际交易决策，风险均由使用者自行承担。

### 许可协议
本项目依据 [CC BY-NC-SA 4.0](LICENSE.md) 协议开源。
