plato-sdk-v2 2.3.1__py3-none-any.whl → 2.3.2__py3-none-any.whl

plato/agents/__init__.py

@@ -85,6 +85,8 @@ __all__ = [
     "span",
     "log_event",
     "upload_artifacts",
+    "upload_artifact",
+    "upload_checkpoint",
     "reset_logging",
 ]
 
@@ -102,7 +104,9 @@ from plato.agents.logging import (
     log_event,
     reset_logging,
     span,
+    upload_artifact,
     upload_artifacts,
+    upload_checkpoint,
 )
 from plato.agents.runner import run_agent
 from plato.agents.trajectory import (

plato/agents/logging.py

@@ -399,3 +399,117 @@ async def upload_artifacts(dir_path: str) -> str | None:
     except Exception as e:
         logger.warning(f"Failed to upload artifacts: {e}")
         return None
+
+
+# =============================================================================
+# Artifact Upload (Generic)
+# =============================================================================
+
+
+async def upload_artifact(
+    data: bytes,
+    artifact_type: str,
+    filename: str | None = None,
+    extra: dict[str, Any] | None = None,
+) -> dict[str, Any] | None:
+    """Upload an artifact to Chronos.
+
+    Artifacts are stored in S3 and linked to the session in the database.
+
+    Args:
+        data: Raw bytes of the artifact
+        artifact_type: Type of artifact (e.g., "state", "logs", "trajectory")
+        filename: Optional filename for the artifact
+        extra: Optional extra data to store with the artifact
+
+    Returns:
+        Dict with artifact_id and s3_url if successful, None otherwise.
+    """
+    chronos = _ChronosLogger._instance
+    if not chronos or not chronos.enabled:
+        return None
+
+    try:
+        data_base64 = base64.b64encode(data).decode("utf-8")
+        logger.info(f"Uploading artifact: type={artifact_type}, size={len(data)} bytes")
+    except Exception as e:
+        logger.warning(f"Failed to encode artifact: {e}")
+        return None
+
+    try:
+        async with httpx.AsyncClient(timeout=120.0) as client:
+            response = await client.post(
+                f"{chronos.callback_url}/artifact",
+                json={
+                    "session_id": chronos.session_id,
+                    "artifact_type": artifact_type,
+                    "data_base64": data_base64,
+                    "filename": filename,
+                    "extra": extra or {},
+                },
+            )
+            if response.status_code == 200:
+                result = response.json()
+                logger.info(f"Uploaded artifact: {result}")
+                return result
+            else:
+                logger.warning(f"Failed to upload artifact: {response.status_code} {response.text}")
+                return None
+    except Exception as e:
+        logger.warning(f"Failed to upload artifact: {e}")
+        return None
+
+
+# =============================================================================
+# Checkpoint Upload
+# =============================================================================
+
+
+async def upload_checkpoint(
+    step_number: int,
+    env_snapshots: dict[str, str],
+    state_artifact_id: str | None = None,
+    extra: dict[str, Any] | None = None,
+) -> dict[str, Any] | None:
+    """Upload checkpoint data to Chronos.
+
+    A checkpoint includes:
+    - Environment snapshots (artifact IDs per env alias)
+    - State artifact (git bundle of /state directory)
+    - Extra data (step number, timestamp, etc.)
+
+    Args:
+        step_number: The step number when this checkpoint was created
+        env_snapshots: Dict mapping env alias to artifact_id
+        state_artifact_id: Artifact ID of the state bundle (from upload_artifact)
+        extra: Optional additional data
+
+    Returns:
+        Dict with checkpoint_id if successful, None otherwise.
+    """
+    chronos = _ChronosLogger._instance
+    if not chronos or not chronos.enabled:
+        return None
+
+    try:
+        async with httpx.AsyncClient(timeout=60.0) as client:
+            response = await client.post(
+                f"{chronos.callback_url}/checkpoint",
+                json={
+                    "session_id": chronos.session_id,
+                    "step_number": step_number,
+                    "env_snapshots": env_snapshots,
+                    "state_artifact_id": state_artifact_id,
+                    "extra": extra or {},
+                },
+            )
+            if response.status_code == 200:
+                result = response.json()
+                logger.info(f"Uploaded checkpoint: step={step_number}, checkpoint_id={result.get('checkpoint_id')}")
+                return result
+            else:
+                logger.warning(f"Failed to upload checkpoint: {response.status_code} {response.text}")
+                return None
+    except Exception as e:
+        logger.warning(f"Failed to upload checkpoint: {e}")
+        return None

plato/worlds/__init__.py

@@ -52,7 +52,7 @@ from plato.worlds.base import (
     get_world,
     register_world,
 )
-from plato.worlds.config import Agent, AgentConfig, Env, EnvConfig, RunConfig, Secret
+from plato.worlds.config import Agent, AgentConfig, CheckpointConfig, Env, EnvConfig, RunConfig, Secret, StateConfig
 from plato.worlds.runner import run_world
 
 __all__ = [
@@ -66,6 +66,8 @@ __all__ = [
     "get_world",
     # Config
     "RunConfig",
+    "CheckpointConfig",
+    "StateConfig",
     "AgentConfig",
     "Agent",
     "Secret",

plato/worlds/base.py

@@ -3,7 +3,9 @@
 from __future__ import annotations
 
 import logging
+import subprocess
 from abc import ABC, abstractmethod
+from pathlib import Path
 from typing import TYPE_CHECKING, Any, ClassVar, Generic, TypeVar, get_args, get_origin
 
 from pydantic import BaseModel, Field
@@ -18,6 +20,8 @@ from plato.agents.logging import init_logging as _init_chronos_logging
 from plato.agents.logging import log_event as _log_event
 from plato.agents.logging import reset_logging as _reset_chronos_logging
 from plato.agents.logging import span as _span
+from plato.agents.logging import upload_artifact as _upload_artifact
+from plato.agents.logging import upload_checkpoint as _upload_checkpoint
 
 logger = logging.getLogger(__name__)
 
@@ -195,6 +199,248 @@ class BaseWorld(ABC, Generic[ConfigT]):
             except Exception as e:
                 self.logger.warning(f"Error stopping Plato heartbeat: {e}")
 
+    async def _create_checkpoint(self) -> dict[str, str] | None:
+        """Create a checkpoint snapshot of all environments (excluding configured envs).
+
+        Uses snapshot_store for efficient chunk-based deduplication.
+
+        Returns:
+            Dict mapping environment alias to artifact_id, or None if no session connected.
+        """
+        if not self.plato_session:
+            self.logger.warning("Cannot create checkpoint: Plato session not connected")
+            return None
+
+        exclude_envs = set(self.config.checkpoint.exclude_envs)
+        envs_to_snapshot = [env for env in self.plato_session.envs if env.alias not in exclude_envs]
+
+        if not envs_to_snapshot:
+            self.logger.info("No environments to checkpoint (all excluded)")
+            return {}
+
+        self.logger.info(
+            f"Creating checkpoint for {len(envs_to_snapshot)} environment(s): {[e.alias for e in envs_to_snapshot]}"
+        )
+
+        results: dict[str, str] = {}
+        for env in envs_to_snapshot:
+            try:
+                result = await env.snapshot_store()
+                artifact_id = result.artifact_id
+                results[env.alias] = artifact_id
+
+                # Check for success/error fields (available after SDK regeneration)
+                success = getattr(result, "success", True)
+                error = getattr(result, "error", None)
+
+                if not success or error:
+                    self.logger.error(
+                        f"Checkpoint failed for '{env.alias}': {error or 'unknown error'} (job_id={env.job_id})"
+                    )
+                elif artifact_id:
+                    self.logger.info(f"Checkpoint created for '{env.alias}': {artifact_id}")
+                else:
+                    self.logger.warning(
+                        f"Checkpoint for '{env.alias}' returned empty artifact_id (job_id={env.job_id})"
+                    )
+            except Exception as e:
+                self.logger.error(f"Failed to checkpoint '{env.alias}': {e}")
+
+        return results
+
+    def _init_state_directory(self) -> None:
+        """Initialize the state directory as a git repository.
+
+        Creates the state directory if it doesn't exist and initializes it
+        as a git repository with an initial commit.
+        """
+        if not self.config.state.enabled:
+            return
+
+        state_path = Path(self.config.state.path)
+
+        # Create directory if it doesn't exist
+        if not state_path.exists():
+            state_path.mkdir(parents=True)
+            self.logger.info(f"Created state directory: {state_path}")
+
+        # Check if already a git repo
+        git_dir = state_path / ".git"
+        if git_dir.exists():
+            self.logger.info(f"State directory already initialized: {state_path}")
+            return
+
+        # Initialize git repo
+        try:
+            subprocess.run(
+                ["git", "init"],
+                cwd=state_path,
+                capture_output=True,
+                check=True,
+            )
+            # Create initial commit (even if empty)
+            subprocess.run(
+                ["git", "config", "user.email", "plato@plato.so"],
+                cwd=state_path,
+                capture_output=True,
+                check=True,
+            )
+            subprocess.run(
+                ["git", "config", "user.name", "Plato"],
+                cwd=state_path,
+                capture_output=True,
+                check=True,
+            )
+            # Add all files and create initial commit
+            subprocess.run(
+                ["git", "add", "-A"],
+                cwd=state_path,
+                capture_output=True,
+                check=True,
+            )
+            subprocess.run(
+                ["git", "commit", "--allow-empty", "-m", "Initial state"],
+                cwd=state_path,
+                capture_output=True,
+                check=True,
+            )
+            self.logger.info(f"Initialized git repo in state directory: {state_path}")
+        except subprocess.CalledProcessError as e:
+            self.logger.warning(f"Failed to initialize state git repo: {e.stderr}")
+
+    def _commit_state(self, message: str) -> bool:
+        """Commit current state directory changes.
+
+        Args:
+            message: Commit message
+
+        Returns:
+            True if commit was created (or no changes), False on error.
+        """
+        if not self.config.state.enabled:
+            return True
+
+        state_path = Path(self.config.state.path)
+        if not state_path.exists():
+            return True
+
+        try:
+            # Add all changes
+            subprocess.run(
+                ["git", "add", "-A"],
+                cwd=state_path,
+                capture_output=True,
+                check=True,
+            )
+            # Check if there are changes to commit
+            result = subprocess.run(
+                ["git", "status", "--porcelain"],
+                cwd=state_path,
+                capture_output=True,
+                text=True,
+                check=True,
+            )
+            if not result.stdout.strip():
+                self.logger.debug("No state changes to commit")
+                return True
+
+            # Commit changes
+            subprocess.run(
+                ["git", "commit", "-m", message],
+                cwd=state_path,
+                capture_output=True,
+                check=True,
+            )
+            self.logger.info(f"Committed state changes: {message}")
+            return True
+        except subprocess.CalledProcessError as e:
+            self.logger.warning(f"Failed to commit state: {e.stderr}")
+            return False
+
+    def _create_state_bundle(self) -> bytes | None:
+        """Create a git bundle of the state directory.
+
+        Returns:
+            Bundle bytes if successful, None otherwise.
+        """
+        if not self.config.state.enabled:
+            return None
+
+        state_path = Path(self.config.state.path)
+        if not state_path.exists():
+            return None
+
+        git_dir = state_path / ".git"
+        if not git_dir.exists():
+            self.logger.warning("State directory is not a git repository")
+            return None
+
+        try:
+            # Create bundle to stdout
+            result = subprocess.run(
+                ["git", "bundle", "create", "-", "--all"],
+                cwd=state_path,
+                capture_output=True,
+                check=True,
+            )
+            bundle_data = result.stdout
+            self.logger.info(f"Created state bundle: {len(bundle_data)} bytes")
+            return bundle_data
+        except subprocess.CalledProcessError as e:
+            self.logger.warning(f"Failed to create state bundle: {e.stderr}")
+            return None
+
+    async def _create_and_upload_checkpoint(self) -> dict[str, Any] | None:
+        """Create a full checkpoint including env snapshots and state bundle.
+
+        This method:
+        1. Commits any pending state changes
+        2. Creates env snapshots using snapshot_store
+        3. Creates and uploads state bundle as an artifact
+        4. Calls the checkpoint endpoint with all data
+
+        Returns:
+            Checkpoint result dict if successful, None otherwise.
+        """
+        # Commit state changes first
+        self._commit_state(f"Checkpoint at step {self._step_count}")
+
+        # Create env snapshots
+        env_snapshots = await self._create_checkpoint()
+        if env_snapshots is None:
+            env_snapshots = {}
+
+        # Create and upload state bundle
+        state_artifact_id: str | None = None
+        if self.config.state.enabled:
+            bundle_data = self._create_state_bundle()
+            if bundle_data:
+                result = await _upload_artifact(
+                    data=bundle_data,
+                    artifact_type="state",
+                    filename=f"state_step_{self._step_count}.bundle",
+                    extra={
+                        "step_number": self._step_count,
+                        "state_path": self.config.state.path,
+                    },
+                )
+                if result:
+                    state_artifact_id = result.get("artifact_id")
+                    self.logger.info(f"Uploaded state artifact: {state_artifact_id}")
+
+        # Upload checkpoint with all data
+        checkpoint_result = await _upload_checkpoint(
+            step_number=self._step_count,
+            env_snapshots=env_snapshots,
+            state_artifact_id=state_artifact_id,
+            extra={
+                "world_name": self.name,
+                "world_version": self.get_version(),
+            },
+        )
+
+        return checkpoint_result
+
     def get_env(self, alias: str) -> Environment | None:
         """Get an environment by alias.
 
@@ -236,6 +482,9 @@ class BaseWorld(ABC, Generic[ConfigT]):
         Returns:
             Dict of environment variable name -> value
 
+        Raises:
+            ImportError: If a sim environment is configured but package is not installed.
+
         Example:
             env_vars = self.get_sim_env_vars()
             # Returns: {"AWS_ENDPOINT_URL": "https://...", "GITEA_URL": "https://...", ...}
@@ -263,7 +512,13 @@ class BaseWorld(ABC, Generic[ConfigT]):
                 env_vars.update(sim_vars)
                 self.logger.info(f"{package_name} env vars: {list(sim_vars.keys())}")
             except ImportError:
-                self.logger.debug(f"{package_name} sim package not installed, skipping")
+                raise ImportError(
+                    f"Environment '{env_alias}' is configured but 'plato.sims.{package_name}' "
+                    f"package is not installed.\n\n"
+                    f"Install sims packages:\n"
+                    f'  export INDEX_URL="https://__token__:${{PLATO_API_KEY}}@plato.so/api/v2/pypi/sims/simple/"\n'
+                    f"  uv pip install '.[sims]' --extra-index-url $INDEX_URL"
+                ) from None
             except Exception as e:
                 self.logger.warning(f"Failed to get {package_name} env vars: {e}")
 
@@ -278,6 +533,9 @@ class BaseWorld(ABC, Generic[ConfigT]):
         Returns:
             Markdown string with instructions, or empty string if no sims configured.
 
+        Raises:
+            ImportError: If a sim environment is configured but package is not installed.
+
         Example:
             instructions = self.get_sim_instructions()
             # Returns markdown with LocalStack/Gitea setup instructions
@@ -306,7 +564,13 @@ class BaseWorld(ABC, Generic[ConfigT]):
                         instructions_parts.append(instructions)
                         self.logger.info(f"Added {package_name} instructions to prompt")
             except ImportError:
-                self.logger.debug(f"{package_name} sim package not installed, skipping instructions")
+                raise ImportError(
+                    f"Environment '{env_alias}' is configured but 'plato.sims.{package_name}' "
+                    f"package is not installed.\n\n"
+                    f"Install sims packages:\n"
+                    f'  export INDEX_URL="https://__token__:${{PLATO_API_KEY}}@plato.so/api/v2/pypi/sims/simple/"\n'
+                    f"  uv pip install '.[sims]' --extra-index-url $INDEX_URL"
+                ) from None
             except Exception as e:
                 self.logger.warning(f"Failed to get {package_name} instructions: {e}")
 
@@ -363,6 +627,9 @@ The following services are available for your use:
 
         self.logger.info(f"Starting world '{self.name}'")
 
+        # Initialize state directory (creates git repo if needed)
+        self._init_state_directory()
+
         # Initialize the logging singleton for agents to use
         if config.callback_url and config.session_id:
             _init_chronos_logging(
@@ -415,6 +682,13 @@ The following services are available for your use:
 
                 self.logger.info(f"Step {self._step_count}: done={result.done}")
 
+                # Create checkpoint if enabled and interval matches
+                # Note: The checkpoint event is created by the callback endpoint,
+                # so we don't need a span wrapper here (would create duplicates)
+                if self.config.checkpoint.enabled and self._step_count % self.config.checkpoint.interval == 0:
+                    self.logger.info(f"Creating checkpoint after step {self._step_count}")
+                    await self._create_and_upload_checkpoint()
+
                 if result.done:
                     break
 

plato/worlds/config.py

@@ -72,6 +72,36 @@ class Env:
         self.required = required
 
 
+class StateConfig(BaseModel):
+    """Configuration for world state persistence.
+
+    The state directory is a git-tracked directory that persists across checkpoints.
+    At each checkpoint, the state directory is git bundled and uploaded as an artifact.
+    On restore, bootstrap.sh downloads and unbundles the state before the world starts.
+
+    Attributes:
+        enabled: Whether to enable state persistence (default: True).
+        path: Path to the state directory (default: /state).
+    """
+
+    enabled: bool = True
+    path: str = "/state"
+
+
+class CheckpointConfig(BaseModel):
+    """Configuration for automatic checkpointing during world execution.
+
+    Attributes:
+        enabled: Whether to enable automatic checkpoints after steps.
+        interval: Create checkpoint every N steps (default: 1 = every step).
+        exclude_envs: Environment aliases to exclude from checkpoints (default: ["runtime"]).
+    """
+
+    enabled: bool = True
+    interval: int = 1
+    exclude_envs: list[str] = Field(default_factory=lambda: ["runtime"])
+
+
 class RunConfig(BaseModel):
     """Base configuration for running a world.
 
@@ -98,6 +128,7 @@ class RunConfig(BaseModel):
         session_id: Unique Chronos session identifier
         callback_url: Callback URL for status updates
         plato_session: Serialized Plato session for connecting to existing VM session
+        checkpoint: Configuration for automatic checkpoints after steps
     """
 
     session_id: str = ""
@@ -108,6 +139,12 @@ class RunConfig(BaseModel):
     # This is the output of Session.dump() - used to restore session with Session.load()
     plato_session: SerializedSession | None = None
 
+    # Checkpoint configuration for automatic snapshots after steps
+    checkpoint: CheckpointConfig = Field(default_factory=CheckpointConfig)
+
+    # State persistence configuration
+    state: StateConfig = Field(default_factory=StateConfig)
+
     model_config = {"extra": "allow"}
 
     @classmethod
@@ -145,7 +182,7 @@ class RunConfig(BaseModel):
         envs = []
 
         # Skip runtime fields
-        runtime_fields = {"session_id", "callback_url", "all_secrets", "plato_session"}
+        runtime_fields = {"session_id", "callback_url", "all_secrets", "plato_session", "checkpoint", "state"}
 
         for field_name, prop_schema in properties.items():
             if field_name in runtime_fields:

plato/worlds/runner.py

@@ -246,12 +246,49 @@ def _extract_agent_images_from_config(config_data: dict) -> list[str]:
     return images
 
 
+async def _create_chronos_session(
+    chronos_url: str,
+    api_key: str,
+    world_name: str,
+    world_config: dict,
+    plato_session_id: str | None = None,
+) -> tuple[str, str]:
+    """Create a session in Chronos.
+
+    Args:
+        chronos_url: Chronos base URL (e.g., https://chronos.plato.so)
+        api_key: Plato API key for authentication
+        world_name: Name of the world being run
+        world_config: World configuration dict
+        plato_session_id: Optional Plato session ID if already created
+
+    Returns:
+        Tuple of (session_id, callback_url)
+    """
+    import httpx
+
+    url = f"{chronos_url.rstrip('/')}/api/sessions"
+
+    async with httpx.AsyncClient(timeout=30.0) as client:
+        response = await client.post(
+            url,
+            json={
+                "world_name": world_name,
+                "world_config": world_config,
+                "plato_session_id": plato_session_id,
+            },
+            headers={"x-api-key": api_key},
+        )
+        response.raise_for_status()
+        data = response.json()
+
+    return data["public_id"], data["callback_url"]
+
+
 async def _run_dev(
     world_name: str,
     config_path: Path,
     env_timeout: int = 600,
-    chronos_url: str | None = None,
-    api_key: str | None = None,
     agents_dir: Path | None = None,
 ) -> None:
     """Run a world locally with automatic environment creation.
@@ -260,22 +297,31 @@ async def _run_dev(
     1. Load and parse the config
     2. Build local agent images if --agents-dir is provided
     3. Create Plato session with all environments
-    4. Optionally initialize Chronos logging for callbacks
+    4. Create Chronos session for logging/callbacks
     5. Run the world with the session attached
 
+    Requires environment variables:
+        CHRONOS_URL: Chronos base URL (e.g., https://chronos.plato.so)
+        PLATO_API_KEY: API key for Plato and Chronos authentication
+
     Args:
         world_name: Name of the world to run
         config_path: Path to the config JSON file
         env_timeout: Timeout for environment creation (seconds)
-        chronos_url: Optional Chronos base URL for sending log events
-        api_key: Optional Plato API key (used for Chronos session creation)
         agents_dir: Optional directory containing agent source code
     """
-    from uuid import uuid4
-
     from plato.v2 import AsyncPlato
     from plato.worlds.base import get_world
 
+    # Get required env vars
+    chronos_url = os.environ.get("CHRONOS_URL")
+    api_key = os.environ.get("PLATO_API_KEY")
+
+    if not chronos_url:
+        raise ValueError("CHRONOS_URL environment variable is required")
+    if not api_key:
+        raise ValueError("PLATO_API_KEY environment variable is required")
+
     discover_worlds()
 
     world_cls = get_world(world_name)
@@ -316,29 +362,14 @@ async def _run_dev(
     # Create Plato client
     plato = AsyncPlato()
     session = None
-
-    # Initialize Chronos logging if URL provided
-    chronos_session_id: str | None = None
-    if chronos_url:
-        from plato.agents import init_logging
-
-        chronos_session_id = f"dev-{uuid4().hex[:8]}"
-        callback_url = f"{chronos_url.rstrip('/')}/api/v1/callback"
-        init_logging(
-            callback_url=callback_url,
-            session_id=chronos_session_id,
-        )
-        logger.info(f"Chronos logging enabled: {callback_url} (session: {chronos_session_id})")
-
-        # Update run_config with session info for agents
-        run_config.session_id = chronos_session_id
-        run_config.callback_url = callback_url
+    plato_session_id: str | None = None
 
     try:
         if env_configs:
             logger.info(f"Creating {len(env_configs)} environments...")
             session = await plato.sessions.create(envs=env_configs, timeout=env_timeout)
-            logger.info(f"Created Plato session: {session.session_id}")
+            plato_session_id = session.session_id
+            logger.info(f"Created Plato session: {plato_session_id}")
             logger.info(f"Environments: {[e.alias for e in session.envs]}")
 
             # Serialize and add to config
@@ -347,6 +378,30 @@ async def _run_dev(
         else:
             logger.info("No environments defined for this world")
 
+        # Create Chronos session (after Plato session so we can link them)
+        logger.info(f"Creating Chronos session at {chronos_url}...")
+        chronos_session_id, callback_url = await _create_chronos_session(
+            chronos_url=chronos_url,
+            api_key=api_key,
+            world_name=world_name,
+            world_config=config_data,
+            plato_session_id=plato_session_id,
+        )
+        logger.info(f"Created Chronos session: {chronos_session_id}")
+        logger.info(f"View at: {chronos_url}/sessions/{chronos_session_id}")
+
+        # Initialize logging
+        from plato.agents import init_logging
+
+        init_logging(
+            callback_url=callback_url,
+            session_id=chronos_session_id,
+        )
+
+        # Update run_config with session info for agents
+        run_config.session_id = chronos_session_id
+        run_config.callback_url = callback_url
+
         # Run the world
         logger.info(f"Starting world '{world_name}'...")
         world_instance = world_cls()
@@ -360,10 +415,9 @@ async def _run_dev(
         await plato.close()
 
         # Reset logging
-        if chronos_url:
-            from plato.agents import reset_logging
+        from plato.agents import reset_logging
 
-            reset_logging()
+        reset_logging()
 
 
 def _setup_colored_logging(verbose: bool = False) -> None:
@@ -411,10 +465,6 @@ def dev(
     world: Annotated[str, typer.Option("--world", "-w", help="World name to run")],
     config: Annotated[Path, typer.Option("--config", "-c", help="Path to config JSON file")],
     env_timeout: Annotated[int, typer.Option("--env-timeout", help="Timeout for environment creation (seconds)")] = 600,
-    chronos_url: Annotated[
-        str | None, typer.Option("--chronos-url", help="Chronos base URL for log events (e.g., http://localhost:8000)")
-    ] = None,
-    api_key: Annotated[str | None, typer.Option("--api-key", help="Plato API key for Chronos authentication")] = None,
     agents_dir: Annotated[
         Path | None,
         typer.Option("--agents-dir", "-a", help="Directory containing agent source code (builds local images)"),
@@ -423,10 +473,8 @@ def dev(
 ) -> None:
     """Run a world locally for development/debugging.
 
-    This creates Plato environments automatically (like Chronos does)
-    and runs the world with the session attached.
-
-    Optionally sends log events to a Chronos server for real-time monitoring.
+    This creates Plato environments automatically (like Chronos does),
+    creates a Chronos session for logging, and runs the world.
 
     Example config.json:
     {
@@ -440,18 +488,16 @@ def dev(
         }
     }
 
-    Environment variables:
-        PLATO_API_KEY: API key for Plato (required)
+    Required environment variables:
+        CHRONOS_URL: Chronos base URL (e.g., https://chronos.plato.so)
+        PLATO_API_KEY: API key for Plato and Chronos authentication
 
     Examples:
         # Basic usage
-        plato-world-runner dev -w code -c config.json
+        CHRONOS_URL=https://chronos.plato.so plato-world-runner dev -w code -c config.json
 
         # With local agent builds (from plato-client repo)
         plato-world-runner dev -w code -c config.json --agents-dir ~/plato-client/agents
-
-        # With Chronos logging
-        plato-world-runner dev -w code -c config.json --chronos-url http://localhost:8000
     """
     # Setup colored logging with filtered noisy loggers
     _setup_colored_logging(verbose)
@@ -460,12 +506,16 @@ def dev(
         typer.echo(f"Error: Config file not found: {config}", err=True)
         raise typer.Exit(1)
 
+    if not os.environ.get("CHRONOS_URL"):
+        typer.echo("Error: CHRONOS_URL environment variable required", err=True)
+        raise typer.Exit(1)
+
     if not os.environ.get("PLATO_API_KEY"):
         typer.echo("Error: PLATO_API_KEY environment variable required", err=True)
         raise typer.Exit(1)
 
     try:
-        asyncio.run(_run_dev(world, config, env_timeout, chronos_url, api_key, agents_dir))
+        asyncio.run(_run_dev(world, config, env_timeout, agents_dir))
     except Exception as e:
         logger.exception(f"World execution failed: {e}")
         raise typer.Exit(1)

{plato_sdk_v2-2.3.1.dist-info → plato_sdk_v2-2.3.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plato-sdk-v2
-Version: 2.3.1
+Version: 2.3.2
 Summary: Python SDK for the Plato API
 Author-email: Plato <support@plato.so>
 License-Expression: MIT
@@ -44,6 +44,7 @@ Description-Content-Type: text/markdown
 
 # Plato Python SDK
 
+
 Python SDK for the Plato platform. Uses [Harbor](https://harborframework.com) for agent execution.
 
 ## Installation

{plato_sdk_v2-2.3.1.dist-info → plato_sdk_v2-2.3.2.dist-info}/RECORD

@@ -297,11 +297,11 @@ plato/_sims_generator/templates/python/errors.py.jinja,sha256=8L_FbHczBNLXJrbSlN
 plato/_sims_generator/templates/python/package_init.py.jinja,sha256=sOcJxUT0LuOWu5jOMGGKYxfCEjcYQv1hGF3n0iOA4hQ,986
 plato/_sims_generator/templates/python/tag_init.py.jinja,sha256=WB_9cv0JKIVg5TOXeSolET3tAfVg7sExjboh5jbCXz4,170
 plato/_sims_generator/templates/python/version_init.py.jinja,sha256=sGvFcYVfzXFyQDAe0PSOrg9yys93KE0XInFQNb1TvCY,179
-plato/agents/__init__.py,sha256=qslIFTVSe1yFeTRCKr8Z-mInWarj2HDbNZV4u6AiXek,2755
+plato/agents/__init__.py,sha256=1l-Vw5SFydmPsl1toXdc2oH3eLhFwz6jtI_DKUx4vmo,2847
 plato/agents/base.py,sha256=vUbPQuNSo6Ka2lIB_ZOXgi4EoAjtAD7GIj9LnNotam0,4577
 plato/agents/build.py,sha256=CNMbVQFs2_pYit1dA29Davve28Yi4c7TNK9wBB7odrE,1621
 plato/agents/config.py,sha256=VZVMdCmEQnoR0VkrGdScG8p6zSKVFe7BZPd2h8lKNjI,5460
-plato/agents/logging.py,sha256=z9rDlGPbrpcTS8PephbK2rDqT7thC1KyLkua4ypUkv4,12210
+plato/agents/logging.py,sha256=bL3Q14YeFxWCQydGKrQzQPgKQzBoCCXy_AAQPZpBylU,16307
 plato/agents/runner.py,sha256=k3t6TZYfk0K4efpjNUmMbRd76KPyiQs5BRCfU53RZHA,6721
 plato/agents/trajectory.py,sha256=WdiBmua0KvCrNaM3qgPI7-7B4xmSkfbP4oZ_9_8qHzU,10529
 plato/chronos/__init__.py,sha256=RHMvSrQS_-vkKOyTRuAkp2gKDP1HEuBLDnw8jcZs1Jg,739
@@ -463,12 +463,12 @@ plato/v2/utils/db_cleanup.py,sha256=lnI5lsMHNHpG85Y99MaE4Rzc3618piuzhvH-uXO1zIc,
 plato/v2/utils/models.py,sha256=PwehSSnIRG-tM3tWL1PzZEH77ZHhIAZ9R0UPs6YknbM,1441
 plato/v2/utils/proxy_tunnel.py,sha256=8ZTd0jCGSfIHMvSv1fgEyacuISWnGPHLPbDglWroTzY,10463
 plato/worlds/README.md,sha256=TgG4aidude0ouJSCfY81Ev45hsUxPkO85HUIiWNqkcc,5463
-plato/worlds/__init__.py,sha256=crzpXFh4XD8eS4pYFTEUf3XgUf0wapFPT4npAu8sWwk,2078
-plato/worlds/base.py,sha256=254kR0YmRaaOyenDC1jlRhNlEsENgUpcq-crkWJcRe8,15200
+plato/worlds/__init__.py,sha256=ALoou3l5lXvs_YZc5eH6HdMHpvhnpzKWqz__aSC1jFc,2152
+plato/worlds/base.py,sha256=KsDq1TVVd4BKEFo42WodF4DPgodr00Gd1NrfzZEPqyw,25632
 plato/worlds/build_hook.py,sha256=KSoW0kqa5b7NyZ7MYOw2qsZ_2FkWuz0M3Ru7AKOP7Qw,3486
-plato/worlds/config.py,sha256=ggDcySspfeFry2KBUwhgnS6Po2KssYzwZNIDmVeGhPQ,9460
-plato/worlds/runner.py,sha256=RNnWFQ7rfEWE7TQ_tqgLHgLm1a4VxtP0mR7beALx4f0,15781
-plato_sdk_v2-2.3.1.dist-info/METADATA,sha256=pNXvkxBj-N1xWHG_UWZ6TFzR9PPlwW_aqMYCl6lk57I,8508
-plato_sdk_v2-2.3.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-plato_sdk_v2-2.3.1.dist-info/entry_points.txt,sha256=upGMbJCx6YWUTKrPoYvYUYfFCqYr75nHDwhA-45m6p8,136
-plato_sdk_v2-2.3.1.dist-info/RECORD,,
+plato/worlds/config.py,sha256=fkWoetCawIPf5xgj5EyJCvopmPPzZQAqt0Ke9P4hq5c,10845
+plato/worlds/runner.py,sha256=306dZrH1NSUxXcA4oJSlmOfSSfwHtH7KMquPvgxxbCI,17255
+plato_sdk_v2-2.3.2.dist-info/METADATA,sha256=0Qy3LhEnq8ZEKOcQgkV0t9Kcd37I6X2_7fClGV6ZHtg,8509
+plato_sdk_v2-2.3.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+plato_sdk_v2-2.3.2.dist-info/entry_points.txt,sha256=upGMbJCx6YWUTKrPoYvYUYfFCqYr75nHDwhA-45m6p8,136
+plato_sdk_v2-2.3.2.dist-info/RECORD,,