Metadata-Version: 2.4
Name: sp-quant
Version: 1.0.4
Summary: Speculation Trading System
Requires-Python: <3.13,>=3.12
Description-Content-Type: text/markdown
Requires-Dist: setuptools>=61.0
Requires-Dist: aiohappyeyeballs>=2.6.1
Requires-Dist: aiohttp>=3.13.2
Requires-Dist: aiosignal>=1.4.0
Requires-Dist: akshare>=1.17.91
Requires-Dist: attrs>=25.4.0
Requires-Dist: autogen-agentchat>=0.7.5
Requires-Dist: baostock>=0.8.9
Requires-Dist: beautifulsoup4>=4.14.3
Requires-Dist: build>=1.3.0
Requires-Dist: certifi>=2025.11.12
Requires-Dist: charset-normalizer>=3.4.4
Requires-Dist: contourpy>=1.3.3
Requires-Dist: cycler>=0.12.1
Requires-Dist: decorator>=5.2.1
Requires-Dist: efinance>=0.5.5.2
Requires-Dist: et-xmlfile>=2.0.0
Requires-Dist: fonttools>=4.61.0
Requires-Dist: frozenlist>=1.8.0
Requires-Dist: html5lib>=1.1
Requires-Dist: idna>=3.11
Requires-Dist: jsonpath>=0.82.2
Requires-Dist: kiwisolver>=1.4.9
Requires-Dist: lxml>=6.0.2
Requires-Dist: markdown-it-py>=4.0.0
Requires-Dist: matplotlib>=3.10.7
Requires-Dist: mdurl>=0.1.2
Requires-Dist: mini-racer>=0.12.4
Requires-Dist: mplfinance>=0.12.10b0
Requires-Dist: multidict>=6.7.0
Requires-Dist: multitasking>=0.0.12
Requires-Dist: nest-asyncio>=1.6.0
Requires-Dist: numpy>=2.3.5
Requires-Dist: openpyxl>=3.1.5
Requires-Dist: packaging>=25.0
Requires-Dist: pandas<4,>=3.0.0
Requires-Dist: pillow>=12.0.0
Requires-Dist: propcache>=0.4.1
Requires-Dist: py>=1.11.0
Requires-Dist: pygments>=2.19.2
Requires-Dist: pyparsing>=3.2.5
Requires-Dist: pyproject-hooks>=1.2.0
Requires-Dist: python-dateutil>=2.9.0.post0
Requires-Dist: pytz>=2025.2
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: requests>=2.32.5
Requires-Dist: retry>=0.9.2
Requires-Dist: rich>=14.2.0
Requires-Dist: six>=1.17.0
Requires-Dist: soupsieve>=2.8
Requires-Dist: ta-lib>=0.6.8
Requires-Dist: tabulate>=0.9.0
Requires-Dist: tqdm>=4.67.1
Requires-Dist: typing-extensions>=4.15.0
Requires-Dist: tzdata>=2025.2
Requires-Dist: urllib3>=2.6.0
Requires-Dist: webencodings>=0.5.1
Requires-Dist: xlrd>=2.0.2
Requires-Dist: yarl>=1.22.0
Requires-Dist: annotated-types>=0.7.0
Requires-Dist: anyio>=4.12.0
Requires-Dist: autogen-core>=0.7.5
Requires-Dist: autogen-ext[redisvl]>=0.7.5
Requires-Dist: h11>=0.16.0
Requires-Dist: httpcore>=1.0.9
Requires-Dist: httpx>=0.28.1
Requires-Dist: importlib-metadata>=8.7.0
Requires-Dist: iniconfig>=2.3.0
Requires-Dist: jsonref>=1.1.0
Requires-Dist: ollama>=0.6.1
Requires-Dist: opentelemetry-api>=1.39.0
Requires-Dist: pluggy>=1.6.0
Requires-Dist: protobuf>=5.29.5
Requires-Dist: pytest>=9.0.2
Requires-Dist: regex>=2025.11.3
Requires-Dist: loguru>=0.7.2
Requires-Dist: tiktoken>=0.12.0
Requires-Dist: typing-inspection>=0.4.2
Requires-Dist: zipp>=3.23.0
Requires-Dist: kdata-quant>=1.1.0
Requires-Dist: autogen>=0.10.2
Requires-Dist: openai>=2.11.0
Requires-Dist: ag2[ollama]>=0.10.2
Requires-Dist: python-dotenv>=1.2.1
Requires-Dist: fear-and-greed>=0.4
Requires-Dist: autogen-openai>=0.0.1
Requires-Dist: setuptools>=80.9.0
Requires-Dist: wheel>=0.45.1
Requires-Dist: tp-quant>=1.2.5
Requires-Dist: m-patternpy>=2.0.1
Requires-Dist: redis>=5.0.0
Requires-Dist: kafka-python>=2.0.2
Requires-Dist: fastapi>=0.115.0
Requires-Dist: uvicorn>=0.32.0

## 投机倒把 (Speculation)

基于技术面形态识别与 LLM 深度分析的量化选股框架。系统集成了高信噪比的预筛选漏斗与并发处理流水线。

### 核心特性 (v1.4.0)

1.  **两阶段并发流水线**：
    - **阶段 1：技术面初筛 (Technical Scan)**：基于 `TradingPatternScanner` v1.4.0，通过六层漏斗（流动性、价格结构、趋势背景、量能质量、生命周期、综合评分）并发扫描标的。
    - **阶段 2：AI 深度分析 (AI Analysis)**：对排序后的 Top 标的进行并发 LLM 分析，自动识别 `底部企稳` 或 `趋势跟随` 策略逻辑。批量场景下会按 **市场 + 日期** 预生成 **大盘 AI 简报**，同市场当日所有标的共用同一份结论，减少 token 与判断分歧。
2.  **高信噪比过滤**：不仅识别形态，更通过多维度技术标准过滤掉僵尸股、妖股及趋势背离标的。
3.  **RAG 知识增强**：支持 Redis 存储历史分析报告，AI 在分析时会自动参考该标的的往期研判。



### 快速入门

#### 1. 环境准备
```shell
uv sync
source .venv/bin/activate
```

#### 2. 技术面扫描 (不走 AI，快速寻找信号)
使用 `-s basic` 参数仅执行技术面初筛。

```shell
# 探测底部反转信号 (BRP)
uv run speculation -l brp -s basic -f data/china/ETF/config_etf.yaml 

# 探测趋势跟随信号 (TF)
uv run speculation -l tf -s basic -f data/china/ETF/config_etf.yaml 

# 组合扫描 (Combined)
uv run speculation -l combined -s basic -f data/china/ETF/config_etf.yaml 

uv run speculation -l combined -s basic -f data/china/ETF/config_etf.yaml  -d 2026-05-01

# 量价异动与潜在机会雷达 (Radar)
uv run speculation -l radar -s basic -f data/china/ETF/config_etf.yaml 
```

#### 3. 全自动分析 (技术分析 + AI 研判)
默认模式。系统会筛选出得分最高的标的交付给 AI。

```shell
# 运行美股分析
uv run speculation -f data/usa/config_test.yaml

# 运行 A 股 ETF 深度分析
uv run speculation -l combined -f data/china/config_etf_test.yaml
```

---

### 选择器模式说明 (`-l` 参数)

| 模式 | 名称 | 扫描行为 (mode) | 适用场景 |
| :--- | :--- | :--- | :--- |
| `brp` | 底部反转 | `all` (仅限底部反转/等待突破) | 专门识别双底、头肩底、圆弧底等“底部企稳”信号 |
| `tf` | 趋势跟踪 | `trend` | 专门识别上升通道、旗形、三角形等“趋势跟随”信号 |
| `combined`| 组合模式 | `all` | 同时探测底部反转、趋势延续及震荡蓄势信号 (默认推荐) |
| `radar` | 机会雷达 | `radar` | 基于 tp-quant 1.0.4 接口，识别【量化异动】与【潜在机会】标的 |
| `all` | 全量直通 | `all` | 扫描所有形态，且跳过技术面拦截，直接交付 AI |

---

### 策略优先级与打分截断机制

在 `combined` 或多信号模式下，初筛后的标的按照 **“严格分级 + 全局高分优先”** 的规则进行打分截断和 AI 交付，优先保证高确定性与高形态质量的标的入选：

- **T0（最高优）**：量化异动、机会雷达、右侧确认、右侧候选
- **T1（高优）**：趋势跟随、等待突破
- **T2（中优）**：底部反转、筑底成熟
- **T3（一般）**：区间震荡、均线压缩

**排序逻辑**：
1. 优先按策略层级升序排列（T0 -> T3）。
2. 在同一层级内，按 `tp-quant` 综合形态评分（`total_score`）降序排列。
3. 规则与阈值配置统一维护于 `src/speculation/constants.py`（单一事实来源），可按需调整策略门槛与优先级。

---

### AI 分析 RAG（Redis Memory）

