plato-sdk-v2 2.0.7__py3-none-any.whl

plato/__init__.py

@@ -0,0 +1,28 @@
+# Plato SDK
+#
+# v1: Legacy SDK (deprecated)
+# v2: New SDK with separate sync/async modules
+#
+# Usage (v2 - recommended):
+#   from plato.v2 import AsyncPlato, Plato, Env
+#
+# Usage (v1 - deprecated):
+#   from plato import Plato, SyncPlato
+
+from plato import v2 as v2
+
+__all__ = ["v2"]
+
+
+def __getattr__(name: str):
+    """Lazy import to avoid loading all modules at once."""
+    if name in ("Plato", "SyncPlato", "PlatoTask", "v1"):
+        try:
+            from plato import v1
+
+            if name == "v1":
+                return v1
+            return getattr(v1, name)
+        except ImportError:
+            raise AttributeError(f"module 'plato' has no attribute '{name}' (v1 unavailable)")
+    raise AttributeError(f"module 'plato' has no attribute '{name}'")

plato/_generated/__init__.py

@@ -0,0 +1,37 @@
+"""Plato API SDK - v0.14.0"""
+
+from . import api, errors, models
+from .client import AsyncClient, Client
+from .errors import (
+    APIError,
+    BadRequestError,
+    ConflictError,
+    ForbiddenError,
+    InternalServerError,
+    NotFoundError,
+    RateLimitError,
+    ServiceUnavailableError,
+    UnauthorizedError,
+    UnprocessableEntityError,
+)
+
+__all__ = [
+    # Clients
+    "Client",
+    "AsyncClient",
+    # Modules
+    "api",
+    "models",
+    "errors",
+    # Error types for convenience
+    "APIError",
+    "BadRequestError",
+    "UnauthorizedError",
+    "ForbiddenError",
+    "NotFoundError",
+    "ConflictError",
+    "UnprocessableEntityError",
+    "RateLimitError",
+    "InternalServerError",
+    "ServiceUnavailableError",
+]

plato/_generated/api/__init__.py

@@ -0,0 +1,8 @@
+"""Generated API modules."""
+
+from . import v1, v2
+
+__all__ = [
+    "v1",
+    "v2",
+]

plato/_generated/api/v1/__init__.py

@@ -0,0 +1,31 @@
+"""API version module."""
+
+from . import (
+    agent_artifacts,
+    cluster,
+    env,
+    evals,
+    gitea,
+    jobs,
+    organization,
+    queue,
+    sandbox,
+    session,
+    simulator,
+    testcases,
+)
+
+__all__ = [
+    "agent_artifacts",
+    "cluster",
+    "env",
+    "evals",
+    "gitea",
+    "jobs",
+    "organization",
+    "queue",
+    "sandbox",
+    "session",
+    "simulator",
+    "testcases",
+]

plato/_generated/api/v1/agent_artifacts/__init__.py

@@ -0,0 +1,10 @@
+"""API endpoints."""
+
+from . import archive_agent_artifact, create_agent_artifact, get_agent_artifact_by_public_id, get_agent_artifacts
+
+__all__ = [
+    "get_agent_artifacts",
+    "create_agent_artifact",
+    "get_agent_artifact_by_public_id",
+    "archive_agent_artifact",
+]

plato/_generated/api/v1/agent_artifacts/archive_agent_artifact.py

