Metadata-Version: 2.4
Name: quantnodes
Version: 3.0.3
Summary: AI-native quantitative research framework with symbolic computation and SQL pushdown
Author-email: sn0wfree <snowfreedom0815@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/sn0wfree/QuantNodes
Project-URL: Documentation, https://github.com/sn0wfree/QuantNodes/tree/master/docs
Project-URL: Repository, https://github.com/sn0wfree/QuantNodes.git
Project-URL: Issues, https://github.com/sn0wfree/QuantNodes/issues
Project-URL: Changelog, https://github.com/sn0wfree/QuantNodes/blob/master/CHANGELOG.md
Keywords: Node,Databases,Quantitative
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.110.0
Requires-Dist: uvicorn[standard]>=0.29.0
Requires-Dist: websockets>=12.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pandas>=2.1.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: polars>=1.0.0
Requires-Dist: SQLAlchemy>=2.0.0
Requires-Dist: clickhouse-connect>=0.6.0
Requires-Dist: PyMySQL>=1.0.0
Requires-Dist: duckdb>=0.9.0
Requires-Dist: pydantic>=2.6.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: statsmodels>=0.14.0
Requires-Dist: sympy>=1.12.0
Requires-Dist: openai>=1.3.0
Requires-Dist: plotly>=5.17.0
Requires-Dist: requests>=2.33.0
Requires-Dist: tqdm>=4.66.0
Requires-Dist: rich>=13.0.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: progressbar2>=4.0.0
Requires-Dist: tables>=3.8.0
Requires-Dist: APScheduler>=3.10.0
Requires-Dist: llmwikify>=0.30.0
Requires-Dist: bs4>=0.0.1
Requires-Dist: msgpack>=1.0.0
Requires-Dist: scipy>=1.10.0
Requires-Dist: fastmcp>=2.0
Requires-Dist: pyarrow>=14.0.0
Provides-Extra: agent
Requires-Dist: nanobot-ai<0.3.0,>=0.2.1; extra == "agent"
Provides-Extra: mcp
Requires-Dist: fastmcp>=3.0; extra == "mcp"
Requires-Dist: mcp[cli]>=1.0; extra == "mcp"
Provides-Extra: all
Requires-Dist: quantnodes[agent,mcp]; extra == "all"
Provides-Extra: streamlit-ui
Requires-Dist: streamlit>=1.28.0; extra == "streamlit-ui"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: pytest-timeout>=2.0; extra == "dev"
Requires-Dist: hypothesis>=6.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: mypy>=1.5; extra == "dev"

# QuantNodes

> 量化研究节点架构 - 基于 Pipeline 组合原语的统一量化分析平台

