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

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

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

plato_sdk_v2-2.3.7/VERSION

@@ -0,0 +1 @@
+2.3.7

{plato_sdk_v2-2.3.6 → plato_sdk_v2-2.3.7}/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,42 @@ _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()
-
             # 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 +77,77 @@ 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 world logs
+        tracer = trace.get_tracer(service_name)
+        _log_handler = OTelSpanLogHandler(tracer, level=logging.INFO)
+
+        # Add handler to plato.worlds loggers
+        plato_worlds_logger = logging.getLogger("plato.worlds")
+        plato_worlds_logger.addHandler(_log_handler)
 
-        # 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 +158,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_worlds_logger = logging.getLogger("plato.worlds")
+            plato_worlds_logger.removeHandler(_log_handler)
         except Exception:
             pass
-        _logging_handler = None
+        _log_handler = None
 
     if _tracer_provider:
         try:
@@ -229,6 +204,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 +219,20 @@ 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")
 
     if not otel_endpoint:
         # Return default tracer (no-op if no provider configured)
         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.7/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)