# Hezor Common

Hezor 项目的公共库，提供数据模型、SDK 客户端、安全工具等通用能力。

## Features

- **Data Models** — Pydantic 数据模型（Creation、Chapter、Section 等）
- **DataHub SDK** — 智能工具搜索与执行客户端（搜索 → AI 构参 → 执行）
- **Hezor2 SDK** — 创作报告发布客户端（Webhook）
- **Security** — Ed25519 签名、JWT 编解码、密钥管理

## Installation

```bash
pip install hezor-common
```

---

## DataHub SDK

通过「搜索 → 构建参数 → 执行」三步工作流，调用 DataHub 数据接口。

### 快速开始

```python
from hezor_common.transfer.datahub_sdk import DatahubSDK

async with DatahubSDK(
    base_url="http://10.8.98.9:12580",
    api_key="your-api-key",
) as sdk:
    # 一步完成：搜索工具 → AI 构建参数 → 执行
    result = await sdk.make_call(
        query="查询日均实收金额",
        context="去年10月，门店编码 S001",
    )
    print(result.data)
```

### 分步调用

```python
async with DatahubSDK(api_key="your-api-key") as sdk:
    # 1. 搜索工具
    search_resp = await sdk.search_tools(query="查询日均实收", top_k=3)

    # 2. AI 构建参数
    args = await sdk.build_args(
        search_response=search_resp,
        args_fill_tips="去年10月，门店 S001",
    )

    # 3. 执行工具
    result = await sdk.execute_tool(
        tool_name=search_resp.tools[0].name,
        args=args,
    )
    print(result.success, result.data)
```

### 批量调用

```python
async with DatahubSDK(api_key="your-api-key") as sdk:
    results = await sdk.make_call_multi(
        query="查询品牌信息",
        context="获取所有品牌和品类",
        top_k=3,
    )
    for tool_name, result in results.items():
        print(f"{tool_name}: {result.data}")
```

### 环境变量配置

```bash
DATAHUB_API_BASE_URL=http://192.168.0.125:12580
DATAHUB_API_KEY=your-api-key
DATAHUB_LLM_MODEL_ID=gpt-oss-20b
DATAHUB_LLM_API_KEY=your-llm-api-key
DATAHUB_LLM_BASE_URL=http://localhost:8000
```

> 详细文档见 [docs/datahub_sdk/](docs/datahub_sdk/README.md)

---

## Hezor2 SDK

向 Hezor2 服务发布创作报告。

### 快速开始

```python
from hezor_common.transfer.hezor2_sdk import Hezor2SDK, CreationGenerateResult

async with Hezor2SDK(
    base_url="http://localhost:8000",
    api_key="your-api-key",
) as sdk:
    result = await sdk.publish_creation_report(
        creation_result=creation_generate_result,
        task_id="monthly_report",
        execution_id="exec_2026_03_11_001",
    )
    print(result.status, result.report_id)
```

### 环境变量配置

```bash
HEZOR2_API_BASE_URL=http://localhost:8000
HEZOR2_API_KEY=your-api-key
```

> 详细文档见 [docs/hezor2_sdk/](docs/hezor2_sdk/api_reference.md)

---

## 认证方式

两个 SDK 共享相同的认证机制，支持 **API Key** 和 **MetaInfo JWT** 两种方式。

### API Key 认证

通过 `Authorization: Bearer <api_key>` 请求头传递：

```python
async with DatahubSDK(api_key="your-api-key") as sdk:
    ...
```

### MetaInfo JWT 认证（Ed25519）

通过 `X-META-INFO` 请求头传递 JWT Token，携带业务元信息并使用 Ed25519 私钥签名：

```python
from hezor_common.transfer.base_sdk import MetaInfo

meta = MetaInfo(
    subject="鮨大山",
    subject_code="wdyl_001",
    caller_id="user_123",
    data_coverage="202401-202412",
    creation_slug="single_store_profit_model",
    creation_name="单店盈利模型",
)

async with DatahubSDK(
    api_key="your-api-key",
    meta_info=meta,
    private_key_path="private_key.pem",
    password=b"your_password",
    meta_info_expires_in=3600,
) as sdk:
    ...
```

两种认证可同时使用，也可单独使用。

> 详细认证文档见 [docs/datahub_sdk/authentication.md](docs/datahub_sdk/authentication.md)

---

## Security 模块

提供 Ed25519 密钥管理、消息签名和 JWT 编解码：

```python
from hezor_common.security import (
    generate_key_pair,
    serialize_private_key,
    serialize_public_key,
    encode,  # JWT 编码 (encode_jwt_with_file)
    decode,  # JWT 解码 (decode_jwt_with_file)
    sign,    # JSON 签名 (sign_json_with_file)
    verify,  # 签名验证 (verify_json_signature_with_file)
)

# 生成密钥对
private_key, public_key = generate_key_pair()
private_pem = serialize_private_key(private_key, password=b"secret")
public_pem = serialize_public_key(public_key)

# JWT 签名与验证
token = encode("private_key.pem", payload={"user": "test"}, password=b"secret", expires_in=3600)
data = decode("public_key.pem", token=token, verify=True)
```

---

## Data Models

Pydantic 数据模型，用于结构化内容创作：

```python
from hezor_common.data_model import (
    CreationModel,
    CreationMeta,
    Author,
    ChapterModel,
    SectionModel,
)

author = Author(name="John Doe", avatar="https://example.com/avatar.jpg")
meta = CreationMeta(
    name="Single Store Profit Model",
    description="A comprehensive profit analysis model",
    author=author,
    path="food_beverage/single_store_profit_model",
    domain="food_beverage",
    slug="single_store_profit_model",
)
creation = CreationModel(meta=meta, summary=None, chapters=[])
```

**导出模型**：

- **Creation**: `CreationModel`, `CreationMeta`, `CreationSummary`, `Author`, `Contributor`
- **Chapter**: `ChapterModel`, `ChapterMeta`, `ChapterSummary`
- **Section**: `SectionModel`, `TitleGuideline`, `DataQuery`, `Dataset`, `ChartSuggestion`, `AnalysisGuideline`
- **Results**: `SectionGenerateResult`, `ChapterGenerateResult`

---

## Requirements

- Python >= 3.11
- pydantic >= 2.0.0

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for detailed version history.

## License

MIT License - see LICENSE file for details.