[![Python](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

## 项目简介

QuantNodes 是一个面向量化研究的节点架构平台，通过统一的 **BaseNode + Pipeline** 模式，实现因子计算、回测分析、数据库查询的无缝集成。

### 核心特性

- **统一节点架构**: 万物皆 Node，Pipeline 是唯一组合原语
- **317+ 内置算子**: 涵盖时间序列、截面运算、多截面聚合等，装饰器注册表模式
- **多数据库支持**: ClickHouse、DuckDB、MySQL、SQLite、CSV、Parquet
- **Config-Driven 回测**: YAML 配置文件驱动回测，支持算子扩展
- **可选 LLM Agent**（v3.0.0）: 直接消费上游 [HKUDS/nanobot](https://github.com/HKUDS/nanobot) 0.2.1，作为 `[agent]` 可选依赖——装则获得 WebUI / WebSocket / cron / subagent / 多 channel，不装则纯量化库完全可用
- **MCP server**（可选）: 把量化能力暴露为 MCP tools（stdio + HTTP）
- **方法库 + 提示词库**: 纯 Python 方法 + 内置策略提示词，亦可经 REST API 供外部 Agent 调用
- **自动化因子挖掘（v2.9.0, QuantAlpha）**: 5 智能体编排（idea-generator → formula-translator → evaluator → reflector → critic），基于 nanobot spawn + OperatorVocab 162 算子 + PolarsAlphaCalculator（AlphaGen 兼容 7 方法）。CLI `quantnodes alpha-gpt` + REST API 5 端点 + WebSocket 实时流 + Vue 3 前端可视化。详见 [`docs/quant_alpha/alpha_gpt_user_guide.md`](docs/quant_alpha/alpha_gpt_user_guide.md)
- **Table 4 复现 v2.10.0-mock.1（QuantAlpha Stage 1 mock）**: 论文 Table 4 端到端 mock 复现。3 baseline (G1 手工 / G2 LLM-Only / G3 Alpha-GPT) + 统一接口契约 + 端到端 mock pipeline。11 文件 + 8 测试（114 PASSED，97% 覆盖 evaluation/ 子包）。CLI `python3.11 scripts/reproduce_table4_mock.py --quick`。详见 [`docs/quant_alpha/table4_reproduction.md`](docs/quant_alpha/table4_reproduction.md) + [`docs/quant_alpha/stage2_data_requirements.md`](docs/quant_alpha/stage2_data_requirements.md)

## 架构概览

```
┌─────────────────────────────────────────────────────────────┐
│  Layer 3: Meta-Programming AI                                │
│  StrategyGenerator │ PipelineOptimizer │ CodeSandbox          │
├─────────────────────────────────────────────────────────────┤
│  Layer 2: Pipeline 组合原语                                    │
│  Pipeline │ Parallel │ Join │ IfNode │ MapNode │ WhileNode   │
├─────────────────────────────────────────────────────────────┤
│  Layer 1: 处理节点                                            │
│  DatabaseNode │ FactorNode │ BacktestNode │ UINode │ ConfigNode │
└─────────────────────────────────────────────────────────────┘
```

## 目录结构

```
QuantNodes/
├── archive/                          # 统一归档目录
│   ├── QuantNodes/                   # QuantNodes 包归档（v2.x 旧代码）
│   │   └── test/                     # 测试数据归档
│   ├── frontend/                    # 前端归档
│   │   └── src/archive/             # 前端 Chat UI 归档
│   ├── api/                         # API 归档
│   │   └── archive/                 # API 归档
│   └── docs/                        # 文档归档
│       └── archived/                # 历史文档
├── QuantNodes/                      # 主包
│   ├── agent/                       # Agent 系统（v3.0.0: 上游 nanobot + 量化工具）
│   │   ├── nanobot_bridge.py        # Nanobot.from_config 包装门面
│   │   ├── config_mapper.py         # .env → nanobot_config.json
│   │   ├── tools/                   # 14 个量化工具（继承 nanobot Tool）
│   │   ├── skills_quant/            # 6 个量化 SKILL.md
│   │   └── cron_jobs.py             # 量化专属 cron 调度
│   ├── mcp_server/                  # MCP server（9 个量化 tools）
│   ├── monitor/                     # 监控 agent 工具（策略监控/调度/版本）
│   ├── methods/                     # 方法库（外部 Agent API）
│   ├── prompts/                     # 提示词库
│   ├── factor_node/                 # 因子引擎（317+ 算子）
│   ├── core/                        # 核心架构（BaseNode / Pipeline / 回测）
│   ├── database_node/               # 数据库节点（ClickHouse/DuckDB/MySQL/SQLite/CSV/Parquet）
│   └── ...
├── api/                             # FastAPI 服务器
│   ├── routers/                     # API 路由
│   └── services/                    # 服务层（含 nanobot_runtime.py 单进程包装器）
├── frontend/src/                    # Vue 3 + Ant Design 前端
│   └── views/
├── tests/                           # 测试套件（5163+ 非 agent / 574 agent）
├── examples/                        # 示例代码
├── docs/                           # 设计文档
├── .agent/                          # nanobot workspace（gitignore，含 API key）
├── output/                          # factor_test pipeline 节点产物 (运行时)
└── outputs/                         # 回测引擎结果 (运行时)
```

## 快速开始

### 安装

```bash
pip install -e .
```

可选附加组件:

```bash
pip install -e '.[agent]'          # LLM Agent（上游 nanobot）/ WebUI / 多 channel
pip install -e '.[mcp]'            # MCP server（把量化能力暴露为 MCP tools）
pip install -e '.[all]'            # agent + mcp 一键装齐
pip install -e '.[streamlit-ui]'   # 启用 Streamlit Agent 调试 UI
```

### 初始化项目

```bash
# 初始化配置文件（创建 .env 和 conn.ini）
quantnodes init
# 或使用 Python 模块方式
python -m QuantNodes init
```

### 启动服务

```bash
# ── v3.0.0 推荐方式（lifecycle 接口）──
quantnodes serve                     # 前台启动，Ctrl+C 停止
quantnodes serve --check-env        # 启动前校验 API key
quantnodes serve --gateway-port 18090  # 自定义 nanobot gateway 端口
quantnodes serve --frontend         # 同时启动 Vite dev server
quantnodes serve --daemon           # 后台运行，写 .quantnodes.pid
quantnodes stop                     # 停止后台 serve
quantnodes status                   # 综合健康检查
quantnodes logs -f                  # 实时查看日志

# ── 旧接口（兼容保留）──
quantnodes run
quantnodes run --host 0.0.0.0 --port 19380 --gateway-port 18090 --daemon
quantnodes run --api-only
quantnodes run --frontend-only
```

详细使用文档：[`docs/16-quantnodes-cli使用指南.md`](docs/16-quantnodes-cli使用指南.md)

### 外部 Agent API

QuantNodes 通过 REST API 为外部 Agent 提供方法调用和提示词。

v3.0.0 新增内置 agent 端点（需 `[agent]` extra，否则返回 503）：

```bash
# 查询 agent 状态
curl http://localhost:8000/api/agent/status

# 发送 chat 消息
curl -X POST http://localhost:8000/api/agent/chat/send \
  -H "Content-Type: application/json" \
  -d '{"message": "分析最近的动量因子表现"}'
```

#### 获取策略提示词

```bash
curl -X GET "http://localhost:8000/api/prompts/strategy/momentum" \
  -H "X-API-Key: qn_live_xxxxxxxxxxxxxxxxxxxxxxxx"
```

#### 验证代码安全

```bash
curl -X POST "http://localhost:8000/api/code/validate" \
  -H "X-API-Key: qn_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"code": "import pandas as pd\\nprint(pd.DataFrame())"}'
```

#### 运行回测

```bash
curl -X POST "http://localhost:8000/api/backtest/run" \
  -H "X-API-Key: qn_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"pipeline_code": "...", "start_date": "2020-01-01", "end_date": "2024-12-31"}'
```

### 基本使用

```python
from QuantNodes.core.node import BaseNode, Pipeline
from QuantNodes.factor_node.factor_functions import get_operator, list_operators

# 列出所有算子
print(list_operators())  # ['abs', 'add', 'aggr_count', ...]

# 获取算子
rolling_mean = get_operator('rolling_mean', 'time')

# 构建 Pipeline
pipeline = Pipeline(
    source_node,
    transform_node,
    output_node
)

# 执行
result = pipeline.execute()
```

### 因子计算示例

```python
from QuantNodes.factor_node.factor_functions import rolling_mean, rolling_std, zscore

# 滚动均值
result = rolling_mean(factor_data, window=20)

# 滚动标准差
std = rolling_std(factor_data, window=20)

# Z-Score 标准化
zscore = zscore(factor_data)
```

## 算子注册表 API

```python
from QuantNodes.factor_node.factor_functions import (
    list_operators,    # 列出所有算子
    get_operator,      # 获取算子函数
    operator_info,     # 获取算子元信息
    generate_documentation,  # 生成文档
)

# 按类别列出算子
point_ops = list_operators('point')      # 单点运算
time_ops = list_operators('time')       # 时间序列运算
section_ops = list_operators('section') # 截面运算
multi_ops = list_operators('multi_section')  # 多截面运算

# 获取算子详情
info = operator_info('rolling_mean', 'time')
print(info)
# {'name': 'rolling_mean', 'category': 'time', 'doc': '...', 'parameters': [...]}

# 生成 Markdown 文档
docs = generate_documentation('markdown')
```

## 算子分类

| 类别 | 数量 | 示例 |
|------|------|------|
| **Point (单点)** | 46 | `abs`, `log`, `sign`, `isnull` |
| **Time (时间序列)** | 65 | `rolling_mean`, `rolling_std`, `ewm`, `diff` |
| **Section (截面)** | 17 | `standardizeZScore`, `winsorize`, `fillNaNByVal` |
| **Multi-Section (多截面)** | 15 | `aggregate`, `disaggregate`, `aggr_sum` |
| **TA-Lib** | 174 | `talib_rsi`, `talib_sma`, `talib_macd_line` |
| **Custom (用户自定义)** | ∞ | `@CustomOperator.point()`, Builder API |

## 自定义算子 API

```python
from QuantNodes.operators import CustomOperator

# 装饰器风格（直接注册）
@CustomOperator.point("my_double")
def my_double(f, multiplier=2.0):
    return f * multiplier

# Builder 链式风格
my_ewm_30 = (CustomOperator.time("my_ewm_30")
    .param("span", int, 30, "窗口大小")
    .execute(lambda s, span: s.ewm_mean(span=span))
    .register())

# 模板工厂（基于内置算子创建）
from QuantNodes.operators import CustomOperator
my_ewm_30 = CustomOperator.time_from("my_ewm_30", "ewm_mean", span=30)

# 级联查询：自定义算子优先，内置算子 fallback
from QuantNodes.factor_node.factor_functions import get_operator
op = get_operator("my_double")  # 先查自定义，再查内置
```

## 测试

> 要求 Python 3.11+。全量测试需先装系统级/可选依赖：`pip install ta-lib tables plotly`（`ta-lib` 需先装 TA-Lib C 库）。缺失时相关测试会优雅降级或跳过。基线：非 agent `5163 passed / 21 skipped / 0 failed`，`tests/agent` `574 passed / 13 skipped`。详见 [可选依赖安装指南](docs/15-可选依赖安装指南.md)。

```bash
# 运行所有测试
pytest tests/ -v

# 运行特定测试
pytest tests/test_factor_functions.py -v
pytest tests/test_backtest_tool.py -v

# 查看覆盖率
pytest tests/ --cov=QuantNodes --cov-report=html
```

## 设计文档

- [架构设计](docs/04-架构设计.md)
- [执行清单](docs/07-执行清单.md)
- [算子系统设计与规范](docs/22-算子系统设计与规范.md)
- [核心功能框架设计](docs/24-核心功能框架设计.md)
- [大型项目开发测试规范](docs/大型项目开发测试规范.md)
- [操作手册](docs/QuantNodes-操作手册.md)
- [Feature 3A - WikiFactorProxy](docs/Feature3A-实施计划.md)
- [Feature 3B - 研报复现](docs/Feature3B-实施计划.md)
- [Feature 3C - AutoResearch 自动因子挖掘](docs/Feature3C-实施计划.md)
- [Feature 3D - 用户友好自定义算子 API](docs/Feature3D-用户友好自定义算子API设计.md)
- [v2.6.0 实际架构基线](docs/Architecture-v2.6.md)
- [单因子回测节点化整合设计](docs/SingleFactorBacktest-Integration-Design.md)
- [演化框架设计 (FactorFeedback + TrajectoryPool + QualityGate)](docs/Evolution-Framework.md)
  - [FactorFeedback 详细规格](docs/FactorFeedback.md)
  - [TrajectoryPool 详细规格](docs/TrajectoryPool.md)
  - [QualityGate 详细规格](docs/QualityGate.md)

## 变更日志

> 完整变更记录见 [CHANGELOG.md](CHANGELOG.md)。下面仅列里程碑版本。

### v3.0.0 (2026-06-23)

- ✅ **上游 nanobot 迁移**: Agent 核心从自写 runtime 改为直接消费 [HKUDS/nanobot](https://github.com/HKUDS/nanobot) 0.2.1（`Nanobot.from_config()` 门面）
- ✅ **nanobot-ai 改为可选依赖**: `pip install 'quantnodes[agent]'`；纯量化库可独立使用
- ✅ **单进程架构**: FastAPI uvicorn + nanobot gateway 共存于同一进程（`api/services/nanobot_runtime.py`）
- ✅ **Phase 5 功能**: subagent 多 Agent 团队 / MCP server（9 tools）/ 单进程 WebUI / WebSocket + 飞书 channel / 量化专属 cron 调度
- ✅ **workspace 迁移**: `.quant_agent/` → `.agent/`（HKUDS nanobot 约定，附迁移脚本）
- ⚙️ **Python 3.11+**（上游最低要求）；**pandas 3.0 兼容**（`applymap`→`.map` 等）
- ✅ **测试稳定化**: 非 agent `5163 passed / 21 skipped / 0 failed`、`tests/agent` `574 passed / 13 skipped`（顺序 + 并行均通过）；可选依赖优雅降级
- 💥 **Breaking**: 删除自写 `agent/core/{loop,runner,memory,...}`，改用 `Agent.run()` / `Nanobot.from_config()` facade

### v2.6.0 (2026-05-14)

- ✅ **架构重构**: 从"带 UI 的 Agent 系统"转向"外部 Agent 方法库 + 提示词库"
- ✅ **移除 Chat UI**: 前端不再有交互式 Chat
- ✅ **移除 Agent LLM**: QuantNodes 不再包含 LLM
- ✅ **新增 methods/**: 纯方法实现，外部 Agent 可通过 API 调用
- ✅ **新增 prompts/**: 完整策略提示词库，含参考代码
- ✅ **API 重构**: 新增 prompts、code 路由，移除 chat 路由
- ✅ **API Key 认证**: 支持 X-API-Key 和 Authorization Bearer 认证
- ✅ **前端展示页面**: Dashboard、Portfolios、Status 视图

### v2.5.0 (2026-05-10)

- ✅ Agent 智能体系统：15 个内置工具，支持文件操作、代码搜索、Git、Web 搜索等
- ✅ 新增 `web_fetch` 工具：网页抓取，支持 text/html 格式
- ✅ 新增 `web_search` 工具：DuckDuckGo 网络搜索
- ✅ 新增 `task` 工具：任务管理（创建/更新/列表），JSON 持久化
- ✅ 新增 `quantnodes chat` 命令：Rich Agent 交互终端
- ✅ CLI 重构为包结构（`cli/`）
- ✅ 修复 `compile_expression` 方言 import Bug
- ✅ 修复 Agent `api_base` URL 双重拼接 Bug
- ✅ 修复 `should_execute_tools` 逻辑 Bug
- ✅ 2698+ 测试用例

### v2.4.1 (2026-05-09)

- ✅ CLI 优化：依赖安装自动化（Python 依赖通过 pyproject.toml，前端依赖首次 import 时自动安装）
- ✅ CLI 优化：init 流程简化（只初始化 Wiki 和创建配置文件）
- ✅ llmwikify Wiki 集成：初始化时自动创建 raw/, wiki/, wiki.md, index.md, log.md
- ✅ 目录结构优化：Wiki 放在项目根目录，与 data/ 平级

### v2.4.0 (2026-05-08)

- ✅ Feature 3A - WikiFactorProxy：因子库读写接口，支持 llmwikify 解析 PDF
- ✅ Feature 3B - 研报复现：从研报提取因子公式，验证有效性，存入 Wiki 因子库
- ✅ Feature 3C - AutoResearch 自动因子挖掘：模板枚举 + MCTS 搜索自动生成验证因子
- ✅ Feature 3D - 用户友好自定义算子 API：装饰器风格 + Builder 链式 + 模板工厂 + 级联查询
- ✅ 317+ 内置算子（point: 46, time: 65, section: 17, multi_section: 15, talib: 174）
- ✅ 2574+ 测试用例，覆盖率 ~80%
- ✅ 统一前端到 Vue 3 + Ant Design Vue 4.x

### v2.3.0 (2026-04-30)

- ✅ 实现 config-driven 回测的算子扩展机制（通用 fallback + custom_operators 加载）
- ✅ 迁移 6 个独有算子到 factor_functions（mad, weighted_aggr_mean, fill_null_by_strategy 等）
- ✅ 删除 factor_nodes.py，统一算子系统（-1274 行）
- ✅ ts_corr 协方差公式修复 + group_winsorize 实现
- ✅ 算子构建规范文档

### v2.2.0 (2026-04-28)

- ✅ 实现 DataPreprocessingFun 类，完全移除 QuantStudio 依赖
- ✅ 统一 PointOperation/TimeOperation 空数据处理
- ✅ 添加参数边界验证 (winsorize, half_life)
- ✅ 改进 rolling_regress 错误处理
- ✅ 修复 rolling_change_rate 除法顺序问题
- ✅ 添加 pandas_utils 工具模块
- ✅ 添加 Vue 3 前端应用骨架 (后统一为 Vue)

### v2.1.0 (2026-04-27)

- ✅ 完成 9/9 阶段重构
- ✅ 97+ 因子算子实现
- ✅ 完整测试套件
- ✅ 多数据库支持

## 致谢

- [HKUDS/nanobot](https://github.com/HKUDS/nanobot) — Agent 核心运行时（v3.0.0 直接消费上游 0.2.1）
- [QuantaAlpha](https://arxiv.org/abs/2602.07085) — 演化实验框架设计（CoSTEER 反馈 / TrajectoryPool / QualityGate）
- [QuantStudio](https://github.com/quantopian/quantstudio) — 因子计算系统设计灵感
- [TA-Lib](https://ta-lib.org/) — 174 个技术指标算子（C 库 + Python wrapper）

## 许可证

MIT License
