Metadata-Version: 2.2
Name: paddlehelix-sdk
Version: 2.0.0
Summary: PaddleHelix SDK
Author-email: Paddlehelix Team <bcp@baidu.com>
Project-URL: Homepage, https://gitee.com/paddlehelix/paddlehelix
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: Apache Software License
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests~=2.32.3
Requires-Dist: pyyaml~=6.0.2
Requires-Dist: pandas
Requires-Dist: termcolor
Requires-Dist: six
Requires-Dist: python-dateutil
Requires-Dist: urllib3
Requires-Dist: certifi
Requires-Dist: tabulate

# PaddleHelix 平台 SDK

![PyPI - Version](https://img.shields.io/pypi/v/paddlehelix-sdk)


Paddlehelix Python SDK 是 [PaddleHelix 网站](https://paddlehelix.baidu.com/) 提供的整套服务的一部分，用于简化用户批量使用 PaddleHelix 平台服务的复杂性，方便用户将 PaddleHelix 服务集成到自己的项目中。

Paddlehelix Python SDK 已升级到 2.0 版本，修复大量已知问题，欢迎大家体验！

## 0. 安装前必备

请先自行安装好 python，版本大于等于 3.7.0，可以从 [python 官网](https://www.python.org/) 下载安装包，或使用 conda：

```shell
   conda create -n phsdk python=3.13
   conda activate phsdk
```

## 1. 安装 Paddlehelix SDK
    
目前 Paddlehelix Python SDK 已发布到 PyPI，可使用 pip 命令进行安装。

```shell
   pip3 install paddlehelix-sdk
```


## 2. 设置API鉴权AK、SK
1. 开通 CHPC 服务（若已开通则跳过此步）：[前往开通](https://console.bce.baidu.com/chpc/#/landing)。  
2. 获取鉴权所需的密钥 AK 和 SK。具体步骤请参考：[如何获取 AK、SK](https://cloud.baidu.com/doc/Reference/s/9jwvz2egb)。  
3. 调用 SDK 设置 AK、SK。注意请用你的 AK、SK 替换下面命令的 <your_ak>、<your_sk> 两个字段：  
    ```bash
    python3 -m paddlehelix.cli.client --ak <your_ak> --sk <your_sk>
    ```
**注意：首次设置 AK、SK 后，下次使用相同的账号提交无需重复设置**，SDK 会将其保存在用户的配置文件中。若需更换 AK、SK，可重复此步，新配置将覆盖原有信息。

## 3. 快速使用 HelixFold3 顶层接口

SDK 为用户提供了一个便捷的顶层接口，来完成询价、提交、查询任务状态、结果下载的全部流程。

1. 将下面的 python 代码片段保存为一个文件 `example.py`。

> `input_data` 参数指定了 HelixFold3 的输入（具体格式请参考：[HelixFold3 输入数据格式](https://paddlehelix.baidu.com/app/tut/guide/all/helixfold3json)），`output_dir` 指定了本次提交的输出路径。

```python
from paddlehelix.task import helixfold3

input_data = [
    {
        "job_name": "7xwo_chain_F_22",
        "entities": [
            {
                "type": "protein",
                "sequence": "HKTDSFVGLMA",
                "count": 2
            }
        ]
    }
]
helixfold3.execute(input_data=input_data, output_dir="output")
```

2. 用下面的命令启动提交流程。**注意：本次提交将消耗约 0.4 元，若您的百度云余额不足，SDK 将提示余额不足并退出。**

```bash
python3 example.py
```

3. 任务将耗时几分钟，您将在终端中看到任务运行的全过程。当任务结束后，将显示本次提交的汇总信息，示例输出如下：

```text
[2025-03-07 15:53:59 polling_task](helixfold3.py 187): INFO Task #0, Task_id: 111714, Status: Success
[2025-03-07 15:54:00 polling_task](helixfold3.py 147): INFO Task #0 downloaded.
[2025-03-07 15:54:01 main](helixfold3.py 330): INFO Finished!
[2025-03-07 15:54:01 main](helixfold3.py 336): INFO Task completed! Successful tasks: 1, Failed tasks: 0, Cancelled tasks: 0
[2025-03-07 15:54:01 main](helixfold3.py 351): INFO 
+-----------+---------------------+---------+----------------------------------------------------------------------------------+
|   task_id | status              |   price | storage_path                                                                     |
+===========+=====================+=========+==================================================================================+
|    111714 | DONE and DOWNLOADED |    0.41 | output/7/result/helixfold3_result_to_download_7xwo_chain_F_22_20250307155008.zip |
+-----------+---------------------+---------+----------------------------------------------------------------------------------+
```

4. 获取任务结果。可以直接通过第3步打印出的表格中的 `storage_path` 字段得知各个任务结果的路径，完整表格记录在：`{output_dir}/table.csv`。每个任务的结果都是一个 zip 压缩包，压缩包中的内容可参考: [压缩包内容说明](https://paddlehelix.baidu.com/app/tut/guide/all/helixfold3) 中的`数据下载`部分。

## 4. HelixFold3 顶层接口参数说明

- `input_data`：任务的输入数据通过 `input_data` 指定，支持 JSON 文件、包含多个 JSON 文件的文件夹、python dict 对象或 python dict 对象列表。具体格式请参考：[HelixFold3 输入数据格式](https://paddlehelix.baidu.com/app/tut/guide/all/helixfold3json)。单次提交的任务数上限为 1000 个。

- `output_dir`：指定结果存储目录，SDK 将在此目录中管理本次提交的所有任务信息。**若任务因意外中断，可以指定同一目录再次提交，SDK 将自动读取状态文件并从上次任务中断处继续执行。** 注意：若想从头开始新的提交，请提供一个新的未使用过的目录。

- `quiet`（可选，默认为 `False`）：指定是否静默提交任务。若设为 `True`，任务将直接提交，无需用户确认；如果设为 `False`，SDK 会在提交前询问。
