plato-sdk-v2 2.6.1__py3-none-any.whl → 2.7.0__py3-none-any.whl

plato/v1/cli/chronos.py

@@ -48,30 +48,21 @@ def launch(
         help="Wait for job completion and stream logs",
     ),
 ):
-    """
-    Launch a Chronos job from a config file.
-
-    \b
-    Config format:
-        {
-            "world": {
-                "package": "plato-world-structured-execution:0.1.17",
-                "config": {
-                    "skill_runner": {
-                        "image": "computer-use:1.1.0",
-                        "config": { ... }
-                    },
-                    "secrets": { ... }
-                }
-            },
-            "runtime": {
-                "artifact_id": "..."  // optional
-            }
-        }
-
-    Examples:
-        plato chronos launch config.json
-        plato chronos launch config.json --wait
+    """Launch a Chronos job from a config file.
+
+    Submits a job configuration to the Chronos service to run a world with its
+    configured agents and secrets.
+
+    Arguments:
+        config: Path to the job configuration JSON file
+
+    Options:
+        -u, --url: Chronos API URL (default: https://chronos.plato.so, or CHRONOS_URL env var)
+        -k, --api-key: Plato API key for authentication (or PLATO_API_KEY env var)
+        -w, --wait: Wait for job completion and stream logs (not yet implemented)
+
+    The config file should contain world.package (required) and optionally world.config,
+    runtime.artifact_id, and tags.
     """
     import httpx
 
@@ -148,12 +139,18 @@ def example(
         help="Output file path (prints to stdout if not specified)",
     ),
 ):
-    """
-    Generate an example job config file.
+    """Generate an example job config file.
+
+    Creates a sample JSON configuration for launching Chronos jobs, which can be
+    customized for your use case.
+
+    Arguments:
+        world: World type to generate example for (default: "structured-execution")
 
-    Examples:
-        plato chronos example
-        plato chronos example structured-execution -o config.json
+    Options:
+        -o, --output: Output file path. If not specified, prints to stdout.
+
+    Available worlds: structured-execution, code-world
     """
     examples = {
         "structured-execution": {
@@ -724,14 +721,17 @@ def stop(
         help="Plato API key for authentication",
     ),
 ):
-    """
-    Stop a running Chronos session.
+    """Stop a running Chronos session.
 
-    This marks the session as cancelled with status reason "User cancelled".
+    Marks the session as cancelled with status reason "User cancelled" and terminates
+    any running containers.
 
-    Examples:
-        plato chronos stop abc123
-        plato chronos stop abc123 --url https://chronos.plato.so
+    Arguments:
+        session_id: The session ID to stop (from 'plato chronos launch' output)
+
+    Options:
+        -u, --url: Chronos API URL (default: https://chronos.plato.so, or CHRONOS_URL env var)
+        -k, --api-key: Plato API key for authentication (or PLATO_API_KEY env var)
     """
     # Set defaults
     if not chronos_url:
@@ -784,32 +784,20 @@ def dev(
         typer.Option("--env-timeout", help="Timeout for environment creation (seconds)"),
     ] = 7200,
 ):
-    """
-    Run a world locally for development/debugging.
+    """Run a world locally for development/debugging.
 
-    This runs the world in a Docker container with docker.sock mounted,
-    allowing the world to spawn agent containers.
+    Builds and runs the world in a Docker container with docker.sock mounted,
+    allowing the world to spawn agent containers. Mounts local source code for
+    live development without rebuilding.
 
-    \b
-    Config format (same as Chronos launch):
-    {
-        "world": {
-            "package": "plato-world-structured-execution:0.1.17",
-            "config": {
-                "skill_runner": {
-                    "image": "computer-use:1.1.0",
-                    "config": { ... }
-                },
-                "secrets": { ... }
-            }
-        },
-        "runtime": {
-            "artifact_id": "..."
-        }
-    }
+    Arguments:
+        config: Path to job config JSON file (same format as 'plato chronos launch')
 
-    Example:
-        plato chronos dev config.json -w ~/worlds/my-world -a ~/agents --platform linux/amd64
+    Options:
+        -w, --world-dir: Directory containing world source code to mount into the container
+        -a, --agents-dir: Directory containing agent source code to mount (optional)
+        -p, --platform: Docker platform for building (e.g., 'linux/amd64' for M1 Macs)
+        --env-timeout: Timeout in seconds for environment creation (default: 7200 = 2 hours)
     """
     logging.basicConfig(
         level=logging.INFO,

plato/v1/cli/main.py

@@ -11,6 +11,7 @@ from dotenv import load_dotenv
 from plato.v1.cli.agent import agent_app
 from plato.v1.cli.chronos import chronos_app
 from plato.v1.cli.pm import pm_app
+from plato.v1.cli.proxy import app as proxy_app
 from plato.v1.cli.sandbox import sandbox_app
 from plato.v1.cli.utils import console
 from plato.v1.cli.world import world_app
@@ -73,6 +74,7 @@ app.add_typer(pm_app, name="pm")
 app.add_typer(agent_app, name="agent")
 app.add_typer(world_app, name="world")
 app.add_typer(chronos_app, name="chronos")
+app.add_typer(proxy_app, name="proxy")
 
 
 # =============================================================================
@@ -84,21 +86,13 @@ app.add_typer(chronos_app, name="chronos")
 def hub(
     ctx: typer.Context,
 ):
-    """
-    Launch the Plato Hub CLI (interactive TUI for managing simulators).
-
-    The hub command opens the Go-based Plato CLI which provides an interactive
-    terminal UI for browsing simulators, launching environments, and managing VMs.
+    """Launch the Plato Hub CLI (interactive TUI for managing simulators).
 
-    Available subcommands:
-    - clone <service>: Clone a service from Plato Hub
-    - credentials: Display your Plato Hub credentials
-    - (no args): Start interactive TUI mode
+    Opens the Go-based Plato CLI which provides an interactive terminal UI for
+    browsing simulators, launching environments, and managing VMs. Any additional
+    arguments are passed through to the Go CLI.
 
-    Examples:
-        plato hub clone espocrm
-        plato hub credentials
-        plato hub
+    Common subcommands: 'clone <service>', 'credentials', or no args for interactive mode.
     """
     # Find the bundled CLI binary
     plato_bin = _find_bundled_cli()
@@ -129,14 +123,12 @@ def hub(
 def clone(
     service: str = typer.Argument(..., help="Service name to clone (e.g., espocrm)"),
 ):
-    """
-    Clone a service repository from Plato Hub (Gitea).
+    """Clone a service repository from Plato Hub (Gitea).
 
-    This clones the simulator source code to your local machine.
+    Clones the simulator source code to your local machine for development or review.
 
-    Examples:
-        plato clone espocrm
-        plato clone gitea
+    Arguments:
+        service: Service name to clone (e.g., 'espocrm', 'gitea')
     """
     plato_bin = _find_bundled_cli()
     if not plato_bin:
@@ -153,13 +145,10 @@ def clone(
 
 @app.command()
 def credentials():
-    """
-    Display your Plato Hub (Gitea) credentials.
-
-    Shows the username and password needed to access Plato's Gitea repositories.
+    """Display your Plato Hub (Gitea) credentials.
 
-    Example:
-        plato credentials
+    Shows the username and password needed to access Plato's Gitea repositories
+    for cloning and pushing simulator code.
     """
     plato_bin = _find_bundled_cli()
     if not plato_bin:

plato/v1/cli/pm.py

@@ -240,44 +240,20 @@ def _list_pending_reviews(review_type: str):
 
 @list_app.command(name="base")
 def list_base():
-    """
-    List simulators pending base/environment review.
-
-    Shows simulators waiting for environment review (status: env_review_requested).
-    Use this to see what needs reviewing before running 'plato pm review base'.
-
-    USAGE:
-
-        plato pm list base
-
-    OUTPUT COLUMNS:
+    """List simulators pending base/environment review.
 
-        - Name: Simulator name
-        - Assignees: Who's assigned to review
-        - Notes: Any notes about the simulator
-        - base_artifact_id: The artifact to review
+    Shows simulators with status 'env_review_requested' in a table format.
+    Displays name, assignees, notes, and base_artifact_id for each simulator.
     """
     _list_pending_reviews("base")
 
 
 @list_app.command(name="data")
 def list_data():
-    """
-    List simulators pending data review.
-
-    Shows simulators waiting for data review (status: data_review_requested).
-    Use this to see what needs reviewing before running 'plato pm review data'.
-
-    USAGE:
-
-        plato pm list data
+    """List simulators pending data review.
 
-    OUTPUT COLUMNS:
-
-        - Name: Simulator name
-        - Assignees: Who's assigned to review
-        - Notes: Any notes about the simulator
-        - data_artifact_id: The artifact to review
+    Shows simulators with status 'data_review_requested' in a table format.
+    Displays name, assignees, notes, and data_artifact_id for each simulator.
     """
     _list_pending_reviews("data")
 
@@ -307,25 +283,19 @@ def review_base(
         help="Run login flow and check state, but skip interactive review. For automated verification.",
     ),
 ):
-    """
-    Review base/environment artifact for a simulator.
-
-    Opens the simulator in a browser for manual testing. After testing,
-    you can pass (→ env_approved) or reject (→ env_in_progress).
-
-    SPECIFYING SIMULATOR AND ARTIFACT:
+    """Review base/environment artifact for a simulator.
 
-        -s <simulator>                      Use server's base_artifact_id
-        -s <simulator> -a <artifact-uuid>   Explicit artifact
-        -s <simulator>:<artifact-uuid>      Colon notation (same as above)
-
-    EXAMPLES:
-
-        plato pm review base -s espocrm
-        plato pm review base -s espocrm -a e9c25ca5-1234-5678-9abc-def012345678
-        plato pm review base -s espocrm:e9c25ca5-1234-5678-9abc-def012345678
+    Creates an environment from the artifact, launches a browser for testing,
+    runs the login flow, and checks for database mutations. After testing,
+    choose pass (→ env_approved) or reject (→ env_in_progress).
 
     Requires simulator status: env_review_requested
+
+    Options:
+        -s, --simulator: Simulator name. Supports colon notation for artifact:
+            '-s sim' (uses server's base_artifact_id) or '-s sim:<uuid>'
+        -a, --artifact: Explicit artifact UUID to review. Overrides server's value.
+        --skip-review: Run automated checks without interactive review session.
     """
     api_key = require_api_key()
 
@@ -676,25 +646,18 @@ def review_data(
         help="Artifact UUID to review. If not provided, uses server's data_artifact_id.",
     ),
 ):
-    """
-    Launch browser with EnvGen Recorder extension for data review.
+    """Launch browser with EnvGen Recorder extension for data review.
 
     Opens Chrome with the EnvGen Recorder extension installed for reviewing
-    data artifacts. Close the browser when done.
-
-    SPECIFYING SIMULATOR AND ARTIFACT:
-
-        -s <simulator>                      Use server's data_artifact_id
-        -s <simulator> -a <artifact-uuid>   Explicit artifact
-        -s <simulator>:<artifact-uuid>      Colon notation (same as above)
-
-    EXAMPLES:
-
-        plato pm review data -s fathom
-        plato pm review data -s fathom -a e9c25ca5-1234-5678-9abc-def012345678
-        plato pm review data -s fathom:e9c25ca5-1234-5678-9abc-def012345678
+    data artifacts. The extension sidebar can be used to record and submit reviews.
+    Press Control-C to exit when done.
 
     Requires simulator status: data_review_requested
+
+    Options:
+        -s, --simulator: Simulator name. Supports colon notation for artifact:
+            '-s sim' (uses server's data_artifact_id) or '-s sim:<uuid>'
+        -a, --artifact: Explicit artifact UUID to review. Overrides server's value.
     """
     api_key = require_api_key()
 
@@ -924,27 +887,14 @@ def review_data(
 
 @submit_app.command(name="base")
 def submit_base():
-    """
-    Submit base/environment artifact for review after snapshot.
-
-    Reads simulator name and artifact ID from .sandbox.yaml (created by
-    plato sandbox start). Run this from the simulator directory after
-    creating a snapshot.
-
-    Transitions simulator from env_in_progress → env_review_requested.
-
-    USAGE:
+    """Submit base/environment artifact for review after snapshot.
 
-        plato pm submit base    # No args needed - reads from .sandbox.yaml
-
-    PREREQUISITES:
-
-        1. plato sandbox start --from-config
-        2. plato sandbox start-services
-        3. plato sandbox snapshot
-        4. plato pm submit base   ← you are here
+    Reads simulator name and artifact_id from .sandbox.yaml, syncs metadata from
+    plato-config.yml to the server, and transitions status to env_review_requested.
+    Run from the simulator directory after creating a snapshot.
 
     Requires simulator status: env_in_progress
+    No arguments needed - reads everything from .sandbox.yaml and plato-config.yml.
     """
     api_key = require_api_key()
 
@@ -1091,22 +1041,17 @@ def submit_data(
         help="Artifact UUID to submit for data review (required).",
     ),
 ):
-    """
-    Submit data artifact for review after data generation.
-
-    Transitions simulator from data_in_progress → data_review_requested.
+    """Submit data artifact for review after data generation.
 
-    SPECIFYING SIMULATOR AND ARTIFACT (both required):
-
-        -s <simulator> -a <artifact-uuid>   Explicit artifact
-        -s <simulator>:<artifact-uuid>      Colon notation (same as above)
-
-    EXAMPLES:
-
-        plato pm submit data -s espocrm -a e9c25ca5-1234-5678-9abc-def012345678
-        plato pm submit data -s espocrm:e9c25ca5-1234-5678-9abc-def012345678
+    Transitions simulator from data_in_progress → data_review_requested and
+    tags the artifact as 'data-pending-review'.
 
     Requires simulator status: data_in_progress
+
+    Options:
+        -s, --simulator: Simulator name. Supports colon notation:
+            '-s sim:<uuid>' or use separate -a flag
+        -a, --artifact: Artifact UUID to submit (required)
     """
     api_key = require_api_key()