plato-sdk-v2 2.5.0__py3-none-any.whl → 2.6.0__py3-none-any.whl

plato/chronos/api/checkpoints/preview_checkpoint.py

@@ -0,0 +1,74 @@
+"""Preview Checkpoint"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from plato.chronos.errors import raise_for_status
+from plato.chronos.models import PreviewResponse
+
+
+def _build_request_args(
+    checkpoint_id: str,
+) -> dict[str, Any]:
+    """Build request arguments."""
+    url = f"/api/checkpoints/{checkpoint_id}/preview"
+
+    return {
+        "method": "POST",
+        "url": url,
+    }
+
+
+def sync(
+    client: httpx.Client,
+    checkpoint_id: str,
+) -> PreviewResponse:
+    """Launch a preview session from a checkpoint.
+
+    Creates an ephemeral Plato session using the checkpoint's artifact IDs.
+    Returns serialized session data that can be used with Session.load()
+    to send heartbeats and eventually close the session.
+
+    The frontend should:
+    1. Call this endpoint to get the serialized session
+    2. Use Session.load(serialized_session) to restore the session
+    3. Call session.start_heartbeat() to keep envs alive
+    4. Display env URLs/job IDs in a modal
+    5. Call session.stop_heartbeat() and session.close() when done"""
+
+    request_args = _build_request_args(
+        checkpoint_id=checkpoint_id,
+    )
+
+    response = client.request(**request_args)
+    raise_for_status(response)
+    return PreviewResponse.model_validate(response.json())
+
+
+async def asyncio(
+    client: httpx.AsyncClient,
+    checkpoint_id: str,
+) -> PreviewResponse:
+    """Launch a preview session from a checkpoint.
+
+    Creates an ephemeral Plato session using the checkpoint's artifact IDs.
+    Returns serialized session data that can be used with Session.load()
+    to send heartbeats and eventually close the session.
+
+    The frontend should:
+    1. Call this endpoint to get the serialized session
+    2. Use Session.load(serialized_session) to restore the session
+    3. Call session.start_heartbeat() to keep envs alive
+    4. Display env URLs/job IDs in a modal
+    5. Call session.stop_heartbeat() and session.close() when done"""
+
+    request_args = _build_request_args(
+        checkpoint_id=checkpoint_id,
+    )
+
+    response = await client.request(**request_args)
+    raise_for_status(response)
+    return PreviewResponse.model_validate(response.json())

plato/chronos/api/events/__init__.py

@@ -0,0 +1,8 @@
+"""API endpoints."""
+
+from . import get_session_event, list_session_events
+
+__all__ = [
+    "list_session_events",
+    "get_session_event",
+]

plato/chronos/api/events/get_session_event.py

@@ -0,0 +1,68 @@
+"""Get Event"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from plato.chronos.errors import raise_for_status
+from plato.chronos.models import OTelSpan
+
+
+def _build_request_args(
+    span_id: str,
+    x_api_key: str | None = None,
+) -> dict[str, Any]:
+    """Build request arguments."""
+    url = f"/api/events/{span_id}"
+
+    headers: dict[str, str] = {}
+    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,
+    span_id: str,
+    x_api_key: str | None = None,
+) -> OTelSpan:
+    """Get a span by ID.
+
+    Note: This requires scanning all batches, so it's not efficient.
+    Consider caching or indexing spans if this is used frequently."""
+
+    request_args = _build_request_args(
+        span_id=span_id,
+        x_api_key=x_api_key,
+    )
+
+    response = client.request(**request_args)
+    raise_for_status(response)
+    return OTelSpan.model_validate(response.json())
+
+
+async def asyncio(
+    client: httpx.AsyncClient,
+    span_id: str,
+    x_api_key: str | None = None,
+) -> OTelSpan:
+    """Get a span by ID.
+
+    Note: This requires scanning all batches, so it's not efficient.
+    Consider caching or indexing spans if this is used frequently."""
+
+    request_args = _build_request_args(
+        span_id=span_id,
+        x_api_key=x_api_key,
+    )
+
+    response = await client.request(**request_args)
+    raise_for_status(response)
+    return OTelSpan.model_validate(response.json())

plato/chronos/api/events/list_session_events.py