@@ -0,0 +1,68 @@
+"""Archive Agent Artifact"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from plato._generated.errors import raise_for_status
+
+
+def _build_request_args(
+    artifact_id: str,
+    authorization: str | None = None,
+    x_api_key: str | None = None,
+) -> dict[str, Any]:
+    """Build request arguments."""
+    url = f"/api/v1/agent-artifacts/{artifact_id}"
+
+    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": "DELETE",
+        "url": url,
+        "headers": headers,
+    }
+
+
+def sync(
+    client: httpx.Client,
+    artifact_id: str,
+    authorization: str | None = None,
+    x_api_key: str | None = None,
+) -> Any:
+    """Archive Agent Artifact"""
+
+    request_args = _build_request_args(
+        artifact_id=artifact_id,
+        authorization=authorization,
+        x_api_key=x_api_key,
+    )
+
+    response = client.request(**request_args)
+    raise_for_status(response)
+    return response.json()
+
+
+async def asyncio(
+    client: httpx.AsyncClient,
+    artifact_id: str,
+    authorization: str | None = None,
+    x_api_key: str | None = None,
+) -> Any:
+    """Archive Agent Artifact"""
+
+    request_args = _build_request_args(
+        artifact_id=artifact_id,
+        authorization=authorization,
+        x_api_key=x_api_key,
+    )
+
+    response = await client.request(**request_args)
+    raise_for_status(response)
+    return response.json()

plato/_generated/api/v1/agent_artifacts/create_agent_artifact.py

@@ -0,0 +1,70 @@
+"""Create Agent Artifact"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from plato._generated.errors import raise_for_status
+from plato._generated.models import CreateAgentArtifactRequest
+
+
+def _build_request_args(
+    body: CreateAgentArtifactRequest,
+    authorization: str | None = None,
+    x_api_key: str | None = None,
+) -> dict[str, Any]:
+    """Build request arguments."""
+    url = "/api/v1/agent-artifacts/"
+
+    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,
+    body: CreateAgentArtifactRequest,
+    authorization: str | None = None,
+    x_api_key: str | None = None,
+) -> Any:
+    """Create Agent Artifact"""
+
+    request_args = _build_request_args(
+        body=body,
+        authorization=authorization,
+        x_api_key=x_api_key,
+    )
+
+    response = client.request(**request_args)
+    raise_for_status(response)
+    return response.json()
+
+
+async def asyncio(
+    client: httpx.AsyncClient,
+    body: CreateAgentArtifactRequest,
+    authorization: str | None = None,
+    x_api_key: str | None = None,
+) -> Any:
+    """Create Agent Artifact"""
+
+    request_args = _build_request_args(
+        body=body,
+        authorization=authorization,
+        x_api_key=x_api_key,
+    )
+
+    response = await client.request(**request_args)
+    raise_for_status(response)
+    return response.json()

plato/_generated/api/v1/agent_artifacts/get_agent_artifact_by_public_id.py

@@ -0,0 +1,68 @@
+"""Get Agent Artifact By Public Id"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from plato._generated.errors import raise_for_status
+
+
+def _build_request_args(
+    public_id: str,
+    authorization: str | None = None,
+    x_api_key: str | None = None,
+) -> dict[str, Any]:
+    """Build request arguments."""
+    url = f"/api/v1/agent-artifacts/{public_id}"
+
+    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": "GET",
+        "url": url,
+        "headers": headers,
+    }
+
+
+def sync(
+    client: httpx.Client,
+    public_id: str,
+    authorization: str | None = None,
+    x_api_key: str | None = None,
+) -> Any:
+    """Get Agent Artifact By Public Id"""
+
+    request_args = _build_request_args(
+        public_id=public_id,
+        authorization=authorization,
+        x_api_key=x_api_key,
+    )
+
+    response = client.request(**request_args)
+    raise_for_status(response)
+    return response.json()
+
+
+async def asyncio(
+    client: httpx.AsyncClient,
+    public_id: str,
+    authorization: str | None = None,
+    x_api_key: str | None = None,
+) -> Any:
+    """Get Agent Artifact By Public Id"""
+
+    request_args = _build_request_args(
+        public_id=public_id,
+        authorization=authorization,
+        x_api_key=x_api_key,
+    )
+
+    response = await client.request(**request_args)
+    raise_for_status(response)
+    return response.json()

plato/_generated/api/v1/agent_artifacts/get_agent_artifacts.py

@@ -0,0 +1,63 @@
+"""Get Agent Artifacts"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from plato._generated.errors import raise_for_status
+
+
+def _build_request_args(
+    authorization: str | None = None,
+    x_api_key: str | None = None,
+) -> dict[str, Any]:
+    """Build request arguments."""
+    url = "/api/v1/agent-artifacts/"
+
+    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": "GET",
+        "url": url,
+        "headers": headers,
+    }
+
+
+def sync(
+    client: httpx.Client,
+    authorization: str | None = None,
+    x_api_key: str | None = None,
+) -> Any:
+    """Get Agent Artifacts"""
+
+    request_args = _build_request_args(
+        authorization=authorization,
+        x_api_key=x_api_key,
+    )
+
+    response = client.request(**request_args)
+    raise_for_status(response)
+    return response.json()
+
+
+async def asyncio(
+    client: httpx.AsyncClient,
+    authorization: str | None = None,
+    x_api_key: str | None = None,
+) -> Any:
+    """Get Agent Artifacts"""
+
+    request_args = _build_request_args(
+        authorization=authorization,
+        x_api_key=x_api_key,
+    )
+
+    response = await client.request(**request_args)
+    raise_for_status(response)
+    return response.json()

