plato-sdk-v2 2.1.16__py3-none-any.whl → 2.1.17__py3-none-any.whl

plato/worlds/__init__.py

@@ -1,7 +1,8 @@
 """Plato Worlds - typed world definitions for agent execution.
 
 Usage:
-    from plato.worlds import BaseWorld, RunConfig, Agent, Secret, AgentConfig, register_world
+    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):
@@ -15,6 +16,12 @@ Usage:
         # 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[CodeWorldConfig]):
         name = "code"
@@ -25,11 +32,17 @@ Usage:
             url = self.config.repository_url
             agent = self.config.coder
             token = self.config.git_token
+            gitea = self.config.gitea  # EnvConfig
 
         async def step(self) -> StepResult:
             ...
 """
 
+from plato._generated.models import (
+    EnvFromArtifact,
+    EnvFromResource,
+    EnvFromSimulator,
+)
 from plato.worlds.base import (
     BaseWorld,
     ConfigT,
@@ -39,7 +52,7 @@ from plato.worlds.base import (
     get_world,
     register_world,
 )
-from plato.worlds.config import Agent, AgentConfig, RunConfig, Secret
+from plato.worlds.config import Agent, AgentConfig, Env, EnvConfig, RunConfig, Secret
 from plato.worlds.runner import run_world
 
 __all__ = [
@@ -56,6 +69,12 @@ __all__ = [
     "AgentConfig",
     "Agent",
     "Secret",
+    "Env",
+    "EnvConfig",
+    # Env types (re-exported from generated models)
+    "EnvFromArtifact",
+    "EnvFromSimulator",
+    "EnvFromResource",
     # Runner
     "run_world",
 ]

plato/worlds/base.py

@@ -11,6 +11,7 @@ from pydantic import BaseModel, Field
 from plato.worlds.config import RunConfig
 
 if TYPE_CHECKING:
+    from plato.v2.async_.environment import Environment
     from plato.v2.async_.session import Session
 
 from plato.agents.logging import init_logging as _init_chronos_logging
@@ -193,6 +194,38 @@ class BaseWorld(ABC, Generic[ConfigT]):
             except Exception as e:
                 self.logger.warning(f"Error stopping Plato heartbeat: {e}")
 
+    def get_env(self, alias: str) -> Environment | None:
+        """Get an environment by alias.
+
+        Use this to access environments defined in the world config (e.g., gitea, localstack).
+
+        Args:
+            alias: The environment alias (e.g., "gitea", "localstack", "runtime")
+
+        Returns:
+            The Environment object or None if not found or session not connected.
+
+        Example:
+            gitea = self.get_env("gitea")
+            if gitea:
+                result = await gitea.execute("git status")
+        """
+        if not self.plato_session:
+            self.logger.warning("Cannot get env: Plato session not connected")
+            return None
+        return self.plato_session.get_env(alias)
+
+    @property
+    def envs(self) -> list[Environment]:
+        """Get all environments in the Plato session.
+
+        Returns:
+            List of Environment objects. Empty list if session not connected.
+        """
+        if not self.plato_session:
+            return []
+        return self.plato_session.envs
+
     async def run(self, config: ConfigT) -> None:
         """Run the world: reset -> step until done -> close.
 

plato/worlds/config.py

@@ -3,12 +3,20 @@
 from __future__ import annotations
 
 from pathlib import Path
-from typing import Any
+from typing import Any, Union
 
 from pydantic import BaseModel, Field
 
+from plato._generated.models import (
+    EnvFromArtifact,
+    EnvFromResource,
+    EnvFromSimulator,
+)
 from plato.v2.async_.session import SerializedSession
 
+# Union type for environment configurations
+EnvConfig = Union[EnvFromArtifact, EnvFromSimulator, EnvFromResource]
+
 
 class AgentConfig(BaseModel):
     """Configuration for an agent.
@@ -46,10 +54,28 @@ class Secret:
         self.required = required
 
 
+class Env:
+    """Annotation marker for environment fields.
+
+    Environments are VMs that run alongside the world's runtime.
+    They can be specified by artifact ID, simulator name, or resource config.
+
+    Usage:
+        gitea: Annotated[EnvConfig, Env(description="Git server")] = EnvFromArtifact(
+            artifact_id="abc123",
+            alias="gitea",
+        )
+    """
+
+    def __init__(self, description: str = "", required: bool = True):
+        self.description = description
+        self.required = required
+
+
 class RunConfig(BaseModel):
     """Base configuration for running a world.
 
-    Subclass this with your world-specific fields, agents, and secrets:
+    Subclass this with your world-specific fields, agents, secrets, and envs:
 
         class CodeWorldConfig(RunConfig):
             # World-specific fields
@@ -62,6 +88,12 @@ class RunConfig(BaseModel):
             # 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",
+            )
+
     Attributes:
         session_id: Unique Chronos session identifier
         callback_url: Callback URL for status updates
@@ -79,16 +111,16 @@ class RunConfig(BaseModel):
     model_config = {"extra": "allow"}
 
     @classmethod
-    def get_field_annotations(cls) -> dict[str, Agent | Secret | None]:
-        """Get Agent/Secret annotations for each field."""
-        result: dict[str, Agent | Secret | None] = {}
+    def get_field_annotations(cls) -> dict[str, Agent | Secret | Env | None]:
+        """Get Agent/Secret/Env annotations for each field."""
+        result: dict[str, Agent | Secret | Env | None] = {}
 
         for field_name, field_info in cls.model_fields.items():
             marker = None
 
             # Pydantic stores Annotated metadata in field_info.metadata
             for meta in field_info.metadata:
-                if isinstance(meta, (Agent, Secret)):
+                if isinstance(meta, (Agent, Secret, Env)):
                     marker = meta
                     break
 
@@ -98,7 +130,7 @@ class RunConfig(BaseModel):
 
     @classmethod
     def get_json_schema(cls) -> dict:
-        """Get JSON schema with agents and secrets separated."""
+        """Get JSON schema with agents, secrets, and envs separated."""
         # Get full Pydantic schema
         full_schema = cls.model_json_schema()
         full_schema.pop("title", None)
@@ -110,6 +142,7 @@ class RunConfig(BaseModel):
         world_properties = {}
         agents = []
         secrets = []
+        envs = []
 
         # Skip runtime fields
         runtime_fields = {"session_id", "callback_url", "all_secrets", "plato_session"}
@@ -136,6 +169,26 @@ class RunConfig(BaseModel):
                         "required": marker.required,
                     }
                 )
+            elif isinstance(marker, Env):
+                # Get default value for this env field
+                field_info = cls.model_fields.get(field_name)
+                default_value = None
+                if field_info and field_info.default is not None:
+                    # Serialize the default EnvConfig to dict
+                    default_env = field_info.default
+                    if hasattr(default_env, "model_dump"):
+                        default_value = default_env.model_dump()
+                    elif isinstance(default_env, dict):
+                        default_value = default_env
+
+                envs.append(
+                    {
+                        "name": field_name,
+                        "description": marker.description,
+                        "required": marker.required,
+                        "default": default_value,
+                    }
+                )
             else:
                 world_properties[field_name] = prop_schema
 
@@ -149,8 +202,26 @@ class RunConfig(BaseModel):
             "required": required,
             "agents": agents,
             "secrets": secrets,
+            "envs": envs,
         }
 
+    def get_envs(self) -> list[EnvConfig]:
+        """Get all environment configurations from this config.
+
+        Returns:
+            List of EnvConfig objects (EnvFromArtifact, EnvFromSimulator, or EnvFromResource)
+        """
+        annotations = self.get_field_annotations()
+        envs: list[EnvConfig] = []
+
+        for field_name, marker in annotations.items():
+            if isinstance(marker, Env):
+                value = getattr(self, field_name, None)
+                if value is not None:
+                    envs.append(value)
+
+        return envs
+
     @classmethod
     def from_file(cls, path: str | Path) -> RunConfig:
         """Load config from a JSON file."""
@@ -177,6 +248,9 @@ class RunConfig(BaseModel):
         # Handle secrets dict -> individual secret fields
         secrets_dict = data.pop("secrets", {})
 
+        # Handle envs dict -> individual env fields
+        envs_dict = data.pop("envs", {})
+
         # Merge world_config into top-level
         parsed.update(world_config)
         parsed.update(data)
@@ -191,8 +265,24 @@ class RunConfig(BaseModel):
                     parsed[field_name] = AgentConfig(image=str(agent_data))
             elif isinstance(marker, Secret) and field_name in secrets_dict:
                 parsed[field_name] = secrets_dict[field_name]
+            elif isinstance(marker, Env) and field_name in envs_dict:
+                env_data = envs_dict[field_name]
+                if isinstance(env_data, dict):
+                    parsed[field_name] = _parse_env_config(env_data)
+                else:
+                    parsed[field_name] = env_data
 
         # Store all secrets for agent use
         parsed["all_secrets"] = secrets_dict
 
         return cls(**parsed)
+
+
+def _parse_env_config(data: dict) -> EnvConfig:
+    """Parse an env config dict into the appropriate type."""
+    if "artifact_id" in data:
+        return EnvFromArtifact(**data)
+    elif "sim_config" in data:
+        return EnvFromResource(**data)
+    else:
+        return EnvFromSimulator(**data)

plato/worlds/runner.py

@@ -3,13 +3,15 @@
 from __future__ import annotations
 
 import asyncio
+import json
 import logging
+import os
 from pathlib import Path
 from typing import Annotated
 
 import typer
 
-from plato.worlds.config import RunConfig
+from plato.worlds.config import EnvConfig, RunConfig
 
 app = typer.Typer(
     name="plato-world-runner",
@@ -133,6 +135,123 @@ def list_worlds(
         typer.echo(f"  {name} (v{version}): {desc}")
 
 
+async def _run_dev(
+    world_name: str,
+    config_path: Path,
+    env_timeout: int = 600,
+) -> 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. Create Plato session with all environments
+    3. Run the world with the session attached
+    """
+    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())
+
+    # Get environment configs from the parsed config
+    env_configs: list[EnvConfig] = run_config.get_envs()
+
+    # Create Plato client
+    plato = AsyncPlato()
+    session = 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}")
+            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()
+
+
+@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,
+    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.
+
+    Example config.json:
+    {
+        "repository_url": "https://github.com/user/repo",
+        "prompt": "Fix the bug in main.py",
+        "agents": {
+            "coder": {
+                "image": "openhands:latest",
+                "config": {"model_name": "claude-sonnet-4"}
+            }
+        },
+        "secrets": {
+            "anthropic_api_key": "sk-..."
+        }
+    }
+
+    Environment variables:
+        PLATO_API_KEY: API key for Plato (required)
+    """
+    # 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)
+
+    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))
+    except Exception as e:
+        logger.exception(f"World execution failed: {e}")
+        raise typer.Exit(1)
+
+
 def main() -> None:
     """CLI entry point."""
     app()

{plato_sdk_v2-2.1.16.dist-info → plato_sdk_v2-2.1.17.dist-info}/METADATA

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

{plato_sdk_v2-2.1.16.dist-info → plato_sdk_v2-2.1.17.dist-info}/RECORD

@@ -283,10 +283,13 @@ plato/_generated/api/v2/user/get_current_user.py,sha256=tvamtbWTEkeeNUBLSPqZIcCG
 plato/_generated/api/version/__init__.py,sha256=dQXTYrXjD1RZcvWwnlqXWAZ-eAV-V-6JSNuY7uaca7o,70
 plato/_generated/api/version/check.py,sha256=HTVNw0oi9gbvX4pOVoH4y4JywCxdl1pJTCk2PjJFwJ4,778
 plato/_generated/models/__init__.py,sha256=VGsTMYUCCqa7r_tl5m--dwjy7viYAN20nU2HhVAibcU,154130
-plato/_sims_generator/__init__.py,sha256=Cg8atlEoWsd5nf0qLz3_EbHxFVFtBwPDDUZbx3jxRrc,1125
+plato/_sims_generator/__init__.py,sha256=Km4QOl9wxjQ5dgpdhk9QnBFJFFc9eq3rPbMWIQRjIn0,1602
 plato/_sims_generator/cli.py,sha256=mzolN-dxfMkVAdA-vC0esnai-cGg-i4ozOw8dACefV4,2709
+plato/_sims_generator/instruction.py,sha256=cxRCsvJ92DJdTxpJcW7gUgL8kWM4abcjPZjLQMkgOhs,6575
 plato/_sims_generator/parser.py,sha256=BbgRYllqYf7H76JyMfe7LYo1we-kh7YEOxUwrYT3shc,38347
 plato/_sims_generator/python.py,sha256=ZYZJeOhGhYV95iB2_G-stQHaIv5sQj0jo3GXSLb6SdA,18295
+plato/_sims_generator/templates/instruction/helpers.py.jinja,sha256=kJ8lhVLPygjMh8l-In9rLtFci6Bxg3zVoz5BZFfLKms,4937
+plato/_sims_generator/templates/instruction/init.py.jinja,sha256=oabz8xKdkz9SjRBYwg_GoHZdz1ZrhHXOOEazw2pOczQ,879
 plato/_sims_generator/templates/python/api_init.py.jinja,sha256=HYNtVsiGU91IzhBtBA3qlLv8b3U5kZbmW-FqdZ9F7mQ,188
 plato/_sims_generator/templates/python/client.py.jinja,sha256=H99L4kgRfTwJs3DOC9P-DcGtHNYBDNxcOvtedWEgWYM,19755
 plato/_sims_generator/templates/python/endpoint.py.jinja,sha256=1ToZiS8w_aZydVBhNt5KxLIbCo3toWCi4NPjLAmhVy4,12478
@@ -373,9 +376,9 @@ plato/chronos/models/__init__.py,sha256=Iyh5srlL4oqsviCnjk9xHW7g0BjgJR4lAthFkZoX
 plato/sims/README.md,sha256=FIbJhNVNAV-SO6dq_cXX3Rg0C7HdQCfEY9YxGlkCmsM,6902
 plato/sims/__init__.py,sha256=tnoCGKZwNx6h22tEWLujdpLv6K4PpFU2RnDOhL1o-Uc,1494
 plato/sims/agent_helpers.py,sha256=kITvQywoTCS8mGhro3jZWuPJHDlje-UZujhjoahqhd0,10291
-plato/sims/cli.py,sha256=ySG5TNh9L2E-bgP0Jv4sbewReaoPw5jDYFAQk_jubuw,46093
+plato/sims/cli.py,sha256=VaPZ_jeCbbR-A_l0UR1dz6Ur7UbHGRSHwO6W_9sZfm4,52512
 plato/sims/generate_clients.py,sha256=nEe39v3UOcks-ggv5jomcwN33R5U9n8MDNCpHoZ2lDg,5958
-plato/sims/registry.py,sha256=_xtjcI4HHGBsJ4c0kzxK90U2B_h6FK-5FAoAwyWZokQ,8777
+plato/sims/registry.py,sha256=9qVSFzX575sfxvqPqCBiTExRZNNsEYr5Jl9DyxbJF08,12015
 plato/v1/__init__.py,sha256=t1Ejb7YCFOVSKZL9hJ0UsmEE1mULDvO__f75dz1UueQ,197
 plato/v1/audit_ui.py,sha256=zYYufJKn7291uCNb_59ItmDTYsPr7YLshBFwcAwl1LQ,10990
 plato/v1/cli.py,sha256=iEt58vvW7ab9YH0CLcBHvf4653fk1gcEdij4HZc10YY,269
@@ -390,8 +393,8 @@ plato/v1/sync_sdk.py,sha256=ztAvqR5yW_ALj8g97K6U-jSQzwzVNVKWlGZ-tdMUP_M,25620
 plato/v1/cli/__init__.py,sha256=om4b7PxgsoI7rEwuQelmQkqPdhMVn53_5qEN8kvksYw,105
 plato/v1/cli/agent.py,sha256=GUPDx6iZlGlW3q8QC863Vdrpe5_f6PBtcNo5vYipaEI,43329
 plato/v1/cli/main.py,sha256=ktPtBvMwykR7AjXmTQ6bmZkHdzpAjhX5Fq66cDbGSzA,6844
-plato/v1/cli/pm.py,sha256=sIrh7qVyL-GOI8cgCUDFO2StXCxaKkCpGoN2waMqiyw,47579
-plato/v1/cli/sandbox.py,sha256=r4VrZxfGLwLdmZyylw07dQ70glvsyBg3j7S_qU6UrRs,87801
+plato/v1/cli/pm.py,sha256=wYeOyvaZFb7omQTpdHbKK72nC2CbS0jaoTCwfyCAKtI,47720
+plato/v1/cli/sandbox.py,sha256=Qult0F-YIrgWLl6wAFM6CE-pqhEDJPz2jzuSKtnVZtk,87871
 plato/v1/cli/ssh.py,sha256=pePHD0lFPwSkATZYSannpFtHfJWKImAdLyS2463aRRw,6287
 plato/v1/cli/utils.py,sha256=be-llK6T6NHnIQl_Kfs-8EPu9JhIuZ_k9tJ3Ts-AKt4,3887
 plato/v1/cli/world.py,sha256=f-65n70-V2EBcYs9hbYqCXVT8n2xm7opIgmB5Z6yi3Y,9580
@@ -458,12 +461,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=0ogDVw5GEk4OT7FSD0Z7SrafTn_TBdo8DOU_v6ncbd4,1478
-plato/worlds/base.py,sha256=vLAHkYpYg4kl7LgftQ0uC6xXhASVqREogn6msNWA6Hk,9650
+plato/worlds/__init__.py,sha256=crzpXFh4XD8eS4pYFTEUf3XgUf0wapFPT4npAu8sWwk,2078
+plato/worlds/base.py,sha256=McV2QAuHYztSMfG8EXQML1kEPbdeADLt8tgiYpH35n4,10751
 plato/worlds/build_hook.py,sha256=KSoW0kqa5b7NyZ7MYOw2qsZ_2FkWuz0M3Ru7AKOP7Qw,3486
-plato/worlds/config.py,sha256=-K1dnlRL5I-DNYEoc1I4cKIsTw53X_1QrRY2SWJvRiQ,6256
-plato/worlds/runner.py,sha256=r9B2BxBae8_dM7y5cJf9xhThp_I1Qvf_tlPq2rs8qC8,4013
-plato_sdk_v2-2.1.16.dist-info/METADATA,sha256=5S_mx4Iij8UNv8od9y6b3n8T00t6gFzM01-1wS-rLdg,8509
-plato_sdk_v2-2.1.16.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-plato_sdk_v2-2.1.16.dist-info/entry_points.txt,sha256=upGMbJCx6YWUTKrPoYvYUYfFCqYr75nHDwhA-45m6p8,136
-plato_sdk_v2-2.1.16.dist-info/RECORD,,
+plato/worlds/config.py,sha256=potOy85jYReODN4ndhTp38ebblk2yKbWRrm9uXRi-Vw,9472
+plato/worlds/runner.py,sha256=07fKyPYxem1vIKfPRo4le7eKWTkY3euDXugObVyAsf4,7858
+plato_sdk_v2-2.1.17.dist-info/METADATA,sha256=ZTTHQEnqUbMipKnNNZWL86JfgLY6v67LYUifoemoBsQ,8509
+plato_sdk_v2-2.1.17.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+plato_sdk_v2-2.1.17.dist-info/entry_points.txt,sha256=upGMbJCx6YWUTKrPoYvYUYfFCqYr75nHDwhA-45m6p8,136
+plato_sdk_v2-2.1.17.dist-info/RECORD,,