@@ -0,0 +1,62 @@
+"""List Events For Session"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from plato.chronos.errors import raise_for_status
+from plato.chronos.models import OTelSpanListResponse
+
+
+def _build_request_args(
+    session_public_id: str,
+    x_api_key: str | None = None,
+) -> dict[str, Any]:
+    """Build request arguments."""
+    url = f"/api/events/session/{session_public_id}"
+
+    headers: dict[str, str] = {}
+    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,
+    session_public_id: str,
+    x_api_key: str | None = None,
+) -> OTelSpanListResponse:
+    """List all OTel spans for a session."""
+
+    request_args = _build_request_args(
+        session_public_id=session_public_id,
+        x_api_key=x_api_key,
+    )
+
+    response = client.request(**request_args)
+    raise_for_status(response)
+    return OTelSpanListResponse.model_validate(response.json())
+
+
+async def asyncio(
+    client: httpx.AsyncClient,
+    session_public_id: str,
+    x_api_key: str | None = None,
+) -> OTelSpanListResponse:
+    """List all OTel spans for a session."""
+
+    request_args = _build_request_args(
+        session_public_id=session_public_id,
+        x_api_key=x_api_key,
+    )
+
+    response = await client.request(**request_args)
+    raise_for_status(response)
+    return OTelSpanListResponse.model_validate(response.json())

plato/chronos/api/jobs/launch_job.py

@@ -34,7 +34,10 @@ def sync(
     body: LaunchJobRequest,
     x_api_key: str | None = None,
 ) -> LaunchJobResponse:
-    """Launch a new Chronos job."""
+    """Launch a new Chronos job.
+
+    The world.config is passed directly to the world runner.
+    Agent and secret configs should be embedded in world.config."""
 
     request_args = _build_request_args(
         body=body,
@@ -51,7 +54,10 @@ async def asyncio(
     body: LaunchJobRequest,
     x_api_key: str | None = None,
 ) -> LaunchJobResponse:
-    """Launch a new Chronos job."""
+    """Launch a new Chronos job.
+
+    The world.config is passed directly to the world runner.
+    Agent and secret configs should be embedded in world.config."""
 
     request_args = _build_request_args(
         body=body,

plato/chronos/api/otel/__init__.py

@@ -0,0 +1,8 @@
+"""API endpoints."""
+
+from . import get_session_traces_api_otel_sessions__session_id__traces_get, receive_traces_api_otel_v1_traces_post
+
+__all__ = [
+    "receive_traces_api_otel_v1_traces_post",
+    "get_session_traces_api_otel_sessions__session_id__traces_get",
+]

plato/chronos/api/otel/get_session_traces_api_otel_sessions__session_id__traces_get.py

@@ -0,0 +1,56 @@
+"""Get Session Traces"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from plato.chronos.errors import raise_for_status
+from plato.chronos.models import OTelTraceResponse
+
+
+def _build_request_args(
+    session_id: str,
+) -> dict[str, Any]:
+    """Build request arguments."""
+    url = f"/api/otel/sessions/{session_id}/traces"
+
+    return {
+        "method": "GET",
+        "url": url,
+    }
+
+
+def sync(
+    client: httpx.Client,
+    session_id: str,
+) -> OTelTraceResponse:
+    """Get all parsed traces for a session.
+
+    Returns spans parsed from stored OTLP batches, suitable for UI rendering."""
+
+    request_args = _build_request_args(
+        session_id=session_id,
+    )
+
+    response = client.request(**request_args)
+    raise_for_status(response)
+    return OTelTraceResponse.model_validate(response.json())
+
+
+async def asyncio(
+    client: httpx.AsyncClient,
+    session_id: str,
+) -> OTelTraceResponse:
+    """Get all parsed traces for a session.
+
+    Returns spans parsed from stored OTLP batches, suitable for UI rendering."""
+
+    request_args = _build_request_args(
+        session_id=session_id,
+    )
+
+    response = await client.request(**request_args)
+    raise_for_status(response)
+    return OTelTraceResponse.model_validate(response.json())

plato/chronos/api/otel/receive_traces_api_otel_v1_traces_post.py

@@ -0,0 +1,49 @@
+"""Receive Traces"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from plato.chronos.errors import raise_for_status
+
+
+def _build_request_args() -> dict[str, Any]:
+    """Build request arguments."""
+    url = "/api/otel/v1/traces"
+
+    return {
+        "method": "POST",
+        "url": url,
+    }
+
+
+def sync(
+    client: httpx.Client,
+) -> dict[str, Any]:
+    """Receive OTLP trace data (JSON or protobuf) and store as JSON.
+
+    Resource attributes must include:
+    - plato.session.id: The Chronos session ID"""
+
+    request_args = _build_request_args()
+
+    response = client.request(**request_args)
+    raise_for_status(response)
+    return response.json()
+
+
+async def asyncio(
+    client: httpx.AsyncClient,
+) -> dict[str, Any]:
+    """Receive OTLP trace data (JSON or protobuf) and store as JSON.
+
+    Resource attributes must include:
+    - plato.session.id: The Chronos session ID"""
+
+    request_args = _build_request_args()
+
+    response = await client.request(**request_args)
+    raise_for_status(response)
+    return response.json()

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/chronos/api/runtimes/__init__.py

@@ -1,11 +1,12 @@
 """API endpoints."""
 
-from . import create_runtime, delete_runtime, get_runtime, list_runtimes, test_runtime
+from . import create_runtime, delete_runtime, get_runtime, get_runtime_logs, list_runtimes, test_runtime
 
 __all__ = [
     "list_runtimes",
     "create_runtime",
     "get_runtime",
     "delete_runtime",
+    "get_runtime_logs",
     "test_runtime",
 ]

plato/chronos/api/runtimes/get_runtime_logs.py

@@ -0,0 +1,61 @@
+"""Get Runtime Logs"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from plato.chronos.errors import raise_for_status
+
+
+def _build_request_args(
+    artifact_id: str,
+    x_api_key: str | None = None,
+) -> dict[str, Any]:
+    """Build request arguments."""
+    url = f"/api/runtimes/{artifact_id}/logs"
+
+    headers: dict[str, str] = {}
+    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,
+    artifact_id: str,
+    x_api_key: str | None = None,
+) -> dict[str, Any]:
+    """Get live build logs for a runtime by connecting to the VM."""
+
+    request_args = _build_request_args(
+        artifact_id=artifact_id,
+        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,
+    x_api_key: str | None = None,
+) -> dict[str, Any]:
+    """Get live build logs for a runtime by connecting to the VM."""
+
+    request_args = _build_request_args(
+        artifact_id=artifact_id,
+        x_api_key=x_api_key,
+    )
+
+    response = await client.request(**request_args)
+    raise_for_status(response)
+    return response.json()

plato/chronos/api/sessions/__init__.py

@@ -1,10 +1,33 @@
 """API endpoints."""
 
-from . import get_session, get_session_logs, get_session_logs_download, list_sessions
+from . import (
+    close_session,
+    complete_session,
+    create_session,
+    get_session,
+    get_session_bash_logs_download,
+    get_session_envs,
+    get_session_live_logs,
+    get_session_logs,
+    get_session_logs_download,
+    get_session_status,
+    list_sessions,
+    list_tags,
+    update_session_tags,
+)
 
 __all__ = [
     "list_sessions",
+    "create_session",
+    "list_tags",
     "get_session",
+    "get_session_status",
+    "update_session_tags",
+    "complete_session",
     "get_session_logs",
     "get_session_logs_download",
+    "get_session_bash_logs_download",
+    "get_session_envs",
+    "get_session_live_logs",
+    "close_session",
 ]

plato/chronos/api/sessions/close_session.py

@@ -0,0 +1,66 @@
+"""Close Session"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from plato.chronos.errors import raise_for_status
+from plato.chronos.models import CloseSessionResponse
+
+
+def _build_request_args(
+    public_id: str,
+    x_api_key: str | None = None,
+) -> dict[str, Any]:
+    """Build request arguments."""
+    url = f"/api/sessions/{public_id}/close"
+
+    headers: dict[str, str] = {}
+    if x_api_key is not None:
+        headers["X-API-Key"] = x_api_key
+
+    return {
+        "method": "POST",
+        "url": url,
+        "headers": headers,
+    }
+
+
+def sync(
+    client: httpx.Client,
+    public_id: str,
+    x_api_key: str | None = None,
+) -> CloseSessionResponse:
+    """Close a running session.
+
+    Updates the session status to cancelled and closes the Plato session."""
+
+    request_args = _build_request_args(
+        public_id=public_id,
+        x_api_key=x_api_key,
+    )
+
+    response = client.request(**request_args)
+    raise_for_status(response)
+    return CloseSessionResponse.model_validate(response.json())
+
+
+async def asyncio(
+    client: httpx.AsyncClient,
+    public_id: str,
+    x_api_key: str | None = None,
+) -> CloseSessionResponse:
+    """Close a running session.
+
+    Updates the session status to cancelled and closes the Plato session."""
+
+    request_args = _build_request_args(
+        public_id=public_id,
+        x_api_key=x_api_key,
+    )
+
+    response = await client.request(**request_args)
+    raise_for_status(response)
+    return CloseSessionResponse.model_validate(response.json())

plato/chronos/api/sessions/complete_session.py

@@ -0,0 +1,74 @@
+"""Complete Session"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from plato.chronos.errors import raise_for_status
+from plato.chronos.models import CompleteSessionRequest, SessionResponse
+
+
+def _build_request_args(
+    public_id: str,
+    body: CompleteSessionRequest,
+    x_api_key: str | None = None,
+) -> dict[str, Any]:
+    """Build request arguments."""
+    url = f"/api/sessions/{public_id}/complete"
+
+    headers: dict[str, str] = {}
+    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,
+    public_id: str,
+    body: CompleteSessionRequest,
+    x_api_key: str | None = None,
+) -> SessionResponse:
+    """Mark a session as completed or failed.
+
+    Called by the bootstrap script when the world runner finishes.
+    Uses API key auth (no org check) since it's called from the VM."""
+
+    request_args = _build_request_args(
+        public_id=public_id,
+        body=body,
+        x_api_key=x_api_key,
+    )
+
+    response = client.request(**request_args)
+    raise_for_status(response)
+    return SessionResponse.model_validate(response.json())
+
+
+async def asyncio(
+    client: httpx.AsyncClient,
+    public_id: str,
+    body: CompleteSessionRequest,
+    x_api_key: str | None = None,
+) -> SessionResponse:
+    """Mark a session as completed or failed.
+
+    Called by the bootstrap script when the world runner finishes.
+    Uses API key auth (no org check) since it's called from the VM."""
+
+    request_args = _build_request_args(
+        public_id=public_id,
+        body=body,
+        x_api_key=x_api_key,
+    )
+
+    response = await client.request(**request_args)
+    raise_for_status(response)
+    return SessionResponse.model_validate(response.json())