Metadata-Version: 2.4
Name: zlt-ai-tools
Version: 0.1.0
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）

`zlt-ai-tools` 产品的 Python 聚合入口。

## 这是什么

产品身份与聚合面。它把本生态已有的能力包重导出到一个名字下，**自己不实现任何
业务算法**——每条能力的实现都留在它自己的包里。

装它等于装齐本版的 Python 能力。

## 安装

```bash
pip install zlt-ai-tools
```

不要求 Node.js、Go 或任何其他语言运行时。Python 下界 3.8。

轮子**按平台架构分包**：装哪个由 `pip` 依平台标签自动选，不用自己挑。
本包**自足**：各能力的实现与随包交付的 C 共享库都在包内，装它不再需要另外
解析任何 `zlt-*` 依赖，也不需要联网取原生模块。

## 最小可运行示例

全能力走**包内原生通道**，进程内直接调，不起服务、不发 HTTP：

```python
from zlt_ai_tools import native

print(native.transport)   # "shared-library" 或 "coprocess"
print(native.actions())   # ['aiquery.columns', …, 'websearch.search']

compiled = native.formula.compile(dialect="tdx", source="MA5:MA(CLOSE,5);")
try:
    print(native.formula.execute(handle=compiled["handle"], payload=bars))
finally:
    native.formula.free(handle=compiled["handle"])
```

`native` 上的方法**不是手写的**，是拿原生件自报的动作清单（`域.动作`）生成的。
手写一份方法表的话，Go 那边加一个动作、这里没有，而没有任何测试会因此变红
——表现只是「文档里写了的调用在 Python 上不存在」，要等使用方来报。

行情轻客户端与交易面走 HTTP：

```python
from zlt_ai_tools import market_light, trade

client = market_light.create_client(base_url="https://<数据服务地址>", token="<令牌>")
print(client.bars(symbol="SH600519", frequency="1d", limit=5).rows[-1])

broker = trade.create_client(
    base_url="https://<交易服务地址>", token="<令牌>",
    account="<账号>", require_mode=trade.SIMULATION_MODE,
)
print(broker.account().mode)
```

## 能力清单

| 导出 | 取用方式 | 说明 |
|---|---|---|
| `native.formula` | 包内原生通道 | 四方言公式引擎 |
| `native.datafeed` | 包内原生通道 | 行情取数：K 线、快照、分时、成交、排行、板块、财务…… |
| `native.exdatafeed` | 包内原生通道 | 增值主站四路能力，各连各的数据源、各用各的凭据 |
| `native.websearch` | 包内原生通道 | 在线搜索 |
| `native.aiquery` | 包内原生通道 | AI 问数：找表、找字段、取结构、查证券、执行 SQL |
| `market_light` | HTTP | 行情轻客户端：不落盘、不连 DH |
| `trade` | HTTP | 交易面：mode 是响应的结构成分，读不懂即报错 |
| 命令行 | 包内可执行文件 | 与原生命令行包同一批命令 |

**没有 `native.market` 这个域**。行情取数在 `native.datafeed` 下——旧的
`ZltMarketFetchBars` 对应的就是 `datafeed.bars`，两个名字指同一件事，
留两份只会让人猜该用哪个。

这张域表**不写死在代码里**：跑一次 `native.actions()` 看当前这份产物的实况。
产物按平台分发，不同平台上支持面可能不同。

量化研究能力线见下一节；它有自己的入口。

**本版没有的**（说清楚比留白好）：

- **图表**：图表 SDK 内含上游 fork，公开分发要先过许可合规复核，本版不发。

缺的能力就是缺——不用别的语言运行时兜底，也不拿近似实现顶替。

## 量化研究（`zlt_quantresearcher`）

这条能力线暴露的是**外部研究环境已有的**完整回测能力（`zltHost` + `zltsdk`
原生桥 + `zltquant` 接口 + `zltFactor`），访问路径是
「QRS → `zltsdk` → `zltHost`/公式引擎」。

```python
from zlt_quantresearcher import research

if research.available():
    print(research.environment())
    print(research.capabilities())     # 按三类枚举运行期真实注册表
```

三点要先说清：

- **它只暴露，不实现**。本包不写回测算法，也**不给一个自己写的替代实现**；
- 机器上没装研究环境时，`available()` 返回假，`require()` 明确报缺环境，
  **不静默降级**；
- `zltsdk` 的原生桥按 CPython 版本编译（如 `zltcalc.cp310-win_amd64.pyd`），
  由研究环境自身提供，本包不代为分发。

## musl 发行版（Alpine 等）上换了条传输

那里 `native.*` 走的不是共享库，而是包内一个**常驻协进程**加管道。

原因：Go 编出的共享库在 musl 上根本加载不了——Go 运行时要 initial-exec 线程
本地存储，musl 不给 `dlopen` 进来的模块分配这种存储。四轮实测，含 Alpine 原生
工具链，改我们的代码去不掉。

**你不需要为此改任何代码**：方法、参数、返回值、错误分档两边完全一致。差别只有
两处，都在别处看不见：

- 每次调用多一个进程间来回（协进程是常驻的，不是每次调用起一个）
- `native.transport` 读出来是 `"coprocess"` 而不是 `"shared-library"`

一个宿主进程只起**一个**协进程，公式与行情共用它。

## 已知未覆盖面

- `capabilities()` 只在装有研究环境的机器上验过；无环境机器只验了明确失败这一支。

## 许可

见发行包内 `LICENSE`。
