Metadata-Version: 2.4
Name: pandaai-cli
Version: 0.1.0
Summary: PandaAI 因子分析 CLI 工具 — 传入 Python 因子代码或公式，自动完成登录、创建、执行、结果和余额查询
Author: PandaAI
License: MIT
Project-URL: Homepage, https://www.pandaaiquant.com
Keywords: pandaai,factor,quant,cli,因子分析,量化
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28
Requires-Dist: pyyaml>=6.0
Dynamic: license-file

# PandaAI 因子分析 CLI

供 AI Skill 调用的命令行工具，传入 Python 因子代码或公式，自动完成登录 → 创建 → 执行 → 轮询 → 结果 + 余额。

## 安装

```bash
# 方式一：源码安装
uv venv --python 3.12
uv pip install -r requirements.txt

# 方式二：whl 安装
uv pip install dist/pandaai_cli-0.1.0-py3-none-any.whl
# 安装后直接使用: pandaai-cli factor_list
```

## 快速开始

```bash
# 0. 激活虚拟环境
source .venv/bin/activate

# 1. 登录（token 自动保存到 config.yaml）
python cli.py login --phone 13800138000 --password 'your_password'

# 2. 创建因子分析
python cli.py factor_create --formula "close/ref(close,5)-1"
# → ✅ 因子分析已创建: 6a461b10...

# 3. 执行并拿结果
python cli.py factor_run 6a461b10... --download

# 4. 查看列表
python cli.py factor_list
```

## 命令一览

```
python cli.py <command> [options]

命令:
  login                                   登录并保存 token
  factor_create                           创建因子分析（不执行），返回 factor_id
  factor_info <factor_id>                 查看因子详情（代码/公式 + 所有参数）
  factor_update <factor_id> [options]     修改因子参数
  factor_run <factor_id>                  执行已有因子分析（启动 + 轮询 + 结果）
  factor_list                             列出所有因子分析
  balance                                 查询算力余额
  factor_result <run_id>                  查询运行结果（14 个因子分析接口）
  factor_delete <factor_id> [factor_id...] 删除因子分析
```

## 详细参数

### login — 登录

```bash
python cli.py login [--phone PHONE] [--password PWD]
```

| 参数 | 说明 |
|------|------|
| `--phone` | 手机号（不传则交互式输入） |
| `--password` | 密码（不传则隐藏输入，更安全） |

登录成功后 token 自动保存到 `config.yaml`，后续命令无需再登录。token 过期时自动提示重新登录。

### factor_create — 创建因子分析

```bash
python cli.py factor_create (--code | --formula | --file) CONTENT
  [--name NAME] [--start-date YYYYMMDD] [--end-date YYYYMMDD]
```

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `--code CODE` | - | Python 因子代码（需继承 `Factor` 基类） |
| `--formula FORMULA` | - | 因子公式字符串 |
| `--file FILE` | - | 从文件读取代码/公式 |
| `--name NAME` | 新建因子分析 | 因子分析名称 |
| `--start-date` | 昨天-60天 | 因子构建开始日期，格式 YYYYMMDD |
| `--end-date` | 昨天 | 因子构建结束日期，格式 YYYYMMDD |
| `--adjustment-cycle` | 1 | 调仓周期（1-10） |
| `--factor-direction` | 1 | 因子方向：0=负向，1=正向 |

> 分组数量固定为 10，股票池固定为沪深全A，不可修改。

**返回值（JSON）：**
```json
{"success": true, "factor_id": "6a46..."}
```

**示例：**
```bash
python cli.py factor_create --formula "close/ref(close,5)-1"
# → ✅ 因子分析已创建: 6a461b10...

python cli.py factor_create --code "$(cat factor.py)" --name "动量因子"
python cli.py factor_create --file ./factor.py --start-date 20240101 --end-date 20240630

# 自定义因子分析参数
python cli.py factor_create --formula "close/ref(close,5)-1" \
  --adjustment-cycle 3 --factor-direction 0
```

### factor_info — 查看因子详情

```bash
python cli.py factor_info <factor_id>
```

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `factor_id` | 必填 | 因子分析 ID |

展示内容：名称、ID、类型（Python 代码/因子公式）、创建时间、调仓周期、分组数量、因子方向、股票池、日期范围、代码/公式内容。

### factor_update — 修改因子参数

```bash
python cli.py factor_update <factor_id> [options]
```

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `factor_id` | 必填 | 因子分析 ID |
| `--name` | - | 新名称 |
| `--code` / `--formula` / `--file` | - | 新代码/公式（三选一） |
| `--start-date` | - | 开始日期 YYYYMMDD |
| `--end-date` | - | 结束日期 YYYYMMDD |
| `--adjustment-cycle` | - | 调仓周期 1-10 |
| `--factor-direction` | - | 因子方向 0=负向 1=正向 |

