arkruntime 0.9.0__tar.gz → 0.10.0__tar.gz

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

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

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

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

{arkruntime-0.9.0 → arkruntime-0.10.0}/src/arkruntime/_client.py

@@ -135,6 +135,7 @@ class Ark(SyncAPIClient):
         self.environments = resources.Environments(self)
         self.memory_stores = resources.MemoryStores(self)
         self.sessions = resources.Sessions(self)
+        self.checkpoints = resources.Checkpoints(self)
         self.skills = resources.Skills(self)
         self.vaults = resources.Vaults(self)
 
@@ -289,6 +290,7 @@ class AsyncArk(AsyncAPIClient):
         self.environments = resources.AsyncEnvironments(self)
         self.memory_stores = resources.AsyncMemoryStores(self)
         self.sessions = resources.AsyncSessions(self)
+        self.checkpoints = resources.AsyncCheckpoints(self)
         self.skills = resources.AsyncSkills(self)
         self.vaults = resources.AsyncVaults(self)
 

{arkruntime-0.9.0 → arkruntime-0.10.0}/src/arkruntime/resources/__init__.py

@@ -5,6 +5,7 @@
 from .agents import Agents, AsyncAgents
 from .batch import AsyncBatch, Batch
 from .chat import AsyncChat, Chat
+from .checkpoints import AsyncCheckpoints, Checkpoints
 from .content_generation import AsyncContentGeneration, ContentGeneration
 from .embeddings import AsyncEmbeddings, Embeddings
 from .environments import AsyncEnvironments, AsyncEnvironmentWork, Environments, EnvironmentWork
@@ -31,7 +32,9 @@ from .tokenization import AsyncTokenization, Tokenization
 from .vaults import AsyncCredentials, AsyncVaults, Credentials, Vaults
 
 __all__ = [
+    "Checkpoints",
     "Chat",
+    "AsyncCheckpoints",
     "AsyncChat",
     "Embeddings",
     "AsyncEmbeddings",

{arkruntime-0.9.0 → arkruntime-0.10.0}/src/arkruntime/resources/agents/agents.py

@@ -83,13 +83,29 @@ class Agents(SyncAPIResource):
             cast_to=Agent,
         )
 
-    def retrieve(self, agent_id: str, *, extra_headers=None, extra_query=None, extra_body=None, timeout=None) -> Agent:
+    def retrieve(
+        self,
+        agent_id: str,
+        *,
+        version: Optional[int] | 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")
+        query: dict = {}
+        if version is not NOT_GIVEN and version is not None:
+            query["version"] = version
         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
+                query=query or None,
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
             ),
             cast_to=Agent,
         )
@@ -248,14 +264,28 @@ class AsyncAgents(AsyncAPIResource):
         )
 
     async def retrieve(
-        self, agent_id: str, *, extra_headers=None, extra_query=None, extra_body=None, timeout=None
+        self,
+        agent_id: str,
+        *,
+        version: Optional[int] | 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")
+        query: dict = {}
+        if version is not NOT_GIVEN and version is not None:
+            query["version"] = version
         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
+                query=query or None,
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
             ),
             cast_to=Agent,
         )

arkruntime-0.10.0/src/arkruntime/resources/checkpoints.py

