# DataHub SDK 文档

DataHub SDK 是一个用于访问 DataHub API 的 Python SDK，提供了搜索工具、参数构建和工具执行等功能的统一接口。

## � 工作原理

DataHub SDK 通过三步工作流程实现智能工具调用：

```
用户意图 → 搜索工具 → 构建参数 → 执行工具 → 返回结果
```

1. **搜索工具**：根据用户的查询意图（`query`），在 DataHub 中搜索最匹配的工具
2. **构建参数**：使用 AI 模型根据上下文（`context`）自动生成工具所需的参数
3. **执行工具**：调用 DataHub API 执行工具，获取数据结果

**核心优势**：
- 🎯 **自动化**：无需手动查找工具或构造参数
- 🧠 **智能化**：AI 理解自然语言并生成正确参数
- 🔄 **容错性**：参数构建失败时自动重试

示例流程：
```python
# 用户只需提供意图和上下文
result = await sdk.make_call(
    query="查询日均实收",           # 搜索 → 找到 query_daily_avg_received_amount 工具
    context="去年10月，门店S001"    # 构建参数 → {"month": "202410", "store_code": "S001"}
)                                  # 执行 → 返回查询结果
```

## �📚 文档导航

### 详细指南
- **[安装和配置](installation.md)** - 安装方式和环境变量配置
- **[基本用法](basic_usage.md)** - make_call、make_call_multi 和分步调用
- **[认证方式](authentication.md)** - API Key 和 MetaInfo JWT 认证详解
- **[高级功能](advanced.md)** - 自定义 LLM、调试模式、工具函数构建

### 参考资料
- **[API 参考](api_reference.md)** - 完整的类和方法文档
- **[最佳实践](best_practices.md)** - 开发建议和常见问题解答

---

## 🚀 快速开始

5 分钟快速上手 DataHub SDK。

### 安装

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

### 环境配置（可选）

DataHub SDK 支持两种配置方式：

**方式 1: 通过构造参数配置（推荐用于快速测试）**

```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:
    result = await sdk.make_call("query")
```

**方式 2: 通过环境变量配置（推荐用于生产环境）**

创建 `.env` 文件：

```bash
DATAHUB_API_BASE_URL=http://10.8.98.9: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
```

**⚠️ 关键：必须在导入 SDK 之前加载环境变量**

```python
from dotenv import load_dotenv
load_dotenv()  # 1. 先加载环境变量

from hezor_common.transfer.datahub_sdk import DatahubSDK  # 2. 再导入 SDK
```

> 详细配置说明请参考 [安装和配置](installation.md)

### 基本使用

#### 示例 1: 最简单的调用

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

async def main():
    # 方式 1: 直接传参配置
    async with DatahubSDK(
        base_url="http://10.8.98.9:12580",
        api_key="your-api-key"
    ) as sdk:
        result = await sdk.make_call("get_brands_categories")
        print(result.data)
    
    # 方式 2: 使用环境变量（需先 load_dotenv()）
    async with DatahubSDK() as sdk:
        result = await sdk.make_call("get_brands_categories")
        print(result.data)

asyncio.run(main())
```

#### 示例 2: 带上下文的调用

```python
async with DatahubSDK(
    base_url="http://10.8.98.9:12580",
    api_key="your-api-key"
) as sdk:
    result = await sdk.make_call(
        query="query_daily_avg_received_amount",
        context="去年 10 月日均实收，门店 code 填写 1"
    )
    print(result.data)
```

#### 示例 3: 带认证的调用

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

meta_info = MetaInfo(
    caller_id="user_123",
    subject="鮨大山",
    subject_code="s0001",
    creation_name="单店盈利模型",
    creation_slug="single_store_profit_model",
    data_coverage="20240101-20241231"
)

async with DatahubSDK(
    api_key="your-api-key",
    meta_info=meta_info,
    private_key_path="private_key.pem",
    password=b"your-password"
) as sdk:
    result = await sdk.make_call("get_brands_categories")
    print(result.data)
```

> 详细认证说明请参考 [认证方式](authentication.md)

#### 示例 4: 批量调用多个工具

```python
async with DatahubSDK(
    base_url="http://10.8.98.9:12580",
    api_key="your-api-key"
) as sdk:
    results = await sdk.make_call_multi(
        query="查询品牌",
        context="获取所有品牌和品类信息",
        top_k=2  # 返回最匹配的 2 个工具
    )
    
    for tool_name, result in results.items():
        print(f"{tool_name}: {result.data}")
```

### 完整示例

运行项目中的完整示例：

```bash
# 列出所有示例
uv run examples/transfer/datahub_sdk_example.py --list

# 运行示例 1
uv run examples/transfer/datahub_sdk_example.py 1

# 运行所有示例
uv run examples/transfer/datahub_sdk_example.py
```

### 下一步

- 📖 [基本用法](basic_usage.md) - 了解更多使用方式
- 🔐 [认证方式](authentication.md) - 配置 API Key 和 JWT 认证
- 🚀 [高级功能](advanced.md) - 自定义 LLM、调试模式等
- ❓ [最佳实践](best_practices.md) - 常见问题和解决方案

### 常见问题

**Q: 必须使用环境变量吗？**

A: 不是必须的。你可以：
- 直接通过构造参数传递配置（适合快速测试）
- 使用环境变量配置（适合生产环境，便于管理）

**Q: 如果使用环境变量，为什么 SDK 没有读取到 .env 中的配置？**

A: 必须在导入 SDK **之前**调用 `load_dotenv()`，详见 [最佳实践](best_practices.md#环境变量加载顺序)

**Q: 如何查看更多示例？**

A: 查看 [examples/transfer/datahub_sdk_example.py](../../examples/transfer/datahub_sdk_example.py)

---

## 📦 示例代码

完整的可运行示例：
- [examples/transfer/datahub_sdk_example.py](../../examples/transfer/datahub_sdk_example.py)

## 🔗 相关资源

- [项目主页](../../README.md)
- [数据模型定义](../../src/hezor_common/data_model/searching/data/api_models.py)
