plato-sdk-v2 2.7.8__tar.gz → 2.8.0__tar.gz

{plato_sdk_v2-2.7.8 → plato_sdk_v2-2.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plato-sdk-v2
-Version: 2.7.8
+Version: 2.8.0
 Summary: Python SDK for the Plato API
 Author-email: Plato <support@plato.so>
 License-Expression: MIT

plato_sdk_v2-2.8.0/VERSION

@@ -0,0 +1 @@
+2.8.0

{plato_sdk_v2-2.7.8 → plato_sdk_v2-2.8.0}/plato/_generated/__init__.py

@@ -1,4 +1,4 @@
-"""Plato API SDK - v0.47.0"""
+"""Plato API SDK - v0.48.2"""
 
 from . import api, errors, models
 from .client import AsyncClient, Client

{plato_sdk_v2-2.7.8 → plato_sdk_v2-2.8.0}/plato/_generated/api/v2/sessions/__init__.py

@@ -23,6 +23,7 @@ from . import (
     list_sessions,
     log_job_mutation,
     make,
+    remove_job,
     reset,
     set_date,
     setup_sandbox,
@@ -37,6 +38,7 @@ __all__ = [
     "make",
     "list_jobs",
     "add_job",
+    "remove_job",
     "reset",
     "heartbeat",
     "connect_network",

plato_sdk_v2-2.8.0/plato/_generated/api/v2/sessions/remove_job.py

@@ -0,0 +1,89 @@
+"""Remove Job"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from plato._generated.errors import raise_for_status
+from plato._generated.models import RemoveJobRequest, RemoveJobResponse
+
+
+def _build_request_args(
+    session_id: str,
+    body: RemoveJobRequest,
+    authorization: str | None = None,
+    x_api_key: str | None = None,
+) -> dict[str, Any]:
+    """Build request arguments."""
+    url = f"/api/v2/sessions/{session_id}/remove-job"
+
+    headers: dict[str, str] = {}
+    if authorization is not None:
+        headers["authorization"] = authorization
+    if x_api_key is not None:
+        headers["X-API-Key"] = x_api_key
+
+    return {
+        "method": "POST",
+        "url": url,
+        "json": body.model_dump(mode="json", exclude_none=True),
+        "headers": headers,
+    }
+
+
+def sync(
+    client: httpx.Client,
+    session_id: str,
+    body: RemoveJobRequest,
+    authorization: str | None = None,
+    x_api_key: str | None = None,
+) -> RemoveJobResponse:
+    """Remove a job from a session.
+
+    This will:
+    1. Remove the job from the session's network (if connected)
+    2. Shut down the VM associated with the job
+    3. Cancel the job in the system
+
+    Use this to clean up individual jobs without closing the entire session."""
+
+    request_args = _build_request_args(
+        session_id=session_id,
+        body=body,
+        authorization=authorization,
+        x_api_key=x_api_key,
+    )
+
+    response = client.request(**request_args)
+    raise_for_status(response)
+    return RemoveJobResponse.model_validate(response.json())
+
+
+async def asyncio(
+    client: httpx.AsyncClient,
+    session_id: str,
+    body: RemoveJobRequest,
+    authorization: str | None = None,
+    x_api_key: str | None = None,
+) -> RemoveJobResponse:
+    """Remove a job from a session.
+
+    This will:
+    1. Remove the job from the session's network (if connected)
+    2. Shut down the VM associated with the job
+    3. Cancel the job in the system
+
+    Use this to clean up individual jobs without closing the entire session."""
+
+    request_args = _build_request_args(
+        session_id=session_id,
+        body=body,
+        authorization=authorization,
+        x_api_key=x_api_key,
+    )
+
+    response = await client.request(**request_args)
+    raise_for_status(response)
+    return RemoveJobResponse.model_validate(response.json())

{plato_sdk_v2-2.7.8 → plato_sdk_v2-2.8.0}/plato/_generated/models/__init__.py

@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
-#   filename:  tmpy5rfux2_.json
-#   timestamp: 2026-01-29T20:47:53+00:00
+#   filename:  tmp2hcn27e0.json
+#   timestamp: 2026-01-29T22:45:52+00:00
 
 from __future__ import annotations
 
@@ -1158,6 +1158,14 @@ class EnvFromArtifact(BaseModel):
     """
 
 
+class RootfsStorageBackend(Enum):
+    sparse_s3 = "sparse-s3"
+    blockdiff = "blockdiff"
+    blockdiff_checkpoint = "blockdiff_checkpoint"
+    blockdiff_disk = "blockdiff_disk"
+    snapshot_store = "snapshot-store"
+
+
 class EnvFromSimulator(BaseModel):
     model_config = ConfigDict(
         extra="allow",
@@ -1929,6 +1937,11 @@ class NodeSessionNetworkConfig(BaseModel):
     """
 
 
+class DefaultRootfsStorageBackend(Enum):
+    sparse_s3 = "sparse-s3"
+    snapshot_store = "snapshot-store"
+
+
 class NodeSnapshotStoreConfig(BaseModel):
     model_config = ConfigDict(
         extra="allow",
@@ -1977,9 +1990,12 @@ class NodeSnapshotStoreConfig(BaseModel):
     """
     Local storage root for snapshot-store data.
     """
-    dedup_rootfs: Annotated[bool | None, Field(title="Dedup Rootfs")] = False
+    default_rootfs_storage_backend: Annotated[
+        DefaultRootfsStorageBackend | None,
+        Field(title="Default Rootfs Storage Backend"),
+    ] = DefaultRootfsStorageBackend.sparse_s3
     """
-    Enable rootfs-level dedup via snapshot-store FUSE mount instead of file copy.
+    Default rootfs storage backend. 'sparse-s3' uses S3 archives, 'snapshot-store' uses FUSE-based dedup.
     """
 
 
@@ -2334,6 +2350,38 @@ class ReleaseStatus(Enum):
     failed = "failed"
 
 
+class RemoveJobRequest(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+    )
+    job_id: Annotated[str, Field(title="Job Id")]
+    """
+    Job ID to remove from the session
+    """
+
+
+class RemoveJobResponse(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+    )
+    session_id: Annotated[str, Field(title="Session Id")]
+    """
+    Session ID the job was removed from
+    """
+    job_id: Annotated[str, Field(title="Job Id")]
+    """
+    Job ID that was removed
+    """
+    success: Annotated[bool, Field(title="Success")]
+    """
+    Whether the removal was successful
+    """
+    message: Annotated[str | None, Field(title="Message")] = None
+    """
+    Status message or error details
+    """
+
+
 class RepositoryResponse(BaseModel):
     model_config = ConfigDict(
         extra="allow",
@@ -4324,6 +4372,18 @@ class EnvFromResource(BaseModel):
     """
     Custom name for this environment
     """
+    docker_image_url: Annotated[str | None, Field(title="Docker Image Url")] = None
+    """
+    Custom Docker image URL (ECR). If not set, uses default from settings.
+    """
+    rootfs_storage_backend: Annotated[RootfsStorageBackend | None, Field(title="Rootfs Storage Backend")] = None
+    """
+    Storage backend for rootfs ('sparse-s3' or 'snapshot-store'). If not set, uses default.
+    """
+    upload_rootfs: Annotated[bool | None, Field(title="Upload Rootfs")] = True
+    """
+    Upload rootfs to S3/snapshot-store if not already cached. Set to False for one-off VMs.
+    """
 
 
 class ExecuteCommandResponse(BaseModel):

{plato_sdk_v2-2.7.8 → plato_sdk_v2-2.8.0}/plato/chronos/api/agents/get_agent_versions.py

@@ -7,7 +7,7 @@ from typing import Any
 import httpx
 
 from plato.chronos.errors import raise_for_status
-from plato.chronos.models import AgentVersionsResponse
+from plato.chronos.models import ChronosModelsAgentAgentVersionsResponse
 
 
 def _build_request_args(
@@ -32,7 +32,7 @@ def sync(
     client: httpx.Client,
     name: str,
     x_api_key: str | None = None,
-) -> AgentVersionsResponse:
+) -> ChronosModelsAgentAgentVersionsResponse:
     """Get all versions of an agent by name."""
 
     request_args = _build_request_args(
@@ -42,14 +42,14 @@ def sync(
 
     response = client.request(**request_args)
     raise_for_status(response)
-    return AgentVersionsResponse.model_validate(response.json())
+    return ChronosModelsAgentAgentVersionsResponse.model_validate(response.json())
 
 
 async def asyncio(
     client: httpx.AsyncClient,
     name: str,
     x_api_key: str | None = None,
-) -> AgentVersionsResponse:
+) -> ChronosModelsAgentAgentVersionsResponse:
     """Get all versions of an agent by name."""
 
     request_args = _build_request_args(
@@ -59,4 +59,4 @@ async def asyncio(
 
     response = await client.request(**request_args)
     raise_for_status(response)
-    return AgentVersionsResponse.model_validate(response.json())
+    return ChronosModelsAgentAgentVersionsResponse.model_validate(response.json())

{plato_sdk_v2-2.7.8 → plato_sdk_v2-2.8.0}/plato/chronos/api/agents/list_agents.py

@@ -7,7 +7,7 @@ from typing import Any
 import httpx
 
 from plato.chronos.errors import raise_for_status
-from plato.chronos.models import AgentListResponse
+from plato.chronos.models import ChronosModelsAgentAgentListResponse
 
 
 def _build_request_args(
@@ -30,7 +30,7 @@ def _build_request_args(
 def sync(
     client: httpx.Client,
     x_api_key: str | None = None,
-) -> AgentListResponse:
+) -> ChronosModelsAgentAgentListResponse:
     """List all agents for the org."""
 
     request_args = _build_request_args(
@@ -39,13 +39,13 @@ def sync(
 
     response = client.request(**request_args)
     raise_for_status(response)
-    return AgentListResponse.model_validate(response.json())
+    return ChronosModelsAgentAgentListResponse.model_validate(response.json())
 
 
 async def asyncio(
     client: httpx.AsyncClient,
     x_api_key: str | None = None,
-) -> AgentListResponse:
+) -> ChronosModelsAgentAgentListResponse:
     """List all agents for the org."""
 
     request_args = _build_request_args(
@@ -54,4 +54,4 @@ async def asyncio(
 
     response = await client.request(**request_args)
     raise_for_status(response)
-    return AgentListResponse.model_validate(response.json())
+    return ChronosModelsAgentAgentListResponse.model_validate(response.json())

{plato_sdk_v2-2.7.8 → plato_sdk_v2-2.8.0}/plato/chronos/api/registry/get_agent_versions_api_registry_agents__agent_name__versions_get.py

@@ -7,7 +7,7 @@ from typing import Any
 import httpx
 
 from plato.chronos.errors import raise_for_status
-from plato.chronos.models import ChronosApiRegistryAgentVersionsResponse
+from plato.chronos.models import AgentVersionsResponse
 
 
 def _build_request_args(
@@ -25,7 +25,7 @@ def _build_request_args(
 def sync(
     client: httpx.Client,
     agent_name: str,
-) -> ChronosApiRegistryAgentVersionsResponse:
+) -> AgentVersionsResponse:
     """Get versions for an agent from the registry."""
 
     request_args = _build_request_args(
@@ -34,13 +34,13 @@ def sync(
 
     response = client.request(**request_args)
     raise_for_status(response)
-    return ChronosApiRegistryAgentVersionsResponse.model_validate(response.json())
+    return AgentVersionsResponse.model_validate(response.json())
 
 
 async def asyncio(
     client: httpx.AsyncClient,
     agent_name: str,
-) -> ChronosApiRegistryAgentVersionsResponse:
+) -> AgentVersionsResponse:
     """Get versions for an agent from the registry."""
 
     request_args = _build_request_args(
@@ -49,4 +49,4 @@ async def asyncio(
 
     response = await client.request(**request_args)
     raise_for_status(response)
-    return ChronosApiRegistryAgentVersionsResponse.model_validate(response.json())
+    return AgentVersionsResponse.model_validate(response.json())

{plato_sdk_v2-2.7.8 → plato_sdk_v2-2.8.0}/plato/chronos/api/registry/list_registry_agents_api_registry_agents_get.py

@@ -7,7 +7,7 @@ from typing import Any
 import httpx
 
 from plato.chronos.errors import raise_for_status
-from plato.chronos.models import ChronosApiRegistryAgentListResponse
+from plato.chronos.models import AgentListResponse
 
 
 def _build_request_args() -> dict[str, Any]:
@@ -22,23 +22,23 @@ def _build_request_args() -> dict[str, Any]:
 
 def sync(
     client: httpx.Client,
-) -> ChronosApiRegistryAgentListResponse:
+) -> AgentListResponse:
     """List all agents from the registry with their ECR image URIs."""
 
     request_args = _build_request_args()
 
     response = client.request(**request_args)
     raise_for_status(response)
-    return ChronosApiRegistryAgentListResponse.model_validate(response.json())
+    return AgentListResponse.model_validate(response.json())
 
 
 async def asyncio(
     client: httpx.AsyncClient,
-) -> ChronosApiRegistryAgentListResponse:
+) -> AgentListResponse:
     """List all agents from the registry with their ECR image URIs."""
 
     request_args = _build_request_args()
 
     response = await client.request(**request_args)
     raise_for_status(response)
-    return ChronosApiRegistryAgentListResponse.model_validate(response.json())
+    return AgentListResponse.model_validate(response.json())

{plato_sdk_v2-2.7.8 → plato_sdk_v2-2.8.0}/plato/chronos/models/__init__.py

@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
-#   filename:  tmp9iosw1i3.json
-#   timestamp: 2026-01-29T20:31:32+00:00
+#   filename:  tmpi9d4hw2u.json
+#   timestamp: 2026-01-29T22:45:54+00:00
 
 from __future__ import annotations
 
@@ -30,6 +30,13 @@ class AgentInfo(BaseModel):
     image_uri: Annotated[str, Field(title="Image Uri")]
 
 
+class AgentListResponse(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+    )
+    agents: Annotated[list[AgentInfo], Field(title="Agents")]
+
+
 class AgentLookupResponse(BaseModel):
     model_config = ConfigDict(
         extra="allow",
@@ -71,14 +78,6 @@ class AgentVersionInfo(BaseModel):
     created_at: Annotated[AwareDatetime, Field(title="Created At")]
 
 
-class AgentVersionsResponse(BaseModel):
-    model_config = ConfigDict(
-        extra="allow",
-    )
-    name: Annotated[str, Field(title="Name")]
-    versions: Annotated[list[AgentVersionInfo], Field(title="Versions")]
-
-
 class AuthStatusResponse(BaseModel):
     model_config = ConfigDict(
         extra="allow",
@@ -566,13 +565,6 @@ class WorldVersionsResponse(BaseModel):
     versions: Annotated[list[str], Field(title="Versions")]
 
 
-class ChronosApiRegistryAgentListResponse(BaseModel):
-    model_config = ConfigDict(
-        extra="allow",
-    )
-    agents: Annotated[list[AgentInfo], Field(title="Agents")]
-
-
 class ChronosApiRegistryAgentSchemaResponse(BaseModel):
     model_config = ConfigDict(
         extra="allow",
@@ -592,12 +584,19 @@ class ChronosApiRegistryAgentVersionInfo(BaseModel):
     created_at: Annotated[str | None, Field(title="Created At")] = None
 
 
-class ChronosApiRegistryAgentVersionsResponse(BaseModel):
+class ChronosModelsAgentAgentListResponse(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+    )
+    agents: Annotated[list[AgentResponse], Field(title="Agents")]
+
+
+class ChronosModelsAgentAgentVersionsResponse(BaseModel):
     model_config = ConfigDict(
         extra="allow",
     )
     name: Annotated[str, Field(title="Name")]
-    versions: Annotated[list[ChronosApiRegistryAgentVersionInfo], Field(title="Versions")]
+    versions: Annotated[list[AgentVersionInfo], Field(title="Versions")]
 
 
 class ChronosModelsSessionWorldInfo(BaseModel):
@@ -610,11 +609,12 @@ class ChronosModelsSessionWorldInfo(BaseModel):
     config_schema: Annotated[dict[str, Any] | None, Field(title="Config Schema")] = None
 
 
-class AgentListResponse(BaseModel):
+class AgentVersionsResponse(BaseModel):
     model_config = ConfigDict(
         extra="allow",
     )
-    agents: Annotated[list[AgentResponse], Field(title="Agents")]
+    name: Annotated[str, Field(title="Name")]
+    versions: Annotated[list[ChronosApiRegistryAgentVersionInfo], Field(title="Versions")]
 
 
 class CreatorsListResponse(BaseModel):

{plato_sdk_v2-2.7.8 → plato_sdk_v2-2.8.0}/plato/v2/async_/session.py

@@ -23,6 +23,8 @@ if TYPE_CHECKING:
 
 from plato._generated.api.v2.jobs import get_flows as jobs_get_flows
 from plato._generated.api.v2.jobs import public_url as jobs_public_url
+from plato._generated.api.v2.jobs import wait_for_ready as jobs_wait_for_ready
+from plato._generated.api.v2.sessions import add_job as sessions_add_job
 from plato._generated.api.v2.sessions import close as sessions_close
 from plato._generated.api.v2.sessions import connect_network as sessions_connect_network
 from plato._generated.api.v2.sessions import disk_snapshot as sessions_disk_snapshot
@@ -31,6 +33,7 @@ from plato._generated.api.v2.sessions import execute as sessions_execute
 from plato._generated.api.v2.sessions import get_public_url as sessions_get_public_url
 from plato._generated.api.v2.sessions import heartbeat as sessions_heartbeat
 from plato._generated.api.v2.sessions import make as sessions_make
+from plato._generated.api.v2.sessions import remove_job as sessions_remove_job
 from plato._generated.api.v2.sessions import reset as sessions_reset
 from plato._generated.api.v2.sessions import set_date as sessions_set_date
 from plato._generated.api.v2.sessions import setup_sandbox as sessions_setup_sandbox
@@ -39,6 +42,7 @@ from plato._generated.api.v2.sessions import snapshot_store as sessions_snapshot
 from plato._generated.api.v2.sessions import state as sessions_state
 from plato._generated.api.v2.sessions import wait_for_ready as sessions_wait_for_ready
 from plato._generated.models import (
+    AddJobRequest,
     AppApiV2SchemasSessionCreateSnapshotRequest,
     AppApiV2SchemasSessionCreateSnapshotResponse,
     AppApiV2SchemasSessionEvaluateResponse,
@@ -49,10 +53,12 @@ from plato._generated.models import (
     CreateDiskSnapshotResponse,
     CreateSessionFromEnvs,
     CreateSessionFromTask,
+    EnvironmentContext,
     Envs,
     ExecuteCommandRequest,
     ExecuteCommandResponse,
     Flow,
+    RemoveJobRequest,
     ResetSessionRequest,
     ResetSessionResponse,
     RunSessionSource,
@@ -780,6 +786,158 @@ class Session:
 
         return result
 
+    async def add_env(
+        self,
+        env: EnvFromSimulator | EnvFromArtifact | EnvFromResource,
+        *,
+        timeout: int = 1800,
+        heartbeat_timeout: int | None = None,
+        wait_for_ready: bool = True,
+    ) -> Environment:
+        """Add a new environment to this session.
+
+        The new environment will:
+        1. Become part of the session's job group
+        2. Be matched to an available VM via the resource matcher
+        3. Automatically join the session's WireGuard network if one exists
+
+        Args:
+            env: Environment configuration (from Env.simulator(), Env.artifact(), or Env.resource()).
+            timeout: VM timeout in seconds (default: 1800).
+            heartbeat_timeout: Per-VM heartbeat timeout. None=use default (300s), 0=disabled.
+            wait_for_ready: If True, wait for the job to be ready before returning (default: True).
+
+        Returns:
+            Environment object for the new job.
+
+        Raises:
+            RuntimeError: If session is closed or job creation fails.
+            TimeoutError: If wait_for_ready=True and the job doesn't become ready within timeout.
+        """
+        self._check_closed()
+
+        # Auto-generate alias if not set
+        if env.alias is None:
+            existing_aliases = {e.alias for e in self.envs}
+            unique_alias = f"env-{uuid.uuid4().hex[:8]}"
+            while unique_alias in existing_aliases:
+                unique_alias = f"env-{uuid.uuid4().hex[:8]}"
+            env.alias = unique_alias
+
+        # Build request
+        request = AddJobRequest(
+            env=env,
+            timeout=timeout,
+            heartbeat_timeout=heartbeat_timeout,
+        )
+
+        # Call the add_job API
+        response = await sessions_add_job.asyncio(
+            client=self._http,
+            session_id=self.session_id,
+            body=request,
+            x_api_key=self._api_key,
+        )
+
+        # Check for failures
+        if not response.env.success:
+            raise RuntimeError(f"Failed to add job: {response.env.error}")
+
+        if not response.env.job_id:
+            raise RuntimeError("Backend did not return job_id for new environment")
+
+        job_id = response.env.job_id
+
+        # Wait for the job to be ready if requested
+        if wait_for_ready:
+            ready_response = await jobs_wait_for_ready.asyncio(
+                client=self._http,
+                job_id=job_id,
+                timeout=timeout,
+                x_api_key=self._api_key,
+            )
+
+            if not ready_response.ready:
+                error = ready_response.error or "Unknown error"
+                raise TimeoutError(f"Job {job_id} did not become ready: {error}")
+
+        # Update internal context with the new environment
+        new_env_context = EnvironmentContext(
+            job_id=job_id,
+            alias=env.alias,
+            artifact_id=response.env.artifact_id,
+            simulator=getattr(env, "simulator", None),
+        )
+
+        # Add to context's envs list
+        if self._context.envs is None:
+            self._context.envs = []
+        self._context.envs.append(new_env_context)
+
+        # Reset cached envs to force rebuild
+        self._envs = None
+
+        # Create and return the Environment object
+        new_environment = Environment(
+            session=self,
+            job_id=job_id,
+            alias=env.alias,
+            artifact_id=response.env.artifact_id,
+        )
+
+        logger.info(f"Added job {job_id} (alias={env.alias}) to session {self.session_id}")
+        return new_environment
+
+    async def remove_env(self, env: Environment | str) -> None:
+        """Remove an environment from this session.
+
+        This will:
+        1. Remove the job from the session's network (if connected)
+        2. Shut down the VM associated with the job
+        3. Cancel the job in the system
+
+        Args:
+            env: Environment object or alias string to remove.
+
+        Raises:
+            RuntimeError: If session is closed or removal fails.
+            ValueError: If environment not found in session.
+        """
+        self._check_closed()
+
+        # Resolve to job_id
+        if isinstance(env, str):
+            # Find by alias
+            found_env = self.get_env(env)
+            if not found_env:
+                raise ValueError(f"Environment with alias '{env}' not found in session")
+            job_id = found_env.job_id
+            alias = env
+        else:
+            job_id = env.job_id
+            alias = env.alias
+
+        # Call the remove_job API
+        request = RemoveJobRequest(job_id=job_id)
+        response = await sessions_remove_job.asyncio(
+            client=self._http,
+            session_id=self.session_id,
+            body=request,
+            x_api_key=self._api_key,
+        )
+
+        if not response.success:
+            raise RuntimeError(f"Failed to remove job {job_id}")
+
+        # Update internal context - remove the environment
+        if self._context.envs:
+            self._context.envs = [e for e in self._context.envs if e.job_id != job_id]
+
+        # Reset cached envs to force rebuild
+        self._envs = None
+
+        logger.info(f"Removed job {job_id} (alias={alias}) from session {self.session_id}")
+
     async def cleanup_databases(self) -> SessionCleanupResult:
         """Clean up database audit logs for all environments.