plato/_generated/api/v1/cluster/__init__.py

@@ -0,0 +1,21 @@
+"""API endpoints."""
+
+from . import (
+    cleanup_stale_vms,
+    get_dispatchers,
+    get_nodes_status,
+    get_snapshot_lineage,
+    get_snapshots_status,
+    pause_resume_dispatchers,
+    prefetch_snapshot,
+)
+
+__all__ = [
+    "prefetch_snapshot",
+    "pause_resume_dispatchers",
+    "get_snapshots_status",
+    "get_snapshot_lineage",
+    "get_nodes_status",
+    "get_dispatchers",
+    "cleanup_stale_vms",
+]

plato/_generated/api/v1/cluster/cleanup_stale_vms.py

@@ -0,0 +1,87 @@
+"""Cleanup Stale Vms"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from plato._generated.errors import raise_for_status
+from plato._generated.models import CleanupStaleVMsRequest, CleanupStaleVMsResponse
+
+
+def _build_request_args(
+    body: CleanupStaleVMsRequest,
+) -> dict[str, Any]:
+    """Build request arguments."""
+    url = "/api/v1/cluster/cleanup/stale-vms"
+
+    return {
+        "method": "POST",
+        "url": url,
+        "json": body.model_dump(mode="json", exclude_none=True),
+    }
+
+
+def sync(
+    client: httpx.Client,
+    body: CleanupStaleVMsRequest,
+) -> CleanupStaleVMsResponse:
+    """Clean up stale VMs that haven't sent heartbeats recently.
+
+    Requires internal service authentication.
+
+    A VM is considered stale if its last_server_heartbeat is older than
+    the specified threshold (default: 10 minutes).
+
+    This endpoint will:
+    1. Scan all VM records in Redis
+    2. Identify VMs with stale heartbeats
+    3. Send forced shutdown requests to each stale VM
+    4. Delete the VM records from Redis
+
+    Args:
+        cleanup_request: Cleanup parameters (threshold)
+
+    Returns:
+        CleanupStaleVMsResponse with cleanup results"""
+
+    request_args = _build_request_args(
+        body=body,
+    )
+
+    response = client.request(**request_args)
+    raise_for_status(response)
+    return CleanupStaleVMsResponse.model_validate(response.json())
+
+
+async def asyncio(
+    client: httpx.AsyncClient,
+    body: CleanupStaleVMsRequest,
+) -> CleanupStaleVMsResponse:
+    """Clean up stale VMs that haven't sent heartbeats recently.
+
+    Requires internal service authentication.
+
+    A VM is considered stale if its last_server_heartbeat is older than
+    the specified threshold (default: 10 minutes).
+
+    This endpoint will:
+    1. Scan all VM records in Redis
+    2. Identify VMs with stale heartbeats
+    3. Send forced shutdown requests to each stale VM
+    4. Delete the VM records from Redis
+
+    Args:
+        cleanup_request: Cleanup parameters (threshold)
+
+    Returns:
+        CleanupStaleVMsResponse with cleanup results"""
+
+    request_args = _build_request_args(
+        body=body,
+    )
+
+    response = await client.request(**request_args)
+    raise_for_status(response)
+    return CleanupStaleVMsResponse.model_validate(response.json())

plato/_generated/api/v1/cluster/get_dispatchers.py

@@ -0,0 +1,50 @@
+"""Get Dispatchers"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from plato._generated.errors import raise_for_status
+from plato._generated.models import DispatchersResponse
+
+
+def _build_request_args() -> dict[str, Any]:
+    """Build request arguments."""
+    url = "/api/v1/cluster/dispatchers"
+
+    return {
+        "method": "GET",
+        "url": url,
+    }
+
+
+def sync(
+    client: httpx.Client,
+) -> DispatchersResponse:
+    """Get all Firecracker dispatchers with their status and VM counts.
+
+    Returns:
+        DispatchersResponse with all dispatcher information"""
+
+    request_args = _build_request_args()
+
+    response = client.request(**request_args)
+    raise_for_status(response)
+    return DispatchersResponse.model_validate(response.json())
+
+
+async def asyncio(
+    client: httpx.AsyncClient,
+) -> DispatchersResponse:
+    """Get all Firecracker dispatchers with their status and VM counts.
+
+    Returns:
+        DispatchersResponse with all dispatcher information"""
+
+    request_args = _build_request_args()
+
+    response = await client.request(**request_args)
+    raise_for_status(response)
+    return DispatchersResponse.model_validate(response.json())

