arkruntime 0.1.0__py3-none-any.whl

arkruntime/resources/vaults/credentials.py

@@ -0,0 +1,253 @@
+from __future__ import annotations
+
+from ..._base_client import make_request_options
+from ..._managed_agents_serialize import dump_body
+from ..._resource import AsyncAPIResource, SyncAPIResource
+from ..._types import NOT_GIVEN
+from ...types.vault.credential import Credential
+from ...types.vault.credential_auth import CredentialAuth
+from ...types.vault.credential_validation import CredentialValidation
+from ...types.vault.delete_credential_response import DeleteCredentialResponse
+from ...types.vault.list_credentials_response import ListCredentialsResponse
+
+__all__ = ["Credentials", "AsyncCredentials"]
+
+
+def _prefix(vault_id: str) -> str:
+    return f"/vaults/{vault_id}/credentials"
+
+
+def _list_query(*, limit=NOT_GIVEN, page=NOT_GIVEN) -> dict:
+    q: dict = {}
+    for k, v in {"limit": limit, "page": page}.items():
+        if v is not NOT_GIVEN and v is not None:
+            q[k] = v
+    return q
+
+
+class Credentials(SyncAPIResource):
+    def create(
+        self,
+        vault_id: str,
+        *,
+        auth: CredentialAuth,
+        display_name=NOT_GIVEN,
+        metadata=NOT_GIVEN,
+        extra_headers=None,
+        extra_query=None,
+        extra_body=None,
+        timeout=None,
+    ) -> Credential:
+        if not vault_id:
+            raise ValueError("vault_id is required")
+        return self._post(
+            _prefix(vault_id),
+            body=dump_body({"auth": auth, "display_name": display_name, "metadata": metadata}),
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=Credential,
+        )
+
+    def retrieve(
+        self, vault_id: str, credential_id: str, *, extra_headers=None, extra_query=None, extra_body=None, timeout=None
+    ) -> Credential:
+        if not vault_id or not credential_id:
+            raise ValueError("vault_id and credential_id are required")
+        return self._get(
+            f"{_prefix(vault_id)}/{credential_id}",
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=Credential,
+        )
+
+    def list(
+        self,
+        vault_id: str,
+        *,
+        limit=NOT_GIVEN,
+        page=NOT_GIVEN,
+        extra_headers=None,
+        extra_query=None,
+        extra_body=None,
+        timeout=None,
+    ) -> ListCredentialsResponse:
+        if not vault_id:
+            raise ValueError("vault_id is required")
+        return self._get(
+            _prefix(vault_id),
+            options=make_request_options(
+                query=_list_query(limit=limit, page=page),
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+            ),
+            cast_to=ListCredentialsResponse,
+        )
+
+    def update(
+        self,
+        vault_id: str,
+        credential_id: str,
+        *,
+        auth=NOT_GIVEN,
+        display_name=NOT_GIVEN,
+        metadata=NOT_GIVEN,
+        extra_headers=None,
+        extra_query=None,
+        extra_body=None,
+        timeout=None,
+    ) -> Credential:
+        if not vault_id or not credential_id:
+            raise ValueError("vault_id and credential_id are required")
+        return self._post(
+            f"{_prefix(vault_id)}/{credential_id}",
+            body=dump_body({"auth": auth, "display_name": display_name, "metadata": metadata}),
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=Credential,
+        )
+
+    def delete(
+        self, vault_id: str, credential_id: str, *, extra_headers=None, extra_query=None, extra_body=None, timeout=None
+    ) -> DeleteCredentialResponse:
+        if not vault_id or not credential_id:
+            raise ValueError("vault_id and credential_id are required")
+        return self._delete(
+            f"{_prefix(vault_id)}/{credential_id}",
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=DeleteCredentialResponse,
+        )
+
+    def validate(
+        self, vault_id: str, credential_id: str, *, extra_headers=None, extra_query=None, extra_body=None, timeout=None
+    ) -> CredentialValidation:
+        if not vault_id or not credential_id:
+            raise ValueError("vault_id and credential_id are required")
+        return self._post(
+            f"{_prefix(vault_id)}/{credential_id}/mcp_oauth_validate",
+            body=None,
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=CredentialValidation,
+        )
+
+
+class AsyncCredentials(AsyncAPIResource):
+    async def create(
+        self,
+        vault_id: str,
+        *,
+        auth: CredentialAuth,
+        display_name=NOT_GIVEN,
+        metadata=NOT_GIVEN,
+        extra_headers=None,
+        extra_query=None,
+        extra_body=None,
+        timeout=None,
+    ) -> Credential:
+        if not vault_id:
+            raise ValueError("vault_id is required")
+        return await self._post(
+            _prefix(vault_id),
+            body=dump_body({"auth": auth, "display_name": display_name, "metadata": metadata}),
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=Credential,
+        )
+
+    async def retrieve(
+        self, vault_id: str, credential_id: str, *, extra_headers=None, extra_query=None, extra_body=None, timeout=None
+    ) -> Credential:
+        if not vault_id or not credential_id:
+            raise ValueError("vault_id and credential_id are required")
+        return await self._get(
+            f"{_prefix(vault_id)}/{credential_id}",
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=Credential,
+        )
+
+    async def list(
+        self,
+        vault_id: str,
+        *,
+        limit=NOT_GIVEN,
+        page=NOT_GIVEN,
+        extra_headers=None,
+        extra_query=None,
+        extra_body=None,
+        timeout=None,
+    ) -> ListCredentialsResponse:
+        if not vault_id:
+            raise ValueError("vault_id is required")
+        return await self._get(
+            _prefix(vault_id),
+            options=make_request_options(
+                query=_list_query(limit=limit, page=page),
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+            ),
+            cast_to=ListCredentialsResponse,
+        )
+
+    async def update(
+        self,
+        vault_id: str,
+        credential_id: str,
+        *,
+        auth=NOT_GIVEN,
+        display_name=NOT_GIVEN,
+        metadata=NOT_GIVEN,
+        extra_headers=None,
+        extra_query=None,
+        extra_body=None,
+        timeout=None,
+    ) -> Credential:
+        if not vault_id or not credential_id:
+            raise ValueError("vault_id and credential_id are required")
+        return await self._post(
+            f"{_prefix(vault_id)}/{credential_id}",
+            body=dump_body({"auth": auth, "display_name": display_name, "metadata": metadata}),
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=Credential,
+        )
+
+    async def delete(
+        self, vault_id: str, credential_id: str, *, extra_headers=None, extra_query=None, extra_body=None, timeout=None
+    ) -> DeleteCredentialResponse:
+        if not vault_id or not credential_id:
+            raise ValueError("vault_id and credential_id are required")
+        return await self._delete(
+            f"{_prefix(vault_id)}/{credential_id}",
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=DeleteCredentialResponse,
+        )
+
+    async def validate(
+        self, vault_id: str, credential_id: str, *, extra_headers=None, extra_query=None, extra_body=None, timeout=None
+    ) -> CredentialValidation:
+        if not vault_id or not credential_id:
+            raise ValueError("vault_id and credential_id are required")
+        return await self._post(
+            f"{_prefix(vault_id)}/{credential_id}/mcp_oauth_validate",
+            body=None,
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=CredentialValidation,
+        )