@@ -0,0 +1,250 @@
+from __future__ import annotations
+
+from typing import List, Optional
+
+from .._base_client import make_request_options
+from .._managed_agents_serialize import dump_body
+from .._resource import AsyncAPIResource, SyncAPIResource
+from .._types import NOT_GIVEN, NotGiven
+from ..types.session.checkpoint_status import CheckpointStatus
+from ..types.session.create_session_checkpoint_response import (
+    CreateSessionCheckpointResponse,
+)
+from ..types.session.delete_session_checkpoint_response import (
+    DeleteSessionCheckpointResponse,
+)
+from ..types.session.get_session_checkpoint_response import (
+    GetSessionCheckpointResponse,
+)
+from ..types.session.list_session_checkpoints_response import (
+    ListSessionCheckpointsResponse,
+)
+
+__all__ = ["Checkpoints", "AsyncCheckpoints"]
+
+_PREFIX = "/checkpoints"
+
+
+def _list_query(
+    *,
+    source_session_id=NOT_GIVEN,
+    status=NOT_GIVEN,
+    limit=NOT_GIVEN,
+    page=NOT_GIVEN,
+) -> dict:
+    q: dict = {}
+    for k, v in {
+        "source_session_id": source_session_id,
+        "status": status,
+        "limit": limit,
+        "page": page,
+    }.items():
+        if v is not NOT_GIVEN and v is not None:
+            q[k] = v
+    return q
+
+
+class Checkpoints(SyncAPIResource):
+    def create(
+        self,
+        session_id: str,
+        *,
+        name: str,
+        extra_headers=None,
+        extra_query=None,
+        extra_body=None,
+        timeout=None,
+    ) -> CreateSessionCheckpointResponse:
+        """Create a checkpoint of an idle Session.
+
+        The returned checkpoint is initially ``creating`` and becomes
+        ``ready`` once the asynchronous snapshot completes; only ready
+        checkpoints can be used as ``checkpoint_id`` in
+        ``sessions.create``.
+        """
+        if not session_id:
+            raise ValueError("session_id is required")
+        return self._post(
+            f"/sessions/{session_id}/checkpoints",
+            body=dump_body({"name": name}),
+            options=make_request_options(
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+            ),
+            cast_to=CreateSessionCheckpointResponse,
+        )
+
+    def list(
+        self,
+        *,
+        source_session_id: Optional[str] | NotGiven = NOT_GIVEN,
+        status: Optional[List[CheckpointStatus]] | NotGiven = NOT_GIVEN,
+        limit: Optional[int] | NotGiven = NOT_GIVEN,
+        page: Optional[str] | NotGiven = NOT_GIVEN,
+        extra_headers=None,
+        extra_query=None,
+        extra_body=None,
+        timeout=None,
+    ) -> ListSessionCheckpointsResponse:
+        return self._get(
+            _PREFIX,
+            options=make_request_options(
+                query=_list_query(
+                    source_session_id=source_session_id,
+                    status=status,
+                    limit=limit,
+                    page=page,
+                ),
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+            ),
+            cast_to=ListSessionCheckpointsResponse,
+        )
+
+    def retrieve(
+        self,
+        checkpoint_id: str,
+        *,
+        extra_headers=None,
+        extra_query=None,
+        extra_body=None,
+        timeout=None,
+    ) -> GetSessionCheckpointResponse:
+        if not checkpoint_id:
+            raise ValueError("checkpoint_id is required")
+        return self._get(
+            f"{_PREFIX}/{checkpoint_id}",
+            options=make_request_options(
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+            ),
+            cast_to=GetSessionCheckpointResponse,
+        )
+
+    def delete(
+        self,
+        checkpoint_id: str,
+        *,
+        extra_headers=None,
+        extra_query=None,
+        extra_body=None,
+        timeout=None,
+    ) -> DeleteSessionCheckpointResponse:
+        if not checkpoint_id:
+            raise ValueError("checkpoint_id is required")
+        return self._delete(
+            f"{_PREFIX}/{checkpoint_id}",
+            options=make_request_options(
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+            ),
+            cast_to=DeleteSessionCheckpointResponse,
+        )
+
+
+class AsyncCheckpoints(AsyncAPIResource):
+    async def create(
+        self,
+        session_id: str,
+        *,
+        name: str,
+        extra_headers=None,
+        extra_query=None,
+        extra_body=None,
+        timeout=None,
+    ) -> CreateSessionCheckpointResponse:
+        """Async variant of :meth:`Checkpoints.create`."""
+        if not session_id:
+            raise ValueError("session_id is required")
+        return await self._post(
+            f"/sessions/{session_id}/checkpoints",
+            body=dump_body({"name": name}),
+            options=make_request_options(
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+            ),
+            cast_to=CreateSessionCheckpointResponse,
+        )
+
+    async def list(
+        self,
+        *,
+        source_session_id: Optional[str] | NotGiven = NOT_GIVEN,
+        status: Optional[List[CheckpointStatus]] | NotGiven = NOT_GIVEN,
+        limit: Optional[int] | NotGiven = NOT_GIVEN,
+        page: Optional[str] | NotGiven = NOT_GIVEN,
+        extra_headers=None,
+        extra_query=None,
+        extra_body=None,
+        timeout=None,
+    ) -> ListSessionCheckpointsResponse:
+        return await self._get(
+            _PREFIX,
+            options=make_request_options(
+                query=_list_query(
+                    source_session_id=source_session_id,
+                    status=status,
+                    limit=limit,
+                    page=page,
+                ),
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+            ),
+            cast_to=ListSessionCheckpointsResponse,
+        )
+
+    async def retrieve(
+        self,
+        checkpoint_id: str,
+        *,
+        extra_headers=None,
+        extra_query=None,
+        extra_body=None,
+        timeout=None,
+    ) -> GetSessionCheckpointResponse:
+        if not checkpoint_id:
+            raise ValueError("checkpoint_id is required")
+        return await self._get(
+            f"{_PREFIX}/{checkpoint_id}",
+            options=make_request_options(
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+            ),
+            cast_to=GetSessionCheckpointResponse,
+        )
+
+    async def delete(
+        self,
+        checkpoint_id: str,
+        *,
+        extra_headers=None,
+        extra_query=None,
+        extra_body=None,
+        timeout=None,
+    ) -> DeleteSessionCheckpointResponse:
+        if not checkpoint_id:
+            raise ValueError("checkpoint_id is required")
+        return await self._delete(
+            f"{_PREFIX}/{checkpoint_id}",
+            options=make_request_options(
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+            ),
+            cast_to=DeleteSessionCheckpointResponse,
+        )

