plato-sdk-v2 2.0.50__py3-none-any.whl → 2.2.4__py3-none-any.whl

plato/agents/base.py

@@ -0,0 +1,145 @@
+"""Base agent class and registry for Plato agents."""
+
+from __future__ import annotations
+
+import json
+import logging
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Any, ClassVar, Generic, TypeVar, get_args, get_origin
+
+from plato.agents.config import AgentConfig
+
+logger = logging.getLogger(__name__)
+
+# Global registry of agents
+_AGENT_REGISTRY: dict[str, type[BaseAgent]] = {}
+
+# Type variable for config
+ConfigT = TypeVar("ConfigT", bound=AgentConfig)
+
+
+def register_agent(name: str | None = None):
+    """Decorator to register an agent class.
+
+    Usage:
+        @register_agent("openhands")
+        class OpenHandsAgent(BaseAgent[OpenHandsConfig]):
+            ...
+    """
+
+    def decorator(cls: type[BaseAgent]) -> type[BaseAgent]:
+        agent_name = name or getattr(cls, "name", cls.__name__.lower().replace("agent", ""))
+        _AGENT_REGISTRY[agent_name] = cls
+        logger.debug(f"Registered agent: {agent_name} -> {cls.__name__}")
+        return cls
+
+    return decorator
+
+
+def get_registered_agents() -> dict[str, type[BaseAgent]]:
+    """Get all registered agents."""
+    return _AGENT_REGISTRY.copy()
+
+
+def get_agent(name: str) -> type[BaseAgent] | None:
+    """Get an agent by name."""
+    return _AGENT_REGISTRY.get(name)
+
+
+class BaseAgent(ABC, Generic[ConfigT]):
+    """Base class for Plato agents.
+
+    Subclass with a config type parameter for fully typed config access:
+
+        class OpenHandsConfig(AgentConfig):
+            model_name: str = "anthropic/claude-sonnet-4"
+            anthropic_api_key: Annotated[str | None, Secret(description="API key")] = None
+
+        @register_agent("openhands")
+        class OpenHandsAgent(BaseAgent[OpenHandsConfig]):
+            name = "openhands"
+            description = "OpenHands AI software engineer"
+
+            async def run(self, instruction: str) -> None:
+                # self.config is typed as OpenHandsConfig
+                model = self.config.model_name
+                ...
+    """
+
+    # Class attributes
+    name: ClassVar[str] = "base"
+    description: ClassVar[str] = ""
+
+    # Instance attributes
+    config: ConfigT
+
+    def __init__(self) -> None:
+        self.logger = logging.getLogger(f"plato.agents.{self.name}")
+
+    @classmethod
+    def get_config_class(cls) -> type[AgentConfig]:
+        """Get the config class from the generic parameter."""
+        for base in getattr(cls, "__orig_bases__", []):
+            origin = get_origin(base)
+            if origin is BaseAgent:
+                args = get_args(base)
+                if args and isinstance(args[0], type) and issubclass(args[0], AgentConfig):
+                    return args[0]
+        return AgentConfig
+
+    @classmethod
+    def get_version(cls) -> str:
+        """Get version from package metadata."""
+        import importlib.metadata
+
+        for pkg_name in [cls.__module__.split(".")[0], f"plato-agent-{cls.name}"]:
+            try:
+                return importlib.metadata.version(pkg_name)
+            except importlib.metadata.PackageNotFoundError:
+                continue
+        return "0.0.0"
+
+    @classmethod
+    def get_schema(cls) -> dict:
+        """Get full schema for the agent including config and build schemas."""
+        from plato.agents.build import BuildConfig
+
+        config_class = cls.get_config_class()
+        return {
+            "config": config_class.get_json_schema(),
+            "build": BuildConfig.get_json_schema(),
+        }
+
+    @abstractmethod
+    async def run(self, instruction: str) -> None:
+        """Run the agent with the given instruction.
+
+        This is the main entry point for agent execution. Implementations should:
+        1. Set up the environment using self.config
+        2. Execute the agent's core logic
+        3. Write trajectory to logs_dir if applicable
+
+        Args:
+            instruction: The task instruction/prompt for the agent.
+
+        Raises:
+            RuntimeError: If agent execution fails.
+        """
+        pass
+
+    async def write_trajectory(self, trajectory: dict[str, Any]) -> None:
+        """Write ATIF trajectory to the logs directory.
+
+        Args:
+            trajectory: ATIF-formatted trajectory dictionary.
+        """
+        logs_dir = Path(self.config.logs_dir)
+        agent_logs = logs_dir / "agent"
+        agent_logs.mkdir(parents=True, exist_ok=True)
+
+        trajectory_path = agent_logs / "trajectory.json"
+        with open(trajectory_path, "w") as f:
+            json.dump(trajectory, f, indent=2)
+
+        self.logger.info(f"Wrote trajectory to {trajectory_path}")

plato/agents/build.py

@@ -0,0 +1,61 @@
+"""Build configuration for Plato agents.
+
+Reads [tool.plato.build] from pyproject.toml to configure Docker builds.
+
+Example pyproject.toml:
+    [tool.plato.build]
+    env = { "SOME_BUILD_ARG" = "value" }
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+try:
+    import tomllib
+except ImportError:
+    import tomli as tomllib
+
+
+class BuildConfig(BaseModel):
+    """Docker build configuration for an agent.
+
+    Read from [tool.plato.build] in pyproject.toml.
+    """
+
+    env: dict[str, str] = Field(
+        default_factory=dict,
+        description="Environment variables to pass as build args",
+    )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dict for schema output."""
+        return self.model_dump(exclude_defaults=False)
+
+    @classmethod
+    def get_json_schema(cls) -> dict[str, Any]:
+        """Get JSON schema for build config."""
+        schema = cls.model_json_schema()
+        schema.pop("title", None)
+        return schema
+
+    @classmethod
+    def from_pyproject(cls, path: str | Path) -> BuildConfig:
+        """Load build config from pyproject.toml."""
+        path = Path(path)
+        if path.is_dir():
+            path = path / "pyproject.toml"
+
+        with open(path, "rb") as f:
+            data = tomllib.load(f)
+
+        build_config = data.get("tool", {}).get("plato", {}).get("build", {})
+        return cls(**build_config)
+
+
+def load_build_config(agent_path: str | Path) -> BuildConfig:
+    """Load build config from an agent directory."""
+    return BuildConfig.from_pyproject(agent_path)

