plato-sdk-v2 2.3.6__tar.gz → 2.3.8__tar.gz

{plato_sdk_v2-2.3.6 → plato_sdk_v2-2.3.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plato-sdk-v2
-Version: 2.3.6
+Version: 2.3.8
 Summary: Python SDK for the Plato API
 Author-email: Plato <support@plato.so>
 License-Expression: MIT
@@ -47,7 +47,6 @@ 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.6 → plato_sdk_v2-2.3.8}/README.md

@@ -1,6 +1,5 @@
 # Plato Python SDK
 
-
 Python SDK for the Plato platform. Uses [Harbor](https://harborframework.com) for agent execution.
 
 ## Installation

plato_sdk_v2-2.3.8/VERSION

@@ -0,0 +1 @@
+2.3.8

{plato_sdk_v2-2.3.6 → plato_sdk_v2-2.3.8}/plato/agents/otel.py

@@ -1,7 +1,7 @@
 """OpenTelemetry integration for Plato agents and worlds.
 
-Provides tracing and logging utilities using OpenTelemetry SDK. Traces and logs
-are sent directly to the Chronos OTLP endpoint.
+Provides tracing utilities using OpenTelemetry SDK. Traces are sent directly
+to the Chronos OTLP endpoint.
 
 Usage:
     from plato.agents.otel import init_tracing, get_tracer, shutdown_tracing
@@ -19,11 +19,6 @@ Usage:
         span.set_attribute("key", "value")
         # ... do work ...
 
-    # All Python logging is automatically sent to Chronos
-    import logging
-    logger = logging.getLogger(__name__)
-    logger.info("This will appear in the trajectory viewer!")
-
     # Cleanup
     shutdown_tracing()
 """
@@ -39,74 +34,44 @@ _module_logger = logging.getLogger(__name__)
 
 # Global state
 _tracer_provider = None
-_logging_handler = None
 _initialized = False
+_log_handler = None
 
 
-class OTelLoggingHandler(logging.Handler):
-    """Logging handler that emits OTel spans for log messages.
+class OTelSpanLogHandler(logging.Handler):
+    """Logging handler that creates OTel spans for log messages.
 
-    Each log message becomes a span with:
-    - span.type: "log"
-    - log.level: DEBUG/INFO/WARNING/ERROR/CRITICAL
-    - content: the log message
-    - source: the logger name
+    Converts Python log records to OTel spans with log attributes.
     """
 
-    def __init__(self, tracer_name: str = "plato.logging"):
-        super().__init__()
-        self._tracer_name = tracer_name
-        # Filter out noisy loggers
-        self._ignored_loggers = {
-            "httpx",
-            "httpcore",
-            "urllib3",
-            "asyncio",
-            "opentelemetry",
-            "plato.agents.otel",  # Avoid recursion
-        }
+    def __init__(self, tracer: Tracer, level: int = logging.INFO):
+        super().__init__(level)
+        self.tracer = tracer
 
     def emit(self, record: logging.LogRecord) -> None:
         """Emit a log record as an OTel span."""
-        # Skip ignored loggers
-        logger_name = record.name
-        for ignored in self._ignored_loggers:
-            if logger_name.startswith(ignored):
-                return
-
         try:
-            tracer = trace.get_tracer(self._tracer_name)
-
-            # Format the message
-            try:
-                msg = self.format(record)
-            except Exception:
-                msg = record.getMessage()
-
+            # Debug: print that we're emitting a log span
+            print(f"[OTel] Emitting log span: {record.name} - {record.getMessage()[:100]}")
             # Create a span for the log message
-            with tracer.start_as_current_span(
-                f"log.{record.levelname.lower()}",
-                end_on_exit=True,
-            ) as span:
-                span.set_attribute("span.type", "log")
+            with self.tracer.start_as_current_span(f"log.{record.levelname.lower()}") as span:
                 span.set_attribute("log.level", record.levelname)
-                span.set_attribute("content", msg)
-                span.set_attribute("source", logger_name)
+                span.set_attribute("log.message", record.getMessage())
+                span.set_attribute("log.logger", record.name)
+                span.set_attribute("source", "world")
+                span.set_attribute("content", record.getMessage()[:1000])
 
-                # Add extra context if available
                 if record.funcName:
                     span.set_attribute("log.function", record.funcName)
-                if record.pathname:
-                    span.set_attribute("log.file", record.pathname)
                 if record.lineno:
-                    span.set_attribute("log.line", record.lineno)
+                    span.set_attribute("log.lineno", record.lineno)
 
-                # If there's an exception, record it
-                if record.exc_info and record.exc_info[1]:
-                    span.record_exception(record.exc_info[1])
+                # Mark errors
+                if record.levelno >= logging.ERROR:
+                    span.set_attribute("error", True)
 
         except Exception:
-            # Don't let logging failures break the application
+            # Don't let logging errors crash the application
             pass
 
 
@@ -114,66 +79,82 @@ def init_tracing(
     service_name: str,
     session_id: str,
     otlp_endpoint: str,
-    capture_logging: bool = True,
-    log_level: int = logging.INFO,
+    parent_trace_id: str | None = None,
+    parent_span_id: str | None = None,
 ) -> None:
-    """Initialize OpenTelemetry tracing and optionally capture Python logging.
+    """Initialize OpenTelemetry tracing.
 
     Args:
         service_name: Name of the service (e.g., world name or agent name)
         session_id: Chronos session ID (added as resource attribute)
         otlp_endpoint: Chronos OTLP endpoint (e.g., http://chronos/api/otel)
-        capture_logging: If True, install handler to capture Python logs as OTel spans
-        log_level: Minimum log level to capture (default: INFO)
+        parent_trace_id: Optional parent trace ID for linking (hex string)
+        parent_span_id: Optional parent span ID for linking (hex string)
     """
-    global _tracer_provider, _logging_handler, _initialized
+    global _tracer_provider, _initialized, _log_handler
 
     if _initialized:
         _module_logger.debug("Tracing already initialized")
         return
 
     try:
+        from opentelemetry import context as context_api
         from opentelemetry.exporter.otlp.proto.http.trace_exporter import (
             OTLPSpanExporter,
         )
         from opentelemetry.sdk.resources import Resource
         from opentelemetry.sdk.trace import TracerProvider
-        from opentelemetry.sdk.trace.export import BatchSpanProcessor
+        from opentelemetry.sdk.trace.export import SimpleSpanProcessor
+        from opentelemetry.trace import NonRecordingSpan, SpanContext, TraceFlags
 
         # Create resource with session ID
         resource = Resource.create(
             {
                 "service.name": service_name,
-                "session.id": session_id,
+                "plato.session.id": session_id,
             }
         )
 
         # Create tracer provider
         _tracer_provider = TracerProvider(resource=resource)
 
-        # Add OTLP exporter pointing to Chronos
+        # Add OTLP exporter pointing to Chronos (use SimpleSpanProcessor for immediate export)
         otlp_exporter = OTLPSpanExporter(endpoint=f"{otlp_endpoint.rstrip('/')}/v1/traces")
-        _tracer_provider.add_span_processor(BatchSpanProcessor(otlp_exporter))
+        _tracer_provider.add_span_processor(SimpleSpanProcessor(otlp_exporter))
 
         # Set as global tracer provider
         trace.set_tracer_provider(_tracer_provider)
 
-        _initialized = True
+        # If parent context is provided, set it as the current context
+        # This allows new spans to automatically link to the parent
+        if parent_trace_id and parent_span_id:
+            parent_context = SpanContext(
+                trace_id=int(parent_trace_id, 16),
+                span_id=int(parent_span_id, 16),
+                is_remote=True,
+                trace_flags=TraceFlags(0x01),  # Sampled
+            )
+            parent_span = NonRecordingSpan(parent_context)
+            ctx = trace.set_span_in_context(parent_span)
+            context_api.attach(ctx)
+            print(f"[OTel] Using parent context: trace_id={parent_trace_id}, span_id={parent_span_id}")
+
+        # Add OTel logging handler to capture logs from plato SDK
+        tracer = trace.get_tracer(service_name)
+        _log_handler = OTelSpanLogHandler(tracer, level=logging.INFO)
+
+        # Add handler to plato loggers (worlds and agents)
+        # Set level to INFO to ensure logs propagate from child loggers
+        plato_logger = logging.getLogger("plato")
+        plato_logger.setLevel(logging.INFO)
+        plato_logger.addHandler(_log_handler)
+        print(
+            f"[OTel] Added log handler to 'plato' logger (level={plato_logger.level}, handlers={len(plato_logger.handlers)})"
+        )
 
-        # Install logging handler to capture Python logs
-        if capture_logging:
-            _logging_handler = OTelLoggingHandler()
-            _logging_handler.setLevel(log_level)
-            # Add to root logger to capture all logs
-            logging.getLogger().addHandler(_logging_handler)
+        _initialized = True
 
-        # Use print to ensure this shows regardless of logging config
         print(f"[OTel] Tracing initialized: service={service_name}, session={session_id}, endpoint={otlp_endpoint}")
-        _module_logger.info(
-            f"OTel tracing initialized: service={service_name}, "
-            f"session={session_id}, endpoint={otlp_endpoint}, "
-            f"capture_logging={capture_logging}"
-        )
 
     except ImportError as e:
         print(f"[OTel] OpenTelemetry SDK not installed: {e}")
@@ -184,16 +165,17 @@ def init_tracing(
 
 
 def shutdown_tracing() -> None:
-    """Shutdown the tracer provider, flush spans, and remove logging handler."""
-    global _tracer_provider, _logging_handler, _initialized
+    """Shutdown the tracer provider and flush spans."""
+    global _tracer_provider, _initialized, _log_handler
 
-    # Remove logging handler first
-    if _logging_handler:
+    # Remove log handler
+    if _log_handler:
         try:
-            logging.getLogger().removeHandler(_logging_handler)
+            plato_logger = logging.getLogger("plato")
+            plato_logger.removeHandler(_log_handler)
         except Exception:
             pass
-        _logging_handler = None
+        _log_handler = None
 
     if _tracer_provider:
         try:
@@ -229,6 +211,8 @@ def instrument(service_name: str = "plato-agent") -> Tracer:
     Reads the following env vars:
     - OTEL_EXPORTER_OTLP_ENDPOINT: Chronos OTLP endpoint (required for tracing)
     - SESSION_ID: Chronos session ID (default: "local")
+    - OTEL_TRACE_ID: Parent trace ID for linking spans (optional)
+    - OTEL_PARENT_SPAN_ID: Parent span ID for linking spans (optional)
 
     If OTEL_EXPORTER_OTLP_ENDPOINT is not set, returns a no-op tracer.
 
@@ -242,17 +226,23 @@ def instrument(service_name: str = "plato-agent") -> Tracer:
 
     otel_endpoint = os.environ.get("OTEL_EXPORTER_OTLP_ENDPOINT")
     session_id = os.environ.get("SESSION_ID", "local")
+    parent_trace_id = os.environ.get("OTEL_TRACE_ID")
+    parent_span_id = os.environ.get("OTEL_PARENT_SPAN_ID")
+
+    print(f"[OTel] instrument() called: service={service_name}, endpoint={otel_endpoint}, session={session_id}")
 
     if not otel_endpoint:
         # Return default tracer (no-op if no provider configured)
+        print("[OTel] No OTEL_EXPORTER_OTLP_ENDPOINT set, returning no-op tracer")
         return trace.get_tracer(service_name)
 
-    # Initialize tracing
+    # Initialize tracing with parent context if provided
     init_tracing(
         service_name=service_name,
         session_id=session_id,
         otlp_endpoint=otel_endpoint,
-        capture_logging=True,
+        parent_trace_id=parent_trace_id,
+        parent_span_id=parent_span_id,
     )
 
     return trace.get_tracer(service_name)

plato_sdk_v2-2.3.8/plato/agents/runner.py

@@ -0,0 +1,183 @@
+"""Agent runner - run agents in Docker containers.
+
+Agents emit their own OTel spans for trajectory events. This runner:
+1. Runs agents in Docker containers
+2. Streams stdout/stderr for logging
+3. Passes OTel environment variables for trace context propagation
+4. Uploads artifacts to S3 when complete
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import platform
+import tempfile
+
+from opentelemetry import trace
+
+from plato.agents.artifacts import upload_artifacts
+
+logger = logging.getLogger(__name__)
+
+
+async def run_agent(
+    image: str,
+    config: dict,
+    secrets: dict[str, str],
+    instruction: str,
+    workspace: str,
+    logs_dir: str | None = None,
+    pull: bool = True,
+) -> None:
+    """Run an agent in a Docker container.
+
+    Args:
+        image: Docker image URI
+        config: Agent configuration dict
+        secrets: Secret values (API keys, etc.)
+        instruction: Task instruction for the agent
+        workspace: Host directory to mount as /workspace
+        logs_dir: Host directory for logs (temp dir if None)
+        pull: Whether to pull the image first
+
+    Note: Agents handle their own OTel tracing. This runner only passes
+    the trace context (TRACEPARENT) so agent spans link to the parent step.
+    """
+    logs_dir = logs_dir or tempfile.mkdtemp(prefix="agent_logs_")
+
+    # Get session info from environment variables
+    session_id = os.environ.get("SESSION_ID")
+    otel_url = os.environ.get("OTEL_EXPORTER_OTLP_ENDPOINT")
+    upload_url = os.environ.get("UPLOAD_URL")
+
+    # Pull image if requested
+    if pull:
+        pull_proc = await asyncio.create_subprocess_exec(
+            "docker",
+            "pull",
+            image,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.STDOUT,
+        )
+        await pull_proc.wait()
+
+    # Setup
+    os.makedirs(os.path.join(logs_dir, "agent"), exist_ok=True)
+    config_file = tempfile.NamedTemporaryFile(mode="w", suffix=".json", delete=False)
+    json.dump(config, config_file)
+    config_file.close()
+
+    try:
+        # Build docker command
+        docker_cmd = ["docker", "run", "--rm", "--privileged"]
+
+        # Determine if we need host networking
+        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(
+            [
+                "-v",
+                f"{workspace}:/workspace",
+                "-v",
+                f"{logs_dir}:/logs",
+                "-v",
+                f"{config_file.name}:/config.json:ro",
+                "-v",
+                "/var/run/docker.sock:/var/run/docker.sock",
+                "-w",
+                "/workspace",
+            ]
+        )
+
+        # Pass session info to agent
+        if otel_url:
+            traces_endpoint = f"{otel_url.rstrip('/')}/v1/traces"
+            docker_cmd.extend(["-e", f"OTEL_EXPORTER_OTLP_ENDPOINT={otel_url}"])
+            docker_cmd.extend(["-e", f"OTEL_EXPORTER_OTLP_TRACES_ENDPOINT={traces_endpoint}"])
+            docker_cmd.extend(["-e", "OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf"])
+        if session_id:
+            docker_cmd.extend(["-e", f"SESSION_ID={session_id}"])
+        if upload_url:
+            docker_cmd.extend(["-e", f"UPLOAD_URL={upload_url}"])
+
+        # Pass trace context to agent for parent linking
+        # Agent spans will be children of the current step span
+        current_span = trace.get_current_span()
+        span_context = current_span.get_span_context()
+        if span_context.is_valid:
+            trace_id = format(span_context.trace_id, "032x")
+            span_id = format(span_context.span_id, "016x")
+            # W3C Trace Context format for TRACEPARENT
+            traceparent = f"00-{trace_id}-{span_id}-01"
+            docker_cmd.extend(
+                [
+                    "-e",
+                    f"TRACEPARENT={traceparent}",
+                    "-e",
+                    f"OTEL_TRACE_ID={trace_id}",
+                    "-e",
+                    f"OTEL_PARENT_SPAN_ID={span_id}",
+                ]
+            )
+
+        for key, value in secrets.items():
+            docker_cmd.extend(["-e", f"{key.upper()}={value}"])
+
+        docker_cmd.append(image)
+
+        # Pass instruction via CLI arg
+        docker_cmd.extend(["--instruction", instruction])
+
+        # Run container - agents emit their own OTel spans
+        process = await asyncio.create_subprocess_exec(
+            *docker_cmd,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.STDOUT,
+        )
+
+        # Capture output for error reporting
+        output_lines: list[str] = []
+        assert process.stdout is not None
+        while True:
+            line = await process.stdout.readline()
+            if not line:
+                break
+            decoded_line = line.decode().rstrip()
+            output_lines.append(decoded_line)
+
+        await process.wait()
+
+        exit_code = process.returncode or 0
+        if exit_code != 0:
+            error_context = "\n".join(output_lines[-50:]) if output_lines else "No output captured"
+            raise RuntimeError(f"Agent failed with exit code {exit_code}\n\nAgent output:\n{error_context}")
+
+    finally:
+        os.unlink(config_file.name)
+
+        # Upload artifacts if we have upload URL configured
+        if upload_url:
+            await upload_artifacts(upload_url, logs_dir)

{plato_sdk_v2-2.3.6 → plato_sdk_v2-2.3.8}/plato/v1/cli/sandbox.py

@@ -131,6 +131,9 @@ def sandbox_start(
     timeout: int = typer.Option(1800, "--timeout", help="VM lifetime in seconds (default: 30 minutes)"),
     no_reset: bool = typer.Option(False, "--no-reset", help="Skip initial reset after ready"),
     json_output: bool = typer.Option(False, "--json", "-j", help="Output as JSON"),
+    working_dir: Path = typer.Option(
+        None, "--working-dir", "-w", help="Working directory for .sandbox.yaml and .plato/"
+    ),
 ):
     """
     Start a sandbox environment.
@@ -377,7 +380,7 @@ def sandbox_start(
                     console.print("[cyan]  Generating SSH key pair...[/cyan]")
 
                 base_url = os.getenv("PLATO_BASE_URL", "https://plato.so")
-                ssh_info = setup_ssh_for_sandbox(base_url, job_id, username=ssh_username)
+                ssh_info = setup_ssh_for_sandbox(base_url, job_id, username=ssh_username, working_dir=working_dir)
                 ssh_host = ssh_info["ssh_host"]
                 ssh_config_path = ssh_info["config_path"]
                 ssh_private_key_path = ssh_info["private_key_path"]
@@ -489,7 +492,7 @@ def sandbox_start(
         # Add heartbeat PID
         if heartbeat_pid:
             state["heartbeat_pid"] = heartbeat_pid
-        save_sandbox_state(state)
+        save_sandbox_state(state, working_dir)
 
         # Close the plato client (heartbeat process keeps session alive)
         plato.close()

{plato_sdk_v2-2.3.6 → plato_sdk_v2-2.3.8}/plato/v1/cli/ssh.py

@@ -9,21 +9,21 @@ from cryptography.hazmat.primitives import serialization
 from cryptography.hazmat.primitives.asymmetric import ed25519
 
 
-def get_plato_dir() -> Path:
+def get_plato_dir(working_dir: Path | str | None = None) -> Path:
     """Get the directory for plato config/SSH files.
 
-    Uses /workspace/.plato if /workspace exists (container environment),
-    otherwise uses ~/.plato (local development).
+    Args:
+        working_dir: If provided, returns working_dir/.plato (for container/agent use).
+                     If None, returns ~/.plato (local development).
     """
-    workspace = Path("/workspace")
-    if workspace.exists() and workspace.is_dir():
-        return workspace / ".plato"
+    if working_dir is not None:
+        return Path(working_dir) / ".plato"
     return Path.home() / ".plato"
 
 
-def get_next_sandbox_number() -> int:
+def get_next_sandbox_number(working_dir: Path | str | None = None) -> int:
     """Find next available sandbox number by checking existing config files."""
-    plato_dir = get_plato_dir()
+    plato_dir = get_plato_dir(working_dir)
     if not plato_dir.exists():
         return 1
 
@@ -41,13 +41,13 @@ def get_next_sandbox_number() -> int:
     return max_num + 1
 
 
-def generate_ssh_key_pair(sandbox_num: int) -> tuple[str, str]:
+def generate_ssh_key_pair(sandbox_num: int, working_dir: Path | str | None = None) -> tuple[str, str]:
     """
     Generate a new ed25519 SSH key pair for a specific sandbox.
 
     Returns (public_key_str, private_key_path).
     """
-    plato_dir = get_plato_dir()
+    plato_dir = get_plato_dir(working_dir)
     plato_dir.mkdir(mode=0o700, exist_ok=True)
 
     private_key_path = plato_dir / f"ssh_{sandbox_num}_key"
@@ -136,6 +136,7 @@ def create_ssh_config(
     username: str,
     private_key_path: str,
     sandbox_num: int,
+    working_dir: Path | str | None = None,
 ) -> str:
     """
     Create a temporary SSH config file for a specific sandbox.
@@ -172,7 +173,7 @@ def create_ssh_config(
     TCPKeepAlive yes
 """
 
-    plato_dir = get_plato_dir()
+    plato_dir = get_plato_dir(working_dir)
     plato_dir.mkdir(mode=0o700, exist_ok=True)
 
     config_path = plato_dir / f"ssh_{sandbox_num}.conf"
@@ -182,7 +183,12 @@ def create_ssh_config(
     return str(config_path)
 
 
-def setup_ssh_for_sandbox(base_url: str, job_public_id: str, username: str = "plato") -> dict:
+def setup_ssh_for_sandbox(
+    base_url: str,
+    job_public_id: str,
+    username: str = "plato",
+    working_dir: Path | str | None = None,
+) -> dict:
     """
     Set up SSH access for a sandbox - generates keys and creates config.
 
@@ -190,14 +196,14 @@ def setup_ssh_for_sandbox(base_url: str, job_public_id: str, username: str = "pl
 
     Returns dict with: ssh_host, config_path, public_key, private_key_path
     """
-    sandbox_num = get_next_sandbox_number()
+    sandbox_num = get_next_sandbox_number(working_dir)
     ssh_host = f"sandbox-{sandbox_num}"
 
     # Choose random port between 2200 and 2299
     local_port = random.randint(2200, 2299)
 
     # Generate SSH key pair
-    public_key, private_key_path = generate_ssh_key_pair(sandbox_num)
+    public_key, private_key_path = generate_ssh_key_pair(sandbox_num, working_dir)
 
     # Create SSH config file
     config_path = create_ssh_config(
@@ -208,6 +214,7 @@ def setup_ssh_for_sandbox(base_url: str, job_public_id: str, username: str = "pl
         username=username,
         private_key_path=private_key_path,
         sandbox_num=sandbox_num,
+        working_dir=working_dir,
     )
 
     return {