Metadata-Version: 2.4
Name: synaster-client
Version: 0.12.2
Summary: SynAster 官方 Python SDK 与命令行客户端
Project-URL: Homepage, https://syn-aster.bohrium.com
Project-URL: Documentation, https://syn-aster.bohrium.com
Project-URL: Repository, https://github.com/macroversus/SynAsterHub
Project-URL: Issues, https://github.com/macroversus/SynAsterHub/issues
Author: SynAster Team
Keywords: ai-for-science,bioinformatics,bohrium,cli,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Requires-Dist: httpx>=0.28
Description-Content-Type: text/markdown

# synaster-client 中文使用说明

这是 SynAster 官方轻量 Python SDK 与 `synaster` 命令行客户端，面向终端用户、
Python 程序和 AI Agent。客户端复用现有 Bohrium OpenAPI，不会安装或运行
FastAPI、Celery、Redis、Nextflow 或科学计算工具容器。

要求 Python 3.10 或更高版本。

## 安装

```bash
pipx install synaster-client
synaster --version

# 临时执行，不写入当前 Python 环境
uvx --from synaster-client synaster --version
```

命令行入口与模块入口完全等价：

```bash
synaster skills --json
python -m synaster_client skills --json
```

## 安全认证与运行

AccessKey 只能通过 `SYNASTER_ACCESS_KEY` 环境变量，或配合
`--access-key-stdin` 从标准输入读取一行。客户端故意不提供
`--access-key VALUE`，并拒绝配置文件中的密钥字段。

```bash
export SYNASTER_ACCESS_KEY="<你的 Bohrium AccessKey>"

synaster doctor
synaster describe adabmdca
synaster run adabmdca \
  --input family_msa.fasta \
  --file query=query.fasta
```

使用 `submit` 只发送一次提交请求，随后可用返回的任务 ID 恢复：

```bash
synaster submit tmpred --input proteins.fasta
synaster wait <task-id>
synaster download <task-id>
```

使用 `--mode bohr` 时，CLI 会刷新实时机型价格，并要求对本次命令明确确认费用。
所有任务提交请求都不会自动重试。

完整的命令、JSON、退出码、恢复、下载和 Python SDK 说明见仓库内
[`docs/synaster-cli-sop.md`](https://github.com/macroversus/SynAsterHub/blob/main/docs/synaster-cli-sop.md)。

## Python SDK

Python 类名、方法名和结构化字段保持英文，以保证程序兼容；公开说明、异常消息和
CLI 人类可读输出使用简体中文。

### 提交 hosted 任务并等待结果

```python
import os

from synaster_client import SynAsterClient


with SynAsterClient(access_key=os.environ["SYNASTER_ACCESS_KEY"]) as client:
    request = client.build_request(
        "tmpred",
        input_path="proteins.fasta",
        execution_mode="hosted",
    )
    result = client.run(request, output_dir="synaster-results/tmpred")

print(result.status.status)
print(result.result_files)
```

`run()` 严格执行“提交一次 → 等待 → 下载”。如果进程中断，请保留任务 ID，使用
`get_status()` 或 `wait()` 恢复；不要重新提交可能已经创建的任务。

### 捕获类型化异常

```python
from synaster_client import (
    SynAsterError,
    SynAsterRemoteTaskError,
    SynAsterWaitError,
)

try:
    result = client.run(request)
except SynAsterWaitError as exc:
    print(f"本地等待未完成，可继续查询任务：{exc.task_id}")
except SynAsterRemoteTaskError as exc:
    print(f"远端任务失败：{exc.message}")
except SynAsterError as exc:
    print(f"SynAster 调用失败：{exc.message}")
```

## Bohrium 费用安全

bohr 高层 `run()` 必须传入与实时 `bohr-options` 一致的
`BohrChargeConfirmation`。SDK 不会替调用方取得费用授权；提交响应超时或断连时，
异常可能带有 `submission_uncertain=True`，此时先到 Bohrium 控制台排查，禁止自动重提。

## 稳定接口说明

- 命令名、Python 类名/方法名、JSON 字段和 `error.kind` 保持英文，便于脚本稳定解析。
- CLI 默认人类输出、帮助、交互提示和 SDK 本地异常消息使用简体中文。
- `--json` 的 stdout 始终只输出一个 JSON 对象，进度与费用提示写入 stderr。
- 默认生产地址为 `https://open.bohrium.com/openapi/v1/syn-aster`。
