plato-sdk-v2 2.1.11__py3-none-any.whl → 2.3.0__py3-none-any.whl

plato/_sims_generator/__init__.py

@@ -1,9 +1,10 @@
 """OpenAPI SDK Generator for Plato.
 
-This module provides tools to generate Python SDKs from OpenAPI specifications.
+This module provides tools to generate Python SDKs from OpenAPI specifications,
+as well as instruction-based SDKs for sims that don't need API clients.
 
-Usage:
-    from plato.sims.generator import parse_openapi, PythonGenerator, OAuthConfig
+Usage (OpenAPI-based):
+    from plato._sims_generator import parse_openapi, PythonGenerator, OAuthConfig
 
     api = parse_openapi(spec_dict)
     generator = PythonGenerator(
@@ -21,10 +22,22 @@ Usage:
     )
     generator.generate()
 
+Usage (Instruction-based):
+    from plato._sims_generator import InstructionConfig, InstructionGenerator
+
+    config = InstructionConfig.from_yaml(Path("specs/instructions.yaml"))
+    generator = InstructionGenerator(
+        config,
+        output_path,
+        package_name="localstack",
+    )
+    generator.generate()
+
 Or via CLI:
-    uv run python -m plato.sims.generator.cli --path spec.yaml --output ./output --package mypackage
+    plato sims publish --config plato-config.yml
 """
 
+from .instruction import InstructionConfig, InstructionGenerator
 from .parser import API, Endpoint, Schema, Type, parse_openapi
 from .python import AuthConfig, BasicAuthConfig, BearerTokenConfig, OAuthConfig, PythonGenerator, SessionAuthConfig
 
@@ -40,4 +53,6 @@ __all__ = [
     "BearerTokenConfig",
     "BasicAuthConfig",
     "SessionAuthConfig",
+    "InstructionConfig",
+    "InstructionGenerator",
 ]

plato/_sims_generator/instruction.py

