Metadata-Version: 2.4
Name: qteasy-ai
Version: 0.2.2
Summary: AI orchestration shell for qteasy — natural language plans over qteasy APIs
Author-email: Jackie PENG <jackie.pengzhao@gmail.com>
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/shepherdpp/qteasy-ai
Project-URL: Documentation, https://github.com/shepherdpp/qteasy-ai#readme
Project-URL: Issues, https://github.com/shepherdpp/qteasy-ai/issues
Project-URL: Repository, https://github.com/shepherdpp/qteasy-ai
Keywords: quantitative investment,ai,llm,qteasy,skills
Requires-Python: <3.13,>=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: qteasy>=2.6.0
Provides-Extra: workbench
Requires-Dist: starlette>=0.27; extra == "workbench"
Requires-Dist: uvicorn>=0.22; extra == "workbench"
Requires-Dist: httpx>=0.24; extra == "workbench"
Requires-Dist: textual>=0.47; extra == "workbench"
Dynamic: license-file

# qteasy-ai 介绍

**qteasy-ai** 是 [qteasy](https://github.com/shepherdpp/qteasy) 的 **独立 AI 编排外壳**：自然语言 → ToolPlan → 用户确认 → 调用 qteasy API → 结构化结果。  
它不修改 qteasy 回测/交易内核，仅作为可插拔的 skills + planner + executor 层。

> **当前版本：0.2.2**。  
> 用户指南：[docs/USER_GUIDE.md](docs/USER_GUIDE.md)。人工 smoke 见 [docs/MANUAL_TEST.md](docs/MANUAL_TEST.md)。  
> **协作规范与 Q-AI 计划真源**仍在 qteasy 仓库的 [`.cursor/rules/`](https://github.com/shepherdpp/qteasy/tree/master/.cursor/rules) 与 [`.cursor/plans/`](https://github.com/shepherdpp/qteasy/tree/master/.cursor/plans)。

## 与 qteasy 的关系

| 项目 | 职责 |
| --- | --- |
| **qteasy** | 数据、HistoryPanel、回测、优化、模拟实盘内核 |
| **qteasy-ai** | AI 外壳：SkillRegistry、Planner、PlanExecutor、只读/高副作用 skills |

- **依赖方向**：`qteasy-ai` → `qteasy`（pip 安装 `qteasy>=2.6.0`）
- **发布**：两项目 **独立 semver**；qteasy 新版本 API 可由 qteasy-ai skills 增量适配

## 安装

```bash
pip install qteasy>=2.6.0
pip install qteasy-ai
# optional desktop Web + TUI
pip install "qteasy-ai[workbench]"
```

本地联调（两仓并列开发时）：

```bash
pip install -e /path/to/qteasy
pip install -e /path/to/qteasy-ai
```

## 配置

优先使用环境变量（与 Stage A 设计一致）：

- `QTEASY_AI_HOME` — 本地记忆目录（profile / env_facts / runs）
- `QTEASY_AI_MODEL` / `QTEASY_AI_API_KEY` / `QTEASY_AI_BASE_URL` — OpenAI-compatible Provider

详见 [docs/USER_GUIDE.md](docs/USER_GUIDE.md)、[docs/tutorials/quickstart.md](docs/tutorials/quickstart.md)、[docs/WORKBENCH.md](docs/WORKBENCH.md)。

## 开发

- 本地建议与 qteasy **同一 Cursor multi-root 工作区**（见 `qteasy-ecosystem.code-workspace`）
- 规范与测试约定：**沿用 qteasy** [`.cursor/rules/`](https://github.com/shepherdpp/qteasy/tree/master/.cursor/rules)（py39、unittest、用户可见信息英文等）
- 更多说明：[docs/dev-context.md](docs/dev-context.md)、[CONTRIBUTING.md](CONTRIBUTING.md)

## License

BSD-3-Clause（与 qteasy 相同）

## Changelog

见 [CHANGELOG.md](CHANGELOG.md)。
