Metadata-Version: 2.4
Name: zlt-ai-tools
Version: 1.1.3
Summary: zlt-ai-tools Python SDK and command
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# zlt-ai-tools

给 Python 用的智量通量化工具包。

## 一、能做什么

装上它，你的程序可以：

| 你想做的事 | 用哪个 |
|---|---|
| **算技术指标、跑自己写的公式** —— 通达信、同花顺等方言的公式直接编译执行，136 个内置函数 | `native.formula` |
| **做因子研究** —— 算因子、评有效性（信息系数、分层收益、换手率）、出可入库比对的结果 | `research` |
| **取行情** —— K 线、分时、财务、板块分类、排行榜 | `native.datafeed` |
| **查数据资产** —— 用自然语言找表、找字段、找证券 | `native.aiquery` |
| **联网检索** —— 搜新闻、研报、政策、论文 | `native.websearch` |
| **下单与查持仓**（含仿真盘） | `trade` |
| **轻量取行情** —— 不落盘、只发 HTTP | `market_light` |

一句话：**你写公式，它负责编译、取数、算出来，还能告诉你这个因子有没有用。**

装完还会带上一批命令行程序（`zlt-formula`、`zlt-datafeed`、`zlt-trade` 等），
装在环境的 `bin`/`Scripts` 里，直接就能敲。

不需要装 Node.js、Go 或其他语言运行时。每个平台架构一个轮子，`pip` 自动挑。

## 二、先拿账号

除公式计算外的能力都要账号——行情、问数、检索都在服务端。

```bash
# 扫码登录，拿到 API Key 并存进本机凭据库
zlt-qrlogin -identity gateway-api-key -entry <给这把钥匙起个名>
```

跑起来会存一张二维码图片并告诉你路径，用微信扫它，确认之后钥匙自动落库。
**钥匙不会打印在屏幕上，也不进日志和命令行参数**——程序取用时从凭据库读，
人不需要看见它。

如果这个微信还没绑手机号，会让你补一次短信验证；照提示做即可。

只算公式、不取数的话，这一步可以跳过。

## 三、怎么用

### 算一条公式

```python
from zlt_ai_tools import native

compiled = native.formula.compile(dialect="tdx",
                                  source="OUT:(CLOSE-MA(CLOSE,20))/MA(CLOSE,20);")
bars = native.datafeed.bars(symbol="SH600519", frequency="1d", limit=120)
result = native.formula.execute(handle=compiled["handle"], payload=bars["value"])
native.formula.free(handle=compiled["handle"])       # 用完还回去
print(result["value"][-1])                            # 最新一根的因子值
```

### 评一个因子有没有用

```python
from zlt_ai_tools import research

report = research.run_factor_study(
    symbols=["SH600519", "SZ000001", "SH601318", "SZ000858",
             "SH600036", "SZ002415", "SH601899", "SZ300750"],
    start="2026-01-01", end="2026-06-30",
    dialect="tdx", source="OUT:(CLOSE-MA(CLOSE,20))/MA(CLOSE,20);",
    quantiles=5,
)
print(report.ic_mean)           # 因子与下一期收益的相关性
print(report.top_minus_bottom)  # 最高一层减最低一层的收益
print(report.turnover_mean)     # 换手率：太高就吃不到收益
for line in report.diagnostics:
    print(line)                 # 跳过的期、取不到的标的都在这
```

**三个指标要一起看**：相关性再高，分层不单调多半是被极端值带的；
前两项再好，换手率覆盖不了成本也是纸面收益。

### 看有哪些能力可以调

```python
from zlt_ai_tools import native
print(native.version())    # 版本
print(native.actions())    # 全部动作，形如 "formula.compile"、"datafeed.bars"
print(native.transport)    # 这一次走的是共享库还是协进程
```

方法名按 `域.动作` 组织，`native.<域>.<动作>()` 直接调。`actions()` 是从原生件
自报的清单生成的——**以它为准**，文档可能滞后，那份清单不会。

## 四、出问题时

| 症状 | 去哪看 |
|---|---|
| `pip` 说找不到匹配的发行版 | 手册「安装与平台覆盖」；确认 Python ≥ 3.8 与平台架构 |
| 调用报未授权 / 401 / 403 | 第二节重新扫码；钥匙可能过期或没绑到标识上 |
| 公式编译报错 | 手册的方言分卷：不同方言的函数与语义不完全一样 |
| 因子研究报「没有共同的期」 | 两侧的期标识不是一套写法；**这不是「因子没用」**，是数据没对齐 |
| 取数为空 | 手册「行情取数」：先确认代码写法与频率参数 |
| 命令行程序敲不动 | 确认装在虚拟环境里且已激活；轮子把命令装进环境的 `bin`/`Scripts` |

**手册在发布页的 `manuals` 包里**（每个版本的 Release 附件），解压后打开
`index.html`。里面按能力线分卷：公式引擎、行情取数、在线搜索与问数、交易、
量化研究。

报问题时请附上 `native.version()` 与 `native.transport` 的输出——**这两样决定
了排障从哪开始**：版本对不上和通道不同，症状可能一模一样而原因完全不同。

---

## 附：技术细节

这些不影响使用，排障或做集成时才需要。

- **两条传输通道**：优先走 C 共享库（进程内调用）；musl 发行版（Alpine 等）
  上共享库加载不了，自动改走协进程——同一份实现、同一个调用面，`transport`
  告诉你这次走的哪条。
- **包的构成**：每个平台架构一个轮子，内含该平台的共享库或协进程程序，
  外加同批命令行程序。行情轻客户端、交易客户端与量化研究能力包的源码已内联，
  装它不需要另外解析依赖。
- **聚合面自己不实现业务算法**：因子研究的计算在 `zlt_quantresearcher`，
  取数与公式由聚合面注入——能力线不反向依赖包装层。
- 图表 SDK 不在本包公开面里：内含上游分支，公开分发要先过许可合规复核。