AI 分析支持 RAG：每次分析完成后将报告和总结存入 Redis，下次分析同一只股票时自动注入历史记录作为参考。

```shell
# 需启动 Redis，默认 redis://127.0.0.1:6379/0
export REDIS_URL=redis://127.0.0.1:6379/0
# 同步下大盘数据
uv run kdata-market --cn
uv run ai-analyze-stock -s sh.600000 -t 2026-03-31
uv run ai-analyze-stock -s 159825
```

---

### 单独工具

- **单股 AI**：`uv run ai-analyze-stock -s sh.600000 -t 2026-03-31`（直接对指定标的做深度分析；会先取或生成当日该市场的大盘简报并注入提示词）。
- **大盘简报**：`uv run ai-analyze-market -m A -t 2026-03-31`（仅生成大盘环境 AI 简报，与单股分析注入的是同一份缓存）。

市场 `-m`：`A`（A 股主要指数）、`US`、`HK`、`ETF`（与 A 股大盘同源）。默认若该日该市场的简报文件已存在则跳过 LLM；加 `--force` 可删缓存后重算。

简报默认落在 **`<REPORT_DIR>/market_briefs/{MARKET}_{YYYY-MM-DD}.md`**（与个股报告共用 `REPORT_DIR`；若设置 `K_DATA_CENTER`，则为 `<K_DATA_CENTER>/report/market_briefs/`）。也可通过环境变量 `SPECULATION_MARKET_BRIEF_DIR` 指定独立目录。

---

### 批量执行 (Batch Run)

针对历史回测或定期批量任务，可以使用内置的 shell 脚本按日期范围或时间间隔执行。

```shell
# 1. 按日期范围运行，每隔 5 天执行一次
./script/batch_run.sh -s 2026-01-01 -e 2026-05-01 -i 5

# 2. 运行最近 30 天的任务，每周执行一次 (间隔 7 天)
./script/batch_run.sh -n 30 -i 7 -f data/china/etf/config_etf.yaml

# 3. 运行最近 7 天，默认配置 (间隔 5 天)
./script/batch_run.sh -n 7
```

**参数说明：**
- `-s`: 开始日期 (`YYYY-MM-DD`)
- `-e`: 结束日期 (`YYYY-MM-DD`)
- `-n`: 最近天数 (与 `-s/-e` 二选一)
- `-i`: 间隔天数 (默认 5 天)
- `-f`: 配置文件路径
- `-l`: 选择器模式 (`combined`, `brp`, `tf`, `radar`, `all`)

---

### 构建与部署

- **普通构建（源码 wheel）**: `uv run python -m build`
- **机器码分发构建（Cython）**: `make build` — 在本机（macOS 上即当前架构）生成带 **`macosx_…`** 的 wheel；wheel 内 **不含 `.py`**，资源文件由 `packaging/prepare_native_build.py` 自动扫描（已排除 `__pycache__` / `.pyc`）。
  - **在 macOS 上同时出 Linux 多架构**：需安装 **Docker**，然后：
    - `make build-linux-x86_64` → **manylinux x86_64**（`linux/amd64`）
    - `make build-linux-aarch64` → **manylinux aarch64**（`linux/arm64`）
    - `make build-all` → `clean` 后依次打 **本机 + 上述两个 Linux**（产物均在 `dist/`）。
  - manylinux 内 Python 次版本默认与当前 **`$(PYTHON)`** 一致，可用 **`MANYLINUX_PY=3.12`** 覆盖。
  - Apple Silicon 上打 **x86_64** 会走模拟，速度较慢属正常。
- **发布到 PyPI**:
  - `make publish`: 上传 `dist/` 下包含的三平台/单平台所有 wheel 到 PyPI。
  - `make publish-all`: 自动执行 `make build-all` 依次编译本机 macOS + Linux x86_64 + Linux aarch64 三平台 wheel，并一键上传至 PyPI（需环境变量 `TOKEN` 或 `UV_PUBLISH_TOKEN`）。
- **平台与标签**：产物为 **`cp3xx-cp3xx-<platform>`**，与 **OS + CPU + Python ABI** 绑定；**不能**用单个 `none-any` wheel 替代多平台构建。
- **安全与形态说明**：
  - **`.pyc`**：易被反编译，保护弱。
  - **Cython / C 扩展（本 `make build`）**：分发 **机器码**，**逆向成本通常比 `.pyc` 高得多**，但 **仍可被逆向**，**不是绝对安全**；且与 **OS + CPU + Python ABI** 绑定，与 `py3-none-any` 式纯 Python wheel 不同。

