From 91c5d3fcdf6e10dd70e503fa7877b01415fe22c9 Mon Sep 17 00:00:00 2001 From: "ark-hand[bot]" <315378070+ark-hand[bot]@users.noreply.github.com> Date: Wed, 9 Sep 2026 12:11:45 +0800 Subject: [PATCH] chore: sync from ark-apis d20f0d68da Auto-generated SDK sync from ark-apis at d20f0d68da2100d87a660921aedc9b72d75c6a34. Generated files are overwritten by the sync pipeline and should not be edited by hand. Sync-Source-Commit: 49c3974c74c71949bddedab29bcd594c319301e6 Ark-APIs-Commit: d20f0d68da2100d87a660921aedc9b72d75c6a34 Release-Version: 0.6.0 --- VERSION | 2 +- pyproject.toml | 2 +- src/arkruntime/resources/images/images.py | 15 ++-- src/arkruntime/types/images/__init__.py | 2 + src/arkruntime/types/images/background.py | 18 +++++ .../images/create_image_generation_request.py | 15 ++-- .../create_image_generation_request_param.py | 14 ++-- src/arkruntime/types/session/__init__.py | 8 ++ .../types/session/agent_with_upgrades.py | 73 +++++++++++++++++++ .../session/create_session_upgrade_request.py | 53 ++++++++++++++ .../session/environment_with_upgrades.py | 43 +++++++++++ .../types/session/model_overrides.py | 12 +++ .../types/session/model_upgrades.py | 52 +++++++++++++ .../types/session/session_status.py | 3 + uv.lock | 2 +- 15 files changed, 296 insertions(+), 18 deletions(-) create mode 100644 src/arkruntime/types/images/background.py create mode 100644 src/arkruntime/types/session/agent_with_upgrades.py create mode 100644 src/arkruntime/types/session/create_session_upgrade_request.py create mode 100644 src/arkruntime/types/session/environment_with_upgrades.py create mode 100644 src/arkruntime/types/session/model_upgrades.py diff --git a/VERSION b/VERSION index 8f0916f..a918a2a 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.5.0 +0.6.0 diff --git a/pyproject.toml b/pyproject.toml index 6d81038..241ce58 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "arkruntime" -version = "0.5.0" +version = "0.6.0" description = "Ark runtime SDK for Python" readme = "README.md" requires-python = ">=3.8" diff --git a/src/arkruntime/resources/images/images.py b/src/arkruntime/resources/images/images.py index a88d742..91379cf 100644 --- a/src/arkruntime/resources/images/images.py +++ b/src/arkruntime/resources/images/images.py @@ -4,7 +4,7 @@ from __future__ import annotations -from typing import List, Optional +from typing import List, Optional, Union import httpx @@ -14,6 +14,7 @@ from ..._types import Body, Headers, Query # AUTOGEN-START create-imports +from ...types.images.background import Background from ...types.images.image_generation_response import ImageGenerationResponse from ...types.images.image_generation_stream_event import ImageGenerationStreamEvent from ...types.images.optimize_prompt_options_param import OptimizePromptOptionsParam @@ -36,8 +37,8 @@ def generate( *, # AUTOGEN-START create-kwargs model: str, - prompt: str, - image: Optional[List[str]] = None, + prompt: Optional[str] = None, + image: Optional[Union[str, List[str]]] = None, stream: Optional[bool] = None, response_format: Optional[ResponseFormat] = None, seed: Optional[int] = None, @@ -50,6 +51,7 @@ def generate( optimize_prompt_options: Optional[OptimizePromptOptionsParam] = None, tools: Optional[List[ToolParam]] = None, output_format: Optional[OutputFormat] = None, + background: Optional[Background] = None, layer_decomposition: Optional[bool] = None, # AUTOGEN-END create-kwargs extra_headers: Headers | None = None, @@ -76,6 +78,7 @@ def generate( "optimize_prompt_options": optimize_prompt_options, "tools": tools, "output_format": output_format, + "background": background, "layer_decomposition": layer_decomposition, # AUTOGEN-END create-body }, @@ -97,8 +100,8 @@ async def generate( *, # AUTOGEN-START create-kwargs model: str, - prompt: str, - image: Optional[List[str]] = None, + prompt: Optional[str] = None, + image: Optional[Union[str, List[str]]] = None, stream: Optional[bool] = None, response_format: Optional[ResponseFormat] = None, seed: Optional[int] = None, @@ -111,6 +114,7 @@ async def generate( optimize_prompt_options: Optional[OptimizePromptOptionsParam] = None, tools: Optional[List[ToolParam]] = None, output_format: Optional[OutputFormat] = None, + background: Optional[Background] = None, layer_decomposition: Optional[bool] = None, # AUTOGEN-END create-kwargs extra_headers: Headers | None = None, @@ -137,6 +141,7 @@ async def generate( "optimize_prompt_options": optimize_prompt_options, "tools": tools, "output_format": output_format, + "background": background, "layer_decomposition": layer_decomposition, # AUTOGEN-END create-body }, diff --git a/src/arkruntime/types/images/__init__.py b/src/arkruntime/types/images/__init__.py index d9086ff..dc9eb8a 100644 --- a/src/arkruntime/types/images/__init__.py +++ b/src/arkruntime/types/images/__init__.py @@ -6,6 +6,7 @@ from __future__ import annotations +from .background import Background from .bounding_box import BoundingBox from .create_image_generation_request import CreateImageGenerationRequest from .image_data_item import ImageDataItem @@ -25,6 +26,7 @@ from .usage import Usage __all__ = [ + "Background", "BoundingBox", "CreateImageGenerationRequest", "ImageDataItem", diff --git a/src/arkruntime/types/images/background.py b/src/arkruntime/types/images/background.py new file mode 100644 index 0000000..f7edab6 --- /dev/null +++ b/src/arkruntime/types/images/background.py @@ -0,0 +1,18 @@ +# Generated by datamodel-code-generator from ark-apis typespec/openapi. +# DO NOT EDIT — regenerate with `make gen-py-` in ark-apis. +# +# Copyright (c) 2026 ByteDance Ltd. and/or its affiliates. +# SPDX-License-Identifier: Apache-2.0 + +from __future__ import annotations + +from enum import Enum + + +class Background(str, Enum): + """ + Background of the generated image. + """ + + opaque = "opaque" + transparent = "transparent" diff --git a/src/arkruntime/types/images/create_image_generation_request.py b/src/arkruntime/types/images/create_image_generation_request.py index 3bb80bf..5e310ad 100644 --- a/src/arkruntime/types/images/create_image_generation_request.py +++ b/src/arkruntime/types/images/create_image_generation_request.py @@ -6,10 +6,11 @@ from __future__ import annotations -from typing import List, Optional +from typing import List, Optional, Union from arkruntime._models import BaseModel +from .background import Background from .optimize_prompt_options import OptimizePromptOptions from .output_format import OutputFormat from .response_format import ResponseFormat @@ -23,13 +24,13 @@ class CreateImageGenerationRequest(BaseModel): """ The model identifier to use. """ - prompt: str + prompt: Optional[str] = None """ - Text prompt describing the desired image. + Text prompt describing the desired image. Required for standard generation; may be omitted for automatic layer decomposition when `layer_decomposition=true`. """ - image: Optional[List[str]] = None + image: Optional[Union[str, List[str]]] = None """ - Reference / edit images. Each entry is a URL or a `data:` URI. + Reference / edit images, as a single URL or `data:` URI, or an array of them. """ stream: Optional[bool] = None """ @@ -81,6 +82,10 @@ class CreateImageGenerationRequest(BaseModel): """ Container/codec for the generated image bytes. """ + background: Optional[Background] = None + """ + Output background. Defaults to `opaque`. `transparent` requires exactly one PNG reference image with an alpha channel and PNG output. + """ layer_decomposition: Optional[bool] = None """ Decompose one reference image into a base image and independently diff --git a/src/arkruntime/types/images/create_image_generation_request_param.py b/src/arkruntime/types/images/create_image_generation_request_param.py index 342c9ed..20932a9 100644 --- a/src/arkruntime/types/images/create_image_generation_request_param.py +++ b/src/arkruntime/types/images/create_image_generation_request_param.py @@ -6,10 +6,11 @@ from __future__ import annotations -from typing import List, Optional +from typing import List, Optional, Union from typing_extensions import Required, TypedDict +from .background import Background from .optimize_prompt_options_param import OptimizePromptOptionsParam from .output_format import OutputFormat from .response_format import ResponseFormat @@ -24,11 +25,11 @@ class CreateImageGenerationRequestParam(TypedDict, total=False): model: Required[str] """The model identifier to use.""" - prompt: Required[str] - """Text prompt describing the desired image.""" + prompt: Optional[str] + """Text prompt describing the desired image. Required for standard generation; may be omitted for automatic layer decomposition when `layer_decomposition=true`.""" - image: Optional[List[str]] - """Reference / edit images. Each entry is a URL or a `data:` URI.""" + image: Optional[Union[str, List[str]]] + """Reference / edit images, as a single URL or `data:` URI, or an array of them.""" stream: Optional[bool] """Stream partial images as they are generated (server-sent events).""" @@ -66,6 +67,9 @@ class CreateImageGenerationRequestParam(TypedDict, total=False): output_format: Optional[OutputFormat] """Container/codec for the generated image bytes.""" + background: Optional[Background] + """Output background. Defaults to `opaque`. `transparent` requires exactly one PNG reference image with an alpha channel and PNG output.""" + layer_decomposition: Optional[bool] """ Decompose one reference image into a base image and independently diff --git a/src/arkruntime/types/session/__init__.py b/src/arkruntime/types/session/__init__.py index 87f6f38..d46dfee 100644 --- a/src/arkruntime/types/session/__init__.py +++ b/src/arkruntime/types/session/__init__.py @@ -8,11 +8,13 @@ from .agent_identifier import AgentIdentifier from .agent_ref import AgentRef +from .agent_with_upgrades import AgentWithUpgrades from .base64_document_source import Base64DocumentSource from .base64_image_source import Base64ImageSource from .cache_creation import CacheCreation from .create_session_request import CreateSessionRequest from .create_session_resource_request import CreateSessionResourceRequest +from .create_session_upgrade_request import CreateSessionUpgradeRequest from .delete_session_response import DeleteSessionResponse from .document_source import DocumentSource from .environment_config_override import EnvironmentConfigOverride @@ -20,6 +22,7 @@ from .environment_packages_config import EnvironmentPackagesConfig from .environment_tos_config import EnvironmentTosConfig from .environment_with_overrides import EnvironmentWithOverrides +from .environment_with_upgrades import EnvironmentWithUpgrades from .file_document_source import FileDocumentSource from .file_image_source import FileImageSource from .image_source import ImageSource @@ -72,6 +75,7 @@ ManagedAgentsUserToolResultEventParams, ) from .model_overrides import ModelOverrides +from .model_upgrades import ModelUpgrades from .plain_text_document_source import PlainTextDocumentSource from .search_result_citations import SearchResultCitations from .search_result_content import SearchResultContent @@ -94,11 +98,13 @@ __all__ = [ "AgentIdentifier", "AgentRef", + "AgentWithUpgrades", "Base64DocumentSource", "Base64ImageSource", "CacheCreation", "CreateSessionRequest", "CreateSessionResourceRequest", + "CreateSessionUpgradeRequest", "DeleteSessionResponse", "DocumentSource", "EnvironmentConfigOverride", @@ -106,6 +112,7 @@ "EnvironmentPackagesConfig", "EnvironmentTosConfig", "EnvironmentWithOverrides", + "EnvironmentWithUpgrades", "FileDocumentSource", "FileImageSource", "ImageSource", @@ -142,6 +149,7 @@ "ManagedAgentsUserToolConfirmationEventParams", "ManagedAgentsUserToolResultEventParams", "ModelOverrides", + "ModelUpgrades", "PlainTextDocumentSource", "SearchResultCitations", "SearchResultContent", diff --git a/src/arkruntime/types/session/agent_with_upgrades.py b/src/arkruntime/types/session/agent_with_upgrades.py new file mode 100644 index 0000000..3408d95 --- /dev/null +++ b/src/arkruntime/types/session/agent_with_upgrades.py @@ -0,0 +1,73 @@ +# Generated by datamodel-code-generator from ark-apis typespec/openapi. +# DO NOT EDIT — regenerate with `make gen-py-` in ark-apis. +# +# Copyright (c) 2026 ByteDance Ltd. and/or its affiliates. +# SPDX-License-Identifier: Apache-2.0 + +from __future__ import annotations + +from typing import Dict, List, Literal, Optional + +from arkruntime._models import BaseModel + +from .model_upgrades import ModelUpgrades + + +class AgentWithUpgrades(BaseModel): + """ + Session upgrade 的目标 Agent 运行配置。 + + `id` 必须等于当前 Session 的 Agent ID —— upgrade 不支持换绑到另一个 + Agent，不一致返回 403 `AgentMismatch`。 + + 数组字段（`tools` / `mcp_servers` / `skills`）是**整组替换**语义：省略 + 表示保留原值，显式传 `[]` 表示清空。两者在 wire 上必须可区分，SDK 不能 + 把空数组优化成省略字段。 + """ + + type: Literal["agent_with_upgrades"] + """ + 固定 `"agent_with_upgrades"`。 + """ + id: str + """ + Agent ID；必须与当前 Session 的 Agent ID 一致。 + """ + version: Optional[int] = None + """ + 目标 Agent 版本号。 + + 省略或传 `0` 表示**不锁版本、沿用 Session 当前的 Agent 快照**（注意与创建 + 期不同：这里不是"走最新版"）。传正整数则以该版本的 payload 为基线物化 + ——`system` / `tools` / `mcp_servers` / `skills` / `multiagent` / `model` + 整组跟着版本走，本次请求里的同名字段再叠加其上；版本不存在返回 404。 + 传负数返回 400。 + """ + model: Optional[ModelUpgrades] = None + """ + 模型运行参数升级。 + """ + system: Optional[str] = None + """ + System prompt。 + """ + tools: Optional[List[Dict[str, object]]] = None + """ + 工具配置（整组替换）。 + """ + mcp_servers: Optional[List[Dict[str, object]]] = None + """ + MCP server 配置（整组替换）。 + """ + skills: Optional[List[Dict[str, object]]] = None + """ + Skill 配置（整组替换）。 + """ + multiagent: Optional[Dict[str, object]] = None + """ + 多 Agent 配置。 + """ + display_name: Optional[str] = None + """ + Agent 展示名。 + """ diff --git a/src/arkruntime/types/session/create_session_upgrade_request.py b/src/arkruntime/types/session/create_session_upgrade_request.py new file mode 100644 index 0000000..450c2af --- /dev/null +++ b/src/arkruntime/types/session/create_session_upgrade_request.py @@ -0,0 +1,53 @@ +# Generated by datamodel-code-generator from ark-apis typespec/openapi. +# DO NOT EDIT — regenerate with `make gen-py-` in ark-apis. +# +# Copyright (c) 2026 ByteDance Ltd. and/or its affiliates. +# SPDX-License-Identifier: Apache-2.0 + +from __future__ import annotations + +from typing import List, Optional + +from arkruntime._models import BaseModel + +from .agent_with_upgrades import AgentWithUpgrades +from .environment_with_upgrades import EnvironmentWithUpgrades +from .managed_agents_event_params import ManagedAgentsEventParams + + +class CreateSessionUpgradeRequest(BaseModel): + """ + 发起一次已有 Session 的运行配置升级。 + + `agent` / `environment` / `vault_ids` 至少提供一个作为升级目标，全部省略 + 返回 400 `MissingUpgradeTarget`（只传 `initial_events` 不算升级目标）。 + Session 必须处于 `idle` 且上一轮 turn 以 `end_turn` 收尾，否则返回 403 + `SessionNotIdle` / `SessionNotEndTurn`；同一 Session 上一次升级尚未收敛时 + 返回 403 `UpgradeInProgress`。 + """ + + agent: Optional[AgentWithUpgrades] = None + """ + 目标 Agent 运行配置。 + """ + environment: Optional[EnvironmentWithUpgrades] = None + """ + 目标 Environment 运行配置。 + """ + vault_ids: Optional[List[str]] = None + """ + Session 绑定的 Vault 列表。 + + 只能用来**刷新已绑定 Vault 的内容**，不能改变绑定集合：传入集合必须与 + 当前 Session 的 `vault_ids` 相等（忽略顺序与重复），否则返回 403 + `VaultMismatch`。显式传 `[]` 表示声明空集，仅当当前 Session 本身没有 + Vault 绑定时通过 —— 因此省略与 `[]` 在 wire 上必须可区分，SDK 不能把 + 空数组优化成省略字段。 + """ + initial_events: Optional[List[ManagedAgentsEventParams]] = None + """ + 配置切换收敛后由服务端补投的事件。当前只接受**恰好一个** `user.message` + 事件，且 content 为单个 text block、内容是 `/compact` 命令 XML；不满足 + 返回 400 `InvalidInitialEvents` / `InvalidCompactCommand`。省略或传 `[]` + 表示本次不投递事件。 + """ diff --git a/src/arkruntime/types/session/environment_with_upgrades.py b/src/arkruntime/types/session/environment_with_upgrades.py new file mode 100644 index 0000000..dcf870a --- /dev/null +++ b/src/arkruntime/types/session/environment_with_upgrades.py @@ -0,0 +1,43 @@ +# Generated by datamodel-code-generator from ark-apis typespec/openapi. +# DO NOT EDIT — regenerate with `make gen-py-` in ark-apis. +# +# Copyright (c) 2026 ByteDance Ltd. and/or its affiliates. +# SPDX-License-Identifier: Apache-2.0 + +from __future__ import annotations + +from typing import Literal, Optional + +from arkruntime._models import BaseModel + +from .environment_config_override import EnvironmentConfigOverride + + +class EnvironmentWithUpgrades(BaseModel): + """ + Session upgrade 的目标 Environment 运行配置。 + + `id` 必须等于当前 Session 的 Environment ID —— upgrade 不支持换绑到另一个 + Environment，不一致返回 403 `EnvironmentMismatch`；`config.type` 也必须与 + 当前 Session 的环境类型一致（不支持 cloud ↔ self_hosted 互切），不一致 + 返回 403 `EnvironmentTypeMismatch`。 + + cloud 环境开放 `networking` / `packages` / `env` / `setup_script` 升级， + 在当前 Sandbox 上原地生效，不更换 Sandbox 实例。self_hosted 沙箱由用户 + 自建，除 `config.type` 外不接受任何运行时字段（这类 Session 仍可升级 + agent 并投递 `initial_events`）；`tos` 一律拒绝，返回 400 + `TosUpgradeNotSupported`。 + """ + + type: Literal["environment_with_upgrades"] + """ + 固定 `"environment_with_upgrades"`。 + """ + id: str + """ + Environment ID；必须与当前 Session 的 Environment ID 一致。 + """ + config: Optional[EnvironmentConfigOverride] = None + """ + 运行时配置升级。 + """ diff --git a/src/arkruntime/types/session/model_overrides.py b/src/arkruntime/types/session/model_overrides.py index 1b632d9..15916a0 100644 --- a/src/arkruntime/types/session/model_overrides.py +++ b/src/arkruntime/types/session/model_overrides.py @@ -14,8 +14,16 @@ class ModelOverrides(BaseModel): """ Session 创建时允许临时覆写的模型运行参数。 + + 内部字段省略表示继承 base Agent 的对应值。 """ + id: Optional[str] = None + """ + 模型 semantic 覆写，形如 `"doubao-seed-2-0-pro-260215"`；服务端按最右 + 侧一个 `-` 拆成 (name, version) 冻结进本 Session 的 Agent 快照，不回写 + base Agent。解析失败返回 400，模型未开通返回 403 `ModelNotOpen`。 + """ speed: Optional[str] = None """ 模型速度档位。 @@ -28,3 +36,7 @@ class ModelOverrides(BaseModel): """ 推理努力程度。 """ + service_tier: Optional[str] = None + """ + 服务档位。 + """ diff --git a/src/arkruntime/types/session/model_upgrades.py b/src/arkruntime/types/session/model_upgrades.py new file mode 100644 index 0000000..546890f --- /dev/null +++ b/src/arkruntime/types/session/model_upgrades.py @@ -0,0 +1,52 @@ +# Generated by datamodel-code-generator from ark-apis typespec/openapi. +# DO NOT EDIT — regenerate with `make gen-py-` in ark-apis. +# +# Copyright (c) 2026 ByteDance Ltd. and/or its affiliates. +# SPDX-License-Identifier: Apache-2.0 + +from __future__ import annotations + +from typing import Optional + +from arkruntime._models import BaseModel + + +class ModelUpgrades(BaseModel): + """ + Session upgrade 中允许调整的模型配置子集。 + + 与创建期的 `ModelOverrides` 的差别在于 `id`：upgrade 允许改模型身份， + 服务端把它解析成完整 provider / protocol / endpoint 后冻结进 Session 的 + Agent 快照。 + """ + + id: Optional[str] = None + """ + 目标模型标识，形如 `"doubao-seed-2-0-pro-260215"`。 + + 与创建期 `ModelOverrides.id` 的**解析路径不同**：此处服务端拿它当 + endpoint 反查元数据来得到 (name, version)，而不是按字符串拆分。因此 + endpoint 不存在 / 已关闭 / 元信息缺失均返回 400；显式传空串也返回 400 + （upgrade 不支持卸载底模）。模型未开通返回 403 `ModelNotOpen`；底模不支持 + 作为 Agent 使用返回 400。 + + 换 `id` 时 `speed` / `thinking` / `reasoning_effort` / `service_tier` 会按 + **新**底模重新校验取值：本次未显式提供的，沿用升级前的值参与校验，落在新 + 底模白名单外返回 400。 + """ + speed: Optional[str] = None + """ + 模型速度档位。 + """ + thinking: Optional[str] = None + """ + thinking 配置。 + """ + reasoning_effort: Optional[str] = None + """ + 推理努力程度。 + """ + service_tier: Optional[str] = None + """ + 服务档位。 + """ diff --git a/src/arkruntime/types/session/session_status.py b/src/arkruntime/types/session/session_status.py index 67fbbc3..ab1e1dc 100644 --- a/src/arkruntime/types/session/session_status.py +++ b/src/arkruntime/types/session/session_status.py @@ -18,3 +18,6 @@ class SessionStatus(str, Enum): running = "running" terminated = "terminated" rescheduling = "rescheduling" + initializing = "initializing" + failed = "failed" + upgrading = "upgrading" diff --git a/uv.lock b/uv.lock index 7377dd6..eda8b3b 100644 --- a/uv.lock +++ b/uv.lock @@ -73,7 +73,7 @@ wheels = [ [[package]] name = "arkruntime" -version = "0.5.0" +version = "0.6.0" source = { editable = "." } dependencies = [ { name = "anyio", version = "4.5.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.9'" },