arkruntime 0.1.0__py3-none-any.whl

arkruntime/common/streaming/chat/_events.py

@@ -0,0 +1,96 @@
+# 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 typing import Generic, List, Optional, Union
+
+from typing_extensions import Literal
+
+from ...._models import BaseModel, GenericModel
+from ....types.chat import ChatCompletionChunk, ChatCompletionTokenLogprob
+from ..._parsing import ResponseFormatT
+from ._types import ParsedChatCompletionSnapshot
+
+
+class ChunkEvent(BaseModel):
+    type: Literal["chunk"]
+
+    chunk: ChatCompletionChunk
+
+    snapshot: ParsedChatCompletionSnapshot
+
+
+class ContentDeltaEvent(BaseModel):
+    """This event is yielded for every chunk with `choice.delta.content` data."""
+
+    type: Literal["content.delta"]
+
+    delta: str
+
+    snapshot: str
+
+    parsed: Optional[object] = None
+
+
+class ContentDoneEvent(GenericModel, Generic[ResponseFormatT]):
+    type: Literal["content.done"]
+
+    content: str
+
+    parsed: Optional[ResponseFormatT] = None
+
+
+class FunctionToolCallArgumentsDeltaEvent(BaseModel):
+    type: Literal["tool_calls.function.arguments.delta"]
+
+    name: str
+
+    index: int
+
+    arguments: str
+    """Accumulated raw JSON string"""
+
+    parsed_arguments: object
+    """The parsed arguments so far"""
+
+    arguments_delta: str
+    """The JSON string delta"""
+
+
+class FunctionToolCallArgumentsDoneEvent(BaseModel):
+    type: Literal["tool_calls.function.arguments.done"]
+
+    name: str
+
+    index: int
+
+    arguments: str
+    """Accumulated raw JSON string"""
+
+    parsed_arguments: object
+    """The parsed arguments"""
+
+
+class LogprobsContentDeltaEvent(BaseModel):
+    type: Literal["logprobs.content.delta"]
+
+    content: List[ChatCompletionTokenLogprob]
+
+    snapshot: List[ChatCompletionTokenLogprob]
+
+
+class LogprobsContentDoneEvent(BaseModel):
+    type: Literal["logprobs.content.done"]
+
+    content: List[ChatCompletionTokenLogprob]
+
+
+ChatCompletionStreamEvent = Union[
+    ChunkEvent,
+    ContentDeltaEvent,
+    ContentDoneEvent[ResponseFormatT],
+    FunctionToolCallArgumentsDeltaEvent,
+    FunctionToolCallArgumentsDoneEvent,
+    LogprobsContentDeltaEvent,
+    LogprobsContentDoneEvent,
+]

arkruntime/common/streaming/chat/_types.py

@@ -0,0 +1,28 @@
+# 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 typing_extensions import TypeAlias
+
+from ....types.chat import (
+    ParsedChatCompletion,
+    ParsedChatCompletionMessage,
+    ParsedChoice,
+)
+
+ParsedChatCompletionSnapshot: TypeAlias = ParsedChatCompletion[object]
+"""Snapshot type representing an in-progress accumulation of
+a `ParsedChatCompletion` object.
+"""
+
+ParsedChatCompletionMessageSnapshot: TypeAlias = ParsedChatCompletionMessage[object]
+"""Snapshot type representing an in-progress accumulation of
+a `ParsedChatCompletionMessage` object.
+
+If the content has been fully accumulated, the `.parsed` content will be
+the `response_format` instance, otherwise it'll be the raw JSON parsed version.
+"""
+
+ParsedChoiceSnapshot: TypeAlias = ParsedChoice[object]

arkruntime/pagination.py

