Metadata-Version: 2.4
Name: synaster-client
Version: 0.18.0
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
Requires-Dist: jwcrypto<2,>=1.5.6
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
```

上述 PyPI 安装支持手工 AK。官网可在版本号不变时发布包含新能力的固定提交构建，
因此同一个版本号不保证已有 PyPI 包支持 `auth`。自动授权请按
[官方 Skill 的客户端校验步骤](https://syn-aster.bohrium.com/skills/synaster.md)
读取 `/release.json` 和 `/clients/current.json`，核对 release、完整 Git SHA、
官方同源 wheel URL 和 SHA-256；下载后实际计算文件摘要，使用
`uvx --from '<已校验本地wheel>' synaster auth --help` 验证后，所有自动授权与任务命令
继续使用该固定构建并在每次调用前复验缓存。不能假定 uvx 会校验 URL 的 `#sha256=`，
不得把未校验的 URL 直接交给包安装器，
也不要通过 `pipx upgrade` 猜测是否获得同版本新能力。此过程只安装客户端，不读取 AK。

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

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

## 安全认证与运行

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

部署已启用玻尔配对入口后，支持同 UID 校验的 Unix 环境中，Agent 也可使用显式
的内存会话（本次自动化测试覆盖 Linux）。
`auth connect` 只创建链接，用户在自己的已登录玻尔主站的浏览器打开链接；
`auth status` 显示已验证账号。Agent 必须先在聊天说明账号、用途、调用端和时限，
获得明确许可后才能执行 `auth authorize`。主页没有登录门槛或授权按钮。

```bash
synaster auth connect --client-name "My Agent" --json
synaster auth status --auth-session <session-id> --json
# 用户明确许可后，填写 status 返回的实际 user_id 和 org_id：
synaster auth authorize --auth-session <session-id> \
  --user-id <user-id> --org-id <org-id> --approve-read-access-key --json
synaster auth status --auth-session <session-id> --json
# 多个 AK 时，由用户选择 available_keys 中的 id：
synaster auth select --auth-session <session-id> --key-id <key-id> --json
synaster doctor --auth-session <session-id>
synaster auth logout --auth-session <session-id>
```

用户拒绝则执行 `auth cancel --auth-session <session-id> --reason user_denied`。
配对链接有效 5 分钟；浏览器需在完成领取前保持在线。`auth status` 会在已授权、
凭据准备完成时私密领取，绝不输出 AK。会话 ID 不是密钥，可供后续 CLI 进程或
`SynAsterClient(auth_session="<session-id>")` 使用，不能与手工 AK 同用。

原始 AK 仅保留于当前账号的内存 broker 和请求内存，最长 60 分钟且受交接时的
主站 token 到期时间约束；不写配置文件。自动模式只调用正式 SynAster 网关，
拒绝自定义地址、下载外链和重定向。退出、到期或重启后需重新授权，保留原
`task_id` 继续查询。此期限和用途策略不会缩减或撤销玻尔原始 AK 的上游权限。
服务器记录的是 Agent 的聊天许可声明，不能独立证明人类同意；只对遵守 skill
的受信 Agent 使用此流程。不支持受限 Unix IPC 的平台继续使用 env/stdin。

```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)
print(result.status.warnings)  # 非空时先检查下载目录中的完整性报告
```

`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`。