plato/_generated/api/v1/cluster/get_nodes_status.py

@@ -0,0 +1,62 @@
+"""Get Nodes Status"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from plato._generated.errors import raise_for_status
+from plato._generated.models import NodeStatusResponse
+
+
+def _build_request_args() -> dict[str, Any]:
+    """Build request arguments."""
+    url = "/api/v1/cluster/nodes/status"
+
+    return {
+        "method": "GET",
+        "url": url,
+    }
+
+
+def sync(
+    client: httpx.Client,
+) -> NodeStatusResponse:
+    """Get node/VM status across all Firecracker worker instances.
+
+    Returns detailed information about:
+    - Total instances with VMs
+    - Total active VMs across all instances
+    - Total capacity across all instances
+    - Per-instance VM counts by state
+
+    Returns:
+        NodeStatusResponse with comprehensive node/VM status"""
+
+    request_args = _build_request_args()
+
+    response = client.request(**request_args)
+    raise_for_status(response)
+    return NodeStatusResponse.model_validate(response.json())
+
+
+async def asyncio(
+    client: httpx.AsyncClient,
+) -> NodeStatusResponse:
+    """Get node/VM status across all Firecracker worker instances.
+
+    Returns detailed information about:
+    - Total instances with VMs
+    - Total active VMs across all instances
+    - Total capacity across all instances
+    - Per-instance VM counts by state
+
+    Returns:
+        NodeStatusResponse with comprehensive node/VM status"""
+
+    request_args = _build_request_args()
+
+    response = await client.request(**request_args)
+    raise_for_status(response)
+    return NodeStatusResponse.model_validate(response.json())

plato/_generated/api/v1/cluster/get_snapshot_lineage.py

@@ -0,0 +1,78 @@
+"""Get Snapshot Lineage"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from plato._generated.errors import raise_for_status
+from plato._generated.models import ArtifactLineageResponse, SnapshotConfig
+
+
+def _build_request_args(
+    artifact_id: str,
+    include_full_details: bool | None = None,
+) -> dict[str, Any]:
+    """Build request arguments."""
+    url = "/api/v1/cluster/snapshots/lineage"
+
+    params: dict[str, Any] = {}
+    if artifact_id is not None:
+        params["artifact_id"] = artifact_id
+    if include_full_details is not None:
+        params["include_full_details"] = include_full_details
+
+    return {
+        "method": "GET",
+        "url": url,
+        "params": params,
+    }
+
+
+def sync(
+    client: httpx.Client,
+    artifact_id: str,
+    include_full_details: bool | None = None,
+) -> SnapshotConfig | ArtifactLineageResponse:
+    """Build and return the full snapshot lineage for a given artifact ID.
+
+    This works for both regular snapshots and blockdiff checkpoints.
+
+    Args:
+        artifact_id: The artifact ID to build lineage for
+        include_full_details: If True, returns full artifact details for migration purposes.
+                             If False (default), returns minimal SnapshotConfig for VM operations."""
+
+    request_args = _build_request_args(
+        artifact_id=artifact_id,
+        include_full_details=include_full_details,
+    )
+
+    response = client.request(**request_args)
+    raise_for_status(response)
+    return response.json()
+
+
+async def asyncio(
+    client: httpx.AsyncClient,
+    artifact_id: str,
+    include_full_details: bool | None = None,
+) -> SnapshotConfig | ArtifactLineageResponse:
+    """Build and return the full snapshot lineage for a given artifact ID.
+
+    This works for both regular snapshots and blockdiff checkpoints.
+
+    Args:
+        artifact_id: The artifact ID to build lineage for
+        include_full_details: If True, returns full artifact details for migration purposes.
+                             If False (default), returns minimal SnapshotConfig for VM operations."""
+
+    request_args = _build_request_args(
+        artifact_id=artifact_id,
+        include_full_details=include_full_details,
+    )
+
+    response = await client.request(**request_args)
+    raise_for_status(response)
+    return response.json()