@@ -0,0 +1,128 @@
+# 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 typing import Any, Generic, List, Optional, TypeVar, cast
+
+from typing_extensions import Protocol, override, runtime_checkable
+
+from ._base_client import BaseAsyncPage, BasePage, BaseSyncPage, PageInfo
+
+__all__ = ["SyncPage", "AsyncPage", "SyncCursorPage", "AsyncCursorPage"]
+
+_T = TypeVar("_T")
+
+
+@runtime_checkable
+class CursorPageItem(Protocol):
+    id: Optional[str]
+
+
+class SyncPage(BaseSyncPage[_T], BasePage[_T], Generic[_T]):
+    """Note: no pagination actually occurs yet, this is for forwards-compatibility."""
+
+    data: List[_T]
+    object: str
+
+    @override
+    def _get_page_items(self) -> List[_T]:
+        data = self.data
+        if not data:
+            return []
+        return data
+
+    @override
+    def next_page_info(self) -> None:
+        """
+        This page represents a response that isn't actually paginated at the API level
+        so there will never be a next page.
+        """
+        return None
+
+
+class AsyncPage(BaseAsyncPage[_T], BasePage[_T], Generic[_T]):
+    """Note: no pagination actually occurs yet, this is for forwards-compatibility."""
+
+    data: List[_T]
+    object: str
+
+    @override
+    def _get_page_items(self) -> List[_T]:
+        data = self.data
+        if not data:
+            return []
+        return data
+
+    @override
+    def next_page_info(self) -> None:
+        """
+        This page represents a response that isn't actually paginated at the API level
+        so there will never be a next page.
+        """
+        return None
+
+
+class SyncCursorPage(BaseSyncPage[_T], BasePage[_T], Generic[_T]):
+    data: List[_T]
+    has_more: Optional[bool] = None
+
+    @override
+    def _get_page_items(self) -> List[_T]:
+        data = self.data
+        if not data:
+            return []
+        return data
+
+    @override
+    def has_next_page(self) -> bool:
+        has_more = self.has_more
+        if has_more is not None and has_more is False:
+            return False
+
+        return super().has_next_page()
+
+    @override
+    def next_page_info(self) -> Optional[PageInfo]:
+        data = self.data
+        if not data:
+            return None
+
+        item = cast(Any, data[-1])
+        if not isinstance(item, CursorPageItem) or item.id is None:
+            # TODO emit warning log
+            return None
+
+        return PageInfo(params={"after": item.id})
+
+
+class AsyncCursorPage(BaseAsyncPage[_T], BasePage[_T], Generic[_T]):
+    data: List[_T]
+    has_more: Optional[bool] = None
+
+    @override
+    def _get_page_items(self) -> List[_T]:
+        data = self.data
+        if not data:
+            return []
+        return data
+
+    @override
+    def has_next_page(self) -> bool:
+        has_more = self.has_more
+        if has_more is not None and has_more is False:
+            return False
+
+        return super().has_next_page()
+
+    @override
+    def next_page_info(self) -> Optional[PageInfo]:
+        data = self.data
+        if not data:
+            return None
+
+        item = cast(Any, data[-1])
+        if not isinstance(item, CursorPageItem) or item.id is None:
+            # TODO emit warning log
+            return None
+
+        return PageInfo(params={"after": item.id})

arkruntime/resources/__init__.py