arkruntime/resources/vaults/vaults.py

@@ -0,0 +1,197 @@
+from __future__ import annotations
+
+from ..._base_client import make_request_options
+from ..._compat import cached_property
+from ..._managed_agents_serialize import dump_body
+from ..._resource import AsyncAPIResource, SyncAPIResource
+from ..._types import NOT_GIVEN
+from ...types.vault.delete_vault_response import DeleteVaultResponse
+from ...types.vault.list_vaults_response import ListVaultsResponse
+from ...types.vault.vault import Vault
+from .credentials import AsyncCredentials, Credentials
+
+__all__ = ["Vaults", "AsyncVaults"]
+
+_PREFIX = "/vaults"
+
+
+def _list_query(*, limit=NOT_GIVEN, page=NOT_GIVEN) -> dict:
+    q: dict = {}
+    for k, v in {"limit": limit, "page": page}.items():
+        if v is not NOT_GIVEN and v is not None:
+            q[k] = v
+    return q
+
+
+class Vaults(SyncAPIResource):
+    @cached_property
+    def credentials(self) -> Credentials:
+        return Credentials(self._client)
+
+    def create(
+        self,
+        *,
+        display_name: str,
+        metadata=NOT_GIVEN,
+        extra_headers=None,
+        extra_query=None,
+        extra_body=None,
+        timeout=None,
+    ) -> Vault:
+        return self._post(
+            _PREFIX,
+            body=dump_body({"display_name": display_name, "metadata": metadata}),
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=Vault,
+        )
+
+    def retrieve(self, vault_id: str, *, extra_headers=None, extra_query=None, extra_body=None, timeout=None) -> Vault:
+        if not vault_id:
+            raise ValueError("vault_id is required")
+        return self._get(
+            f"{_PREFIX}/{vault_id}",
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=Vault,
+        )
+
+    def list(
+        self, *, limit=NOT_GIVEN, page=NOT_GIVEN, extra_headers=None, extra_query=None, extra_body=None, timeout=None
+    ) -> ListVaultsResponse:
+        return self._get(
+            _PREFIX,
+            options=make_request_options(
+                query=_list_query(limit=limit, page=page),
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+            ),
+            cast_to=ListVaultsResponse,
+        )
+
+    def update(
+        self,
+        vault_id: str,
+        *,
+        display_name=NOT_GIVEN,
+        metadata=NOT_GIVEN,
+        extra_headers=None,
+        extra_query=None,
+        extra_body=None,
+        timeout=None,
+    ) -> Vault:
+        if not vault_id:
+            raise ValueError("vault_id is required")
+        return self._post(
+            f"{_PREFIX}/{vault_id}",
+            body=dump_body({"display_name": display_name, "metadata": metadata}),
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=Vault,
+        )
+
+    def delete(
+        self, vault_id: str, *, extra_headers=None, extra_query=None, extra_body=None, timeout=None
+    ) -> DeleteVaultResponse:
+        if not vault_id:
+            raise ValueError("vault_id is required")
+        return self._delete(
+            f"{_PREFIX}/{vault_id}",
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=DeleteVaultResponse,
+        )
+
+
+class AsyncVaults(AsyncAPIResource):
+    @cached_property
+    def credentials(self) -> AsyncCredentials:
+        return AsyncCredentials(self._client)
+
+    async def create(
+        self,
+        *,
+        display_name: str,
+        metadata=NOT_GIVEN,
+        extra_headers=None,
+        extra_query=None,
+        extra_body=None,
+        timeout=None,
+    ) -> Vault:
+        return await self._post(
+            _PREFIX,
+            body=dump_body({"display_name": display_name, "metadata": metadata}),
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=Vault,
+        )
+
+    async def retrieve(
+        self, vault_id: str, *, extra_headers=None, extra_query=None, extra_body=None, timeout=None
+    ) -> Vault:
+        if not vault_id:
+            raise ValueError("vault_id is required")
+        return await self._get(
+            f"{_PREFIX}/{vault_id}",
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=Vault,
+        )
+
+    async def list(
+        self, *, limit=NOT_GIVEN, page=NOT_GIVEN, extra_headers=None, extra_query=None, extra_body=None, timeout=None
+    ) -> ListVaultsResponse:
+        return await self._get(
+            _PREFIX,
+            options=make_request_options(
+                query=_list_query(limit=limit, page=page),
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+            ),
+            cast_to=ListVaultsResponse,
+        )
+
+    async def update(
+        self,
+        vault_id: str,
+        *,
+        display_name=NOT_GIVEN,
+        metadata=NOT_GIVEN,
+        extra_headers=None,
+        extra_query=None,
+        extra_body=None,
+        timeout=None,
+    ) -> Vault:
+        if not vault_id:
+            raise ValueError("vault_id is required")
+        return await self._post(
+            f"{_PREFIX}/{vault_id}",
+            body=dump_body({"display_name": display_name, "metadata": metadata}),
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=Vault,
+        )
+
+    async def delete(
+        self, vault_id: str, *, extra_headers=None, extra_query=None, extra_body=None, timeout=None
+    ) -> DeleteVaultResponse:
+        if not vault_id:
+            raise ValueError("vault_id is required")
+        return await self._delete(
+            f"{_PREFIX}/{vault_id}",
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=DeleteVaultResponse,
+        )