**约束：**
- 调仓周期必须在 1-10 之间
- 分组数量固定为 10，不可修改
- 股票池固定为沪深全A，不可修改

### factor_run — 执行因子分析

```bash
python cli.py factor_run <factor_id>
  [--download [PATH]] [--poll-interval SEC] [--timeout SEC]
```

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `factor_id` | 必填 | 要执行的因子分析 ID |
| `--download [PATH]` | 不下载 | 下载结果 CSV，默认 ~/Downloads/ |
| `--poll-interval` | 2 | 状态轮询间隔（秒） |
| `--timeout` | 600 | 超时时间（秒） |

> 算力服务器固定使用 cpu=4, memory=8, gpu=4，无需手动选择。

**返回值（JSON）：**

成功：
```json
{
  "success": true,
  "status": "SUCCESS",
  "factor_id": "6a46...",
  "factor_run_id": "6a46...",
  "duration_seconds": 6.5,
  "output": [{"node_title": "因子分析", "node_output": {"task_id": "..."}}],
  "billing": {"balance": 9451.51, "deducted": 2.0, "status": "ok"},
  "results": {
    "nodes": {...},
    "factor_analysis": {
      "query_factor_analysis_data": [...],
      "query_group_return_analysis": [...],
      ...
    }
  }
}
```

失败：
```json
{
  "success": false,
  "status": "FAILED",
  "error": {"type": "WORKFLOW_FAILED", "message": "...", "node_errors": [...]},
  "billing": {"balance": 9449.51, "deducted": 2.0, "status": "ok"}
}
```

**示例：**
```bash
python cli.py factor_run 6a461b10... --download
python cli.py factor_run 6a461b10... --download /tmp/my_data.csv
python cli.py factor_run 6a461b10... --timeout 120
```

### factor_list — 列出因子分析

```bash
python cli.py factor_list [--limit N] [--offset N] [--no-detail]
```

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `--limit` | 100 | 每页条数（最大 100） |
| `--offset` | 0 | 偏移量 |
| `--no-detail` | false | 跳过获取分析摘要（更快） |

列表列：名称、创建时间、最后一次运行时间、Run ID、分析摘要（14 个指标）

分析摘要包含：
- **核心绩效**：因子收益、夏普比率、年化收益、最大回撤
- **IC 系列**：IC_mean、Rank_IC、IC_std、IC_IR、IR、P(IC<-0.02)、P(IC>0.02)、t统计量、p-value、单调性

**返回值（JSON）：**
```json
{
  "success": true,
  "total": 180,
  "count": 100,
  "limit": 100,
  "offset": 0,
  "factors": [
    {"_id": "6a46...", "name": "动量因子", "create_at": 1782..., "last_run_id": "6a46...", "_last_run_time": "...", "_analysis_summary": "因子收益 20.90%  夏普比率 8.02  年化收益 175.58%  最大回撤 0.00%  IC_mean -0.06  Rank_IC -0.07  IC_std 0.11  IC_IR -0.50  IR -4.01  P(IC<-0.02) 83.33%  P(IC>0.02) 16.67%  t统计量 -1.22  p-value 0.28  单调性 0.73"}
  ]
}
```

**示例：**
```bash
python cli.py factor_list
python cli.py factor_list --limit 50 --offset 50
python cli.py factor_list --no-detail
```

### balance — 查询算力余额

```bash
python cli.py balance
```

**返回值（文本）：**
```
算力: 9435.51
```

**返回值（JSON）：**
```json
{"success": true, "balance": {"computingPower": 9435.51, ...}}
```

### factor_result — 查询运行结果

```bash
python cli.py factor_result <run_id> [--download [PATH]]
```

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `run_id` | 必填 | 运行 ID |
| `--download [PATH]` | 不下载 | 下载结果 CSV |

调用全部 14 个因子分析接口，展示：
- **核心绩效**：因子收益、夏普比率、年化收益、最大回撤
- **因子分析指标**：IC_mean, Rank_IC, IC_std, IC_IR, IR, P(IC<-0.02), P(IC>0.02), t统计量, p-value, 单调性
- **分组收益**：10 分组 + 多空组合的 年化收益/超额收益/夏普比率/最大回撤/月胜率
- **Top 因子**：最新日期因子值最高的 10 只股票
- **图表数据**：IC 序列、IC 衰减、IC 密度分布等 10 个图表（完整 JSON，含全量数据点）

**示例：**
```bash
python cli.py factor_result 6a461b10...
python cli.py factor_result 6a461b10... --download
```

### factor_delete — 删除因子分析

```bash
python cli.py factor_delete <factor_id> [factor_id...]
python cli.py factor_delete --pattern "quota-test" [--yes]
```

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `factor_id` | 至少一个 | 因子分析 ID（支持多个） |
| `--pattern` | - | 按名称前缀批量匹配 |
| `--yes` | false | 跳过删除确认 |

