arkruntime 0.8.0__tar.gz → 0.9.0__tar.gz

{arkruntime-0.8.0/src/arkruntime.egg-info → arkruntime-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arkruntime
-Version: 0.8.0
+Version: 0.9.0
 Summary: Ark runtime SDK for Python
 Author: Volcengine
 License: Apache-2.0

{arkruntime-0.8.0 → arkruntime-0.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "arkruntime"
-version = "0.8.0"
+version = "0.9.0"
 description = "Ark runtime SDK for Python"
 readme = "README.md"
 requires-python = ">=3.8"

{arkruntime-0.8.0 → arkruntime-0.9.0}/src/arkruntime/resources/skills/skills.py

@@ -6,6 +6,7 @@ from ..._base_client import make_request_options
 from ..._resource import AsyncAPIResource, SyncAPIResource
 from ..._types import NOT_GIVEN, NotGiven
 from ...types.skill.skill import Skill
+from ...types.skill.skill_version import SkillVersion
 
 __all__ = ["Skills", "AsyncSkills"]
 
@@ -70,6 +71,35 @@ class Skills(SyncAPIResource):
             cast_to=Skill,
         )
 
+    def create_version(
+        self,
+        skill_id: str,
+        *,
+        files: FileArg,
+        display_title: Optional[str] | NotGiven = NOT_GIVEN,
+        extra_headers=None,
+        extra_query=None,
+        extra_body=None,
+        timeout=None,
+    ) -> SkillVersion:
+        if not skill_id:
+            raise ValueError("skill_id is required")
+        body: dict = {}
+        if display_title is not NOT_GIVEN and display_title is not None:
+            body["display_title"] = display_title
+        return self._post(
+            f"{_PREFIX}/{skill_id}/versions",
+            body=body,
+            files=_files_kwarg(files),
+            options=make_request_options(
+                extra_headers=_multipart_headers(extra_headers),
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+            ),
+            cast_to=SkillVersion,
+        )
+
 
 class AsyncSkills(AsyncAPIResource):
     async def create(
@@ -110,3 +140,32 @@ class AsyncSkills(AsyncAPIResource):
             ),
             cast_to=Skill,
         )
+
+    async def create_version(
+        self,
+        skill_id: str,
+        *,
+        files: FileArg,
+        display_title: Optional[str] | NotGiven = NOT_GIVEN,
+        extra_headers=None,
+        extra_query=None,
+        extra_body=None,
+        timeout=None,
+    ) -> SkillVersion:
+        if not skill_id:
+            raise ValueError("skill_id is required")
+        body: dict = {}
+        if display_title is not NOT_GIVEN and display_title is not None:
+            body["display_title"] = display_title
+        return await self._post(
+            f"{_PREFIX}/{skill_id}/versions",
+            body=body,
+            files=_files_kwarg(files),
+            options=make_request_options(
+                extra_headers=_multipart_headers(extra_headers),
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+            ),
+            cast_to=SkillVersion,
+        )

{arkruntime-0.8.0 → arkruntime-0.9.0}/src/arkruntime/types/session/__init__.py

@@ -12,9 +12,17 @@ from .agent_with_upgrades import AgentWithUpgrades
 from .base64_document_source import Base64DocumentSource
 from .base64_image_source import Base64ImageSource
 from .cache_creation import CacheCreation
+from .checkpoint_component import CheckpointComponent
+from .checkpoint_component_status import CheckpointComponentStatus
+from .checkpoint_restore_config import CheckpointRestoreConfig
+from .checkpoint_session_snapshot import CheckpointSessionSnapshot
+from .checkpoint_status import CheckpointStatus
+from .create_session_checkpoint_request import CreateSessionCheckpointRequest
+from .create_session_checkpoint_response import CreateSessionCheckpointResponse
 from .create_session_request import CreateSessionRequest
 from .create_session_resource_request import CreateSessionResourceRequest
 from .create_session_upgrade_request import CreateSessionUpgradeRequest
+from .delete_session_checkpoint_response import DeleteSessionCheckpointResponse
 from .delete_session_response import DeleteSessionResponse
 from .document_source import DocumentSource
 from .environment_config_override import EnvironmentConfigOverride
@@ -25,7 +33,9 @@ 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 .get_session_checkpoint_response import GetSessionCheckpointResponse
 from .image_source import ImageSource
+from .list_session_checkpoints_response import ListSessionCheckpointsResponse
 from .list_session_events_response_wire import ListSessionEventsResponseWire
 from .list_session_resources_response import ListSessionResourcesResponse
 from .list_session_threads_response import ListSessionThreadsResponse