plato/agents/config.py

@@ -0,0 +1,160 @@
+"""Typed configuration for Plato agents.
+
+Provides base configuration classes that agents extend with their specific fields.
+Secret fields are automatically loaded from environment variables using pydantic-settings.
+
+Example:
+    from plato.agents import AgentConfig, Secret
+    from typing import Annotated
+
+    class OpenHandsConfig(AgentConfig):
+        model_name: str = "anthropic/claude-sonnet-4"
+        anthropic_api_key: Annotated[str | None, Secret(description="API key")] = None
+
+    # Secrets auto-loaded from env vars (ANTHROPIC_API_KEY -> anthropic_api_key)
+    config = OpenHandsConfig.from_file("/config.json")
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Secret:
+    """Annotation marker for secret fields.
+
+    Fields annotated with Secret are automatically loaded from environment variables.
+    The env var name is the uppercase version of the field name (e.g., api_key -> API_KEY).
+
+    Usage:
+        api_key: Annotated[str, Secret(description="API key")]
+    """
+
+    def __init__(self, description: str = "", required: bool = False):
+        self.description = description
+        self.required = required
+
+
+class AgentConfig(BaseSettings):
+    """Base configuration for agents.
+
+    Extends pydantic-settings BaseSettings, so secret fields are automatically loaded
+    from environment variables. The env var name is the uppercase field name.
+
+    Subclass with agent-specific fields:
+
+        class OpenHandsConfig(AgentConfig):
+            model_name: str = "anthropic/claude-sonnet-4"
+            anthropic_api_key: Annotated[str | None, Secret(description="API key")] = None
+
+        # ANTHROPIC_API_KEY env var is automatically loaded into anthropic_api_key
+        config = OpenHandsConfig.from_file("/config.json")
+
+    Attributes:
+        logs_dir: Directory for agent logs and trajectory output.
+        checkpoint_paths: Directories to watch for checkpoint triggers (for workspace tracking).
+        checkpoint_debounce_ms: Debounce interval for checkpoints.
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="",  # No prefix - ANTHROPIC_API_KEY maps to anthropic_api_key
+        extra="allow",
+        env_ignore_empty=True,
+    )
+
+    logs_dir: str = "/logs"
+    checkpoint_paths: list[str] = Field(default_factory=list)
+    checkpoint_debounce_ms: int = 500
+
+    @classmethod
+    def get_field_secrets(cls) -> dict[str, Secret]:
+        """Get Secret annotations for each field."""
+        result: dict[str, Secret] = {}
+
+        for field_name, field_info in cls.model_fields.items():
+            for meta in field_info.metadata:
+                if isinstance(meta, Secret):
+                    result[field_name] = meta
+                    break
+
+        return result
+
+    @classmethod
+    def get_json_schema(cls) -> dict:
+        """Get JSON schema with secrets separated."""
+        full_schema = cls.model_json_schema()
+        full_schema.pop("title", None)
+
+        secrets_map = cls.get_field_secrets()
+        properties = full_schema.get("properties", {})
+
+        config_properties = {}
+        secrets = []
+
+        # Skip internal fields
+        internal_fields = {"logs_dir", "checkpoint_paths", "checkpoint_debounce_ms"}
+
+        for field_name, prop_schema in properties.items():
+            if field_name in internal_fields:
+                continue
+
+            if field_name in secrets_map:
+                secret = secrets_map[field_name]
+                secrets.append(
+                    {
+                        "name": field_name,
+                        "description": secret.description,
+                        "required": secret.required,
+                    }
+                )
+            else:
+                config_properties[field_name] = prop_schema
+
+        required = [r for r in full_schema.get("required", []) if r not in internal_fields and r not in secrets_map]
+
+        return {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "type": "object",
+            "properties": config_properties,
+            "required": required,
+            "secrets": secrets,
+        }
+
+    def get_secrets_dict(self) -> dict[str, str]:
+        """Extract secret values as a dict for environment variables."""
+        secrets_map = self.get_field_secrets()
+        result: dict[str, str] = {}
+
+        for field_name in secrets_map:
+            value = getattr(self, field_name, None)
+            if value is not None:
+                result[field_name] = value
+
+        return result
+
+    def get_config_dict(self) -> dict[str, Any]:
+        """Extract non-secret config values as a dict."""
+        secrets_map = self.get_field_secrets()
+        internal_fields = {"logs_dir", "checkpoint_paths", "checkpoint_debounce_ms"}
+
+        result: dict[str, Any] = {}
+        for field_name in self.model_fields:
+            if field_name not in secrets_map and field_name not in internal_fields:
+                value = getattr(self, field_name, None)
+                if value is not None:
+                    result[field_name] = value
+
+        return result
+
+    @classmethod
+    def from_file(cls, path: str | Path) -> AgentConfig:
+        """Load config from a JSON file."""
+        path = Path(path)
+        with open(path) as f:
+            data = json.load(f)
+        return cls(**data)