Python SDK 参考

公开入口 from envloop import Client。方法同步返回字典，关键字参数按下表使用；服务端仍负责验证与执行。安装与运行见 Python SDK guide。

Client

方法	行为
`Client.remote(api_url=None, *, timeout=30, api_key=None, workspace_id=None)`	创建 HTTP 客户端；省略配置读取系统环境，不读取 `.env.local`
`Client.local(*, work_dir=None, repository_root=None, repository_commit=None)`	创建并管理进程内 LocalServer；需可选 EnvPlatform
`Client(server)`	使用调用方管理的服务；server 必填
`Client.init_repository(root)`	初始化本地 registry，不改 Git；返回 None
`client.close()`	本地等待自己持有的服务关闭；远程不停止平台任务

支持 context manager。remote 的 timeout 是单次 HTTP 请求期限；tasks/jobs 的 wait timeout 是客户端总等待期限。repository 省略 commit 时固定本地 main。

Tasks

client.tasks.submit(
    source=None,
    *,
    request_id=None,
    runner=None,
    dataset=None,
    task_id=None,
    namespace=None,
    config=None,
    split=None,
    revision=None,
    profile_id=None,
    job_id=None,
    tag=None,
    queue_id="default",
    priority=0,
    profile=None,
    task_ref=None,
    profile_name=None,
    profile_version=None,
    profile_sha256=None,
    profile_overrides=None,
    seed=None,
    execution=None,
    command=None,
)

参数	行为
`source`	两文件目录 str / Path，或文件内容 Mapping
`runner` / `dataset`	命名 runner 与 Dataset 名称或 selector Mapping；同 source / task_ref 互斥
`task_id`	Dataset 内的单 Task；也可放在 dataset selector 中
`namespace` / `config` / `split` / `revision`	Dataset 选择；冲突的 selector 字段会报 ValueError
`profile_id`	APIServer 的不可变 Profile ID
`job_id` / `tag`	可选 Job 归属与运行标签
`queue_id` / `priority`	默认 default / 0；较大的 priority 先派发等待中的任务
`request_id`	非空字符串；省略生成 UUID；重试复用首次执行
`profile`	内联参数 Mapping，由 Task 解释
`task_ref`	平台固定任务引用 Mapping，需由配套 repository / Dataset API 提供；不是裸 task_name 或 URL
`profile_name` / `profile_version`	服务端命名 Profile，省略版本需显式默认
`profile_sha256`	预期规范化 ProfileSpec 哈希
`profile_overrides`	参数覆盖 Mapping
`seed`	seed 覆盖
`execution`	执行覆盖 Mapping，例如 `{"timeout_sec": 60}`
`command`	可选非空 UTF-8 shell 脚本，最多 65536 字节、无 NUL；原文在 Runner 工作目录执行

普通用户优先用 source；固定 task_ref 需对应平台快照。不要同时传任务内容和固定引用；内联与命名 Profile 的组合由平台校验，不用其混搭猜测优先级。submit 返回含 trial_id 的状态字典。

命名 runner 提交通过 HTTP /v1/trials，Dataset selector 示例为 {"name": "org/benchmark", "version": "1", "task_id": "org/task"}；字符串 org/benchmark@1 也可配合 task_id。APIServer 负责权限、catalog 解析、冻结和执行；SDK 不读取任务目录。旧两文件提交继续使用 /v1/tasks。未提供 catalog 的 LocalServer / JobMaster 会拒绝未解析的命名 runner 请求。

方法	返回 / 行为
`tasks.status(trial_id)`	状态详情，包括终态、退出码或错误字段
`tasks.wait(trial_id, *, timeout=30, poll_interval=0.05)`	返回最终状态，终态 succeeded / failed / cancelled
`tasks.result(trial_id)`	stdout、stderr、outputs，不自动等待
`tasks.snapshot(trial_id)`	冻结输入快照
`tasks.stop(trial_id)`	停止请求响应；能力取决于执行后端

wait 要求有限且非负 timeout、有限且为正 poll_interval。超时抛 TimeoutError，不取消运行；执行失败返回 failed 状态。目录读取和平台校验错误独立传播。

Jobs

client.jobs.submit(
    dataset,
    *,
    request_id=None,
    attempts=1,
    namespace=None,
    config=None,
    split=None,
    revision=None,
    runner=None,
    profile_id=None,
    job_id=None,
    tag=None,
    queue_id="default",
    priority=0,
    command=None,
    **options,
)

dataset 为名称、name@version 或固定 dataset_ref Mapping。带 runner 时，也接受不含 kind 的 Dataset selector Mapping。选择项不能与固定 dataset_ref 混用。runner 为 name 或 name@version；profile_id、job_id、tag 可选，queue_id 默认 default，priority 默认 0，数值越大先派发等待中的任务。options 传平台提交字段，例如 profile_name、profile_version、seed、execution；不代表任意字段都受平台支持。submit 返回含 job_id 的字典。所有选择通过 /v1/jobs 交给平台解析，客户端不冻结 catalog。

command 覆盖所有成员的 Runner 默认脚本，校验规则与 Task 一致。缺省使用 Runner 的 execution.command，未声明时按入口使用 bash main.sh 或 python main.py。源码目录默认包含 runner.toml；旧 task.toml 兼容，两种配置同时存在会被拒绝。

方法	返回 / 行为
`jobs.status(job_id)`	状态详情
`jobs.wait(job_id, *, timeout=600, poll_interval=0.1)`	返回最终状态，completed / failed / cancelled
`jobs.result(job_id)`	作业聚合结果；wait 不代替此方法
`jobs.list(**kwargs)`	分页结果；常用 limit、cursor，HTTP 默认 limit 25
`jobs.stop(job_id)`	取消请求响应

Job wait 使用与 Task wait 相同的数值限制，超时不自动取消。

Profiles

这些方法对应本地 Profile 管理契约，HTTP 管理未实现。

方法	行为
`profiles.init(root)`	初始化 repository registry
`profiles.put(spec)` / `profiles.create(spec)`	保存完整 ProfileSpec Mapping
`profiles.get(name, version=None)`	获取版本 / 默认
`profiles.list(**kwargs)`	name、include_archived、limit（默认 50）、cursor
`profiles.resolve(name, version=None, expected_sha256=None)`	解析并校验版本
`profiles.set_default(name, version, *, expected_version)`	更新默认；首次设置传 expected_version=None
`profiles.archive(name, version)`	归档
`profiles.export(name, version)`	导出 bytes
`profiles.import_spec(raw, *, name=None, version=None)`	导入 JSON bytes，可核对名称和版本

操作示例见 Profiles guide。

Errors and result interpretation

SDK wait 不把 failed 终态转成异常。超时抛 TimeoutError；客户端输入可能抛 ValueError、文件系统或 TOML 错误。本地平台 TaskError 可提供 status_code；远程错误使用脱敏 code。不要依赖私有客户端成员或任意错误正文。

状态成功、命令成功与 verifier reward=1 是不同结论，评分以实际 result 为准。当前没有 client.train 或异步 Client 工厂。

Client​

Tasks​

Jobs​

Profiles​

Errors and result interpretation​

Client

Tasks

Jobs

Profiles

Errors and result interpretation