arkruntime/types/__init__.py

@@ -0,0 +1,7 @@
+# Copyright (c) 2025 ByteDance Ltd. and/or its affiliates.
+# SPDX-License-Identifier: Apache-2.0
+# License text: https://github.com/volcengine/ark-runtime-python/blob/main/LICENSE
+
+from __future__ import annotations
+
+from .completion_usage import CompletionUsage as CompletionUsage

arkruntime/types/agent/__init__.py

@@ -0,0 +1,56 @@
+# 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 .agent import Agent
+from .agent_ref import AgentRef
+from .agent_ref_type import AgentRefType
+from .agent_skill_ref import AgentSkillRef
+from .create_agent_request import CreateAgentRequest
+from .delete_agent_response import DeleteAgentResponse
+from .list_agents_response import ListAgentsResponse
+from .mcp_server import MCPServer
+from .mcp_server_type import MCPServerType
+from .model_config import ModelConfig
+from .model_speed import ModelSpeed
+from .multiagent_config import MultiagentConfig
+from .multiagent_type import MultiagentType
+from .permission_policy import PermissionPolicy
+from .permission_policy_type import PermissionPolicyType
+from .skill_ref_type import SkillRefType
+from .tag import Tag
+from .tool_config import ToolConfig
+from .tool_default_config import ToolDefaultConfig
+from .tool_item import ToolItem
+from .update_agent_request import UpdateAgentRequest
+
+__all__ = [
+    "Agent",
+    "AgentRef",
+    "AgentRefType",
+    "AgentSkillRef",
+    "CreateAgentRequest",
+    "DeleteAgentResponse",
+    "ListAgentsResponse",
+    "MCPServer",
+    "MCPServerType",
+    "ModelConfig",
+    "ModelSpeed",
+    "MultiagentConfig",
+    "MultiagentType",
+    "PermissionPolicy",
+    "PermissionPolicyType",
+    "SkillRefType",
+    "Tag",
+    "ToolConfig",
+    "ToolDefaultConfig",
+    "ToolItem",
+    "UpdateAgentRequest",
+]
+
+# Hand-written extras (preserved across regen via Makefile rsync --exclude=*_shim.py).
+from ._init_extras_shim import *  # noqa: F401,F403