@@ -0,0 +1,203 @@
+"""Instruction-based simulator SDK generator.
+
+Generates simple helper packages for sims that don't need OpenAPI clients.
+These sims provide setup instructions and environment variable helpers.
+"""
+
+import importlib.resources
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import yaml
+from jinja2 import Environment, FileSystemLoader
+
+
+@dataclass
+class ServiceConfig:
+    """Configuration for a named service endpoint."""
+
+    port: int
+    description: str = ""
+
+
+@dataclass
+class EnvVarConfig:
+    """Configuration for an environment variable."""
+
+    description: str = ""
+    template: str | None = None  # Template with {service:NAME} placeholders
+    default: str | None = None  # Static default value
+    env_key: str | None = None  # Read from another env var
+
+
+@dataclass
+class InstructionConfig:
+    """Parsed instruction configuration from instructions.yaml."""
+
+    env_prefix: str
+    services: dict[str, ServiceConfig] = field(default_factory=dict)
+    env_vars: dict[str, EnvVarConfig] = field(default_factory=dict)
+    instructions: str = ""
+    title: str = ""
+    description: str = ""
+    version: str = "0.1.0"
+
+    @classmethod
+    def from_yaml(cls, path: Path) -> "InstructionConfig":
+        """Parse instruction config from YAML file."""
+        with open(path) as f:
+            data = yaml.safe_load(f)
+
+        if data.get("type") != "instruction":
+            raise ValueError(f"Expected type: instruction, got: {data.get('type')}")
+
+        env_prefix = data.get("env_prefix", "")
+        title = data.get("title", "")
+        description = data.get("description", "")
+        version = data.get("version", "0.1.0")
+
+        # Parse services
+        services = {}
+        for name, svc_data in data.get("services", {}).items():
+            services[name] = ServiceConfig(
+                port=svc_data["port"],
+                description=svc_data.get("description", ""),
+            )
+
+        # Parse env vars
+        env_vars = {}
+        for name, var_data in data.get("env_vars", {}).items():
+            env_vars[name] = EnvVarConfig(
+                description=var_data.get("description", ""),
+                template=var_data.get("template"),
+                default=var_data.get("default"),
+                env_key=var_data.get("env_key"),
+            )
+
+        instructions = data.get("instructions", "")
+
+        return cls(
+            env_prefix=env_prefix,
+            services=services,
+            env_vars=env_vars,
+            instructions=instructions,
+            title=title,
+            description=description,
+            version=version,
+        )
+
+
+class InstructionGenerator:
+    """Generates instruction-based simulator SDK packages."""
+
+    def __init__(
+        self,
+        config: InstructionConfig,
+        output_path: Path,
+        package_name: str,
+        generator_version: str | None = None,
+    ):
+        self.config = config
+        self.output = output_path
+        self.package_name = package_name
+        self.generator_version = generator_version
+
+        # Get template directory using importlib.resources
+        template_ref = importlib.resources.files("plato._sims_generator") / "templates" / "instruction"
+        # For filesystem templates, we need the actual path
+        self.template_dir = Path(str(template_ref))
+
+        self.env = Environment(
+            loader=FileSystemLoader(self.template_dir),
+            trim_blocks=True,
+            lstrip_blocks=True,
+        )
+
+    def generate(self):
+        """Generate the instruction-based SDK package."""
+        # Create output structure
+        self.output.mkdir(parents=True, exist_ok=True)
+
+        # Generate helpers.py
+        self._generate_helpers()
+
+        # Generate __init__.py
+        self._generate_init()
+
+        # Copy instructions.yaml to output
+        self._copy_instructions_yaml()
+
+        # Generate py.typed marker
+        self._generate_py_typed()
+
+        # Format with ruff
+        self._format()
+
+    def _generate_helpers(self):
+        """Generate the helpers module."""
+        template = self.env.get_template("helpers.py.jinja")
+        content = template.render(
+            config=self.config,
+            package_name=self.package_name,
+            generator_version=self.generator_version,
+        )
+        (self.output / "helpers.py").write_text(content)
+
+    def _generate_init(self):
+        """Generate package __init__.py."""
+        template = self.env.get_template("init.py.jinja")
+        content = template.render(
+            config=self.config,
+            package_name=self.package_name,
+            generator_version=self.generator_version,
+        )
+        (self.output / "__init__.py").write_text(content)
+
+    def _copy_instructions_yaml(self):
+        """Bundle the instructions.yaml config with the package."""
+        # We'll generate a cleaned version of the config
+        env_vars: dict[str, dict[str, str | int]] = {}
+        config_data: dict[str, str | dict] = {
+            "type": "instruction",
+            "env_prefix": self.config.env_prefix,
+            "title": self.config.title,
+            "description": self.config.description,
+            "version": self.config.version,
+            "services": {
+                name: {"port": svc.port, "description": svc.description} for name, svc in self.config.services.items()
+            },
+            "env_vars": env_vars,
+            "instructions": self.config.instructions,
+        }
+
+        for name, var in self.config.env_vars.items():
+            var_data: dict = {"description": var.description}
+            if var.template:
+                var_data["template"] = var.template
+            if var.default:
+                var_data["default"] = var.default
+            if var.env_key:
+                var_data["env_key"] = var.env_key
+            env_vars[name] = var_data
+
+        with open(self.output / "instructions.yaml", "w") as f:
+            yaml.dump(config_data, f, default_flow_style=False, sort_keys=False)
+
+    def _generate_py_typed(self):
+        """Generate py.typed marker for PEP 561 compliance."""
+        (self.output / "py.typed").write_text("")
+
+    def _format(self):
+        """Format generated code with ruff."""
+        try:
+            subprocess.run(
+                ["ruff", "check", str(self.output), "--fix", "--quiet"],
+                capture_output=True,
+            )
+            subprocess.run(
+                ["ruff", "format", str(self.output), "--quiet"],
+                capture_output=True,
+            )
+        except FileNotFoundError:
+            pass  # ruff not installed, skip formatting

