# API 参考

完整的 DataHub SDK API 文档。

## DatahubSDK 类

### 构造函数

```python
DatahubSDK(
    base_url: str = DEFAULT_DATA_API_BASE_URL,
    timeout: float = 30.0,
    api_key: str | None = DEFAULT_DATA_API_KEY,
    meta_info: MetaInfo | None = None,
    private_key_path: str | Path | None = None,
    password: bytes | None = None,
    meta_info_expires_in: int = 3600,
    model: Model | None = None
)
```

#### 参数

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `base_url` | `str` | 环境变量 | DataHub API 基础 URL |
| `timeout` | `float` | `30.0` | 请求超时时间（秒） |
| `api_key` | `str \| None` | 环境变量 | API 密钥 |
| `meta_info` | `MetaInfo \| None` | `None` | 元信息对象（用于 JWT 认证） |
| `private_key_path` | `str \| Path \| None` | `None` | 私钥文件路径 |
| `password` | `bytes \| None` | `None` | 私钥密码 |
| `meta_info_expires_in` | `int` | `3600` | JWT token 过期时间（秒） |
| `model` | `Model \| None` | `None` | AI 模型（用于参数构建） |

#### 示例

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

async with DatahubSDK(
    base_url="http://api.example.com",
    timeout=60.0,
    api_key="your-api-key"
) as sdk:
    # 使用 SDK
    pass
```

---

## 核心方法

### make_call()

快捷调用方法，自动搜索工具、构建参数并执行。

```python
async def make_call(
    query: str,
    context: str = "",
    max_retries: int = 3,
    model_kwargs: dict[str, Any] | None = None,
    agent_kwargs: dict[str, Any] | None = None
) -> ExecuteResponse
```

#### 参数

- **query** (`str`) - 工具调用意图（用于搜索工具）
- **context** (`str`) - 调用上下文或参数提示，默认为空
- **max_retries** (`int`) - 调用失败时的最大重试次数，默认为 3
- **model_kwargs** (`dict[str, Any] | None`) - 模型参数，可选
- **agent_kwargs** (`dict[str, Any] | None`) - Agent 参数，可选

#### 返回

`ExecuteResponse` - 执行结果

#### 异常

- `ValueError` - 未找到匹配的工具
- `Exception` - 执行失败或其他错误

#### 示例

```python
result = await sdk.make_call(
    query="get_weather",
    context="查询北京今天的天气",
    max_retries=5
)
```

---

### make_call_multi()

批量调用多个工具。

```python
async def make_call_multi(
    query: str,
    context: str = "",
    top_k: int = 3,
    max_retries: int = 3,
    model_kwargs: dict[str, Any] | None = None,
    agent_kwargs: dict[str, Any] | None = None
) -> dict[str, ExecuteResponse]
```

#### 参数

- **query** (`str`) - 工具调用意图
- **context** (`str`) - 调用上下文
- **top_k** (`int`) - 返回工具数量，默认为 3
- **max_retries** (`int`) - 参数构建失败时的最大重试次数
- **model_kwargs** (`dict[str, Any] | None`) - 模型参数
- **agent_kwargs** (`dict[str, Any] | None`) - Agent 参数

#### 返回

`dict[str, ExecuteResponse]` - 工具名到执行结果的映射

#### 示例

```python
results = await sdk.make_call_multi(
    query="查询品牌",
    context="获取品牌信息",
    top_k=5
)

for tool_name, result in results.items():
    print(f"{tool_name}: {result.data}")
```

---

### search_tools()

搜索工具。

```python
async def search_tools(
    query: str,
    top_k: int = 3
) -> SearchResponse
```

#### 参数

- **query** (`str`) - 搜索查询
- **top_k** (`int`) - 返回结果数量，默认为 3

#### 返回

`SearchResponse` - 搜索结果
- `tools` - 工具列表 (`list[ToolSchema]`)

#### 示例

```python
search_resp = await sdk.search_tools("天气查询", top_k=5)
for tool in search_resp.tools:
    print(f"工具: {tool.name}")