{arkruntime-0.9.0 → arkruntime-0.10.0}/src/arkruntime/resources/environments/work.py

@@ -14,6 +14,7 @@ from ..._resource import AsyncAPIResource, SyncAPIResource
 from ...types.environment.heartbeat_work_response import HeartbeatWorkResponse
 from ...types.environment.stop_work_body import StopWorkBody
 from ...types.environment.work_item import WorkItem
+from ...types.environment.work_stop_reason import WorkStopReason
 
 __all__ = ["EnvironmentWork", "AsyncEnvironmentWork"]
 
@@ -42,6 +43,11 @@ def _worker_headers(worker_id: str, extra_headers: Optional[dict]) -> dict:
     return headers
 
 
+def _validate_stop_reason(force: bool, reason: Optional[WorkStopReason]) -> None:
+    if reason is not None and not force:
+        raise ValueError("reason requires force=True")
+
+
 class EnvironmentWork(SyncAPIResource):
     def poll(
         self,
@@ -124,12 +130,14 @@ class EnvironmentWork(SyncAPIResource):
         work_id: str,
         *,
         force: bool = False,
+        reason: Optional[WorkStopReason] = None,
         extra_headers=None,
         timeout: float | httpx.Timeout | None = None,
     ) -> WorkItem:
         if not work_id:
             raise ValueError("work_id is required")
-        body = StopWorkBody(force=True) if force else StopWorkBody()
+        _validate_stop_reason(force, reason)
+        body = StopWorkBody(force=True if force else None, reason=reason)
         return self._post_without_retry(
             _path(environment_id, f"{quote(work_id, safe='')}/stop"),
             body=dump_body(body.model_dump(exclude_none=True, by_alias=True)),
@@ -220,12 +228,14 @@ class AsyncEnvironmentWork(AsyncAPIResource):
         work_id: str,
         *,
         force: bool = False,
+        reason: Optional[WorkStopReason] = None,
         extra_headers=None,
         timeout: float | httpx.Timeout | None = None,
     ) -> WorkItem:
         if not work_id:
             raise ValueError("work_id is required")