**示例：**
```bash
python cli.py factor_delete 6a461b10...
python cli.py factor_delete abc123 def456 ghi789
python cli.py factor_delete --pattern "quota-test" --yes
```

## 通用参数

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `--config PATH` | ~/.pandaai/config.yaml | 配置文件路径 |
| `--json` | false | 仅输出 JSON（不输出 INFO 日志） |

> 注意：`--config` 和 `--json` 必须放在子命令**前面**：
> ```bash
> python cli.py --json factor_create --formula "..."
> ```

## 因子代码规范

### 代码模式（`--code` / `--file`）

需继承 `Factor` 基类，实现 `calculate(self, factors)` 方法：

```python
class CombinedFactor(Factor):
    def calculate(self, factors):
        volume = factors['volume']
        close = factors['close']

        # 大单比例信号
        large_order_volume = TS_MAX(volume, 20)
        buy_signal = (large_order_volume / volume > 0.01).astype(int)

        # OBV 突破信号
        obv = (volume * ((close - close.shift(1)) / close.shift(1))).cumsum()
        obv_signal = ((obv == obv.rolling(90).max()) & (obv > obv.rolling(30).mean())).astype(int)

        return buy_signal + obv_signal
```

### 公式模式（`--formula`）

直接写因子表达式，可用变量 `open`, `close`, `high`, `low`, `volume`, `amount` 等：

```bash
# 5日收益率
--formula "close/ref(close,5)-1"

# 对数市值排名
--formula "RANK(-LOG(MARKET_CAP))"
```

## 因子分析链路

```
CodeControl → FactorBuildProControl → FactorAnalysisControl → FactorAnalysisChartControl
(Python代码)   (线性因子构建)          (因子分析)             (结果展示)
                              → DataDownloadControl (数据下载)
```

## 配置

配置文件默认位置 `~/.pandaai/config.yaml`，也可通过 `--config` 指定其他路径。

首次使用直接 `login` 会自动创建：

```bash
# 自动创建 ~/.pandaai/config.yaml
python cli.py login --phone 13800138000 --password 'xxx'
```

`config.yaml` 内容：

```yaml
gateway_url: "https://www.pandaaiquant.com/pandaApi"
token: "eyJ..."
uid: "35981"
```

## 目录结构

```
pandaai_cli/
├── cli.py                   # 入口：argparse + 子命令 dispatch
├── template.py              # 因子分析模板构建
├── pyproject.toml           # Python 打包配置（whl/pypi）
├── config.yaml              # 配置文件（gateway_url + token）
├── config.example.yaml      # 配置示例
├── requirements.txt         # requests, pyyaml
├── README.md                # 本文件
└── pandaai/                 # 功能模块
    ├── __init__.py           # 统一导出
    ├── constants.py          # 状态常量
    ├── config.py             # 配置加载 & token 持久化
    ├── auth.py               # 登录 & token 验证
    ├── billing.py            # 算力余额查询
    ├── factor_core.py        # 因子分析 CRUD + 轮询（含 info/update）
    ├── output.py             # 运行结果查询
    ├── factor.py             # 因子分析格式化（14 指标 + 图表）
    ├── factor_list.py        # 因子列表 & 删除（14 指标摘要）
    ├── formatting.py         # 成功/失败 JSON 格式化
    └── download.py           # CSV 下载
```

## 打包

```bash
# 构建 whl
uv run python -m build --wheel
# → dist/pandaai_cli-0.1.0-py3-none-any.whl

# 安装
pip install dist/pandaai_cli-0.1.0-py3-none-any.whl

# 使用
pandaai-cli factor_list --limit 3
```

## error.type 全集

| type | 说明 |
|------|------|
| `LOGIN_FAILED` | 登录失败 |
| `LOGIN_REQUIRED` | 未登录或 token 过期 |
| `CREATE_FAILED` | 因子分析创建失败（含限额 402） |
| `RUN_FAILED` | 因子分析启动失败 |
| `WORKFLOW_FAILED` | 因子分析代码执行报错 |
| `LIST_FAILED` | 获取因子列表失败 |
| `DELETE_FAILED` | 删除因子分析失败 |
| `INFO_FAILED` | 查看因子详情失败 |
| `UPDATE_FAILED` | 修改因子失败 |
| `BALANCE_FAILED` | 查询算力余额失败 |
| `INSUFFICIENT_BALANCE` | 余额不足被终止 |
| `TIMEOUT` | 轮询超时 |
| `INPUT_ERROR` | 输入参数错误 |
| `CONFIG_ERROR` | 配置文件不存在 |
| `UNKNOWN` | 未知错误 |
