# RoboDock SDK

Python SDK for RoboDock Platform - 提供数据管理、模型训练任务管理等功能。

## 特性

- 🚀 简洁的API设计
- 📦 S3数据上传下载
- 🔄 训练任务状态管理
- 📊 数据集管理
- 🔐 安全的文件解压（防zip-slip攻击）

## 安装

### 使用pip安装

```bash
pip install robodock-sdk
```

### 从源码安装

```bash
git clone https://github.com/FII-AILab/robodock-sdk.git
cd robodock-sdk
pip install -e .
```

## 快速开始

### 基础用法

```python
from robodock_sdk import RoboDockClient

# 创建客户端（使用默认配置）
client = RoboDockClient()

# 或者自定义配置
client = RoboDockClient(
    s3_endpoint="http://192.168.1.6:9000",
    s3_access_key="robodock",
    s3_secret_key="robodock",
    api_url="http://192.168.1.2:31080"
)

# 获取数据集信息
dataset_info = client.get_dataset("dataset-uuid")

# 下载数据集
local_path = client.download_dataset(
    data_name="data.zip",
    uuid="data-uuid",
    dirname="singledata"
)

# 更新任务状态
client.update_run_status(
    unique_name="project-run",
    status="processing",
    start_time=1234567890000
)

# 上传模型（同步）
s3_key = client.upload_model(
    outdir_path="/path/to/model",
    upload_path="models/project/run"
)

# 上传模型（异步）
s3_key = client.upload_model_async(
    outdir_path="/path/to/model",
    upload_path="models/project/run"
)
```

### 使用底层Actions API

```python
from robodock_sdk import RoboDockActions

actions = RoboDockActions(
    s3_endpoint="http://192.168.1.6:9000",
    api_url="http://192.168.1.2:31080"
)

# 获取运行信息
run_info = actions.get_run_info("run-uuid")

# 下载检查点
checkpoint_path = actions.download_checkpoint(
    online_path="checkpoints/model.tar",
    local_path="/local/path"
)
```

## 环境变量配置

SDK支持通过环境变量进行配置：

```bash
export PROJECT_NAME=my_project
export RUN_NAME=run_001
export DATASET_UUID=dataset-uuid-here
export OUTPUT_DIR=/workspace/checkpoints
export RESUME=true
export RESUME_FROM=previous-run-uuid
```

### SDK 连接配置（优先级）

`RoboDockClient` / `RoboDockActions` 的配置优先级为：

1. 传入的参数
2. 环境变量
3. 内置默认值

支持的环境变量：

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `S3_ENDPOINT_URL` | S3 服务端点 | http://192.168.1.6:9000 |
| `AWS_ACCESS_KEY_ID` | S3 访问密钥 | robodock |
| `AWS_SECRET_ACCESS_KEY` | S3 密钥 | robodock |
| `S3_BUCKET_NAME` | S3 桶名称 | robodock |
| `S3_REGION_NAME` | S3 区域 | us-east-1 |
| `ROBOCK_SERVER_URL` | RoboDock API URL | http://192.168.1.2:31080 |

完整的环境变量列表：

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `PROJECT_NAME` | 项目名称 | default_project |
| `RUN_NAME` | 运行名称 | default_run |
| `DATASET_UUID` | 数据集UUID | - |
| `OUTPUT_DIR` | 输出目录 | /workspace/checkpoints |
| `RESUME` | 是否恢复训练 | false |
| `RESUME_FROM` | 恢复的运行UUID | - |
| `SAVE_INTERVAL` | 保存间隔 | 5000 |
| `BATCH_SIZE` | 批次大小 | 32 |
| `NUM_TRAIN_STEPS` | 训练步数 | 20000 |
| `LOG_INTERVAL` | 日志间隔 | 10 |

## API文档

### RoboDockClient

高层客户端接口，提供便捷的API调用。

#### 方法

- `get_dataset(uuid)` - 获取数据集信息
- `get_data(uuid)` - 获取单条数据信息
- `get_run(unique_name, unique_type)` - 获取运行信息
- `download_dataset(data_name, uuid, dirname)` - 下载数据集
- `download_checkpoint(online_path, local_path)` - 下载检查点
- `upload_model(outdir_path, upload_path)` - 上传模型
- `upload_model_async(outdir_path, upload_path)` - 异步上传模型
- `update_run_status(unique_name, status, **kwargs)` - 更新运行状态

### RoboDockActions

底层操作接口，提供更细粒度的控制。

#### 方法

- `get_dataset_info(uuid)` - 获取数据集信息
- `get_singledata_info(uuid)` - 获取单条数据信息
- `get_run_info(unique_name, unique_type)` - 获取运行信息
- `download_data(data_name, uuid, dirname)` - 下载并解压数据
- `download_checkpoint(online_path, local_path)` - 下载并解压检查点
- `upload_data(outdir_path, upload_path)` - 压缩并上传数据
- `upload_data_async(outdir_path, upload_path)` - 异步压缩并上传数据
- `update_singledata(uuid, checker_result, checker_info)` - 更新数据检查结果
- `update_run(unique_name, body, unique_type)` - 更新运行状态

## 开发

### 安装开发依赖

```bash
pip install -e ".[dev]"
```

### 运行测试

```bash
pytest tests/
```

### 代码格式化

```bash
black robodock_sdk/
```

### 类型检查

```bash
mypy robodock_sdk/
```

## 示例

查看 `examples/` 目录获取更多使用示例：

- `examples/basic_usage.py` - 基础用法示例
- `examples/training_workflow.py` - 完整训练流程示例

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request！