arkruntime/types/agent/_init_extras_shim.py

@@ -0,0 +1,12 @@
+# Copyright (c) 2026 ByteDance Ltd. and/or its affiliates.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Hand-written extras shim for the agent API (empty stub).
+
+Preserved across regen via the Makefile rsync --exclude=*_shim.py rule.
+Add re-exports here as needed.
+"""
+
+from __future__ import annotations
+
+__all__: list[str] = []

arkruntime/types/agent/agent.py

@@ -0,0 +1,86 @@
+# 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, Literal, Optional
+
+from arkruntime._models import BaseModel
+
+from .agent_skill_ref import AgentSkillRef
+from .mcp_server import MCPServer
+from .model_config import ModelConfig
+from .multiagent_config import MultiagentConfig
+from .tag import Tag
+from .tool_item import ToolItem
+
+
+class Agent(BaseModel):
+    """
+    ARK Managed Agents 控制面核心资源
+    （模型 + System Prompt + Tools + MCP servers + Skills 的可复用、版本化配置）。
+    """
+
+    id: str
+    """
+    Agent ID，格式 `agent_<opaque>`。对外暴露给 session 引用。
+    """
+    type: Literal["agent"]
+    """
+    固定 `"agent"`。
+    """
+    name: str
+    """
+    人类可读名称，1–256 字符。
+    """
+    description: Optional[str] = None
+    """
+    描述信息，最大 2048 字符。
+    """
+    version: int
+    """
+    版本号；每次 update 递增。
+    """
+    model: Optional[ModelConfig] = None
+    """
+    模型配置。
+    """
+    system: Optional[str] = None
+    """
+    System prompt，最大 100,000 字符。
+    """
+    tools: Optional[List[ToolItem]] = None
+    """
+    工具配置数组。
+    """
+    mcp_servers: Optional[List[MCPServer]] = None
+    """
+    MCP 服务器列表，最多 20 项。
+    """
+    skills: Optional[List[AgentSkillRef]] = None
+    """
+    Skill 列表，最多 20 项。
+    """
+    multiagent: Optional[MultiagentConfig] = None
+    """
+    多 Agent 编排拓扑（可选）。
+    """
+    metadata: Optional[Dict[str, str]] = None
+    """
+    用户自定义键值对元数据。最多 16 对，key ≤ 64 字符，value ≤ 512 字符。
+    """
+    tags: Optional[List[Tag]] = None
+    """
+    资源标签。
+    """
+    created_at: str
+    """
+    RFC 3339 时间。
+    """
+    updated_at: str
+    """
+    RFC 3339 时间。
+    """

arkruntime/types/agent/agent_ref.py

@@ -0,0 +1,32 @@
+# 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 .agent_ref_type import AgentRefType
+
+
+class AgentRef(BaseModel):
+    """
+    coordinator Agent 编排的下属 Agent 引用。
+    """
+
+    type: AgentRefType
+    """
+    引用类型。
+    """
+    id: Optional[str] = None
+    """
+    被引用 Agent 的 ID。
+    """
+    version: Optional[int] = None
+    """
+    被引用 Agent 的版本号。
+    """

arkruntime/types/agent/agent_ref_type.py

@@ -0,0 +1,18 @@
+# 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 AgentRefType(str, Enum):
+    """
+    多 Agent 引用类型。
+    """
+
+    agent = "agent"
+    self = "self"

arkruntime/types/agent/agent_skill_ref.py

@@ -0,0 +1,32 @@
+# 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 .skill_ref_type import SkillRefType
+
+
+class AgentSkillRef(BaseModel):
+    """
+    Agent 引用的一条 Skill。
+    """
+
+    type: SkillRefType
+    """
+    Skill 引用类型。一期仅支持 `skill_hub`。
+    """
+    skill_id: Optional[str] = None
+    """
+    Skill ID，形如 `skill_01XJ5...`。
+    """
+    version: Optional[str] = None
+    """
+    Skill 版本号，可选；不传走最新。
+    """