@@ -76,12 +86,14 @@ from .managed_agents_user_tool_result_event_params import (
 )
 from .model_overrides import ModelOverrides
 from .model_upgrades import ModelUpgrades
+from .override_token_limits import OverrideTokenLimits
 from .plain_text_document_source import PlainTextDocumentSource
 from .search_result_citations import SearchResultCitations
 from .search_result_content import SearchResultContent
 from .send_session_events_request import SendSessionEventsRequest
 from .send_session_events_response import SendSessionEventsResponse
 from .session import Session
+from .session_checkpoint import SessionCheckpoint
 from .session_resource import SessionResource
 from .session_resource_access import SessionResourceAccess
 from .session_resource_type import SessionResourceType
@@ -102,9 +114,17 @@ __all__ = [
     "Base64DocumentSource",
     "Base64ImageSource",
     "CacheCreation",
+    "CheckpointComponent",
+    "CheckpointComponentStatus",
+    "CheckpointRestoreConfig",
+    "CheckpointSessionSnapshot",
+    "CheckpointStatus",
+    "CreateSessionCheckpointRequest",
+    "CreateSessionCheckpointResponse",
     "CreateSessionRequest",
     "CreateSessionResourceRequest",
     "CreateSessionUpgradeRequest",
+    "DeleteSessionCheckpointResponse",
     "DeleteSessionResponse",
     "DocumentSource",
     "EnvironmentConfigOverride",
@@ -115,7 +135,9 @@ __all__ = [
     "EnvironmentWithUpgrades",
     "FileDocumentSource",
     "FileImageSource",
+    "GetSessionCheckpointResponse",
     "ImageSource",
+    "ListSessionCheckpointsResponse",
     "ListSessionEventsResponseWire",
     "ListSessionResourcesResponse",
     "ListSessionThreadsResponse",
@@ -150,12 +172,14 @@ __all__ = [
     "ManagedAgentsUserToolResultEventParams",
     "ModelOverrides",
     "ModelUpgrades",
+    "OverrideTokenLimits",
     "PlainTextDocumentSource",
     "SearchResultCitations",
     "SearchResultContent",
     "SendSessionEventsRequest",
     "SendSessionEventsResponse",
     "Session",
+    "SessionCheckpoint",
     "SessionResource",
     "SessionResourceAccess",
     "SessionResourceType",

arkruntime-0.9.0/src/arkruntime/types/session/checkpoint_component.py

@@ -0,0 +1,50 @@
+# Generated by datamodel-code-generator from ark-apis typespec/openapi.
+# DO NOT EDIT — regenerate with `make gen-py-<api>` 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
+
+from .checkpoint_component_status import CheckpointComponentStatus
+
+
+class CheckpointComponent(BaseModel):
+    """
+    Checkpoint 中单个资源组件的脱敏执行摘要。
+
+    不暴露运行时 Snapshot ID、平台 TOS Prefix、Credential 等内部信息。
+    """
+
+    type: str
+    """
+    组件类型。
+    """
+    status: CheckpointComponentStatus
+    """
+    组件快照状态。
+    """
+    source_resource_id: Optional[str] = None
+    """
+    源资源 ID。
+    """
+    object_count: Optional[int] = None
+    """
+    快照对象数。
+    """
+    storage_bytes: Optional[int] = None
+    """
+    快照占用字节数。
+    """
+    error_code: Optional[str] = None
+    """
+    失败错误码。
+    """
+    error_message: Optional[str] = None
+    """
+    失败错误信息。
+    """

arkruntime-0.9.0/src/arkruntime/types/session/checkpoint_component_status.py

@@ -0,0 +1,20 @@
+# Generated by datamodel-code-generator from ark-apis typespec/openapi.
+# DO NOT EDIT — regenerate with `make gen-py-<api>` 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 CheckpointComponentStatus(str, Enum):
+    """
+    单个 Checkpoint 组件（资源快照分区）的状态。
+    """
+
+    creating = "creating"
+    ready = "ready"
+    failed = "failed"
+    deleted = "deleted"

arkruntime-0.9.0/src/arkruntime/types/session/checkpoint_restore_config.py

@@ -0,0 +1,33 @@
+# Generated by datamodel-code-generator from ark-apis typespec/openapi.
+# DO NOT EDIT — regenerate with `make gen-py-<api>` in ark-apis.
+#
+# Copyright (c) 2026 ByteDance Ltd. and/or its affiliates.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from arkruntime._models import BaseModel
+
+
+class CheckpointRestoreConfig(BaseModel):
+    """
+    跨账号 Checkpoint 恢复的目标账号侧配置。
+
+    是否提供分三种情况：
+    - 同账号恢复：**必须省略**，携带返回 400；
+    - 跨账号恢复但 Checkpoint 不含 customer TOS 数据（仅平台托管的
+    uploads/outputs/memory 等）：**必须省略**，携带返回 400，错误码
+    消息为 "checkpoint_restore_config is only allowed when the
+    checkpoint contains customer TOS data"；
+    - 跨账号恢复且 Checkpoint 包含 customer TOS 数据：**必填**
+    `tos_bucket`，声明调用方已离线同步好快照的目标账号 TOS 桶；
+    省略返回 400。
+
+    快照源 prefix、region、mount_path、access 均从 Checkpoint 继承，
+    最终 Session 目标 key 由平台生成。
+    """
+
+    tos_bucket: str
+    """
+    调用方已将 customer TOS 快照同步到的目标账号 TOS 桶。
+    """

arkruntime-0.9.0/src/arkruntime/types/session/checkpoint_session_snapshot.py

@@ -0,0 +1,49 @@
+# Generated by datamodel-code-generator from ark-apis typespec/openapi.
+# DO NOT EDIT — regenerate with `make gen-py-<api>` 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, Optional
+
+from arkruntime._models import BaseModel
+
+from .session_resource import SessionResource
+from .tag import Tag
+
+
+class CheckpointSessionSnapshot(BaseModel):
+    """
+    创建 Checkpoint 时冻结的用户可见 Session 配置。
+
+    `agent` / `environment` 反映创建瞬间的 wire 形态（分别与 Ark.Agent 的
+    Agent、Ark.Environment 的 Environment 同 shape），为保持本模块自足，
+    此处承载为 `Record<unknown>`。
+    """
+
+    agent: Optional[Dict[str, object]] = None
+    """
+    冻结的 Agent 快照。
+    """
+    environment: Optional[Dict[str, object]] = None
+    """
+    冻结的 Environment 快照。
+    """
+    resources: Optional[List[SessionResource]] = None
+    """
+    冻结的挂载资源列表。
+    """
+    vault_ids: Optional[List[str]] = None
+    """
+    冻结的可访问 Vault ID 列表。
+    """
+    title: Optional[str] = None
+    """
+    冻结的会话标题。
+    """
+    tags: Optional[List[Tag]] = None
+    """
+    冻结的资源标签。
+    """

arkruntime-0.9.0/src/arkruntime/types/session/checkpoint_status.py

@@ -0,0 +1,21 @@
+# Generated by datamodel-code-generator from ark-apis typespec/openapi.
+# DO NOT EDIT — regenerate with `make gen-py-<api>` 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 CheckpointStatus(str, Enum):
+    """
+    Checkpoint 生命周期状态。
+    """
+
+    creating = "creating"
+    ready = "ready"
+    failed = "failed"
+    deleting = "deleting"
+    deleted = "deleted"

arkruntime-0.9.0/src/arkruntime/types/session/create_session_checkpoint_request.py

@@ -0,0 +1,21 @@
+# Generated by datamodel-code-generator from ark-apis typespec/openapi.
+# DO NOT EDIT — regenerate with `make gen-py-<api>` in ark-apis.
+#
+# Copyright (c) 2026 ByteDance Ltd. and/or its affiliates.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from arkruntime._models import BaseModel
+
+
+class CreateSessionCheckpointRequest(BaseModel):
+    """
+    创建 Session Checkpoint 的请求体。
+    """
+
+    name: str
+    """
+    Checkpoint 名称；由调用方提供，长度 1–128，仅用于展示。
+    Checkpoint ID 由平台生成并在响应的 `id` 字段返回。
+    """

arkruntime-0.9.0/src/arkruntime/types/session/create_session_checkpoint_response.py

@@ -0,0 +1,22 @@
+# Generated by datamodel-code-generator from ark-apis typespec/openapi.
+# DO NOT EDIT — regenerate with `make gen-py-<api>` in ark-apis.
+#
+# Copyright (c) 2026 ByteDance Ltd. and/or its affiliates.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from arkruntime._models import BaseModel
+
+from .session_checkpoint import SessionCheckpoint
+
+
+class CreateSessionCheckpointResponse(BaseModel):
+    """
+    `POST /sessions/{session_id}/checkpoints` 响应体。
+    """
+
+    checkpoint: SessionCheckpoint
+    """
+    创建出的 Checkpoint。
+    """

arkruntime-0.9.0/src/arkruntime/types/session/create_session_request.py

@@ -0,0 +1,79 @@
+# Generated by datamodel-code-generator from ark-apis typespec/openapi.
+# DO NOT EDIT — regenerate with `make gen-py-<api>` 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_identifier import AgentIdentifier
+from .checkpoint_restore_config import CheckpointRestoreConfig
+from .environment_with_overrides import EnvironmentWithOverrides
+from .session_resource import SessionResource
+from .tag import Tag
+
+
+class CreateSessionRequest(BaseModel):
+    """
+    创建会话请求。
+
+    `agent` 字段承载两种 wire 形态：
+    - 裸 `agent_id` 字符串
+    - AgentRef 对象：`{"type":"agent","id":"agent_...","version":1}`
+    """
+
+    agent: Optional[AgentIdentifier] = None
+    """
+    Agent 标识。普通创建必填；携带 `checkpoint_id` 恢复时可省略。
+
+    注意两种恢复基线的区别：
+    - **省略 `agent`**：完整继承 Checkpoint 冻结的 Agent 快照（含其
+    system / tools / model 接入配置等全部字段）；
+    - **显式提供 `agent`**：不是在 Checkpoint 快照上做局部修改，而是按
+    Agent 引用重新解析（指定 `version` 取该版本，省略取当前最新版；
+    源 Agent 在 Checkpoint 冻结后更新过就会拿到新配置），再在该基线
+    上应用 `agent_with_overrides` 覆写。
+    """
+    environment_id: Optional[str] = None
+    """
+    关联的 Environment ID。与 `environment` 二选一；恢复时省略则继承快照。
+    """
+    environment: Optional[EnvironmentWithOverrides] = None
+    """
+    关联 Environment 的覆写引用。与 `environment_id` 二选一。
+    """
+    tags: Optional[List[Tag]] = None
+    """
+    资源标签。
+    """
+    resources: Optional[List[SessionResource]] = None
+    """
+    挂载资源列表。普通创建可指定；基于 Checkpoint 恢复时**必须省略**
+    （同账号 / 跨账号都完整继承 Checkpoint 资源，显式传空数组也返回 400）。
+    """
+    title: Optional[str] = None
+    """
+    会话人类可读标题。
+    """
+    vault_ids: Optional[List[str]] = None
+    """
+    会话可访问的 Vault ID 列表。基于 Checkpoint 同账号恢复时必须省略并
+    继承快照；跨账号恢复允许显式提供完整替换列表（空数组同样属于覆盖）。
+    """
+    checkpoint_id: Optional[str] = None
+    """
+    Session Checkpoint ID。省略时为普通创建；传入时以 ready 状态
+    Checkpoint 的冻结配置为默认值创建新 Session，未显式提供的字段均从
+    快照继承。Checkpoint 不存在 / 非 ready 返回对应 4xx。
+    """
+    checkpoint_restore_config: Optional[CheckpointRestoreConfig] = None
+    """
+    跨账号 customer TOS 恢复配置。**不是所有跨账号恢复都需要**：仅当跨
+    账号恢复且 Checkpoint 含 customer TOS 数据时必填；同账号恢复、以及
+    跨账号但不含 customer TOS 时必须省略，否则返回 400。三分支细则见
+    `CheckpointRestoreConfig`。
+    """

arkruntime-0.9.0/src/arkruntime/types/session/delete_session_checkpoint_response.py

@@ -0,0 +1,26 @@
+# Generated by datamodel-code-generator from ark-apis typespec/openapi.
+# DO NOT EDIT — regenerate with `make gen-py-<api>` in ark-apis.
+#
+# Copyright (c) 2026 ByteDance Ltd. and/or its affiliates.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from arkruntime._models import BaseModel
+
+from .checkpoint_status import CheckpointStatus
+
+
+class DeleteSessionCheckpointResponse(BaseModel):
+    """
+    `DELETE /checkpoints/{checkpoint_id}` 响应体。
+    """
+
+    id: str
+    """
+    被删除的 Checkpoint ID。
+    """
+    status: CheckpointStatus
+    """
+    删除受理后的 Checkpoint 状态（通常为 `"deleting"`）。
+    """

arkruntime-0.9.0/src/arkruntime/types/session/get_session_checkpoint_response.py

@@ -0,0 +1,22 @@
+# Generated by datamodel-code-generator from ark-apis typespec/openapi.
+# DO NOT EDIT — regenerate with `make gen-py-<api>` in ark-apis.
+#
+# Copyright (c) 2026 ByteDance Ltd. and/or its affiliates.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from arkruntime._models import BaseModel
+
+from .session_checkpoint import SessionCheckpoint
+
+
+class GetSessionCheckpointResponse(BaseModel):
+    """
+    `GET /checkpoints/{checkpoint_id}` 响应体。
+    """
+
+    checkpoint: SessionCheckpoint
+    """
+    Checkpoint 对象。
+    """

arkruntime-0.9.0/src/arkruntime/types/session/list_session_checkpoints_response.py

@@ -0,0 +1,28 @@
+# Generated by datamodel-code-generator from ark-apis typespec/openapi.
+# DO NOT EDIT — regenerate with `make gen-py-<api>` 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 .session_checkpoint import SessionCheckpoint
+
+
+class ListSessionCheckpointsResponse(BaseModel):
+    """
+    `GET /checkpoints` 响应体。
+    """
+
+    data: List[SessionCheckpoint]
+    """
+    本页 Checkpoint 列表。
+    """
+    next_page: Optional[str] = None
+    """
+    下一页 cursor；已列尽时为空或缺省。
+    """

arkruntime-0.9.0/src/arkruntime/types/session/model_overrides.py

@@ -0,0 +1,79 @@
+# Generated by datamodel-code-generator from ark-apis typespec/openapi.
+# DO NOT EDIT — regenerate with `make gen-py-<api>` 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, Optional
+
+from arkruntime._models import BaseModel
+
+from .override_token_limits import OverrideTokenLimits
+
+
+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
+    """
+    模型速度档位。
+    """
+    thinking: Optional[str] = None
+    """
+    thinking 配置。
+    """
+    reasoning_effort: Optional[str] = None
+    """
+    推理努力程度。
+    """
+    service_tier: Optional[str] = None
+    """
+    服务档位。
+    """
+    provider: Optional[str] = None
+    """
+    模型提供方覆写，例如 `"ark"` 或外接 provider 名。非空才生效，显式传空
+    串返回 400。切到非 ark provider 时，`base_url` 与 `token_limits` 为
+    必填（可继承快照中已有的值，否则返回 400）；ark provider 不允许指定
+    `token_limits`。
+    """
+    protocol: Optional[str] = None
+    """
+    模型接入协议覆写；取值须命中服务端维护的接入协议白名单，非法值返回
+    400。
+    """
+    base_url: Optional[str] = None
+    """
+    自定义模型接入点 base URL。配合非 ark 的 `provider` 使用，把 Session
+    快照里冻结的上游替换成当前环境可达的接入点。
+    """
+    headers: Optional[Dict[str, str]] = None
+    """
+    自定义模型请求 header（整组覆写），例如 `Authorization` 或
+    `X-Trial-Id`；key / value 均为字符串。
+    """
+    token_limits: Optional[OverrideTokenLimits] = None
+    """
+    模型 token 限制覆写（整体替换，提供时内部三字段必填且为正数）；
+    非 ark provider 可用，ark provider 指定返回 400。
+    """
+    input_modalities: Optional[List[str]] = None
+    """
+    底模支持的输入模态列表覆写。取值域：`text` / `image` / `audio` /
+    `video`（无 `document`；文档在内部归入 image 通道）。
+
+    服务端会做归一化：去空白、转小写、元素去重、拒绝空元素，元素长度
+    上限 32，列表长度上限 16，超出返回 400。
+    """

arkruntime-0.9.0/src/arkruntime/types/session/override_token_limits.py

@@ -0,0 +1,37 @@
+# Generated by datamodel-code-generator from ark-apis typespec/openapi.
+# DO NOT EDIT — regenerate with `make gen-py-<api>` in ark-apis.
+#
+# Copyright (c) 2026 ByteDance Ltd. and/or its affiliates.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from typing_extensions import Annotated
+
+
+from arkruntime._models import BaseModel
+from pydantic import Field
+
+
+class OverrideTokenLimits(BaseModel):
+    """
+    Session 创建期模型覆写使用的 token 限制。
+
+    **整体替换语义**：省略整个 `token_limits` 对象表示不覆写、继承快照值；
+    一旦提供对象，三个字段**全部必填**且为正整数（>= 1），服务端不会与
+    快照中的旧 limits 按字段合并——只传部分字段返回 400
+    `model.token_limits.<field>: required`。
+    """
+
+    context_window: Annotated[int, Field(ge=1)]
+    """
+    模型上下文窗口；正整数。
+    """
+    max_input_token_length: Annotated[int, Field(ge=1)]
+    """
+    最大输入 token 长度；正整数。
+    """
+    max_output_token_length: Annotated[int, Field(ge=1)]
+    """
+    最大输出 token 长度；正整数。
+    """