```

---

### build_args()

为单个工具构建参数。

```python
async def build_args(
    search_response: SearchResponse,
    args_fill_tips: str = "请根据工具的参数说明填写合适的参数值",
    max_retries: int = 3,
    model_kwargs: dict[str, Any] | None = None,
    agent_kwargs: dict[str, Any] | None = None,
    tool_index: int = 0
) -> dict[str, Any]
```

#### 参数

- **search_response** (`SearchResponse`) - 工具搜索响应
- **args_fill_tips** (`str`) - 参数填写提示
- **max_retries** (`int`) - 最大重试次数
- **model_kwargs** (`dict[str, Any] | None`) - 模型参数
- **agent_kwargs** (`dict[str, Any] | None`) - Agent 参数
- **tool_index** (`int`) - 工具索引，默认为 0

#### 返回

`dict[str, Any]` - 工具参数

#### 示例

```python
args = await sdk.build_args(
    search_response=search_resp,
    args_fill_tips="查询北京的天气",
    tool_index=0
)
```

---

### build_args_for_all_tools()

为所有工具构建参数。

```python
async def build_args_for_all_tools(
    search_response: SearchResponse,
    args_fill_tips: str = "请根据工具的参数说明填写合适的参数值",
    max_retries: int = 3,
    model_kwargs: dict[str, Any] | None = None,
    agent_kwargs: dict[str, Any] | None = None
) -> dict[str, dict[str, Any]]
```

#### 参数

- **search_response** (`SearchResponse`) - 工具搜索响应
- **args_fill_tips** (`str`) - 参数填写提示
- **max_retries** (`int`) - 最大重试次数
- **model_kwargs** (`dict[str, Any] | None`) - 模型参数
- **agent_kwargs** (`dict[str, Any] | None`) - Agent 参数

#### 返回

`dict[str, dict[str, Any]]` - 所有工具的参数，键为工具名称

#### 示例

```python
all_args = await sdk.build_args_for_all_tools(
    search_response=search_resp,
    args_fill_tips="查询天气信息"
)

for tool_name, args in all_args.items():
    print(f"{tool_name} 参数: {args}")
```

---

### execute_tool()

执行工具。

```python
async def execute_tool(
    tool_name: str,
    args: dict[str, Any]
) -> ExecuteResponse
```

#### 参数

- **tool_name** (`str`) - 工具名称
- **args** (`dict[str, Any]`) - 工具参数

#### 返回

`ExecuteResponse` - 执行结果

#### 示例

```python
result = await sdk.execute_tool(
    tool_name="get_weather",
    args={"city": "Beijing"}
)
```

---

### execute_tool_from_json()

从 JSON 字符串执行工具。

```python
async def execute_tool_from_json(
    request_json: str
) -> ExecuteResponse
```

#### 参数

- **request_json** (`str`) - 包含工具名称和参数的 JSON 字符串

#### 返回

`ExecuteResponse` - 执行结果

#### 示例

```python
json_str = '{"tool": "get_weather", "args": {"city": "Beijing"}}'
result = await sdk.execute_tool_from_json(json_str)
```

---

### build_tool_functions()

构建工具函数。

```python
def build_tool_functions(
    tools: SearchResponse | list[Any]
) -> dict[str, Any]
```

#### 参数

- **tools** (`SearchResponse | list[Any]`) - 搜索响应或工具列表

#### 返回

`dict[str, Any]` - 工具函数字典

#### 示例

```python
search_resp = await sdk.search_tools("天气")
funcs = sdk.build_tool_functions(search_resp)

# 调用生成的函数
result = await funcs["get_weather"](city="Beijing")
```

---

## 数据模型

### ExecuteResponse

执行结果响应。

```python
class ExecuteResponse(BaseModel):
    data: dict[str, Any] | list[Any]
```

#### 字段

- **data** - 执行结果数据，可能是字典或列表

#### 示例

```python
result = await sdk.make_call("query")

if isinstance(result.data, dict):
    print(result.data["key"])
elif isinstance(result.data, list):
    for item in result.data:
        print(item)
```

---

### SearchResponse

搜索结果响应。

```python
class SearchResponse(BaseModel):
    tools: list[ToolSchema]
```

#### 字段

- **tools** - 搜索到的工具列表

---

### MetaInfo

元信息对象（用于 JWT 认证）。

```python
class MetaInfo(BaseModel):
    subject: str
    subject_code: str
    caller_id: str
    data_coverage: str
    creation_slug: str
    creation_name: str
```

#### 字段

- **subject** - 数据主体名称
- **subject_code** - 主体唯一编码
- **caller_id** - 调用者 ID
- **data_coverage** - 数据覆盖周期（如 "202401-202412"）
- **creation_slug** - 报告类型 slug
- **creation_name** - 报告类型名称

#### 示例

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

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

---

## 异常

### ParameterValidationError

参数验证错误。

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

try:
    args = await sdk.build_args(...)
except ParameterValidationError as e:
    print(f"参数验证失败: {e}")
```

---

## 下一步

- 💡 [最佳实践](best_practices.md) - 开发建议和常见问题
- 📖 [基本用法](basic_usage.md) - 学习如何使用这些 API
