plato-sdk-v2 2.2.2__tar.gz → 2.2.3__tar.gz

{plato_sdk_v2-2.2.2 → plato_sdk_v2-2.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plato-sdk-v2
-Version: 2.2.2
+Version: 2.2.3
 Summary: Python SDK for the Plato API
 Author-email: Plato <support@plato.so>
 License-Expression: MIT

plato_sdk_v2-2.2.3/VERSION

@@ -0,0 +1 @@
+2.2.3

{plato_sdk_v2-2.2.2 → plato_sdk_v2-2.2.3}/plato/agents/runner.py

@@ -6,6 +6,7 @@ import asyncio
 import json
 import logging
 import os
+import platform
 import tempfile
 from pathlib import Path
 
@@ -62,21 +63,29 @@ async def run_agent(
             # Build docker command
             docker_cmd = ["docker", "run", "--rm"]
 
-            # Check if iptables is available for network isolation
-            try:
-                proc = await asyncio.create_subprocess_exec(
-                    "iptables",
-                    "-L",
-                    "-n",
-                    stdout=asyncio.subprocess.DEVNULL,
-                    stderr=asyncio.subprocess.DEVNULL,
-                )
-                await proc.wait()
-                has_iptables = proc.returncode == 0
-            except (FileNotFoundError, PermissionError):
-                has_iptables = False
-
-            if not has_iptables:
+            # Determine if we need host networking:
+            # - Required on Linux without iptables for connectivity
+            # - Skip on macOS where --network=host doesn't work properly
+            use_host_network = False
+            is_macos = platform.system() == "Darwin"
+
+            if not is_macos:
+                try:
+                    proc = await asyncio.create_subprocess_exec(
+                        "iptables",
+                        "-L",
+                        "-n",
+                        stdout=asyncio.subprocess.DEVNULL,
+                        stderr=asyncio.subprocess.DEVNULL,
+                    )
+                    await proc.wait()
+                    has_iptables = proc.returncode == 0
+                except (FileNotFoundError, PermissionError):
+                    has_iptables = False
+
+                use_host_network = not has_iptables
+
+            if use_host_network:
                 docker_cmd.extend(["--network=host", "--add-host=localhost:127.0.0.1"])
 
             docker_cmd.extend(
@@ -96,6 +105,8 @@ async def run_agent(
                 docker_cmd.extend(["-e", f"{key.upper()}={value}"])
 
             docker_cmd.append(image)
+
+            # Pass instruction via CLI arg (agents expect --instruction flag)
             docker_cmd.extend(["--instruction", instruction])
 
             # Run container and stream output

{plato_sdk_v2-2.2.2 → plato_sdk_v2-2.2.3}/plato/worlds/base.py

@@ -145,6 +145,7 @@ class BaseWorld(ABC, Generic[ConfigT]):
             "required": schema.get("required", []),
             "agents": schema.get("agents", []),
             "secrets": schema.get("secrets", []),
+            "envs": schema.get("envs", []),
         }
 
     @abstractmethod

plato_sdk_v2-2.2.3/plato/worlds/runner.py

@@ -0,0 +1,480 @@
+"""World runner - discovers and runs Plato worlds."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import platform
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from plato.worlds.config import EnvConfig, RunConfig
+
+app = typer.Typer(
+    name="plato-world-runner",
+    help="Run Plato worlds",
+    no_args_is_help=True,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def discover_worlds() -> None:
+    """Discover and load installed world packages via entry points.
+
+    World packages declare entry points in pyproject.toml:
+        [project.entry-points."plato.worlds"]
+        code = "code_world:CodeWorld"
+
+    This function loads all such entry points, triggering registration.
+    """
+    import importlib.metadata
+
+    try:
+        eps = importlib.metadata.entry_points(group="plato.worlds")
+    except TypeError:
+        # Python < 3.10 compatibility
+        eps = importlib.metadata.entry_points().get("plato.worlds", [])
+
+    for ep in eps:
+        try:
+            ep.load()
+            logger.debug(f"Loaded world: {ep.name}")
+        except Exception as e:
+            logger.warning(f"Failed to load world '{ep.name}': {e}")
+
+
+async def run_world(world_name: str, config: RunConfig) -> None:
+    """Run a world by name with the given configuration.
+
+    Args:
+        world_name: Name of the world to run
+        config: Run configuration (should be the world's typed config class)
+
+    Raises:
+        ValueError: If world not found
+    """
+    discover_worlds()
+
+    from plato.worlds.base import get_registered_worlds, get_world
+
+    world_cls = get_world(world_name)
+    if world_cls is None:
+        available = list(get_registered_worlds().keys())
+        raise ValueError(f"World '{world_name}' not found. Available: {available}")
+
+    world = world_cls()
+    await world.run(config)
+
+
+@app.command()
+def run(
+    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")],
+    verbose: Annotated[bool, typer.Option("--verbose", "-v", help="Enable verbose logging")] = False,
+) -> None:
+    """Run a world with the given configuration."""
+    # Setup logging
+    log_level = logging.DEBUG if verbose else logging.INFO
+    logging.basicConfig(
+        level=log_level,
+        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+    )
+
+    if not config.exists():
+        typer.echo(f"Error: Config file not found: {config}", err=True)
+        raise typer.Exit(1)
+
+    # Discover worlds first to get config class
+    discover_worlds()
+
+    from plato.worlds.base import get_registered_worlds, get_world
+
+    world_cls = get_world(world)
+    if world_cls is None:
+        available = list(get_registered_worlds().keys())
+        typer.echo(f"Error: World '{world}' not found. Available: {available}", err=True)
+        raise typer.Exit(1)
+
+    # Load config using the world's typed config class
+    config_class = world_cls.get_config_class()
+    run_config = config_class.from_file(config)
+
+    try:
+        world_instance = world_cls()
+        asyncio.run(world_instance.run(run_config))
+    except Exception as e:
+        logger.exception(f"World execution failed: {e}")
+        raise typer.Exit(1)
+
+
+@app.command("list")
+def list_worlds(
+    verbose: Annotated[bool, typer.Option("--verbose", "-v", help="Enable verbose logging")] = False,
+) -> None:
+    """List available worlds."""
+    if verbose:
+        logging.basicConfig(level=logging.DEBUG)
+
+    discover_worlds()
+
+    from plato.worlds.base import get_registered_worlds
+
+    worlds = get_registered_worlds()
+    if not worlds:
+        typer.echo("No worlds found.")
+        return
+
+    typer.echo("Available worlds:")
+    for name, cls in worlds.items():
+        desc = getattr(cls, "description", "") or ""
+        version = cls.get_version()
+        typer.echo(f"  {name} (v{version}): {desc}")
+
+
+async def _build_agent_image(
+    agent_name: str,
+    agents_dir: Path,
+    plato_client_root: Path | None = None,
+) -> bool:
+    """Build a local agent Docker image.
+
+    Args:
+        agent_name: Name of the agent (e.g., "openhands")
+        agents_dir: Directory containing agent subdirectories
+        plato_client_root: Root of plato-client repo (for dev builds), or None for prod builds
+
+    Returns:
+        True if build succeeded, False otherwise
+    """
+    import subprocess
+
+    # Resolve paths to absolute
+    agents_dir = agents_dir.expanduser().resolve()
+    agent_path = agents_dir / agent_name
+    dockerfile_path = agent_path / "Dockerfile"
+
+    if not dockerfile_path.exists():
+        logger.warning(f"No Dockerfile found for agent '{agent_name}' at {dockerfile_path}")
+        return False
+
+    image_tag = f"{agent_name}:latest"
+
+    # Determine build context and target
+    if plato_client_root:
+        plato_client_root = plato_client_root.expanduser().resolve()
+
+    if plato_client_root and plato_client_root.exists():
+        # Dev build from plato-client root (includes local python-sdk)
+        build_context = str(plato_client_root)
+        dockerfile_abs = str(dockerfile_path)
+        target = "dev"
+        logger.info(f"Building {image_tag} (dev mode from {build_context})...")
+    else:
+        # Prod build from agent directory
+        build_context = str(agent_path)
+        dockerfile_abs = str(dockerfile_path)
+        target = "prod"
+        logger.info(f"Building {image_tag} (prod mode from {build_context})...")
+
+    cmd = [
+        "docker",
+        "build",
+        "--target",
+        target,
+        "-t",
+        image_tag,
+        "-f",
+        dockerfile_abs,
+    ]
+
+    # Use native platform for local dev on ARM Macs (avoids slow emulation)
+    if platform.machine() == "arm64":
+        cmd.extend(["--build-arg", "PLATFORM=linux/arm64"])
+
+    cmd.append(build_context)
+
+    logger.debug(f"Build command: {' '.join(cmd)}")
+
+    result = subprocess.run(cmd, capture_output=True, text=True)
+
+    if result.returncode != 0:
+        logger.error(f"Failed to build {image_tag}:\n{result.stderr}")
+        return False
+
+    logger.info(f"Successfully built {image_tag}")
+    return True
+
+
+def _extract_agent_images_from_config(config_data: dict) -> list[str]:
+    """Extract agent image names from config data.
+
+    Args:
+        config_data: Raw config dictionary
+
+    Returns:
+        List of image names (without tags) that are local (not from a registry)
+    """
+    images = []
+
+    # Check agents section
+    agents = config_data.get("agents", {})
+    for agent_config in agents.values():
+        if isinstance(agent_config, dict):
+            image = agent_config.get("image", "")
+            # Only include local images (no registry prefix like ghcr.io/)
+            if image and "/" not in image.split(":")[0]:
+                # Extract name without tag
+                name = image.split(":")[0]
+                if name not in images:
+                    images.append(name)
+
+    # Also check direct coder/verifier fields
+    for field in ["coder", "verifier"]:
+        agent_config = config_data.get(field, {})
+        if isinstance(agent_config, dict):
+            image = agent_config.get("image", "")
+            if image and "/" not in image.split(":")[0]:
+                name = image.split(":")[0]
+                if name not in images:
+                    images.append(name)
+
+    return images
+
+
+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.
+
+    This mimics what Chronos does but runs locally for debugging:
+    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
+    5. Run the world with the session attached
+
+    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
+
+    discover_worlds()
+
+    world_cls = get_world(world_name)
+    if world_cls is None:
+        from plato.worlds.base import get_registered_worlds
+
+        available = list(get_registered_worlds().keys())
+        raise ValueError(f"World '{world_name}' not found. Available: {available}")
+
+    # Load config
+    config_class = world_cls.get_config_class()
+    with open(config_path) as f:
+        config_data = json.load(f)
+
+    # Parse the config to get typed access
+    run_config = config_class._from_dict(config_data.copy())
+
+    # Build local agent images if agents_dir is provided
+    if agents_dir:
+        # Resolve agents_dir to absolute path
+        agents_dir = agents_dir.expanduser().resolve()
+        agent_images = _extract_agent_images_from_config(config_data)
+        if agent_images:
+            logger.info(f"Building local agent images: {agent_images}")
+            # Determine if we're in a plato-client repo for dev builds
+            # (agents_dir is something like /path/to/plato-client/agents)
+            plato_client_root = agents_dir.parent if agents_dir.name == "agents" else None
+            for agent_name in agent_images:
+                success = await _build_agent_image(agent_name, agents_dir, plato_client_root)
+                if not success:
+                    raise RuntimeError(f"Failed to build agent image: {agent_name}")
+        else:
+            logger.info("No local agent images found in config")
+
+    # Get environment configs from the parsed config
+    env_configs: list[EnvConfig] = run_config.get_envs()
+
+    # 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
+
+    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}")
+            logger.info(f"Environments: {[e.alias for e in session.envs]}")
+
+            # Serialize and add to config
+            serialized = session.dump()
+            run_config.plato_session = serialized
+        else:
+            logger.info("No environments defined for this world")
+
+        # Run the world
+        logger.info(f"Starting world '{world_name}'...")
+        world_instance = world_cls()
+        await world_instance.run(run_config)
+
+    finally:
+        # Cleanup
+        if session:
+            logger.info("Closing Plato session...")
+            await session.close()
+        await plato.close()
+
+        # Reset logging
+        if chronos_url:
+            from plato.agents import reset_logging
+
+            reset_logging()
+
+
+def _setup_colored_logging(verbose: bool = False) -> None:
+    """Setup colored logging with filtered noisy loggers."""
+    log_level = logging.DEBUG if verbose else logging.INFO
+
+    # Define colors for different log levels
+    colors = {
+        "DEBUG": "\033[36m",  # Cyan
+        "INFO": "\033[32m",  # Green
+        "WARNING": "\033[33m",  # Yellow
+        "ERROR": "\033[31m",  # Red
+        "CRITICAL": "\033[35m",  # Magenta
+    }
+    reset = "\033[0m"
+
+    class ColoredFormatter(logging.Formatter):
+        def format(self, record: logging.LogRecord) -> str:
+            color = colors.get(record.levelname, "")
+            record.levelname = f"{color}{record.levelname}{reset}"
+            record.name = f"\033[34m{record.name}{reset}"  # Blue for logger name
+            return super().format(record)
+
+    # Create handler with colored formatter
+    handler = logging.StreamHandler()
+    handler.setFormatter(
+        ColoredFormatter(
+            "%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+            datefmt="%H:%M:%S",
+        )
+    )
+
+    # Configure root logger
+    root_logger = logging.getLogger()
+    root_logger.setLevel(log_level)
+    root_logger.handlers = [handler]
+
+    # Silence noisy HTTP loggers
+    for noisy_logger in ["httpcore", "httpx", "urllib3", "hpack"]:
+        logging.getLogger(noisy_logger).setLevel(logging.WARNING)
+
+
+@app.command("dev")
+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)"),
+    ] = None,
+    verbose: Annotated[bool, typer.Option("--verbose", "-v", help="Enable verbose logging")] = False,
+) -> 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.
+
+    Example config.json:
+    {
+        "instruction": "Create a git repo and upload files to S3",
+        "coder": {
+            "image": "openhands:latest",
+            "config": {"model_name": "gemini/gemini-3-flash-preview"}
+        },
+        "secrets": {
+            "gemini_api_key": "..."
+        }
+    }
+
+    Environment variables:
+        PLATO_API_KEY: API key for Plato (required)
+
+    Examples:
+        # Basic usage
+        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)
+
+    if not config.exists():
+        typer.echo(f"Error: Config file not found: {config}", 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))
+    except Exception as e:
+        logger.exception(f"World execution failed: {e}")
+        raise typer.Exit(1)
+
+
+def main() -> None:
+    """CLI entry point."""
+    app()
+
+
+if __name__ == "__main__":
+    main()

plato_sdk_v2-2.2.2/VERSION

@@ -1 +0,0 @@
-2.2.2