hezor-common 0.5.1

Common utilities and data models for Hezor projects

Hezor Common

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

Features

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

Installation

pip install hezor-common

---

DataHub SDK

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

快速开始

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)

分步调用

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)

批量调用

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}")

环境变量配置

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/

---

Hezor2 SDK

向 Hezor2 服务发布创作报告。

快速开始

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)

便捷函数

from hezor_common.transfer.hezor2_sdk import publish_creation_report

response = await publish_creation_report(
    creation_result=creation_generate_result,
    task_id="monthly_report",
    execution_id="exec_2026_03_11_001",
    api_key="your-api-key",
)

环境变量配置

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

详细文档见 docs/hezor2_sdk/

---

认证方式

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

API Key 认证

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

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

MetaInfo JWT 认证（Ed25519）

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

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

---

Security 模块

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

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 数据模型，用于结构化内容创作：

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 for detailed version history.

License

MIT License - see LICENSE file for details.