plato/_sims_generator/templates/instruction/helpers.py.jinja

@@ -0,0 +1,161 @@
+"""{{ config.title or package_name }} simulator helpers.
+
+Auto-generated by plato sims publish. Do not edit.
+{% if config.description %}
+
+{{ config.description }}
+{% endif %}
+"""
+
+from __future__ import annotations
+
+import importlib.resources
+import os
+from typing import Any
+
+import yaml
+
+# Load instructions config using importlib.resources
+_config_text = importlib.resources.files(__package__).joinpath("instructions.yaml").read_text()
+_CONFIG: dict[str, Any] = yaml.safe_load(_config_text)
+
+ENV_PREFIX: str = _CONFIG.get("env_prefix", "")
+SERVICES: dict[str, dict[str, Any]] = _CONFIG.get("services", {})
+CONNECT_URL_TEMPLATE: str = "https://{job_id}--{port}.connect.plato.so"
+
+
+def get_service_port(service_name: str) -> int:
+    """Get the port for a named service.
+
+    Args:
+        service_name: Name of the service (e.g., {% for name in config.services.keys() %}"{{ name }}"{% if not loop.last %}, {% endif %}{% endfor %})
+
+    Returns:
+        Port number for the service
+
+    Raises:
+        ValueError: If service not found
+    """
+    if service_name not in SERVICES:
+        available = list(SERVICES.keys())
+        raise ValueError(f"Service '{service_name}' not found. Available: {available}")
+    return int(SERVICES[service_name]["port"])
+
+
+def get_service_url(job_id: str, service_name: str) -> str:
+    """Get the connect URL for a specific service.
+
+    Args:
+        job_id: The job ID from the Plato session
+        service_name: Name of the service
+
+    Returns:
+        Connect URL for the service (e.g., https://jobid--4566.connect.plato.so)
+    """
+    port = get_service_port(service_name)
+    return CONNECT_URL_TEMPLATE.format(job_id=job_id, port=port)
+
+
+def get_service_urls(job_id: str) -> dict[str, str]:
+    """Get connect URLs for all services.
+
+    Args:
+        job_id: The job ID from the Plato session
+
+    Returns:
+        Dict mapping service name to connect URL
+    """
+    return {name: get_service_url(job_id, name) for name in SERVICES}
+
+
+def get_env_vars(service_urls: dict[str, str]) -> dict[str, str]:
+    """Get environment variables with resolved service URLs.
+
+    Args:
+        service_urls: Dict mapping service name to its connect URL
+                     (e.g., {"main": "https://abc--4566.connect.plato.so"})
+
+    Returns:
+        Dict of env var name -> value
+    """
+    env_vars: dict[str, str] = {}
+    for name, var_config in _CONFIG.get("env_vars", {}).items():
+        if "template" in var_config:
+            template = var_config["template"]
+            # Replace {service:NAME} with actual URL
+            for svc_name, svc_url in service_urls.items():
+                template = template.replace("{" + f"service:{svc_name}" + "}", svc_url)
+            env_vars[name] = template
+        elif "default" in var_config:
+            env_vars[name] = str(var_config["default"])
+        elif "env_key" in var_config:
+            env_vars[name] = os.environ.get(var_config["env_key"], "")
+    return env_vars
+
+
+def get_env_vars_from_job(job_id: str) -> dict[str, str]:
+    """Get environment variables for a job ID.
+
+    Args:
+        job_id: The job ID from the Plato session
+
+    Returns:
+        Dict of env var name -> value
+    """
+    service_urls = get_service_urls(job_id)
+    return get_env_vars(service_urls)
+
+
+def setup_env(service_urls: dict[str, str]) -> None:
+    """Set up environment variables for using this sim.
+
+    Note: This sets env vars in the current process. For setting env vars
+    in a runtime container, use get_env_vars() and pass them to the runtime.
+
+    Args:
+        service_urls: Dict mapping service name to its connect URL
+    """
+    for name, value in get_env_vars(service_urls).items():
+        os.environ[name] = value
+
+
+def setup_env_from_job(job_id: str) -> None:
+    """Set up environment variables from a job ID.
+
+    Note: This sets env vars in the current process. For setting env vars
+    in a runtime container, use get_env_vars_from_job() and pass them to the runtime.
+
+    Args:
+        job_id: The job ID from the Plato session
+    """
+    service_urls = get_service_urls(job_id)
+    setup_env(service_urls)
+
+
+def get_instructions(service_urls: dict[str, str]) -> str:
+    """Get formatted instructions with resolved service URLs.
+
+    Args:
+        service_urls: Dict mapping service name to its connect URL
+
+    Returns:
+        Markdown-formatted instructions
+    """
+    template = _CONFIG.get("instructions", "")
+    # Replace {service:NAME} with actual URL
+    for svc_name, svc_url in service_urls.items():
+        template = template.replace("{" + f"service:{svc_name}" + "}", svc_url)
+    return template
+
+
+def get_instructions_from_job(job_id: str) -> str:
+    """Get formatted instructions for a job ID.
+
+    Args:
+        job_id: The job ID from the Plato session
+
+    Returns:
+        Markdown-formatted instructions
+    """
+    service_urls = get_service_urls(job_id)
+    return get_instructions(service_urls)