@@ -0,0 +1,75 @@
+# 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 .agents import Agents, AsyncAgents
+from .batch import AsyncBatch, Batch
+from .chat import AsyncChat, Chat
+from .content_generation import AsyncContentGeneration, ContentGeneration
+from .embeddings import AsyncEmbeddings, Embeddings
+from .environments import AsyncEnvironments, Environments
+from .files import AsyncFiles, Files
+from .images import AsyncImages, Images
+from .memory_stores import (
+    AsyncMemories,
+    AsyncMemoryStores,
+    Memories,
+    MemoryStores,
+)
+from .multimodal_embeddings import AsyncMultimodalEmbeddings, MultimodalEmbeddings
+from .responses import AsyncInputItems, AsyncResponses, InputItems, Responses
+from .sessions import (
+    AsyncSessionEvents,
+    AsyncSessionResources,
+    AsyncSessions,
+    SessionEvents,
+    SessionResources,
+    Sessions,
+)
+from .skills import AsyncSkills, Skills
+from .tokenization import AsyncTokenization, Tokenization
+from .vaults import AsyncCredentials, AsyncVaults, Credentials, Vaults
+
+__all__ = [
+    "Chat",
+    "AsyncChat",
+    "Embeddings",
+    "AsyncEmbeddings",
+    "Tokenization",
+    "AsyncTokenization",
+    "MultimodalEmbeddings",
+    "AsyncMultimodalEmbeddings",
+    "ContentGeneration",
+    "AsyncContentGeneration",
+    "Images",
+    "AsyncImages",
+    "Batch",
+    "AsyncBatch",
+    "AsyncResponses",
+    "Responses",
+    "InputItems",
+    "AsyncInputItems",
+    "Files",
+    "AsyncFiles",
+    # managed-agents
+    "Agents",
+    "AsyncAgents",
+    "Environments",
+    "AsyncEnvironments",
+    "MemoryStores",
+    "AsyncMemoryStores",
+    "Memories",
+    "AsyncMemories",
+    "Sessions",
+    "AsyncSessions",
+    "SessionResources",
+    "AsyncSessionResources",
+    "SessionEvents",
+    "AsyncSessionEvents",
+    "Skills",
+    "AsyncSkills",
+    "Vaults",
+    "AsyncVaults",
+    "Credentials",
+    "AsyncCredentials",
+]

arkruntime/resources/agents/__init__.py

@@ -0,0 +1,3 @@
+from arkruntime.resources.agents.agents import Agents, AsyncAgents
+
+__all__ = ["Agents", "AsyncAgents"]

arkruntime/resources/agents/agents.py

@@ -0,0 +1,372 @@
+from __future__ import annotations
+
+from typing import List, Optional
+
+import httpx
+
+from ..._base_client import make_request_options
+from ..._managed_agents_serialize import dump_body
+from ..._resource import AsyncAPIResource, SyncAPIResource
+from ..._types import NOT_GIVEN, Body, Headers, NotGiven, Query
+from ...types.agent.agent import Agent
+from ...types.agent.agent_skill_ref import AgentSkillRef
+from ...types.agent.delete_agent_response import DeleteAgentResponse
+from ...types.agent.list_agents_response import ListAgentsResponse
+from ...types.agent.mcp_server import MCPServer
+from ...types.agent.model_config import ModelConfig
+from ...types.agent.multiagent_config import MultiagentConfig
+from ...types.agent.tag import Tag
+from ...types.agent.tool_item import ToolItem
+
+__all__ = ["Agents", "AsyncAgents"]
+
+_PREFIX = "/agents"
+
+
+def _list_query(
+    *,
+    limit=NOT_GIVEN,
+    page=NOT_GIVEN,
+    created_at_gte=NOT_GIVEN,
+    created_at_lte=NOT_GIVEN,
+) -> dict:
+    q: dict = {}
+    for k, v in {
+        "limit": limit,
+        "page": page,
+        "created_at_gte": created_at_gte,
+        "created_at_lte": created_at_lte,
+    }.items():
+        if v is not NOT_GIVEN and v is not None:
+            q[k] = v
+    return q
+
+
+class Agents(SyncAPIResource):
+    def create(
+        self,
+        *,
+        name: str,
+        model: ModelConfig,
+        description: Optional[str] | NotGiven = NOT_GIVEN,
+        system: Optional[str] | NotGiven = NOT_GIVEN,
+        mcp_servers: Optional[List[MCPServer]] | NotGiven = NOT_GIVEN,
+        tools: Optional[List[ToolItem]] | NotGiven = NOT_GIVEN,
+        skills: Optional[List[AgentSkillRef]] | NotGiven = NOT_GIVEN,
+        multiagent: Optional[MultiagentConfig] | NotGiven = NOT_GIVEN,
+        metadata: Optional[dict] | NotGiven = NOT_GIVEN,
+        tags: Optional[List[Tag]] | NotGiven = NOT_GIVEN,
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None = None,
+    ) -> Agent:
+        return self._post(
+            _PREFIX,
+            body=dump_body(
+                {
+                    "name": name,
+                    "model": model,
+                    "description": description,
+                    "system": system,
+                    "mcp_servers": mcp_servers,
+                    "tools": tools,
+                    "skills": skills,
+                    "multiagent": multiagent,
+                    "metadata": metadata,
+                    "tags": tags,
+                }
+            ),
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=Agent,
+        )
+
+    def retrieve(self, agent_id: str, *, extra_headers=None, extra_query=None, extra_body=None, timeout=None) -> Agent:
+        if not agent_id:
+            raise ValueError("agent_id is required")
+        return self._get(
+            f"{_PREFIX}/{agent_id}",
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=Agent,
+        )
+
+    def list(
+        self,
+        *,
+        limit=NOT_GIVEN,
+        page=NOT_GIVEN,
+        created_at_gte=NOT_GIVEN,
+        created_at_lte=NOT_GIVEN,
+        extra_headers=None,
+        extra_query=None,
+        extra_body=None,
+        timeout=None,
+    ) -> ListAgentsResponse:
+        return self._get(
+            _PREFIX,
+            options=make_request_options(
+                query=_list_query(
+                    limit=limit,
+                    page=page,
+                    created_at_gte=created_at_gte,
+                    created_at_lte=created_at_lte,
+                ),
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+            ),
+            cast_to=ListAgentsResponse,
+        )
+
+    def update(
+        self,
+        agent_id: str,
+        *,
+        version: int,
+        name: Optional[str] | NotGiven = NOT_GIVEN,
+        model: Optional[ModelConfig] | NotGiven = NOT_GIVEN,
+        description: Optional[str] | NotGiven = NOT_GIVEN,
+        system: Optional[str] | NotGiven = NOT_GIVEN,
+        mcp_servers: Optional[List[MCPServer]] | NotGiven = NOT_GIVEN,
+        tools: Optional[List[ToolItem]] | NotGiven = NOT_GIVEN,
+        skills: Optional[List[AgentSkillRef]] | NotGiven = NOT_GIVEN,
+        multiagent: Optional[MultiagentConfig] | NotGiven = NOT_GIVEN,
+        metadata: Optional[dict] | NotGiven = NOT_GIVEN,
+        extra_headers=None,
+        extra_query=None,
+        extra_body=None,
+        timeout=None,
+    ) -> Agent:
+        if not agent_id:
+            raise ValueError("agent_id is required")
+        return self._post(
+            f"{_PREFIX}/{agent_id}",
+            body=dump_body(
+                {
+                    "version": version,
+                    "name": name,
+                    "model": model,
+                    "description": description,
+                    "system": system,
+                    "mcp_servers": mcp_servers,
+                    "tools": tools,
+                    "skills": skills,
+                    "multiagent": multiagent,
+                    "metadata": metadata,
+                }
+            ),
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=Agent,
+        )
+
+    def delete(
+        self, agent_id: str, *, extra_headers=None, extra_query=None, extra_body=None, timeout=None
+    ) -> DeleteAgentResponse:
+        if not agent_id:
+            raise ValueError("agent_id is required")
+        return self._delete(
+            f"{_PREFIX}/{agent_id}",
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=DeleteAgentResponse,
+        )
+
+    def list_versions(
+        self,
+        agent_id: str,
+        *,
+        limit=NOT_GIVEN,
+        page=NOT_GIVEN,
+        extra_headers=None,
+        extra_query=None,
+        extra_body=None,
+        timeout=None,
+    ) -> ListAgentsResponse:
+        if not agent_id:
+            raise ValueError("agent_id is required")
+        q: dict = {}
+        if limit is not NOT_GIVEN and limit is not None:
+            q["limit"] = limit
+        if page is not NOT_GIVEN and page is not None:
+            q["page"] = page
+        return self._get(
+            f"{_PREFIX}/{agent_id}/versions",
+            options=make_request_options(
+                query=q, extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=ListAgentsResponse,
+        )
+
+
+class AsyncAgents(AsyncAPIResource):
+    async def create(
+        self,
+        *,
+        name: str,
+        model: ModelConfig,
+        description=NOT_GIVEN,
+        system=NOT_GIVEN,
+        mcp_servers=NOT_GIVEN,
+        tools=NOT_GIVEN,
+        skills=NOT_GIVEN,
+        multiagent=NOT_GIVEN,
+        metadata=NOT_GIVEN,
+        tags=NOT_GIVEN,
+        extra_headers=None,
+        extra_query=None,
+        extra_body=None,
+        timeout=None,
+    ) -> Agent:
+        return await self._post(
+            _PREFIX,
+            body=dump_body(
+                {
+                    "name": name,
+                    "model": model,
+                    "description": description,
+                    "system": system,
+                    "mcp_servers": mcp_servers,
+                    "tools": tools,
+                    "skills": skills,
+                    "multiagent": multiagent,
+                    "metadata": metadata,
+                    "tags": tags,
+                }
+            ),
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=Agent,
+        )
+
+    async def retrieve(
+        self, agent_id: str, *, extra_headers=None, extra_query=None, extra_body=None, timeout=None
+    ) -> Agent:
+        if not agent_id:
+            raise ValueError("agent_id is required")
+        return await self._get(
+            f"{_PREFIX}/{agent_id}",
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=Agent,
+        )
+
+    async def list(
+        self,
+        *,
+        limit=NOT_GIVEN,
+        page=NOT_GIVEN,
+        created_at_gte=NOT_GIVEN,
+        created_at_lte=NOT_GIVEN,
+        extra_headers=None,
+        extra_query=None,
+        extra_body=None,
+        timeout=None,
+    ) -> ListAgentsResponse:
+        return await self._get(
+            _PREFIX,
+            options=make_request_options(
+                query=_list_query(
+                    limit=limit,
+                    page=page,
+                    created_at_gte=created_at_gte,
+                    created_at_lte=created_at_lte,
+                ),
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+            ),
+            cast_to=ListAgentsResponse,
+        )
+
+    async def update(
+        self,
+        agent_id: str,
+        *,
+        version: int,
+        name=NOT_GIVEN,
+        model=NOT_GIVEN,
+        description=NOT_GIVEN,
+        system=NOT_GIVEN,
+        mcp_servers=NOT_GIVEN,
+        tools=NOT_GIVEN,
+        skills=NOT_GIVEN,
+        multiagent=NOT_GIVEN,
+        metadata=NOT_GIVEN,
+        extra_headers=None,
+        extra_query=None,
+        extra_body=None,
+        timeout=None,
+    ) -> Agent:
+        if not agent_id:
+            raise ValueError("agent_id is required")
+        return await self._post(
+            f"{_PREFIX}/{agent_id}",
+            body=dump_body(
+                {
+                    "version": version,
+                    "name": name,
+                    "model": model,
+                    "description": description,
+                    "system": system,
+                    "mcp_servers": mcp_servers,
+                    "tools": tools,
+                    "skills": skills,
+                    "multiagent": multiagent,
+                    "metadata": metadata,
+                }
+            ),
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=Agent,
+        )
+
+    async def delete(
+        self, agent_id: str, *, extra_headers=None, extra_query=None, extra_body=None, timeout=None
+    ) -> DeleteAgentResponse:
+        if not agent_id:
+            raise ValueError("agent_id is required")
+        return await self._delete(
+            f"{_PREFIX}/{agent_id}",
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=DeleteAgentResponse,
+        )
+
+    async def list_versions(
+        self,
+        agent_id: str,
+        *,
+        limit=NOT_GIVEN,
+        page=NOT_GIVEN,
+        extra_headers=None,
+        extra_query=None,
+        extra_body=None,
+        timeout=None,
+    ) -> ListAgentsResponse:
+        if not agent_id:
+            raise ValueError("agent_id is required")
+        q: dict = {}
+        if limit is not NOT_GIVEN and limit is not None:
+            q["limit"] = limit
+        if page is not NOT_GIVEN and page is not None:
+            q["page"] = page
+        return await self._get(
+            f"{_PREFIX}/{agent_id}/versions",
+            options=make_request_options(
+                query=q, extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=ListAgentsResponse,
+        )