-        body = StopWorkBody(force=True) if force else StopWorkBody()
+        _validate_stop_reason(force, reason)
+        body = StopWorkBody(force=True if force else None, reason=reason)
         return await self._post_without_retry(
             _path(environment_id, f"{quote(work_id, safe='')}/stop"),
             body=dump_body(body.model_dump(exclude_none=True, by_alias=True)),

{arkruntime-0.9.0 → arkruntime-0.10.0}/src/arkruntime/resources/sessions/sessions.py

@@ -8,9 +8,13 @@ from ..._managed_agents_serialize import dump_body
 from ..._resource import AsyncAPIResource, SyncAPIResource
 from ..._types import NOT_GIVEN, NotGiven
 from ...types.session.agent_identifier import AgentIdentifier
+from ...types.session.agent_with_upgrades import AgentWithUpgrades
+from ...types.session.checkpoint_restore_config import CheckpointRestoreConfig
 from ...types.session.delete_session_response import DeleteSessionResponse
+from ...types.session.environment_with_upgrades import EnvironmentWithUpgrades
 from ...types.session.list_sessions_order import ListSessionsOrder
 from ...types.session.list_sessions_response import ListSessionsResponse
+from ...types.session.managed_agents_event_params import ManagedAgentsEventParams
 from ...types.session.session import Session
 from ...types.session.session_resource import SessionResource
 from ...types.session.session_status import SessionStatus
@@ -73,17 +77,26 @@ class Sessions(SyncAPIResource):
     def create(
         self,
         *,
-        agent: AgentIdentifier,
-        environment_id: str,
+        agent: Optional[AgentIdentifier] | NotGiven = NOT_GIVEN,
+        environment_id: Optional[str] | NotGiven = NOT_GIVEN,
         tags: Optional[List[Tag]] | NotGiven = NOT_GIVEN,
         resources: Optional[List[SessionResource]] | NotGiven = NOT_GIVEN,
         title: Optional[str] | NotGiven = NOT_GIVEN,
         vault_ids: Optional[List[str]] | NotGiven = NOT_GIVEN,
+        checkpoint_id: Optional[str] | NotGiven = NOT_GIVEN,
+        checkpoint_restore_config: Optional[CheckpointRestoreConfig] | NotGiven = NOT_GIVEN,
         extra_headers=None,
         extra_query=None,
         extra_body=None,
         timeout=None,
     ) -> Session:
+        """Create a Session, or restore one from a checkpoint.
+
+        When ``checkpoint_id`` is given, ``agent`` / ``environment_id`` may
+        be omitted and are inherited from the checkpoint snapshot.
+        ``resources`` must be omitted when restoring; ``vault_ids`` must be
+        omitted for same-account restore.
+        """
         return self._post(
             _PREFIX,
             body=dump_body(
@@ -94,6 +107,8 @@ class Sessions(SyncAPIResource):
                     "resources": resources,
                     "title": title,
                     "vault_ids": vault_ids,
+                    "checkpoint_id": checkpoint_id,
+                    "checkpoint_restore_config": checkpoint_restore_config,
                 }
             ),
             options=make_request_options(
@@ -180,6 +195,48 @@ class Sessions(SyncAPIResource):
             cast_to=Session,
         )
 
+    def upgrade(
+        self,
+        session_id: str,
+        *,
+        agent: Optional[AgentWithUpgrades] | NotGiven = NOT_GIVEN,
+        environment: Optional[EnvironmentWithUpgrades] | NotGiven = NOT_GIVEN,
+        vault_ids: Optional[List[str]] | NotGiven = NOT_GIVEN,
+        initial_events: Optional[List[ManagedAgentsEventParams]] | NotGiven = NOT_GIVEN,
+        extra_headers=None,
+        extra_query=None,
+        extra_body=None,
+        timeout=None,
+    ) -> Session:
+        """Upgrade an existing Session's runtime configuration.
+
+        At least one of ``agent``, ``environment``, or ``vault_ids`` must be
+        provided. Agent and environment IDs must match the current Session.
+        Agent array fields use whole-list replacement semantics: an explicit
+        ``[]`` clears the list, while an omitted field keeps its current value.
+        ``vault_ids`` may only refresh the currently bound set; it cannot
+        change that set. An omitted or zero agent version keeps the current
+        snapshot rather than selecting the latest version. Self-hosted
+        environments reject runtime config overrides other than ``config.type``.
+        """
+        if not session_id:
+            raise ValueError("session_id is required")
+        return self._post(
+            f"{_PREFIX}/{session_id}/upgrades",
+            body=dump_body(
+                {
+                    "agent": agent,
+                    "environment": environment,
+                    "vault_ids": vault_ids,
+                    "initial_events": initial_events,
+                }
+            ),
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=Session,
+        )
+
     def delete(
         self, session_id: str, *, extra_headers=None, extra_query=None, extra_body=None, timeout=None
     ) -> DeleteSessionResponse:
@@ -210,12 +267,14 @@ class AsyncSessions(AsyncAPIResource):
     async def create(
         self,
         *,
-        agent: AgentIdentifier,
-        environment_id: str,
+        agent: Optional[AgentIdentifier] | NotGiven = NOT_GIVEN,
+        environment_id: Optional[str] | NotGiven = NOT_GIVEN,
         tags=NOT_GIVEN,
         resources=NOT_GIVEN,
         title=NOT_GIVEN,
         vault_ids=NOT_GIVEN,
+        checkpoint_id=NOT_GIVEN,
+        checkpoint_restore_config=NOT_GIVEN,
         extra_headers=None,
         extra_query=None,
         extra_body=None,
@@ -231,6 +290,8 @@ class AsyncSessions(AsyncAPIResource):
                     "resources": resources,
                     "title": title,
                     "vault_ids": vault_ids,
+                    "checkpoint_id": checkpoint_id,
+                    "checkpoint_restore_config": checkpoint_restore_config,
                 }
             ),
             options=make_request_options(
@@ -317,6 +378,48 @@ class AsyncSessions(AsyncAPIResource):
             cast_to=Session,
         )
 
