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

plato/agents/__init__.py

@@ -1,528 +1,118 @@
-"""Harbor agent re-exports for Plato SDK.
+"""Plato agent framework.
 
-This module provides convenient access to Harbor's built-in agents and base classes
-for building custom agents.
-
-Built-in Agents (installed agents):
-    - ClaudeCode: Claude Code agent
-    - OpenHands: OpenHands code agent
-    - Codex: OpenAI Codex CLI agent
-    - Aider: Aider coding assistant
-    - GeminiCli: Gemini CLI agent
-    - Goose: Block Goose agent
-    - SweAgent: SWE-agent
-    - MiniSweAgent: Mini SWE-agent
-    - ClineCli: Cline CLI agent
-    - CursorCli: Cursor CLI agent
-    - OpenCode: OpenCode agent
-    - QwenCode: Qwen Coder agent
+Provides base classes and utilities for building and running agents.
 
 Base Classes:
-    - BaseAgent: Abstract base for all agents
-    - BaseInstalledAgent: Base for agents installed in containers
-    - ExecInput: Command input for installed agents
-
-Factory:
-    - AgentFactory: Create agents by name or import path
-    - AgentName: Enum of built-in agent names
-
-Example:
-    from plato.agents import ClaudeCode, OpenHands, AgentFactory, AgentName
-
-    # Use factory to create agent by name
-    agent = AgentFactory.create_agent_from_name(
-        AgentName.CLAUDE_CODE,
-        logs_dir=Path("./logs"),
-        model_name="anthropic/claude-sonnet-4",
-    )
-
-    # Or import agent class directly
-    agent = ClaudeCode(
-        logs_dir=Path("./logs"),
-        model_name="anthropic/claude-sonnet-4",
-    )
+    - BaseAgent: Abstract base class for agents
+    - AgentConfig: Base configuration class
+    - Secret: Annotation marker for secrets
+
+Registry:
+    - register_agent: Decorator to register an agent
+    - get_agent: Get an agent by name
+    - get_registered_agents: Get all registered agents
+
+Runner:
+    - AgentRunner: Run agents in Docker containers
+    - AgentRunResult: Async iterator for agent output
+
+Trajectory (ATIF):
+    - Trajectory: ATIF trajectory model
+    - Step, Agent, ToolCall, etc.: ATIF components
+
+Callback:
+    - ChronosCallback: Utility for Chronos communication
+
+Example (direct execution):
+    from plato.agents import BaseAgent, AgentConfig, Secret, register_agent
+    from typing import Annotated
+
+    class MyAgentConfig(AgentConfig):
+        model_name: str = "anthropic/claude-sonnet-4"
+        api_key: Annotated[str, Secret(description="API key")]
+
+    @register_agent("my-agent")
+    class MyAgent(BaseAgent[MyAgentConfig]):
+        name = "my-agent"
+        description = "My custom agent"
+
+        async def run(self, instruction: str) -> None:
+            # Agent implementation
+            ...
+
+Example (Docker execution):
+    from plato.agents import AgentRunner
+
+    async for line in AgentRunner.run(
+        image="my-agent:latest",
+        config={"model_name": "anthropic/claude-sonnet-4"},
+        secrets={"api_key": "sk-..."},
+        instruction="Fix the bug",
+        workspace="/path/to/repo",
+    ):
+        print(line)
 """
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
-
-# Lazy imports to avoid requiring harbor when plato.agents is not used
-if TYPE_CHECKING:
-    from harbor.agents.base import BaseAgent
-    from harbor.agents.factory import AgentFactory
-    from harbor.agents.installed.aider import Aider
-    from harbor.agents.installed.base import BaseInstalledAgent, ExecInput
-    from harbor.agents.installed.claude_code import ClaudeCode
-    from harbor.agents.installed.cline import ClineCli
-    from harbor.agents.installed.codex import Codex
-    from harbor.agents.installed.cursor_cli import CursorCli
-    from harbor.agents.installed.gemini_cli import GeminiCli
-    from harbor.agents.installed.goose import Goose
-    from harbor.agents.installed.mini_swe_agent import MiniSweAgent
-    from harbor.agents.installed.opencode import OpenCode
-    from harbor.agents.installed.openhands import OpenHands
-    from harbor.agents.installed.qwen_code import QwenCode
-    from harbor.agents.installed.swe_agent import SweAgent
-    from harbor.models.agent.name import AgentName
-
 __all__ = [
-    # Base classes
+    # Config
+    "AgentConfig",
+    "Secret",
+    # Build
+    "BuildConfig",
+    "load_build_config",
+    # Base
     "BaseAgent",
-    "BaseInstalledAgent",
-    "ExecInput",
-    # Factory
-    "AgentFactory",
-    "AgentName",
-    # Installed agents
-    "ClaudeCode",
-    "OpenHands",
-    "Codex",
-    "Aider",
-    "GeminiCli",
-    "Goose",
-    "SweAgent",
-    "MiniSweAgent",
-    "ClineCli",
-    "CursorCli",
-    "OpenCode",
-    "QwenCode",
-    # Schemas
-    "get_agent_schema",
-    "AGENT_SCHEMAS",
+    "ConfigT",
+    "register_agent",
+    "get_agent",
+    "get_registered_agents",
+    # Runner
+    "run_agent",
+    # Trajectory (ATIF)
+    "Trajectory",
+    "Step",
+    "Agent",
+    "ToolCall",
+    "Observation",
+    "ObservationResult",
+    "Metrics",
+    "FinalMetrics",
+    "SCHEMA_VERSION",
+    # Logging
+    "init_logging",
+    "span",
+    "log_event",
+    "upload_artifacts",
+    "reset_logging",
 ]
 
-
-def _check_harbor_installed() -> None:
-    """Check that harbor is installed and raise helpful error if not."""
-    try:
-        import harbor  # noqa: F401
-    except ImportError as e:
-        raise ImportError(
-            "Harbor is required for plato.agents but is not installed. "
-            "Install it with: pip install 'plato-sdk-v2[agents]' or pip install harbor"
-        ) from e
-
-
-def __getattr__(name: str):
-    """Lazy import Harbor components."""
-    if name in (
-        "BaseAgent",
-        "BaseInstalledAgent",
-        "ExecInput",
-        "AgentFactory",
-        "AgentName",
-        "ClaudeCode",
-        "OpenHands",
-        "Codex",
-        "Aider",
-        "GeminiCli",
-        "Goose",
-        "SweAgent",
-        "MiniSweAgent",
-        "ClineCli",
-        "CursorCli",
-        "OpenCode",
-        "QwenCode",
-    ):
-        _check_harbor_installed()
-
-        if name == "BaseAgent":
-            from harbor.agents.base import BaseAgent
-
-            return BaseAgent
-        elif name == "BaseInstalledAgent":
-            from harbor.agents.installed.base import BaseInstalledAgent
-
-            return BaseInstalledAgent
-        elif name == "ExecInput":
-            from harbor.agents.installed.base import ExecInput
-
-            return ExecInput
-        elif name == "AgentFactory":
-            from harbor.agents.factory import AgentFactory
-
-            return AgentFactory
-        elif name == "AgentName":
-            from harbor.models.agent.name import AgentName
-
-            return AgentName
-        elif name == "ClaudeCode":
-            from harbor.agents.installed.claude_code import ClaudeCode
-
-            return ClaudeCode
-        elif name == "OpenHands":
-            from harbor.agents.installed.openhands import OpenHands
-
-            return OpenHands
-        elif name == "Codex":
-            from harbor.agents.installed.codex import Codex
-
-            return Codex
-        elif name == "Aider":
-            from harbor.agents.installed.aider import Aider
-
-            return Aider
-        elif name == "GeminiCli":
-            from harbor.agents.installed.gemini_cli import GeminiCli
-
-            return GeminiCli
-        elif name == "Goose":
-            from harbor.agents.installed.goose import Goose
-
-            return Goose
-        elif name == "SweAgent":
-            from harbor.agents.installed.swe_agent import SweAgent
-
-            return SweAgent
-        elif name == "MiniSweAgent":
-            from harbor.agents.installed.mini_swe_agent import MiniSweAgent
-
-            return MiniSweAgent
-        elif name == "ClineCli":
-            from harbor.agents.installed.cline import ClineCli
-
-            return ClineCli
-        elif name == "CursorCli":
-            from harbor.agents.installed.cursor_cli import CursorCli
-
-            return CursorCli
-        elif name == "OpenCode":
-            from harbor.agents.installed.opencode import OpenCode
-
-            return OpenCode
-        elif name == "QwenCode":
-            from harbor.agents.installed.qwen_code import QwenCode
-
-            return QwenCode
-
-    if name == "get_agent_schema":
-        return get_agent_schema
-    if name == "AGENT_SCHEMAS":
-        return AGENT_SCHEMAS
-
-    raise AttributeError(f"module 'plato.agents' has no attribute '{name}'")
-
-
-# JSON Schemas for built-in Harbor agents
-# These define the configuration options for each agent
-AGENT_SCHEMAS: dict[str, dict] = {
-    "claude-code": {
-        "$schema": "https://json-schema.org/draft/2020-12/schema",
-        "$id": "harbor-claude-code",
-        "title": "ClaudeCodeConfig",
-        "description": "Configuration for Claude Code agent.",
-        "type": "object",
-        "properties": {
-            "model_name": {
-                "type": "string",
-                "description": "LLM model to use (e.g., 'anthropic/claude-sonnet-4')",
-            },
-            "max_thinking_tokens": {
-                "type": ["integer", "null"],
-                "default": None,
-                "description": "Maximum tokens for extended thinking mode",
-            },
-            "version": {
-                "type": ["string", "null"],
-                "default": None,
-                "description": "Specific Claude Code version to install",
-            },
-            "prompt_template_path": {
-                "type": ["string", "null"],
-                "default": None,
-                "description": "Path to custom prompt template",
-            },
-        },
-        "required": [],
-    },
-    "openhands": {
-        "$schema": "https://json-schema.org/draft/2020-12/schema",
-        "$id": "harbor-openhands",
-        "title": "OpenHandsConfig",
-        "description": "Configuration for OpenHands agent.",
-        "type": "object",
-        "properties": {
-            "model_name": {
-                "type": "string",
-                "description": "LLM model to use (e.g., 'anthropic/claude-sonnet-4')",
-            },
-            "disable_tool_calls": {
-                "type": "boolean",
-                "default": False,
-                "description": "Whether to disable native function calling",
-            },
-            "reasoning_effort": {
-                "type": ["string", "null"],
-                "enum": ["low", "medium", "high", None],
-                "default": "medium",
-                "description": "Reasoning effort level for the model",
-            },
-            "version": {
-                "type": ["string", "null"],
-                "default": None,
-                "description": "Specific OpenHands version to install",
-            },
-            "git_version": {
-                "type": ["string", "null"],
-                "default": None,
-                "description": "Git version/tag to install from",
-            },
-        },
-        "required": [],
-    },
-    "codex": {
-        "$schema": "https://json-schema.org/draft/2020-12/schema",
-        "$id": "harbor-codex",
-        "title": "CodexConfig",
-        "description": "Configuration for Codex CLI agent.",
-        "type": "object",
-        "properties": {
-            "model_name": {
-                "type": "string",
-                "description": "LLM model to use (e.g., 'openai/gpt-4o')",
-            },
-            "version": {
-                "type": ["string", "null"],
-                "default": None,
-                "description": "Specific Codex version to install",
-            },
-        },
-        "required": [],
-    },
-    "aider": {
-        "$schema": "https://json-schema.org/draft/2020-12/schema",
-        "$id": "harbor-aider",
-        "title": "AiderConfig",
-        "description": "Configuration for Aider agent.",
-        "type": "object",
-        "properties": {
-            "model_name": {
-                "type": "string",
-                "description": "LLM model to use",
-            },
-            "version": {
-                "type": ["string", "null"],
-                "default": None,
-                "description": "Specific Aider version to install",
-            },
-        },
-        "required": [],
-    },
-    "gemini-cli": {
-        "$schema": "https://json-schema.org/draft/2020-12/schema",
-        "$id": "harbor-gemini-cli",
-        "title": "GeminiCliConfig",
-        "description": "Configuration for Gemini CLI agent.",
-        "type": "object",
-        "properties": {
-            "model_name": {
-                "type": "string",
-                "description": "LLM model to use (e.g., 'google/gemini-2.5-pro')",
-            },
-            "version": {
-                "type": ["string", "null"],
-                "default": None,
-                "description": "Specific Gemini CLI version to install",
-            },
-        },
-        "required": [],
-    },
-    "goose": {
-        "$schema": "https://json-schema.org/draft/2020-12/schema",
-        "$id": "harbor-goose",
-        "title": "GooseConfig",
-        "description": "Configuration for Block Goose agent.",
-        "type": "object",
-        "properties": {
-            "model_name": {
-                "type": "string",
-                "description": "LLM model to use",
-            },
-            "version": {
-                "type": ["string", "null"],
-                "default": None,
-                "description": "Specific Goose version to install",
-            },
-        },
-        "required": [],
-    },
-    "swe-agent": {
-        "$schema": "https://json-schema.org/draft/2020-12/schema",
-        "$id": "harbor-swe-agent",
-        "title": "SweAgentConfig",
-        "description": "Configuration for SWE-agent.",
-        "type": "object",
-        "properties": {
-            "model_name": {
-                "type": "string",
-                "description": "LLM model to use",
-            },
-            "version": {
-                "type": ["string", "null"],
-                "default": None,
-                "description": "Specific SWE-agent version to install",
-            },
-        },
-        "required": [],
-    },
-    "mini-swe-agent": {
-        "$schema": "https://json-schema.org/draft/2020-12/schema",
-        "$id": "harbor-mini-swe-agent",
-        "title": "MiniSweAgentConfig",
-        "description": "Configuration for Mini SWE-agent.",
-        "type": "object",
-        "properties": {
-            "model_name": {
-                "type": "string",
-                "description": "LLM model to use",
-            },
-            "version": {
-                "type": ["string", "null"],
-                "default": None,
-                "description": "Specific Mini SWE-agent version to install",
-            },
-        },
-        "required": [],
-    },
-    "cline-cli": {
-        "$schema": "https://json-schema.org/draft/2020-12/schema",
-        "$id": "harbor-cline-cli",
-        "title": "ClineCliConfig",
-        "description": "Configuration for Cline CLI agent.",
-        "type": "object",
-        "properties": {
-            "model_name": {
-                "type": "string",
-                "description": "LLM model to use",
-            },
-            "version": {
-                "type": ["string", "null"],
-                "default": None,
-                "description": "Specific Cline version to install",
-            },
-        },
-        "required": [],
-    },
-    "cursor-cli": {
-        "$schema": "https://json-schema.org/draft/2020-12/schema",
-        "$id": "harbor-cursor-cli",
-        "title": "CursorCliConfig",
-        "description": "Configuration for Cursor CLI agent.",
-        "type": "object",
-        "properties": {
-            "model_name": {
-                "type": "string",
-                "description": "LLM model to use",
-            },
-            "version": {
-                "type": ["string", "null"],
-                "default": None,
-                "description": "Specific Cursor CLI version to install",
-            },
-        },
-        "required": [],
-    },
-    "opencode": {
-        "$schema": "https://json-schema.org/draft/2020-12/schema",
-        "$id": "harbor-opencode",
-        "title": "OpenCodeConfig",
-        "description": "Configuration for OpenCode agent.",
-        "type": "object",
-        "properties": {
-            "model_name": {
-                "type": "string",
-                "description": "LLM model to use",
-            },
-            "version": {
-                "type": ["string", "null"],
-                "default": None,
-                "description": "Specific OpenCode version to install",
-            },
-        },
-        "required": [],
-    },
-    "qwen-coder": {
-        "$schema": "https://json-schema.org/draft/2020-12/schema",
-        "$id": "harbor-qwen-code",
-        "title": "QwenCodeConfig",
-        "description": "Configuration for Qwen Coder agent.",
-        "type": "object",
-        "properties": {
-            "model_name": {
-                "type": "string",
-                "description": "LLM model to use",
-            },
-            "version": {
-                "type": ["string", "null"],
-                "default": None,
-                "description": "Specific Qwen Coder version to install",
-            },
-        },
-        "required": [],
-    },
-    # Plato custom agent (not from Harbor)
-    "computer-use": {
-        "$schema": "https://json-schema.org/draft/2020-12/schema",
-        "$id": "plato-computer-use",
-        "title": "ComputerUseConfig",
-        "description": "Configuration for Computer-Use browser automation agent.",
-        "type": "object",
-        "properties": {
-            "model_name": {
-                "type": "string",
-                "description": "LLM model (e.g., 'claude-sonnet-4-5-20250929', 'gpt-4o', 'gemini-2.0-flash')",
-            },
-            "mode": {
-                "type": "string",
-                "enum": ["browser", "computer"],
-                "default": "browser",
-                "description": "Execution mode: 'browser' (Playwright) or 'computer' (desktop)",
-            },
-            "browser_type": {
-                "type": "string",
-                "enum": ["local", "browserbase", "steel"],
-                "default": "local",
-                "description": "Browser backend type",
-            },
-            "headless": {
-                "type": "boolean",
-                "default": True,
-                "description": "Run browser in headless mode",
-            },
-            "viewport_width": {
-                "type": "integer",
-                "default": 1280,
-                "description": "Browser viewport width",
-            },
-            "viewport_height": {
-                "type": "integer",
-                "default": 800,
-                "description": "Browser viewport height",
-            },
-            "start_url": {
-                "type": ["string", "null"],
-                "default": None,
-                "description": "Optional starting URL",
-            },
-            "timeout_seconds": {
-                "type": "integer",
-                "default": 600,
-                "description": "Timeout for agent execution",
-            },
-        },
-        "required": [],
-    },
-}
-
-
-def get_agent_schema(agent_name: str) -> dict | None:
-    """Get the JSON schema for a built-in Harbor agent.
-
-    Args:
-        agent_name: The agent name (e.g., 'claude-code', 'openhands')
-
-    Returns:
-        JSON schema dict or None if agent not found
-    """
-    return AGENT_SCHEMAS.get(agent_name)
+from plato.agents.base import (
+    BaseAgent,
+    ConfigT,
+    get_agent,
+    get_registered_agents,
+    register_agent,
+)
+from plato.agents.build import BuildConfig, load_build_config
+from plato.agents.config import AgentConfig, Secret
+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,
+    FinalMetrics,
+    Metrics,
+    Observation,
+    ObservationResult,
+    Step,
+    ToolCall,
+    Trajectory,
+)