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

plato/v2/sync/session.py

@@ -12,10 +12,13 @@ import uuid
 from dataclasses import dataclass
 from datetime import datetime
 from pathlib import Path
+from typing import TYPE_CHECKING
 
 import httpx
 import tenacity
-from playwright.sync_api import Browser, BrowserContext, Page
+
+if TYPE_CHECKING:
+    from playwright.sync_api import Browser, BrowserContext, Page
 
 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
@@ -27,6 +30,7 @@ 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 state as sessions_state
 from plato._generated.api.v2.sessions import wait_for_ready as sessions_wait_for_ready
@@ -35,6 +39,8 @@ from plato._generated.models import (
     AppApiV2SchemasSessionCreateSnapshotResponse,
     AppApiV2SchemasSessionEvaluateResponse,
     AppApiV2SchemasSessionHeartbeatResponse,
+    AppApiV2SchemasSessionSetupSandboxRequest,
+    AppApiV2SchemasSessionSetupSandboxResponse,
     CreateDiskSnapshotRequest,
     CreateDiskSnapshotResponse,
     CreateSessionFromEnvs,
@@ -63,6 +69,8 @@ logger = logging.getLogger(__name__)
 class LoginResult:
     """Result of login operation containing browser context and pages.
 
+    Requires playwright to be installed.
+
     Attributes:
         context: The Playwright BrowserContext used for all pages.
         pages: Dict mapping env alias to the logged-in Page.
@@ -265,9 +273,10 @@ class Session:
         )
 
         # Use generated API function
+        # Note: API supports both CreateSessionFromEnvs and CreateSessionFromTask via discriminator
         response = sessions_make.sync(
             client=http_client,
-            body=request_body,
+            body=request_body,  # type: ignore[arg-type]
             x_api_key=api_key,
         )
 
@@ -524,6 +533,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.
 
@@ -600,6 +641,9 @@ class Session:
         Navigates each page to the environment's public URL and executes
         the login flow using the v1 SyncFlowExecutor.
 
+        Requires playwright to be installed:
+            pip install playwright
+
         Args:
             browser: Playwright Browser instance.
             dataset: Dataset name for login flow (default: "base" uses "login" flow).
@@ -612,9 +656,15 @@ class Session:
 
         Raises:
             RuntimeError: If login fails.
+            ImportError: If playwright is not installed.
         """
         self._check_closed()
 
+        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

@@ -0,0 +1,218 @@
+# Plato Worlds - Local Development Guide
+
+Run Plato worlds locally for development and testing.
+
+## Quick Start
+
+```bash
+# List available worlds
+plato-world-runner list
+
+# Run a world with a config file
+plato-world-runner run --world <name> --config config.json
+```
+
+## Config File Format
+
+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
+{
+  "world_config": {
+    "repository_url": "https://github.com/example/repo",
+    "prompt": "Fix the bug in main.py"
+  },
+  "agents": {
+    "coder": {
+      "image": "my-agent:latest"
+    }
+  },
+  "secrets": {
+    "git_token": "ghp_..."
+  },
+  "session_id": "local-test-001"
+}
+```
+
+## Creating a World
+
+### 1. Define the Config and World Class
+
+```python
+from typing import Annotated
+from plato.worlds import (
+    BaseWorld, RunConfig, Agent, Secret, AgentConfig,
+    Observation, StepResult, register_world
+)
+
+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[MyWorldConfig]):
+    name = "my-world"
+    description = "A simple example world"
+
+    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."""
+        return StepResult(
+            observation=Observation(data={"status": "done"}),
+            done=True,
+        )
+
+    async def close(self) -> None:
+        """Cleanup resources."""
+        pass
+```
+
+### 2. Register via Entry Point
+
+In your `pyproject.toml`:
+
+```toml
+[project.entry-points."plato.worlds"]
+my-world = "my_world:MyWorld"
+```
+
+### 3. Run It
+
+```bash
+# Install your package
+pip install -e .
+
+# Verify it's registered
+plato-world-runner list
+
+# Run with config
+plato-world-runner run --world my-world --config config.json -v
+```
+
+## Programmatic Usage
+
+```python
+import asyncio
+from plato.worlds import run_world
+from my_world import MyWorldConfig, AgentConfig
+
+config = MyWorldConfig(
+    prompt="Hello world",
+    worker=AgentConfig(image="agent:latest"),
+    api_key="secret",
+)
+
+asyncio.run(run_world("my-world", config))
+```
+
+Or load from a file:
+
+```python
+from my_world import MyWorldConfig
+
+config = MyWorldConfig.from_file("config.json")
+```
+
+## CLI Options
+
+```
+plato-world-runner [COMMAND] [OPTIONS]
+
+Commands:
+  run     Run a world with the given configuration
+  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
+```
+
+## World Lifecycle
+
+1. **Discovery**: Worlds are discovered via `plato.worlds` entry points
+2. **Instantiation**: World class is instantiated
+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 run --world X --config Y  │
+└───────────────────────────────────────────────┘
+                    │
+                    ▼
+          ┌─────────────────┐
+          │ discover_worlds │
+          └─────────────────┘
+                    │
+                    ▼
+          ┌─────────────────┐
+          │  world.reset()  │
+          └─────────────────┘
+                    │
+                    ▼
+          ┌─────────────────┐
+          │  world.step()   │◄──┐
+          └─────────────────┘   │
+                    │           │
+                ┌───┴───┐       │
+                │ done? │───No──┘
+                └───┬───┘
+                   Yes
+                    │
+                    ▼
+          ┌─────────────────┐
+          │  world.close()  │
+          └─────────────────┘
+```
+
+## Debugging
+
+Enable verbose logging:
+
+```bash
+plato-world-runner run --world my-world --config config.json --verbose
+```
+
+Or set log level in code:
+
+```python
+import logging
+logging.basicConfig(level=logging.DEBUG)
+```

plato/worlds/__init__.py

@@ -1,44 +1,80 @@
-"""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, Env, EnvConfig, RunConfig, Secret
 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",
+    "AgentConfig",
+    "Agent",
+    "Secret",
+    "Env",
+    "EnvConfig",
+    # Env types (re-exported from generated models)
+    "EnvFromArtifact",
+    "EnvFromSimulator",
+    "EnvFromResource",
+    # Runner
     "run_world",
 ]