zerone-cli 0.1.8__tar.gz → 0.3.1__tar.gz

zerone_cli-0.3.1/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: zerone-cli
+Version: 0.3.1
+Summary: Zerone 私募股权数据 CLI 工具
+Author-email: Zerone <tech@zerone.com.cn>
+License: MIT
+Project-URL: Homepage, https://ai.zerone.com.cn
+Project-URL: Documentation, https://ai.zerone.com.cn
+Keywords: cli,private-equity,finance,mcp,zerone
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: typer>=0.9.0
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: pandas>=2.0.0
+
+# Zerone CLI
+
+Zerone 私募股权数据命令行工具，通过 API Key 直接查询 Zerone 数据平台。
+
+## 安装
+
+```bash
+pip install zerone-cli
+```
+
+## 快速开始
+
+### 1. 配置 API Key
+
+```bash
+zerone config set-api-key YOUR_API_KEY
+```
+
+> 如何获取 API Key？请访问 [https://ai.zerone.com.cn](https://ai.zerone.com.cn) 注册账号后申请。
+
+### 2. 查看帮助
+
+```bash
+zerone --help
+```
+
+### 3. 开始查询
+
+#### 第一层：实体定位
+
+```bash
+# 实体模糊搜索
+zerone entity-search "字节跳动"
+```
+
+#### 第二层：业务专题
+
+```bash
+# 查询实体综合画像
+zerone entity-profile "中国石油"
+
+# 查询实体财务数据列表
+zerone entity-financial-list "中国石油" --page 1 --page-size 50
+
+# 查询融资概率预测
+zerone model-financing-probability "字节跳动" --type COMPANY
+
+# 查询机构匹配推荐
+zerone model-company-match-gp "字节跳动" --page 1 --page-size 5
+```
+
+#### 第三层：通用数据查询
+
+```bash
+# 查看有哪些表可以查
+zerone get-available-tables
+
+# 查看某张表的结构（字段名、类型、支持的操作符）
+zerone get-table-schema company
+
+# 单表查询（通过 JSON 文件传入参数）
+zerone query --json-file query.json
+
+# 聚合查询（通过 JSON 文件传入参数）
+zerone aggregate --json-file aggregate.json
+```
+
+## 命令列表
+
+| 命令 | 说明 | 层级 |
+|------|------|------|
+| `zerone config set-api-key` | 设置 API Key | — |
+| `zerone config set-server-url` | 设置服务器地址（可选） | — |
+| `zerone config show` | 查看当前配置 | — |
+| `zerone entity-search` | 实体模糊搜索 | 第一层 |
+| `zerone entity-profile` | 查询实体综合画像 | 第二层 |
+| `zerone entity-financial-list` | 查询实体财务数据列表（分页） | 第二层 |
+| `zerone model-financing-probability` | 查询融资概率预测模型 | 第二层 |
+| `zerone model-company-match-gp` | 为项目公司匹配潜在投资机构 | 第二层 |
+| `zerone get-available-tables` | 获取可查询表列表 | 第三层 |
+| `zerone get-table-schema` | 获取指定表结构 | 第三层 |
+| `zerone query` | 单表查询（筛选/排序/分页） | 第三层 |
+| `zerone aggregate` | 聚合查询（GROUP BY + 聚合函数） | 第三层 |
+
+## 通用查询 JSON 参数示例
+
+### query.json（单表查询）
+
+```json
+{
+  "table": "company",
+  "select_columns": ["company_name", "found_date", "vertical"],
+  "filters": [
+    {"field": "vertical", "type": "like", "value": "人工智能"},
+    {"field": "found_date", "type": "range", "value": ["2020-01-01", "2024-12-31"]}
+  ],
+  "order_by": ["found_date DESC"],
+  "limit": 50
+}
+```
+
+### aggregate.json（聚合查询）
+
+```json
+{
+  "table": "company",
+  "group_by": ["reg_province"],
+  "metrics": [
+    {"field": "company_id", "func": "count", "alias": "company_count"}
+  ],
+  "filters": [
+    {"field": "vertical", "type": "like", "value": "人工智能"}
+  ],
+  "order_by": ["company_count DESC"],
+  "limit": 50
+}
+```
+
+### 使用方式
+
+```bash
+# 从文件读取参数
+zerone query --json-file query.json
+zerone aggregate --json-file aggregate.json
+
+# 直接传入 JSON 字符串
+zerone query --json '{"table":"company","select_columns":["company_name"],"limit":10}'
+zerone aggregate --json '{"table":"company","group_by":["reg_province"],"metrics":[{"field":"company_id","func":"count","alias":"cnt"}]}'
+```
+
+## 常用参数说明
+
+### 分页参数
+- `--page`: 页码，从1开始，默认1
+- `--page-size`: 每页条数，默认50，上限50
+
+### 输出格式
+- `--output`: 输出格式，可选 table/json/csv，默认 table
+
+### 查询参数
+- `--json-file`: JSON 参数文件路径（query/aggregate 专用）
+- `--json`: JSON 参数字符串（query/aggregate 专用）
+
+## 配置说明
+
+配置文件保存在 `~/.zerone/config.yaml`，支持以下环境变量覆盖：
+
+| 环境变量 | 说明 |
+|----------|------|
+| `ZERONE_API_KEY` | API Key |
+| `ZERONE_SERVER_URL` | 服务器地址 |
+
+## 系统要求
+
+- Python 3.9+
+- 有效的 Zerone API Key
+
+## 许可证
+
+MIT

zerone_cli-0.3.1/README.md

@@ -0,0 +1,160 @@
+# Zerone CLI
+
+Zerone 私募股权数据命令行工具，通过 API Key 直接查询 Zerone 数据平台。
+
+## 安装
+
+```bash
+pip install zerone-cli
+```
+
+## 快速开始
+
+### 1. 配置 API Key
+
+```bash
+zerone config set-api-key YOUR_API_KEY
+```
+
+> 如何获取 API Key？请访问 [https://ai.zerone.com.cn](https://ai.zerone.com.cn) 注册账号后申请。
+
+### 2. 查看帮助
+
+```bash
+zerone --help
+```
+
+### 3. 开始查询
+
+#### 第一层：实体定位
+
+```bash
+# 实体模糊搜索
+zerone entity-search "字节跳动"
+```
+
+#### 第二层：业务专题
+
+```bash
+# 查询实体综合画像
+zerone entity-profile "中国石油"
+
+# 查询实体财务数据列表
+zerone entity-financial-list "中国石油" --page 1 --page-size 50
+
+# 查询融资概率预测
+zerone model-financing-probability "字节跳动" --type COMPANY
+
+# 查询机构匹配推荐
+zerone model-company-match-gp "字节跳动" --page 1 --page-size 5
+```
+
+#### 第三层：通用数据查询
+
+```bash
+# 查看有哪些表可以查
+zerone get-available-tables
+
+# 查看某张表的结构（字段名、类型、支持的操作符）
+zerone get-table-schema company
+
+# 单表查询（通过 JSON 文件传入参数）
+zerone query --json-file query.json
+
+# 聚合查询（通过 JSON 文件传入参数）
+zerone aggregate --json-file aggregate.json
+```
+
+## 命令列表
+
+| 命令 | 说明 | 层级 |
+|------|------|------|
+| `zerone config set-api-key` | 设置 API Key | — |
+| `zerone config set-server-url` | 设置服务器地址（可选） | — |
+| `zerone config show` | 查看当前配置 | — |
+| `zerone entity-search` | 实体模糊搜索 | 第一层 |
+| `zerone entity-profile` | 查询实体综合画像 | 第二层 |
+| `zerone entity-financial-list` | 查询实体财务数据列表（分页） | 第二层 |
+| `zerone model-financing-probability` | 查询融资概率预测模型 | 第二层 |
+| `zerone model-company-match-gp` | 为项目公司匹配潜在投资机构 | 第二层 |
+| `zerone get-available-tables` | 获取可查询表列表 | 第三层 |
+| `zerone get-table-schema` | 获取指定表结构 | 第三层 |
+| `zerone query` | 单表查询（筛选/排序/分页） | 第三层 |
+| `zerone aggregate` | 聚合查询（GROUP BY + 聚合函数） | 第三层 |
+
+## 通用查询 JSON 参数示例
+
+### query.json（单表查询）
+
+```json
+{
+  "table": "company",
+  "select_columns": ["company_name", "found_date", "vertical"],
+  "filters": [
+    {"field": "vertical", "type": "like", "value": "人工智能"},
+    {"field": "found_date", "type": "range", "value": ["2020-01-01", "2024-12-31"]}
+  ],
+  "order_by": ["found_date DESC"],
+  "limit": 50
+}
+```
+
+### aggregate.json（聚合查询）
+
+```json
+{
+  "table": "company",
+  "group_by": ["reg_province"],
+  "metrics": [
+    {"field": "company_id", "func": "count", "alias": "company_count"}
+  ],
+  "filters": [
+    {"field": "vertical", "type": "like", "value": "人工智能"}
+  ],
+  "order_by": ["company_count DESC"],
+  "limit": 50
+}
+```
+
+### 使用方式
+
+```bash
+# 从文件读取参数
+zerone query --json-file query.json
+zerone aggregate --json-file aggregate.json
+
+# 直接传入 JSON 字符串
+zerone query --json '{"table":"company","select_columns":["company_name"],"limit":10}'
+zerone aggregate --json '{"table":"company","group_by":["reg_province"],"metrics":[{"field":"company_id","func":"count","alias":"cnt"}]}'
+```
+
+## 常用参数说明
+
+### 分页参数
+- `--page`: 页码，从1开始，默认1
+- `--page-size`: 每页条数，默认50，上限50
+
+### 输出格式
+- `--output`: 输出格式，可选 table/json/csv，默认 table
+
+### 查询参数
+- `--json-file`: JSON 参数文件路径（query/aggregate 专用）
+- `--json`: JSON 参数字符串（query/aggregate 专用）
+
+## 配置说明
+
+配置文件保存在 `~/.zerone/config.yaml`，支持以下环境变量覆盖：
+
+| 环境变量 | 说明 |
+|----------|------|
+| `ZERONE_API_KEY` | API Key |
+| `ZERONE_SERVER_URL` | 服务器地址 |
+
+## 系统要求
+
+- Python 3.9+
+- 有效的 Zerone API Key
+
+## 许可证
+
+MIT

zerone_cli-0.3.1/cli/client.py

@@ -0,0 +1,173 @@
+from typing import Any, Optional
+
+import httpx
+
+from cli.config import config_manager
+
+
+class MCPClient:
+
+    def __init__(self):
+        self.api_key = config_manager.get_api_key()
+        self.server_url = config_manager.get_server_url()
+        self.client = httpx.Client(timeout=60.0)
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        json_data: Optional[dict] = None,
+        params: Optional[dict] = None,
+    ) -> dict:
+        url = f"{self.server_url}{path}"
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+
+        try:
+            response = self.client.request(
+                method=method,
+                url=url,
+                headers=headers,
+                json=json_data,
+                params=params,
+            )
+            response.raise_for_status()
+            data = response.json()
+            if not data.get("success", True):
+                error = data.get("error", {})
+                raise ValueError(f"[{error.get('code', 'UNKNOWN')}] {error.get('message', '未知错误')}")
+            return data
+        except httpx.HTTPStatusError as e:
+            try:
+                error_data = e.response.json()
+                detail = error_data.get("detail", "")
+                if detail:
+                    raise ValueError(f"[HTTP {e.response.status_code}] {detail}")
+            except ValueError:
+                raise
+            except Exception:
+                pass
+            raise ValueError(f"请求失败: {e.response.status_code} - {e.response.text}")
+        except httpx.ConnectError:
+            raise ValueError(f"无法连接到 MCP Server，请检查 server_url 配置：{self.server_url}")
+        except httpx.TimeoutException:
+            raise ValueError("请求超时，请检查网络连接或稍后重试")
+
+    # ========== 第一层：实体定位 ==========
+
+    def entity_search(self, keyword: str) -> dict:
+        return self._request(
+            "POST",
+            "/rest-api/tool/entity_search",
+            json_data={"keyword": keyword},
+        )
+
+    # ========== 第二层：业务专题 ==========
+
+    def entity_profile(
+        self,
+        entity_name: str,
+        entity_type: Optional[str] = None,
+    ) -> dict:
+        return self._request(
+            "POST",
+            "/rest-api/tool/entity_profile",
+            json_data={
+                "entity_name": entity_name,
+                "entity_type": entity_type or "",
+            },
+        )
+
+    def entity_financial_list(
+        self,
+        entity_name: str,
+        entity_type: Optional[str] = None,
+        page: int = 1,
+        page_size: int = 50,
+    ) -> dict:
+        return self._request(
+            "POST",
+            "/rest-api/tool/entity_financial_list",
+            json_data={
+                "entity_name": entity_name,
+                "entity_type": entity_type or "",
+                "page": page,
+                "page_size": page_size,
+            },
+        )
+
+    def model_financing_probability(
+        self,
+        entity_name: str,
+        entity_type: Optional[str] = None,
+    ) -> dict:
+        return self._request(
+            "POST",
+            "/rest-api/tool/model_financing_probability",
+            json_data={
+                "entity_name": entity_name,
+                "entity_type": entity_type or "",
+            },
+        )
+
+    def model_company_match_gp(
+        self,
+        company_name: str,
+        page: int = 1,
+        page_size: int = 5,
+    ) -> dict:
+        return self._request(
+            "POST",
+            "/rest-api/tool/model_company_match_gp",
+            json_data={
+                "company_name": company_name,
+                "page": page,
+                "page_size": page_size,
+            },
+        )
+
+    # ========== 第三层：通用数据查询 ==========
+
+    def get_available_tables(self) -> dict:
+        return self._request("POST", "/rest-api/tool/get_available_tables")
+
+    def get_table_schema(self, table_name: str) -> dict:
+        return self._request(
+            "POST",
+            "/rest-api/tool/get_table_schema",
+            json_data={"table_name": table_name},
+        )
+
+    def execute_query(self, payload: dict) -> dict:
+        return self._request(
+            "POST",
+            "/rest-api/tool/execute_query",
+            json_data=payload,
+        )
+
+    def execute_aggregate_query(self, payload: dict) -> dict:
+        return self._request(
+            "POST",
+            "/rest-api/tool/execute_aggregate_query",
+            json_data=payload,
+        )
+
+    # ========== Debug ==========
+
+    def debug_preview_sql(self, payload: dict) -> dict:
+        return self._request(
+            "POST",
+            "/debug/preview-sql",
+            json_data=payload,
+        )
+
+    def close(self):
+        self.client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()

zerone_cli-0.3.1/cli/commands/__init__.py

@@ -0,0 +1,23 @@
+from cli.commands import config_cmd
+from cli.commands.entity_search import entity_search
+from cli.commands.entity_profile import entity_profile
+from cli.commands.entity_financial_list import entity_financial_list
+from cli.commands.model_financing_probability import model_financing_probability
+from cli.commands.model_company_match_gp import model_company_match_gp
+from cli.commands.get_available_tables import get_available_tables
+from cli.commands.get_table_schema import get_table_schema
+from cli.commands.execute_query import execute_query
+from cli.commands.execute_aggregate_query import execute_aggregate_query
+
+__all__ = [
+    "config_cmd",
+    "entity_search",
+    "entity_profile",
+    "entity_financial_list",
+    "model_financing_probability",
+    "model_company_match_gp",
+    "get_available_tables",
+    "get_table_schema",
+    "execute_query",
+    "execute_aggregate_query",
+]

zerone_cli-0.3.1/cli/commands/execute_aggregate_query.py

@@ -0,0 +1,73 @@
+import json
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from cli.client import MCPClient
+from cli.utils.output import print_result
+
+
+def execute_aggregate_query(
+    json_file: Optional[str] = typer.Option(
+        None, "--json-file", "-f",
+        help="JSON 参数文件路径，内含 table/group_by/metrics/filters/order_by/limit"
+    ),
+    json_string: Optional[str] = typer.Option(
+        None, "--json", "-j",
+        help="JSON 参数字符串"
+    ),
+    output: str = typer.Option("table", "--output", "-o", help="输出格式：table/json/csv"),
+):
+    """
+    通用聚合查询
+
+    支持 GROUP BY + 聚合函数（sum/avg/max/min/count/count_distinct）。
+    参数较复杂，必须通过 JSON 文件或 JSON 字符串传入。
+
+    JSON 参数示例：
+        {
+          "table": "company",
+          "group_by": ["reg_province"],
+          "metrics": [
+            {"field": "company_id", "func": "count", "alias": "company_count"}
+          ],
+          "filters": [
+            {"field": "vertical", "type": "like", "value": "人工智能"}
+          ],
+          "order_by": ["company_count DESC"],
+          "limit": 50
+        }
+
+    示例：
+        zerone aggregate --json-file aggregate.json
+        zerone aggregate --json '{"table":"company","group_by":["reg_province"],"metrics":[{"field":"company_id","func":"count","alias":"cnt"}]}'
+    """
+    payload = None
+
+    if json_file:
+        path = Path(json_file)
+        if not path.exists():
+            typer.echo(f"错误: 文件不存在 {json_file}", err=True)
+            raise typer.Exit(1)
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    elif json_string:
+        payload = json.loads(json_string)
+    else:
+        typer.echo(
+            "错误: 必须提供 --json-file 或 --json 参数。\n"
+            "使用 --help 查看 JSON 参数格式示例。",
+            err=True,
+        )
+        raise typer.Exit(1)
+
+    try:
+        with MCPClient() as client:
+            result = client.execute_aggregate_query(payload)
+            print_result(result, output)
+    except ValueError as e:
+        typer.echo(f"错误: {e}", err=True)
+        raise typer.Exit(1)
+    except Exception as e:
+        typer.echo(f"请求失败: {e}", err=True)
+        raise typer.Exit(1)

zerone_cli-0.3.1/cli/commands/execute_query.py

@@ -0,0 +1,81 @@
+import json
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from cli.client import MCPClient
+from cli.utils.output import print_result
+
+
+def execute_query(
+    json_file: Optional[str] = typer.Option(
+        None, "--json-file", "-f",
+        help="JSON 参数文件路径，内含 table/select_columns/filters/order_by/limit"
+    ),
+    json_string: Optional[str] = typer.Option(
+        None, "--json", "-j",
+        help="JSON 参数字符串，如 '{\"table\":\"company\",\"select_columns\":[\"company_name\"],\"limit\":10}'"
+    ),
+    table: Optional[str] = typer.Option(
+        None, "--table", "-t",
+        help="表名（与 --json-file/--json 互斥时使用）"
+    ),
+    limit: int = typer.Option(
+        200, "--limit", "-l",
+        help="返回条数上限"
+    ),
+    output: str = typer.Option("table", "--output", "-o", help="输出格式：table/json/csv"),
+):
+    """
+    通用单表查询
+
+    支持筛选、排序、分页。参数较复杂，推荐通过 JSON 文件传入。
+
+    JSON 参数示例：
+        {
+          "table": "company",
+          "select_columns": ["company_name", "found_date", "vertical"],
+          "filters": [
+            {"field": "vertical", "type": "like", "value": "人工智能"},
+            {"field": "found_date", "type": "range", "value": ["2020-01-01", "2024-12-31"]}
+          ],
+          "order_by": ["found_date DESC"],
+          "limit": 50
+        }
+
+    示例：
+        zerone query --json-file query.json
+        zerone query --json '{"table":"company","select_columns":["company_name"],"limit":10}'
+        zerone query --table company --limit 10
+    """
+    payload = None
+
+    if json_file:
+        path = Path(json_file)
+        if not path.exists():
+            typer.echo(f"错误: 文件不存在 {json_file}", err=True)
+            raise typer.Exit(1)
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    elif json_string:
+        payload = json.loads(json_string)
+    elif table:
+        payload = {"table": table, "select_columns": [], "limit": limit}
+    else:
+        typer.echo(
+            "错误: 必须提供 --json-file、--json 或 --table 参数。\n"
+            "使用 --help 查看 JSON 参数格式示例。",
+            err=True,
+        )
+        raise typer.Exit(1)
+
+    try:
+        with MCPClient() as client:
+            result = client.execute_query(payload)
+            print_result(result, output)
+    except ValueError as e:
+        typer.echo(f"错误: {e}", err=True)
+        raise typer.Exit(1)
+    except Exception as e:
+        typer.echo(f"请求失败: {e}", err=True)
+        raise typer.Exit(1)