plato-sdk-v2 2.0.64__py3-none-any.whl → 2.3.4__py3-none-any.whl

plato/v2/sync/session.py

@@ -30,7 +30,9 @@ 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 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
 from plato._generated.api.v2.sessions import snapshot as sessions_snapshot
+from plato._generated.api.v2.sessions import snapshot_store as sessions_snapshot_store
 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 (
@@ -38,6 +40,8 @@ from plato._generated.models import (
     AppApiV2SchemasSessionCreateSnapshotResponse,
     AppApiV2SchemasSessionEvaluateResponse,
     AppApiV2SchemasSessionHeartbeatResponse,
+    AppApiV2SchemasSessionSetupSandboxRequest,
+    AppApiV2SchemasSessionSetupSandboxResponse,
     CreateDiskSnapshotRequest,
     CreateDiskSnapshotResponse,
     CreateSessionFromEnvs,
@@ -530,6 +534,38 @@ class Session:
             x_api_key=self._api_key,
         )
 
+    def setup_sandbox(
+        self,
+        timeout: int = 120,
+    ) -> AppApiV2SchemasSessionSetupSandboxResponse:
+        """Setup sandbox environment with Docker overlay on all environments.
+
+        This configures the VMs for Docker usage with overlay2 storage driver,
+        which is significantly faster than the default vfs driver. Should be called
+        after session creation and before pulling Docker images.
+
+        The setup includes:
+        - Mounting /dev/vdb to /mnt/docker for Docker storage
+        - Configuring Docker with overlay2 storage driver
+        - Setting up ECR and Docker Hub authentication
+        - Creating a docker-user service for non-root Docker access
+
+        Args:
+            timeout: Setup timeout in seconds (default: 120).
+
+        Returns:
+            SetupSandboxResponse with results per job_id.
+        """
+        self._check_closed()
+
+        request = AppApiV2SchemasSessionSetupSandboxRequest(timeout=timeout)
+        return sessions_setup_sandbox.sync(
+            client=self._http,
+            session_id=self.session_id,
+            body=request,
+            x_api_key=self._api_key,
+        )
+
     def evaluate(self, **kwargs) -> AppApiV2SchemasSessionEvaluateResponse:
         """Evaluate the session against task criteria.
 
@@ -560,6 +596,38 @@ class Session:
             x_api_key=self._api_key,
         )
 
+    def snapshot_store(
+        self,
+        override_service: str | None = None,
+        override_version: str | None = None,
+        override_dataset: str | None = None,
+    ) -> AppApiV2SchemasSessionCreateSnapshotResponse:
+        """Create a snapshot-store snapshot of all environments in the session.
+
+        Uses the snapshot-store pipeline for chunk-based deduplication and
+        efficient storage. This is the preferred method for new base snapshots.
+
+        Args:
+            override_service: Override simulator/service name in artifact metadata.
+            override_version: Override version/git_hash in artifact metadata.
+            override_dataset: Override dataset name in artifact metadata.
+
+        Returns:
+            Snapshot response with info per job_id.
+        """
+        self._check_closed()
+
+        return sessions_snapshot_store.sync(
+            client=self._http,
+            session_id=self.session_id,
+            body=AppApiV2SchemasSessionCreateSnapshotRequest(
+                override_service=override_service,
+                override_version=override_version,
+                override_dataset=override_dataset,
+            ),
+            x_api_key=self._api_key,
+        )
+
     def disk_snapshot(
         self,
         override_service: str | None = None,
@@ -625,10 +693,10 @@ class Session:
         """
         self._check_closed()
 
-        try:
-            from playwright.sync_api import Page
-        except ImportError as e:
-            raise ImportError("The login() method requires playwright. Install it with: pip install playwright") from e
+        import importlib.util
+
+        if importlib.util.find_spec("playwright") is None:
+            raise ImportError("The login() method requires playwright. Install it with: pip install playwright")
 
         context = browser.new_context()
         pages: dict[str, Page] = {}

plato/worlds/README.md

@@ -6,15 +6,33 @@ Run Plato worlds locally for development and testing.
 
 ```bash
 # List available worlds
-plato-world-runner --list
+plato-world-runner list
 
 # Run a world with a config file
-plato-world-runner --world <name> --config config.json
+plato-world-runner run --world <name> --config config.json
 ```
 
 ## Config File Format
 
-Create a JSON config file with the following structure:
+Create a JSON config file:
+
+```json
+{
+  "repository_url": "https://github.com/example/repo",
+  "prompt": "Fix the bug in main.py",
+  "coder": {
+    "image": "my-agent:latest",
+    "config": {
+      "model": "gpt-4"
+    }
+  },
+  "git_token": "ghp_...",
+  "session_id": "local-test-001",
+  "callback_url": ""
+}
+```
+
+Or with nested format (backwards compatible):
 
 ```json
 {
@@ -24,62 +42,56 @@ Create a JSON config file with the following structure:
   },
   "agents": {
     "coder": {
-      "image": "my-agent:latest",
-      "config": {
-        "model": "gpt-4"
-      }
+      "image": "my-agent:latest"
     }
   },
   "secrets": {
-    "OPENAI_API_KEY": "sk-..."
+    "git_token": "ghp_..."
   },
-  "session_id": "local-test-001",
-  "callback_url": ""
+  "session_id": "local-test-001"
 }
 ```
 
-### Fields
-
-| Field | Description |
-|-------|-------------|
-| `world_config` | World-specific configuration (varies by world) |
-| `agents` | Map of slot name to agent config (`image` + optional `config`) |
-| `secrets` | Secret values (API keys, tokens) |
-| `session_id` | Unique identifier for this run |
-| `callback_url` | Full Chronos callback URL (e.g., `http://server/api/callback`), leave empty for local runs |
-
 ## Creating a World
 
-### 1. Define the World Class
+### 1. Define the Config and World Class
 
 ```python
-# my_world.py
-from plato.worlds import BaseWorld, register_world, AgentSlot, Observation, StepResult
-from plato.worlds.config import RunConfig, WorldConfig
+from typing import Annotated
+from plato.worlds import (
+    BaseWorld, RunConfig, Agent, Secret, AgentConfig,
+    Observation, StepResult, register_world
+)
 
-class MyWorldConfig(WorldConfig):
-    """Typed config for MyWorld."""
+class MyWorldConfig(RunConfig):
+    """Typed config - all fields accessible directly."""
+
+    # World-specific fields
     prompt: str
     max_steps: int = 10
 
+    # Agents (typed, no .get() needed)
+    worker: Annotated[AgentConfig, Agent(description="The main agent")]
+
+    # Secrets (typed, optional)
+    api_key: Annotated[str | None, Secret(description="API key")] = None
+
 @register_world("my-world")
-class MyWorld(BaseWorld):
+class MyWorld(BaseWorld[MyWorldConfig]):
     name = "my-world"
     description = "A simple example world"
-    agents = [
-        AgentSlot(name="worker", description="The main agent", required=True),
-    ]
-    secrets = ["API_KEY"]
-    config_class = MyWorldConfig
 
-    async def reset(self, config: RunConfig[MyWorldConfig]) -> Observation:
-        """Setup the world."""
-        self.prompt = config.world_config.prompt
-        return Observation(data={"prompt": self.prompt})
+    async def reset(self) -> Observation:
+        """Setup the world. Access config via self.config."""
+        # All access is typed - no .get() methods
+        prompt = self.config.prompt          # str
+        worker = self.config.worker          # AgentConfig
+        api_key = self.config.api_key        # str | None
+
+        return Observation(data={"prompt": prompt})
 
     async def step(self) -> StepResult:
         """Execute one step."""
-        # Your world logic here
         return StepResult(
             observation=Observation(data={"status": "done"}),
             done=True,
@@ -106,10 +118,10 @@ my-world = "my_world:MyWorld"
 pip install -e .
 
 # Verify it's registered
-plato-world-runner --list
+plato-world-runner list
 
 # Run with config
-plato-world-runner --world my-world --config config.json -v
+plato-world-runner run --world my-world --config config.json -v
 ```
 
 ## Programmatic Usage
@@ -117,12 +129,12 @@ plato-world-runner --world my-world --config config.json -v
 ```python
 import asyncio
 from plato.worlds import run_world
-from plato.worlds.config import RunConfig
+from my_world import MyWorldConfig, AgentConfig
 
-config = RunConfig(
-    world_config={"prompt": "Hello world"},
-    agents={"worker": {"image": "agent:latest"}},
-    secrets={"API_KEY": "secret"},
+config = MyWorldConfig(
+    prompt="Hello world",
+    worker=AgentConfig(image="agent:latest"),
+    api_key="secret",
 )
 
 asyncio.run(run_world("my-world", config))
@@ -131,20 +143,23 @@ asyncio.run(run_world("my-world", config))
 Or load from a file:
 
 ```python
-from plato.worlds.config import RunConfig
+from my_world import MyWorldConfig
 
-config = RunConfig.from_file("config.json")
+config = MyWorldConfig.from_file("config.json")
 ```
 
 ## CLI Options
 
 ```
-plato-world-runner [OPTIONS]
+plato-world-runner [COMMAND] [OPTIONS]
+
+Commands:
+  run     Run a world with the given configuration
+  list    List available worlds
 
-Options:
-  -w, --world TEXT    World name to run
-  -c, --config PATH   Path to config JSON file
-  -l, --list          List available worlds
+Run options:
+  -w, --world TEXT    World name to run (required)
+  -c, --config PATH   Path to config JSON file (required)
   -v, --verbose       Enable debug logging
 ```
 
@@ -152,14 +167,14 @@ Options:
 
 1. **Discovery**: Worlds are discovered via `plato.worlds` entry points
 2. **Instantiation**: World class is instantiated
-3. **Reset**: `reset(config)` is called to setup the world
+3. **Reset**: `reset()` is called to setup the world (config available via `self.config`)
 4. **Step Loop**: `step()` is called repeatedly until `done=True`
 5. **Cleanup**: `close()` is called to cleanup resources
 
 ```
-┌─────────────────────────────────────────┐
-│  plato-world-runner --world X --config  │
-└─────────────────────────────────────────┘
+┌───────────────────────────────────────────────┐
+│  plato-world-runner run --world X --config Y  │
+└───────────────────────────────────────────────┘
                     │
                     ▼
           ┌─────────────────┐
@@ -192,7 +207,7 @@ Options:
 Enable verbose logging:
 
 ```bash
-plato-world-runner --world my-world --config config.json --verbose
+plato-world-runner run --world my-world --config config.json --verbose
 ```
 
 Or set log level in code:

plato/worlds/__init__.py

@@ -1,44 +1,82 @@
-"""Plato Worlds - simple world definitions for agent execution.
-
-A World defines:
-- Available agent slots (list of strings)
-- Configuration schema
-- Run logic (what happens when the world executes)
+"""Plato Worlds - typed world definitions for agent execution.
 
 Usage:
-    from plato.worlds import BaseWorld, register_world, AgentSlot
+    from plato.worlds import BaseWorld, RunConfig, Agent, Secret, Env, AgentConfig, EnvConfig, register_world
+    from plato._generated.models import EnvFromArtifact, EnvFromSimulator
+    from typing import Annotated
+
+    class CodeWorldConfig(RunConfig):
+        # World-specific fields
+        repository_url: str
+        prompt: str
+
+        # Agents (typed)
+        coder: Annotated[AgentConfig, Agent(description="Coding agent")]
+
+        # Secrets (typed)
+        git_token: Annotated[str | None, Secret(description="GitHub token")] = None
+
+        # Environments (typed)
+        gitea: Annotated[EnvConfig, Env(description="Git server")] = EnvFromArtifact(
+            artifact_id="abc123",
+            alias="gitea",
+        )
 
     @register_world("code")
-    class CodeWorld(BaseWorld):
-        agents = ["coder"]  # Available agent slots
+    class CodeWorld(BaseWorld[CodeWorldConfig]):
+        name = "code"
+        description = "Run coding agents"
+
+        async def reset(self) -> Observation:
+            # Fully typed access
+            url = self.config.repository_url
+            agent = self.config.coder
+            token = self.config.git_token
+            gitea = self.config.gitea  # EnvConfig
 
-        async def run(self, config: RunConfig) -> None:
-            # Clone repo, run agent, etc.
-            pass
+        async def step(self) -> StepResult:
+            ...
 """
 
+from plato._generated.models import (
+    EnvFromArtifact,
+    EnvFromResource,
+    EnvFromSimulator,
+)
 from plato.worlds.base import (
-    AgentSlot,
     BaseWorld,
+    ConfigT,
     Observation,
     StepResult,
     get_registered_worlds,
     get_world,
     register_world,
 )
-from plato.worlds.config import AgentConfig, RunConfig, WorldConfig
+from plato.worlds.config import Agent, AgentConfig, CheckpointConfig, Env, EnvConfig, RunConfig, Secret, StateConfig
 from plato.worlds.runner import run_world
 
 __all__ = [
+    # Base
     "BaseWorld",
-    "AgentSlot",
+    "ConfigT",
     "Observation",
     "StepResult",
-    "WorldConfig",
-    "AgentConfig",
-    "RunConfig",
     "register_world",
     "get_registered_worlds",
     "get_world",
+    # Config
+    "RunConfig",
+    "CheckpointConfig",
+    "StateConfig",
+    "AgentConfig",
+    "Agent",
+    "Secret",
+    "Env",
+    "EnvConfig",
+    # Env types (re-exported from generated models)
+    "EnvFromArtifact",
+    "EnvFromSimulator",
+    "EnvFromResource",
+    # Runner
     "run_world",
 ]