plato-sdk-v2 2.0.50__py3-none-any.whl → 2.2.4__py3-none-any.whl

plato/__init__.py

@@ -4,7 +4,7 @@
 # v2: New SDK with separate sync/async modules
 # agents: Harbor agent framework re-exports (ClaudeCode, OpenHands, Codex, etc.)
 # sims: Simulation clients (Spree, Firefly, etc.)
-# world: OpenAI Gym-like environments backed by Plato simulators
+# chronos: Chronos agent evaluation platform SDK
 #
 # Usage (v2 - recommended):
 #   from plato.v2 import AsyncPlato, Plato, Env
@@ -16,8 +16,9 @@
 # Usage (sims):
 #   from plato.sims import SpreeClient, FireflyClient
 #
-# Usage (world):
-#   from plato.world import World, WorldConfig, EnvSpec
+# Usage (chronos):
+#   from plato.chronos import Client, AsyncClient
+#   from plato.chronos.models import AgentCreate, WorldCreate, LaunchJobRequest
 
 from importlib.metadata import PackageNotFoundError, version
 
@@ -56,9 +57,9 @@ def __getattr__(name: str):
 
         return sims
 
-    if name == "world":
-        from plato import world
+    if name == "chronos":
+        import importlib
 
-        return world
+        return importlib.import_module("plato.chronos")
 
     raise AttributeError(f"module 'plato' has no attribute '{name}'")

plato/_generated/__init__.py

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

plato/_generated/api/v1/env/evaluate_session.py

@@ -12,7 +12,7 @@ from plato._generated.models import AppSchemasEnvRequestsEvaluateRequest, AppSch
 
 def _build_request_args(
     session_id: str,
-    body: AppSchemasEnvRequestsEvaluateRequest | Any,
+    body: AppSchemasEnvRequestsEvaluateRequest,
     authorization: str | None = None,
     x_api_key: str | None = None,
 ) -> dict[str, Any]:
@@ -36,7 +36,7 @@ def _build_request_args(
 def sync(
     client: httpx.Client,
     session_id: str,
-    body: AppSchemasEnvRequestsEvaluateRequest | Any,
+    body: AppSchemasEnvRequestsEvaluateRequest,
     authorization: str | None = None,
     x_api_key: str | None = None,
 ) -> AppSchemasEnvResponsesEvaluateResponse:
@@ -57,7 +57,7 @@ def sync(
 async def asyncio(
     client: httpx.AsyncClient,
     session_id: str,
-    body: AppSchemasEnvRequestsEvaluateRequest | Any,
+    body: AppSchemasEnvRequestsEvaluateRequest,
     authorization: str | None = None,
     x_api_key: str | None = None,
 ) -> AppSchemasEnvResponsesEvaluateResponse:

plato/_generated/api/v1/env/log_state_mutation.py

@@ -7,12 +7,12 @@ from typing import Any
 import httpx
 
 from plato._generated.errors import raise_for_status
-from plato._generated.models import AppApiV1EnvRoutesBatchLogRequest, BaseStructuredRunLog, LogResponse
+from plato._generated.models import BaseStructuredRunLog, LogResponse
 
 
 def _build_request_args(
     session_id: str,
-    body: BaseStructuredRunLog | AppApiV1EnvRoutesBatchLogRequest,
+    body: BaseStructuredRunLog,
 ) -> dict[str, Any]:
     """Build request arguments."""
     url = f"/api/v1/env/{session_id}/log"
@@ -27,7 +27,7 @@ def _build_request_args(
 def sync(
     client: httpx.Client,
     session_id: str,
-    body: BaseStructuredRunLog | AppApiV1EnvRoutesBatchLogRequest,
+    body: BaseStructuredRunLog,
 ) -> LogResponse:
     """Log a state mutation or batch of mutations.
 
@@ -47,7 +47,7 @@ def sync(
 async def asyncio(
     client: httpx.AsyncClient,
     session_id: str,
-    body: BaseStructuredRunLog | AppApiV1EnvRoutesBatchLogRequest,
+    body: BaseStructuredRunLog,
 ) -> LogResponse:
     """Log a state mutation or batch of mutations.
 

plato/_generated/api/v1/sandbox/checkpoint_vm.py

@@ -15,7 +15,7 @@ from plato._generated.models import (
 
 def _build_request_args(
     public_id: str,
-    body: AppApiV1PublicBuildRoutesCreateSnapshotRequest | Any,
+    body: AppApiV1PublicBuildRoutesCreateSnapshotRequest,
     authorization: str | None = None,
     x_api_key: str | None = None,
 ) -> dict[str, Any]:
@@ -39,7 +39,7 @@ def _build_request_args(
 def sync(
     client: httpx.Client,
     public_id: str,
-    body: AppApiV1PublicBuildRoutesCreateSnapshotRequest | Any,
+    body: AppApiV1PublicBuildRoutesCreateSnapshotRequest,
     authorization: str | None = None,
     x_api_key: str | None = None,
 ) -> AppApiV1PublicBuildRoutesCreateSnapshotResponse:
@@ -66,7 +66,7 @@ def sync(
 async def asyncio(
     client: httpx.AsyncClient,
     public_id: str,
-    body: AppApiV1PublicBuildRoutesCreateSnapshotRequest | Any,
+    body: AppApiV1PublicBuildRoutesCreateSnapshotRequest,
     authorization: str | None = None,
     x_api_key: str | None = None,
 ) -> AppApiV1PublicBuildRoutesCreateSnapshotResponse:

plato/_generated/api/v1/sandbox/save_vm_snapshot.py

@@ -15,7 +15,7 @@ from plato._generated.models import (
 
 def _build_request_args(
     public_id: str,
-    body: AppApiV1PublicBuildRoutesCreateSnapshotRequest | Any,
+    body: AppApiV1PublicBuildRoutesCreateSnapshotRequest,
     authorization: str | None = None,
     x_api_key: str | None = None,
 ) -> dict[str, Any]:
@@ -39,7 +39,7 @@ def _build_request_args(
 def sync(
     client: httpx.Client,
     public_id: str,
-    body: AppApiV1PublicBuildRoutesCreateSnapshotRequest | Any,
+    body: AppApiV1PublicBuildRoutesCreateSnapshotRequest,
     authorization: str | None = None,
     x_api_key: str | None = None,
 ) -> AppApiV1PublicBuildRoutesCreateSnapshotResponse:
@@ -65,7 +65,7 @@ def sync(
 async def asyncio(
     client: httpx.AsyncClient,
     public_id: str,
-    body: AppApiV1PublicBuildRoutesCreateSnapshotRequest | Any,
+    body: AppApiV1PublicBuildRoutesCreateSnapshotRequest,
     authorization: str | None = None,
     x_api_key: str | None = None,
 ) -> AppApiV1PublicBuildRoutesCreateSnapshotResponse:

plato/_generated/api/v1/sandbox/setup_sandbox.py

@@ -7,12 +7,12 @@ from typing import Any
 import httpx
 
 from plato._generated.errors import raise_for_status
-from plato._generated.models import SetupSandboxRequest, SetupSandboxResponse
+from plato._generated.models import AppSchemasBuildModelsSetupSandboxRequest, AppSchemasBuildModelsSetupSandboxResponse
 
 
 def _build_request_args(
     public_id: str,
-    body: SetupSandboxRequest,
+    body: AppSchemasBuildModelsSetupSandboxRequest,
     authorization: str | None = None,
     x_api_key: str | None = None,
 ) -> dict[str, Any]:
@@ -36,10 +36,10 @@ def _build_request_args(
 def sync(
     client: httpx.Client,
     public_id: str,
-    body: SetupSandboxRequest,
+    body: AppSchemasBuildModelsSetupSandboxRequest,
     authorization: str | None = None,
     x_api_key: str | None = None,
-) -> SetupSandboxResponse:
+) -> AppSchemasBuildModelsSetupSandboxResponse:
     """Setup sandbox development environment with git clone."""
 
     request_args = _build_request_args(
@@ -51,16 +51,16 @@ def sync(
 
     response = client.request(**request_args)
     raise_for_status(response)
-    return SetupSandboxResponse.model_validate(response.json())
+    return AppSchemasBuildModelsSetupSandboxResponse.model_validate(response.json())
 
 
 async def asyncio(
     client: httpx.AsyncClient,
     public_id: str,
-    body: SetupSandboxRequest,
+    body: AppSchemasBuildModelsSetupSandboxRequest,
     authorization: str | None = None,
     x_api_key: str | None = None,
-) -> SetupSandboxResponse:
+) -> AppSchemasBuildModelsSetupSandboxResponse:
     """Setup sandbox development environment with git clone."""
 
     request_args = _build_request_args(
@@ -72,4 +72,4 @@ async def asyncio(
 
     response = await client.request(**request_args)
     raise_for_status(response)
-    return SetupSandboxResponse.model_validate(response.json())
+    return AppSchemasBuildModelsSetupSandboxResponse.model_validate(response.json())

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

@@ -21,6 +21,7 @@ from . import (
     get_session,
     get_session_replays,
     get_sessions,
+    get_sessions_for_archival,
     get_ui_events,
     restore_session_logs,
     score_session_with_config,
@@ -57,5 +58,6 @@ __all__ = [
     "restore_session_logs",
     "get_logs_status",
     "archive_session_logs_endpoint",
+    "get_sessions_for_archival",
     "set_session_output",
 ]

plato/_generated/api/v1/session/get_sessions_for_archival.py

@@ -0,0 +1,100 @@
+"""Get Sessions For Archival"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from plato._generated.errors import raise_for_status
+from plato._generated.models import SessionArchivalListResponse
+
+
+def _build_request_args(
+    page: int | None = 1,
+    page_size: int | None = 10000,
+    only_unarchived: bool | None = False,
+    authorization: str | None = None,
+    x_api_key: str | None = None,
+) -> dict[str, Any]:
+    """Build request arguments."""
+    url = "/api/v1/session/archival/list"
+
+    params: dict[str, Any] = {}
+    if page is not None:
+        params["page"] = page
+    if page_size is not None:
+        params["page_size"] = page_size
+    if only_unarchived is not None:
+        params["only_unarchived"] = only_unarchived
+
+    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,
+        "params": params,
+        "headers": headers,
+    }
+
+
+def sync(
+    client: httpx.Client,
+    page: int | None = 1,
+    page_size: int | None = 10000,
+    only_unarchived: bool | None = False,
+    authorization: str | None = None,
+    x_api_key: str | None = None,
+) -> SessionArchivalListResponse:
+    """Lightweight endpoint to list sessions with archival-relevant fields only.
+    Requires admin access.
+
+    Returns minimal data (no joins) for fast bulk queries:
+    - session_id, created_at, logs_archived_at, organization_id, simulator_id
+
+    Use only_unarchived=true to filter to sessions that haven't been archived yet."""
+
+    request_args = _build_request_args(
+        page=page,
+        page_size=page_size,
+        only_unarchived=only_unarchived,
+        authorization=authorization,
+        x_api_key=x_api_key,
+    )
+
+    response = client.request(**request_args)
+    raise_for_status(response)
+    return SessionArchivalListResponse.model_validate(response.json())
+
+
+async def asyncio(
+    client: httpx.AsyncClient,
+    page: int | None = 1,
+    page_size: int | None = 10000,
+    only_unarchived: bool | None = False,
+    authorization: str | None = None,
+    x_api_key: str | None = None,
+) -> SessionArchivalListResponse:
+    """Lightweight endpoint to list sessions with archival-relevant fields only.
+    Requires admin access.
+
+    Returns minimal data (no joins) for fast bulk queries:
+    - session_id, created_at, logs_archived_at, organization_id, simulator_id
+
+    Use only_unarchived=true to filter to sessions that haven't been archived yet."""
+
+    request_args = _build_request_args(
+        page=page,
+        page_size=page_size,
+        only_unarchived=only_unarchived,
+        authorization=authorization,
+        x_api_key=x_api_key,
+    )
+
+    response = await client.request(**request_args)
+    raise_for_status(response)
+    return SessionArchivalListResponse.model_validate(response.json())

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

@@ -20,9 +20,11 @@ from . import (
     get_human_recorder_tab_counts,
     get_human_recorder_testcases,
     get_merged_mutations,
-    get_next_output_testcase_for_scoring,
+    get_mutation_groups_for_testcase,
+    get_next_testcase_for_scoring,
     get_organization_test_case_assignments,
     get_testcase,
+    get_testcase_metadata_for_scoring,
     get_testcase_sets,
     get_testcases,
     get_testcases_in_set,
@@ -35,12 +37,14 @@ __all__ = [
     "get_testcases",
     "create_testcase",
     "get_merged_mutations",
+    "get_testcase_metadata_for_scoring",
     "get_testcase_sets",
     "create_testcase_set",
     "get_organization_test_case_assignments",
     "archive_organization_test_case_assignments",
     "get_human_recorder_testcases",
-    "get_next_output_testcase_for_scoring",
+    "get_next_testcase_for_scoring",
+    "get_mutation_groups_for_testcase",
     "filter_human_recorder_testcases",
     "get_testcase",
     "update_testcase",

plato/_generated/api/v1/testcases/get_mutation_groups_for_testcase.py

@@ -0,0 +1,98 @@
+"""Get Mutation Groups For Testcase"""
+
+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,
+    session_ids: str | None = None,
+    authorization: str | None = None,
+    x_api_key: str | None = None,
+) -> dict[str, Any]:
+    """Build request arguments."""
+    url = f"/api/v1/testcases/{public_id}/mutation-groups"
+
+    params: dict[str, Any] = {}
+    if session_ids is not None:
+        params["session_ids"] = session_ids
+
+    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,
+        "params": params,
+        "headers": headers,
+    }
+
+
+def sync(
+    client: httpx.Client,
+    public_id: str,
+    session_ids: str | None = None,
+    authorization: str | None = None,
+    x_api_key: str | None = None,
+) -> Any:
+    """Get mutation groups for a test case using generated scoring configs.
+
+    This uses AI-based config generation to group sessions by their mutation patterns,
+    properly handling things like random IDs (mutation_variables) that differ between
+    sessions but represent the same logical mutation.
+
+    Returns groups of session IDs where sessions in each group have equivalent mutations.
+
+    Args:
+        session_ids: Optional comma-separated list of session IDs to process.
+                    If not provided, will process up to 50 most recent sessions."""
+
+    request_args = _build_request_args(
+        public_id=public_id,
+        session_ids=session_ids,
+        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,
+    session_ids: str | None = None,
+    authorization: str | None = None,
+    x_api_key: str | None = None,
+) -> Any:
+    """Get mutation groups for a test case using generated scoring configs.
+
+    This uses AI-based config generation to group sessions by their mutation patterns,
+    properly handling things like random IDs (mutation_variables) that differ between
+    sessions but represent the same logical mutation.
+
+    Returns groups of session IDs where sessions in each group have equivalent mutations.
+
+    Args:
+        session_ids: Optional comma-separated list of session IDs to process.
+                    If not provided, will process up to 50 most recent sessions."""
+
+    request_args = _build_request_args(
+        public_id=public_id,
+        session_ids=session_ids,
+        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/testcases/{get_next_output_testcase_for_scoring.py → get_next_testcase_for_scoring.py}

@@ -1,4 +1,4 @@
-"""Get Next Output Testcase For Scoring"""
+"""Get Next Testcase For Scoring"""
 
 from __future__ import annotations
 
@@ -10,14 +10,17 @@ from plato._generated.errors import raise_for_status
 
 
 def _build_request_args(
+    scoring_type: str,
     exclude_test_case_id: str | None = None,
     authorization: str | None = None,
     x_api_key: str | None = None,
 ) -> dict[str, Any]:
     """Build request arguments."""
-    url = "/api/v1/testcases/next-for-output-scoring"
+    url = "/api/v1/testcases/next-for-scoring"
 
     params: dict[str, Any] = {}
+    if scoring_type is not None:
+        params["scoring_type"] = scoring_type
     if exclude_test_case_id is not None:
         params["exclude_test_case_id"] = exclude_test_case_id
 
@@ -37,16 +40,21 @@ def _build_request_args(
 
 def sync(
     client: httpx.Client,
+    scoring_type: str,
     exclude_test_case_id: str | None = None,
     authorization: str | None = None,
     x_api_key: str | None = None,
 ) -> Any:
-    """Get the next OUTPUT test case that needs scoring for the current annotator.
-    Returns test cases in NEEDS_SCORING stage with scoring_types=['output'].
-    Excludes test cases where the user has already scored all sessions.
-    Optionally excludes a specific test case (e.g., the current one)."""
+    """Get the next test case that needs scoring for the current annotator.
+    Returns test cases in NEEDS_SCORING stage with the specified scoring_type.
+    Excludes test cases where the user has already scored or created sessions.
+    Optionally excludes a specific test case (e.g., the current one).
+
+    Ordering: Prioritizes test cases with higher average scores per session (closer to completion).
+    Selection: Random from batch of 50 eligible test cases."""
 
     request_args = _build_request_args(
+        scoring_type=scoring_type,
         exclude_test_case_id=exclude_test_case_id,
         authorization=authorization,
         x_api_key=x_api_key,
@@ -59,16 +67,21 @@ def sync(
 
 async def asyncio(
     client: httpx.AsyncClient,
+    scoring_type: str,
     exclude_test_case_id: str | None = None,
     authorization: str | None = None,
     x_api_key: str | None = None,
 ) -> Any:
-    """Get the next OUTPUT test case that needs scoring for the current annotator.
-    Returns test cases in NEEDS_SCORING stage with scoring_types=['output'].
-    Excludes test cases where the user has already scored all sessions.
-    Optionally excludes a specific test case (e.g., the current one)."""
+    """Get the next test case that needs scoring for the current annotator.
+    Returns test cases in NEEDS_SCORING stage with the specified scoring_type.
+    Excludes test cases where the user has already scored or created sessions.
+    Optionally excludes a specific test case (e.g., the current one).
+
+    Ordering: Prioritizes test cases with higher average scores per session (closer to completion).
+    Selection: Random from batch of 50 eligible test cases."""
 
     request_args = _build_request_args(
+        scoring_type=scoring_type,
         exclude_test_case_id=exclude_test_case_id,
         authorization=authorization,
         x_api_key=x_api_key,

plato/_generated/api/v1/testcases/get_testcase_metadata_for_scoring.py

@@ -0,0 +1,74 @@
+"""Get Testcase Metadata For Scoring"""
+
+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/testcases/metadata-for-scoring/{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 limited test case metadata for the scoring page.
+    Only returns: publicId, name, scoringTypes.
+    This endpoint is designed for annotators who should not see sensitive test case data
+    like prompts, hints, or expected outputs."""
+
+    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 limited test case metadata for the scoring page.
+    Only returns: publicId, name, scoringTypes.
+    This endpoint is designed for annotators who should not see sensitive test case data
+    like prompts, hints, or expected outputs."""
+
+    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/v2/__init__.py

@@ -1,6 +1,6 @@
 """API version module."""
 
-from . import agents, artifacts, chronos, chronos_packages, cluster, jobs, pypi, releases, sessions
+from . import agents, artifacts, chronos, chronos_packages, cluster, jobs, pypi, releases, sessions, user
 
 __all__ = [
     "agents",
@@ -12,4 +12,5 @@ __all__ = [
     "pypi",
     "releases",
     "sessions",
+    "user",
 ]

plato/_generated/api/v2/jobs/__init__.py

@@ -14,7 +14,9 @@ from . import (
     public_url,
     reset,
     set_date,
+    setup_sandbox,
     snapshot,
+    snapshot_store,
     state,
     wait_for_ready,
 )
@@ -25,7 +27,9 @@ __all__ = [
     "close",
     "execute",
     "set_date",
+    "setup_sandbox",
     "snapshot",
+    "snapshot_store",
     "checkpoint",
     "disk_snapshot",
     "state",

plato/_generated/api/v2/jobs/checkpoint.py

@@ -12,7 +12,7 @@ from plato._generated.models import CreateCheckpointRequest, CreateCheckpointRes
 
 def _build_request_args(
     job_id: str,
-    body: CreateCheckpointRequest | Any,
+    body: CreateCheckpointRequest,
     authorization: str | None = None,
     x_api_key: str | None = None,
 ) -> dict[str, Any]:
@@ -36,7 +36,7 @@ def _build_request_args(
 def sync(
     client: httpx.Client,
     job_id: str,
-    body: CreateCheckpointRequest | Any,
+    body: CreateCheckpointRequest,
     authorization: str | None = None,
     x_api_key: str | None = None,
 ) -> CreateCheckpointResult:
@@ -66,7 +66,7 @@ def sync(
 async def asyncio(
     client: httpx.AsyncClient,
     job_id: str,
-    body: CreateCheckpointRequest | Any,
+    body: CreateCheckpointRequest,
     authorization: str | None = None,
     x_api_key: str | None = None,
 ) -> CreateCheckpointResult: