plato-sdk-v2 2.0.23__tar.gz

plato_sdk_v2-2.0.23/.gitignore

@@ -0,0 +1,23 @@
+__pycache__/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+
+# pyenv
+.python-version
+
+# Environments
+.env
+.venv
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# JetBrains
+.idea/
+
+/coverage.xml
+/.coverage

plato_sdk_v2-2.0.23/BUILDING_SIMS.md

@@ -0,0 +1,70 @@
+# Building Simulators
+
+Internal documentation for building and snapshotting simulators.
+
+## Snapshot Environments
+
+Create snapshots of environment state:
+
+```python
+from plato.v2 import AsyncPlato, Env
+
+async def main():
+    plato = AsyncPlato()
+
+    session = await plato.sessions.create(
+        envs=[Env.simulator("gitea", alias="gitea")],
+        timeout=600,
+    )
+
+    await session.start_heartbeat()
+
+    # ... make changes to the environment ...
+
+    # Snapshot all environments
+    snapshots = await session.snapshot()
+    print(snapshots)
+
+    # Or snapshot individual environment
+    gitea = session.get_env("gitea")
+    if gitea:
+        snapshot = await gitea.snapshot()
+        print(snapshot)
+
+    await session.close()
+    await plato.close()
+```
+
+## Database Cleanup
+
+Clean up database audit logs before snapshotting (async only):
+
+```python
+from plato.v2 import AsyncPlato, Env
+
+async def main():
+    plato = AsyncPlato()
+
+    session = await plato.sessions.create(
+        envs=[Env.simulator("gitea", alias="gitea")],
+        timeout=600,
+    )
+
+    # ... make changes ...
+
+    # Clean up audit logs before snapshot
+    cleanup_result = await session.cleanup_databases()
+    print(cleanup_result)
+
+    # Then snapshot
+    snapshots = await session.snapshot()
+
+    await session.close()
+    await plato.close()
+```
+
+Requires additional dependencies:
+
+```bash
+pip install plato-sdk-v2[db-cleanup]
+```

plato_sdk_v2-2.0.23/PKG-INFO

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: plato-sdk-v2
+Version: 2.0.23
+Summary: Python SDK for the Plato API
+Author-email: Plato <support@plato.so>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: aiohttp>=3.13.2
+Requires-Dist: datamodel-code-generator>=0.43.0
+Requires-Dist: email-validator>=2.0.0
+Requires-Dist: google-genai>=1.0.0
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: jinja2>=3.1.0
+Requires-Dist: openapi-pydantic>=0.5.1
+Requires-Dist: playwright>=1.56.0
+Requires-Dist: pydantic-settings>=2.12.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.2.1
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: requests>=2.32.5
+Requires-Dist: rich>=13.0.0
+Requires-Dist: tenacity>=9.1.2
+Requires-Dist: tomli>=2.0.0
+Requires-Dist: typer>=0.9.0
+Provides-Extra: db-cleanup
+Requires-Dist: aiomysql>=0.2; extra == 'db-cleanup'
+Requires-Dist: aiosqlite>=0.20; extra == 'db-cleanup'
+Requires-Dist: asyncpg>=0.29; extra == 'db-cleanup'
+Requires-Dist: sqlalchemy[asyncio]>=2.0; extra == 'db-cleanup'
+Provides-Extra: dev
+Requires-Dist: basedpyright>=1.18; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Plato Python SDK
+
+Python SDK for the Plato API v2.
+
+## Installation
+
+```bash
+pip install plato-sdk-v2
+```
+
+Or with uv:
+
+```bash
+uv add plato-sdk-v2
+```
+
+## Configuration
+
+Create a `.env` file in your project root:
+
+```bash
+PLATO_API_KEY=your-api-key
+PLATO_BASE_URL=https://plato.so  # optional, defaults to https://plato.so
+```
+
+Or set environment variables directly:
+
+```bash
+export PLATO_API_KEY=your-api-key
+```
+
+## Usage
+
+There are two main flows depending on your use case:
+
+### Flow 1: Create Session from Environments
+
+Use this when you want to spin up environments for development, testing, or custom automation.
+
+```python
+import asyncio
+from plato.v2 import AsyncPlato, Env
+
+async def main():
+    plato = AsyncPlato()
+
+    # Create session with one or more environments
+    # (heartbeat starts automatically to keep session alive)
+    session = await plato.sessions.create(
+        envs=[
+            Env.simulator("gitea", dataset="blank", alias="gitea"),
+            Env.simulator("kanboard", alias="kanboard"),
+        ],
+        timeout=600,
+    )
+
+    # Reset environments to initial state
+    await session.reset()
+
+    # Get public URLs for browser access
+    public_urls = await session.get_public_url()
+    for alias, url in public_urls.items():
+        print(f"{alias}: {url}")
+
+    # ============================================
+    # Interact with environments via browser/API
+    # ============================================
+
+    # Get state mutations from all environments
+    state = await session.get_state()
+    print(state)
+
+    # Cleanup
+    await session.close()
+    await plato.close()
+
+asyncio.run(main())
+```
+
+### Flow 2: Create Session from Task
+
+Use this when running evaluations against predefined tasks. This flow includes task evaluation at the end.
+
+```python
+import asyncio
+from plato.v2 import AsyncPlato
+
+async def main():
+    plato = AsyncPlato()
+
+    # Create session from task ID
+    # (heartbeat starts automatically to keep session alive)
+    session = await plato.sessions.create(task=123, timeout=600)
+
+    # Reset environments to initial state
+    await session.reset()
+
+    # Get public URLs for browser access
+    public_urls = await session.get_public_url()
+    for alias, url in public_urls.items():
+        print(f"{alias}: {url}")
+
+    # ============================================
+    # Interact with environments via browser/API
+    # ============================================
+
+    # Get state mutations from all environments
+    state = await session.get_state()
+    print(state)
+
+    # Evaluate task completion
+    evaluation = await session.evaluate()
+    print(f"Task completed: {evaluation}")
+
+    # Cleanup
+    await session.close()
+    await plato.close()
+
+asyncio.run(main())
+```
+
+## Environment Configuration
+
+Two ways to specify environments:
+
+```python
+from plato.v2 import Env
+
+# 1. From simulator (most common)
+Env.simulator("gitea")                          # default tag
+Env.simulator("gitea", tag="staging")           # specific tag
+Env.simulator("gitea", dataset="blank")         # specific dataset
+Env.simulator("gitea", alias="my-git")          # custom alias
+
+# 2. From artifact ID
+Env.artifact("artifact-abc123")
+Env.artifact("artifact-abc123", alias="my-env")
+```
+
+## Per-Environment Operations
+
+Access individual environments within a session:
+
+```python
+# Get all environments
+for env in session.envs:
+    print(f"{env.alias}: {env.job_id}")
+
+# Get specific environment by alias
+gitea = session.get_env("gitea")
+
+if gitea:
+    # Execute shell command
+    result = await gitea.execute("whoami", timeout=30)
+    print(result)
+
+    # Get state for this environment only
+    state = await gitea.get_state()
+
+    # Reset this environment only
+    await gitea.reset()
+```
+
+## Sync Client
+
+A synchronous client is also available:
+
+```python
+from plato.v2 import Plato, Env
+
+plato = Plato()
+
+# Heartbeat starts automatically
+session = plato.sessions.create(
+    envs=[Env.simulator("gitea", alias="gitea")],
+    timeout=600,
+)
+
+session.reset()
+
+public_urls = session.get_public_url()
+state = session.get_state()
+
+session.close()
+plato.close()
+```
+
+## License
+
+MIT

plato_sdk_v2-2.0.23/README.md

@@ -0,0 +1,190 @@
+# Plato Python SDK
+
+Python SDK for the Plato API v2.
+
+## Installation
+
+```bash
+pip install plato-sdk-v2
+```
+
+Or with uv:
+
+```bash
+uv add plato-sdk-v2
+```
+
+## Configuration
+
+Create a `.env` file in your project root:
+
+```bash
+PLATO_API_KEY=your-api-key
+PLATO_BASE_URL=https://plato.so  # optional, defaults to https://plato.so
+```
+
+Or set environment variables directly:
+
+```bash
+export PLATO_API_KEY=your-api-key
+```
+
+## Usage
+
+There are two main flows depending on your use case:
+
+### Flow 1: Create Session from Environments
+
+Use this when you want to spin up environments for development, testing, or custom automation.
+
+```python
+import asyncio
+from plato.v2 import AsyncPlato, Env
+
+async def main():
+    plato = AsyncPlato()
+
+    # Create session with one or more environments
+    # (heartbeat starts automatically to keep session alive)
+    session = await plato.sessions.create(
+        envs=[
+            Env.simulator("gitea", dataset="blank", alias="gitea"),
+            Env.simulator("kanboard", alias="kanboard"),
+        ],
+        timeout=600,
+    )
+
+    # Reset environments to initial state
+    await session.reset()
+
+    # Get public URLs for browser access
+    public_urls = await session.get_public_url()
+    for alias, url in public_urls.items():
+        print(f"{alias}: {url}")
+
+    # ============================================
+    # Interact with environments via browser/API
+    # ============================================
+
+    # Get state mutations from all environments
+    state = await session.get_state()
+    print(state)
+
+    # Cleanup
+    await session.close()
+    await plato.close()
+
+asyncio.run(main())
+```
+
+### Flow 2: Create Session from Task
+
+Use this when running evaluations against predefined tasks. This flow includes task evaluation at the end.
+
+```python
+import asyncio
+from plato.v2 import AsyncPlato
+
+async def main():
+    plato = AsyncPlato()
+
+    # Create session from task ID
+    # (heartbeat starts automatically to keep session alive)
+    session = await plato.sessions.create(task=123, timeout=600)
+
+    # Reset environments to initial state
+    await session.reset()
+
+    # Get public URLs for browser access
+    public_urls = await session.get_public_url()
+    for alias, url in public_urls.items():
+        print(f"{alias}: {url}")
+
+    # ============================================
+    # Interact with environments via browser/API
+    # ============================================
+
+    # Get state mutations from all environments
+    state = await session.get_state()
+    print(state)
+
+    # Evaluate task completion
+    evaluation = await session.evaluate()
+    print(f"Task completed: {evaluation}")
+
+    # Cleanup
+    await session.close()
+    await plato.close()
+
+asyncio.run(main())
+```
+
+## Environment Configuration
+
+Two ways to specify environments:
+
+```python
+from plato.v2 import Env
+
+# 1. From simulator (most common)
+Env.simulator("gitea")                          # default tag
+Env.simulator("gitea", tag="staging")           # specific tag
+Env.simulator("gitea", dataset="blank")         # specific dataset
+Env.simulator("gitea", alias="my-git")          # custom alias
+
+# 2. From artifact ID
+Env.artifact("artifact-abc123")
+Env.artifact("artifact-abc123", alias="my-env")
+```
+
+## Per-Environment Operations
+
+Access individual environments within a session:
+
+```python
+# Get all environments
+for env in session.envs:
+    print(f"{env.alias}: {env.job_id}")
+
+# Get specific environment by alias
+gitea = session.get_env("gitea")
+
+if gitea:
+    # Execute shell command
+    result = await gitea.execute("whoami", timeout=30)
+    print(result)
+
+    # Get state for this environment only
+    state = await gitea.get_state()
+
+    # Reset this environment only
+    await gitea.reset()
+```
+
+## Sync Client
+
+A synchronous client is also available:
+
+```python
+from plato.v2 import Plato, Env
+
+plato = Plato()
+
+# Heartbeat starts automatically
+session = plato.sessions.create(
+    envs=[Env.simulator("gitea", alias="gitea")],
+    timeout=600,
+)
+
+session.reset()
+
+public_urls = session.get_public_url()
+state = session.get_state()
+
+session.close()
+plato.close()
+```
+
+## License
+
+MIT

plato_sdk_v2-2.0.23/plato/__init__.py

@@ -0,0 +1,44 @@
+# Plato SDK
+#
+# v1: Legacy SDK (deprecated)
+# v2: New SDK with separate sync/async modules
+# agents: Code execution agent framework
+# sims: Simulation clients (Spree, Firefly, etc.)
+#
+# Usage (v2 - recommended):
+#   from plato.v2 import AsyncPlato, Plato, Env
+#
+# Usage (agents):
+#   from plato.agents import CodeAgent, CodeExecutor
+#
+# Usage (sims):
+#   from plato.sims import SpreeClient, FireflyClient
+
+from plato import v2 as v2
+
+__all__ = ["v2"]
+
+
+def __getattr__(name: str):
+    """Lazy import to avoid loading all modules at once."""
+    if name in ("Plato", "SyncPlato", "PlatoTask", "v1"):
+        try:
+            from plato import v1
+
+            if name == "v1":
+                return v1
+            return getattr(v1, name)
+        except ImportError:
+            raise AttributeError(f"module 'plato' has no attribute '{name}' (v1 unavailable)")
+
+    if name == "agents":
+        from plato import agents
+
+        return agents
+
+    if name == "sims":
+        from plato import sims
+
+        return sims
+
+    raise AttributeError(f"module 'plato' has no attribute '{name}'")

plato_sdk_v2-2.0.23/plato/_generated/__init__.py

@@ -0,0 +1,37 @@
+"""Plato API SDK - v0.19.3"""
+
+from . import api, errors, models
+from .client import AsyncClient, Client
+from .errors import (
+    APIError,
+    BadRequestError,
+    ConflictError,
+    ForbiddenError,
+    InternalServerError,
+    NotFoundError,
+    RateLimitError,
+    ServiceUnavailableError,
+    UnauthorizedError,
+    UnprocessableEntityError,
+)
+
+__all__ = [
+    # Clients
+    "Client",
+    "AsyncClient",
+    # Modules
+    "api",
+    "models",
+    "errors",
+    # Error types for convenience
+    "APIError",
+    "BadRequestError",
+    "UnauthorizedError",
+    "ForbiddenError",
+    "NotFoundError",
+    "ConflictError",
+    "UnprocessableEntityError",
+    "RateLimitError",
+    "InternalServerError",
+    "ServiceUnavailableError",
+]

plato_sdk_v2-2.0.23/plato/_generated/api/__init__.py

@@ -0,0 +1,8 @@
+"""Generated API modules."""
+
+from . import v1, v2
+
+__all__ = [
+    "v1",
+    "v2",
+]

plato_sdk_v2-2.0.23/plato/_generated/api/v1/__init__.py

@@ -0,0 +1,31 @@
+"""API version module."""
+
+from . import (
+    agent_artifacts,
+    cluster,
+    env,
+    evals,
+    gitea,
+    jobs,
+    organization,
+    queue,
+    sandbox,
+    session,
+    simulator,
+    testcases,
+)
+
+__all__ = [
+    "agent_artifacts",
+    "cluster",
+    "env",
+    "evals",
+    "gitea",
+    "jobs",
+    "organization",
+    "queue",
+    "sandbox",
+    "session",
+    "simulator",
+    "testcases",
+]

plato_sdk_v2-2.0.23/plato/_generated/api/v1/agent_artifacts/__init__.py

@@ -0,0 +1,10 @@
+"""API endpoints."""
+
+from . import archive_agent_artifact, create_agent_artifact, get_agent_artifact_by_public_id, get_agent_artifacts
+
+__all__ = [
+    "get_agent_artifacts",
+    "create_agent_artifact",
+    "get_agent_artifact_by_public_id",
+    "archive_agent_artifact",
+]