plato/_sims_generator/templates/instruction/init.py.jinja

@@ -0,0 +1,43 @@
+"""{{ config.title or package_name }} simulator.
+{% if config.description %}
+
+{{ config.description }}
+{% endif %}
+
+Auto-generated by plato sims publish. Do not edit.
+"""
+
+from .helpers import (
+    CONNECT_URL_TEMPLATE,
+    ENV_PREFIX,
+    SERVICES,
+    get_env_vars,
+    get_env_vars_from_job,
+    get_instructions,
+    get_instructions_from_job,
+    get_service_port,
+    get_service_url,
+    get_service_urls,
+    setup_env,
+    setup_env_from_job,
+)
+
+{% if generator_version %}
+__generator_version__ = "{{ generator_version }}"
+{% endif %}
+__version__ = "{{ config.version }}"
+
+__all__ = [
+    "CONNECT_URL_TEMPLATE",
+    "ENV_PREFIX",
+    "SERVICES",
+    "get_env_vars",
+    "get_env_vars_from_job",
+    "get_instructions",
+    "get_instructions_from_job",
+    "get_service_port",
+    "get_service_url",
+    "get_service_urls",
+    "setup_env",
+    "setup_env_from_job",
+]

plato/agents/__init__.py

@@ -69,8 +69,7 @@ __all__ = [
     "get_agent",
     "get_registered_agents",
     # Runner
-    "AgentRunner",
-    "AgentRunResult",
+    "run_agent",
     # Trajectory (ATIF)
     "Trajectory",
     "Step",
@@ -81,8 +80,12 @@ __all__ = [
     "Metrics",
     "FinalMetrics",
     "SCHEMA_VERSION",
-    # Callback
-    "ChronosCallback",
+    # Logging
+    "init_logging",
+    "span",
+    "log_event",
+    "upload_artifacts",
+    "reset_logging",
 ]
 
 from plato.agents.base import (
@@ -93,9 +96,15 @@ from plato.agents.base import (
     register_agent,
 )
 from plato.agents.build import BuildConfig, load_build_config
-from plato.agents.callback import ChronosCallback
 from plato.agents.config import AgentConfig, Secret
-from plato.agents.runner import AgentRunner, AgentRunResult
+from plato.agents.logging import (
+    init_logging,
+    log_event,
+    reset_logging,
+    span,
+    upload_artifacts,
+)
+from plato.agents.runner import run_agent
 from plato.agents.trajectory import (
     SCHEMA_VERSION,
     Agent,