+    async def upgrade(
+        self,
+        session_id: str,
+        *,
+        agent: Optional[AgentWithUpgrades] | NotGiven = NOT_GIVEN,
+        environment: Optional[EnvironmentWithUpgrades] | NotGiven = NOT_GIVEN,
+        vault_ids: Optional[List[str]] | NotGiven = NOT_GIVEN,
+        initial_events: Optional[List[ManagedAgentsEventParams]] | NotGiven = NOT_GIVEN,
+        extra_headers=None,
+        extra_query=None,
+        extra_body=None,
+        timeout=None,
+    ) -> Session:
+        """Upgrade an existing Session's runtime configuration.
+
+        At least one of ``agent``, ``environment``, or ``vault_ids`` must be
+        provided. Agent and environment IDs must match the current Session.
+        Agent array fields use whole-list replacement semantics: an explicit
+        ``[]`` clears the list, while an omitted field keeps its current value.
+        ``vault_ids`` may only refresh the currently bound set; it cannot
+        change that set. An omitted or zero agent version keeps the current
+        snapshot rather than selecting the latest version. Self-hosted
+        environments reject runtime config overrides other than ``config.type``.
+        """
+        if not session_id:
+            raise ValueError("session_id is required")
+        return await self._post(
+            f"{_PREFIX}/{session_id}/upgrades",
+            body=dump_body(
+                {
+                    "agent": agent,
+                    "environment": environment,
+                    "vault_ids": vault_ids,
+                    "initial_events": initial_events,
+                }
+            ),
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=Session,
+        )
+
     async def delete(
         self, session_id: str, *, extra_headers=None, extra_query=None, extra_body=None, timeout=None
     ) -> DeleteSessionResponse:

{arkruntime-0.9.0 → arkruntime-0.10.0}/src/arkruntime/selfhosted/client.py

@@ -18,6 +18,7 @@ import httpx
 from arkruntime import Ark
 from arkruntime._constants import CLIENT_REQUEST_HEADER, SERVER_REQUEST_HEADER
 from arkruntime._types import NOT_GIVEN
+from arkruntime.types.environment import WorkStopReason
 
 from .types import (
     EXPECTED_LAST_HEARTBEAT_NO_HEARTBEAT,
@@ -106,7 +107,14 @@ class ClientAPI:
         )
         return response
 
-    def stop_work(self, environment_id: str, work_id: str, *, force: bool = False) -> None:
+    def stop_work(
+        self,
+        environment_id: str,
+        work_id: str,
+        *,
+        force: bool = False,
+        reason: Optional[WorkStopReason] = None,
+    ) -> None:
         if not environment_id:
             raise ValueError("environment_id is required")
         if not work_id:
@@ -115,6 +123,7 @@ class ClientAPI:
             environment_id,
             work_id,
             force=force,
+            reason=reason,
             timeout=10.0,
         )