Metadata-Version: 2.4
Name: tp-quant
Version: 1.2.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.1.2
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

# Python API 接口参考文档 (API Reference)

本文档面向需要在下游系统（如 LLM AI Agent、量化自动化交易流水线、复盘看板）中直接集成 `tp-quant` 的开发者。

安装包：`pip install tp-quant`

> [!TIP]
> 🌟 **全频段自适应特性 (Timeframe-Agnostic Adaptation)**  
> 核心引擎（包括各大策略与形态机）内置了自动频率推断。你可以自由传入**日线 (Daily)** 或 **周线 (Weekly)** DataFrame：
> - **内部参数自适应**：算法会自动探测 `df` 的物理间隔（如 1天 vs 7天），并将所有硬编码的 K 线阈值（如横盘 15 天）智能折算（如变更为横盘 3 周）。
> - **多周期共振升维**：涉及“跨周期共振”的策略，输入日线时会自动参考周线，而**输入周线时则会自动升维参考月线 (Monthly)**！无需人工指定参数，实现无缝的小图进场、大图顺势。

---

## 目录索引 (Table of Contents)

1. [全域机会雷达综合引擎 (Combined Opportunity Radar)](#1-全域机会雷达综合引擎-combined-opportunity-radar)
   - 1.1 [统一策略枚举与事件契约 (`StrategyEngine.COMBINED`)](#11-统一策略枚举与事件契约)
   - 1.2 [单标的雷达信号调用 (`get_strategy_signal` / `evaluate_opportunity_radar_item`)](#12-单标的雷达信号调用)
   - 1.3 [全市场多周期雷达批量扫描 (`analyze_opportunity_radar`)](#13-全市场多周期雷达批量扫描)
   - 1.4 [全景回测与实战验证 CLI](#14-全景回测与实战验证-cli)
2. [网格交易与组合资产顾问 (`grid` & `grid_advisor`)](#2-网格交易与组合资产顾问)
   - 2.1 [单标的网格计划 (`build_grid_plan`)](#21-单标的网格计划-build_grid_plan)
   - 2.2 [ETF 网格严选评估 (`evaluate_strict_grid_candidate`)](#22-etf-网格严选评估-evaluate_strict_grid_candidate)
   - 2.3 [网格事件驱动轻量回测 (`simulate_grid_strategy`)](#23-网格事件驱动轻量回测-simulate_grid_strategy)
   - 2.4 [多标的组合网格与 8 步调仓换仓 (`build_etf_grid_advice`)](#24-多标的组合网格与-8-步调仓换仓-build_etf_grid_advice)
3. [技术形态扫描与预筛选管道 (`pre_screen_and_scan`)](#3-技术形态扫描与预筛选管道-pre_screen_and_scan)
   - 3.1 [预筛选与扫描主接口](#31-预筛选与扫描主接口)
   - 3.2 [Context Package 上下文数据包全字段解析](#32-context-package-上下文数据包全字段解析)
   - 3.3 [威科夫量价供需分析 (`detect_wyckoff_context`)](#33-威科夫量价供需分析-detect_wyckoff_context)
4. [市场状态机与多周期趋势评估](#4-市场状态机与多周期趋势评估)
   - 4.1 [综合唯一主状态机 (`detect_side_state`)](#41-综合唯一主状态机-detect_side_state)
   - 4.2 [做多右侧状态机 (`detect_right_side_state`)](#42-做多右侧状态机-detect_right_side_state)
   - 4.3 [底部结构跟踪状态机 (`detect_bottom_tracking_state`)](#43-底部结构跟踪状态机-detect_bottom_tracking_state)
   - 4.4 [独立周线中期趋势质量评分 (`evaluate_weekly_trend`)](#44-独立周线中期趋势质量评分-evaluate_weekly_trend)
5. [市场环境与辅助分析工具](#5-市场环境与辅助分析工具)
   - 5.1 [市场情绪温度计 (`sentiment_thermometer`)](#51-市场情绪温度计-sentiment_thermometer)
   - 5.2 [动态支撑阻力计算 (`calculate_support_resistance`)](#52-动态支撑阻力计算-calculate_support_resistance)
   - 5.3 [组合风险平权与相关性去重](#53-组合风险平权与相关性去重)

---

## 1. 全域机会雷达综合引擎 (Combined Opportunity Radar)

**全域机会雷达综合引擎 (`Combined Radar`) 是系统推荐的唯一全天候量化决策与机会发现中枢**。

它自动融合了三大专精策略的全部优势，形成“三位一体”的完整交易闭环：
1. **左侧绝望拐点**：由 **Engine 2 (极限反转)** 率先在 52 周最低超跌区抄底阻击；
2. **右侧主升浪确立**：由 **Engine 1 (趋势突破)** 在突破防守线或真阳企稳时重仓顺势跟进；
3. **全天候自适应跟踪**：由 **Engine 3 (Kaufman 趋势)** 依托 KAMA 均线、效率比率与抛物线乖离率全程移动锁利与冲顶止盈。

```
                  ┌────────────────────────────────────────────────────────────┐
                  │              StrategySignalEvent 统一信号契约              │
                  │  (buy_signal, sell_signal, stop_loss, take_profit, reason) │
                  └─────────────────────────────┬──────────────────────────────┘
                                                │
                          【Combined Opportunity Radar 综合雷达】
                       StrategyEngine.COMBINED / analyze_opportunity_radar
                                                │
         ┌──────────────────────────────┼──────────────────────────────┐
         ▼                              ▼                              ▼
【左侧超跌拐点抄底】            【右侧主升浪首发/接力】        【全天候自适应跟踪/冲顶】
  Engine 2 (极限反转)             Engine 1 (趋势突破)           Engine 3 (Kaufman趋势)
```

---

### 1.1 统一策略枚举与事件契约

```python
from tradingpatterns import (
    StrategyEngine,                 # 核心策略枚举类 (COMBINED, ENGINE1_TREND, ENGINE2_REVERSAL, ENGINE3_KAUFMAN)
    EngineType,                     # StrategyEngine 别名
    get_strategy_signal,            # 顶层统一策略信号分发器
    evaluate_opportunity_radar_item,# 单标的全维度雷达评估
    analyze_opportunity_radar,      # 全池多周期雷达批量扫描
    StrategySignalEvent,            # 统一信号事件基类
)
```

#### 统一返回对象 (`StrategySignalEvent` 标准契约)：
支持属性访问（`sig.buy_signal`）与字典键访问（`sig["buy_signal"]`）：

| 字段/属性 | 类型 | 说明 |
| :--- | :--- | :--- |
| **`buy_signal`** | `bool` | 是否触发次日开盘买入信号。 |
| **`sell_signal`** | `bool` | 是否触发次日开盘卖出/离场信号。 |
| **`stop_loss`** | `float` | 建议的量化止损防守线（破位即走，内置 $\le 7\%$ 硬风险兜底）。 |
| **`take_profit`** | `float` | 建议的目标止盈价/关键阻力位（到达考虑减仓止盈）。 |
| **`signal_tier`** | `str \| None` | 信号确定性分级 (`"L3"` 强信号 \| `"L2"` 中等/接力 \| `"L1"` 预警关注 \| `None`)。 |
| **`reason`** | `str` | 信号触发的详细原因说明。 |
| **`state`** | `str` | 策略内部状态机状态 / 体制（如 `"RIGHT_CONFIRMED"`, `"TREND_BULL"`, `"TRIGGERED"`）。 |
| **`symbol`** | `str` | 标的代码。 |
| **`date`** | `str` | 信号产生的 K 线日期 (`YYYY-MM-DD`)。 |
| **`details`** | `dict` | 包含三大引擎底层指标、KAMA 生命线与形态元数据的完整字典。 |

---

### 1.2 单标的雷达信号调用

#### 方式一：调用标准策略引擎接口 (`StrategyEngine.COMBINED`)
```python
import tradingpatterns as tp
import kdata

# 抓取日线 OHLCV 数据
df = kdata.get_ohlc("513120", "2024-01-01", "2026-08-19")
df_mkt = kdata.get_ohlc("510300", "2024-01-01", "2026-08-19")

# 运行全域机会雷达综合决策
sig = tp.get_strategy_signal(
    tp.StrategyEngine.COMBINED, 
    df, 
    symbol="513120", 
    market_df=df_mkt,
    use_multitimeframe=True,
    pnl_max_pct=0.15,          # 可选：传入当前持仓最高浮盈用于阶段动态锁利
    holding_bars=10            # 可选：传入已持仓天数
)

if sig.buy_signal:
    print(f"【🔥买入提示】{sig.strategy_name} ({sig.signal_tier}) | 建议止损: {sig.stop_loss:.3f} | 原因: {sig.reason}")
elif sig.sell_signal:
    print(f"【🛑卖出提示】{sig.strategy_name} | 原因: {sig.reason}")
```

#### 方式二：调用单标的全维度雷达评估 (`evaluate_opportunity_radar_item`)
```python
from tradingpatterns import evaluate_opportunity_radar_item

item_res = evaluate_opportunity_radar_item(
    df=df,
    symbol="515880",
    name="通信ETF",
    frequency="weekly",      # "weekly" (周频) 或 "daily" (日频)
    min_amount_ea=None,      # 异动成交额门槛 (亿)，None 时自动取默认
    min_vol_ratio=1.5,       # 放量倍数门槛 (默认 1.5 倍)
    min_pct_change=1.5,      # 涨跌幅门槛 (默认 1.5%)
    weekly_mode="early",     # 周线模式
)

print(f"机会来源: {item_res['primary_opp_source']}")
print(f"状态变迁: {item_res['prev_state_cn']} ━━➔ {item_res['curr_state_cn']}")
print(f"建议防守线: {item_res['suggested_stop_loss']}")
```

**核心输出字段**：
- `has_buy_signal` (bool): 是否触发任一核心买点。
- `has_sell_signal` (bool): 是否触发离场/移动止损/止盈信号。
- `opp_sources` (List[str]): 机会来源组合（包含 `"ENGINE1"`, `"ENGINE2"`, `"ENGINE3"`）。
- `primary_opp_source` (str): 主导机会来源中文说明。
- `signal_tier`: 最高信号级别 (`"L3"` 强信号 \| `"L2"` 中等/接力 \| `"L1"` 预警关注)。
- `is_opportunity` (bool): 是否归入【潜在机会】。
- `is_vol_abnormal` (bool): 是否归入【量化异动】。
- `is_risk` (bool): 是否归入【风险提示】。

---

### 1.3 全市场多周期雷达批量扫描

雷达模块负责全市场标的实时扫描、多引擎信号聚合、时效性降级 (Staleness Check) 以及多栏目去重归类，可直接作为**自媒体每日内容生产工具**与**选品大漏斗**：

```python
from tradingpatterns import analyze_opportunity_radar

# 批量扫描标的池
vol_list, opp_list, risk_list = analyze_opportunity_radar(
    etf_pool={"515880": ("通信ETF", df1), "512880": ("证券ETF", df2), "513120": ("港股创新药", df3)},
    frequency="weekly",   # "weekly" 或 "daily"
    min_amount_ea=None,
    min_vol_ratio=1.5,
    min_pct_change=1.5,
)

# 自动格式化输出自媒体复盘日报
print(f"📊 【量化机会雷达 | 今日全市场扫描】\n")

print("🔥 【核心策略引擎触发】")
for item in opp_list:
    if item["opp_sources"]:
        print(f"• [{item['primary_opp_source']}] {item['symbol']} {item['name']}: 建议防守位 {item['stop_loss']:.3f}")

print("\n👀 【蓄势预热池】")
for item in opp_list:
    if not item["opp_sources"] and item["curr_state_cn"] in ["筑底成熟", "启动预热", "蓄势待发"]:
        print(f"• {item['symbol']} {item['name']}: 状态【{item['curr_state_cn']}】, 均线贴近支撑")

print("\n⚠️ 【风险预警】")
for item in risk_list:
    print(f"• {item['symbol']} {item['name']}: 状态【{item['curr_state_cn']}】, 警惕回调风险")
```

---

### 1.4 全景回测与实战验证 CLI

项目提供多周期（日线/周线/双周期对比）与多进程批量回测 CLI 工具：

```bash
# 1. 综合雷达全池日周双周期回测 (前向盲持触发胜率 + 实盘闭环仿真)
uv run python scripts/backtest_opportunity_radar.py -f data/etf/fliter_cn.yaml -t both --start 2024-01-01 --end 2026-01-01

# 2. 单标的回测并生成 K 线买卖点标注图
uv run python scripts/backtest_opportunity_radar.py -s 510050 -t both -p

# 3. 综合雷达标准策略引擎批量回测 (Combined Radar)
uv run python scripts/backtest_engines.py -f data/etf/fliter_cn.yaml -e combined -t both --start 2024-01-01 --end 2026-01-01
```

---

## 2. 网格交易与组合资产顾问

网格模块提供**震荡市均值回归套利**的完整量化解决方案，包括单标的几何 ATR 网格构建、ETF 专属最优参数池、事件驱动回测引擎与组合层 8 步调仓换仓顾问。

### 2.1 单标的网格计划：`build_grid_plan`

```python
from tradingpatterns import build_grid_plan

plan = build_grid_plan(
    df,
    symbol="510300",
    capital=100000.0,
    grid_count=8,
    min_step_pct=0.008,
    max_step_pct=0.035,
    base_position_pct=0.30,
    max_position_pct=0.80,
    allocation_style="equal",    # "equal" 等额 或 "pyramid" 金字塔加权
    weekly=False,                # True 时按周线自适应
)
```

**返回值核心字段**：
- `state`: 网格状态枚举（`GRID_ACTIVE` 适合开网, `PAUSED_TREND_UP` 向上突破暂停买入, `FAILED_BREAKDOWN` 跌破止损, `RESET_REQUIRED` 需要重置, `WAIT_RANGE` 等待区间）。
- `is_grid_tradeable` (bool): 当前是否满足开网条件。
- `orders` (list[dict]): 包含具体买卖挂单价格与份额的委托计划。
- `next_triggers` (dict): 最近的下一买入与卖出触发价位。

---

### 2.2 ETF 网格严选评估：`evaluate_strict_grid_candidate`

一站式评估标的是否符合开启网格的严苛风控标准（包含趋势形态过滤、区间位置与收益率下限）：

```python
from tradingpatterns import evaluate_strict_grid_candidate, get_etf_optimal_grid_params

res = evaluate_strict_grid_candidate(
    df,
    symbol="515880",
    capital=100000.0,
    grid_count=8,
    name="通信ETF",
    is_weekly_grid=True          # 启用周线大网格模式
)

if res["is_strict_pass"]:
    print("通过严选，可开启网格交易！")
else:
    print(f"未通过原因: {res['strict_fail_reasons']}")
```

- **内置最优参数表 (`ETF_WEEKLY_OPTIMAL_PARAMS`)**：系统内置 44 只核心 ETF 的周线实证最优参数，启用 `is_weekly_grid=True` 时会自动覆盖为最优配置。

---

### 2.3 网格事件驱动轻量回测：`simulate_grid_strategy`

基于“收盘确认、次日开盘成交”原则的轻量事件驱动回测引擎：

```python
from tradingpatterns import simulate_grid_strategy

backtest = simulate_grid_strategy(
    df,
    symbol="510300",
    capital=100000.0,
    grid_count=8,
    max_loss_pct=0.12            # 账户最大亏损强制止损阈值 (12%)
)

print(f"总收益率: {backtest['summary']['return_pct']}%")
print(f"最大回撤: {backtest['summary']['max_drawdown_pct']}%")
print(f"网格往返套利次数: {backtest['summary']['grid_roundtrips']}")
```

---

### 2.4 多标的组合网格与 8 步调仓换仓：`build_etf_grid_advice`

针对大容量 ETF 池在固定持仓上限（如 `max_active_symbols = 10`）下的组合网格交易与资金统筹调度：

```python
from tradingpatterns import build_etf_grid_advice, compute_candidate_score

advice = build_etf_grid_advice(
    pool=etf_dfs_dict,
    asof_date="2026-08-19",
    max_active_symbols=10,
    capital=1000000.0,
    min_holding_days=20,
    min_switch_score_gap=15.0    # 候补第一名分差领先 15 分触发调仓
)
```

---

## 3. 技术形态扫描与预筛选管道 (`pre_screen_and_scan`)

### 3.1 预筛选与扫描主接口

一体化的预筛选与形态扫描管道 (v2.4)，结合生命周期、趋势环境与量价配合度，对标的进行严格漏斗过滤并生成详尽的 **Context Package**。

```python
from tradingpatterns import pre_screen_and_scan

# 单标的诊断/扫描
result = pre_screen_and_scan(df, symbol="sh.600519", min_score=6.0)

# 批量扫描
results = pre_screen_and_scan(jobs, min_score=6.0, max_workers=8)
```

---

### 3.2 Context Package 上下文数据包全字段解析

```json
{
  "symbol": "sh.600519",
  "name": "贵州茅台",
  "total_score": 8.5,
  "pre_screen_passed": true,
  "rejection_reason": null,
  "pre_screen": {
    "strategy_hint": "趋势跟随",
    "priority_score": 0.88,
    "urgency": "MEDIUM",
    "signal_age_days": 2,
    "stale": false,
    "stop_infeasible": false
  },
  "trend_structure": {
    "ema_alignment": "bullish_aligned",
    "adx": 28.5
  },
  "volume": {
    "vr": 1.1,
    "vr_type": "正常",
    "obv_accumulation": true
  },
  "wyckoff": {
    "phase": "accumulation",
    "event": "spring",
    "bias": "demand"
  },
  "weekly_context": {
    "weekly_trend_direction": "bullish"
  },
  "calculated_constraints": {
    "max_position_pct": 30,
    "min_rrr": 1.2
  }
}
```

| 字段路径 | 说明 |
| :--- | :--- |
| **`total_score`** | 日线预筛选 0~10 排序总分（由优先级、最高形态分、置信度、共振项加权生成）。 |
| **`pre_screen.strategy_hint`** | 建议策略框架（`趋势跟随`, `底部反转`, `区间震荡`, `等待突破`, `观望`）。 |
| **`pre_screen.stop_infeasible`** | 止损不可行硬标记（价格偏离技术位超过允许的 ATR 上限）。 |
| **`wyckoff`** | 威科夫供需分析结果 (`phase`, `event`, `bias`, `score`)。 |
| **`calculated_constraints`** | 系统预计算的风控约束（建议最大仓位比例、最小盈亏比、最大止损宽容度）。 |

---

### 3.3 威科夫量价供需分析：`detect_wyckoff_context`

```python
from tradingpatterns import detect_wyckoff_context

wyckoff = detect_wyckoff_context(df)
print(wyckoff["phase"], wyckoff["event"], wyckoff["bias"])
```

---

## 4. 市场状态机与多周期趋势评估

### 4.1 综合唯一主状态机：`detect_side_state`

将筑底状态与右侧趋势合并为全局唯一主状态：

```python
from tradingpatterns import detect_side_state, SideState

res = detect_side_state(df, weekly_mode="balanced")
print(f"主状态: {res['state']} | 来源: {res['state_source']}")
```

---

### 4.2 做多右侧状态机：`detect_right_side_state`

```python
from tradingpatterns import detect_right_side_state, RightSideState

rs = detect_right_side_state(df, weekly_mode="balanced")
# 状态包括: BASE, CANDIDATE, RIGHT_CONFIRMED, RIGHT_ACTIVE, RIGHT_EXTENDED, FAILED
```

---

### 4.3 底部结构跟踪状态机：`detect_bottom_tracking_state`

```python
from tradingpatterns import detect_bottom_tracking_state, BottomTrackingState

bt = detect_bottom_tracking_state(df)
# 状态包括: DECLINING, BOTTOM_WATCH, BOTTOM_BUILDING, BOTTOM_MATURE, STARTUP_PREHEAT, BOTTOM_FAILED
```

---

### 4.4 独立周线中期趋势质量评分：`evaluate_weekly_trend`

独立的中期周线质量评分系统（0~100 分），不参与日线预筛选总分合成：

```python
from tradingpatterns import evaluate_weekly_trend, evaluate_weekly_trends

res = evaluate_weekly_trend(df, symbol="512880")
print(f"周线评分: {res['weekly_trend_score']} | 评级: {res['rating']}")
```

---

## 5. 市场环境与辅助分析工具

### 5.1 市场情绪温度计：`sentiment_thermometer`

提供 A 股市场整体情绪温度（0~100）的计算、自适应历史分位数归一化及情绪状态分级：

```python
from tradingpatterns import (
    compute_sentiment_snapshot,
    compute_sentiment_series,
    DEFAULT_CONFIG,
    SentimentConfig
)

# 1. 单日情绪快照 (推荐使用周频 freq="W" 进行波段择时)
snapshot = compute_sentiment_snapshot(date="2026-08-19", config=SentimentConfig(freq="W"))
print(f"情绪温度: {snapshot['temperature']} | 状态: {snapshot['state']} | 趋势: {snapshot['direction']}")

# 状态包含: ICE_COLD (≤15 极佳中线左侧区), COLD (15~35), NEUTRAL (35~65), HOT (65~85), OVERHEAT (≥85 止盈防守区)
```

---

### 5.2 动态支撑阻力计算：`calculate_support_resistance`

```python
from tradingpatterns import calculate_support_resistance

sr_df = calculate_support_resistance(df, window=3)
current_support = sr_df["support"].dropna().iloc[-1]
```

---

### 5.3 组合风险平权与相关性去重

```python
from tradingpatterns import filter_correlated_assets, volatility_adjusted_position_sizing

# 1. 过滤高相关性同质化标的 (相关系数 > 0.8)
kept_symbols = filter_correlated_assets(returns_df, scores_dict, threshold=0.80)

# 2. 基于 ATR 倒数的风险平权资金分配 (Risk Parity)
weights = volatility_adjusted_position_sizing(atr_dict, total_capital=100000.0)
```
